Project Fleet
Invoke as $project-fleet.
Use this skill when a project is no longer a single repo or task list, but a fleet: one control repository coordinates many downstream repositories, implementation targets, specs, clients, migrations, content items, experiments, or generated artifacts.
Examples: seeding many private repos from a spec store, migrating many packages, generating plans for many apps, rolling out the same change across customer repos, or advancing a queue while rate limits or external windows control provisioning.
Core Model
A fleet has:
- Control repo: canonical state, conventions, queue, scripts, logs, and status.
- Fleet items: downstream repos or work units, each with an ID, target, source, state, and blocker field.
- Provisioning lane: creates or updates external targets under strict guards.
- Work lane: advances already-provisioned targets while provisioning is blocked or waiting.
- Blocker ledger: records stop conditions and retry rules.
- Status dashboard: summarizes next action without re-reading the whole project.
State Machine
Use project-specific names when needed, but preserve these semantics:
candidate
ready-to-provision
provisioning-blocked
provisioned
planning-needed
plan-ready
work-in-progress
verification-needed
done
blocked
Never collapse "provisioned" into "done." A created repo, generated scaffold, or reserved artifact is only an available target until planning, work, and verification finish.
For broad solution-space exploration, spec-clone stores, generated app fleets, or other candidate-heavy projects, prefer this portfolio funnel:
candidate -> shortlisted -> spec-ready -> seeded -> active-build -> shipped | archived | blocked
Preserve these meanings:
- candidate: cheap broad idea or rough spec; not approved for repo creation or implementation.
- shortlisted: scored and intentionally kept for deeper work.
- spec-ready: implementation-ready source/spec exists with required evidence, constraints, and blockers.
- seeded: downstream repo, scaffold, or external target exists; still not implementation-complete.
- active-build: selected for runnable milestone work under the active fleet cap.
- shipped: verified output reached the project's done definition.
- archived: intentionally removed from active consideration.
- blocked: cannot advance until the recorded blocker clears.
Use scaffold-only as an explicit item tag, not a state, when a project intentionally creates downstream scaffolds before spec-ready. A scaffold-only item may be seeded for inventory purposes, but it cannot enter active-build until it becomes spec-ready.
Portfolio Policy
When a fleet contains many candidate apps, specs, repos, experiments, content items, or implementation targets, optimize for return on effort instead of breadth alone:
- Track portfolio fields per item: ID, name, target, source/reference, state, score, score rationale, readiness state, downstream repo or artifact, active-build eligibility, last verified state, blocker, and next milestone.
- Score candidates before deep specification or provisioning. Use project-specific criteria when present; otherwise score implementation leverage, demo value, legal/provider risk, reusable components, data/API availability, user or market signal, and build cost.
- Default active-build cap is 5 when the project has no explicit cap. Do not add more
active-build items until an active item ships, blocks, or is archived.
- Default downstream provisioning gate is
spec-ready. Only seed earlier when the item is explicitly marked scaffold-only and project rules allow scaffold inventory.
- Prefer runnable milestone progress over more broad expansion once any
active-build item exists.
- Do not let candidate count, scaffold count, or repo count stand in for shipped or runnable progress.
Process
- Read conventions first. Load
AGENTS.md, CLAUDE.md, or equivalent control-repo instructions. Treat project-specific safety rules as higher priority than this generic skill.
- Find fleet state. Look for
tasks/, docs/, scripts/, manifest tables, status files, queue files, or project-local conventions. If no state exists, propose a minimal one before executing.
- Normalize the queue. Ensure each item has: ID, name, target, source/reference, state, last action, blocker, and next action. For candidate-heavy fleets, also normalize score, score rationale, readiness state, downstream repo/artifact, active-build eligibility, last verified state, and next milestone.
- Run preflight guards. Check auth, rate limits, dirty worktrees, target visibility/safety, required scripts, and project-specific stop conditions before external writes.
- Choose exactly one lane:
- Provisioning lane when guards pass and the next target is eligible.
- Work lane when provisioning is blocked by time, rate limits, or an external dependency but existing targets can advance.
- Repair lane when a blocker is actionable and safe to fix.
- Planning lane when the queue lacks enough detail for execution.
- Portfolio lane when candidate scoring, culling, active-cap enforcement, or
scaffold-only/spec-ready classification is needed before safe provisioning or implementation.
- Execute in bounded batches. Follow project batch size, serial/parallel limits, and external-service rules. If no policy exists, default to one item.
- Verify before state changes. Do not mark an item advanced until evidence exists: target exists, expected files or outputs exist, tests/checks pass, visibility is correct, or the planned artifact is committed.
- Update central state. Record completed work, blocker evidence, next eligible time, next target, and any skipped items.
- Ship changes. If tracked files changed, follow the repository shipping convention: validate, commit, and push unless the project explicitly says not to.
- Report the next action. End with the next concrete fleet item and the recommended command or lane.
Control-Repo Files
Prefer existing files. If the project lacks a structure, create or recommend:
tasks/fleet-status.md # generated or hand-maintained dashboard
tasks/fleet-queue.md # manifest of items and states
tasks/fleet-blockers.md # blocker ledger if not embedded in queue
tasks/history.md # shipped work log
scripts/fleet-status.* # optional deterministic status generator
scripts/fleet-next.* # optional next-item selector
scripts/fleet-provision.* # optional guarded provisioning script
For domain-specific projects, use clearer names like tasks/repo-seeding.md, tasks/migration-queue.md, or tasks/customer-rollout.md. Generic file names are a fallback, not a requirement.
Guarded Provisioning
Provisioning means any operation that creates, publishes, mutates, or schedules many external targets. Examples: gh repo create, remote pushes, deployments, package publishing, account/API provisioning, bulk imports, or paid-service operations.
Before provisioning:
- Confirm explicit user/project approval exists for the operation class.
- Confirm target visibility and privacy defaults.
- Confirm the target satisfies the project's readiness gate. For candidate-heavy fleets, the default gate is
spec-ready; earlier provisioning requires an explicit scaffold-only tag.
- Check service limits and local rolling caps.
- Use project scripts when they exist.
- Keep operations serial unless the project explicitly permits parallelism.
- Stop on auth failures, rate limits, permission errors, target conflicts, visibility mismatches, partial propagation, template validation failures, or unexpected paid/irreversible actions.
On a rate limit, obey retry-after or reset headers when available. Otherwise record a conservative next eligible time and switch to work lane if safe.
Productive Fallback Work
When provisioning is waiting or blocked, advance existing fleet items without violating the provisioning guard:
- Generate or refine per-item roadmaps.
- Expand implementation plans from source specs.
- Score and cull candidates, promote promising candidates to
shortlisted, or archive low-return candidates.
- Run local validation or hygiene checks.
- Fix documented blockers that do not require the blocked external operation.
- Prepare templates, scripts, or status reports.
- Verify already-created targets.
Do not use fallback work to bypass a guard. If the blocked operation is required for an item, pick a different eligible item.
Blocker Ledger
Each blocker entry should include:
timestamp
item ID / target
lane
blocker type
evidence
attempted fix
retry rule or owner
next eligible action
Common blocker types:
auth-permission
rate-limit
target-conflict
propagation-delay
visibility-safety
template-validation
dirty-worktree
missing-source
verification-failure
legal-or-policy-risk
manual-human-action
Output
Report:
- Current fleet count by state.
- Portfolio summary when relevant: active-build count/cap, top scored candidates,
scaffold-only count, spec-ready count, and archived/blocked count.
- Lane selected and why.
- Items advanced.
- Guards checked.
- Blockers created or cleared.
- Validation evidence.
- Files changed and shipped status.
- Next work: the next concrete item or blocker.
- Recommended next command:
$project-fleet --execute, $project-fleet --status, another project-specific skill, or the exact project script.
Constraints
- Do not invent permission to create, publish, deploy, spend money, or make public resources.
- Do not continue provisioning after a stop-condition failure.
- Do not parallelize externally fragile operations unless the project explicitly allows it.
- Do not mark planning/scaffold targets as implementation-complete.
- Do not move
candidate, shortlisted, or scaffold-only items into active-build without spec-ready evidence.
- Do not exceed the active-build cap unless the project explicitly changes the cap.
- Do not let downstream repos become the source of truth for fleet-wide state unless the project explicitly chooses a distributed model.
Alignment Page
Follow the shared alignment-page convention via the packaged convention resolver; output path is alignment/project-fleet-{topic}.html.
Default Shipping Contract
- Default next-step routing: when reporting completion, include either
Recommended next skill: <command> or the two-line pair **Next work:** <specific task or "none"> and **Recommended next command:** <one command or route> so the next caller has a concrete handoff.
- If this skill creates or modifies tracked repository files, follow
docs/github-delivery-contract.md and finish with an issue-backed non-primary branch plus ready pull request; do not merge it.
- Do not leave tracked changes or unpushed commits behind. If unrelated tracked work is already present, either include it in sensible commits too or stop and explain the blocker.
- This contract does not override stricter safety rules about secrets, destructive history changes, release publication/tag confirmation, production deploy confirmation, paid actions, or public visibility changes.
1---2name: project-fleet3description: Orchestrate a central control repository that plans, provisions, tracks, and advances many related downstream repositories or work items with guarded batches, blocker handling, and productive fallback work.4---5
6# Project Fleet
7
8Invoke as `$project-fleet`.
9
10Use this skill when a project is no longer a single repo or task list, but a fleet: one control repository coordinates many downstream repositories, implementation targets, specs, clients, migrations, content items, experiments, or generated artifacts.
11
12Examples: seeding many private repos from a spec store, migrating many packages, generating plans for many apps, rolling out the same change across customer repos, or advancing a queue while rate limits or external windows control provisioning.
13
14## Core Model
15
16A fleet has:
17
18- **Control repo:** canonical state, conventions, queue, scripts, logs, and status.
19- **Fleet items:** downstream repos or work units, each with an ID, target, source, state, and blocker field.
20- **Provisioning lane:** creates or updates external targets under strict guards.
21- **Work lane:** advances already-provisioned targets while provisioning is blocked or waiting.
22- **Blocker ledger:** records stop conditions and retry rules.
23- **Status dashboard:** summarizes next action without re-reading the whole project.
24
25## State Machine
26
27Use project-specific names when needed, but preserve these semantics:
28
29```text
30candidate
31ready-to-provision
32provisioning-blocked
33provisioned
34planning-needed
35plan-ready
36work-in-progress
37verification-needed
38done
39blocked
40```
41
42Never collapse "provisioned" into "done." A created repo, generated scaffold, or reserved artifact is only an available target until planning, work, and verification finish.
43
44For broad solution-space exploration, spec-clone stores, generated app fleets, or other candidate-heavy projects, prefer this portfolio funnel:
45
46```text
47candidate -> shortlisted -> spec-ready -> seeded -> active-build -> shipped | archived | blocked
48```
49
50Preserve these meanings:
51
52- **candidate:** cheap broad idea or rough spec; not approved for repo creation or implementation.
53- **shortlisted:** scored and intentionally kept for deeper work.
54- **spec-ready:** implementation-ready source/spec exists with required evidence, constraints, and blockers.
55- **seeded:** downstream repo, scaffold, or external target exists; still not implementation-complete.
56- **active-build:** selected for runnable milestone work under the active fleet cap.
57- **shipped:** verified output reached the project's done definition.
58- **archived:** intentionally removed from active consideration.
59- **blocked:** cannot advance until the recorded blocker clears.
60
61Use `scaffold-only` as an explicit item tag, not a state, when a project intentionally creates downstream scaffolds before `spec-ready`. A `scaffold-only` item may be seeded for inventory purposes, but it cannot enter `active-build` until it becomes `spec-ready`.
62
63## Portfolio Policy
64
65When a fleet contains many candidate apps, specs, repos, experiments, content items, or implementation targets, optimize for return on effort instead of breadth alone:
66
67- Track portfolio fields per item: ID, name, target, source/reference, state, score, score rationale, readiness state, downstream repo or artifact, active-build eligibility, last verified state, blocker, and next milestone.
68- Score candidates before deep specification or provisioning. Use project-specific criteria when present; otherwise score implementation leverage, demo value, legal/provider risk, reusable components, data/API availability, user or market signal, and build cost.
69- Default active-build cap is 5 when the project has no explicit cap. Do not add more `active-build` items until an active item ships, blocks, or is archived.
70- Default downstream provisioning gate is `spec-ready`. Only seed earlier when the item is explicitly marked `scaffold-only` and project rules allow scaffold inventory.
71- Prefer runnable milestone progress over more broad expansion once any `active-build` item exists.
72- Do not let candidate count, scaffold count, or repo count stand in for shipped or runnable progress.
73
74## Process
75
761. **Read conventions first.** Load `AGENTS.md`, `CLAUDE.md`, or equivalent control-repo instructions. Treat project-specific safety rules as higher priority than this generic skill.
772. **Find fleet state.** Look for `tasks/`, `docs/`, `scripts/`, manifest tables, status files, queue files, or project-local conventions. If no state exists, propose a minimal one before executing.
783. **Normalize the queue.** Ensure each item has: ID, name, target, source/reference, state, last action, blocker, and next action. For candidate-heavy fleets, also normalize score, score rationale, readiness state, downstream repo/artifact, active-build eligibility, last verified state, and next milestone.
794. **Run preflight guards.** Check auth, rate limits, dirty worktrees, target visibility/safety, required scripts, and project-specific stop conditions before external writes.
805. **Choose exactly one lane:**
81 - **Provisioning lane** when guards pass and the next target is eligible.
82 - **Work lane** when provisioning is blocked by time, rate limits, or an external dependency but existing targets can advance.
83 - **Repair lane** when a blocker is actionable and safe to fix.
84 - **Planning lane** when the queue lacks enough detail for execution.
85 - **Portfolio lane** when candidate scoring, culling, active-cap enforcement, or `scaffold-only`/`spec-ready` classification is needed before safe provisioning or implementation.
866. **Execute in bounded batches.** Follow project batch size, serial/parallel limits, and external-service rules. If no policy exists, default to one item.
877. **Verify before state changes.** Do not mark an item advanced until evidence exists: target exists, expected files or outputs exist, tests/checks pass, visibility is correct, or the planned artifact is committed.
888. **Update central state.** Record completed work, blocker evidence, next eligible time, next target, and any skipped items.
899. **Ship changes.** If tracked files changed, follow the repository shipping convention: validate, commit, and push unless the project explicitly says not to.
9010. **Report the next action.** End with the next concrete fleet item and the recommended command or lane.
91
92## Control-Repo Files
93
94Prefer existing files. If the project lacks a structure, create or recommend:
95
96```text
97tasks/fleet-status.md # generated or hand-maintained dashboard
98tasks/fleet-queue.md # manifest of items and states
99tasks/fleet-blockers.md # blocker ledger if not embedded in queue
100tasks/history.md # shipped work log
101scripts/fleet-status.* # optional deterministic status generator
102scripts/fleet-next.* # optional next-item selector
103scripts/fleet-provision.* # optional guarded provisioning script
104```
105
106For domain-specific projects, use clearer names like `tasks/repo-seeding.md`, `tasks/migration-queue.md`, or `tasks/customer-rollout.md`. Generic file names are a fallback, not a requirement.
107
108## Guarded Provisioning
109
110Provisioning means any operation that creates, publishes, mutates, or schedules many external targets. Examples: `gh repo create`, remote pushes, deployments, package publishing, account/API provisioning, bulk imports, or paid-service operations.
111
112Before provisioning:
113
114- Confirm explicit user/project approval exists for the operation class.
115- Confirm target visibility and privacy defaults.
116- Confirm the target satisfies the project's readiness gate. For candidate-heavy fleets, the default gate is `spec-ready`; earlier provisioning requires an explicit `scaffold-only` tag.
117- Check service limits and local rolling caps.
118- Use project scripts when they exist.
119- Keep operations serial unless the project explicitly permits parallelism.
120- Stop on auth failures, rate limits, permission errors, target conflicts, visibility mismatches, partial propagation, template validation failures, or unexpected paid/irreversible actions.
121
122On a rate limit, obey `retry-after` or reset headers when available. Otherwise record a conservative next eligible time and switch to work lane if safe.
123
124## Productive Fallback Work
125
126When provisioning is waiting or blocked, advance existing fleet items without violating the provisioning guard:
127
128- Generate or refine per-item roadmaps.
129- Expand implementation plans from source specs.
130- Score and cull candidates, promote promising candidates to `shortlisted`, or archive low-return candidates.
131- Run local validation or hygiene checks.
132- Fix documented blockers that do not require the blocked external operation.
133- Prepare templates, scripts, or status reports.
134- Verify already-created targets.
135
136Do not use fallback work to bypass a guard. If the blocked operation is required for an item, pick a different eligible item.
137
138## Blocker Ledger
139
140Each blocker entry should include:
141
142```text
143timestamp
144item ID / target
145lane
146blocker type
147evidence
148attempted fix
149retry rule or owner
150next eligible action
151```
152
153Common blocker types:
154
155```text
156auth-permission
157rate-limit
158target-conflict
159propagation-delay
160visibility-safety
161template-validation
162dirty-worktree
163missing-source
164verification-failure
165legal-or-policy-risk
166manual-human-action
167```
168
169## Output
170
171Report:
172
173- Current fleet count by state.
174- Portfolio summary when relevant: active-build count/cap, top scored candidates, `scaffold-only` count, `spec-ready` count, and archived/blocked count.
175- Lane selected and why.
176- Items advanced.
177- Guards checked.
178- Blockers created or cleared.
179- Validation evidence.
180- Files changed and shipped status.
181- **Next work:** the next concrete item or blocker.
182- **Recommended next command:** `$project-fleet --execute`, `$project-fleet --status`, another project-specific skill, or the exact project script.
183
184## Constraints
185
186- Do not invent permission to create, publish, deploy, spend money, or make public resources.
187- Do not continue provisioning after a stop-condition failure.
188- Do not parallelize externally fragile operations unless the project explicitly allows it.
189- Do not mark planning/scaffold targets as implementation-complete.
190- Do not move `candidate`, `shortlisted`, or `scaffold-only` items into `active-build` without `spec-ready` evidence.
191- Do not exceed the active-build cap unless the project explicitly changes the cap.
192- Do not let downstream repos become the source of truth for fleet-wide state unless the project explicitly chooses a distributed model.
193
194## Alignment Page
195
196Follow the shared alignment-page convention via the packaged convention resolver; output path is `alignment/project-fleet-{topic}.html`.
197
198## Default Shipping Contract
199
200- **Default next-step routing:** when reporting completion, include either `Recommended next skill: <command>` or the two-line pair `**Next work:** <specific task or "none">` and `**Recommended next command:** <one command or route>` so the next caller has a concrete handoff.
201- If this skill creates or modifies tracked repository files, follow `docs/github-delivery-contract.md` and finish with an issue-backed non-primary branch plus ready pull request; do not merge it.
202- Do not leave tracked changes or unpushed commits behind. If unrelated tracked work is already present, either include it in sensible commits too or stop and explain the blocker.
203- This contract does not override stricter safety rules about secrets, destructive history changes, release publication/tag confirmation, production deploy confirmation, paid actions, or public visibility changes.
GeorgeQLe