gsd-pi 2.41.0-dev.0acbce9 → 2.41.0-dev.5a170d0

package/src/resources/extensions/gsd/tests/worktree-symlink-removal.test.ts

@@ -0,0 +1,140 @@
+/**
+ * Regression test for #1852: removeWorktree targets wrong path when .gsd/ is a symlink.
+ *
+ * When .gsd/ is a symlink to an external state directory, git registers
+ * the worktree at the resolved (real) path. But removeWorktree recomputes
+ * the path via worktreePath() which uses the unresolved symlink, causing
+ * a mismatch — the removal silently fails.
+ *
+ * Fix: removeWorktree should query `git worktree list` to find the actual
+ * registered path when the computed path doesn't match.
+ */
+import { mkdtempSync, mkdirSync, rmSync, symlinkSync, unlinkSync, writeFileSync, existsSync, realpathSync } from "node:fs";
+import { join } from "node:path";
+import { tmpdir } from "node:os";
+import { execSync } from "node:child_process";
+
+import {
+  createWorktree,
+  removeWorktree,
+  listWorktrees,
+  worktreePath,
+} from "../worktree-manager.ts";
+import { createTestContext } from './test-helpers.ts';
+
+const { assertEq, assertTrue, report } = createTestContext();
+
+function run(command: string, cwd: string): string {
+  return execSync(command, { cwd, stdio: ["ignore", "pipe", "pipe"], encoding: "utf-8" }).trim();
+}
+
+// Set up a test repo with .gsd/ as a symlink to an external directory,
+// mimicking the external state directory layout (~/.gsd/projects/<hash>/).
+// Resolve tmpdir to handle macOS /tmp -> /private/var/... symlink.
+const realTmp = realpathSync(tmpdir());
+const base = mkdtempSync(join(realTmp, "gsd-wt-symlink-test-"));
+const externalState = mkdtempSync(join(realTmp, "gsd-wt-symlink-ext-"));
+
+run("git init -b main", base);
+run('git config user.name "Test"', base);
+run('git config user.email "test@example.com"', base);
+
+// Create external state directory structure
+mkdirSync(join(externalState, "worktrees"), { recursive: true });
+
+// Create .gsd as a symlink to the external state directory
+symlinkSync(externalState, join(base, ".gsd"));
+
+// Verify the symlink is in place
+assertTrue(existsSync(join(base, ".gsd")), ".gsd symlink exists");
+assertTrue(
+  realpathSync(join(base, ".gsd")) === externalState,
+  ".gsd resolves to external state dir",
+);
+
+// Create initial commit so we have a valid repo
+writeFileSync(join(base, "README.md"), "# Test\n", "utf-8");
+run("git add .", base);
+run('git commit -m "init"', base);
+
+async function main(): Promise<void> {
+  console.log("\n=== #1852: removeWorktree with symlinked .gsd/ ===");
+
+  // Create a worktree — git will resolve the symlink and register
+  // the worktree at the external path
+  const info = createWorktree(base, "M002", { branch: "milestone/M002" });
+  assertTrue(info.exists, "worktree created");
+
+  // Verify worktree was created at the resolved (external) path
+  const realWtPath = realpathSync(info.path);
+  assertTrue(
+    realWtPath.startsWith(externalState),
+    `worktree real path (${realWtPath}) is under external state dir`,
+  );
+
+  // Verify git registered the worktree
+  const gitList = run("git worktree list", base);
+  assertTrue(gitList.includes("M002"), "git worktree list shows M002");
+
+  // The computed path via worktreePath uses the symlink path
+  const computedPath = worktreePath(base, "M002");
+  assertTrue(existsSync(computedPath), "computed path exists (via symlink)");
+
+  // Simulate what syncStateToProjectRoot does: replace the .gsd symlink with
+  // a real directory containing stale worktree data. This causes worktreePath()
+  // to compute a LOCAL path that differs from git's REGISTERED path (the
+  // resolved external path). The stale local dir passes existsSync but is not
+  // a real git worktree, so nativeWorktreeRemove fails silently.
+  unlinkSync(join(base, ".gsd"));  // remove the symlink
+  mkdirSync(join(base, ".gsd", "worktrees", "M002"), { recursive: true });
+  // Write a dummy file so the stale directory is non-empty
+  writeFileSync(join(base, ".gsd", "worktrees", "M002", "stale.txt"), "stale sync artifact", "utf-8");
+
+  // Now worktreePath(base, "M002") points to the LOCAL stale dir, not the
+  // external path where git actually registered the worktree.
+  const stalePath = worktreePath(base, "M002");
+  assertTrue(existsSync(stalePath), "stale local worktree dir exists");
+  assertTrue(
+    stalePath !== realWtPath,
+    `computed path (${stalePath}) differs from git-registered path (${realWtPath})`,
+  );
+
+  // THE ACTUAL TEST: removeWorktree must find the git-registered path and
+  // remove the real worktree, not just operate on the stale local directory.
+  removeWorktree(base, "M002", { branch: "milestone/M002", deleteBranch: true });
+
+  // After removal, the worktree should be gone from git's list
+  const gitListAfter = run("git worktree list", base);
+  assertTrue(
+    !gitListAfter.includes("M002"),
+    "worktree removed from git worktree list after removeWorktree",
+  );
+
+  // The branch should be deleted
+  const branches = run("git branch", base);
+  assertTrue(
+    !branches.includes("milestone/M002"),
+    "milestone/M002 branch deleted after removeWorktree",
+  );
+
+  // The worktree directory should be gone
+  assertTrue(
+    !existsSync(realWtPath),
+    "worktree directory removed from disk",
+  );
+
+  // List should be empty
+  const listed = listWorktrees(base);
+  assertEq(listed.length, 0, "no worktrees listed after removal");
+
+  // Cleanup
+  rmSync(base, { recursive: true, force: true });
+  rmSync(externalState, { recursive: true, force: true });
+
+  report();
+}
+
+main().catch((error) => {
+  console.error(error);
+  process.exit(1);
+});

package/src/resources/extensions/gsd/tests/worktree-sync-milestones.test.ts

@@ -19,6 +19,8 @@
  *   - syncWorktreeStateBack syncs root-level .gsd/ files (REQUIREMENTS, PROJECT, etc.)
  *   - syncWorktreeStateBack syncs ALL milestone directories, not just the current one
  *   - syncWorktreeStateBack handles next-milestone artifacts created during completion
+ *   - syncGsdStateToWorktree syncs non-standard milestone dir names (#1547)
+ *   - syncWorktreeStateBack syncs non-standard milestone dir names (#1547)
  */
 
 import { mkdtempSync, mkdirSync, writeFileSync, rmSync, existsSync, readFileSync } from 'node:fs';
@@ -517,6 +519,78 @@ async function main(): Promise<void> {
     }
   }
 
+  // ─── 14. syncGsdStateToWorktree syncs non-standard milestone dir names (#1547) ──
+  console.log('\n=== 14. syncGsdStateToWorktree syncs non-standard milestone dir names (#1547) ===');
+  {
+    const mainBase = createBase('main');
+    const wtBase = createBase('wt');
+
+    try {
+      // Main has milestone dirs with non-standard names
+      const customDir = join(mainBase, '.gsd', 'milestones', 'sprint-alpha');
+      mkdirSync(customDir, { recursive: true });
+      writeFileSync(join(customDir, 'CONTEXT.md'), '# Sprint Alpha Context');
+
+      const suffixDir = join(mainBase, '.gsd', 'milestones', 'M001-abc123');
+      mkdirSync(suffixDir, { recursive: true });
+      writeFileSync(join(suffixDir, 'M001-abc123-CONTEXT.md'), '# M001 Context');
+
+      assertTrue(!existsSync(join(wtBase, '.gsd', 'milestones', 'sprint-alpha')), 'sprint-alpha missing before sync');
+      assertTrue(!existsSync(join(wtBase, '.gsd', 'milestones', 'M001-abc123')), 'M001-abc123 missing before sync');
+
+      const result = syncGsdStateToWorktree(mainBase, wtBase);
+
+      assertTrue(
+        existsSync(join(wtBase, '.gsd', 'milestones', 'sprint-alpha', 'CONTEXT.md')),
+        '#1547: non-standard milestone dir "sprint-alpha" synced to worktree',
+      );
+      assertTrue(
+        existsSync(join(wtBase, '.gsd', 'milestones', 'M001-abc123', 'M001-abc123-CONTEXT.md')),
+        '#1547: suffixed milestone dir "M001-abc123" synced to worktree',
+      );
+      assertTrue(result.synced.length > 0, 'sync reported files');
+    } finally {
+      cleanup(mainBase);
+      cleanup(wtBase);
+    }
+  }
+
+  // ─── 15. syncWorktreeStateBack syncs non-standard milestone dir names (#1547) ──
+  console.log('\n=== 15. syncWorktreeStateBack syncs non-standard milestone dir names (#1547) ===');
+  {
+    const mainBase = mkdtempSync(join(tmpdir(), 'gsd-wt-back-custom-main-'));
+    const wtBase = mkdtempSync(join(tmpdir(), 'gsd-wt-back-custom-wt-'));
+
+    try {
+      mkdirSync(join(mainBase, '.gsd', 'milestones'), { recursive: true });
+      mkdirSync(join(wtBase, '.gsd', 'milestones'), { recursive: true });
+
+      // Worktree has a non-standard milestone dir
+      const wtCustomDir = join(wtBase, '.gsd', 'milestones', 'sprint-beta');
+      mkdirSync(wtCustomDir, { recursive: true });
+      writeFileSync(join(wtCustomDir, 'SUMMARY.md'), '# Sprint Beta Summary');
+
+      assertTrue(
+        !existsSync(join(mainBase, '.gsd', 'milestones', 'sprint-beta')),
+        'sprint-beta missing in main before sync',
+      );
+
+      const { synced } = syncWorktreeStateBack(mainBase, wtBase, 'M001');
+
+      assertTrue(
+        existsSync(join(mainBase, '.gsd', 'milestones', 'sprint-beta', 'SUMMARY.md')),
+        '#1547: non-standard milestone dir "sprint-beta" synced back to main',
+      );
+      assertTrue(
+        synced.some((p) => p.includes('sprint-beta')),
+        '#1547: sprint-beta appears in synced list',
+      );
+    } finally {
+      rmSync(mainBase, { recursive: true, force: true });
+      rmSync(wtBase, { recursive: true, force: true });
+    }
+  }
+
   report();
 }
 

package/src/resources/extensions/gsd/types.ts

@@ -404,6 +404,8 @@ export interface HookStatusEntry {
 
 // ─── Database Types (Decisions & Requirements) ────────────────────────────
 
+export type DecisionMadeBy = "human" | "agent" | "collaborative";
+
 export interface Decision {
   seq: number; // auto-increment primary key
   id: string; // e.g. "D001"
@@ -413,6 +415,7 @@ export interface Decision {
   choice: string; // the specific choice made
   rationale: string; // why this choice
   revisable: string; // whether/when revisable
+  made_by: DecisionMadeBy; // who made the decision: human, agent, or collaborative
   superseded_by: string | null; // ID of superseding decision, or null
 }
 

package/src/resources/extensions/gsd/workflow-engine.ts

@@ -0,0 +1,38 @@
+/**
+ * workflow-engine.ts — WorkflowEngine interface.
+ *
+ * Defines the contract every engine implementation must satisfy.
+ * Imports only from the leaf-node engine-types.
+ */
+
+import type {
+  EngineState,
+  EngineDispatchAction,
+  CompletedStep,
+  ReconcileResult,
+  DisplayMetadata,
+} from "./engine-types.js";
+
+/** A pluggable workflow engine that drives the auto-loop. */
+export interface WorkflowEngine {
+  /** Unique identifier for this engine (e.g. "dev", "custom"). */
+  readonly engineId: string;
+
+  /** Derive the current engine state from the project on disk. */
+  deriveState(basePath: string): Promise<EngineState>;
+
+  /** Decide what the loop should do next given current state. */
+  resolveDispatch(
+    state: EngineState,
+    context: { basePath: string },
+  ): Promise<EngineDispatchAction>;
+
+  /** Reconcile state after a step has been executed. */
+  reconcile(
+    state: EngineState,
+    completedStep: CompletedStep,
+  ): Promise<ReconcileResult>;
+
+  /** Return UI-facing metadata for progress display. */
+  getDisplayMetadata(state: EngineState): DisplayMetadata;
+}

package/src/resources/extensions/gsd/workflow-templates.ts

@@ -8,10 +8,21 @@
 import { readFileSync, existsSync } from "node:fs";
 import { join, dirname } from "node:path";
 import { fileURLToPath } from "node:url";
+import { homedir } from "node:os";
 
-const __extensionDir = dirname(fileURLToPath(import.meta.url));
+const __extensionDir = resolveGsdExtensionDir();
 const registryPath = join(__extensionDir, "workflow-templates", "registry.json");
 
+/** Resolve the GSD extension dir with fallback to ~/.gsd/agent/extensions/gsd/. */
+function resolveGsdExtensionDir(): string {
+  const moduleDir = dirname(fileURLToPath(import.meta.url));
+  if (existsSync(join(moduleDir, "workflow-templates"))) return moduleDir;
+  const gsdHome = process.env.GSD_HOME || join(homedir(), ".gsd");
+  const agentGsdDir = join(gsdHome, "agent", "extensions", "gsd");
+  if (existsSync(join(agentGsdDir, "workflow-templates"))) return agentGsdDir;
+  return moduleDir;
+}
+
 // ─── Types ───────────────────────────────────────────────────────────────────
 
 export interface TemplateEntry {

package/src/resources/extensions/gsd/worktree-manager.ts

@@ -286,11 +286,26 @@ export function removeWorktree(
   name: string,
   opts: { deleteBranch?: boolean; force?: boolean; branch?: string } = {},
 ): void {
-  const wtPath = worktreePath(basePath, name);
-  const resolvedWtPath = existsSync(wtPath) ? realpathSync(wtPath) : wtPath;
+  let wtPath = worktreePath(basePath, name);
   const branch = opts.branch ?? worktreeBranchName(name);
   const { deleteBranch = true, force = true } = opts;
 
+  // Resolve the ACTUAL worktree path from git's worktree list.
+  // The computed path may differ when .gsd/ is (or was) a symlink to an
+  // external state directory — git resolves symlinks at worktree creation
+  // time, so its registered path points to the resolved external location.
+  // If syncStateToProjectRoot later creates a real .gsd/ directory that
+  // shadows the symlink, the computed path diverges from git's record.
+  try {
+    const entries = nativeWorktreeList(basePath);
+    const entry = entries.find(e => e.branch === branch);
+    if (entry?.path) {
+      wtPath = entry.path;
+    }
+  } catch { /* fall back to computed path */ }
+
+  const resolvedWtPath = existsSync(wtPath) ? realpathSync(wtPath) : wtPath;
+
   // If we're inside the worktree, move out first — git can't remove an in-use directory
   const cwd = process.cwd();
   const resolvedCwd = existsSync(cwd) ? realpathSync(cwd) : cwd;
@@ -306,12 +321,12 @@ export function removeWorktree(
     return;
   }
 
-  // Remove worktree (force if requested, to handle dirty worktrees)
-  try { nativeWorktreeRemove(basePath, wtPath, force); } catch { /* may fail */ }
+  // Remove worktree using the resolved path (force if requested, to handle dirty worktrees)
+  try { nativeWorktreeRemove(basePath, resolvedWtPath, force); } catch { /* may fail */ }
 
   // If the directory is still there (e.g. locked), try harder with force
-  if (existsSync(wtPath)) {
-    try { nativeWorktreeRemove(basePath, wtPath, true); } catch { /* may fail */ }
+  if (existsSync(resolvedWtPath)) {
+    try { nativeWorktreeRemove(basePath, resolvedWtPath, true); } catch { /* may fail */ }
   }
 
   // Prune stale entries so git knows the worktree is gone

package/src/resources/extensions/gsd/worktree-resolver.ts

@@ -28,7 +28,7 @@ export interface WorktreeResolverDeps {
     basePath: string,
     milestoneId: string,
     roadmapContent: string,
-  ) => { pushed: boolean };
+  ) => { pushed: boolean; codeFilesChanged: boolean };
   syncWorktreeStateBack: (
     mainBasePath: string,
     worktreePath: string,
@@ -371,10 +371,23 @@ export class WorktreeResolver {
           milestoneId,
           roadmapContent,
         );
-        ctx.notify(
-          `Milestone ${milestoneId} merged to main.${mergeResult.pushed ? " Pushed to remote." : ""}`,
-          "info",
-        );
+        if (mergeResult.codeFilesChanged) {
+          ctx.notify(
+            `Milestone ${milestoneId} merged to main.${mergeResult.pushed ? " Pushed to remote." : ""}`,
+            "info",
+          );
+        } else {
+          // (#1906) Milestone produced only .gsd/ metadata — no actual code was
+          // merged. This typically means the LLM wrote planning artifacts
+          // (summaries, roadmaps) but never implemented the code. Surface this
+          // clearly so the user knows the milestone is not truly complete.
+          ctx.notify(
+            `WARNING: Milestone ${milestoneId} merged to main but contained NO code changes — only .gsd/ metadata files. ` +
+              `The milestone summary may describe planned work that was never implemented. ` +
+              `Review the milestone output and re-run if code is missing.`,
+            "warning",
+          );
+        }
       } else {
         // No roadmap at either location — teardown but PRESERVE the branch so
         // commits are not orphaned. The user can merge manually later (#1573).
@@ -478,10 +491,18 @@ export class WorktreeResolver {
       // Rebuild GitService after merge (branch HEAD changed)
       this.rebuildGitService();
 
-      ctx.notify(
-        `Milestone ${milestoneId} merged (branch mode).${mergeResult.pushed ? " Pushed to remote." : ""}`,
-        "info",
-      );
+      if (mergeResult.codeFilesChanged) {
+        ctx.notify(
+          `Milestone ${milestoneId} merged (branch mode).${mergeResult.pushed ? " Pushed to remote." : ""}`,
+          "info",
+        );
+      } else {
+        ctx.notify(
+          `WARNING: Milestone ${milestoneId} merged (branch mode) but contained NO code changes — only .gsd/ metadata. ` +
+            `Review the milestone output and re-run if code is missing.`,
+          "warning",
+        );
+      }
       debugLog("WorktreeResolver", {
         action: "mergeAndExit",
         milestoneId,

package/src/resources/extensions/subagent/index.ts

@@ -516,12 +516,16 @@ async function runSingleAgentInCmuxSplit(
 		const bundledPaths = (process.env.GSD_BUNDLED_EXTENSION_PATHS ?? "").split(path.delimiter).map((s) => s.trim()).filter(Boolean);
 		const extensionArgs = bundledPaths.flatMap((p) => ["--extension", p]);
 		const processArgs = [process.env.GSD_BIN_PATH!, ...extensionArgs, ...buildSubagentProcessArgs(agent, task, tmpPromptPath)];
+		// Normalize all paths to forward slashes before embedding in bash strings.
+		// On Windows, backslashes are interpreted as escape characters by bash,
+		// mangling paths like C:\Users\user into C:Useruser (#1436).
+		const bashPath = (p: string) => shellEscape(p.replaceAll("\\", "/"));
 		const innerScript = [
-			`cd ${shellEscape(cwd ?? defaultCwd)}`,
+			`cd ${bashPath(cwd ?? defaultCwd)}`,
 			"set -o pipefail",
-			`${shellEscape(process.execPath)} ${processArgs.map(shellEscape).join(" ")} 2> >(tee ${shellEscape(stderrPath)} >&2) | tee ${shellEscape(stdoutPath)}`,
+			`${bashPath(process.execPath)} ${processArgs.map(a => bashPath(a)).join(" ")} 2> >(tee ${bashPath(stderrPath)} >&2) | tee ${bashPath(stdoutPath)}`,
 			"status=${PIPESTATUS[0]}",
-			`printf '%s' "$status" > ${shellEscape(exitPath)}`,
+			`printf '%s' "$status" > ${bashPath(exitPath)}`,
 		].join("; ");
 
 		const sent = await cmuxClient.sendSurface(cmuxSurfaceId, `bash -lc ${shellEscape(innerScript)}`);

package/src/resources/extensions/voice/index.ts

@@ -2,7 +2,7 @@ import type { ExtensionAPI, ExtensionContext } from "@gsd/pi-coding-agent";
 import { shortcutDesc } from "../shared/mod.js";
 import type { AssistantMessage } from "@gsd/pi-ai";
 import { isKeyRelease, Key, matchesKey, truncateToWidth, visibleWidth } from "@gsd/pi-tui";
-import { spawn, execSync, type ChildProcess } from "node:child_process";
+import { spawn, execFileSync, type ChildProcess } from "node:child_process";
 import * as fs from "node:fs";
 import * as os from "node:os";
 import * as path from "node:path";
@@ -32,7 +32,7 @@ function linuxPython(): string {
 function ensureBinary(): boolean {
 	if (fs.existsSync(RECOGNIZER_BIN)) return true;
 	try {
-		execSync(`swiftc "${SWIFT_SRC}" -o "${RECOGNIZER_BIN}" -framework Speech -framework AVFoundation`, {
+		execFileSync("swiftc", [SWIFT_SRC, "-o", RECOGNIZER_BIN, "-framework", "Speech", "-framework", "AVFoundation"], {
 			timeout: 60000,
 		});
 		return true;
@@ -54,7 +54,7 @@ function ensureLinuxReady(ctx: ExtensionContext): boolean {
 
 	// Check python3 exists
 	try {
-		execSync("which python3", { stdio: "pipe" });
+		execFileSync("which", ["python3"], { stdio: "pipe" });
 	} catch {
 		ctx.ui.notify("Voice: python3 not found — install with: sudo apt install python3", "error");
 		return false;
@@ -63,7 +63,7 @@ function ensureLinuxReady(ctx: ExtensionContext): boolean {
 	// Check that sounddevice is importable
 	const py = linuxPython();
 	try {
-		execSync(`${py} -c "import sounddevice"`, {
+		execFileSync(py, ["-c", "import sounddevice"], {
 			stdio: "pipe",
 			timeout: 10000,
 		});

package/src/resources/skills/create-workflow/SKILL.md

@@ -0,0 +1,103 @@
+---
+name: create-workflow
+description: Conversational guide for creating valid YAML workflow definitions. Use when asked to "create a workflow", "new workflow definition", "build a workflow", "workflow YAML", "define workflow steps", or "workflow from template".
+---
+
+<essential_principles>
+You are a workflow definition author. You help users create valid V1 YAML workflow definitions that the GSD workflow engine can execute.
+
+**V1 Schema Basics:**
+
+- Every definition requires `version: 1`, a non-empty `name`, and at least one step in `steps[]`.
+- Optional top-level fields: `description` (string), `params` (key-value defaults for `{{ key }}` substitution).
+- Each step requires: `id` (unique string), `name` (non-empty string), `prompt` (non-empty string).
+- Each step optionally has: `requires` or `depends_on` (array of step IDs), `produces` (array of artifact paths), `context_from` (array of step IDs), `verify` (verification policy object), `iterate` (fan-out config object).
+- YAML uses **snake_case** keys: `depends_on`, `context_from`. The engine converts to camelCase internally.
+
+**Validation Rules:**
+
+- Step IDs must be unique across the workflow.
+- Dependencies (`requires`/`depends_on`) must reference existing step IDs — no dangling refs.
+- A step cannot depend on itself.
+- The dependency graph must be acyclic (no circular dependencies).
+- `produces` paths must not contain `..` (path traversal rejected).
+- `iterate.source` must not contain `..` (path traversal rejected).
+- `iterate.pattern` must be a valid regex with at least one capture group.
+
+**Four Verification Policies:**
+
+1. `content-heuristic` — Checks artifact content. Optional: `minSize` (number), `pattern` (string).
+2. `shell-command` — Runs a shell command. Required: `command` (non-empty string).
+3. `prompt-verify` — Asks an LLM to verify. Required: `prompt` (non-empty string).
+4. `human-review` — Pauses for human approval. No extra fields required.
+
+**Parameter Substitution:**
+
+- Define defaults in top-level `params: { key: "default_value" }`.
+- Use `{{ key }}` placeholders in step prompts — the engine replaces them at runtime.
+- CLI overrides take precedence over definition defaults.
+- Parameter values must not contain `..` (path traversal guard).
+- Any unresolved `{{ key }}` after substitution causes an error.
+
+**Path Traversal Guard:**
+
+- The engine rejects any `produces` path or `iterate.source` containing `..`.
+- Parameter values are also checked for `..` during substitution.
+
+**Output Location:**
+
+- Finished definitions go in `.gsd/workflow-defs/<name>.yaml`.
+- After writing, tell the user to validate with `/gsd workflow validate <name>`.
+</essential_principles>
+
+<routing>
+Determine the user's intent and route to the appropriate workflow:
+
+**"I want to create a workflow from scratch" / "new workflow" / "build a workflow":**
+→ Read `workflows/create-from-scratch.md` and follow it.
+
+**"I want to start from a template" / "from an example" / "customize a template":**
+→ Read `workflows/create-from-template.md` and follow it.
+
+**"Help me understand the schema" / "what fields are available?":**
+→ Read `references/yaml-schema-v1.md` and explain the relevant parts.
+
+**"How does verification work?" / "verify policies":**
+→ Read `references/verification-policies.md` and explain.
+
+**"How do I use context_from / iterate / params?":**
+→ Read `references/feature-patterns.md` and explain the relevant feature.
+
+**If intent is unclear, ask one clarifying question:**
+- "Do you want to create a workflow from scratch, or start from an existing template?"
+- Then route based on the answer.
+</routing>
+
+<reference_index>
+Read these files when you need detailed schema knowledge during workflow authoring:
+
+- `references/yaml-schema-v1.md` — Complete field-by-field V1 schema reference. Read when you need to explain any field's type, constraints, or defaults.
+- `references/verification-policies.md` — All four verify policies with complete YAML examples. Read when helping the user choose or configure verification for a step.
+- `references/feature-patterns.md` — Usage patterns for `context_from`, `iterate`, and `params` with complete YAML examples. Read when the user wants context chaining, fan-out iteration, or parameterized workflows.
+</reference_index>
+
+<templates_index>
+Available templates in `templates/`:
+
+- `workflow-definition.yaml` — Blank scaffold with all fields shown as comments. Copy and fill for a quick start.
+- `blog-post-pipeline.yaml` — Linear chain with params and content-heuristic verification.
+- `code-audit.yaml` — Iterate-based fan-out with shell-command verification.
+- `release-checklist.yaml` — Diamond dependency graph with human-review verification.
+</templates_index>
+
+<output_conventions>
+When assembling the final YAML:
+
+1. Use 2-space indentation consistently.
+2. Quote string values that contain special YAML characters (`:`, `{`, `}`, `[`, `]`, `#`).
+3. Always include `version: 1` as the first field.
+4. Order top-level fields: `version`, `name`, `description`, `params`, `steps`.
+5. Order step fields: `id`, `name`, `prompt`, `requires`, `produces`, `context_from`, `verify`, `iterate`.
+6. Write the file to `.gsd/workflow-defs/<name>.yaml`.
+7. After writing, tell the user: "Run `/gsd workflow validate <name>` to check the definition."
+</output_conventions>