draht-claude 2026.4.23

package/cli.mjs

@@ -0,0 +1,348 @@
+#!/usr/bin/env node
+/**
+ * draht-claude CLI — installs this package as a Claude Code plugin via a local marketplace.
+ *
+ * Architecture:
+ *   1. Copy plugin files into a local marketplace at ~/.draht/claude-marketplace/
+ *   2. Write marketplace.json listing draht-claude as an available plugin
+ *   3. Shell out to `claude plugin marketplace add` and `claude plugin install`
+ *   4. Claude Code tracks the plugin in its own registries and enables it
+ *
+ * The install is reversible via `draht-claude uninstall`.
+ *
+ * Usage:
+ *   npx draht-claude install [--path <dir>] [--force]
+ *   npx draht-claude uninstall [--path <dir>]
+ *   npx draht-claude update [--path <dir>]
+ *   npx draht-claude status [--path <dir>]
+ *   npx draht-claude --help
+ */
+
+import { execSync, spawnSync } from "node:child_process";
+import * as fs from "node:fs";
+import * as os from "node:os";
+import * as path from "node:path";
+import { fileURLToPath } from "node:url";
+
+const __dirname = path.dirname(fileURLToPath(import.meta.url));
+const PACKAGE_ROOT = __dirname;
+
+// Marketplace and plugin names
+const MARKETPLACE_NAME = "draht";
+const PLUGIN_NAME = "draht";
+
+// Default location for the local marketplace we generate
+const DEFAULT_MARKETPLACE_DIR = path.join(os.homedir(), ".draht", "claude-marketplace");
+
+// Files in the npm package that must NOT be copied into the plugin tree
+const IGNORE = new Set([
+	"node_modules",
+	"package.json",
+	"cli.mjs",
+	".npmignore",
+	".DS_Store",
+	"CHANGELOG.md",
+]);
+
+// ─── args ───────────────────────────────────────────────────────────────────
+
+function parseArgs(argv) {
+	const args = argv.slice(2);
+	const command = args[0];
+	const flags = { path: null, force: false, help: false };
+	for (let i = 1; i < args.length; i++) {
+		const a = args[i];
+		if (a === "--path" || a === "-p") {
+			flags.path = args[++i];
+		} else if (a === "--force" || a === "-f") {
+			flags.force = true;
+		} else if (a === "--help" || a === "-h") {
+			flags.help = true;
+		}
+	}
+	if (!command || command === "--help" || command === "-h") flags.help = true;
+	return { command, flags };
+}
+
+function printHelp() {
+	console.log(`draht-claude — install the draht Claude Code plugin
+
+Usage:
+  npx draht-claude install            Install as a Claude Code plugin
+  npx draht-claude install --force    Reinstall even if already present
+  npx draht-claude install --path DIR Custom marketplace directory
+  npx draht-claude uninstall          Remove the plugin and marketplace
+  npx draht-claude update             Reinstall (same as install --force)
+  npx draht-claude status             Show install + enabled state
+
+Options:
+  -p, --path <dir>   Custom local marketplace directory
+  -f, --force        Overwrite existing install
+  -h, --help         Show this help
+
+What this installs:
+  • Local Claude Code marketplace named "${MARKETPLACE_NAME}" at ~/.draht/claude-marketplace/
+  • Plugin "${PLUGIN_NAME}" inside that marketplace, registered and enabled
+  • 16 slash commands (/new-project, /plan-phase, /execute-phase, /orchestrate, ...)
+  • 7 specialist subagents (architect, implementer, reviewer, debugger, ...)
+  • 3 workflow skills (gsd-workflow, tdd-workflow, ddd-workflow)
+  • Workflow hook scripts (pre-execute, post-task, post-phase, quality-gate)
+  • Claude Code lifecycle hooks (SessionStart, UserPromptSubmit)
+  • Self-contained draht-tools CLI
+
+After install, restart Claude Code. Commands appear in the slash command picker.
+
+Docs: https://draht.dev
+`);
+}
+
+// ─── helpers ────────────────────────────────────────────────────────────────
+
+function log(msg) {
+	console.log(msg);
+}
+
+function err(msg) {
+	console.error(`error: ${msg}`);
+}
+
+function readPluginManifest() {
+	const manifestPath = path.join(PACKAGE_ROOT, ".claude-plugin", "plugin.json");
+	if (!fs.existsSync(manifestPath)) {
+		err(`Plugin manifest not found at ${manifestPath}`);
+		err("This usually means the package was installed incorrectly. Reinstall via 'npx draht-claude@latest install'.");
+		process.exit(1);
+	}
+	return JSON.parse(fs.readFileSync(manifestPath, "utf-8"));
+}
+
+function copyRecursive(src, dest) {
+	const stat = fs.statSync(src);
+	if (stat.isDirectory()) {
+		fs.mkdirSync(dest, { recursive: true });
+		for (const entry of fs.readdirSync(src)) {
+			if (IGNORE.has(entry)) continue;
+			copyRecursive(path.join(src, entry), path.join(dest, entry));
+		}
+	} else {
+		fs.copyFileSync(src, dest);
+		// Preserve executable bit on bin/ and scripts/
+		const parentDir = path.basename(path.dirname(src));
+		if ((parentDir === "bin" || parentDir === "scripts") && (stat.mode & 0o111) !== 0) {
+			fs.chmodSync(dest, 0o755);
+		}
+	}
+}
+
+function removeRecursive(target) {
+	if (!fs.existsSync(target)) return;
+	fs.rmSync(target, { recursive: true, force: true });
+}
+
+function hasClaudeCli() {
+	const which = spawnSync(process.platform === "win32" ? "where" : "which", ["claude"], { encoding: "utf-8" });
+	return which.status === 0 && which.stdout.trim().length > 0;
+}
+
+function runClaude(args, { allowFail = false } = {}) {
+	log(`  $ claude ${args.join(" ")}`);
+	const res = spawnSync("claude", args, { stdio: "inherit" });
+	if (res.status !== 0 && !allowFail) {
+		err(`claude ${args[0]} ${args[1] || ""} failed with exit code ${res.status}`);
+		process.exit(1);
+	}
+	return res.status === 0;
+}
+
+function writeMarketplaceManifest(marketplaceDir, pluginManifest) {
+	const manifest = {
+		$schema: "https://anthropic.com/claude-code/marketplace.schema.json",
+		name: MARKETPLACE_NAME,
+		description: "Local marketplace for draht-claude. Managed by the draht-claude CLI.",
+		owner: {
+			name: pluginManifest.author?.name || "draht",
+			url: pluginManifest.homepage || "https://draht.dev",
+		},
+		plugins: [
+			{
+				name: PLUGIN_NAME,
+				description: pluginManifest.description || "Draht GSD, multi-agent, TDD and DDD workflows as a Claude Code plugin",
+				source: `./plugins/${PLUGIN_NAME}`,
+				category: "workflow",
+				homepage: pluginManifest.homepage || "https://draht.dev",
+			},
+		],
+	};
+	const manifestDir = path.join(marketplaceDir, ".claude-plugin");
+	fs.mkdirSync(manifestDir, { recursive: true });
+	fs.writeFileSync(path.join(manifestDir, "marketplace.json"), `${JSON.stringify(manifest, null, 2)}\n`);
+}
+
+// ─── commands ───────────────────────────────────────────────────────────────
+
+function cmdInstall(flags) {
+	const marketplaceDir = flags.path || DEFAULT_MARKETPLACE_DIR;
+	const pluginDir = path.join(marketplaceDir, "plugins", PLUGIN_NAME);
+	const manifest = readPluginManifest();
+
+	log("draht-claude installer");
+	log(`  plugin:      ${manifest.name} v${manifest.version}`);
+	log(`  source:      ${PACKAGE_ROOT}`);
+	log(`  marketplace: ${marketplaceDir}`);
+	log(`  plugin dir:  ${pluginDir}`);
+	log("");
+
+	// Check prerequisites
+	if (!hasClaudeCli()) {
+		err("claude CLI not found in PATH");
+		err("Install Claude Code first: https://claude.com/claude-code");
+		process.exit(1);
+	}
+
+	// Bail early if already installed and not forcing
+	if (fs.existsSync(pluginDir) && !flags.force) {
+		err(`plugin already installed at ${pluginDir}`);
+		err("use --force to reinstall, or 'draht-claude update' to refresh");
+		process.exit(1);
+	}
+
+	// Copy plugin files into marketplace dir
+	log("Copying plugin files...");
+	if (flags.force && fs.existsSync(pluginDir)) {
+		removeRecursive(pluginDir);
+	}
+	fs.mkdirSync(pluginDir, { recursive: true });
+	copyRecursive(PACKAGE_ROOT, pluginDir);
+
+	// Write marketplace manifest
+	log("Writing marketplace.json...");
+	writeMarketplaceManifest(marketplaceDir, manifest);
+
+	// Validate marketplace + plugin before registering
+	log("Validating manifest...");
+	runClaude(["plugin", "validate", pluginDir], { allowFail: true });
+
+	// Add marketplace to Claude Code (idempotent — will error if already added, so allow fail)
+	log("Registering marketplace with Claude Code...");
+	runClaude(["plugin", "marketplace", "add", marketplaceDir], { allowFail: true });
+
+	// Update marketplace so Claude Code picks up any changes to our plugin files on reinstall
+	runClaude(["plugin", "marketplace", "update", MARKETPLACE_NAME], { allowFail: true });
+
+	// Install the plugin
+	log("Installing plugin...");
+	const pluginSpec = `${PLUGIN_NAME}@${MARKETPLACE_NAME}`;
+	runClaude(["plugin", "install", pluginSpec, "--scope", "user"]);
+
+	// Enable explicitly — install usually enables automatically, but be safe
+	runClaude(["plugin", "enable", pluginSpec], { allowFail: true });
+
+	log("");
+	log(`✓ installed ${PLUGIN_NAME}@${MARKETPLACE_NAME} v${manifest.version}`);
+	log("");
+	log("Next steps:");
+	log("  1. Restart Claude Code so it picks up the plugin");
+	log("  2. Check that commands appear: run `claude plugin list`");
+	log("  3. Try /new-project or /orchestrate inside Claude Code");
+	log("");
+	log("Docs: https://draht.dev");
+}
+
+function cmdUninstall(flags) {
+	const marketplaceDir = flags.path || DEFAULT_MARKETPLACE_DIR;
+	const pluginDir = path.join(marketplaceDir, "plugins", PLUGIN_NAME);
+	const pluginSpec = `${PLUGIN_NAME}@${MARKETPLACE_NAME}`;
+
+	log("draht-claude uninstaller");
+	log(`  marketplace: ${marketplaceDir}`);
+	log(`  plugin:      ${pluginSpec}`);
+	log("");
+
+	// Try to uninstall via claude CLI first (removes from settings.json + registries)
+	if (hasClaudeCli()) {
+		log("Disabling plugin in Claude Code...");
+		runClaude(["plugin", "disable", pluginSpec], { allowFail: true });
+		log("Uninstalling plugin...");
+		runClaude(["plugin", "uninstall", pluginSpec], { allowFail: true });
+		log("Removing marketplace...");
+		runClaude(["plugin", "marketplace", "remove", MARKETPLACE_NAME], { allowFail: true });
+	} else {
+		log("(claude CLI not found — skipping registry cleanup)");
+	}
+
+	// Remove local marketplace files
+	if (fs.existsSync(marketplaceDir)) {
+		log(`Removing ${marketplaceDir}...`);
+		removeRecursive(marketplaceDir);
+	}
+
+	log("");
+	log("✓ uninstalled");
+}
+
+function cmdUpdate(flags) {
+	cmdInstall({ ...flags, force: true });
+}
+
+function cmdStatus(flags) {
+	const marketplaceDir = flags.path || DEFAULT_MARKETPLACE_DIR;
+	const pluginDir = path.join(marketplaceDir, "plugins", PLUGIN_NAME);
+	const pluginManifestPath = path.join(pluginDir, ".claude-plugin", "plugin.json");
+
+	log(`marketplace dir: ${marketplaceDir}`);
+
+	if (!fs.existsSync(pluginManifestPath)) {
+		log("status:          not installed");
+		return;
+	}
+	try {
+		const manifest = JSON.parse(fs.readFileSync(pluginManifestPath, "utf-8"));
+		log("status:          files present");
+		log(`plugin:          ${manifest.name} v${manifest.version}`);
+		log(`description:     ${manifest.description || "(none)"}`);
+	} catch (e) {
+		log(`status:          files present (manifest unreadable: ${e.message})`);
+	}
+
+	// Show claude's view if available
+	if (hasClaudeCli()) {
+		log("");
+		log("Claude Code plugin list:");
+		try {
+			const out = execSync("claude plugin list", { encoding: "utf-8" });
+			process.stdout.write(out);
+		} catch {
+			log("  (failed to run `claude plugin list`)");
+		}
+	}
+}
+
+// ─── main ───────────────────────────────────────────────────────────────────
+
+const { command, flags } = parseArgs(process.argv);
+
+if (flags.help) {
+	printHelp();
+	process.exit(0);
+}
+
+switch (command) {
+	case "install":
+		cmdInstall(flags);
+		break;
+	case "uninstall":
+	case "remove":
+		cmdUninstall(flags);
+		break;
+	case "update":
+	case "upgrade":
+		cmdUpdate(flags);
+		break;
+	case "status":
+		cmdStatus(flags);
+		break;
+	default:
+		err(`unknown command: ${command}`);
+		err("run 'draht-claude --help' for usage");
+		process.exit(1);
+}

package/commands/atomic-commit.md

@@ -0,0 +1,61 @@
+---
+description: Analyze uncommitted changes and create atomic conventional commits (one logical change per commit)
+allowed-tools: Bash, Read, Task
+---
+
+# /atomic-commit
+
+Analyze changes and create atomic commits.
+
+## Atomic Reasoning
+
+Before creating commits, decompose changes into atomic reasoning units:
+
+**For each file change:**
+1. **State the logical component** — What does this change do? What is its purpose? Does it complete a thought?
+2. **Validate independence** — Can this change be applied independently? Does it depend on other changes? Does it break the build alone?
+3. **Verify correctness** — Is this change logically complete? Does it mix concerns? Should it be split further?
+
+**Synthesize commit strategy:**
+- Group changes by logical concern (one commit = one idea)
+- Order commits so each builds successfully
+- Write clear commit messages that explain WHY, not just WHAT
+- Ensure each commit is self-contained and reviewable
+
+## Gathering Current State
+
+First, gather the current state:
+
+1. Run `git status` to see what changed
+2. Run `git diff` to see unstaged changes
+3. Run `git diff --cached` to see staged changes
+
+## Strategy
+
+Based on the changes, analyze and group them into logical, ATOMIC commits. Each commit should:
+
+1. Contain ONE logical change only
+2. Be self-contained and complete
+3. Not break the build if applied independently
+
+You may delegate this work to the `git-committer` subagent via the **Task tool** with `subagent_type: "git-committer"` if the change set is large or spans multiple areas. The git-committer will review diffs, group changes, and create commits with conventional commit messages.
+
+For each group of changes you identify:
+- List the specific files that belong together
+- Generate a clear, descriptive commit message following conventional commits format
+- Explain WHY these changes belong in one commit
+
+Then execute the `git add <specific-files>` and `git commit` commands for each atomic commit in the order they should be applied.
+
+Format each commit message as:
+```
+type(scope): brief description
+```
+
+Common types: feat, fix, refactor, docs, test, chore, style, perf. For strict TDD cycles, also use `red:`, `green:`, `refactor:`.
+
+## Rules
+- NEVER use `git add -A` or `git add .` — always stage specific files
+- NEVER use `git commit --no-verify`
+- NEVER force push
+- Review diffs before committing to ensure nothing unexpected is staged

package/commands/discuss-phase.md

@@ -0,0 +1,54 @@
+---
+description: Capture implementation decisions before planning a phase
+argument-hint: "<phase-number>"
+allowed-tools: Bash, Read, Write, Edit
+---
+
+# /discuss-phase
+
+Capture implementation decisions before planning a phase.
+
+Phase: $1
+
+> **Tool note**: Invoke `draht-tools <subcommand>` as `node "${CLAUDE_PLUGIN_ROOT}/bin/draht-tools.cjs" <subcommand>` via the Bash tool.
+
+## Atomic Reasoning
+
+Before questioning, decompose this phase scope into atomic reasoning units:
+
+**For each implementation decision:**
+1. **State the logical component** — What gray area exists? What choice needs to be made? Why does this matter?
+2. **Validate independence** — Can this decision be made independently, or does it depend on other choices? What downstream impacts does it have?
+3. **Verify correctness** — What criteria determine the right answer? What trade-offs exist? What domain terms need clarification?
+
+**Synthesize discussion strategy:**
+- Identify critical decisions that block planning
+- Group related decisions (e.g., all API decisions together)
+- Sequence questions from foundational to detailed
+- Ensure domain language is established first
+
+## Steps
+1. Run `draht-tools phase-info $1` to load phase context
+2. Identify gray areas based on what's being built
+3. Present 1-2 questions at a time about preferences
+4. If `.planning/DOMAIN.md` exists, load it and validate discovered terms against the glossary. Add any new domain terms found during discussion.
+5. Record decisions with `draht-tools save-context $1`
+6. Commit: `draht-tools commit-docs "capture phase $1 context"`
+
+## Workflow
+This is one step in the per-phase cycle. Use fresh sessions (`/clear`) between steps:
+
+```
+/discuss-phase N → /plan-phase N → /execute-phase N → /verify-work N → /discuss-phase N+1 → ...
+```
+
+After completing this command, tell the user to start a fresh session and run `/plan-phase $1`. Do NOT suggest `/next-milestone` — that is only after ALL phases in the milestone are verified.
+
+## Gray Area Categories
+- **Visual features** → Layout, density, interactions, empty states
+- **APIs/CLIs** → Response format, error handling, auth
+- **Data models** → Schema, relationships, validation
+- **Content** → Structure, tone, depth, flow
+- **Refactoring** → Grouping, naming, migration strategy
+- **Testability** → What needs testing, test framework preference, coverage goals, integration vs unit boundaries
+- **Domain boundaries** → What are the bounded contexts in play? Are there existing domain terms to respect? What aggregates/entities are involved?

package/commands/execute-phase.md

@@ -0,0 +1,111 @@
+---
+description: Execute all plans in a phase with atomic commits (parallel implementer subagents + TDD cycle)
+argument-hint: "<phase-number> [--gaps-only]"
+allowed-tools: Bash, Read, Write, Edit, Task
+---
+
+# /execute-phase
+
+Execute all plans in a phase with atomic commits, parallelizing independent plans via subagents.
+
+Phase: $1
+Arguments: $ARGUMENTS
+
+> **Tool note**: Invoke `draht-tools <subcommand>` as `node "${CLAUDE_PLUGIN_ROOT}/bin/draht-tools.cjs" <subcommand>`. For subagent delegation, use the **Task tool** with `subagent_type: "implementer"`. Dispatch multiple parallel tasks in a single assistant turn by making multiple Task tool calls at once.
+
+## Atomic Reasoning
+
+Before executing, decompose this phase execution into atomic reasoning units:
+
+**For each plan in the phase:**
+1. **State the logical component** — What is this plan's singular purpose? What observable outcome does it produce?
+2. **Validate independence** — Can this plan execute in parallel with others, or does it depend on their outputs? Which files does it touch?
+3. **Verify correctness** — What tests will prove this plan works? What failure modes exist?
+
+**Synthesize execution strategy:**
+- Identify parallel execution groups (plans with no shared files/dependencies)
+- Order dependent plans (plan B depends on plan A's outputs)
+- Map each plan to a subagent task with clear success criteria
+
+## Steps
+0. Run the pre-execute check:
+   ```bash
+   node "${CLAUDE_PLUGIN_ROOT}/scripts/gsd-pre-execute.cjs" $1
+   ```
+   If it exits non-zero, STOP and report errors to the user. Do not proceed.
+
+1. Run `draht-tools discover-plans $1` to find and order plans
+2. Read each plan file yourself (from `.planning/phases/`) and analyze dependencies to identify which plans can run in parallel vs sequential
+
+3. **Delegate execution to subagents via the Task tool:**
+   - For **independent plans** (no shared files, no dependency chain): dispatch multiple `Task` tool calls in parallel (single assistant turn), each with `subagent_type: "implementer"`, one per plan.
+   - For **dependent plans**: dispatch sequentially — one `Task` call at a time, waiting for the previous to complete before starting the next.
+   - Each implementer prompt must include:
+     - The full plan content (paste it inline — the subagent cannot run draht-tools)
+     - The TDD cycle instructions (see template below)
+     - Instructions to commit with `git add <files> && git commit -m "description"`
+
+4. After all subagents complete, collect results and check for failures
+5. For each completed task, run the post-task hook (record results + type check + test run):
+   ```bash
+   node "${CLAUDE_PLUGIN_ROOT}/scripts/gsd-post-task.cjs" <phase> <plan> <task-num> <status> <commit-hash>
+   ```
+6. Run `draht-tools verify-phase $1` yourself (not the subagent)
+7. Run the post-phase hook to generate the phase report:
+   ```bash
+   node "${CLAUDE_PLUGIN_ROOT}/scripts/gsd-post-phase.cjs" $1
+   ```
+8. Run `draht-tools update-state` yourself
+9. Final commit: `draht-tools commit-docs "complete phase $1 execution"`
+10. Tell the user to start a fresh session (`/clear`) and run `/verify-work $1`
+
+## Subagent Task Template
+
+Each implementer Task call receives a prompt like:
+
+```
+Execute this plan. Here is the full plan content:
+
+<paste full plan XML here>
+
+For each <task> in the plan, follow this TDD cycle:
+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>"
+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>"
+3. REFACTOR — Apply <refactor> improvements if any. Tests must stay green after each change. Commit with: git add <files> && git commit -m "refactor: <description>"
+4. VERIFY — Run the <verify> step, confirm <done> criteria are met.
+
+Domain rules: Use ubiquitous language from .planning/DOMAIN.md (read it). Do not import across bounded context boundaries.
+
+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.
+```
+
+## Parallelization Rules
+- Plans sharing no files and having no dependency edges can run in parallel
+- If plan B depends on output of plan A, plan B must wait for A to complete
+- If a parallel subagent fails, report which plan failed and continue with independent plans
+
+## TDD Rules
+- Never write implementation before a failing test exists
+- If a test passes immediately after being written, it is not testing the right thing — fix it
+- Red → Green → Refactor is not optional; skipping steps invalidates the safety net
+- Each TDD phase gets its own commit so the history is auditable
+
+## Domain Rules
+- All identifiers (class names, method names, variables) must use the ubiquitous language from `.planning/DOMAIN.md`
+- Do not import across bounded context boundaries directly — use domain events or ACL adapters
+- If implementation reveals a missing domain term, stop and update DOMAIN.md before continuing
+
+## Workflow
+This is one step in the per-phase cycle:
+
+```
+/discuss-phase N → /plan-phase N → /execute-phase N → /verify-work N
+```
+
+After completing this command, tell the user to start a fresh session (`/clear`) and run `/verify-work $1`. Do NOT suggest `/next-milestone`.
+
+## Flags
+- `--gaps-only` → only execute FIX-PLAN.md files from failed verification

package/commands/fix.md

@@ -0,0 +1,50 @@
+---
+description: Diagnose and fix a bug with TDD discipline (debugger subagent → reproducing test → minimal fix)
+argument-hint: "<description of what's broken>"
+allowed-tools: Bash, Read, Write, Edit, Task
+---
+
+# /fix
+
+Diagnose and fix a specific bug or failing task with TDD discipline, using a subagent for diagnosis.
+
+Issue: $ARGUMENTS
+
+> **Tool note**: Invoke `draht-tools <subcommand>` as `node "${CLAUDE_PLUGIN_ROOT}/bin/draht-tools.cjs" <subcommand>`. For subagents, use the **Task tool** with `subagent_type: "debugger"` or `"implementer"`.
+
+## Atomic Reasoning
+
+Before diagnosing, decompose this bug into atomic reasoning units:
+
+1. **State the logical component** — What is the observed failure? What should happen vs what actually happens?
+2. **Validate independence** — Which components/files are involved? Can we isolate the failure? Are there related bugs that should be fixed separately?
+3. **Verify correctness** — What test will reproduce this bug reliably? What would prove it's fixed? What regressions could the fix introduce?
+
+**Synthesize fix strategy:**
+- Trace the failure to root cause
+- Write a minimal reproducing test
+- Identify the smallest change that makes the test pass
+- Plan regression checks
+
+## Steps
+1. **Diagnose via Task tool** with `subagent_type: "debugger"` and prompt:
+   "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."
+
+2. **Write a reproducing test**: Based on the diagnosis, write a test that demonstrates the bug (it must fail)
+   - Commit: `git add <test-files> && git commit -m "red: reproduce <bug description>"`
+
+3. **Minimal fix**: Write the smallest change that makes the test pass
+   - Do not refactor or add features — just fix the bug
+   - Run the full test suite to check for regressions
+   - Commit: `git add <files> && git commit -m "green: fix <bug description>"`
+
+4. **Refactor** (if needed): Clean up without changing behavior
+   - Tests must stay green after every change
+   - Commit: `git add <files> && git commit -m "refactor: <description>"`
+
+5. **Update state**: `draht-tools update-state`
+
+## Rules
+- Always reproduce before fixing — a fix without a test is a guess
+- One bug, one fix, one commit series. Do not bundle unrelated changes.
+- If the root cause spans multiple files, explain the chain in the commit message body