project-expansion-scout
Configure and run the Project Expansion Scout — an autonomous strategic growth agent that scans active projects for expansion opportunities, consults the BOD for configurable feasibility approval (def
SKILL.mdskills/project-expansion-scout/SKILL.md
GitHubProject Expansion Scout
An autonomous strategic growth agent that runs on a configurable schedule, finds expansion opportunities across all active projects, gets BOD approval, and updates PROJECT.md accordingly.
Setup
Files
| File | Purpose |
|---|---|
{agency-root}/agents-archive/generalist-2026-10-06/specialized/project-expansion-scout.md |
Archived role definition (read as the scout's role file) |
~/.claude/memory/expansion-scouts/ |
Storage for drafts and voting state |
~/.claude/memory/expansion-scouts/voting-state.json |
Configuration + per-project voting state |
Configure the Scout
Edit voting-state.json to set:
{
"scan_interval": "weekly",
"approval_threshold": 0.80,
"max_revision_cycles": 5,
"projects": {}
}
| Field | Values | Default | Notes |
|---|---|---|---|
scan_interval |
"daily" / "weekly" / "biweekly" |
"weekly" |
Affects cron schedule |
approval_threshold |
0.0 – 1.0 |
0.80 |
Fraction of BOD votes needed |
max_revision_cycles |
1 – 10 |
5 |
Max revise iterations before archiving |
Set Up Cron Schedule
Note: Cron jobs are session-only and auto-expire after 7 days. You must re-establish the cron at the start of each session. The cron_job_id is stored in voting-state.json for reference.
Use /cron-list and /cron-delete to manage. Default schedule:
- Weekly: Every Monday at 8:00 AM local —
0 8 * * 1 - Biweekly: Every other Monday at 8:00 AM —
0 8 * * 1 */2 - Daily: Every day at 8:00 AM —
0 8 * * *
Cron fires, wakes the scout (general-purpose + /project-expansion-scout), which runs its full scan → BOD consult → vote → execute cycle.
Invoking the Scout
Manual Trigger (One-Shot)
Run the scout inline, or spawn general-purpose with /project-expansion-scout and let it run its full cycle:
Skills: /project-expansion-scout
Role: read {agency-root}/agents-archive/generalist-2026-10-06/specialized/project-expansion-scout.md first.
Run one complete expansion scan cycle:
1. Read medium-term.md for active projects
2. Scan each PROJECT.md + source code for expansion signals
3. Write drafts to ~/.claude/memory/expansion-scouts/{project}/current-draft.md
4. If drafts exist → assemble BOD, present drafts, collect votes
5. Tally votes against threshold
6. Execute approved expansions → update PROJECT.md + decisions.md
7. Archive or re-vote based on outcome
Cron-Triggered (Recurring)
The cron job fires the same prompt. The agent checks voting-state.json on wake:
- If
projectshas an active draft → continue BOD consultation (resume mid-vote) - If no active draft → run new scan
What Gets Scanned
Per project:
PROJECT.md—focuslist (stale items, scope underruns),blockers, open questions- Source code —
TODO,FIXME,XXXcomments; deprecated/unimplemented - README / docs — known limitations, planned-but-not-done features
- Cross-project — compare PROJECT.md across all active projects for synergy opportunities
Expansion Draft Lifecycle
[Draft Written] → [BOD Vote #1] → [Revised] → [BOD Vote #2] → ...
↓ ↓
[APPROVED] [Cycle 5 Hit]
↓ ↓
[PROJECT.md [Archived]
Updated]
| State | File | What Happens |
|---|---|---|
| Draft exists | current-draft.md |
Awaiting BOD vote |
| In revision | current-draft.md (updated) |
Incorporating revision notes |
| Approved | history/phase-N-date.md |
Appended to PROJECT.md |
| Rejected | history/phase-N-date-rejected.md |
Logged with rejection reason |
| Skipped (no opportunity) | No file | Nothing to do this cycle |
BOD Vote Tracking
Votes stored in voting-state.json:
{
"projects": {
"{project}": {
"phase": 1,
"revision_cycle": 2,
"draft_date": "2026-03-25",
"votes": {
"council-fable": "approve",
"council-opus": "revise",
"council-sonnet": "approve",
"council-haiku": "approve",
"codex": "approve",
...
},
"revision_notes": {
"council-opus": "Split into two phases: MVP first, polish later"
}
}
}
}
On session resume, the agent reads this state and continues from where it left off.
Integration with Project Memory
Approved expansion phases are written to:
{project}/PROJECT.md— appended under## Expansion Phases{project}/memory/decisions.md— decision log entry
Disabling / Pausing
To pause the scout:
- Delete the cron job (
/cron-delete) - Or set
scan_intervaltonull/ remove it
To disable for a specific project: add it to voting-state.json under a disabled_projects array.
Key Files Reference
| File | Read/Write | Purpose |
|---|---|---|
~/.claude/memory/medium-term.md |
Read | Active project list |
~/.claude/memory/expansion-scouts/voting-state.json |
Read/Write | Config + voting state |
~/.claude/memory/expansion-scouts/{project}/current-draft.md |
Read/Write | Active draft |
~/.claude/memory/expansion-scouts/{project}/history/*.md |
Write | Archive |
{project}/PROJECT.md |
Read/Write | Project source + append expansion |
{project}/memory/decisions.md |
Append | Decision log |