refactor(implement): demand-load phase routing

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

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

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

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

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

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

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

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

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

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.