@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
package/CHANGELOG.md
CHANGED
|
@@ -1,5 +1,22 @@
|
|
|
1
1
|
# Changelog
|
|
2
2
|
|
|
3
|
+
## [2026.5.12] - 2026-05-12
|
|
4
|
+
|
|
5
|
+
### Added
|
|
6
|
+
|
|
7
|
+
- flag plan placeholders and empty sections in validate-plans
|
|
8
|
+
- integrate spec-reviewer, STATUS protocol, and Red Flag gates across commands
|
|
9
|
+
- rewrite /fix as 4-phase systematic debugging protocol
|
|
10
|
+
- add commit-level branding hooks to rebase guard
|
|
11
|
+
|
|
12
|
+
### Changed
|
|
13
|
+
|
|
14
|
+
- ignore local .dev scratch file
|
|
15
|
+
|
|
16
|
+
### Fixed
|
|
17
|
+
|
|
18
|
+
- add missing @sinclair/typebox dependency
|
|
19
|
+
|
|
3
20
|
## [2026.4.25] - 2026-04-25
|
|
4
21
|
|
|
5
22
|
### Added
|
package/bin/draht-tools.cjs
CHANGED
|
@@ -523,6 +523,46 @@ commands["read-plan"] = function (n, p) {
|
|
|
523
523
|
};
|
|
524
524
|
|
|
525
525
|
// --- validate-plans ---
|
|
526
|
+
// Placeholder patterns that indicate a task isn't actually executable.
|
|
527
|
+
// Borrowed from superpowers' writing-plans discipline: tasks with these aren't
|
|
528
|
+
// usable input for an implementer subagent.
|
|
529
|
+
const PLACEHOLDER_PATTERNS = [
|
|
530
|
+
{ pattern: /\[TBD\]/i, label: "[TBD]" },
|
|
531
|
+
{ pattern: /\[files?\]/i, label: "[file] or [files]" },
|
|
532
|
+
{ pattern: /\[description\]/i, label: "[description]" },
|
|
533
|
+
{ pattern: /\[task\s*name\]/i, label: "[task name]" },
|
|
534
|
+
{ pattern: /\bappropriate\s+error\s+handling\b/i, label: '"appropriate error handling"' },
|
|
535
|
+
{ pattern: /\bsimilar\s+to\s+task\s+[NX0-9]+\b/i, label: '"similar to Task N"' },
|
|
536
|
+
{ pattern: /\bsee\s+previous\s+task\b/i, label: '"see previous task"' },
|
|
537
|
+
{ pattern: /\bfill\s+in\s+later\b/i, label: '"fill in later"' },
|
|
538
|
+
{ pattern: /\bfigure\s+(?:this\s+)?out\s+later\b/i, label: '"figure out later"' },
|
|
539
|
+
];
|
|
540
|
+
|
|
541
|
+
function findPlaceholders(content) {
|
|
542
|
+
const hits = [];
|
|
543
|
+
for (const { pattern, label } of PLACEHOLDER_PATTERNS) {
|
|
544
|
+
if (pattern.test(content)) hits.push(label);
|
|
545
|
+
}
|
|
546
|
+
return hits;
|
|
547
|
+
}
|
|
548
|
+
|
|
549
|
+
function findEmptySections(content) {
|
|
550
|
+
// Detect <test>, <action>, <verify>, <done> blocks that are empty or contain only whitespace/placeholders
|
|
551
|
+
const sections = ["test", "action", "verify", "done", "files"];
|
|
552
|
+
const empty = [];
|
|
553
|
+
for (const tag of sections) {
|
|
554
|
+
const re = new RegExp(`<${tag}>([\\s\\S]*?)</${tag}>`, "g");
|
|
555
|
+
let match;
|
|
556
|
+
while ((match = re.exec(content)) !== null) {
|
|
557
|
+
const inner = match[1].trim();
|
|
558
|
+
if (inner.length === 0 || /^\.\.\.$/.test(inner) || /^\[.*\]$/.test(inner)) {
|
|
559
|
+
empty.push(`<${tag}>`);
|
|
560
|
+
}
|
|
561
|
+
}
|
|
562
|
+
}
|
|
563
|
+
return empty;
|
|
564
|
+
}
|
|
565
|
+
|
|
526
566
|
commands["validate-plans"] = function (n) {
|
|
527
567
|
const num = parseInt(n, 10);
|
|
528
568
|
if (!num) { console.error("Usage: draht-tools validate-plans N"); process.exit(1); }
|
|
@@ -547,6 +587,18 @@ commands["validate-plans"] = function (n) {
|
|
|
547
587
|
const taskCount = (content.match(/<task/g) || []).length;
|
|
548
588
|
if (taskCount > 5) issues.push(`${file}: ${taskCount} tasks (max recommended: 5)`);
|
|
549
589
|
if (taskCount === 0) issues.push(`${file}: No tasks defined`);
|
|
590
|
+
|
|
591
|
+
// Placeholder linter — flag tasks that aren't actually executable
|
|
592
|
+
const placeholders = findPlaceholders(content);
|
|
593
|
+
if (placeholders.length > 0) {
|
|
594
|
+
issues.push(`${file}: contains placeholder text → ${placeholders.join(", ")} (tasks must be concrete to dispatch to subagents)`);
|
|
595
|
+
}
|
|
596
|
+
|
|
597
|
+
// Empty section linter — <test>, <action>, <verify>, <done>, <files> must have real content
|
|
598
|
+
const emptySections = findEmptySections(content);
|
|
599
|
+
if (emptySections.length > 0) {
|
|
600
|
+
issues.push(`${file}: empty or placeholder-only sections → ${emptySections.join(", ")}`);
|
|
601
|
+
}
|
|
550
602
|
}
|
|
551
603
|
|
|
552
604
|
console.log(banner(`VALIDATE PHASE ${num}`));
|
|
@@ -556,6 +608,7 @@ commands["validate-plans"] = function (n) {
|
|
|
556
608
|
} else {
|
|
557
609
|
console.log(`\n⚠️ ${issues.length} issue(s):`);
|
|
558
610
|
for (const issue of issues) console.log(` - ${issue}`);
|
|
611
|
+
process.exit(1);
|
|
559
612
|
}
|
|
560
613
|
};
|
|
561
614
|
|
|
@@ -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
|
|
|
@@ -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)
|
|
@@ -1,5 +1,5 @@
|
|
|
1
1
|
---
|
|
2
|
-
description: "Code review and security audit of recent changes"
|
|
2
|
+
description: "Code review and security audit of recent changes (parallel reviewer + security-auditor + optional spec-reviewer)"
|
|
3
3
|
---
|
|
4
4
|
|
|
5
5
|
# /review
|
|
@@ -25,7 +25,7 @@ Before reviewing, decompose code changes into atomic reasoning units:
|
|
|
25
25
|
3. **Verify correctness** — Is this change correct? Type-safe? Secure? Does it follow conventions? What could go wrong?
|
|
26
26
|
|
|
27
27
|
**Synthesize review strategy:**
|
|
28
|
-
- Group changes by concern (correctness, security, style)
|
|
28
|
+
- Group changes by concern (correctness, security, style, spec compliance)
|
|
29
29
|
- Prioritize findings (critical, important, minor)
|
|
30
30
|
- Identify patterns across multiple files
|
|
31
31
|
- Check domain language compliance and bounded context boundaries
|
|
@@ -35,13 +35,30 @@ Before reviewing, decompose code changes into atomic reasoning units:
|
|
|
35
35
|
- If argument given: use those files/directories/description as scope
|
|
36
36
|
- If no argument: run `git diff --stat` and `git diff --cached --stat` to find changes
|
|
37
37
|
2. Determine the list of changed files and produce a scope summary
|
|
38
|
-
3. **
|
|
38
|
+
3. **Detect spec context.** Look for a relevant plan:
|
|
39
|
+
- If `$ARGUMENTS` mentions a phase/task/plan number → load that PLAN.md
|
|
40
|
+
- If `.planning/STATE.md` references an in-progress phase → check its plans for tasks matching the diff
|
|
41
|
+
- If no plan applies → spec-reviewer is skipped
|
|
42
|
+
4. **Delegate to subagents in parallel:**
|
|
39
43
|
Use the `subagent` tool in **parallel mode** with these tasks:
|
|
40
|
-
- `reviewer` agent: "Review the following code changes for correctness, type safety, conventions, and potential issues. Scope: <scope summary and file list>. Read each changed file
|
|
41
|
-
- `security-auditor` agent: "Audit the following code changes for security vulnerabilities. Scope: <scope summary and file list>.
|
|
42
|
-
|
|
43
|
-
|
|
44
|
-
5.
|
|
45
|
-
|
|
46
|
-
|
|
47
|
-
- **
|
|
44
|
+
- `reviewer` agent: "Review the following code changes for correctness, type safety, conventions, and potential issues. Scope: <scope summary and file list>. Read each changed file. For each finding: cite the exact file and line, explain the issue, suggest the fix. Prioritize: Critical / Important / Minor. End with `STATUS: DONE | DONE_WITH_CONCERNS | NEEDS_CONTEXT | BLOCKED`. Do NOT run draht, draht-tools, or pi commands."
|
|
45
|
+
- `security-auditor` agent: "Audit the following code changes for security vulnerabilities. Scope: <scope summary and file list>. Check injection, auth bypass, secrets, unsafe deserialization, path traversal, prototype pollution. Report severity / file / line / fix. End with `STATUS: ...`. Do NOT run draht, draht-tools, or pi commands."
|
|
46
|
+
- **(If spec context exists)** `spec-reviewer` agent: "Review the diff against plan at <plan file path>. ONLY spec compliance — does the diff implement exactly what the <test>/<action>/<done> sections asked? Flag omissions and over-builds. End with `STATUS: ...`."
|
|
47
|
+
|
|
48
|
+
5. Read each subagent's final `STATUS:` line.
|
|
49
|
+
6. Collect and merge results.
|
|
50
|
+
7. Produce a unified, prioritized findings report:
|
|
51
|
+
- **Critical** — must fix before merge (security `BLOCKED`, spec gaps for required deliverables, correctness issues that cause data loss / crashes)
|
|
52
|
+
- **Important** — should fix (bugs, type issues, spec over-builds, missing error handling)
|
|
53
|
+
- **Minor** — style, naming, optional improvements
|
|
54
|
+
|
|
55
|
+
## Reading STATUS
|
|
56
|
+
- Any `STATUS: BLOCKED` → its findings escalate to Critical in the merged report
|
|
57
|
+
- `STATUS: NEEDS_CONTEXT` → provide missing info and re-dispatch that one agent
|
|
58
|
+
- `STATUS: DONE` / `DONE_WITH_CONCERNS` are normal terminal states
|
|
59
|
+
|
|
60
|
+
## Rules
|
|
61
|
+
- Cite file paths and line numbers precisely
|
|
62
|
+
- Do not restate the diff — focus on findings
|
|
63
|
+
- If no issues found, state that explicitly
|
|
64
|
+
- spec-reviewer only runs when a spec exists — ad-hoc reviews skip it
|