diff --git a/implement/README.md b/implement/README.md index 5273aa8..dda6986 100644 --- a/implement/README.md +++ b/implement/README.md @@ -40,6 +40,13 @@ graph TD | Publish | `/publish` | Push branch, create draft PR | `06-pr-description.md` | | Respond | `/respond` | Address reviewer comments | `07-review-responses.md` | +Each phase command invokes `skills/dispatch.md` with the requested phase. The +dispatcher resolves any project override, loads only that phase, and passes +along the command context. After the phase reports its result, +`skills/completion.md` supplies the shared next-step guidance without loading +the full controller. The controller remains the entry point for workflow +discovery and ambiguous requests. + ## Typical Flow ```text @@ -138,7 +145,9 @@ implement/ │ ├── 01-context.md # Ingest context skeleton │ └── story-testplan.md # Story-scoped testplan skeleton ├── skills/ -│ ├── controller.md # Phase dispatcher and transitions +│ ├── controller.md # Discovery and ambiguous-input router +│ ├── dispatch.md # Explicit-phase dispatcher +│ ├── completion.md # Shared next-step guidance │ ├── ingest.md # Fetch story, explore codebase │ ├── plan.md # Design implementation approach │ ├── revise.md # Incorporate plan feedback diff --git a/implement/SKILL.md b/implement/SKILL.md index 3f678a6..b9fab8e 100644 --- a/implement/SKILL.md +++ b/implement/SKILL.md @@ -1,6 +1,6 @@ --- name: implement -version: 0.8.1 +version: 0.9.0 description: >- Story-to-code workflow that takes a Jira Story, plans the implementation, writes contract-based tests and production code via TDD, validates against diff --git a/implement/commands/code.md b/implement/commands/code.md index 48b2607..b5a828d 100644 --- a/implement/commands/code.md +++ b/implement/commands/code.md @@ -4,8 +4,8 @@ description: "Write tests and production code via TDD, committing incrementally" --- # /code -Read `../skills/controller.md` and follow it. +Read `../skills/dispatch.md` and follow it with `PHASE=code`. -Dispatch the **code** phase. Context: +Context: $ARGUMENTS diff --git a/implement/commands/ingest.md b/implement/commands/ingest.md index 9f34699..4c0da7c 100644 --- a/implement/commands/ingest.md +++ b/implement/commands/ingest.md @@ -4,12 +4,8 @@ description: "Fetch Jira story, load design/PRD context, explore codebase, build --- # /ingest -Read `../skills/controller.md` only if it is not already in this session. -Resolve the ingest skill via `../../_shared/recipes/phase-override-resolution.md` -(WORKFLOW=`implement`, PHASE_FILE=`ingest.md`). Read the resolved -`ingest.md` and execute it. Do not glob this workflow. Do not load -`guidelines.md` or `gh-stack`. Do not call `GetDynamicTools`. +Read `../skills/dispatch.md` and follow it with `PHASE=ingest`. -Dispatch the **ingest** phase. Context: +Context: $ARGUMENTS diff --git a/implement/commands/plan.md b/implement/commands/plan.md index bfa27ac..bea0e6b 100644 --- a/implement/commands/plan.md +++ b/implement/commands/plan.md @@ -4,8 +4,8 @@ description: "Design the implementation approach with task breakdown and test st --- # /plan -Read `../skills/controller.md` and follow it. +Read `../skills/dispatch.md` and follow it with `PHASE=plan`. -Dispatch the **plan** phase. Open cited files from `01-context.md` (slices only; see `../skills/plan.md` Step 1). Context: +Context: $ARGUMENTS diff --git a/implement/commands/publish.md b/implement/commands/publish.md index fb4cc13..e19bfa9 100644 --- a/implement/commands/publish.md +++ b/implement/commands/publish.md @@ -4,8 +4,8 @@ description: "Push branch and create a draft PR in the source repo" --- # /publish -Read `../skills/controller.md` and follow it. +Read `../skills/dispatch.md` and follow it with `PHASE=publish`. -Dispatch the **publish** phase. Context: +Context: $ARGUMENTS diff --git a/implement/commands/respond.md b/implement/commands/respond.md index 8691f99..5504e88 100644 --- a/implement/commands/respond.md +++ b/implement/commands/respond.md @@ -4,8 +4,8 @@ description: "Fetch PR review comments, propose responses, apply code changes" --- # /respond -Read `../skills/controller.md` and follow it. +Read `../skills/dispatch.md` and follow it with `PHASE=respond`. -Dispatch the **respond** phase. Context: +Context: $ARGUMENTS diff --git a/implement/commands/revise.md b/implement/commands/revise.md index 8d6f99b..1e1c92d 100644 --- a/implement/commands/revise.md +++ b/implement/commands/revise.md @@ -4,8 +4,8 @@ description: "Incorporate user feedback into the implementation plan" --- # /revise -Read `../skills/controller.md` and follow it. +Read `../skills/dispatch.md` and follow it with `PHASE=revise`. -Dispatch the **revise** phase. Context: +Context: $ARGUMENTS diff --git a/implement/commands/validate.md b/implement/commands/validate.md index 5eb1385..25a5892 100644 --- a/implement/commands/validate.md +++ b/implement/commands/validate.md @@ -4,8 +4,8 @@ description: "Run tests, lint, coverage analysis, and iterate on gaps" --- # /validate -Read `../skills/controller.md` and follow it. +Read `../skills/dispatch.md` and follow it with `PHASE=validate`. -Dispatch the **validate** phase. Context: +Context: $ARGUMENTS diff --git a/implement/skills/code.md b/implement/skills/code.md index 1c05422..1362ce9 100644 --- a/implement/skills/code.md +++ b/implement/skills/code.md @@ -559,4 +559,4 @@ Report your results: - Any discoveries - Overall implementation status -Then **re-read the controller** (`controller.md`) for next-step guidance. +Then return to the invoking workflow router for completion guidance. diff --git a/implement/skills/completion.md b/implement/skills/completion.md new file mode 100644 index 0000000..835a3a6 --- /dev/null +++ b/implement/skills/completion.md @@ -0,0 +1,32 @@ +--- +name: completion +description: Recommend next steps after one attended implement phase. +--- + +# Implement Phase Completion + +After the completed `PHASE` reports its results, recommend the best next step +for the actual outcome, mention relevant alternatives briefly, and stop for the +user. + +- **ingest:** Recommend `/plan` unless the story context has blocking gaps. If + the story is contradictory or incomplete, recommend clarification from the + story author before planning. +- **plan:** Recommend `/revise` for user-requested changes, or `/code` when the + user has already reviewed and accepted the plan. +- **revise:** Recommend `/code` when the user is satisfied, or another + `/revise` round when further changes remain. +- **code:** Recommend `/validate`. If implementation exposed a plan gap, note + the inline plan update or offer `/plan` when redesign requires user review. +- **validate:** Recommend `/publish` only when validation passed. When failures + remain, recommend fixing them and rerunning `/validate`; offer `/plan` for a + design concern or ambiguous acceptance criterion that requires re-scoping. +- **publish:** Recommend `/respond` when review comments arrive; otherwise the + workflow is complete for now. +- **respond:** Recommend `/validate` after code changes, another `/respond` + round while comments remain, or note completion when the PR is approved and + no work remains. + +The user may start at `/code` with an existing plan or partial implementation, +and may skip `/publish` and `/respond` when working locally. Never auto-advance +between attended phases. diff --git a/implement/skills/controller.md b/implement/skills/controller.md index a17e354..4d6a7ee 100644 --- a/implement/skills/controller.md +++ b/implement/skills/controller.md @@ -1,12 +1,13 @@ --- name: controller -description: Top-level workflow controller that manages phase transitions for story implementation. +description: Discover and route ambiguous story implementation requests. --- # Implement Workflow Controller -You are the workflow controller. Your job is to manage the implementation -workflow by executing phases and handling transitions between them. +Use this controller for workflow discovery and ambiguous-input routing. Once a +phase is selected, delegate its execution and completion guidance to the +lightweight dispatcher. ## Phases @@ -58,100 +59,36 @@ the source repo: ## How to Execute a Phase -1. **Announce** the phase to the user: *"Starting /plan."* -2. **Locate** the skill file — read and follow - `../../_shared/recipes/phase-override-resolution.md` with - WORKFLOW=`implement`, PHASE_FILE=`{phase}.md`. -3. **Read** the resolved skill file -4. **Execute** the skill's steps — the user should see your progress -5. When the skill is done, it will tell you to report findings and - re-read this controller. Do that — then use "Recommending Next Steps" - below to offer options. -6. Present the skill's results and your recommendations to the user -7. **Stop and wait** for the user to tell you what to do next. - -## Recommending Next Steps - -After each phase completes, present the user with **options** — not just one -next step. Use the typical flow as a baseline, but adapt to what actually -happened. - -### Typical Flow - -```text -ingest → plan → [revise loop] → code → validate → publish → [respond loop] -``` - -### What to Recommend - -**Continuing forward:** - -- `/ingest` completed → recommend `/plan` (almost always the right next step) -- `/plan` completed → recommend `/revise` for user review of the plan, or `/code` if the user has already reviewed inline -- `/revise` completed (user satisfied) → recommend `/code`, or another `/revise` round -- `/code` completed → recommend `/validate` (always — never skip validation) -- `/validate` completed (all passing) → recommend `/publish` -- `/validate` completed (failures remain) → recommend fixing issues, then re-running `/validate` -- `/publish` completed → recommend `/respond` when review comments arrive -- `/respond` completed → recommend another `/respond` round, or note that the workflow is done when the PR is approved and merged - -**Looping back:** - -- `/plan` reveals story gaps or contradictions → suggest the user clarify with the story author or update the story -- `/code` reveals plan gaps → the plan is updated inline during implementation; offer `/validate` when implementation is complete -- `/validate` reveals test failures → offer to diagnose and fix, then re-run `/validate` -- `/validate` reveals a design concern (e.g., low public-API coverage signals a component needs decomposition) → present the concern to the user; user decides whether to loop back to `/plan` for redesign or accept an exception -- `/validate` reveals unsatisfied acceptance criteria → if fixable (missing tests or implementation gaps), fix during validation; if the criterion is ambiguous or requires re-scoping, escalate to the user -- `/respond` requires code changes → apply changes, re-run `/validate`, then continue responding - -**Skipping:** - -- If the user already has a plan or partial implementation, they may start at `/code` -- If the user wants to skip PR creation (e.g., working locally), `/publish` and `/respond` may be skipped - -### How to Present Options - -Lead with your top recommendation, then list alternatives briefly: - -```text -Recommended next step: /code — begin TDD implementation following the -approved plan. - -Other options: -- /revise — if you want to adjust the plan first -- /validate — if you've already made code changes and want to check them -``` +Set `PHASE` to the selected phase, then read `dispatch.md` and follow it. The +dispatcher owns phase announcement, override resolution, execution, and +completion routing for both built-in phases and project overrides. ## Starting the Workflow -Before dispatching any phase, check if the project has its own `AGENTS.md` -or `CLAUDE.md`. If they are **already in this session** (workspace rules -or a prior read), do not re-read them. Otherwise read them — they may -contain project-specific conventions, testing standards, or other -guidance that affects how the workflow operates. - -For **ingest**, do not load `guidelines.md`. Those rules apply to -`/plan` and `/code`. Do not glob the implement workflow directory. -Do not call `GetDynamicTools`. Write each ingest artifact path once. - When the user provides a Jira issue key or URL: -1. Execute the **ingest** phase -2. After ingestion, present results and wait +1. Set `PHASE=ingest`. +2. Read `dispatch.md` and follow it. + +If the user invokes a specific command (e.g., `/code`), set `PHASE` to that +command's phase, then read `dispatch.md` and follow it. Do not force the user +through earlier phases. -If the user invokes a specific command (e.g., `/code`), execute that phase -directly — don't force them through earlier phases. +For any other input, summarize the available phases, ask the user for a Jira +issue key or URL or a specific phase command, and stop without reading +`dispatch.md`. ## Error Handling -If any phase fails (Jira MCP errors, build failures, test failures, git -errors): +If a phase cannot complete because of an operational error (for example, a +Jira MCP, build, or git error): 1. **Stop immediately.** Do not advance to the next phase. 2. **Report the error** to the user with the specific error message. 3. **Offer options:** retry the failed step, skip the phase (if optional), or escalate. Do not fabricate results when a tool call fails. Do not silently continue -past errors. +past errors. A completed validation report with a failing verdict is a valid +phase outcome; route it through `completion.md` for fix-and-rerun guidance. ## Context Management @@ -168,7 +105,8 @@ subagent spawning. ## Rules - **Never auto-advance.** Always wait for the user between phases. -- **Recommendations come from this file, not from skills.** Skills report findings; this controller decides what to recommend next. +- **Recommendations come from `completion.md`.** Phase skills report findings; + the completion guide provides the authoritative next-step model. - **Jira is read-only.** The `/ingest` phase reads from Jira but never modifies it. No phase in this workflow writes to Jira. - **Plan evolves during implementation.** `/code` updates `02-plan.md` as tasks are completed. This is expected, not a sign of plan failure. - **Validation is mandatory before publishing.** Never recommend `/publish` unless `/validate` has passed. diff --git a/implement/skills/dispatch.md b/implement/skills/dispatch.md new file mode 100644 index 0000000..e6fb793 --- /dev/null +++ b/implement/skills/dispatch.md @@ -0,0 +1,48 @@ +--- +name: dispatch +description: Resolve and execute one explicitly requested implement phase. +--- + +# Implement Phase Dispatch + +Require `PHASE` to be one of `ingest`, `plan`, `revise`, `code`, `validate`, +`publish`, or `respond`. If it is missing or unsupported, report the valid +phases and stop before resolving a filename. + +Before dispatching, initialize `COMPLETION_CONSUMED=false` and read the project's +`AGENTS.md` or `CLAUDE.md` only if neither is already in the session. For +`PHASE=ingest`, do not glob this workflow, load `guidelines.md` or `gh-stack`, or +call `GetDynamicTools`; these guards apply before loading either a built-in +phase or a project override. + +Announce `Starting /{PHASE}.` and read and follow +`../../_shared/recipes/phase-override-resolution.md` with `WORKFLOW=implement` +and `PHASE_FILE={PHASE}.md`. Read and execute the resolved phase file, passing +through the command context unchanged. + +The built-in fallback is the phase file beside this dispatcher. Follow the +phase through its reporting step. Normalize the recipe's supported exits to a +return to this dispatcher: an invoking-router return, a request for this +workflow's completion guide, or a return to this workflow's controller. Map +`COMPLETION_HANDOFF=router-defined` to the invoking-router return. This mapping +applies during override validation as well as execution. Normalize the handoff +without executing its destination and leave `COMPLETION_CONSUMED=false`. Then +read `completion.md` once and follow its guidance for `PHASE`; the dispatcher +is the only component that reads the completion guide. + +Legacy completion instructions may say to follow `controller.md` only if it +is already in the session. After such a phase finishes its steps and report, +treat it as a supported return even when that condition skips reading the +controller. Preserve the loading condition; do not load the controller just to +complete the phase. + +Controller-return normalization preserves the completion contract of existing +project overrides and remains supported. Prefer an invoking-router return for +new implement phases and overrides; legacy exits do not require migration. + +If the recipe rejects an override, continue with its built-in fallback. Stop +without reading `completion.md` only if that fallback cannot be resolved, an +operational error prevents the phase from completing, or the executing phase +lacks supported completion behavior. Report the specific failure. A completed phase +report with a failing verdict, including `validate.md` reporting `FAIL`, is a +valid outcome: read `completion.md` so it can provide fix-and-rerun guidance. diff --git a/implement/skills/ingest.md b/implement/skills/ingest.md index ce20c09..154499e 100644 --- a/implement/skills/ingest.md +++ b/implement/skills/ingest.md @@ -156,4 +156,4 @@ If the user declined overwrite in 7a, report the diff and that existing context ## Done -Follow `controller.md` only if already in session. +Return to the invoking workflow router for completion guidance. diff --git a/implement/skills/plan.md b/implement/skills/plan.md index 99bafb6..6b0c758 100644 --- a/implement/skills/plan.md +++ b/implement/skills/plan.md @@ -262,4 +262,4 @@ Report your results: - Note any risks or open questions - Assessment of plan completeness -Then **re-read the controller** (`controller.md`) for next-step guidance. +Then return to the invoking workflow router for completion guidance. diff --git a/implement/skills/publish.md b/implement/skills/publish.md index 43985e5..b58d3e2 100644 --- a/implement/skills/publish.md +++ b/implement/skills/publish.md @@ -226,7 +226,6 @@ Present: - PR URL (the full `https://github.com/...` link, not just `owner/repo#number`) - Branch name and base - Number of commits included -- Next steps (share with reviewers, wait for comments, then use `/respond`) ## Output @@ -240,6 +239,5 @@ Present: Report your results: - PR URL and branch name - Commits included -- Suggested next steps -Then **re-read the controller** (`controller.md`) for next-step guidance. +Then return to the invoking workflow router for completion guidance. diff --git a/implement/skills/respond.md b/implement/skills/respond.md index e9e2d8b..4eb09ca 100644 --- a/implement/skills/respond.md +++ b/implement/skills/respond.md @@ -234,4 +234,4 @@ Report your results: - Re-validation recommendation - Outstanding items -Then **re-read the controller** (`controller.md`) for next-step guidance. +Then return to the invoking workflow router for completion guidance. diff --git a/implement/skills/revise.md b/implement/skills/revise.md index cb9c270..70d729c 100644 --- a/implement/skills/revise.md +++ b/implement/skills/revise.md @@ -124,4 +124,4 @@ Report your results: - Any consistency updates made as a side effect - Assessment of plan readiness for `/code` -Then **re-read the controller** (`controller.md`) for next-step guidance. +Then return to the invoking workflow router for completion guidance. diff --git a/implement/skills/validate.md b/implement/skills/validate.md index 47a5173..6dc12c6 100644 --- a/implement/skills/validate.md +++ b/implement/skills/validate.md @@ -426,4 +426,4 @@ Report your results: - Regression status - Overall verdict -Then **re-read the controller** (`controller.md`) for next-step guidance. +Then return to the invoking workflow router for completion guidance.