@draht/coding-agent 2026.3.4 → 2026.3.6

package/dist/prompts/commands/verify-work.md

@@ -1,27 +1,47 @@
+---
+description: "Acceptance testing of completed phase work"
+---
+
 # /verify-work
 
-Walk through acceptance testing of completed phase work.
+Walk through acceptance testing of completed phase work, using subagents for parallel verification.
 
 ## Usage
 ```
 /verify-work [N]
 ```
 
+Phase: $1
+
 ## Steps
-1. Run full test suite and capture results:
-   - Execute all tests (`bun test` or project-specific runner)
-   - Record pass/fail counts — verification cannot proceed if tests are failing
-2. Check domain language violations:
-   - Load `.planning/DOMAIN.md` and extract all defined terms
-   - Scan source files for PascalCase identifiers not present in the glossary
-   - Flag any bounded context boundary violations (cross-context direct imports)
-3. Run quality gate: `draht-tools quality-gate --strict`
-4. Run `draht-tools extract-deliverables N` to get testable items
-5. Walk user through each deliverable one at a time
-6. Record results (pass/fail/partially/skip)
-7. For failures: diagnose and create fix plans via `draht-tools create-fix-plan N P`
+1. Run `draht-tools extract-deliverables $1` to get testable items
+2. **Run parallel verification via subagents:**
+   Use the `subagent` tool in **parallel mode** with these tasks:
+   - `verifier` agent: "Run the full test suite for this project. Check package.json for the test command. Record pass/fail counts. Then run any available lint and typecheck commands (e.g. npm run check, npm run lint, npx tsc --noEmit). Report all results with error details. Do NOT run draht, draht-tools, or pi commands."
+   - `security-auditor` agent: "Audit the recent code changes (use git log and git diff to find them). Check for injection risks, auth bypasses, secrets in code, unsafe patterns. Report findings by severity. Do NOT run draht, draht-tools, or pi commands."
+   - `reviewer` agent: "Review the recent code changes (use git log and git diff). Check domain language compliance against `.planning/DOMAIN.md` if it exists — scan for identifiers not in the glossary and cross-context boundary violations. Report findings. Do NOT run draht, draht-tools, or pi commands."
+
+3. Collect results from all subagents
+4. Walk user through each deliverable one at a time, incorporating findings from the parallel checks
+5. Record results (pass/fail/partially/skip)
+6. For failures: diagnose and create fix plans via `draht-tools create-fix-plan $1 P`
    - Fix plans MUST include a reproducing test that demonstrates the failure before any implementation
-8. Write UAT report: `draht-tools write-uat N`
-   - Report must include: test health summary (pass/fail/coverage), domain model status (any glossary violations), deliverable results
-9. If all passed: mark phase complete
-10. If failures: route to `execute-phase N --gaps-only`
+7. Write UAT report: `draht-tools write-uat $1`
+   - Report must include: test health summary (pass/fail/coverage), security audit results, domain model status (any glossary violations), deliverable results
+8. If all passed: mark phase complete.
+   - If more phases remain in the milestone: tell the user to start a new session and run `/discuss-phase N+1`.
+   - If ALL phases in the milestone are complete: tell the user to start a new session and run `/next-milestone`.
+9. If failures: route to `execute-phase $1 --gaps-only`
+
+## Workflow
+This is the last step in the per-phase cycle. Each step runs in its own session (`/new` between steps):
+
+```
+/discuss-phase N → /new → /plan-phase N → /new → /execute-phase N → /new → /verify-work N
+```
+
+After verify-work passes:
+- More phases remaining → `/new` → `/discuss-phase N+1`
+- ALL phases in milestone verified → `/new` → `/next-milestone`
+
+`/next-milestone` is ONLY for generating new phases after every phase in the current milestone is complete.

package/hooks/gsd/draht-post-task.js

@@ -19,28 +19,60 @@ if (!phaseNum || !planNum || !taskNum || !status) {
 	process.exit(1);
 }
 
+// ── 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; }
+}
+
 const PLANNING = ".planning";
 const LOG_FILE = path.join(PLANNING, "execution-log.jsonl");
+const cwd = process.cwd();
+const toolchain = detectToolchain(cwd);
+const hookConfig = readHookConfig(cwd);
 
 // 0. TDD cycle compliance check
-// If the current commit message starts with "green:", the previous commit for this
-// task should start with "red:" — enforce the Red → Green order.
 if (commitHash) {
 	try {
-		// Find the commit message for commitHash and the one before it
 		const currentMsg = execSync(`git log --format=%s -n 1 ${commitHash} 2>/dev/null`, { encoding: "utf-8" }).trim();
 		if (/^green:/i.test(currentMsg)) {
-			// Scope search to commits that mention this phase/plan/task in their message
-			// to avoid false positives from unrelated older commits
 			const taskPrefix = `${phaseNum}-${planNum}-${taskNum}`;
 			const recentMsgs = execSync(`git log --format=%s -n 50 ${commitHash}~1 2>/dev/null`, { encoding: "utf-8" })
 				.trim()
 				.split("\n")
 				.filter((m) => m.includes(taskPrefix) || /^(red|green|refactor):/i.test(m));
-			// Find the nearest TDD-cycle commit scoped to this task
 			const prevTaskMsg = recentMsgs.find((m) => /^(red|green|refactor):/i.test(m) && m.includes(taskPrefix));
 			if (!prevTaskMsg || !/^red:/i.test(prevTaskMsg)) {
-				console.log(`⚠️  TDD violation: "green:" commit detected but no preceding "red:" commit found for task ${phaseNum}-${planNum}-${taskNum}`);
+				const violation = `TDD violation: "green:" commit without preceding "red:" for task ${phaseNum}-${planNum}-${taskNum}`;
+				if (hookConfig.tddMode === "strict") {
+					console.error(`❌ ${violation}`);
+					process.exit(1);
+				} else {
+					console.log(`⚠️  ${violation}`);
+				}
 				fs.appendFileSync(LOG_FILE, JSON.stringify({
 					timestamp: new Date().toISOString(),
 					phase: parseInt(phaseNum, 10),
@@ -69,13 +101,15 @@ const entry = {
 
 fs.appendFileSync(LOG_FILE, JSON.stringify(entry) + "\n");
 
-// 2. Run type check if status is pass
+// 2. Run type check and tests if status is pass
 if (status === "pass") {
+	// Type check
 	try {
-		execSync("bun run tsgo --noEmit 2>&1", { timeout: 30000, encoding: "utf-8" });
+		const tsCmd = toolchain.pm === "bun" ? "bun run tsgo --noEmit 2>&1" : "npx tsc --noEmit 2>&1";
+		execSync(tsCmd, { timeout: 30000, encoding: "utf-8", cwd });
 		// Run tests
 		try {
-			const testOutput = execSync("bun test 2>&1", { timeout: 60000, encoding: "utf-8" });
+			const testOutput = execSync(`${toolchain.testCmd} 2>&1`, { timeout: 60000, encoding: "utf-8", cwd });
 			const testMatch = testOutput.match(/(\d+) pass/);
 			const testCount = testMatch ? testMatch[1] : "?";
 			console.log(`✅ Task ${phaseNum}-${planNum}-${taskNum}: passed + types clean + ${testCount} tests pass`);
@@ -93,7 +127,6 @@ if (status === "pass") {
 		const errorCount = (output.match(/error TS/g) || []).length;
 		if (errorCount > 0) {
 			console.log(`⚠️  Task ${phaseNum}-${planNum}-${taskNum}: passed but ${errorCount} type error(s) introduced`);
-			// Append warning to log
 			fs.appendFileSync(LOG_FILE, JSON.stringify({
 				...entry,
 				warning: `${errorCount} type errors introduced`,

package/hooks/gsd/draht-quality-gate.js

@@ -12,13 +12,67 @@
 
 const { execSync } = require("node:child_process");
 const fs = require("node:fs");
+const path = require("node:path");
 
-const strict = process.argv.includes("--strict");
+// ── 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 {
-	execSync("bun run tsgo --noEmit 2>&1", { timeout: 60000, encoding: "utf-8" });
+	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;
@@ -27,19 +81,19 @@ try {
 	}
 }
 
-// 2. Biome lint check (if biome.json exists)
-if (fs.existsSync("biome.json")) {
+// 2. Lint check (if biome.json exists use biome, else use toolchain lint)
+if (fs.existsSync(path.join(cwd, "biome.json"))) {
 	try {
-		execSync("bunx biome check --error-on-warnings . 2>&1", { timeout: 30000, encoding: "utf-8" });
+		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: "Biome lint issues", details: output.slice(0, 500) });
+		issues.push({ severity: strict ? "error" : "warning", message: "Lint issues", details: output.slice(0, 500) });
 	}
 }
 
 // 3. Run tests
 try {
-	const testOutput = execSync("bun test 2>&1", { timeout: 120000, encoding: "utf-8" });
+	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` });
@@ -56,71 +110,56 @@ try {
 try {
 	const result = execSync(
 		"grep -rn 'console\\.log' src/ --include='*.ts' --include='*.tsx' 2>/dev/null | grep -v '// debug' | head -5",
-		{ encoding: "utf-8" }
+		{ encoding: "utf-8", cwd }
 	).trim();
 	if (result) {
-		issues.push({ severity: "warning", message: `console.log found in source`, details: result });
+		issues.push({ severity: "warning", message: "console.log found in source", details: result });
 	}
-} catch { /* grep returns 1 when no match — that's good */ }
+} catch { /* grep returns 1 when no match — that's fine */ }
 
-// 5. Domain glossary compliance
-// Extract terms from DOMAIN.md and flag new PascalCase classes not in the glossary
-const domainMdPath = ".planning/DOMAIN.md";
-if (fs.existsSync(domainMdPath)) {
+// 5. Domain glossary compliance (checks DOMAIN-MODEL.md, falls back to DOMAIN.md)
+const domainContent = loadDomainContent(cwd);
+if (domainContent) {
 	try {
-		const domainContent = fs.readFileSync(domainMdPath, "utf-8");
-		// Collect all PascalCase tokens that appear in the glossary section
-		const glossarySection = domainContent.match(/## Ubiquitous Language([\s\S]*?)(?:^##|\Z)/m)?.[1] || "";
-		// Each glossary entry is assumed to start the line with a PascalCase term (e.g. "**Order**" or "- Order:")
-		const glossaryTerms = new Set(
-			[...glossarySection.matchAll(/\b([A-Z][a-zA-Z0-9]+)\b/g)].map((m) => m[1])
-		);
-
-		// Scan changed source files for PascalCase class/interface/type declarations
-		try {
-			const changedFiles = execSync(
-				"git diff --cached --name-only 2>/dev/null || git diff --name-only HEAD~1",
-				{ encoding: "utf-8" }
-			).trim().split("\n").filter((f) => f.endsWith(".ts") || f.endsWith(".tsx"));
-
-			const unknownTerms = [];
-			for (const file of changedFiles) {
-				if (!fs.existsSync(file)) continue;
-				const src = fs.readFileSync(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}`);
-					}
-				}
+		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: "warning",
-					message: `${unknownTerms.length} PascalCase type(s) not in DOMAIN.md glossary`,
-					details: unknownTerms.slice(0, 5).join(", "),
-				});
-			}
-		} catch { /* ignore git errors */ }
-	} catch { /* ignore read errors */ }
+		}
+		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" }
+		{ 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(file)) continue;
-		// Determine this file's context (first path segment under src/)
+		if (!fs.existsSync(path.join(cwd, file))) continue;
 		const ownContext = file.split("/")[1];
-		const src = fs.readFileSync(file, "utf-8");
+		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) {
-			// Resolve relative import against the file's directory
 			const resolved = path.normalize(path.join(path.dirname(file), imp));
 			const parts = resolved.split(path.sep);
 			const srcIdx = parts.indexOf("src");
@@ -142,11 +181,11 @@ try {
 try {
 	const allSrc = execSync(
 		"find src -name '*.ts' -not -name '*.test.ts' -not -name '*.spec.ts' 2>/dev/null | wc -l",
-		{ encoding: "utf-8" }
+		{ 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" }
+		{ encoding: "utf-8", cwd }
 	).trim();
 	const srcCount = parseInt(allSrc, 10) || 0;
 	const testCount = parseInt(allTests, 10) || 0;
@@ -163,12 +202,15 @@ try {
 
 // 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" }).trim();
+	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(file, "utf-8");
+				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)` });

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@draht/coding-agent",
-	"version": "2026.3.4",
+	"version": "2026.3.6",
 	"description": "Coding agent CLI with read, bash, edit, write tools and session management",
 	"type": "module",
 	"drahtConfig": {
@@ -46,9 +46,9 @@
 	},
 	"dependencies": {
 		"@mariozechner/jiti": "^2.6.2",
-		"@draht/agent-core": "2026.3.4",
-		"@draht/ai": "2026.3.4",
-		"@draht/tui": "2026.3.4",
+		"@draht/agent-core": "2026.3.6",
+		"@draht/ai": "2026.3.6",
+		"@draht/tui": "2026.3.6",
 		"@silvia-odwyer/photon-node": "^0.3.4",
 		"chalk": "^5.5.0",
 		"cli-highlight": "^2.1.11",
@@ -92,7 +92,7 @@
 		"tui",
 		"agent"
 	],
-	"author": "Mario Zechner",
+	"author": "Oskar Freye",
 	"license": "MIT",
 	"publishConfig": {
 		"access": "public"

package/prompts/agents/build.md

@@ -1,6 +1,10 @@
+---
+description: "Execution agent that implements plans precisely"
+---
+
 # Draht Build Agent
 
-You are an execution agent for the Get Shit Done methodology. Your job is to implement plans precisely.
+You are an execution agent. Your job is to implement plans precisely.
 
 ## Core Rules
 1. Read the plan FIRST — it is your instruction set

package/prompts/agents/plan.md

@@ -1,6 +1,10 @@
+---
+description: "Planning agent that creates atomic, executable plans"
+---
+
 # Draht Plan Agent
 
-You are a planning agent for the Get Shit Done methodology. Your job is to create atomic, executable plans.
+You are a planning agent. Your job is to create atomic, executable plans.
 
 ## Core Rules
 1. Plans are prompts — they tell the executor EXACTLY what to build

package/prompts/agents/verify.md

@@ -1,6 +1,10 @@
+---
+description: "Verification agent that tests work against acceptance criteria"
+---
+
 # Draht Verify Agent
 
-You are a verification agent for the Get Shit Done methodology. Your job is to test completed work against acceptance criteria.
+You are a verification agent. Your job is to test completed work against acceptance criteria.
 
 ## Core Rules
 1. Test from the USER's perspective, not the developer's

package/prompts/commands/atomic-commit.md

@@ -4,19 +4,13 @@ description: "Analyze changes and create atomic commits"
 
 # Git Atomic Commit Analysis
 
-First, check the current status:
+First, gather the current state:
 
-*! git status*
+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
 
-Now get the full diff of all changes:
-
-*! git diff*
-
-And staged changes:
-
-*! git diff --cached*
-
-Based on the changes shown above, analyze and group them into logical, ATOMIC commits. Each commit should:
+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
@@ -27,13 +21,11 @@ For each group of changes you identify:
 - Generate a clear, descriptive commit message following conventional commits format
 - Explain WHY these changes belong in one commit
 
-Then provide the exact `git add` and `git commit` commands to execute for each atomic commit in the order they should be applied.
+Then execute the `git add` and `git commit` commands for each atomic commit in the order they should be applied.
 
 Format each commit message as:
+```
 type(scope): brief description
-- Detailed explanation of what changed
-- Why the change was necessary
-
+```
 
 Common types: feat, fix, refactor, docs, test, chore, style, perf
-

package/prompts/commands/discuss-phase.md

@@ -1,3 +1,7 @@
+---
+description: "Capture implementation decisions before planning a phase"
+---
+
 # /discuss-phase
 
 Capture implementation decisions before planning a phase.
@@ -7,13 +11,25 @@ Capture implementation decisions before planning a phase.
 /discuss-phase [N]
 ```
 
+Phase: $1
+
 ## Steps
-1. Run `draht-tools phase-info N` to load phase context
+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 N`
-6. Commit: `draht-tools commit-docs "capture phase N context"`
+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. Each step runs in its own session (`/new` between steps):
+
+```
+/discuss-phase N → /new → /plan-phase N → /new → /execute-phase N → /new → /verify-work N → /new → /discuss-phase N+1 → ...
+```
+
+After completing this command, tell the user to start a new 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