@draht/coding-agent 2026.3.2-2

package/prompts/commands/execute-phase.md

@@ -0,0 +1,59 @@
+# /execute-phase
+
+Execute all plans in a phase with atomic commits.
+
+## Usage
+```
+/execute-phase [N] [--gaps-only]
+```
+
+## Steps
+1. Run `draht discover-plans N` to find and order plans
+2. For each plan in dependency order:
+   a. Load plan: `draht 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 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 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 commit-task N P T "refactor: description"`
+
+      **✅ VERIFY**
+      - Run the `<verify>` step
+      - Confirm `<done>` criteria met
+
+   c. Write summary: `draht write-summary N P`
+3. Phase verification: `draht verify-phase N`
+4. Update state: `draht update-state`
+5. Final commit: `draht commit-docs "complete phase N execution"`
+
+## TDD Rules
+- Never write implementation before a failing test exists
+- If a test passes immediately after being written, it is not testing the right thing — fix it
+- Red → Green → Refactor is not optional; skipping steps invalidates the safety net
+- Each TDD phase gets its own commit so the history is auditable
+
+## Domain Rules
+- All identifiers (class names, method names, variables) must use the ubiquitous language from `.planning/DOMAIN.md`
+- 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
+
+## Flags
+- `--gaps-only` → only execute FIX-PLAN.md files from failed verification

package/prompts/commands/map-codebase.md

@@ -0,0 +1,32 @@
+# /map-codebase
+
+Analyze existing codebase before planning.
+
+## Usage
+```
+/map-codebase [directory]
+```
+
+## Steps
+1. Run `draht map-codebase [dir]`
+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:
+   - `## 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
+   - `## 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 commit-docs "map existing codebase"`

package/prompts/commands/new-project.md

@@ -0,0 +1,40 @@
+# /new-project
+
+Initialize a new GSD project: questioning → research → requirements → roadmap.
+
+## Usage
+```
+/new-project [description]
+```
+
+## Steps
+1. Run `draht init` to check preconditions
+2. If existing code detected, run `draht map-codebase` first
+3. Deep questioning phase (3-7 rounds, 1-2 questions at a time)
+4. Run `draht create-project` with gathered info
+5. Run `draht create-domain-model` to define bounded contexts, entities, and ubiquitous language
+6. 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
+7. 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.)
+8. Optional research phase via `draht research`
+9. Run `draht create-requirements` with v1/v2/out-of-scope (map requirements to bounded contexts)
+10. Run `draht create-roadmap` with phases
+11. Run `draht init-state`
+12. Git commit via `draht commit-docs "initialize GSD project"`
+
+## 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
+- Stop when you have: problem, audience, MVP scope, constraints, success criteria

package/prompts/commands/pause-work.md

@@ -0,0 +1,12 @@
+# /pause-work
+
+Create a handoff document for session continuity.
+
+## Usage
+```
+/pause-work
+```
+
+## Steps
+1. Run `draht pause` — creates CONTINUE-HERE.md
+2. Commit: `draht commit-docs "pause work"`

package/prompts/commands/plan-phase.md

@@ -0,0 +1,61 @@
+# /plan-phase
+
+Create atomic execution plans for a roadmap phase.
+
+## Usage
+```
+/plan-phase [N]
+```
+
+## Steps
+1. Run `draht load-phase-context N` to gather all context
+2. Optional: `draht research-phase N` 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 create-plan N P`
+5. Validate: `draht validate-plans N`
+6. Commit: `draht commit-docs "create phase N plans"`
+
+## Plan Format
+Plans use XML task format:
+```xml
+<task type="auto">
+  <n>Task name</n>
+  <context>Bounded context this task belongs to</context>
+  <domain>Aggregates, entities, value objects, or events touched</domain>
+  <files>affected files</files>
+  <test>
+    RED phase: Write failing tests FIRST.
+    - List specific test cases with expected behavior
+    - Test domain invariants and business rules
+    - Test at the right level: unit for domain logic, integration for context boundaries
+    - Tests MUST fail before implementation
+  </test>
+  <action>
+    GREEN phase: Minimal implementation to make tests pass.
+    - No gold-plating — just make the red tests green
+    - Respect aggregate boundaries
+    - Use domain language in code (class names, method names, variable names)
+  </action>
+  <refactor>
+    REFACTOR phase: Improve structure while keeping tests green.
+    - Extract value objects, push logic into domain layer
+    - Ensure naming matches ubiquitous language
+    - Remove duplication across bounded contexts (or make shared kernel explicit)
+  </refactor>
+  <verify>How to verify (tests pass + manual check if needed)</verify>
+  <done>What "done" looks like — expressed as passing test assertions</done>
+</task>
+```
+
+Task types: `auto`, `checkpoint:human-verify`, `checkpoint:decision`
+
+## 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
+- If a plan introduces a new domain term, update `.planning/DOMAIN.md` first
+- Cross-context communication should use domain events, not direct imports

package/prompts/commands/progress.md

@@ -0,0 +1,12 @@
+# /progress
+
+Show current project status.
+
+## Usage
+```
+/progress
+```
+
+## Steps
+1. Run `draht progress` — outputs formatted status
+2. Display the result as-is

package/prompts/commands/quick.md

@@ -0,0 +1,19 @@
+# /quick
+
+Execute a small ad-hoc task with GSD tracking.
+
+## Usage
+```
+/quick [description]
+```
+
+## Steps
+1. Run `draht next-quick-number` to get task number
+2. Create quick plan: `draht 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*
+4. Write summary: `draht write-quick-summary NNN`
+5. Update state: `draht update-state`

package/prompts/commands/resume-work.md

@@ -0,0 +1,13 @@
+# /resume-work
+
+Resume from last session state.
+
+## Usage
+```
+/resume-work
+```
+
+## Steps
+1. Run `draht resume` — loads CONTINUE-HERE.md or STATE.md
+2. Display context and ask to continue
+3. Delete CONTINUE-HERE.md after confirmation

package/prompts/commands/verify-work.md

@@ -0,0 +1,27 @@
+# /verify-work
+
+Walk through acceptance testing of completed phase work.
+
+## Usage
+```
+/verify-work [N]
+```
+
+## 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 quality-gate --strict`
+4. Run `draht 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 create-fix-plan N P`
+   - Fix plans MUST include a reproducing test that demonstrates the failure before any implementation
+8. Write UAT report: `draht 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`