@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.
- package/CHANGELOG.md +17 -0
- package/bin/draht-tools.cjs +53 -0
- package/dist/prompts/commands/atomic-commit.md +12 -0
- package/dist/prompts/commands/execute-phase.md +48 -17
- package/dist/prompts/commands/fix.md +86 -23
- package/dist/prompts/commands/map-codebase.md +3 -3
- package/dist/prompts/commands/orchestrate.md +31 -6
- package/dist/prompts/commands/plan-phase.md +39 -6
- package/dist/prompts/commands/quick.md +36 -6
- package/dist/prompts/commands/review.md +28 -11
- package/dist/prompts/commands/verify-work.md +34 -17
- package/package.json +6 -5
- package/prompts/commands/atomic-commit.md +12 -0
- package/prompts/commands/execute-phase.md +48 -17
- package/prompts/commands/fix.md +86 -23
- package/prompts/commands/map-codebase.md +3 -3
- package/prompts/commands/orchestrate.md +31 -6
- package/prompts/commands/plan-phase.md +39 -6
- package/prompts/commands/quick.md +36 -6
- package/prompts/commands/review.md +28 -11
- package/prompts/commands/verify-work.md +34 -17
|
@@ -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
|
|
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.
|
|
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
|
|
37
|
-
- `reviewer` agent: "Review the recent code changes
|
|
38
|
-
|
|
39
|
-
|
|
40
|
-
4.
|
|
41
|
-
|
|
42
|
-
|
|
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
|
-
|
|
45
|
-
|
|
46
|
-
|
|
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
|
-
|
|
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.
|
|
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.
|
|
50
|
-
"@draht/ai": "2026.
|
|
51
|
-
"@draht/tui": "2026.
|
|
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": "
|
|
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.
|
|
34
|
-
3.
|
|
35
|
-
|
|
36
|
-
|
|
37
|
-
|
|
38
|
-
|
|
39
|
-
|
|
40
|
-
|
|
41
|
-
|
|
42
|
-
|
|
43
|
-
|
|
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 "
|
|
59
|
-
2. GREEN — Write minimal implementation from <action> to make tests pass. Run tests, confirm PASS. Commit with: git add <files> && git commit -m "
|
|
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
|
-
-
|
|
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
|
|
package/prompts/commands/fix.md
CHANGED
|
@@ -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
|
|
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
|
-
##
|
|
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
|
-
|
|
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
|
-
|
|
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
|
-
|
|
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
|
-
|
|
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
|
-
|
|
38
|
-
|
|
39
|
-
|
|
40
|
-
|
|
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
|
-
|
|
43
|
-
|
|
44
|
-
|
|
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
|
|
50
|
-
- One bug, one fix, one commit
|
|
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
|
|
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
|
-
|
|
|
30
|
-
| Review
|
|
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.
|
|
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
|
-
-
|
|
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.
|
|
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
|
-
-
|
|
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
|
-
|
|
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
|
-
|
|
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
|
-
|
|
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
|
-
|
|
38
|
-
|
|
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
|
-
|
|
50
|
-
|
|
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)
|