@draht/coding-agent 2026.3.3 → 2026.3.5

package/prompts/commands/fix.md

@@ -0,0 +1,35 @@
+---
+description: "Diagnose and fix a bug with TDD discipline"
+---
+
+# /fix
+
+Diagnose and fix a specific bug or failing task with TDD discipline.
+
+## 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)
+   - 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
+- Always reproduce before fixing — a fix without a test is a guess
+- One bug, one fix, one commit. Do not bundle unrelated changes.
+- If the root cause spans multiple files, explain the chain in the commit message

package/prompts/commands/init-project.md

@@ -0,0 +1,55 @@
+---
+description: "Initialize planning for an existing project"
+---
+
+# /init-project
+
+Initialize planning framework for an existing project: codebase mapping → questioning → domain model → requirements → roadmap.
+
+## Usage
+```
+/init-project [focus area or goal]
+```
+
+Focus: $ARGUMENTS
+
+Use this when you have an existing codebase and want to add structured planning.
+For greenfield projects, use `/new-project` instead.
+
+## Steps
+1. Run `draht-tools init` to check preconditions (git repo, etc.)
+2. Run `draht-tools map-codebase` to build a structural map of the existing code
+3. Analyze the codebase map to understand architecture, tech stack, and conventions
+4. Deep questioning phase (3-7 rounds, 1-2 questions at a time):
+   - What is this project? Who uses it?
+   - What are the current pain points or goals?
+   - What is MVP vs aspirational scope?
+   - What constraints exist (infra, team size, deadlines)?
+5. Run `draht-tools create-project` with gathered info
+6. Run `draht-tools create-domain-model` to define bounded contexts, entities, and ubiquitous language
+7. Create `.planning/DOMAIN.md` with:
+   - `## Bounded Contexts` — each context with name, responsibility, and brief description
+   - `## Ubiquitous Language` — glossary of domain terms agreed with the user (term → definition)
+   - `## Context Map` — how bounded contexts relate to each other (upstream/downstream, shared kernel, ACL)
+   - `## Aggregates` — aggregates and their root entities per context
+   - `## Domain Events` — named events that cross context boundaries
+8. 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 (config files, generated code, etc.)
+9. Optional research phase via `draht-tools research`
+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 project planning"`
+
+## Rules
+- Ask 1-2 questions at a time, never dump 10 at once
+- Follow threads based on answers
+- Use examples ("Like Stripe Checkout, or custom?")
+- Confirm, don't assume
+- 3-7 follow-up rounds typical
+- Respect what already exists — do not propose rewriting working code
+- Stop when you have: current state, goals, MVP scope, constraints, success criteria

package/prompts/commands/map-codebase.md

@@ -1,3 +1,7 @@
+---
+description: "Analyze existing codebase before planning"
+---
+
 # /map-codebase
 
 Analyze existing codebase before planning.
@@ -7,8 +11,10 @@ Analyze existing codebase before planning.
 /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:

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,7 @@ 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"`
 
 ## Rules
 - Ask 1-2 questions at a time, never dump 10 at once

package/prompts/commands/next-milestone.md

@@ -0,0 +1,48 @@
+---
+description: "Plan the next milestone after current one completes"
+---
+
+# /next-milestone
+
+Plan the next milestone after the current one is complete.
+
+## Usage
+```
+/next-milestone
+```
+
+## Prerequisites
+- `.planning/ROADMAP.md` must exist
+- Current milestone should be complete or nearly complete
+
+## Steps
+1. Load project context:
+   - Read `.planning/ROADMAP.md` — identify the completed milestone and its phases
+   - Read `.planning/STATE.md` — understand current status
+   - Read `.planning/REQUIREMENTS.md` — check which requirements are satisfied
+   - Read `.planning/DOMAIN.md` (if exists) — review domain model for evolution needs
+2. Review completed work:
+   - Scan `.planning/phases/` for all UAT reports (`*-UAT.md`) and summaries (`*-SUMMARY.md`)
+   - Note what was built, what worked well, what had issues
+3. Assess requirements:
+   - Which v1 requirements are now satisfied?
+   - Which v1 requirements remain?
+   - Should any v2 requirements be promoted based on what we learned?
+   - Are there new requirements discovered during implementation?
+4. Propose next milestone:
+   - Define 3-5 phases, each with a clear goal (outcome, not activity)
+   - Order phases by dependency
+   - Map each phase to specific requirements
+   - Estimate relative complexity
+5. Present the proposed milestone for user approval before writing files
+6. After approval:
+   - Update `ROADMAP.md` with the new milestone and phases
+   - Update `STATE.md` to reflect milestone transition
+   - Update `REQUIREMENTS.md` if requirements changed
+   - Update `DOMAIN.md` if domain model needs evolution
+   - Commit: `draht-tools commit-docs "plan next milestone"`
+
+## Rules
+- Always review what was actually built, not just what was planned
+- Be honest about requirements that slipped or changed scope
+- Each phase goal must be testable — "user can X" not "implement Y"

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,3 +1,7 @@
+---
+description: "Create atomic execution plans for a roadmap phase"
+---
+
 # /plan-phase
 
 Create atomic execution plans for a roadmap phase.
@@ -7,18 +11,20 @@ Create atomic execution plans for a roadmap phase.
 /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"`
+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"`
 
 ## Plan Format
 Plans use XML task format:

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,15 +1,21 @@
+---
+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"`
+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

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

@@ -0,0 +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.
+
+## 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 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:
+   - **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,3 +1,7 @@
+---
+description: "Acceptance testing of completed phase work"
+---
+
 # /verify-work
 
 Walk through acceptance testing of completed phase work.
@@ -7,6 +11,8 @@ Walk through acceptance testing of completed phase work.
 /verify-work [N]
 ```
 
+Phase: $1
+
 ## Steps
 1. Run full test suite and capture results:
    - Execute all tests (`bun test` or project-specific runner)
@@ -16,12 +22,12 @@ Walk through acceptance testing of completed phase work.
    - 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
+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 N P`
+7. 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`
+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 N --gaps-only`
+10. If failures: route to `execute-phase $1 --gaps-only`