draht-claude 2026.4.23

package/scripts/gsd-quality-gate.cjs

@@ -0,0 +1,252 @@
+#!/usr/bin/env node
+"use strict";
+
+/**
+ * Draht Quality Gate Hook
+ * Runs after task completion to enforce quality standards.
+ * Called by the build agent after each verify step.
+ *
+ * Usage: node gsd-quality-gate.js [--strict]
+ * Exit 0 = quality OK, Exit 1 = quality issues
+ */
+
+const { execSync } = require("node:child_process");
+const fs = require("node:fs");
+const path = require("node:path");
+
+// ── Toolchain detection — mirrors src/gsd/hook-utils.ts ──────────────────────
+function detectToolchain(cwd) {
+	if (fs.existsSync(path.join(cwd, "bun.lockb")) || fs.existsSync(path.join(cwd, "bun.lock"))) {
+		return { pm: "bun", testCmd: "bun test", coverageCmd: "bun test --coverage", lintCmd: "bunx biome check ." };
+	}
+	if (fs.existsSync(path.join(cwd, "pnpm-lock.yaml"))) {
+		return { pm: "pnpm", testCmd: "pnpm test", coverageCmd: "pnpm run test:coverage", lintCmd: "pnpm run lint" };
+	}
+	if (fs.existsSync(path.join(cwd, "yarn.lock"))) {
+		return { pm: "yarn", testCmd: "yarn test", coverageCmd: "yarn run test:coverage", lintCmd: "yarn run lint" };
+	}
+	return { pm: "npm", testCmd: "npm test", coverageCmd: "npm run test:coverage", lintCmd: "npm run lint" };
+}
+
+function readHookConfig(cwd) {
+	const defaults = { coverageThreshold: 80, tddMode: "advisory", qualityGateStrict: false };
+	const configPath = path.join(cwd, ".planning", "config.json");
+	if (!fs.existsSync(configPath)) return defaults;
+	try {
+		const raw = JSON.parse(fs.readFileSync(configPath, "utf-8"));
+		const h = raw.hooks || {};
+		return {
+			coverageThreshold: typeof h.coverageThreshold === "number" ? h.coverageThreshold : defaults.coverageThreshold,
+			tddMode: h.tddMode === "strict" || h.tddMode === "advisory" ? h.tddMode : defaults.tddMode,
+			qualityGateStrict: typeof h.qualityGateStrict === "boolean" ? h.qualityGateStrict : defaults.qualityGateStrict,
+		};
+	} catch { return defaults; }
+}
+
+// Inline domain validator — mirrors src/gsd/domain-validator.ts
+function extractGlossaryTerms(content) {
+	const terms = new Set();
+	const sectionMatch = content.match(/## Ubiquitous Language([\s\S]*?)(?:\n## |$)/);
+	const section = sectionMatch ? sectionMatch[1] : content;
+	for (const m of section.matchAll(/\*\*([A-Z][a-zA-Z0-9]+)\*\*/g)) terms.add(m[1]);
+	for (const m of section.matchAll(/^[-*]\s+([A-Z][a-zA-Z0-9]+)\s*:/gm)) terms.add(m[1]);
+	for (const m of section.matchAll(/\|\s*([A-Z][a-zA-Z0-9]+)\s*\|/g)) terms.add(m[1]);
+	return terms;
+}
+
+function loadDomainContent(cwd) {
+	const modelPath = path.join(cwd, ".planning", "DOMAIN-MODEL.md");
+	if (fs.existsSync(modelPath)) return fs.readFileSync(modelPath, "utf-8");
+	const domainPath = path.join(cwd, ".planning", "DOMAIN.md");
+	if (fs.existsSync(domainPath)) return fs.readFileSync(domainPath, "utf-8");
+	return "";
+}
+
+// ── Main ──────────────────────────────────────────────────────────────────────
+const cwd = process.cwd();
+const toolchain = detectToolchain(cwd);
+const hookConfig = readHookConfig(cwd);
+const strict = process.argv.includes("--strict") || hookConfig.qualityGateStrict;
+const issues = [];
+
+// 1. TypeScript check
+try {
+	const tsCmd = toolchain.pm === "bun" ? "bun run tsgo --noEmit 2>&1" : "npx tsc --noEmit 2>&1";
+	execSync(tsCmd, { timeout: 60000, encoding: "utf-8", cwd });
+} catch (error) {
+	const output = error.stdout || error.stderr || "";
+	const errorCount = (output.match(/error TS/g) || []).length;
+	if (errorCount > 0) {
+		issues.push({ severity: strict ? "error" : "warning", message: `${errorCount} TypeScript error(s)`, details: output.slice(0, 500) });
+	}
+}
+
+// 2. Lint check (if biome.json exists use biome, else use toolchain lint)
+if (fs.existsSync(path.join(cwd, "biome.json"))) {
+	try {
+		execSync(`${toolchain.lintCmd} --error-on-warnings 2>&1`, { timeout: 30000, encoding: "utf-8", cwd });
+	} catch (error) {
+		const output = error.stdout || error.stderr || "";
+		issues.push({ severity: strict ? "error" : "warning", message: "Lint issues", details: output.slice(0, 500) });
+	}
+}
+
+// 3. Run tests
+try {
+	const testOutput = execSync(`${toolchain.testCmd} 2>&1`, { timeout: 120000, encoding: "utf-8", cwd });
+	const failMatch = testOutput.match(/(\d+) fail/);
+	if (failMatch && parseInt(failMatch[1], 10) > 0) {
+		issues.push({ severity: strict ? "error" : "warning", message: `${failMatch[1]} test(s) failing` });
+	}
+} catch (error) {
+	const output = error.stdout || error.stderr || "";
+	const failMatch = output.match(/(\d+) fail/);
+	if (failMatch && parseInt(failMatch[1], 10) > 0) {
+		issues.push({ severity: strict ? "error" : "warning", message: `${failMatch[1]} test(s) failing` });
+	}
+}
+
+// 4. Check for console.log in source files (not tests)
+try {
+	const result = execSync(
+		"grep -rn 'console\\.log' src/ --include='*.ts' --include='*.tsx' 2>/dev/null | grep -v '// debug' | head -5",
+		{ encoding: "utf-8", cwd }
+	).trim();
+	if (result) {
+		issues.push({ severity: "warning", message: "console.log found in source", details: result });
+	}
+} catch { /* grep returns 1 when no match — that's fine */ }
+
+// 5. Domain glossary compliance (checks DOMAIN-MODEL.md, falls back to DOMAIN.md)
+const domainContent = loadDomainContent(cwd);
+if (domainContent) {
+	try {
+		const glossaryTerms = extractGlossaryTerms(domainContent);
+		const changedFiles = execSync(
+			"git diff --cached --name-only 2>/dev/null || git diff --name-only HEAD~1",
+			{ encoding: "utf-8", cwd }
+		).trim().split("\n").filter((f) => f.endsWith(".ts") || f.endsWith(".tsx"));
+
+		const unknownTerms = [];
+		for (const file of changedFiles) {
+			if (!fs.existsSync(path.join(cwd, file))) continue;
+			const src = fs.readFileSync(path.join(cwd, file), "utf-8");
+			const declarations = [...src.matchAll(/(?:class|interface|type|enum)\s+([A-Z][a-zA-Z0-9]+)/g)].map((m) => m[1]);
+			for (const term of declarations) {
+				if (!glossaryTerms.has(term)) unknownTerms.push(`${file}: ${term}`);
+			}
+		}
+		if (unknownTerms.length > 0) {
+			issues.push({
+				severity: hookConfig.tddMode === "strict" ? "error" : "warning",
+				message: `${unknownTerms.length} PascalCase type(s) not in domain glossary (DOMAIN-MODEL.md)`,
+				details: unknownTerms.slice(0, 5).join(", "),
+			});
+		}
+	} catch { /* ignore */ }
+}
+
+// 6. Bounded context boundary check — flag suspicious cross-directory imports
+try {
+	const changedSrcFiles = execSync(
+		"git diff --cached --name-only 2>/dev/null || git diff --name-only HEAD~1",
+		{ encoding: "utf-8", cwd }
+	).trim().split("\n").filter((f) => /^src\/[^/]+\//.test(f) && (f.endsWith(".ts") || f.endsWith(".tsx")));
+
+	const crossContextImports = [];
+	for (const file of changedSrcFiles) {
+		if (!fs.existsSync(path.join(cwd, file))) continue;
+		const ownContext = file.split("/")[1];
+		const src = fs.readFileSync(path.join(cwd, file), "utf-8");
+		const imports = [...src.matchAll(/from\s+['"](\.\.\/.+?)['"]/g)].map((m) => m[1]);
+		for (const imp of imports) {
+			const resolved = path.normalize(path.join(path.dirname(file), imp));
+			const parts = resolved.split(path.sep);
+			const srcIdx = parts.indexOf("src");
+			if (srcIdx !== -1 && parts[srcIdx + 1] && parts[srcIdx + 1] !== ownContext) {
+				crossContextImports.push(`${file} → ${parts.slice(srcIdx).join("/")}`);
+			}
+		}
+	}
+	if (crossContextImports.length > 0) {
+		issues.push({
+			severity: "warning",
+			message: `${crossContextImports.length} suspicious cross-context import(s) detected`,
+			details: crossContextImports.slice(0, 3).join("; "),
+		});
+	}
+} catch { /* ignore */ }
+
+// 7. TDD health — check test-to-source file ratio
+try {
+	const allSrc = execSync(
+		"find src -name '*.ts' -not -name '*.test.ts' -not -name '*.spec.ts' 2>/dev/null | wc -l",
+		{ encoding: "utf-8", cwd }
+	).trim();
+	const allTests = execSync(
+		"find src -name '*.test.ts' -o -name '*.spec.ts' 2>/dev/null | wc -l",
+		{ encoding: "utf-8", cwd }
+	).trim();
+	const srcCount = parseInt(allSrc, 10) || 0;
+	const testCount = parseInt(allTests, 10) || 0;
+	if (srcCount > 0) {
+		const ratio = testCount / srcCount;
+		if (ratio < 0.3) {
+			issues.push({
+				severity: "warning",
+				message: `TDD health: test-to-source ratio is ${(ratio * 100).toFixed(0)}% (${testCount} tests / ${srcCount} sources) — target ≥ 30%`,
+			});
+		}
+	}
+} catch { /* ignore — src/ may not exist */ }
+
+// 8. Check for TODO/FIXME/HACK comments in changed files
+try {
+	const diff = execSync(
+		"git diff --cached --name-only 2>/dev/null || git diff --name-only HEAD~1",
+		{ encoding: "utf-8", cwd }
+	).trim();
+	if (diff) {
+		const files = diff.split("\n").filter((f) => f.endsWith(".ts") || f.endsWith(".tsx"));
+		for (const file of files) {
+			try {
+				const content = fs.readFileSync(path.join(cwd, file), "utf-8");
+				const todos = content.match(/\/\/\s*(TODO|FIXME|HACK|XXX):/gi) || [];
+				if (todos.length > 0) {
+					issues.push({ severity: "info", message: `${file}: ${todos.length} TODO/FIXME comment(s)` });
+				}
+			} catch { /* file may not exist */ }
+		}
+	}
+} catch { /* ignore */ }
+
+// Output
+const errors = issues.filter((i) => i.severity === "error");
+const warnings = issues.filter((i) => i.severity === "warning");
+const infos = issues.filter((i) => i.severity === "info");
+
+if (errors.length > 0) {
+	console.log(`\n❌ Quality Gate FAILED (${errors.length} error(s)):`);
+	for (const e of errors) {
+		console.log(`  ❌ ${e.message}`);
+		if (e.details) console.log(`     ${e.details.split("\n")[0]}`);
+	}
+}
+
+if (warnings.length > 0) {
+	console.log(`\n⚠️  ${warnings.length} warning(s):`);
+	for (const w of warnings) {
+		console.log(`  ⚠️  ${w.message}`);
+	}
+}
+
+if (infos.length > 0) {
+	console.log(`\nℹ️  ${infos.length} note(s):`);
+	for (const i of infos) console.log(`  ℹ️  ${i.message}`);
+}
+
+if (errors.length === 0 && warnings.length === 0) {
+	console.log("✅ Quality gate passed");
+}
+
+process.exit(errors.length > 0 ? 1 : 0);

package/scripts/prompt-context.cjs

@@ -0,0 +1,36 @@
+#!/usr/bin/env node
+"use strict";
+
+/**
+ * UserPromptSubmit Hook
+ * Injects minimal draht planning context before each user prompt is sent to the model.
+ * Only activates in projects with .planning/ and adds at most a short reminder line.
+ * Keep output tiny — this runs on every prompt.
+ */
+
+const fs = require("node:fs");
+const path = require("node:path");
+
+const cwd = process.cwd();
+const PLANNING = path.join(cwd, ".planning");
+
+if (!fs.existsSync(PLANNING)) {
+	process.exit(0);
+}
+
+const statePath = path.join(PLANNING, "STATE.md");
+if (!fs.existsSync(statePath)) {
+	process.exit(0);
+}
+
+try {
+	const state = fs.readFileSync(statePath, "utf-8");
+	const phaseMatch = state.match(/## Current Phase: (.+)/);
+	const statusMatch = state.match(/## Status: (.+)/);
+	if (phaseMatch && statusMatch) {
+		// Print a single-line reminder. Claude Code prepends stdout to the prompt context.
+		console.log(`[draht] ${phaseMatch[1].trim()} — ${statusMatch[1].trim()}`);
+	}
+} catch {}
+
+process.exit(0);

package/scripts/session-start.cjs

@@ -0,0 +1,52 @@
+#!/usr/bin/env node
+"use strict";
+
+/**
+ * Session Start Hook
+ * Surfaces draht planning state when a Claude Code session starts in a project.
+ * - Reports current phase and task from .planning/STATE.md
+ * - Flags CONTINUE-HERE.md if the previous session was paused
+ * - Silent in projects without .planning/
+ */
+
+const fs = require("node:fs");
+const path = require("node:path");
+
+const cwd = process.cwd();
+const PLANNING = path.join(cwd, ".planning");
+
+if (!fs.existsSync(PLANNING)) {
+	// No draht planning — silent
+	process.exit(0);
+}
+
+const lines = [];
+
+// STATE.md — current phase + status
+const statePath = path.join(PLANNING, "STATE.md");
+if (fs.existsSync(statePath)) {
+	try {
+		const state = fs.readFileSync(statePath, "utf-8");
+		const phaseMatch = state.match(/## Current Phase: (.+)/);
+		const statusMatch = state.match(/## Status: (.+)/);
+		const activityMatch = state.match(/## Last Activity: (.+)/);
+		if (phaseMatch) lines.push(`Phase: ${phaseMatch[1].trim()}`);
+		if (statusMatch) lines.push(`Status: ${statusMatch[1].trim()}`);
+		if (activityMatch) lines.push(`Last activity: ${activityMatch[1].trim()}`);
+	} catch {}
+}
+
+// CONTINUE-HERE.md — resume marker
+const continuePath = path.join(PLANNING, "CONTINUE-HERE.md");
+if (fs.existsSync(continuePath)) {
+	lines.push("");
+	lines.push("CONTINUE-HERE.md present — the previous session was paused.");
+	lines.push("Run /resume-work to continue, or read .planning/CONTINUE-HERE.md for the handoff.");
+}
+
+if (lines.length > 0) {
+	console.log("━ Draht planning state ━");
+	for (const line of lines) console.log(line);
+}
+
+process.exit(0);

package/skills/ddd-workflow/SKILL.md

@@ -0,0 +1,108 @@
+---
+name: ddd-workflow
+description: Domain-driven design discipline — bounded contexts, ubiquitous language, aggregates, domain events, context maps, and how the .planning/DOMAIN.md file drives code structure and naming. Use whenever the user is modelling a new domain, extracting domain concepts from existing code, deciding where code should live, or naming things.
+---
+
+# DDD Workflow
+
+Draht embeds domain-driven design into project initialization, planning, and execution. The `.planning/DOMAIN.md` file is the single source of truth for domain concepts.
+
+## .planning/DOMAIN.md Structure
+
+```markdown
+## Bounded Contexts
+- **Billing** — everything about invoices, payments, subscriptions
+- **Catalog** — products, pricing, availability
+- **Fulfillment** — order processing, shipping, returns
+
+## Ubiquitous Language
+- **Invoice** — a document requesting payment for delivered goods or services
+- **Order** — a customer's request to purchase goods, before fulfillment
+- **Line Item** — a single row on an invoice or order
+- **SKU** — a unique identifier for a product variant in the catalog
+
+## Context Map
+- Billing ← Catalog (downstream — billing reads product info)
+- Fulfillment ← Billing (downstream — fulfillment needs invoice status)
+- Shared kernel: Money, TaxRate (used by Billing and Fulfillment)
+
+## Aggregates
+### Billing
+- Invoice (root) — LineItem, Payment
+- Subscription (root) — BillingCycle
+
+### Catalog
+- Product (root) — Variant, Price
+
+## Domain Events
+- `InvoiceIssued` — Billing → Fulfillment, Notification
+- `PaymentReceived` — Billing → Notification
+- `OrderShipped` — Fulfillment → Notification, Customer
+```
+
+## The Five Rules
+
+### 1. Bounded contexts shape the code
+- File/module structure mirrors bounded contexts: `src/billing/`, `src/catalog/`, `src/fulfillment/`
+- Each context owns its aggregates, value objects, services, and domain events
+- Cross-context imports are suspicious — prefer domain events or ACL adapters
+
+### 2. Code uses the ubiquitous language
+- Class names, method names, variable names must match the glossary
+- If you need a new term, update `DOMAIN.md` **first**, then write the code
+- Never invent terms in code that aren't in the glossary
+
+### 3. Aggregates enforce invariants
+- Each aggregate has one root entity
+- All writes go through the root — never modify child entities directly from outside
+- Aggregate boundaries align with transaction boundaries
+- Aggregates reference each other by ID, not by reference
+
+### 4. Domain events cross context boundaries
+- Upstream context publishes an event (`InvoiceIssued`)
+- Downstream contexts subscribe and react (Notification sends email, Fulfillment releases order)
+- No direct function call from Billing into Fulfillment — always via event
+
+### 5. Shared kernel is explicit
+- If two contexts must share a type (e.g. `Money`, `TaxRate`), put it in `src/shared/` and document it in the Context Map
+- Shared kernel changes are high-cost — they affect multiple contexts
+- Prefer duplication over coupling when in doubt
+
+## The Post-Phase Domain Health Check
+
+The `gsd-post-phase.cjs` hook checks `DOMAIN.md` after each phase:
+- Is `## Bounded Contexts` section present?
+- Is `## Ubiquitous Language` section present?
+- Count of unique PascalCase terms (proxy for glossary size)
+
+The `gsd-quality-gate.cjs` script also runs a domain validator that compares identifiers in code against the glossary and flags unknown terms.
+
+## Extracting Domain from Existing Code
+
+When running `/init-project` or `/map-codebase` on a codebase that wasn't built with DDD:
+
+1. List top-level `src/` subdirectories — candidates for bounded contexts
+2. Scan PascalCase class / interface / type names — candidates for entities and value objects
+3. Scan repeated nouns in function names — candidates for domain concepts
+4. Look for cross-directory imports — candidates for context coupling to fix
+5. Write `DOMAIN.md` with what you found + what should exist
+6. Use subsequent phases to refactor toward the target model
+
+## Anti-patterns
+
+**Anemic domain model** — entities that are just data bags with no behaviour. Push logic into the entities.
+
+**Scattered aggregates** — one aggregate's logic spread across multiple contexts. Consolidate or introduce an ACL.
+
+**Terminology drift** — the same concept called different things in different files. Fix in `DOMAIN.md` first, rename code second.
+
+**Shared database** — multiple contexts writing to the same tables without explicit shared-kernel agreement. Break the coupling.
+
+**Direct cross-context imports** — `import { ... } from '../billing/...'` in `src/fulfillment/`. Use domain events or ACL adapters.
+
+## When to Update DOMAIN.md
+
+- Before writing code that introduces a new term → add it to the glossary first
+- During `/discuss-phase` when gray areas reveal missing concepts
+- After `/verify-work` when the reviewer agent flags domain language drift
+- Whenever a refactor reveals that existing names don't match reality

package/skills/gsd-workflow/SKILL.md

@@ -0,0 +1,111 @@
+---
+name: gsd-workflow
+description: Draht's Get Shit Done workflow — how to use /new-project, /discuss-phase, /plan-phase, /execute-phase, /verify-work, /next-milestone, /pause-work, /resume-work, /progress, /fix, /quick and the .planning/ directory structure to drive a project from idea to shipping. Use when the user asks how to plan work, structure a project, set up milestones, track progress, or wants to start using draht's workflow.
+---
+
+# GSD (Get Shit Done) Workflow
+
+Draht's GSD workflow is a milestone → phase → plan → task hierarchy that lives in `.planning/` and is driven by slash commands + hooks.
+
+## Directory Structure
+
+```
+.planning/
+├── PROJECT.md              # what are we building
+├── REQUIREMENTS.md         # v1 / v2 / out-of-scope
+├── ROADMAP.md              # phases grouped into milestones
+├── DOMAIN.md               # bounded contexts + ubiquitous language (DDD)
+├── TEST-STRATEGY.md        # test framework, levels, coverage
+├── STATE.md                # current phase, status, last activity
+├── CONTINUE-HERE.md        # handoff doc (only when paused)
+├── execution-log.jsonl     # append-only task execution log
+├── phases/
+│   └── 01-phase-slug/
+│       ├── 01-01-PLAN.md
+│       ├── 01-01-SUMMARY.md
+│       └── 01-02-PLAN.md
+└── phase-N-report.md       # generated by post-phase hook
+```
+
+## The Cycle
+
+### Project initialization (once)
+- **`/new-project`** — greenfield: questioning → domain model → requirements → roadmap
+- **`/init-project`** — existing codebase: map → extract domain → questioning → roadmap
+- **`/map-codebase`** — standalone codebase analysis
+
+### Per-phase cycle (fresh session between each step)
+1. **`/discuss-phase N`** — capture decisions, gray areas, domain terms
+2. **`/plan-phase N`** — create atomic execution plans (parallel via architect subagents)
+3. **`/execute-phase N`** — TDD red→green→refactor (parallel via implementer subagents)
+4. **`/verify-work N`** — parallel verifier + security-auditor + reviewer, produce UAT report
+
+Start a fresh session (`/clear`) between steps. Each command assumes a clean context.
+
+### Milestone transition
+- **`/next-milestone`** — only after ALL phases in the current milestone are `complete`
+
+### Session continuity
+- **`/pause-work`** — create `CONTINUE-HERE.md` with in-progress state
+- **`/resume-work`** — read handoff, verify state, continue
+- **`/progress`** — show current position in the roadmap
+
+### Ad-hoc
+- **`/quick`** — small task with tracking but without full phase ceremony
+- **`/fix`** — bug fix with TDD discipline (reproducing test first)
+- **`/review`** — parallel code review + security audit
+- **`/atomic-commit`** — analyze diff, split into atomic conventional commits
+
+## Task Format (XML inside PLAN.md files)
+
+```xml
+<task type="auto">
+  <n>Task name</n>
+  <context>Bounded context</context>
+  <domain>Aggregates/entities touched</domain>
+  <files>affected files</files>
+  <test>RED phase — write failing tests first</test>
+  <action>GREEN phase — minimal impl to pass tests</action>
+  <refactor>REFACTOR phase — improve without breaking tests</refactor>
+  <verify>How to verify (tests pass + manual check)</verify>
+  <done>What "done" looks like as assertions</done>
+</task>
+```
+
+Task types: `auto`, `checkpoint:human-verify`, `checkpoint:decision`.
+
+## Hooks
+
+The plugin ships workflow hooks under `${CLAUDE_PLUGIN_ROOT}/scripts/`:
+
+- `gsd-pre-execute.cjs <phase>` — preconditions before execution (DOMAIN.md, plans, uncommitted changes)
+- `gsd-post-task.cjs <phase> <plan> <task> <status> [commit]` — record result + type check + tests + TDD cycle check
+- `gsd-post-phase.cjs <phase>` — generate phase report, update ROADMAP status
+- `gsd-quality-gate.cjs [--strict]` — lint + typecheck + test + coverage against `.planning/config.json` threshold
+
+These are invoked from inside commands (not as Claude Code lifecycle hooks).
+
+## Configuration
+
+`.planning/config.json` (optional):
+
+```json
+{
+  "hooks": {
+    "coverageThreshold": 80,
+    "tddMode": "advisory",
+    "qualityGateStrict": false
+  }
+}
+```
+
+- `tddMode: "strict"` — post-task hook aborts on green: commit without preceding red:
+- `tddMode: "advisory"` — logs a warning instead
+- `qualityGateStrict: true` — fail the gate on any lint/type/test/coverage miss
+
+## Key Rules
+
+- One phase at a time, one cycle step per session
+- `/next-milestone` ONLY after every phase in the current milestone is verified
+- Fix plans include a reproducing test before any implementation
+- Never skip verification — it's the only thing that marks a phase complete

package/skills/tdd-workflow/SKILL.md

@@ -0,0 +1,115 @@
+---
+name: tdd-workflow
+description: Test-driven development discipline — red→green→refactor cycle, commit conventions (red:, green:, refactor:), TDD cycle violations, reproducing tests before fixes, and how to write tests that actually drive design. Use whenever the user is writing code that has testable behaviour, fixing bugs, or asks about TDD.
+---
+
+# TDD Workflow
+
+Draht enforces strict test-driven development through commit conventions, post-task hooks, and the plan task format.
+
+## The Cycle
+
+### RED — Write a failing test
+1. Write a test that describes the behaviour you want
+2. Run the test runner — it MUST fail for the right reason (not a syntax error, not a missing import)
+3. Commit with prefix `red:`
+   ```
+   git add <test-files>
+   git commit -m "red: <what the test proves>"
+   ```
+
+### GREEN — Make it pass with the smallest possible change
+1. Write the minimum implementation that makes the failing test pass
+2. Run the test — confirm it passes
+3. Run the full test suite — confirm no regressions
+4. Commit with prefix `green:`
+   ```
+   git add <impl-files>
+   git commit -m "green: <task name>"
+   ```
+
+### REFACTOR — Improve structure while staying green
+1. Tests must stay green after every change — run them often
+2. Extract value objects, push logic into domain layer, remove duplication
+3. Keep to the ubiquitous language from `.planning/DOMAIN.md`
+4. Commit with prefix `refactor:`
+   ```
+   git add <files>
+   git commit -m "refactor: <what was improved>"
+   ```
+
+## Rules
+
+1. **Never write implementation before a failing test.** If you find yourself writing code that doesn't have a failing test waiting for it, stop and write the test first.
+
+2. **A test that passes on first run is suspect.** It means you're not testing what you think. Make it fail by breaking the implementation temporarily — does it fail? If not, the test is useless.
+
+3. **One red → one green → optional refactor.** Keep cycles small. A red commit with 20 failing tests is too big.
+
+4. **Test behaviour, not implementation.** Write tests against the public API. Tests that mock everything are tests of the mocks.
+
+5. **Domain tests use domain language.** Class names, test names, fixture names must match `.planning/DOMAIN.md` if it exists. Domain tests read like specs.
+
+6. **Fix bugs with a reproducing test first.** No exceptions. The test must fail before the fix, pass after.
+
+## TDD Cycle Violations
+
+The post-task hook (`gsd-post-task.cjs`) checks commit history for cycle violations:
+
+- A `green:` commit with no preceding `red:` commit for the same task → violation
+- In `strict` mode: the hook aborts execution
+- In `advisory` mode: the hook logs a warning to `.planning/execution-log.jsonl`
+
+Set the mode in `.planning/config.json`:
+```json
+{ "hooks": { "tddMode": "strict" } }
+```
+
+## When to Skip the Cycle
+
+Only skip TDD for:
+- Pure configuration (tsconfig, biome, prettier)
+- Documentation-only changes
+- Generated code (auto-generated clients, schema bindings)
+- Mechanical refactors with no behaviour change (e.g., rename)
+
+Never skip for:
+- Bug fixes
+- New features
+- Changes to domain logic
+- Changes to APIs
+
+## The Plan Task Format Drives TDD
+
+Plan tasks use `<test>`, `<action>`, `<refactor>` sections precisely to force the cycle:
+
+```xml
+<task type="auto">
+  <n>Add user authentication</n>
+  <test>
+    RED phase: Write failing tests FIRST.
+    - test/auth.test.ts: valid credentials → returns session token
+    - test/auth.test.ts: invalid password → throws UnauthorizedError
+    - test/auth.test.ts: expired token → returns null
+  </test>
+  <action>
+    GREEN phase: Minimal implementation.
+    - src/auth/login.ts: verify password hash, return token
+    - src/auth/session.ts: read/write session store
+  </action>
+  <refactor>
+    Extract password verification into domain layer. Keep session IO at the boundary.
+  </refactor>
+</task>
+```
+
+When executing, the implementer subagent follows this order strictly. Commits get the `red:` / `green:` / `refactor:` prefixes automatically.
+
+## Coverage Goals
+
+`.planning/config.json` sets the threshold:
+```json
+{ "hooks": { "coverageThreshold": 80 } }
+```
+
+The `gsd-quality-gate.cjs` script enforces this at verification time. Coverage is a floor, not a target — aim for the meaningful paths.