@draht/coding-agent 2026.3.4 → 2026.3.6

package/prompts/commands/execute-phase.md

@@ -1,43 +1,62 @@
+---
+description: "Execute all plans in a phase with atomic commits"
+---
+
 # /execute-phase
 
-Execute all plans in a phase with atomic commits.
+Execute all plans in a phase with atomic commits, parallelizing independent plans via subagents.
 
 ## Usage
 ```
 /execute-phase [N] [--gaps-only]
 ```
 
+Phase: $1
+Arguments: $ARGUMENTS
+
 ## Steps
-1. Run `draht-tools discover-plans N` to find and order plans
-2. For each plan in dependency order:
-   a. Load plan: `draht-tools read-plan N P`
-   b. Execute each task in strict TDD cycle:
-
-      **🔴 RED — Write failing tests first**
-      - Write the test cases from `<test>`
-      - Run tests — confirm they FAIL (if they pass, the test is wrong)
-      - Commit failing tests: `draht-tools commit-task N P T "red: test description"`
-
-      **🟢 GREEN — Minimal implementation**
-      - Write the minimum code from `<action>` to make tests pass
-      - Use domain language from `<context>` and `<domain>` for all names
-      - Run tests — confirm they PASS
-      - Commit: `draht-tools commit-task N P T "green: task name"`
-
-      **🔵 REFACTOR — Clean up with safety net**
-      - Apply improvements from `<refactor>` (if any)
-      - Run tests after each change — must stay green
-      - Verify domain language compliance (names match DOMAIN.md)
-      - Commit: `draht-tools commit-task N P T "refactor: description"`
-
-      **✅ VERIFY**
-      - Run the `<verify>` step
-      - Confirm `<done>` criteria met
-
-   c. Write summary: `draht-tools write-summary N P`
-3. Phase verification: `draht-tools verify-phase N`
-4. Update state: `draht-tools update-state`
-5. Final commit: `draht-tools commit-docs "complete phase N execution"`
+1. Run `draht-tools discover-plans $1` to find and order plans
+2. Read each plan file yourself (from `.planning/phases/`) and analyze dependencies to identify which plans can run in parallel vs sequential
+3. **Delegate execution to subagents:**
+   - For independent plans (no shared files, no dependency chain): use the `subagent` tool in **parallel mode** with `implementer` agents, one per plan.
+   - For dependent plans: execute them sequentially, each via a **single** `subagent` call to `implementer`, waiting for the previous to complete before starting the next.
+   - Each subagent task must include:
+     - The full plan content (paste it into the task — the subagent cannot run draht-tools)
+     - The TDD cycle instructions (see template below)
+     - Instructions to commit with `git add <files> && git commit -m "description"`
+
+4. After all subagents complete, collect results and check for failures
+5. Run `draht-tools verify-phase $1` yourself (not the subagent)
+6. Run `draht-tools update-state` yourself
+7. Final commit: `draht-tools commit-docs "complete phase $1 execution"`
+8. After execution, tell the user to start a new session and run `/verify-work $1`.
+
+## Subagent Task Template
+
+Each implementer subagent receives a task like:
+
+```
+Execute this plan. Here is the full plan content:
+
+<paste full plan XML here>
+
+For each <task> in the plan, follow this TDD cycle:
+1. RED — Write failing tests from <test>. Run the test runner, confirm they FAIL. Commit with: git add <test-files> && git commit -m "red: <description>"
+2. GREEN — Write minimal implementation from <action> to make tests pass. Run tests, confirm PASS. Commit with: git add <files> && git commit -m "green: <task name>"
+3. REFACTOR — Apply <refactor> improvements if any. Tests must stay green after each change. Commit with: git add <files> && git commit -m "refactor: <description>"
+4. VERIFY — Run the <verify> step, confirm <done> criteria are met.
+
+Domain rules: Use ubiquitous language from .planning/DOMAIN.md (read it). Do not import across bounded context boundaries.
+Checkpoint handling: type="auto" → execute silently. type="checkpoint:human-verify" → stop and report back what was built. type="checkpoint:decision" → stop and report the options.
+
+Important: Do NOT run draht, draht-tools, draht help, or pi commands. Use only standard tools (read, bash, edit, write, grep, find, ls).
+```
+
+## Parallelization Rules
+- Plans sharing no files and having no dependency edges can run in parallel
+- If plan B depends on output of plan A, plan B must wait for A to complete
+- Maximum parallel subagents: follow the subagent tool limits (max 8 tasks, 4 concurrent)
+- If a parallel subagent fails, report which plan failed and continue with independent plans
 
 ## TDD Rules
 - Never write implementation before a failing test exists
@@ -50,10 +69,15 @@ Execute all plans in a phase with atomic commits.
 - Do not import across bounded context boundaries directly — use domain events or ACL adapters
 - If implementation reveals a missing domain term, stop and update DOMAIN.md before continuing
 
-## Checkpoint Handling
-- `type="auto"` → execute without pausing
-- `type="checkpoint:human-verify"` → pause, show user, wait for confirmation
-- `type="checkpoint:decision"` → pause, present options, wait for choice
+## Workflow
+This is one step in the per-phase cycle. Each step runs in its own session (`/new` between steps):
+
+```
+/discuss-phase N → /new → /plan-phase N → /new → /execute-phase N → /new → /verify-work N → /new → /discuss-phase N+1 → ...
+```
+
+After completing this command, tell the user to start a new session and run `/verify-work $1`.
+Do NOT suggest `/next-milestone` — that is only after ALL phases in the milestone are verified.
 
 ## Flags
 - `--gaps-only` → only execute FIX-PLAN.md files from failed verification

package/prompts/commands/fix.md

@@ -1,26 +1,34 @@
+---
+description: "Diagnose and fix a bug with TDD discipline"
+---
+
 # /fix
 
-Diagnose and fix a specific bug or failing task with TDD discipline.
+Diagnose and fix a specific bug or failing task with TDD discipline, using a subagent for diagnosis.
 
 ## Usage
 ```
 /fix [description of what's broken]
 ```
 
+Issue: $ARGUMENTS
+
 ## Steps
-1. **Diagnose**: Read the relevant code and error output to identify the root cause
-   - If a test is failing, run it first to see the actual error
-   - If a runtime bug, reproduce it and capture the error
-2. **Write a reproducing test**: Before touching any implementation:
-   - Write a test that demonstrates the bug (it must fail)
+1. **Diagnose via subagent**: Use the `subagent` tool in **single mode** with the `debugger` agent:
+   "Diagnose this issue: $ARGUMENTS. Reproduce the bug by running the relevant test or command. Trace the root cause by reading the code. Identify the exact files and lines involved. Do NOT fix it yet — only report the diagnosis with: root cause, affected files, and a recommended fix approach. Do NOT run draht, draht-tools, or pi commands."
+
+2. **Write a reproducing test**: Based on the diagnosis, write a test that demonstrates the bug (it must fail)
    - Commit: `draht-tools commit-docs "red: reproduce bug"`
+
 3. **Minimal fix**: Write the smallest change that makes the test pass
    - Do not refactor or add features — just fix the bug
    - Run the full test suite to check for regressions
    - Commit: `draht-tools commit-docs "green: fix description"`
+
 4. **Refactor** (if needed): Clean up without changing behavior
    - Tests must stay green after every change
    - Commit: `draht-tools commit-docs "refactor: description"`
+
 5. **Update state**: `draht-tools update-state`
 
 ## Rules

package/prompts/commands/init-project.md

@@ -1,13 +1,19 @@
+---
+description: "Initialize planning for an existing project"
+---
+
 # /init-project
 
-Initialize GSD planning framework for an existing project: codebase mapping → questioning → domain model → requirements → roadmap.
+Initialize planning framework for an existing project: codebase mapping → questioning → domain model → requirements → roadmap.
 
 ## Usage
 ```
 /init-project [focus area or goal]
 ```
 
-Use this when you have an existing codebase and want to add GSD methodology.
+Focus: $ARGUMENTS
+
+Use this when you have an existing codebase and want to add structured planning.
 For greenfield projects, use `/new-project` instead.
 
 ## Steps
@@ -37,7 +43,19 @@ For greenfield projects, use `/new-project` instead.
 10. Run `draht-tools create-requirements` with v1/v2/out-of-scope (map requirements to bounded contexts)
 11. Run `draht-tools create-roadmap` with phases
 12. Run `draht-tools init-state`
-13. Git commit via `draht-tools commit-docs "initialize GSD planning"`
+13. Git commit via `draht-tools commit-docs "initialize project planning"`
+
+## Workflow
+After project initialization, phases are executed one at a time in new sessions:
+
+```
+/init-project → /new → /discuss-phase 1 → /new → /plan-phase 1 → /new → /execute-phase 1 → /new → /verify-work 1
+            → /new → /discuss-phase 2 → /new → /plan-phase 2 → /new → /execute-phase 2 → /new → /verify-work 2
+            → ... (repeat for all phases in the milestone)
+            → /new → /next-milestone (only after ALL phases are complete)
+```
+
+Each step runs in its own session (`/new` between steps). Do NOT suggest `/next-milestone` until every phase in the milestone is verified.
 
 ## Rules
 - Ask 1-2 questions at a time, never dump 10 at once

package/prompts/commands/map-codebase.md

@@ -1,32 +1,37 @@
+---
+description: "Analyze existing codebase before planning"
+---
+
 # /map-codebase
 
-Analyze existing codebase before planning.
+Analyze existing codebase before planning, using subagents for parallel analysis.
 
 ## Usage
 ```
 /map-codebase [directory]
 ```
 
+Directory: $1
+
 ## Steps
-1. Run `draht-tools map-codebase [dir]`
+1. Run `draht-tools map-codebase $1`
 2. Tool generates: STACK.md, ARCHITECTURE.md, CONVENTIONS.md, CONCERNS.md
-3. Review output, supplement with your own analysis if needed
-4. Identify implicit bounded contexts from directory structure:
-   - Look for top-level `src/` subdirectories, packages, or modules that encapsulate a coherent domain concept
-   - Note any cross-directory coupling that suggests context boundaries are blurred
-5. Extract domain language from existing code:
-   - Collect PascalCase class/interface/type names, key function names, and database table/collection names
-   - Look for repeated nouns that represent core domain concepts (e.g., `Order`, `Invoice`, `Subscription`)
-6. If `.planning/DOMAIN.md` does not already exist, create it with:
+3. **Run parallel deep analysis via subagents:**
+   Use the `subagent` tool in **parallel mode** with these tasks:
+   - `architect` agent: "Analyze the codebase at $1. Identify bounded contexts from directory structure — look for top-level src/ subdirectories, packages, or modules that encapsulate coherent domain concepts. Note any cross-directory coupling suggesting blurred context boundaries. Extract domain language: collect PascalCase class/interface/type names, key function names, database table/collection names. Look for repeated nouns representing core domain concepts. Output a structured list of: bounded contexts (name + description), domain terms (glossary), aggregates per context, and context relationships (upstream/downstream, shared kernel, ACL). Do NOT run draht, draht-tools, or pi commands."
+   - `verifier` agent: "Analyze the test infrastructure at $1. Discover: test framework(s) in use (check package.json, config files), test directory conventions (co-located, __tests__/, test/), existing coverage configuration and goals, which layers have tests (unit, integration, e2e), gaps and recommendations. Output a structured test strategy report. Do NOT run draht, draht-tools, or pi commands."
+
+4. Collect subagent results and merge with the draht-tools output
+5. Create `.planning/DOMAIN.md` (if it doesn't exist) with:
    - `## Bounded Contexts` — one entry per discovered context with a brief description
    - `## Ubiquitous Language` — glossary of extracted domain terms
-   - `## Context Map` — rough diagram or list showing how contexts relate
-   - `## Aggregates` — list aggregates and their root entities per context
+   - `## Context Map` — how bounded contexts relate (upstream/downstream, shared kernel, ACL)
+   - `## Aggregates` — aggregates and their root entities per context
    - `## Domain Events` — any existing event names or patterns discovered
-7. Discover test infrastructure and document findings in `.planning/TEST-STRATEGY.md`:
-   - Test framework(s) in use (Jest, Vitest, Bun test, Mocha, etc.)
-   - Test directory conventions (co-located, `__tests__/`, `test/`, etc.)
-   - Existing coverage configuration and goals (if any)
-   - Which layers have tests today (unit, integration, e2e)
-   - Gaps and recommendations
-8. Commit: `draht-tools commit-docs "map existing codebase"`
+6. Create `.planning/TEST-STRATEGY.md` with:
+   - `## Test Framework` — chosen framework and rationale
+   - `## Directory Conventions` — where test files live relative to source
+   - `## Coverage Goals` — target coverage percentage and which paths are critical
+   - `## Testing Levels` — what is tested at unit level vs integration vs e2e, with examples
+   - `## Excluded` — what is explicitly not tested and why
+7. Commit: `draht-tools commit-docs "map existing codebase"`

package/prompts/commands/new-project.md

@@ -1,12 +1,18 @@
+---
+description: "Initialize a new project with structured planning"
+---
+
 # /new-project
 
-Initialize a new GSD project: questioning → research → requirements → roadmap.
+Initialize a new project: questioning → research → requirements → roadmap.
 
 ## Usage
 ```
 /new-project [description]
 ```
 
+Description: $ARGUMENTS
+
 ## Steps
 1. Run `draht-tools init` to check preconditions
 2. If existing code detected, run `draht-tools map-codebase` first
@@ -29,7 +35,19 @@ Initialize a new GSD project: questioning → research → requirements → road
 9. Run `draht-tools create-requirements` with v1/v2/out-of-scope (map requirements to bounded contexts)
 10. Run `draht-tools create-roadmap` with phases
 11. Run `draht-tools init-state`
-12. Git commit via `draht-tools commit-docs "initialize GSD project"`
+12. Git commit via `draht-tools commit-docs "initialize project planning"`
+
+## Workflow
+After project initialization, phases are executed one at a time in new sessions:
+
+```
+/new-project → /new → /discuss-phase 1 → /new → /plan-phase 1 → /new → /execute-phase 1 → /new → /verify-work 1
+           → /new → /discuss-phase 2 → /new → /plan-phase 2 → /new → /execute-phase 2 → /new → /verify-work 2
+           → ... (repeat for all phases in the milestone)
+           → /new → /next-milestone (only after ALL phases are complete)
+```
+
+Each step runs in its own session (`/new` between steps). Do NOT suggest `/next-milestone` until every phase in the milestone is verified.
 
 ## Rules
 - Ask 1-2 questions at a time, never dump 10 at once

package/prompts/commands/next-milestone.md

@@ -1,6 +1,10 @@
+---
+description: "Plan the next milestone after ALL phases in the current milestone are complete"
+---
+
 # /next-milestone
 
-Plan the next milestone after the current one is complete.
+Plan the next milestone after ALL phases in the current one are complete.
 
 ## Usage
 ```
@@ -9,7 +13,9 @@ Plan the next milestone after the current one is complete.
 
 ## Prerequisites
 - `.planning/ROADMAP.md` must exist
-- Current milestone should be complete or nearly complete
+- ALL phases in the current milestone must be complete (verified via /verify-work)
+- This command is ONLY for milestone transitions — NOT for moving between phases within a milestone
+- Between phases, use `/discuss-phase`, `/plan-phase`, `/execute-phase`, `/verify-work` — never `/next-milestone`
 
 ## Steps
 1. Load project context:

package/prompts/commands/pause-work.md

@@ -1,3 +1,7 @@
+---
+description: "Create a handoff document for session continuity"
+---
+
 # /pause-work
 
 Create a handoff document for session continuity.

package/prompts/commands/plan-phase.md

@@ -1,24 +1,42 @@
+---
+description: "Create atomic execution plans for a roadmap phase"
+---
+
 # /plan-phase
 
-Create atomic execution plans for a roadmap phase.
+Create atomic execution plans for a roadmap phase, using subagents for parallel plan creation.
 
 ## Usage
 ```
 /plan-phase [N]
 ```
 
+Phase: $1
+
 ## Steps
-1. Run `draht-tools load-phase-context N` to gather all context
-2. Optional: `draht-tools research-phase N` for domain research
+1. Run `draht-tools load-phase-context $1` to gather all context
+2. Optional: `draht-tools research-phase $1` for domain research
 3. Goal-backward planning:
    a. State the goal (outcome, not activity)
    b. Derive observable truths (3-7 from user perspective)
    c. From each observable truth, derive the test scenarios that would prove it (specific inputs → expected outputs or state changes)
    d. Map to required artifacts (files, endpoints, schemas)
-   e. Break into atomic tasks (2-5 per plan)
-4. Write plans: `draht-tools create-plan N P`
-5. Validate: `draht-tools validate-plans N`
-6. Commit: `draht-tools commit-docs "create phase N plans"`
+   e. Break into plan groups of 2-5 tasks each
+4. Identify which plans are independent (no shared files, no dependency edges)
+5. **Delegate plan creation to subagents:**
+   - For independent plans: use the `subagent` tool in **parallel mode** with `architect` agents, one per plan. Each task should include the phase context, the specific observable truths, target files, and the XML task format (below).
+   - For dependent plans: create them sequentially, each via a **single** `subagent` call to `architect`, passing the outputs of predecessor plans as context.
+   - Each subagent task must include:
+     - The phase context summary (paste it — subagents cannot run draht-tools)
+     - The specific observable truths this plan must satisfy
+     - The target files/artifacts
+     - The XML task format specification (below)
+     - Instruction to output the plan as XML (you will save it via `draht-tools create-plan`)
+
+6. Collect all plan outputs from subagents
+7. Save plans yourself: `draht-tools create-plan $1 P` for each plan
+8. Validate: `draht-tools validate-plans $1`
+9. Commit: `draht-tools commit-docs "create phase $1 plans"`
 
 ## Plan Format
 Plans use XML task format:
@@ -54,6 +72,16 @@ Plans use XML task format:
 
 Task types: `auto`, `checkpoint:human-verify`, `checkpoint:decision`
 
+## Workflow
+This is one step in the per-phase cycle. Each step runs in its own session (`/new` between steps):
+
+```
+/discuss-phase N → /new → /plan-phase N → /new → /execute-phase N → /new → /verify-work N → /new → /discuss-phase N+1 → ...
+```
+
+After completing this command, tell the user to start a new session and run `/execute-phase $1`.
+Do NOT suggest `/next-milestone` — that is only after ALL phases in the milestone are verified.
+
 ## Domain Rules for Plans
 - File/module structure should mirror bounded contexts (e.g., `src/billing/`, `src/catalog/`)
 - Never scatter one aggregate's logic across multiple contexts without an explicit ACL

package/prompts/commands/progress.md

@@ -1,3 +1,7 @@
+---
+description: "Show current project status"
+---
+
 # /progress
 
 Show current project status.

package/prompts/commands/quick.md

@@ -1,19 +1,32 @@
+---
+description: "Execute a small ad-hoc task with tracking"
+---
+
 # /quick
 
-Execute a small ad-hoc task with GSD tracking.
+Execute a small ad-hoc task with tracking.
 
 ## Usage
 ```
 /quick [description]
 ```
 
+Task: $ARGUMENTS
+
 ## Steps
 1. Run `draht-tools next-quick-number` to get task number
-2. Create quick plan: `draht-tools create-quick-plan NNN "description"`
-3. Execute tasks following the TDD cycle:
-   - **🔴 RED** — Write a failing test that describes the desired behaviour
-   - **🟢 GREEN** — Write the minimum implementation to make it pass
-   - **🔵 REFACTOR** — Clean up while keeping the test green
-   - *Exception: skip the TDD cycle only for pure config or documentation-only tasks that have no testable behaviour*
+2. Create quick plan: `draht-tools create-quick-plan NNN "$ARGUMENTS"`
+3. **Delegate execution to subagent**: Use the `subagent` tool in **single mode** with the `implementer` agent:
+   "Execute this task: $ARGUMENTS
+
+   Follow the TDD cycle:
+   - RED — Write a failing test that describes the desired behaviour
+   - GREEN — Write the minimum implementation to make it pass
+   - REFACTOR — Clean up while keeping the test green
+   Exception: skip the TDD cycle only for pure config or documentation-only tasks that have no testable behaviour.
+
+   After completion, report: files changed, tests written, and verification results.
+   Do NOT run draht, draht-tools, draht help, or pi commands — use only standard tools."
+
 4. Write summary: `draht-tools write-quick-summary NNN`
 5. Update state: `draht-tools update-state`

package/prompts/commands/resume-work.md

@@ -1,3 +1,7 @@
+---
+description: "Resume from last session state"
+---
+
 # /resume-work
 
 Resume from last session state.

package/prompts/commands/review.md

@@ -1,26 +1,32 @@
+---
+description: "Code review and security audit of recent changes"
+---
+
 # /review
 
-Ad-hoc code review and security audit of recent changes or a specific scope.
+Code review and security audit of recent changes, using subagents for parallel analysis.
 
 ## Usage
 ```
 /review [scope]
 ```
 
+Scope: $ARGUMENTS
+
 If no scope given, reviews all recent uncommitted changes.
 
 ## Steps
 1. Identify the scope:
-   - If argument given: review those files/directories/description
+   - If argument given: use those files/directories/description as scope
    - If no argument: run `git diff --stat` and `git diff --cached --stat` to find changes
-2. For each changed file, examine:
-   - Correctness: logic errors, off-by-one, null handling, error paths
-   - Type safety: any `as` casts, `any` types, missing null checks
-   - Conventions: naming, file organization, import style
-   - Security: injection risks, auth bypasses, secrets in code, unsafe deserialization
-   - Performance: unnecessary allocations, missing indexes, N+1 queries
-3. Produce a prioritized findings report:
+2. Determine the list of changed files and produce a scope summary
+3. **Delegate to subagents in parallel:**
+   Use the `subagent` tool in **parallel mode** with these tasks:
+   - `reviewer` agent: "Review the following code changes for correctness, type safety, conventions, and potential issues. Scope: <scope summary and file list>. Read each changed file to understand the changes. For each finding: cite the exact file and line, explain the issue, suggest the fix. Prioritize: Critical (must fix) > Important (should fix) > Minor (style/optional). Do NOT run draht, draht-tools, or pi commands."
+   - `security-auditor` agent: "Audit the following code changes for security vulnerabilities. Scope: <scope summary and file list>. Read each changed file. Check for: injection risks, auth bypasses, secrets in code, unsafe deserialization, path traversal, prototype pollution. Report findings with severity, file, line, and recommendation. Do NOT run draht, draht-tools, or pi commands."
+
+4. Collect and merge results from both subagents
+5. Produce a unified, prioritized findings report:
    - **Critical** — must fix before merge (security, data loss, crashes)
    - **Important** — should fix (bugs, type issues, missing error handling)
    - **Minor** — style, naming, or optional improvements
-4. For each finding: cite the exact file and line, explain the issue, suggest the fix

package/prompts/commands/verify-work.md

@@ -1,27 +1,47 @@
+---
+description: "Acceptance testing of completed phase work"
+---
+
 # /verify-work
 
-Walk through acceptance testing of completed phase work.
+Walk through acceptance testing of completed phase work, using subagents for parallel verification.
 
 ## Usage
 ```
 /verify-work [N]
 ```
 
+Phase: $1
+
 ## Steps
-1. Run full test suite and capture results:
-   - Execute all tests (`bun test` or project-specific runner)
-   - Record pass/fail counts — verification cannot proceed if tests are failing
-2. Check domain language violations:
-   - Load `.planning/DOMAIN.md` and extract all defined terms
-   - Scan source files for PascalCase identifiers not present in the glossary
-   - Flag any bounded context boundary violations (cross-context direct imports)
-3. Run quality gate: `draht-tools quality-gate --strict`
-4. Run `draht-tools extract-deliverables N` to get testable items
-5. Walk user through each deliverable one at a time
-6. Record results (pass/fail/partially/skip)
-7. For failures: diagnose and create fix plans via `draht-tools create-fix-plan N P`
+1. Run `draht-tools extract-deliverables $1` to get testable items
+2. **Run parallel verification via subagents:**
+   Use the `subagent` tool in **parallel mode** with these tasks:
+   - `verifier` agent: "Run the full test suite for this project. Check package.json for the test command. Record pass/fail counts. Then run any available lint and typecheck commands (e.g. npm run check, npm run lint, npx tsc --noEmit). Report all results with error details. Do NOT run draht, draht-tools, or pi commands."
+   - `security-auditor` agent: "Audit the recent code changes (use git log and git diff to find them). Check for injection risks, auth bypasses, secrets in code, unsafe patterns. Report findings by severity. Do NOT run draht, draht-tools, or pi commands."
+   - `reviewer` agent: "Review the recent code changes (use git log and git diff). Check domain language compliance against `.planning/DOMAIN.md` if it exists — scan for identifiers not in the glossary and cross-context boundary violations. Report findings. Do NOT run draht, draht-tools, or pi commands."
+
+3. Collect results from all subagents
+4. Walk user through each deliverable one at a time, incorporating findings from the parallel checks
+5. Record results (pass/fail/partially/skip)
+6. For failures: diagnose and create fix plans via `draht-tools create-fix-plan $1 P`
    - Fix plans MUST include a reproducing test that demonstrates the failure before any implementation
-8. Write UAT report: `draht-tools write-uat N`
-   - Report must include: test health summary (pass/fail/coverage), domain model status (any glossary violations), deliverable results
-9. If all passed: mark phase complete
-10. If failures: route to `execute-phase N --gaps-only`
+7. Write UAT report: `draht-tools write-uat $1`
+   - Report must include: test health summary (pass/fail/coverage), security audit results, domain model status (any glossary violations), deliverable results
+8. If all passed: mark phase complete.
+   - If more phases remain in the milestone: tell the user to start a new session and run `/discuss-phase N+1`.
+   - If ALL phases in the milestone are complete: tell the user to start a new session and run `/next-milestone`.
+9. If failures: route to `execute-phase $1 --gaps-only`
+
+## Workflow
+This is the last step in the per-phase cycle. Each step runs in its own session (`/new` between steps):
+
+```
+/discuss-phase N → /new → /plan-phase N → /new → /execute-phase N → /new → /verify-work N
+```
+
+After verify-work passes:
+- More phases remaining → `/new` → `/discuss-phase N+1`
+- ALL phases in milestone verified → `/new` → `/next-milestone`
+
+`/next-milestone` is ONLY for generating new phases after every phase in the current milestone is complete.