@draht/coding-agent 2026.3.5 → 2026.3.11-1

package/prompts/commands/fix.md

@@ -4,7 +4,7 @@ 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
 ```
@@ -14,19 +14,21 @@ Diagnose and fix a specific bug or failing task with TDD discipline.
 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

@@ -45,6 +45,18 @@ For greenfield projects, use `/new-project` instead.
 12. Run `draht-tools init-state`
 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
 - Follow threads based on answers

package/prompts/commands/map-codebase.md

@@ -4,7 +4,7 @@ description: "Analyze existing codebase before planning"
 
 # /map-codebase
 
-Analyze existing codebase before planning.
+Analyze existing codebase before planning, using subagents for parallel analysis.
 
 ## Usage
 ```
@@ -16,23 +16,22 @@ Directory: $1
 ## Steps
 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

@@ -37,6 +37,18 @@ Description: $ARGUMENTS
 11. Run `draht-tools init-state`
 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
 - Follow threads based on answers

package/prompts/commands/next-milestone.md

@@ -1,10 +1,10 @@
 ---
-description: "Plan the next milestone after current one completes"
+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
 ```
@@ -13,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/plan-phase.md

@@ -4,7 +4,7 @@ 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
 ```
@@ -21,10 +21,22 @@ Phase: $1
    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 $1 P`
-5. Validate: `draht-tools validate-plans $1`
-6. Commit: `draht-tools commit-docs "create phase $1 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:
@@ -60,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/quick.md

@@ -16,10 +16,17 @@ Task: $ARGUMENTS
 ## Steps
 1. Run `draht-tools next-quick-number` to get task number
 2. Create quick plan: `draht-tools create-quick-plan NNN "$ARGUMENTS"`
-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*
+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/review.md

@@ -4,7 +4,7 @@ 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
 ```
@@ -17,16 +17,16 @@ 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

@@ -4,7 +4,7 @@ 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
 ```
@@ -14,20 +14,34 @@ Walk through acceptance testing of completed phase work.
 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 $1` 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 $1 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 $1`
-   - 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 $1 --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.