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,21 @@ 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/`. A workflow may instead use a lightweight
+`../skills/dispatch.md` from its command wrappers to resolve overrides and load
+only the requested phase and a dedicated completion guide. Migrate workflows
+separately so each change can account for its routing and override contracts.
+If the workflow has no controller or dispatcher, its command wrapper or
+`../SKILL.md` entry point must perform the same override resolution before
+reading the resolved phase file. Never bypass override resolution by reading a
+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,21 +129,23 @@ 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. Every phase route—whether invoked through a controller, dispatcher, workflow entry point, or command wrapper—must resolve the phase filename and check 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/`)
+1. **`.workflows/{workflow}/skills/{phase-file}`** — project-level override at the repo root
+2. **`{phase-file}`** — workflow's built-in default (sibling file in `skills/`)
 
-For example, a team that needs a custom `/sync` phase for the design workflow drops a file at `.workflows/design/skills/sync.md` in their repo. The controller picks it up automatically and announces the override to the user.
+For example, a team that needs a custom `/sync` phase for the design workflow drops a file at `.workflows/design/skills/sync.md` in their repo. The route resolves that file and announces the override to the user.
 
-**Filename mapping.** Most workflows map `/phase` to `{phase}.md`, but some use different filenames. For example, docs-writer maps `/gather` to `gather-context.md` and `/plan` to `plan-structure.md`. Check the Phases list in the workflow's controller to find the correct filename for the override.
+**Filename mapping.** Determine `{phase-file}` once from the workflow's routing documentation—its controller, dispatcher, or documented phase map—and use that same filename for both the project override and built-in fallback. Most workflows map `/phase` to `{phase}.md`, but some use different filenames. For example, docs-writer maps `/gather` to `gather-context.md` and `/plan` to `plan-structure.md`.
 
 ### 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
@@ -138,7 +154,7 @@ Commit `.workflows/` to the consuming repo. Overrides are team-level decisions 
 
 ### Discoverability
 
-When a project uses overrides, document them in the project's `CLAUDE.md` or `AGENTS.md` so newcomers know which phases behave differently from the built-in defaults. The controller announces overrides at runtime, but a static list prevents surprises when reading workflow documentation.
+When a project uses overrides, document them in the project's `CLAUDE.md` or `AGENTS.md` so newcomers know which phases behave differently from the built-in defaults. The route announces project overrides at runtime, but a static list prevents surprises when reading workflow documentation.
 
 ### Example Project Layout
 
@@ -254,7 +270,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
 
@@ -23,9 +23,13 @@ default. Use the first match found:
    at the repo root
 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.
+If the override file exists but is empty, appears malformed, or does not end
+with a detectable terminal instruction, warn the user and fall back to the
+built-in default. The terminal instruction must explicitly direct one supported
+exit: return control to the invoking router, read a completion guide, or re-read
+a controller. The invoking workflow's router determines which supported exits
+it accepts or normalizes; preserve the built-in phase's behavioral contract
+without requiring one routing architecture for every workflow.
 
 If using a project override, announce it: *"Using project override for
 /{phase}."*

bugfix/README.md

@@ -48,8 +48,10 @@ bugfix/
 ├── skills/               # Detailed process definitions
 │   ├── start.md
 │   ├── assess.md
+│   ├── completion.md
 │   ├── controller.md
 │   ├── diagnose.md
+│   ├── dispatch.md
 │   ├── document.md
 │   ├── feedback.md
 │   ├── fix.md
@@ -65,11 +67,25 @@ 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 attended phase **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. `/unattended` continues to use its dedicated unattended flow.
 
 `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