@draht/coding-agent 2026.3.2-2

package/extensions/subagent.ts

@@ -0,0 +1,312 @@
+/**
+ * Subagent Tool for Draht — adapted from the pi subagent example
+ *
+ * Spawns isolated draht processes for delegated tasks.
+ * Agents are defined in .draht/agents/*.md (project) or ~/.draht/agent/agents/*.md (global).
+ *
+ * Modes:
+ *   single   — { agent, task }
+ *   parallel — { tasks: [{ agent, task }] }  (max 8, concurrency 4)
+ *   chain    — { chain: [{ agent, task }] }  (sequential, {previous} placeholder)
+ */
+
+import { spawn } from "node:child_process";
+import * as fs from "node:fs";
+import * as os from "node:os";
+import * as path from "node:path";
+import type { Message } from "@draht/ai";
+import { StringEnum } from "@draht/ai";
+import { type ExtensionAPI, getAgentDir, parseFrontmatter } from "@draht/coding-agent";
+import { Type } from "@sinclair/typebox";
+
+const MAX_PARALLEL = 8;
+const MAX_CONCURRENCY = 4;
+// Use the same binary that's currently running
+const DRAHT_BIN = process.execPath;
+
+// ─── Agent discovery ────────────────────────────────────────────────────────
+
+interface AgentConfig {
+	name: string;
+	description: string;
+	tools?: string[];
+	model?: string;
+	systemPrompt: string;
+	source: "user" | "project";
+}
+
+function loadAgentsFromDir(dir: string, source: "user" | "project"): AgentConfig[] {
+	if (!fs.existsSync(dir)) return [];
+	let entries: fs.Dirent[];
+	try {
+		entries = fs.readdirSync(dir, { withFileTypes: true });
+	} catch {
+		return [];
+	}
+	const agents: AgentConfig[] = [];
+	for (const entry of entries) {
+		if (!entry.isFile() || !entry.name.endsWith(".md")) continue;
+		try {
+			const content = fs.readFileSync(path.join(dir, entry.name), "utf-8");
+			const { frontmatter, body } = parseFrontmatter<Record<string, string>>(content);
+			if (!frontmatter.name || !frontmatter.description) continue;
+			const tools = frontmatter.tools?.split(",").map((t: string) => t.trim()).filter(Boolean);
+			agents.push({
+				name: frontmatter.name,
+				description: frontmatter.description,
+				tools: tools?.length ? tools : undefined,
+				model: frontmatter.model,
+				systemPrompt: body,
+				source,
+			});
+		} catch {
+			continue;
+		}
+	}
+	return agents;
+}
+
+function findProjectAgentsDir(cwd: string): string | null {
+	let dir = cwd;
+	while (true) {
+		const candidate = path.join(dir, ".draht", "agents");
+		try {
+			if (fs.statSync(candidate).isDirectory()) return candidate;
+		} catch {}
+		const parent = path.dirname(dir);
+		if (parent === dir) return null;
+		dir = parent;
+	}
+}
+
+type AgentScope = "user" | "project" | "both";
+
+function discoverAgents(cwd: string, scope: AgentScope): AgentConfig[] {
+	const userDir = path.join(getAgentDir(), "agents");
+	const projectDir = findProjectAgentsDir(cwd);
+	const userAgents = scope !== "project" ? loadAgentsFromDir(userDir, "user") : [];
+	const projectAgents = scope !== "user" && projectDir ? loadAgentsFromDir(projectDir, "project") : [];
+	const map = new Map<string, AgentConfig>();
+	for (const a of userAgents) map.set(a.name, a);
+	for (const a of projectAgents) map.set(a.name, a); // project overrides global
+	return Array.from(map.values());
+}
+
+// ─── Runner ─────────────────────────────────────────────────────────────────
+
+interface RunResult {
+	agent: string;
+	task: string;
+	exitCode: number;
+	output: string;
+	stderr: string;
+	step?: number;
+}
+
+function writeTemp(name: string, content: string): { file: string; dir: string } {
+	const dir = fs.mkdtempSync(path.join(os.tmpdir(), "draht-subagent-"));
+	const file = path.join(dir, `${name.replace(/[^\w.-]/g, "_")}.md`);
+	fs.writeFileSync(file, content, { encoding: "utf-8", mode: 0o600 });
+	return { file, dir };
+}
+
+function cleanTemp(file: string, dir: string) {
+	try { fs.unlinkSync(file); } catch {}
+	try { fs.rmdirSync(dir); } catch {}
+}
+
+function getFinalText(messages: Message[]): string {
+	for (let i = messages.length - 1; i >= 0; i--) {
+		const msg = messages[i];
+		if (msg.role === "assistant") {
+			for (const part of msg.content) {
+				if (part.type === "text") return part.text;
+			}
+		}
+	}
+	return "";
+}
+
+async function runAgent(
+	cwd: string,
+	agent: AgentConfig,
+	task: string,
+	signal?: AbortSignal,
+	step?: number,
+): Promise<RunResult> {
+	const args: string[] = ["--mode", "json", "-p", "--no-session"];
+	if (agent.model) args.push("--model", agent.model);
+	if (agent.tools?.length) args.push("--tools", agent.tools.join(","));
+
+	let tmpFile: string | null = null;
+	let tmpDir: string | null = null;
+
+	if (agent.systemPrompt.trim()) {
+		const tmp = writeTemp(agent.name, agent.systemPrompt);
+		tmpFile = tmp.file;
+		tmpDir = tmp.dir;
+		args.push("--append-system-prompt", tmpFile);
+	}
+
+	args.push(`Task: ${task}`);
+
+	const messages: Message[] = [];
+	let stderr = "";
+
+	try {
+		const exitCode = await new Promise<number>((resolve) => {
+			const proc = spawn(DRAHT_BIN, args, { cwd, shell: false, stdio: ["ignore", "pipe", "pipe"] });
+			let buf = "";
+
+			const processLine = (line: string) => {
+				if (!line.trim()) return;
+				try {
+					const event = JSON.parse(line);
+					if ((event.type === "message_end" || event.type === "tool_result_end") && event.message) {
+						messages.push(event.message as Message);
+					}
+				} catch {}
+			};
+
+			proc.stdout.on("data", (d) => {
+				buf += d.toString();
+				const lines = buf.split("\n");
+				buf = lines.pop() || "";
+				for (const l of lines) processLine(l);
+			});
+			proc.stderr.on("data", (d) => { stderr += d.toString(); });
+			proc.on("close", (code) => {
+				if (buf.trim()) processLine(buf);
+				resolve(code ?? 0);
+			});
+			proc.on("error", () => resolve(1));
+
+			if (signal) {
+				const kill = () => { proc.kill("SIGTERM"); setTimeout(() => { if (!proc.killed) proc.kill("SIGKILL"); }, 5000); };
+				if (signal.aborted) kill();
+				else signal.addEventListener("abort", kill, { once: true });
+			}
+		});
+
+		return { agent: agent.name, task, exitCode, output: getFinalText(messages), stderr, step };
+	} finally {
+		if (tmpFile && tmpDir) cleanTemp(tmpFile, tmpDir);
+	}
+}
+
+async function runParallel<T>(
+	items: T[],
+	concurrency: number,
+	fn: (item: T, i: number) => Promise<T extends unknown ? RunResult : never>,
+): Promise<RunResult[]> {
+	const results: RunResult[] = new Array(items.length);
+	let next = 0;
+	await Promise.all(
+		Array.from({ length: Math.min(concurrency, items.length) }, async () => {
+			while (true) {
+				const i = next++;
+				if (i >= items.length) return;
+				results[i] = await (fn as (item: T, i: number) => Promise<RunResult>)(items[i], i);
+			}
+		}),
+	);
+	return results;
+}
+
+// ─── Extension ──────────────────────────────────────────────────────────────
+
+const TaskItem = Type.Object({
+	agent: Type.String({ description: "Agent name" }),
+	task: Type.String({ description: "Task description" }),
+});
+
+const ChainItem = Type.Object({
+	agent: Type.String({ description: "Agent name" }),
+	task: Type.String({ description: "Task, optionally using {previous} placeholder" }),
+});
+
+const Params = Type.Object({
+	agent: Type.Optional(Type.String()),
+	task: Type.Optional(Type.String()),
+	tasks: Type.Optional(Type.Array(TaskItem, { description: "Parallel tasks" })),
+	chain: Type.Optional(Type.Array(ChainItem, { description: "Chained tasks" })),
+	agentScope: Type.Optional(
+		StringEnum(["user", "project", "both"] as const, { default: "both" }),
+	),
+});
+
+export default function (pi: ExtensionAPI) {
+	pi.registerTool({
+		name: "subagent",
+		label: "Subagent",
+		description:
+			"Delegate to specialized agents. single: {agent,task} | parallel: {tasks:[]} | chain: {chain:[]} with {previous} placeholder. agentScope: 'both' (default) uses project .draht/agents/ + global.",
+		parameters: Params,
+
+		async execute(_id, params, signal, _onUpdate, ctx) {
+			const scope: AgentScope = (params.agentScope as AgentScope) ?? "both";
+			const agents = discoverAgents(ctx.cwd, scope);
+			const available = agents.map((a) => a.name).join(", ") || "none";
+
+			const find = (name: string) => agents.find((a) => a.name === name);
+			const notFound = (name: string) => ({
+				content: [{ type: "text" as const, text: `Unknown agent "${name}". Available: ${available}` }],
+				isError: true,
+			});
+
+			// ── Chain mode ──
+			if (params.chain?.length) {
+				let previous = "";
+				const results: RunResult[] = [];
+				for (let i = 0; i < params.chain.length; i++) {
+					const step = params.chain[i];
+					const agent = find(step.agent);
+					if (!agent) return notFound(step.agent);
+					const task = step.task.replace(/\{previous\}/g, previous);
+					const result = await runAgent(ctx.cwd, agent, task, signal, i + 1);
+					results.push(result);
+					if (result.exitCode !== 0) {
+						return {
+							content: [{ type: "text" as const, text: `Chain failed at step ${i + 1} (${step.agent}):\n${result.output || result.stderr}` }],
+							isError: true,
+						};
+					}
+					previous = result.output;
+				}
+				return { content: [{ type: "text" as const, text: results[results.length - 1].output || "(no output)" }] };
+			}
+
+			// ── Parallel mode ──
+			if (params.tasks?.length) {
+				if (params.tasks.length > MAX_PARALLEL) {
+					return { content: [{ type: "text" as const, text: `Too many tasks (max ${MAX_PARALLEL})` }], isError: true };
+				}
+				for (const t of params.tasks) { if (!find(t.agent)) return notFound(t.agent); }
+
+				const results = await runParallel(params.tasks, MAX_CONCURRENCY, async (t, i) => {
+					return runAgent(ctx.cwd, find(t.agent)!, t.task, signal);
+				});
+
+				const ok = results.filter((r) => r.exitCode === 0).length;
+				const summary = results
+					.map((r) => `[${r.agent}] ${r.exitCode === 0 ? "✓" : "✗"} ${r.output.slice(0, 200)}`)
+					.join("\n\n");
+				return { content: [{ type: "text" as const, text: `Parallel: ${ok}/${results.length} succeeded\n\n${summary}` }] };
+			}
+
+			// ── Single mode ──
+			if (params.agent && params.task) {
+				const agent = find(params.agent);
+				if (!agent) return notFound(params.agent);
+				const result = await runAgent(ctx.cwd, agent, params.task, signal);
+				const isError = result.exitCode !== 0;
+				return {
+					content: [{ type: "text" as const, text: result.output || result.stderr || "(no output)" }],
+					...(isError ? { isError: true } : {}),
+				};
+			}
+
+			return { content: [{ type: "text" as const, text: `Provide exactly one mode. Available agents: ${available}` }], isError: true };
+		},
+	});
+}

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

@@ -0,0 +1,133 @@
+#!/usr/bin/env node
+"use strict";
+
+/**
+ * Draht Post-Phase Hook
+ * Runs after phase completion to generate reports and update state.
+ *
+ * Usage: node gsd-post-phase.js <phase-number>
+ */
+
+const fs = require("node:fs");
+const path = require("node:path");
+
+const phaseNum = process.argv[2];
+if (!phaseNum) {
+	console.error("Usage: gsd-post-phase.js <phase-number>");
+	process.exit(1);
+}
+
+const PLANNING = ".planning";
+const LOG_FILE = path.join(PLANNING, "execution-log.jsonl");
+
+// 1. Read execution log for this phase
+let entries = [];
+if (fs.existsSync(LOG_FILE)) {
+	entries = fs.readFileSync(LOG_FILE, "utf-8")
+		.split("\n")
+		.filter(Boolean)
+		.map((l) => JSON.parse(l))
+		.filter((e) => e.phase === parseInt(phaseNum, 10));
+}
+
+const passed = entries.filter((e) => e.status === "pass").length;
+const failed = entries.filter((e) => e.status === "fail").length;
+const skipped = entries.filter((e) => e.status === "skip").length;
+const warnings = entries.filter((e) => e.warning).length;
+
+// 2. Compute TDD and domain health metrics
+const tddViolations = entries.filter((e) => e.status === "tdd-violation").length;
+
+// TDD commit counts: derive from git log scoped to commits since phase start
+// (use the earliest entry timestamp as the lower bound)
+let tddSummary = "⚠️  No TDD commit data in log";
+try {
+	const { execSync } = require("node:child_process");
+	// Scope to commits that follow TDD naming convention for this phase
+	const gitLog = execSync(
+		`git log --format=%s --grep="^[0-9]" -E --extended-regexp 2>/dev/null || git log --format=%s 2>/dev/null`,
+		{ encoding: "utf-8" }
+	).trim();
+	const lines = gitLog.split("\n");
+	const redCount = lines.filter((l) => /^red:/i.test(l)).length;
+	const greenCount = lines.filter((l) => /^green:/i.test(l)).length;
+	const refactorCount = lines.filter((l) => /^refactor:/i.test(l)).length;
+	if (redCount + greenCount + refactorCount > 0) {
+		tddSummary = `🔴 Red: ${redCount}  🟢 Green: ${greenCount}  🔵 Refactor: ${refactorCount}`;
+	} else {
+		tddSummary = "⚠️  No red:/green:/refactor: commits found — TDD cycle may not have been followed";
+	}
+} catch { /* ignore */ }
+
+// Domain health: check DOMAIN.md presence and glossary size
+let domainSummary = "⚠️  .planning/DOMAIN.md not found";
+const domainPath = path.join(PLANNING, "DOMAIN.md");
+if (fs.existsSync(domainPath)) {
+	const domainContent = fs.readFileSync(domainPath, "utf-8");
+	const termMatches = [...domainContent.matchAll(/\b([A-Z][a-zA-Z0-9]+)\b/g)];
+	const termCount = new Set(termMatches.map((m) => m[1])).size;
+	const hasContexts = domainContent.includes("## Bounded Contexts");
+	const hasGlossary = domainContent.includes("## Ubiquitous Language");
+	domainSummary = `${hasContexts ? "✅" : "❌"} Bounded Contexts  ${hasGlossary ? "✅" : "❌"} Ubiquitous Language  📖 ~${termCount} terms`;
+}
+
+// TEST-STRATEGY health
+let testStrategySummary = "⚠️  .planning/TEST-STRATEGY.md not found";
+if (fs.existsSync(path.join(PLANNING, "TEST-STRATEGY.md"))) {
+	testStrategySummary = "✅ TEST-STRATEGY.md present";
+}
+
+// 3. Generate phase report
+const reportPath = path.join(PLANNING, `phase-${phaseNum}-report.md`);
+const report = `# Phase ${phaseNum} Execution Report
+
+Generated: ${new Date().toISOString().replace("T", " ").slice(0, 19)}
+
+## Task Results
+- ✅ Passed: ${passed}
+- ❌ Failed: ${failed}
+- ⏭️  Skipped: ${skipped}
+- ⚠️  Warnings: ${warnings}
+
+## Execution Log
+| Timestamp | Plan | Task | Status | Commit |
+|-----------|------|------|--------|--------|
+${entries.map((e) => `| ${e.timestamp.slice(0, 19)} | ${e.plan} | ${e.task} | ${e.status} | ${e.commit || "-"} |`).join("\n")}
+
+## Quality Gate
+${failed === 0 ? "✅ All tasks passed — ready for verification" : `❌ ${failed} failure(s) — fix plans may be needed`}
+${warnings > 0 ? `⚠️  ${warnings} task(s) introduced type errors` : "✅ No type errors introduced"}
+
+## TDD Health
+${tddSummary}
+${tddViolations > 0 ? `❌ ${tddViolations} TDD cycle violation(s) recorded (green: without red:)` : "✅ No TDD cycle violations recorded"}
+
+## Domain Model Health
+${domainSummary}
+${testStrategySummary}
+`;
+
+fs.writeFileSync(reportPath, report);
+console.log(`Phase ${phaseNum} report: ${reportPath}`);
+
+// 4. Update ROADMAP.md status
+const roadmapPath = path.join(PLANNING, "ROADMAP.md");
+if (fs.existsSync(roadmapPath)) {
+	let roadmap = fs.readFileSync(roadmapPath, "utf-8");
+	const newStatus = failed === 0 ? "complete" : "needs-fixes";
+	const regex = new RegExp(`(## Phase ${phaseNum}:.+?)— \`\\w+\``, "m");
+	roadmap = roadmap.replace(regex, `$1— \`${newStatus}\``);
+	fs.writeFileSync(roadmapPath, roadmap);
+	console.log(`ROADMAP.md: Phase ${phaseNum} → ${newStatus}`);
+}
+
+// 5. Summary
+console.log(`\n━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━`);
+console.log(` Draht ► PHASE ${phaseNum} ${failed === 0 ? "COMPLETE ✅" : "NEEDS FIXES ❌"}`);
+console.log(`━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━`);
+console.log(`\n${passed} passed, ${failed} failed, ${skipped} skipped`);
+if (failed === 0) {
+	console.log(`\nNext: gsd-verify-work ${phaseNum}`);
+} else {
+	console.log(`\nNext: gsd-execute-phase ${phaseNum} --gaps-only`);
+}

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

@@ -0,0 +1,132 @@
+#!/usr/bin/env node
+"use strict";
+
+/**
+ * Draht Post-Task Hook
+ * Runs after each task execution to validate and record results.
+ *
+ * Usage: node gsd-post-task.js <phase> <plan> <task-num> <status> [commit-hash]
+ * Status: pass | fail | skip
+ */
+
+const fs = require("node:fs");
+const path = require("node:path");
+const { execSync } = require("node:child_process");
+
+const [phaseNum, planNum, taskNum, status, commitHash] = process.argv.slice(2);
+if (!phaseNum || !planNum || !taskNum || !status) {
+	console.error("Usage: gsd-post-task.js <phase> <plan> <task-num> <status> [commit-hash]");
+	process.exit(1);
+}
+
+const PLANNING = ".planning";
+const LOG_FILE = path.join(PLANNING, "execution-log.jsonl");
+
+// 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}`);
+				fs.appendFileSync(LOG_FILE, JSON.stringify({
+					timestamp: new Date().toISOString(),
+					phase: parseInt(phaseNum, 10),
+					plan: parseInt(planNum, 10),
+					task: parseInt(taskNum, 10),
+					status: "tdd-violation",
+					warning: "green: commit without preceding red: commit",
+					commit: commitHash,
+				}) + "\n");
+			}
+		}
+	} catch {
+		// Not a git repo or commit not found — ignore
+	}
+}
+
+// 1. Append to execution log
+const entry = {
+	timestamp: new Date().toISOString(),
+	phase: parseInt(phaseNum, 10),
+	plan: parseInt(planNum, 10),
+	task: parseInt(taskNum, 10),
+	status,
+	commit: commitHash || null,
+};
+
+fs.appendFileSync(LOG_FILE, JSON.stringify(entry) + "\n");
+
+// 2. Run type check if status is pass
+if (status === "pass") {
+	try {
+		execSync("bun run tsgo --noEmit 2>&1", { timeout: 30000, encoding: "utf-8" });
+		// Run tests
+		try {
+			const testOutput = execSync("bun test 2>&1", { timeout: 60000, encoding: "utf-8" });
+			const testMatch = testOutput.match(/(\d+) pass/);
+			const testCount = testMatch ? testMatch[1] : "?";
+			console.log(`✅ Task ${phaseNum}-${planNum}-${taskNum}: passed + types clean + ${testCount} tests pass`);
+		} catch (testErr) {
+			const testOut = testErr.stdout || testErr.stderr || "";
+			const failMatch = testOut.match(/(\d+) fail/);
+			if (failMatch) {
+				console.log(`⚠️  Task ${phaseNum}-${planNum}-${taskNum}: passed + types clean but ${failMatch[1]} test(s) failed`);
+			} else {
+				console.log(`✅ Task ${phaseNum}-${planNum}-${taskNum}: passed + types clean (no test runner found)`);
+			}
+		}
+	} catch (error) {
+		const output = error.stdout || "";
+		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`,
+			}) + "\n");
+		} else {
+			console.log(`✅ Task ${phaseNum}-${planNum}-${taskNum}: passed`);
+		}
+	}
+} else if (status === "fail") {
+	console.log(`❌ Task ${phaseNum}-${planNum}-${taskNum}: FAILED`);
+
+	// Check if we should create a fix plan
+	const logContent = fs.readFileSync(LOG_FILE, "utf-8");
+	const taskFailures = logContent.split("\n")
+		.filter(Boolean)
+		.map((l) => JSON.parse(l))
+		.filter((e) => e.phase === parseInt(phaseNum, 10) && e.plan === parseInt(planNum, 10) && e.task === parseInt(taskNum, 10) && e.status === "fail");
+
+	if (taskFailures.length >= 3) {
+		console.log(`\n⚠️  Task has failed 3+ times. Consider creating a fix plan:`);
+		console.log(`   draht create-fix-plan ${phaseNum} ${planNum} "Task ${taskNum} failed repeatedly"`);
+	}
+} else {
+	console.log(`⏭️  Task ${phaseNum}-${planNum}-${taskNum}: skipped`);
+}
+
+// 3. Update STATE.md last activity
+const statePath = path.join(PLANNING, "STATE.md");
+if (fs.existsSync(statePath)) {
+	let state = fs.readFileSync(statePath, "utf-8");
+	state = state.replace(
+		/## Last Activity:.*/,
+		`## Last Activity: ${new Date().toISOString().replace("T", " ").slice(0, 19)}`
+	);
+	fs.writeFileSync(statePath, state);
+}