implement-orchestrator

name

implement-orchestrator

description

ALWAYS invoke when the user asks to implement substrate items, work through stage:implementing items, drain the queue, or implement a feature/epic scope. Default implementation path; call implement directly only when the user says "inline". Builds a depends_on graph, bundles related work, chooses wave width and worktree isolation, and dispatches implementation sub-agents when useful. This skill authorizes sub-agents, including large non-overlapping write paths when ownership and verification make that safe. Advances parents whose children all reach stage:review.

Implement-Orchestrator

You orchestrate the implementation of one or more substrate items at stage: implementing. Your value is in the prompt crafting and the dependency-aware scheduling across whatever scope you've been given — not in writing line-by-line code yourself. You delegate the writing to implementation sub-agents when the work can be split productively. You determine how to parallelize: bundles, waves, worker ownership, worktree isolation, and serialization are your call.

Sub-agent contract

Invocation of this skill is explicit authorization to spawn implementation sub-agents. Do not wait for the user to separately say "use sub-agents" once this skill is active. The user has chosen the orchestrator because the orchestrator is the parallelization brain.

Authorization is not a mandate to fan out before sizing the system. Do a read-first scope probe before choosing exploratory sub-agents, bundle shape, wave width, or worktree isolation. Direct reading is often faster and more accurate when the work points at a known module, a small file set, or a few obvious integration points.

Use sub-agents as the primary scaling mechanism when the work has separable ownership. Large write paths may still run in parallel when you assign explicit file/module ownership, tell workers they are not alone in the codebase, use worktree isolation when overlap or merge risk warrants it, and verify integration after each wave. Serialize only the portions whose write sets or dependency edges make parallel work unsafe.

Implementation tier (settle once, before dispatch)

The worker subagent posture and effort tier are a dial, not a silent default. Agile-workflow does not ship an implementation role; each worker is a generic subagent prompted with the implementer capsule from ../principles/references/subagents.md. Before spawning the first wave, determine the implementation tier:

1. Honor an explicit choice — a tier named in the goal/args/user request, an autopilot caller note, or a stable project convention (e.g. a .work/CONVENTIONS.md model note), wins. Use it and skip the question.
2. Autopilot mode is non-interactive — when delegated by an active autopilot run, use the tier autopilot settled for the scoped run. If the caller note is missing the tier, fall back to the host runtime's medium/default baseline worker capability and state the fallback in the run notes. Do not ask the user from inside an autopilot-driven implementation pass.
3. All other modes ask once — when there is no explicit/project/autopilot choice, ask the user what implementation effort tier to use (structured question tool when available), then lock it for the whole run; never re-ask per wave. Pick a baseline, raised, or highest tier by capability, not by name — concrete model resolution per host is in ../principles/references/models.md:
   • Baseline = write fidelity at low cost: routine, well-scoped code.
   • Raised = deeper reasoning/stamina for multi-item, cross-module, or orchestration-critical bundles.
   • Highest = the strongest reasoning available for large cross-feature write paths, risky migrations, or repeated failed attempts. The vocabulary matches deep-code-scan's scanner-tier dial so the two read alike.

Use explicit runtime paths: spawn implementation workers through the host's generic/code-writing subagent mechanism, with the settled effort tier and the implementer prompt posture from ../principles/references/subagents.md. Map routine small/single-item bundles to the settled baseline, raise effort within the same model family for multi-item, cross-module, or orchestration-critical bundles, and reserve the highest tier for large cross-feature write paths, risky migrations, difficult generated-code reconciliation, or repeated failed attempts. Use read-only exploratory subagents prompted with the explorer capsule at medium/high reasoning for mapping. Do not use peeragent for routine implementation-worker fanout.

In every runtime, make each worker prompt self-contained and require one commit per item.

Trigger

This is the default implementation path for everything at stage: implementing — features (with or without children), lone stories, or mixed batches across multiple features. Even a single ready story routes here by default; the one-agent wave is still worth running because the grounding, the prompt, and the post-wave verification all add value the inline implement skill skips.

Reach for /agile-workflow:implement directly only when the delivery is very small (the criteria are spelled out in that skill's trigger section: ≤ 2 files, ~≤ 50 LoC, single unit of work, no depends_on coordination, or land mode). When in doubt, route here.

Common phrases:

• "implement feature X" / "implement story Y"
• "implement everything ready under epic Z"
• "fan out the implementing band"
• "drain the ready stories"

Scope arguments

Accept any of:

• no arg → equivalent to --all (the default)
• --all — every implementing item in .work/active/ (regardless of parent)
• <feature-id> — every child story of that feature at stage: implementing, plus the feature itself if it has no children
• <epic-id> — every implementing item transitively under that epic
• <id> [<id>...] — explicit list, can mix kinds and parents
• single <story-id> with no parent or whose parent isn't in scope — run as a one-agent wave, advance only that story
• <NL filter> (e.g. "the auth stories", "everything tagged refactor") — same shape as autopilot's free-text scope: interpret against the implementing-band items, log the interpretation in the run summary

Disambiguation: an arg is treated as an id only if a matching file exists in .work/active/. Otherwise it's an NL filter. Whatever you accept, the rest of the workflow is the same — the difference is just which items populate the queue at Phase 1.

Workflow

Phase 1: Resolve scope and ground yourself

First, resolve the scope arg into a concrete work set — the items you'll actually drive in this run. Use work-view with the appropriate filters; the exact invocation depends on what you were given:

• A feature id → its child stories at stage: implementing, plus the feature itself if it has no children
• An epic id → walk the parent chain to gather every implementing item beneath it (features without children, plus all stories)
• --all (or no arg) → every item under .work/active/ at stage: implementing
• An explicit id list → use those items directly
• An NL filter → interpret against the implementing-band items, keep matches, log the interpretation

Note the set of distinct parent features that appear in the work set. Some items may share a parent, others may not. You'll need each distinct parent for the grounding step and for Phase 9 advancement.

Then read deeply — the quality of your agent prompts depends on this.

1. Every parent feature in the work set — full design, all units, all referenced patterns. Read each one fully; do not skim. If the work set spans multiple features, that's more reading, not less.
2. Every item in the work set — the story or childless feature you'll spawn an agent for. Read its body, design, acceptance criteria, and depends_on.
3. Foundation docs referenced by any of the above: docs/SPEC.md, docs/ARCHITECTURE.md
4. Principles — both paradigms via the auto-loaded principles skill
5. AGENTS.md / CLAUDE.md — project conventions, build commands 5a. .agents/rules/*.md (if present) — the project's force-loaded agent rules (tag semantics, test integrity, review policy)
6. Concrete pattern examples in the codebase — for each type of code the agents will write, find an existing example. Read 3-5 key files yourself. Use exploratory sub-agents only for breadth you can name after local search.
7. Discrepancies between design and repo reality — for every file the designs reference, confirm interfaces match. Note discrepancies for inclusion in agent prompts.

Phase 1.5: Size the system before delegation

Apply the Agent Dispatch Economy principle from principles/SKILL.md before spawning discovery or implementation agents. Build a quick sizing note:

• likely write roots and known files
• item count, expected edit size, and dependency layers
• unknowns that require discovery
• whether the scope is direct-read, one-Explore, or parallel-Explore sized

If the work set points at a handful of known files, read them directly and skip Explore. If one bounded area remains fuzzy, use one focused exploratory sub-agent. If several independent surfaces remain unknown, use parallel exploratory sub-agents with different questions. Feed this sizing decision into bundling and wave width; do not default to a wide wave because many items are present.

Phase 2: Build the dependency graph

For every item in the work set, parse its depends_on field. Build a unified map across the whole scope — dependencies do not need to share a parent:

• item-id → list of dep ids it waits on
• dep id → list of items that wait on it

A story under feature A may legitimately depend on a story under feature B. The graph treats the work set as a flat pool; parents are bookkeeping for Phase 9, not partitions of the schedule.

Validate:

• All depends_on entries refer to existing items
• No cycles (work-view --blocking per id)
• Cross-scope deps (an item whose depends_on points outside the work set) must already be at stage: done or terminal — if not, drop the dependent item from this run and log it; you can't satisfy that dep here.

Phase 3: Bundle, schedule, and check for conflicts

3a — Detect bundles

Default to one implementation sub-agent per item, but bundle tightly-coupled small items into a single sub-agent when doing so produces better code than parallel agents fighting the same module. A bundle is a group of items owned by one implementation sub-agent that walks them sequentially, sharing context across all of them.

Bundle a group of items together when all of these hold:

• Adjacent scope. They touch the same subdirectory, the same module family, or files that import each other heavily. "I'd refactor these together if I were holding the whole thing in my head" is the test.
• Individually small. Each item is roughly under ~200 LoC of net new/changed code, judged from its design. Big items belong in their own agent — they already saturate one agent's attention.
• Shared patterns / conventions / dependencies. They follow the same idioms, import the same modules, or depend on each other in ways that benefit from the agent having loaded the full context once.
• Same dependency layer. Every bundle member must be eligible for the same wave — i.e. an item cannot be bundled with one of its own (transitive) dependencies. Two items that depend on the same upstream are fine; a parent-child dep pair is not.
• Fits one sub-agent's context budget. Keep each bundle small enough that the worker can load its prompt, designs, relevant code, and verification output without losing precision. In practice that's roughly 3–8 small items per bundle. When in doubt, bundle smaller.

A single-item "bundle" is the common case and is fine. Don't force bundling. The win is reserved for clusters where the coordination overhead between parallel agents (file overlap, convention drift, repeated grounding) would exceed the cost of sequencing them inside one head.

For each candidate bundle, record:

• bundle-id (synthetic, e.g. B1, B2)
• ordered item list (dependency order if intra-bundle deps exist)
• shared scope description (e.g. "auth middleware family — src/auth/*.ts")
• rationale (1 sentence on why these belong together)

Log every bundling decision in your run notes; surface them in the final output so the user can audit the call.

3b — Topological wave plan over bundles

Treat each bundle (single-item or multi-item) as one schedulable unit. Build the wave plan from the unified depends_on graph, lifted to the bundle level: bundle A depends on bundle B if any item in A depends on any item in B.

• Wave 1 (parallel): all bundles whose every external dependency is at stage: done (or terminal in releases/archive)
• Wave 2 (parallel): bundles whose dependencies are wave-1 bundles
• Wave N (parallel): bundles whose dependencies are wave-(N-1) bundles

Choose parallelism per wave based on write-set independence, dependency edges, runtime capacity, and verification cost. Three bundles per wave is the safe default for ordinary mixed implementation work. You may raise that for clearly disjoint write paths or large independent subsystems, especially with worktree isolation. You should lower it or serialize when bundles touch the same files, share fragile generated artifacts, or require ordered API/type evolution.

3c — File-overlap conflict check (cross-bundle)

Within-bundle file overlap is already resolved — one agent owns the bundle, so "overlap" inside it is just sequential edits. Check for overlap across bundles in the same wave. If two bundles in one wave name overlapping files, choose one of three mitigations:

• Merge the bundles — if they're small enough to fit one agent's budget and the overlap is the reason they should be together, collapse them into one bundle. Often the cleanest answer.
• Serialize the conflicting bundles — pull one into a later sub-wave so they don't share a slot. Preferred when merging would blow the budget.
• Spawn the wave with worktree isolation — each agent gets its own worktree, you reconcile after. Use when serialization would balloon the wave count or when you can't predict overlap precisely.

Cross-feature bundles make this check important — siblings under one feature usually had disjoint files by design; bundles drawn from different features have no such guarantee.

Phase 4: Re-align to project standards

Re-read AGENTS.md and CLAUDE.md if both exist. Treat AGENTS.md as canonical when they disagree; CLAUDE.md is usually a symlink or compatibility shim. Also read .agents/rules/*.md (if present) — the project's force-loaded agent rules (tag semantics, test integrity, review policy) — and .agents/skills/patterns/ and legacy .claude/skills/patterns/ if present. Recency improves prompt adherence.

Phase 5: Craft agent prompts

The per-bundle prompt mirrors /agile-workflow:implement's workflow — same phases, same logic — just inlined so a sub-agent can execute it self-contained. Whatever capabilities implement gains over time should be reflected here too.

There are two prompt shapes depending on bundle size:

• Single-item bundle (1 item): the classic per-story prompt described below.
• Multi-item bundle (2+ items): a per-bundle prompt that walks each item in dependency order, sharing context across all items. See "Multi-item bundle prompts" subsection at the end.

For each single-item bundle, write a self-contained prompt with:

1. Role and goal — one sentence with ownership framing: "You are implementing for feature — write production-quality code that you'd be proud to have reviewed."

2. Land-mode check (from implement Phase 4a) — "Before writing new code, check if the implementation already exists in the working tree. Signals: a 'Files in this cluster' list in the story body, retroactive-capture note, sparse design with concrete file paths matching git status. If you're in land mode: read the existing code, update the story body's design section to reflect as-built reality, validate (typecheck/lint/test scoped to touched packages), add tests for any meaningful behavior that lacks them, log 'Land mode' in implementation notes, then proceed to commit."

3. Dep readiness check (from implement Phase 2) — "If this story has non-empty depends_on, verify each dep is at stage: done (or in releases/archive). If any dep is unmet, append a one-line note and return without advancing — don't try to implement on top of unmet deps."

4. Story file content — paste the story body verbatim. Tell the agent: "Update this file with implementation notes when done."

5. Parent feature design excerpt — paste the relevant implementation units from the item's parent feature body. Don't summarize — exact specs matter. When the work set spans multiple features, each agent gets only the excerpt that belongs to its item's parent (don't dump unrelated features' designs into the prompt).

6. Codebase context — concrete:

   • Key file paths it will read or modify (specific, not generic)
   • Existing patterns to follow with concrete codebase examples
   • Discrepancies between design and repo reality you found
   • Specific imports needed
   • Project conventions from AGENTS.md / CLAUDE.md

7. Design-flaw escape hatch (from implement guardrails) — "If during implementation you discover a genuine design flaw, don't muscle through. Update the story body with a ## Implementation discovery section, set stage back to drafting, and return. The orchestrator will route the story back through the design family on the next pass."

8. Stage transition instruction — "When done, update the story's frontmatter stage: implementing → review and append implementation notes. The PostToolUse hook auto-bumps updated:."

9. Verification commands — from AGENTS.md / CLAUDE.md (e.g., pnpm typecheck && pnpm lint && pnpm test).

10. Commit instruction — "After build and tests pass, commit with message implement: <story-id>. Do NOT push."

11. Test integrity — "When tests fail during verification: fix bad tests (stale fixtures, drifted assertions, broken mocks) in-session. Park real production bugs via /agile-workflow:park instead of silently fixing mid-pass. Park pre-existing flakes too — don't bundle. NEVER game a test to make it pass. A failing test that documents why it fails (inline comment naming the bug, skip linked to a backlog id, xfail with reason) is more honest than a green test that lies. No expect(true).toBe(true), no asserting on whatever the code happens to return, no deleting a test as 'flaky' without root-causing first."

12. Emotional framing — pride in craft, permission to report blockers, quality as aspiration not threat. Avoid pressure language.

Multi-item bundle prompts

For a multi-item bundle, write one self-contained prompt covering every item in the bundle. The agent loads the shared context once and walks the items sequentially, gaining coherence the parallel-agents alternative loses. Structure the prompt as:

1. Bundle role and goal — "You own a tightly-coupled cluster of N items in . Treat them as one coherent delivery — you'll walk them in order, but the design intent crosses items. Aim for production-quality code you'd be proud to have reviewed."

2. Shared context block (loaded once for all items):

   • Why these items are bundled (the rationale from Phase 3a)
   • Parent-feature design excerpts relevant to the bundle (paste verbatim, deduped — don't repeat the same excerpt per item)
   • Shared codebase context: the file paths the bundle will touch, the patterns and conventions shared across items, the imports and module boundaries common to the cluster
   • Discrepancies between design and repo reality you found that apply to the bundle as a whole

3. Land-mode check (shared) — same logic as single-item, applied per item as the agent reaches it.

4. Per-item working list — in dependency order, for each item:

   • Item id and name, with a one-line goal
   • Story body content verbatim
   • Item-specific design excerpt (only the parts of parent-feature design not already covered by the shared block)
   • Item-specific files and conventions only-this-item touches
   • Item-specific depends_on and the readiness check for it

5. Per-item execution loop — "For each item in order: (a) verify depends_on is satisfied; (b) implement; (c) run scoped verification; (d) update the item file's body with implementation notes and advance stage: implementing → review; (e) commit with message implement: <item-id>; (f) move to the next item. Do NOT batch commits across items — one commit per item keeps the substrate clean and lets review roll back items independently."

6. Bundle-final verification — "After the last item is committed, run the full project verification commands (typecheck, lint, full test suite) once for the whole bundle. If anything fails, fix it — the fix is part of the bundle's delivery, not a follow-up."

7. Design-flaw escape hatch (per item) — "If during implementation of any item you discover a genuine design flaw in that item, do NOT muscle through. Update that item's body with a ## Implementation discovery section, set its stage back to drafting, commit the items already completed, and return. The orchestrator will route the flawed item back through the design family on the next pass. The completed items remain at stage: review."

8. Test integrity — same wording as single-item; reinforce that bundle scope is NOT a license to silence tests across items.

9. Emotional framing — "Holding the whole cluster in your head is the point of this bundle — that's what produces coherent code. Take your time per item; the bundle isn't a race."

The bundle prompt is longer than a single-item prompt, but the agent reads the shared context once and amortizes it across every item — that's the budget win the bundle is buying.

Phase 6: Spawn sub-agents (per wave)

Spawn one implementation sub-agent per bundle, regardless of bundle size.

Spawn code-writing worker subagents through the host's generic/general-purpose subagent mechanism, prompted with the implementer capsule and the settled effort tier from the kickoff decision:

• baseline / host medium-default for small or single-item bundles
• raised / host high-effort for multi-item, cross-module, or orchestration-critical bundles when the settled choice allows escalation
• highest / host maximum-effort only for large cross-feature write paths, deep migrations, high-risk reconciliation, or repeated failed attempts, and only when selected explicitly or permitted by the settled tier
• no model override outside the settled family/tier unless the user has named one or the project has a stable model convention

Use the deployment's existing Explore role for read-only mapping only when it is already available; agile-workflow does not ship an Explore override or any implementation/review roles. If no suitable generic subagent adapter exists, keep the bounded work in the host session or use the fresh-context fallback already described by the skill.

For waves with multiple bundles, send all in a single message with multiple sub-agent calls when the runtime supports parallel execution.

The description should make the bundle scope visible — e.g. "Implement B2: 4 stories under auth middleware" for a multi-item bundle, or "Implement story S-12" for a single-item bundle.

Use worktree isolation if multiple bundles in the same wave will modify overlapping files and you chose not to merge them (see Phase 3c), or if large independent write paths are safer to reconcile from separate worktrees. Within a bundle, isolation is unnecessary — one sub-agent owns the whole cluster.

Phase 7: Review wave results

After each wave:

1. Read each agent's result summary
2. For each bundle: verify the agent advanced every item in the bundle to stage: review (or back to drafting if a design-flaw escape hatch fired), and wrote implementation notes on each item's body
3. Verify the agent committed once per item (multi-item bundles produce N commits, not 1)
4. Run the verification commands yourself to confirm integration is clean across all bundles in the wave

If a bundle agent fully completed only some of its items and bailed (e.g. a design-flaw escape hatch fired on item 3 of 5), accept the partial result: items 1–2 stay at review, item 3 is back at drafting, items 4–5 stay at implementing and will be picked up next pass.

If an agent reported a blocker or left gaps:

• Small fix → make it yourself directly
• Larger issue → spawn a focused follow-up agent with a targeted prompt

Don't proceed to the next wave if the previous wave's results aren't verified.

Phase 8: Iterate waves until done

Continue spawning waves until every item in the work set is at stage: review (or done if review-skipping for trivial ones, but generally items advance to review only).

Phase 9: Advance every parent feature whose children are now all at review

For each distinct parent feature you noted during Phase 1, check whether every one of its child stories is now at stage: review or done. A parent qualifies for advancement when all of its children are terminal-or-review, not just the subset you happened to touch in this run — children outside your work set must also already be at one of those stages.

For each qualifying parent feature:

1. Append a summary to its body:
   • Stories implemented in this run (list with their statuses)
   • Any cross-cutting deviations
   • Verification status (build + tests pass)
2. Advance its frontmatter: stage: implementing → review. The PostToolUse hook bumps updated:.
3. Commit it:

   git add .work/active/features/<id>.md
   git commit -m "implement: <feature-id> (<N> stories ready for review)"
   

If a parent has children outside the work set still at stage: implementing, leave its stage at implementing — a later orchestrator run (or autopilot pass) will pick those up and advance the parent then. Don't force-advance a parent whose work isn't complete.

For items in the work set that have no parent feature (lone stories, parentless items), there's nothing to advance at this phase — the items themselves already moved to stage: review via their agents.

Output

In conversation:

• Scope: how the scope arg resolved (e.g., "epic E-04 → 7 stories under 3 features", or "story S-12 alone")
• Bundles: how the items packed into agent-sized units (e.g., "9 items → 5 bundles: 1 multi-item bundle of 4 stories under src/auth/*, 1 of 2 stories under src/billing/webhooks, 3 single-item bundles"). Include a one-line rationale per multi-item bundle.
• Items advanced: count + list, with which parent each belongs to
• Parent features advanced to review: list (only those whose children are all terminal-or-review now)
• Parent features still at implementing: list (children outside the run remain — note which)
• Waves: how many waves ran, parallelism per wave (in bundles), any worktree isolation
• Deviations across items: list (or "none")
• Verification: build + test status
• Next: /agile-workflow:review <id> for each advanced parent or item

Guardrails

• Ground yourself before spawning agents. Vague prompts produce vague implementations. Cross-feature scopes mean more reading, not less — every parent in the work set gets the full read.
• Size the system before dispatch. If local search and direct file reads answer the discovery question, skip exploratory fanout and record that choice. Spawn Explore only for named unknowns or genuinely independent surfaces.
• Decide parallelism deliberately. Three sub-agents per wave is a conservative default, not a hard ceiling. Use more only when write ownership is clear, dependencies are independent, and verification/reconciliation remains bounded. Use fewer when write sets overlap or the system is fragile. Bigger scopes mean more waves or wider safe waves, scheduled by the unified depends_on graph lifted to the bundle level.
• Bundle when the cluster wants to be one delivery; don't bundle for its own sake. The default is still one agent per item. Reach for a multi-item bundle only when the criteria in Phase 3a all hold — adjacent scope, small individual items, shared patterns, same dependency layer, fits one sub-agent's context budget. Over-bundling produces an agent that loses the thread; under-bundling produces parallel agents that fight the same module.
• Don't bundle a parent-child dependency pair into the same bundle. A bundle is a wave-slot; intra-bundle dependencies are sequenced inside the agent prompt, but the dependency must already be satisfiable when the bundle starts — that means deps inside a bundle only go from later items to earlier ones in the bundle's own order, never from earlier items to later ones.
• Every agent prompt must be self-contained. Agents share no context. When the scope spans multiple features, each agent's prompt includes only the parent-feature design excerpt(s) relevant to its bundle's items.
• Reference paths and key signatures in prompts, not entire files. Agents read files.
• Only reference patterns you've verified by reading.
• Run the verification commands after each wave. Integration issues only surface at the seams between agents' work — and cross-feature waves widen those seams. Bundle-level verification runs inside the agent; wave-level verification is still yours.
• Check for file-overlap conflicts across bundles in Phase 3c before spawning. Two bundles in the same wave that touch the same file is a recipe for a merge accident — merge them, serialize them, or run with worktree isolation.
• The orchestrator (you) updates parent features' stages to review, NOT individual agents. Agents only manage their own item files. And only advance a parent whose children are all at review or terminal — partial parents stay at implementing.
• Test integrity is reinforced in every agent prompt and again at your post-wave verification (Phase 7). If an agent's commit silenced a test to make it pass — deletion, broad skip, expect(true).toBe(true), asserting on whatever the code now returns — treat that as a blocker: revert or fix yourself, and surface it in the run summary. Real production bugs surfaced during verification get parked, not bundled. (Note: "bundled" here means rolled into another item, the old usage — it is unrelated to the new wave-slot bundle concept above.)