refactor(bugfix): demand-load phase routing

.coderabbit.yaml

@@ -61,8 +61,9 @@ reviews:
     - label: "workflow-structure"
       instructions: >-
         Apply when the PR changes SKILL.md, guidelines.md, controller.md,
-        or adds/removes/renames files in skills/ or commands/ directories.
-        Structural changes affect how AI agents discover and execute workflows.
+        dispatch.md, completion.md, or adds/removes/renames files in skills/
+        or commands/ directories. Structural changes affect how AI agents
+        discover and execute workflows.
 
     - label: "new-workflow"
       instructions: >-
@@ -153,15 +154,21 @@ reviews:
           step-by-step instructions or decision logic
         - Must include $ARGUMENTS placeholder to pass user context
         - Path references must be relative to the command file's location:
-          use ../skills/controller.md or ../SKILL.md, not absolute paths
-          and not skills/controller.md (missing ../ prefix)
-        - Every command must have a corresponding skill file it routes to
+          use ../skills/controller.md, ../skills/dispatch.md, ../SKILL.md,
+          or a direct phase-skill path; do not use absolute paths or omit
+          the required ../ prefix
+        - Every command must route to its corresponding phase, either through
+          a direct file reference or an explicit phase parameter passed to a
+          dispatcher (for example, PHASE=assess)
         - No IDE-specific syntax
 
-    # ── Phase skill files ───────────────────────────────────────
+    # ── Workflow skill files ────────────────────────────────────
     - path: "*/skills/*.md"
       instructions: |
-        Phase skill review (ai-workflows conventions):
+        Workflow skill review (ai-workflows conventions):
+        - First classify the file as a phase implementation, controller,
+          dispatcher, completion guide, or other support file. Apply
+          phase-specific rules only to phase implementations.
         - Maximum 10 steps per skill invocation — flag if exceeded
           (cognitive load / context window risk for AI agents)
         - Main steps must be numbered sequentially: no gaps, no
@@ -174,8 +181,17 @@ reviews:
         - Synthesis tasks (summarization, assessment, verdict) must NOT
           be buried after heavy per-item processing — they degrade in
           long contexts
-        - controller.md must reference sibling skills as phase-name.md
-          (not skills/phase-name.md) — relative to its own directory
+        - controller.md, dispatch.md, and completion.md must reference sibling
+          skill files as file-name.md (not skills/file-name.md) — relative to
+          their own directory
+        - A controller may centrally dispatch phases and own transitions, or
+          limit itself to discovery and ambiguous-input routing when explicit
+          commands use a lightweight dispatcher
+        - A dispatcher must remain a thin router: resolve the requested phase,
+          preserve override behavior and context, and delegate transition
+          decisions rather than implementing phase logic
+        - A completion guide may centralize next-step recommendations so phase
+          files do not duplicate the workflow transition model
         - Skills referencing _shared/ resources must use the correct
           relative path depth (e.g., ../../_shared/recipes/self-review-gate.md
           from skills/)
@@ -699,20 +715,28 @@ reviews:
           that exist. Flag references to files that don't exist (dangling
           references). Also flag skill or command files that exist but
           are never referenced from SKILL.md, controller.md, or any
-          command file (orphaned files). For skills/* simple skills, require
+          command file (orphaned files). Treat an explicit dispatcher parameter
+          such as PHASE=assess as a reference to skills/assess.md when the
+          dispatcher documents that mapping. Treat files referenced by a
+          reachable dispatcher or completion guide as reachable. For skills/*
+          simple skills, require
           only that supporting resources are reachable from SKILL.md or another
           reachable reference; do not require workflow-specific files.
         mode: "warning"
 
       - name: "no-content-duplication"
         instructions: |
-          When any of SKILL.md, guidelines.md, or controller.md in a
-          workflow is changed, compare it against whichever of the other
-          two files are present and check for verbatim duplication of
+          When any of SKILL.md, guidelines.md, controller.md, dispatch.md, or
+          completion.md in a workflow is changed, compare it against the other
+          architectural files that are present and check for duplication of
           multi-line instruction blocks or paragraphs. Each has a distinct
           role: SKILL.md is
           the thin entry point, guidelines.md holds principles/limits/
-          safety/quality/escalation, controller.md manages phase dispatch.
+          safety/quality/escalation. A controller may own centralized phase
+          routing and transitions; in a demand-loaded design it handles
+          discovery and ambiguous routing, dispatch.md handles explicit phase
+          routing, and completion.md may hold the authoritative transition
+          model.
           Phase names and brief one-line descriptions appearing in
           multiple files is EXPECTED (cross-referencing, not duplication)
           — only flag substantial blocks of identical prose or

AGENTS.md

@@ -37,10 +37,12 @@ workflow-name/
   guidelines.md         # Behavioral rules: principles, hard limits, safety, quality
   README.md             # Human-readable documentation (prerequisites, artifacts, usage)
   skills/
-    controller.md       # Optional phase dispatcher
+    controller.md       # Optional discovery and ambiguous-input router
+    dispatch.md         # Optional lightweight explicit-phase dispatcher
+    completion.md       # Optional centralized next-step guidance
     phase-name.md       # Implementation for each phase
   commands/
-    phase-name.md       # Thin wrappers that invoke controller or SKILL.md
+    phase-name.md       # Thin wrappers that invoke a controller, dispatcher, SKILL.md, or phase
   scripts/              # Optional — deterministic operations invoked by skills
   prompts/              # Optional — prompt templates for sub-agent delegation
 ```
@@ -69,7 +71,7 @@ guidelines, README, or artifact lifecycle by default.
 3. **Relative paths**: All file references must be relative to the file's location (for symlink compatibility)
 4. **Phase-based execution**: Most workflows operate through discrete phases with explicit transitions
 5. **Shared resources**: Cross-cutting concerns live in `_shared/` and are referenced by relative path from workflows or simple skills
-6. **Phase overrides**: Projects can override individual phases by placing a replacement skill file at `.workflows/{workflow}/skills/{phase}.md` in their repo root. The controller checks for this override before falling back to the built-in default. See CONTRIBUTING.md for details.
+6. **Phase overrides**: Projects can override individual phases by placing a replacement skill file at `.workflows/{workflow}/skills/{phase}.md` in their repo root. The controller or lightweight dispatcher checks for this override before falling back to the built-in default. See CONTRIBUTING.md for details.
 
 ### Shared Resources (`_shared/`)
 
@@ -95,8 +97,8 @@ Recipes are self-contained, parameterized procedures that packages reference via
 ### File Reference Conventions
 
 Critical for symlink resolution:
-- `commands/*.md` reference `../skills/controller.md` (if workflow has a controller) or `../SKILL.md` (for workflows without a controller) or `../skills/phase-name.md` (direct phase reference)
-- `skills/controller.md` (when present) references sibling skills as `phase-name.md` (not `skills/phase-name.md`)
+- `commands/*.md` reference `../skills/controller.md`, `../skills/dispatch.md`, `../SKILL.md`, or `../skills/phase-name.md`; dispatchers identify the target with an explicit phase parameter
+- `skills/controller.md`, `skills/dispatch.md`, and `skills/completion.md` reference sibling skills as `phase-name.md` (not `skills/phase-name.md`)
 - `SKILL.md` references `guidelines.md` and optionally `skills/controller.md` (same directory)
 - `skills/{skill-name}/SKILL.md` references its resources relative to the simple skill directory (for example, `references/rendering.md`)
 

CONTRIBUTING.md

@@ -37,10 +37,12 @@ workflow-name/
   guidelines.md         # Behavioral rules: principles, hard limits, safety, quality, escalation
   README.md             # Human-readable documentation
   skills/
-    controller.md       # Optional -- phase dispatch, transitions, next-step recommendations
+    controller.md       # Optional -- workflow routing and orchestration
+    dispatch.md         # Optional -- lightweight explicit-phase dispatch
+    completion.md       # Optional -- centralized next-step recommendations
     phase-name.md       # One file per phase
   commands/
-    phase-name.md       # Thin wrappers that invoke the controller or SKILL.md for a specific phase
+    phase-name.md       # Thin wrappers that invoke a router, SKILL.md, or phase
 
 Project-level phase overrides (in the consuming repo):
 
@@ -78,12 +80,16 @@ Some workflows use a controller to manage phase execution and transitions. This
 
 - List all phases with references to sibling skill files (e.g. `assess.md`, not `skills/assess.md`).
 - Define how to execute a phase (announce, read, execute, report, wait).
-- Provide next-step recommendations after each phase.
+- Provide next-step recommendations after each phase, directly or through a
+  dedicated completion guide.
 - Never auto-advance -- always wait for the user.
 
 ### skills/phase-name.md
 
-Each phase skill contains the detailed steps for that phase. At the end, it should instruct the agent to report findings and re-read the controller for next-step guidance.
+Each phase skill contains the detailed steps for that phase. At the end, it
+should report findings and follow the workflow's completion contract: either
+return to the invoking router, read a completion guide, or re-read the
+controller, as defined by that workflow.
 
 ### commands/phase-name.md
 
@@ -99,13 +105,18 @@ Dispatch the **phase-name** phase. Context:
 $ARGUMENTS
 ```
 
-The path `../skills/controller.md` is relative to the command file's location inside `commands/`. If the workflow has no controller, commands can reference `../SKILL.md` or the phase skill directly.
+The path `../skills/controller.md` is relative to the command file's location
+inside `commands/`. The bugfix workflow is the first to use a lightweight
+`skills/dispatch.md` that resolves overrides and loads only the requested phase
+and a dedicated completion guide. Migrate other workflows separately so each
+change can account for its routing and override contracts. If the workflow has
+no controller, commands can reference `../SKILL.md` or the phase skill directly.
 
 ## Path Conventions
 
 All internal file references must be **relative to the file's own location**:
 
-- `commands/*.md` reference the controller as `../skills/controller.md` (or `../SKILL.md` if no controller)
+- `commands/*.md` reference `../skills/controller.md`, `../skills/dispatch.md`, `../SKILL.md`, or a phase skill directly
 - `skills/controller.md` (when present) references sibling skills as `assess.md`, `fix.md`, etc.
 - `SKILL.md` references `guidelines.md` and optionally `skills/controller.md` (both in the same directory)
 
@@ -115,7 +126,7 @@ This ensures symlinks resolve paths correctly regardless of where the workflow i
 
 ## Phase Overrides
 
-Projects can override individual phase skills without forking the workflow. When a controller dispatches a phase, it checks for a project-level override before falling back to the built-in default:
+Projects can override individual phase skills without forking the workflow. When a controller or dispatcher routes a phase, it checks for a project-level override before falling back to the built-in default:
 
 1. **`.workflows/{workflow}/skills/{phase}.md`** — project-level override at the repo root
 2. **`{phase}.md`** — workflow's built-in default (sibling file in `skills/`)
@@ -126,10 +137,12 @@ For example, a team that needs a custom `/sync` phase for the design workflow dr
 
 ### Rules for Override Files
 
-- **Start from a copy.** Copy the built-in phase file and modify it rather than writing from scratch. This avoids accidentally omitting contract scaffolding such as artifact paths, exit behavior, or the controller re-read instruction.
+- **Start from a copy.** Copy the built-in phase file and modify it rather than writing from scratch. This avoids accidentally omitting contract scaffolding such as artifact paths and exit behavior.
 - **Full replacement.** An override replaces the entire phase — it is not merged with the built-in. The override file must be self-contained.
-- **Same contract.** The override must read the same input artifacts and write the same output artifacts as the built-in phase. Downstream phases and the controller depend on this contract (see the Artifacts table in each controller).
-- **Same exit behavior.** End the override file with the same "report findings and re-read the controller" instruction so the controller can recommend next steps.
+- **Same contract.** The override must read the same input artifacts and write the same output artifacts as the built-in phase. Downstream phases and the workflow router depend on this contract (see the workflow's Artifacts table).
+- **Same exit behavior.** Preserve the built-in phase's completion contract.
+  Depending on the workflow, that may return to the invoking router, read a
+  completion guide, or re-read the controller.
 - **No cross-references to built-in internals.** The override should not reference sibling files in the workflow's `skills/` directory — it lives in the project repo and should be self-contained.
 
 ### Version Control
@@ -254,7 +267,7 @@ for example `$bugfix assess`.
 
 1. Install locally: `./install.sh cursor` (or `all`).
 2. Open a Cursor project and reference the package to verify discovery.
-3. For a workflow, run at least one phase and verify controller dispatch. For a
+3. For a workflow, run at least one phase and verify its configured routing. For a
    simple skill, exercise its primary behavior and permission gates.
 4. Run every changed script's tests and the same checks configured in CI.
 5. Uninstall and reinstall to verify clean teardown: `./uninstall.sh && ./install.sh cursor`.

_shared/recipes/phase-override-resolution.md

@@ -1,6 +1,6 @@
 ---
 name: phase-override-resolution
-version: 0.1.0
+version: 0.1.1
 ---
 # Recipe: Phase Override Resolution
 
@@ -24,8 +24,11 @@ default. Use the first match found:
 2. **`{PHASE_FILE}`** — workflow's built-in default (sibling file in `skills/`)
 
 If the override file exists but is empty, appears malformed, or does not
-contain exit instructions to re-read the controller, warn the user and fall
-back to the built-in default.
+contain completion or exit guidance, warn the user and fall back to the
+built-in default. Valid exit guidance may return control to the invoking
+router, read a completion guide, or re-read a controller; require the same
+behavioral contract as the workflow's built-in phase rather than one specific
+routing architecture.
 
 If using a project override, announce it: *"Using project override for
 /{phase}."*

bugfix/README.md

@@ -37,6 +37,7 @@ bugfix/
 │   ├── start.md
 │   ├── assess.md
 │   ├── diagnose.md
+│   ├── dispatch.md
 │   ├── document.md
 │   ├── fix.md
 │   ├── pr.md
@@ -48,6 +49,7 @@ bugfix/
 ├── skills/               # Detailed process definitions
 │   ├── start.md
 │   ├── assess.md
+│   ├── completion.md
 │   ├── controller.md
 │   ├── diagnose.md
 │   ├── document.md
@@ -65,11 +67,24 @@ bugfix/
 
 ### How Commands and Skills Work Together
 
-Each **command** is a thin wrapper that invokes a corresponding **skill**. When you run `/diagnose`, the command file tells the agent to read `skills/diagnose.md` and execute it — passing along any arguments you provided plus existing session context.
+Each **command** is a thin wrapper that invokes `skills/dispatch.md` with the
+requested phase. The dispatcher resolves a project override, loads only that
+phase, and passes along the command arguments and session context. It does not
+load the full controller for an explicit command.
 
 `SKILL.md` routes to commands first: if the user invoked a specific command (e.g. `/unattended`, `/diagnose`), it reads the matching `commands/{command}.md`. Otherwise it falls through to the interactive controller flow.
 
-This separation keeps commands simple and consistent while the skills contain the full process details.
+The controller remains available for unqualified requests and legacy project
+overrides whose exit guidance explicitly re-reads it. Explicit commands use
+`skills/completion.md` as the authoritative next-step model without reloading
+the controller after a built-in phase.
+
+Routing `/feedback` through the dispatcher also gives it the same project-level
+phase override support as the other attended commands.
+
+Bugfix is the first workflow to use this demand-loaded dispatch pattern. Other
+workflows continue to use controller-based command routing and can be migrated
+in follow-up changes that account for their individual routing contracts.
 
 ## Workflow Phases
 

bugfix/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: bugfix
-version: 0.7.0
+version: 0.8.0
 description: >-
   Diagnostic and repair workflow that analyzes error logs, traces root causes,
   implements fixes, and verifies with regression tests.

bugfix/commands/assess.md

@@ -4,8 +4,8 @@ description: "Analytical bug assessment: error signature, recommendation, source
 ---
 # /assess
 
-Read `../skills/controller.md` and follow it.
+Read `../skills/dispatch.md` and follow it with `PHASE=assess`.
 
-Dispatch the **assess** phase. Context:
+Context:
 
 $ARGUMENTS

bugfix/commands/diagnose.md

@@ -4,8 +4,8 @@ description: "Identify root cause and impact of a bug"
 ---
 # /diagnose
 
-Read `../skills/controller.md` and follow it.
+Read `../skills/dispatch.md` and follow it with `PHASE=diagnose`.
 
-Dispatch the **diagnose** phase. Context:
+Context:
 
 $ARGUMENTS

bugfix/commands/document.md

@@ -4,8 +4,8 @@ description: "Write release notes and documentation for the fix"
 ---
 # /document
 
-Read `../skills/controller.md` and follow it.
+Read `../skills/dispatch.md` and follow it with `PHASE=document`.
 
-Dispatch the **document** phase. Context:
+Context:
 
 $ARGUMENTS

bugfix/commands/feedback.md

@@ -4,7 +4,7 @@ description: "Address PR review comments on a bug fix"
 ---
 # /feedback
 
-Read `../skills/feedback.md` and follow it.
+Read `../skills/dispatch.md` and follow it with `PHASE=feedback`.
 
 Address PR review feedback. Context:
 

bugfix/commands/fix.md

@@ -4,8 +4,8 @@ description: "Implement the bug fix with minimal diff"
 ---
 # /fix
 
-Read `../skills/controller.md` and follow it.
+Read `../skills/dispatch.md` and follow it with `PHASE=fix`.
 
-Dispatch the **fix** phase. Context:
+Context:
 
 $ARGUMENTS

bugfix/commands/pr.md

@@ -4,8 +4,8 @@ description: "Submit a pull request for the bug fix"
 ---
 # /pr
 
-Read `../skills/controller.md` and follow it.
+Read `../skills/dispatch.md` and follow it with `PHASE=pr`.
 
-Dispatch the **pr** phase. Context:
+Context:
 
 $ARGUMENTS

bugfix/commands/reproduce.md

@@ -4,8 +4,8 @@ description: "Confirm and document bug reproduction steps"
 ---
 # /reproduce
 
-Read `../skills/controller.md` and follow it.
+Read `../skills/dispatch.md` and follow it with `PHASE=reproduce`.
 
-Dispatch the **reproduce** phase. Context:
+Context:
 
 $ARGUMENTS

bugfix/commands/review.md

@@ -4,8 +4,8 @@ description: "Critically evaluate fix and tests for quality"
 ---
 # /review
 
-Read `../skills/controller.md` and follow it.
+Read `../skills/dispatch.md` and follow it with `PHASE=review`.
 
-Dispatch the **review** phase. Context:
+Context:
 
 $ARGUMENTS