@draht/coding-agent 2026.4.26 → 2026.5.12

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
@@ -1,10 +1,10 @@
1
1
  ---
2
- description: "Acceptance testing of completed phase work"
2
+ description: "Acceptance testing of completed phase work (parallel verifier + security-auditor + reviewer + spec-reviewer)"
3
3
  ---
4
4
 
5
5
  # /verify-work
6
6
 
7
- Walk through acceptance testing of completed phase work, using subagents for parallel verification.
7
+ Walk through acceptance testing of completed phase work, using subagents for parallel verification — including a spec-compliance pass against the phase's plan files.
8
8
 
9
9
  ## Usage
10
10
  ```
@@ -23,30 +23,47 @@ Before verifying, decompose phase acceptance into atomic reasoning units:
23
23
  3. **Verify correctness** — What tests prove it works? What edge cases must pass? What security concerns exist?
24
24
 
25
25
  **Synthesize verification strategy:**
26
- - Group parallel verification tasks (test suite, security audit, code review, domain compliance)
27
- - Map each deliverable to specific test scenarios and acceptance criteria
26
+ - Group parallel verification tasks (test suite, security audit, code review, spec compliance, domain compliance)
27
+ - Map each deliverable to its plan file (the spec)
28
28
  - Identify critical vs optional checks
29
29
  - Plan fix strategies for potential failures
30
30
 
31
31
  ## Steps
32
32
  1. Run `draht-tools extract-deliverables $1` to get testable items
33
- 2. **Run parallel verification via subagents:**
33
+ 2. Discover the phase's plan files (`.planning/phases/<N>-*/<N>-NN-PLAN.md`). Each plan is the spec the spec-reviewer evaluates against.
34
+ 3. **Run parallel verification via subagents:**
34
35
  Use the `subagent` tool in **parallel mode** with these tasks:
35
- - `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."
36
- - `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."
37
- - `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."
38
-
39
- 3. Collect results from all subagents
40
- 4. Walk user through each deliverable one at a time, incorporating findings from the parallel checks
41
- 5. Record results (pass/fail/partially/skip)
42
- 6. For failures: diagnose and create fix plans via `draht-tools create-fix-plan $1 P`
36
+ - `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. End with `STATUS: DONE | DONE_WITH_CONCERNS | NEEDS_CONTEXT | BLOCKED`. Do NOT run draht, draht-tools, or pi commands."
37
+ - `security-auditor` agent: "Audit the recent code changes (use git log and git diff, scoped to this phase's commits). Check for injection risks, auth bypasses, secrets in code, unsafe patterns. Report findings by severity. End with `STATUS: ...`. Do NOT run draht, draht-tools, or pi commands."
38
+ - `reviewer` agent: "Review the recent code changes for this phase. Check domain language compliance against `.planning/DOMAIN.md` if it exists — scan for identifiers not in the glossary and cross-context boundary violations. Report Must fix / Should fix / Consider. End with `STATUS: ...`. Do NOT run draht, draht-tools, or pi commands."
39
+ - `spec-reviewer` agent: "Phase-level spec compliance check for phase $1. The phase has these plan files (each is a spec): <list of .planning/phases/<N>-*/<N>-NN-PLAN.md paths>. For each plan, evaluate whether the phase's commits implement exactly what the plan's <task> elements asked — no missing tasks, no over-builds. Use git log and git diff against the phase commit range. Output a per-plan compliance verdict with omissions and over-builds. End with `STATUS: ...`."
40
+
41
+ 4. **Read each subagent's `STATUS:` line.** Treat the phase as failed if any of these is `BLOCKED`:
42
+ - `verifier` (tests / lint / typecheck failed)
43
+ - `security-auditor` (Critical or High findings)
44
+ - `spec-reviewer` (any plan non-compliant)
45
+ - `reviewer` (Must-fix correctness issues)
46
+
47
+ 5. Collect results and walk user through each deliverable, incorporating findings.
48
+ 6. Record results (pass/fail/partially/skip).
49
+ 7. For failures: diagnose and create fix plans via `draht-tools create-fix-plan $1 P`
43
50
  - Fix plans MUST include a reproducing test that demonstrates the failure before any implementation
44
- 7. Write UAT report: `draht-tools write-uat $1`
45
- - Report must include: test health summary (pass/fail/coverage), security audit results, domain model status (any glossary violations), deliverable results
46
- 8. If all passed: mark phase complete.
51
+ - Spec-reviewer omissions become explicit fix-plan tasks (one task per omission)
52
+ 8. Write UAT report: `draht-tools write-uat $1`
53
+ - Report must include: test health summary (pass/fail/coverage), security audit results, **spec compliance summary per plan**, domain model status (any glossary violations), deliverable results
54
+ 9. If all passed: mark phase complete.
47
55
  - If more phases remain in the milestone: tell the user to start a new session and run `/discuss-phase N+1`.
48
56
  - If ALL phases in the milestone are complete: tell the user to start a new session and run `/next-milestone`.
49
- 9. If failures: route to `execute-phase $1 --gaps-only`
57
+ 10. If failures: route to `execute-phase $1 --gaps-only`
58
+
59
+ ## Why a phase-level spec-reviewer
60
+
61
+ `/execute-phase` already runs spec-reviewer **per task** before the next task starts. The phase-level pass here catches things the per-task loop can miss:
62
+ - A whole plan was skipped (no implementer ever ran on it)
63
+ - A task's commit was reverted or rebased away
64
+ - Out-of-scope drift that accumulated across multiple tasks
65
+
66
+ Cheap insurance — the diff and plans already exist; the agent maps one to the other.
50
67
 
51
68
  ## Workflow
52
69
  This is the last step in the per-phase cycle. Each step runs in its own session (`/new` between steps):
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@draht/coding-agent",
3
- "version": "2026.4.26",
3
+ "version": "2026.5.12",
4
4
  "description": "Coding agent CLI with read, bash, edit, write tools and session management",
5
5
  "type": "module",
6
6
  "drahtConfig": {
@@ -46,10 +46,11 @@
46
46
  },
47
47
  "dependencies": {
48
48
  "@mariozechner/jiti": "^2.6.2",
49
- "@draht/agent-core": "2026.4.26",
50
- "@draht/ai": "2026.4.26",
51
- "@draht/tui": "2026.4.26",
49
+ "@draht/agent-core": "2026.5.12",
50
+ "@draht/ai": "2026.5.12",
51
+ "@draht/tui": "2026.5.12",
52
52
  "@silvia-odwyer/photon-node": "^0.3.4",
53
+ "@sinclair/typebox": "^0.34.41",
53
54
  "ajv": "^8.17.1",
54
55
  "chalk": "^5.5.0",
55
56
  "cli-highlight": "^2.1.11",
@@ -93,7 +94,7 @@
93
94
  "tui",
94
95
  "agent"
95
96
  ],
96
- "author": "Mario Zechner",
97
+ "author": "Oskar Freye",
97
98
  "license": "MIT",
98
99
  "publishConfig": {
99
100
  "access": "public"
@@ -4,6 +4,18 @@ description: "Analyze changes and create atomic commits"
4
4
 
5
5
  # Git Atomic Commit Analysis
6
6
 
7
+ ## Red Flags — STOP
8
+
9
+ Do NOT proceed with a commit if **any** of these is true:
10
+
11
+ - A single proposed commit mixes unrelated concerns (feature + unrelated refactor + config tweak)
12
+ - The change set contains potential secrets (`.env`, credentials, API keys in source)
13
+ - Staged content includes files unrelated to the user's stated intent
14
+ - Pre-commit hooks fail — fix the cause, never use `--no-verify`
15
+ - You cannot articulate the "why" of a commit in one sentence — split it
16
+
17
+ Surface any of these to the user and split the change set before continuing.
18
+
7
19
  ## Atomic Reasoning
8
20
 
9
21
  Before creating commits, decompose changes into atomic reasoning units:
@@ -1,10 +1,10 @@
1
1
  ---
2
- description: "Execute all plans in a phase with atomic commits"
2
+ description: "Execute all plans in a phase with atomic commits + per-task two-stage review"
3
3
  ---
4
4
 
5
5
  # /execute-phase
6
6
 
7
- Execute all plans in a phase with atomic commits, parallelizing independent plans via subagents.
7
+ Execute all plans in a phase with atomic commits, parallelizing independent plans via subagents. Each task is implemented, then **spec-reviewed**, then **quality-reviewed** before the next task begins.
8
8
 
9
9
  ## Usage
10
10
  ```
@@ -14,6 +14,16 @@ Execute all plans in a phase with atomic commits, parallelizing independent plan
14
14
  Phase: $1
15
15
  Arguments: $ARGUMENTS
16
16
 
17
+ ## Red Flags — STOP
18
+
19
+ STOP and report to the user instead of proceeding if **any** of these is true:
20
+
21
+ - Any plan file contains placeholder text: `[TBD]`, `[files]`, `[description]`, "appropriate error handling", "similar to Task N", or empty `<test>` / `<action>` / `<verify>` / `<done>` sections
22
+ - A plan has zero `<task>` elements
23
+ - `.planning/DOMAIN.md` is absent on a non-greenfield project
24
+ - The working tree is dirty with changes unrelated to this phase
25
+ - A subagent returns `STATUS: BLOCKED` — never retry blindly; report and ask the user
26
+
17
27
  ## Atomic Reasoning
18
28
 
19
29
  Before executing, decompose this phase execution into atomic reasoning units:
@@ -30,22 +40,35 @@ Before executing, decompose this phase execution into atomic reasoning units:
30
40
 
31
41
  ## Steps
32
42
  1. Run `draht-tools discover-plans $1` to find and order plans
33
- 2. Read each plan file yourself (from `.planning/phases/`) and analyze dependencies to identify which plans can run in parallel vs sequential
34
- 3. **Delegate execution to subagents:**
35
- - For independent plans (no shared files, no dependency chain): use the `subagent` tool in **parallel mode** with `implementer` agents, one per plan.
36
- - For dependent plans: execute them sequentially, each via a **single** `subagent` call to `implementer`, waiting for the previous to complete before starting the next.
37
- - Each subagent task must include:
38
- - The full plan content (paste it into the task — the subagent cannot run draht-tools)
39
- - The TDD cycle instructions (see template below)
40
- - Instructions to commit with `git add <files> && git commit -m "description"`
41
-
42
- 4. After all subagents complete, collect results and check for failures
43
- 5. Run `draht-tools verify-phase $1` yourself (not the subagent)
43
+ 2. Run `draht-tools validate-plans $1` — if any plan has placeholders or missing sections, STOP and fix the plan first
44
+ 3. Read each plan file yourself (from `.planning/phases/`) and analyze dependencies to identify which plans can run in parallel vs sequential
45
+ 4. **Per-plan execution loop.** For each plan (parallel where independent, sequential where dependent), iterate over its `<task>` elements with a **three-stage** dispatch:
46
+
47
+ ### Stage 1 — Implementer
48
+ Use the `subagent` tool in **single mode** with the `implementer` agent. Prompt includes the full plan content + the TDD cycle instructions (template below). Read the final `STATUS:` line:
49
+ - `DONE` → go to Stage 2.
50
+ - `DONE_WITH_CONCERNS` → if concerns are correctness-related, re-dispatch with a fix instruction; otherwise note and proceed.
51
+ - `NEEDS_CONTEXT` → provide the missing info and re-dispatch.
52
+ - `BLOCKED` → STOP, report to the user.
53
+
54
+ ### Stage 2 — Spec-reviewer
55
+ Use the `subagent` tool with the `spec-reviewer` agent. ONLY checks "does the diff cover exactly what the spec asked for". Prompt includes the task XML and the diff range.
56
+ - `DONE` → go to Stage 3.
57
+ - `DONE_WITH_CONCERNS` → note and proceed.
58
+ - `BLOCKED` → re-dispatch implementer with the "Required Fixes" list; repeat Stage 1+2 until `DONE`. Never proceed to Stage 3 with a non-compliant diff.
59
+
60
+ ### Stage 3 — Reviewer (code quality)
61
+ Use the `subagent` tool with the `reviewer` agent for code-quality review. Spec compliance is already ✅.
62
+ - `DONE` → task complete; move to next task.
63
+ - `DONE_WITH_CONCERNS` → log `Should fix` items; if any are correctness-critical, re-dispatch implementer.
64
+ - `BLOCKED` → `Must fix` issues exist; re-dispatch implementer with the issue list. Repeat until `DONE`.
65
+
66
+ 5. After all plans complete, run `draht-tools verify-phase $1` yourself (not the subagent)
44
67
  6. Run `draht-tools update-state` yourself
45
68
  7. Final commit: `draht-tools commit-docs "complete phase $1 execution"`
46
69
  8. After execution, tell the user to start a new session and run `/verify-work $1`.
47
70
 
48
- ## Subagent Task Template
71
+ ## Subagent Task Template (Stage 1: implementer)
49
72
 
50
73
  Each implementer subagent receives a task like:
51
74
 
@@ -55,20 +78,28 @@ Execute this plan. Here is the full plan content:
55
78
  <paste full plan XML here>
56
79
 
57
80
  For each <task> in the plan, follow this TDD cycle:
58
- 1. RED — Write failing tests from <test>. Run the test runner, confirm they FAIL. Commit with: git add <test-files> && git commit -m "test: <description>"
59
- 2. GREEN — Write minimal implementation from <action> to make tests pass. Run tests, confirm PASS. Commit with: git add <files> && git commit -m "feat: <task name>"
81
+ 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>"
82
+ 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>"
60
83
  3. REFACTOR — Apply <refactor> improvements if any. Tests must stay green after each change. Commit with: git add <files> && git commit -m "refactor: <description>"
61
84
  4. VERIFY — Run the <verify> step, confirm <done> criteria are met.
62
85
 
63
86
  Domain rules: Use ubiquitous language from .planning/DOMAIN.md (read it). Do not import across bounded context boundaries.
64
87
  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.
65
88
 
89
+ End your response with `STATUS: DONE | DONE_WITH_CONCERNS | NEEDS_CONTEXT | BLOCKED` per the agent contract.
90
+
66
91
  Important: Do NOT run draht, draht-tools, draht help, or pi commands. Use only standard tools (read, bash, edit, write, grep, find, ls).
67
92
  ```
68
93
 
94
+ ## Two-Stage Review Rationale
95
+
96
+ - **Spec compliance prevents over/under-building.** The spec-reviewer catches drift before quality review masks it.
97
+ - **Code quality runs only after spec ✅.** Never accept "close enough" on spec compliance.
98
+ - **Tasks within a plan are sequential** — review loop completes before next task starts.
99
+
69
100
  ## Parallelization Rules
70
101
  - Plans sharing no files and having no dependency edges can run in parallel
71
- - If plan B depends on output of plan A, plan B must wait for A to complete
102
+ - Inside a plan, tasks run sequentially with the three-stage loop
72
103
  - Maximum parallel subagents: follow the subagent tool limits (max 8 tasks, 4 concurrent)
73
104
  - If a parallel subagent fails, report which plan failed and continue with independent plans
74
105
 
@@ -1,10 +1,10 @@
1
1
  ---
2
- description: "Diagnose and fix a bug with TDD discipline"
2
+ description: "Diagnose and fix a bug with a 4-phase systematic debugging protocol + TDD discipline"
3
3
  ---
4
4
 
5
5
  # /fix
6
6
 
7
- Diagnose and fix a specific bug or failing task with TDD discipline, using a subagent for diagnosis.
7
+ Diagnose and fix a bug using the **four-phase systematic debugging protocol**: root cause investigation → pattern analysis → hypothesis & testing → implementation with a reproducing test.
8
8
 
9
9
  ## Usage
10
10
  ```
@@ -13,39 +13,102 @@ Diagnose and fix a specific bug or failing task with TDD discipline, using a sub
13
13
 
14
14
  Issue: $ARGUMENTS
15
15
 
16
- ## Atomic Reasoning
16
+ ## The Iron Law
17
+
18
+ > **NO FIXES WITHOUT ROOT CAUSE INVESTIGATION FIRST.**
19
+
20
+ Symptom fixes are failure. If you find yourself proposing a "quick fix for now, investigate later", STOP and return to Phase 1.
21
+
22
+ ## Red Flags — STOP
17
23
 
18
- Before diagnosing, decompose this bug into atomic reasoning units:
24
+ Stop immediately if you catch yourself:
25
+ - Proposing "quick fixes for now, investigate later"
26
+ - Attempting multiple changes simultaneously
27
+ - Skipping a reproducing test before fixing
28
+ - Proposing solutions before understanding data flow
29
+ - Making "one more fix attempt" after already trying 2+
30
+ - Watching each fix reveal new problems elsewhere
31
+
32
+ After **3 failed fix attempts**, STOP. This is an architectural problem, not a hypothesis problem. Report back to the user — do not try a 4th fix.
33
+
34
+ ## Atomic Reasoning
19
35
 
20
36
  1. **State the logical component** — What is the observed failure? What should happen vs what actually happens?
21
37
  2. **Validate independence** — Which components/files are involved? Can we isolate the failure? Are there related bugs that should be fixed separately?
22
38
  3. **Verify correctness** — What test will reproduce this bug reliably? What would prove it's fixed? What regressions could the fix introduce?
23
39
 
24
- **Synthesize fix strategy:**
25
- - Trace the failure to root cause
26
- - Write a minimal reproducing test
27
- - Identify the smallest change that makes the test pass
28
- - Plan regression checks
40
+ ## The Four Phases
29
41
 
30
- ## Steps
31
- 1. **Diagnose via subagent**: Use the `subagent` tool in **single mode** with the `debugger` agent:
32
- "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."
42
+ ### Phase 1 — Root Cause Investigation (before ANY fix)
33
43
 
34
- 2. **Write a reproducing test**: Based on the diagnosis, write a test that demonstrates the bug (it must fail)
35
- - Commit: `draht-tools commit-docs "test: reproduce bug"`
44
+ Use the `subagent` tool in **single mode** with the `debugger` agent. Prompt:
36
45
 
37
- 3. **Minimal fix**: Write the smallest change that makes the test pass
38
- - Do not refactor or add features — just fix the bug
39
- - Run the full test suite to check for regressions
40
- - Commit: `draht-tools commit-docs "fix: fix description"`
46
+ ```
47
+ Investigate this issue using Phase 1 root-cause discipline. Do NOT fix anything — only diagnose.
48
+
49
+ Issue: $ARGUMENTS
50
+
51
+ Walk through these steps and report on each:
52
+ 1. Read the error message / stack trace carefully — exact line numbers, exact file paths.
53
+ 2. Reproduce consistently — exact steps. If you cannot reproduce, gather more data instead of guessing.
54
+ 3. Check recent changes — `git log --oneline -20` and `git diff HEAD~5` against affected files.
55
+ 4. Trace data flow upward until you find the source. Fix at source, not at symptom.
56
+ 5. State the root cause as one sentence: "X happens because Y at <file:line>."
57
+
58
+ End your response with `STATUS: DONE | DONE_WITH_CONCERNS | NEEDS_CONTEXT | BLOCKED`.
59
+ Do NOT run draht, draht-tools, or pi commands.
60
+ ```
41
61
 
42
- 4. **Refactor** (if needed): Clean up without changing behavior
43
- - Tests must stay green after every change
44
- - Commit: `draht-tools commit-docs "refactor: description"`
62
+ If `BLOCKED` or `NEEDS_CONTEXT`: provide the missing info and re-dispatch.
63
+
64
+ ### Phase 2 — Pattern Analysis
65
+
66
+ 1. Find working examples in the codebase that do the same kind of thing correctly
67
+ 2. Read those references completely — not skimmed
68
+ 3. List every difference between the working code and the broken code
69
+ 4. Note dependencies the working version assumes
70
+
71
+ If Phase 2 reveals a different root cause, go back to Phase 1.
72
+
73
+ ### Phase 3 — Single Hypothesis Test
74
+
75
+ 1. State ONE hypothesis: "I think the root cause is X because Y."
76
+ 2. Apply the smallest possible change to test it — one variable.
77
+ 3. Did it fix the issue?
78
+ - Yes → proceed to Phase 4.
79
+ - No → form a NEW hypothesis. Revert the test change. Do not pile changes.
80
+ 4. After 3 hypotheses still failing: STOP. Question architecture, not hypothesis. Report to user.
81
+
82
+ ### Phase 4 — Implementation
83
+
84
+ 1. **Write the reproducing test FIRST.** Confirm it FAILS for the right reason.
85
+ - Commit: `draht-tools commit-docs "red: reproduce <bug>"`
86
+
87
+ 2. **Apply the single fix** from Phase 3. No other changes.
88
+ - Failing test now PASSES.
89
+ - Full test suite — no regressions.
90
+ - Commit: `draht-tools commit-docs "green: fix <bug>"`
91
+
92
+ 3. **Refactor (optional)** — only if clear improvement, no behaviour change. Tests stay green.
93
+ - Commit: `draht-tools commit-docs "refactor: <description>"`
94
+
95
+ 4. **Verify the original symptom is gone** — run the user-level reproduction.
45
96
 
46
97
  5. **Update state**: `draht-tools update-state`
47
98
 
99
+ ## Rationalization Table
100
+
101
+ | Excuse | Reality |
102
+ |--------|---------|
103
+ | "Simple bug, skip the process" | Simple bugs have root causes too. The process is fast. |
104
+ | "It's an emergency, no time" | Systematic debugging is *faster* than thrashing. |
105
+ | "I'll write the test after I confirm the fix" | Untested fixes don't stick. |
106
+ | "I'll just try things and see what works" | Can't isolate what worked. Creates new bugs. |
107
+ | "I already manually tested it" | A reproducing test is the only durable proof. |
108
+
48
109
  ## Rules
49
- - Always reproduce before fixing — a fix without a test is a guess
50
- - One bug, one fix, one commit. Do not bundle unrelated changes.
110
+ - Always reproduce before fixing
111
+ - One bug, one fix, one commit series
112
+ - Fix at source, not symptom
113
+ - 3 failed attempts ⇒ architecture problem, stop and discuss
51
114
  - If the root cause spans multiple files, explain the chain in the commit message
@@ -34,10 +34,10 @@ Before analyzing, decompose codebase understanding into atomic reasoning units:
34
34
  2. Tool generates: STACK.md, ARCHITECTURE.md, CONVENTIONS.md, CONCERNS.md
35
35
  3. **Run parallel deep analysis via subagents:**
36
36
  Use the `subagent` tool in **parallel mode** with these tasks:
37
- - `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."
38
- - `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."
37
+ - `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). End with `STATUS: DONE | DONE_WITH_CONCERNS | NEEDS_CONTEXT | BLOCKED`. Do NOT run draht, draht-tools, or pi commands."
38
+ - `verifier` agent: "Analyze the test infrastructure at $1. Discover: test framework(s) in use, test directory conventions, existing coverage configuration and goals, which layers have tests (unit, integration, e2e), gaps and recommendations. Output a structured test strategy report. End with `STATUS: ...`. Do NOT run draht, draht-tools, or pi commands."
39
39
 
40
- 4. Collect subagent results and merge with the draht-tools output
40
+ 4. Read each subagent's `STATUS:` line. `BLOCKED` or `NEEDS_CONTEXT` from either means STOP — partial output here corrupts downstream phases. Collect subagent results and merge with the draht-tools output.
41
41
  5. Create `.planning/DOMAIN.md` (if it doesn't exist) with:
42
42
  - `## Bounded Contexts` — one entry per discovered context with a brief description
43
43
  - `## Ubiquitous Language` — glossary of extracted domain terms
@@ -9,7 +9,7 @@ Decompose a task and dispatch the right mix of specialist subagents.
9
9
 
10
10
  Task: $ARGUMENTS
11
11
 
12
- > **Tool note**: Use the `subagent` tool. Set `agent` to one of: `architect`, `implementer`, `reviewer`, `debugger`, `verifier`, `git-committer`, `security-auditor`. Use `tasks: [...]` for parallel dispatch and `chain: [...]` for sequential pipelines.
12
+ > **Tool note**: Use the `subagent` tool. Set `agent` to one of: `architect`, `implementer`, `spec-reviewer`, `reviewer`, `debugger`, `verifier`, `git-committer`, `security-auditor`. Use `tasks: [...]` for parallel dispatch and `chain: [...]` for sequential pipelines.
13
13
 
14
14
  ## Atomic Reasoning
15
15
 
@@ -26,12 +26,15 @@ Before delegating, decompose the task into atomic work units:
26
26
  |---|---|
27
27
  | Plan structure before coding | `architect` |
28
28
  | Write or change code | `implementer` |
29
- | Find what's broken | `debugger` |
30
- | Review for correctness / conventions / domain | `reviewer` |
29
+ | Check that a diff covers exactly the spec — no more, no less | `spec-reviewer` |
30
+ | Review code quality (correctness, conventions, domain language) | `reviewer` |
31
+ | Find what's broken (root-cause diagnosis) | `debugger` |
31
32
  | Audit for security issues | `security-auditor` |
32
33
  | Run lint / typecheck / tests | `verifier` |
33
34
  | Create atomic commits | `git-committer` |
34
35
 
36
+ `spec-reviewer` and `reviewer` are distinct on purpose. Spec-reviewer ONLY checks "did the diff implement what the spec asked, no more no less". Reviewer evaluates quality. For any task with a written spec, run spec-reviewer **before** reviewer.
37
+
35
38
  ## Orchestration Modes
36
39
 
37
40
  ### Parallel
@@ -43,15 +46,37 @@ Use the `subagent` tool with `chain: [...]` when later work depends on earlier o
43
46
  ### Fan-out / Fan-in
44
47
  Architect decomposes into N independent plans → dispatch N implementers in parallel → collect all outputs → single verifier run → single reviewer audit. This is the standard pattern for `/execute-phase` work.
45
48
 
49
+ ### Two-Stage Review (spec → quality)
50
+ For any task that has a written spec, follow implementer with **spec-reviewer first, then reviewer**:
51
+
52
+ ```
53
+ implementer → spec-reviewer → reviewer
54
+ ↓ BLOCKED
55
+ re-dispatch implementer with required fixes
56
+ ```
57
+
58
+ Never run quality review on a spec-non-compliant diff. This is the per-task loop inside `/execute-phase`.
59
+
60
+ ## Reading Subagent Status
61
+
62
+ Every draht agent ends its response with one of four status lines. Branch on it:
63
+
64
+ - `STATUS: DONE` — proceed to the next step in the chain.
65
+ - `STATUS: DONE_WITH_CONCERNS` — note the concerns. If correctness-related, address before moving on; otherwise log and continue.
66
+ - `STATUS: NEEDS_CONTEXT` — provide the missing info and re-dispatch the same agent. Do NOT skip ahead with a guess.
67
+ - `STATUS: BLOCKED` — STOP. Report the blocker. Do not retry the same agent on the same input — adjust inputs (more context, decompose further, different agent) or surface to the user.
68
+
46
69
  ## Steps
47
70
  1. Read the task description and identify sub-tasks
48
71
  2. Map each sub-task to the right agent from the table above
49
- 3. Decide parallel vs chain vs fan-out based on dependencies
72
+ 3. Decide parallel vs chain vs fan-out vs two-stage based on dependencies
50
73
  4. Dispatch via the `subagent` tool accordingly
51
- 5. Collect results, handle failures, report the final outcome to the user
74
+ 5. Read each subagent's final `STATUS:` line and branch per the protocol above
75
+ 6. Collect results, handle failures, report the final outcome to the user
52
76
 
53
77
  ## Rules
54
78
  - Prefer parallel dispatch when possible — it's faster and each subagent has its own context
55
79
  - Pass complete context to subagents — they cannot see the main conversation
56
80
  - Do not nest delegations deeply — one level is usually enough
57
- - If a subagent fails, report the failure and suggest next steps rather than retrying blindly
81
+ - Never retry the same agent on the same input after `BLOCKED` — change something
82
+ - For any spec-driven work, spec-reviewer runs before quality reviewer
@@ -13,6 +13,19 @@ Create atomic execution plans for a roadmap phase, using subagents for parallel
13
13
 
14
14
  Phase: $1
15
15
 
16
+ ## Red Flags — STOP
17
+
18
+ A plan is only as good as the tasks inside it. STOP and revise instead of saving if **any** of these is true:
19
+
20
+ - Any task contains placeholder text: `[TBD]`, `[files]`, `[description]`, "appropriate error handling", "similar to Task N", `...` in code positions
21
+ - A task's `<test>` section names no concrete test cases (e.g., "test the function" with no inputs/outputs)
22
+ - A task's `<files>` section lists no concrete file paths
23
+ - A task takes more than ~5 minutes — break it down further
24
+ - The plan introduces new domain terms that are NOT in `.planning/DOMAIN.md` — update DOMAIN.md first
25
+ - A plan touches more than one bounded context without explicit ACL — split per context
26
+
27
+ Run `draht-tools validate-plans $1` after saving. Fix any issues it reports before commit.
28
+
16
29
  ## Atomic Reasoning
17
30
 
18
31
  Before creating plans, decompose this phase goal into atomic reasoning units:
@@ -39,22 +52,42 @@ Before creating plans, decompose this phase goal into atomic reasoning units:
39
52
  e. Break into plan groups of 2-5 tasks each
40
53
  4. Identify which plans are independent (no shared files, no dependency edges)
41
54
  5. **Delegate plan creation to subagents:**
42
- - 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).
55
+ - For independent plans: use the `subagent` tool in **parallel mode** with `architect` agents, one per plan.
43
56
  - For dependent plans: create them sequentially, each via a **single** `subagent` call to `architect`, passing the outputs of predecessor plans as context.
44
57
  - Each subagent task must include:
45
58
  - The phase context summary (paste it — subagents cannot run draht-tools)
46
59
  - The specific observable truths this plan must satisfy
47
60
  - The target files/artifacts
48
61
  - The XML task format specification (below)
49
- - Instruction to output the plan as XML (you will save it via `draht-tools create-plan`)
62
+ - The **delimiter convention** (below) so the orchestrator can split plan content from the `STATUS:` footer
63
+
64
+ ### Architect Output Delimiter Convention
65
+
66
+ The architect agent appends a `STATUS:` footer per the standard agent contract. For `/plan-phase`, we pipe the architect's plan output to `create-plan` as a file — we must NOT include the `STATUS:` line in the saved plan.
50
67
 
51
- 6. Collect all plan outputs from subagents
52
- 7. Save each plan by piping the subagent's output into `draht-tools create-plan`:
68
+ Include this in every architect prompt:
53
69
  ```
54
- echo 'plan content from subagent' | draht-tools create-plan $1 P [title]
70
+ Output your plan as XML, followed by a line containing exactly `---END-PLAN---`, followed by your final `STATUS: ...` line.
71
+
72
+ The orchestrator splits your output on `---END-PLAN---` and saves only the plan content. The STATUS line is read for control flow but not saved.
73
+ ```
74
+
75
+ 6. **Collect and split outputs.** For each architect's output:
76
+ - Split on `---END-PLAN---`
77
+ - Plan content = everything BEFORE the delimiter (trimmed)
78
+ - Status line = everything AFTER (the `STATUS:` line)
79
+ - Branch on status:
80
+ - `DONE` / `DONE_WITH_CONCERNS` → save the plan
81
+ - `NEEDS_CONTEXT` → provide missing info and re-dispatch
82
+ - `BLOCKED` → STOP, report; do not save a partial plan
83
+
84
+ 7. Save each plan by piping the split plan content into `draht-tools create-plan`:
85
+ ```
86
+ printf '%s' "$plan_content" | draht-tools create-plan $1 P [title]
55
87
  ```
56
88
  The content must contain real task details (files, actions, tests) — NOT placeholder brackets. If `create-plan` is called without stdin, it writes a useless template.
57
- 8. Validate: `draht-tools validate-plans $1`
89
+
90
+ 8. Validate: `draht-tools validate-plans $1` — if it exits non-zero, fix the offending plan before commit.
58
91
  9. Commit: `draht-tools commit-docs "create phase $1 plans"`
59
92
 
60
93
  ## Plan Format
@@ -1,5 +1,5 @@
1
1
  ---
2
- description: "Execute a small ad-hoc task with tracking"
2
+ description: "Execute a small ad-hoc task with tracking (implementer + TDD + optional spec-reviewer pass)"
3
3
  ---
4
4
 
5
5
  # /quick
@@ -34,8 +34,10 @@ Before executing, decompose this task into atomic reasoning units:
34
34
  echo 'plan content here' | draht-tools create-quick-plan NNN "$ARGUMENTS"
35
35
  ```
36
36
  The plan content must include: a `# Quick Task NNN: title` heading, a `## Tasks` section with one or more `<task>` XML blocks containing real file paths, real actions, and real verification steps — NOT placeholders like `[files]`.
37
- 3. **Delegate execution to subagent**: Use the `subagent` tool in **single mode** with the `implementer` agent:
38
- "Execute this task: $ARGUMENTS
37
+
38
+ 3. **Stage 1 — Implementer.** Use the `subagent` tool in **single mode** with the `implementer` agent:
39
+ ```
40
+ Execute this task: $ARGUMENTS
39
41
 
40
42
  Follow the TDD cycle:
41
43
  - RED — Write a failing test that describes the desired behaviour
@@ -44,7 +46,35 @@ Before executing, decompose this task into atomic reasoning units:
44
46
  Exception: skip the TDD cycle only for pure config or documentation-only tasks that have no testable behaviour.
45
47
 
46
48
  After completion, report: files changed, tests written, and verification results.
47
- Do NOT run draht, draht-tools, draht help, or pi commands — use only standard tools."
48
49
 
49
- 4. Write summary: `draht-tools write-quick-summary NNN`
50
- 5. Update state: `draht-tools update-state`
50
+ End your response with `STATUS: DONE | DONE_WITH_CONCERNS | NEEDS_CONTEXT | BLOCKED` per the agent contract.
51
+
52
+ Do NOT run draht, draht-tools, draht help, or pi commands — use only standard tools.
53
+ ```
54
+
55
+ Read the final `STATUS:` line:
56
+ - `DONE` → go to Stage 2 (or skip Stage 2 for pure-config / pure-docs).
57
+ - `DONE_WITH_CONCERNS` → log; if correctness, re-dispatch; otherwise continue.
58
+ - `NEEDS_CONTEXT` → provide missing info and re-dispatch.
59
+ - `BLOCKED` → STOP, report.
60
+
61
+ 4. **Stage 2 — Spec-reviewer (skip for pure-config / pure-docs).** Use the `subagent` tool with the `spec-reviewer` agent. Prompt:
62
+ ```
63
+ Review the diff for quick task NNN against `.planning/quick/NNN-*-PLAN.md`. ONLY check spec compliance — does the diff implement exactly what the plan's <test>/<action>/<done> sections asked, no more, no less?
64
+
65
+ End with `STATUS: DONE | DONE_WITH_CONCERNS | NEEDS_CONTEXT | BLOCKED`.
66
+ ```
67
+ - `DONE` → go to Stage 3.
68
+ - `BLOCKED` → re-dispatch implementer with Required Fixes. Repeat until `DONE`.
69
+
70
+ 5. **Stage 3 — Reviewer (optional code-quality pass).** For non-trivial quick tasks (more than one file, or domain code), use the `subagent` tool with the `reviewer` agent. Otherwise skip.
71
+ - `DONE` → task complete.
72
+ - `BLOCKED` → re-dispatch implementer with Must-fix list.
73
+
74
+ 6. Write summary: `draht-tools write-quick-summary NNN`
75
+ 7. Update state: `draht-tools update-state`
76
+
77
+ ## When to skip Stage 3
78
+ - Pure config (tsconfig, biome, formatter)
79
+ - Docs-only edits
80
+ - Single-line obvious changes (typo, version bump)