gsd-pi 2.41.0 → 2.42.0-dev.1df898f

package/dist/resources/extensions/gsd/service-tier.js

@@ -0,0 +1,147 @@
+/**
+ * Service Tier — gating, status formatting, icon resolution, and
+ * the /gsd fast command handler.
+ *
+ * Service tiers (priority/flex) are an OpenAI feature that only applies
+ * to gpt-5.4 variants. This module centralizes the model-gating logic
+ * so that icons, preferences, and the before_provider_request hook all
+ * use a single source of truth.
+ */
+import { existsSync, readFileSync } from "node:fs";
+import { saveFile } from "./files.js";
+import { getGlobalGSDPreferencesPath, loadEffectiveGSDPreferences, loadGlobalGSDPreferences, } from "./preferences.js";
+import { ensurePreferencesFile, serializePreferencesToFrontmatter } from "./commands-prefs-wizard.js";
+const SERVICE_TIER_SCOPE_NOTE = "Only affects gpt-5.4 models, regardless of provider.";
+// ─── Gating ──────────────────────────────────────────────────────────────────
+/**
+ * Returns true when the given model ID supports OpenAI service tiers.
+ * Currently only gpt-5.4 variants qualify.
+ */
+export function supportsServiceTier(modelId) {
+    if (!modelId)
+        return false;
+    // Strip provider prefix if present (e.g. "openai/gpt-5.4" → "gpt-5.4")
+    const bare = modelId.includes("/") ? modelId.split("/").pop() : modelId;
+    return bare.startsWith("gpt-5.4");
+}
+// ─── Status Formatting ───────────────────────────────────────────────────────
+/**
+ * Human-readable description of the current service tier setting.
+ */
+export function formatServiceTierStatus(tier) {
+    if (!tier) {
+        return [
+            "Service tier: disabled",
+            "",
+            "Usage:",
+            "  /gsd fast on     Set to priority (2x cost, faster)",
+            "  /gsd fast flex   Set to flex (0.5x cost, slower)",
+            "  /gsd fast off    Disable service tier",
+            "",
+            SERVICE_TIER_SCOPE_NOTE,
+        ].join("\n");
+    }
+    const label = tier === "priority" ? "priority (2x cost, faster)" : "flex (0.5x cost, slower)";
+    return [
+        `Service tier: ${label}`,
+        "",
+        "Usage:",
+        "  /gsd fast on     Set to priority (2x cost, faster)",
+        "  /gsd fast flex   Set to flex (0.5x cost, slower)",
+        "  /gsd fast off    Disable service tier",
+        "",
+        SERVICE_TIER_SCOPE_NOTE,
+    ].join("\n");
+}
+export function formatServiceTierFooterStatus(tier, modelId) {
+    if (!tier || !modelId || !supportsServiceTier(modelId))
+        return undefined;
+    return tier === "priority" ? "fast: ⚡ priority" : "fast: 💰 flex";
+}
+// ─── Icon Resolution ─────────────────────────────────────────────────────────
+/**
+ * Returns the appropriate icon for the active service tier and model.
+ * Returns empty string when the tier is inactive or the model doesn't
+ * support service tiers.
+ */
+export function resolveServiceTierIcon(tier, modelId) {
+    if (!tier || !supportsServiceTier(modelId))
+        return "";
+    return tier === "priority" ? "⚡" : "💰";
+}
+// ─── Preference Read ─────────────────────────────────────────────────────────
+/**
+ * Read the effective service_tier setting from preferences.
+ */
+export function getEffectiveServiceTier() {
+    const prefs = loadEffectiveGSDPreferences()?.preferences;
+    const raw = prefs?.service_tier;
+    if (raw === "priority" || raw === "flex")
+        return raw;
+    return undefined;
+}
+// ─── Preference Write ────────────────────────────────────────────────────────
+function extractBodyAfterFrontmatter(content) {
+    const start = content.startsWith("---\n") ? 4 : content.startsWith("---\r\n") ? 5 : -1;
+    if (start === -1)
+        return null;
+    const closingIdx = content.indexOf("\n---", start);
+    if (closingIdx === -1)
+        return null;
+    const after = content.slice(closingIdx + 4);
+    return after.trim() ? after : null;
+}
+async function writeGlobalServiceTier(ctx, tier) {
+    const path = getGlobalGSDPreferencesPath();
+    await ensurePreferencesFile(path, ctx, "global");
+    const existing = loadGlobalGSDPreferences();
+    const prefs = existing?.preferences ? { ...existing.preferences } : {};
+    prefs.version = prefs.version || 1;
+    if (tier) {
+        prefs.service_tier = tier;
+    }
+    else {
+        delete prefs.service_tier;
+    }
+    const frontmatter = serializePreferencesToFrontmatter(prefs);
+    let body = "\n# GSD Skill Preferences\n\nSee `~/.gsd/agent/extensions/gsd/docs/preferences-reference.md` for full field documentation and examples.\n";
+    if (existsSync(path)) {
+        const preserved = extractBodyAfterFrontmatter(readFileSync(path, "utf-8"));
+        if (preserved)
+            body = preserved;
+    }
+    await saveFile(path, `---\n${frontmatter}---${body}`);
+    await ctx.waitForIdle();
+    await ctx.reload();
+}
+// ─── Command Handler ─────────────────────────────────────────────────────────
+/**
+ * Handle `/gsd fast [on|off|flex|status]`.
+ */
+export async function handleFast(args, ctx) {
+    const trimmed = args.trim().toLowerCase();
+    if (!trimmed || trimmed === "status") {
+        const tier = getEffectiveServiceTier();
+        ctx.ui.notify(formatServiceTierStatus(tier), "info");
+        return;
+    }
+    if (trimmed === "on") {
+        await writeGlobalServiceTier(ctx, "priority");
+        ctx.ui.setStatus("gsd-fast", formatServiceTierFooterStatus("priority", ctx.model?.id));
+        ctx.ui.notify("Service tier set to priority (2x cost, faster responses). Only affects gpt-5.4 models, regardless of provider.", "info");
+        return;
+    }
+    if (trimmed === "off") {
+        await writeGlobalServiceTier(ctx, undefined);
+        ctx.ui.setStatus("gsd-fast", undefined);
+        ctx.ui.notify("Service tier disabled.", "info");
+        return;
+    }
+    if (trimmed === "flex") {
+        await writeGlobalServiceTier(ctx, "flex");
+        ctx.ui.setStatus("gsd-fast", formatServiceTierFooterStatus("flex", ctx.model?.id));
+        ctx.ui.notify("Service tier set to flex (0.5x cost, slower responses). Only affects gpt-5.4 models, regardless of provider.", "info");
+        return;
+    }
+    ctx.ui.notify("Usage: /gsd fast [on|off|flex|status]\n\n  on    Priority tier (2x cost, faster)\n  off   Disable service tier\n  flex  Flex tier (0.5x cost, slower)\n  status Show current setting", "warning");
+}

package/dist/resources/extensions/gsd/session-lock.js

@@ -199,7 +199,7 @@ export function acquireSessionLock(basePath) {
                 // during a long LLM call — not a real takeover. Log and continue.
                 const elapsed = Date.now() - _lockAcquiredAt;
                 if (elapsed < 1_800_000) {
-                    process.stderr.write(`[gsd] Lock heartbeat mismatch after ${Math.round(elapsed / 1000)}s — event loop stall, continuing.\n`);
+                    process.stderr.write(`[gsd] Lock heartbeat caught up after ${Math.round(elapsed / 1000)}s — long LLM call, no action needed.\n`);
                     return; // Suppress false positive
                 }
                 // Past the stale window — check if the lock file still belongs to us before
@@ -252,7 +252,7 @@ export function acquireSessionLock(basePath) {
                         // on benign mtime drift (laptop sleep, heavy LLM event loop stalls).
                         const elapsed = Date.now() - _lockAcquiredAt;
                         if (elapsed < 1_800_000) {
-                            process.stderr.write(`[gsd] Lock heartbeat mismatch after ${Math.round(elapsed / 1000)}s — event loop stall, continuing.\n`);
+                            process.stderr.write(`[gsd] Lock heartbeat caught up after ${Math.round(elapsed / 1000)}s — long LLM call, no action needed.\n`);
                             return;
                         }
                         // Check PID ownership before declaring compromise (#1578)

package/dist/resources/extensions/gsd/structured-data-formatter.js

@@ -25,6 +25,7 @@ export function formatDecisionCompact(decision) {
         decision.choice,
         decision.rationale,
         decision.revisable,
+        decision.made_by ?? 'agent',
     ].join(" | ");
 }
 /** Format multiple decisions in compact notation with a Fields header. */
@@ -32,7 +33,7 @@ export function formatDecisionsCompact(decisions) {
     if (decisions.length === 0) {
         return "# Decisions (compact)\n(none)";
     }
-    const header = "# Decisions (compact)\nFields: id | when | scope | decision | choice | rationale | revisable";
+    const header = "# Decisions (compact)\nFields: id | when | scope | decision | choice | rationale | revisable | made_by";
     const lines = decisions.map(formatDecisionCompact);
     return `${header}\n\n${lines.join("\n")}`;
 }

package/dist/resources/extensions/gsd/templates/decisions.md

@@ -4,5 +4,5 @@
      To reverse a decision, add a new row that supersedes it.
      Read this file at the start of any planning or research phase. -->
 
-| # | When | Scope | Decision | Choice | Rationale | Revisable? |
-|---|------|-------|----------|--------|-----------|------------|
+| # | When | Scope | Decision | Choice | Rationale | Revisable? | Made By |
+|---|------|-------|----------|--------|-----------|------------|---------|

package/dist/resources/extensions/gsd/workflow-engine.js

@@ -0,0 +1,7 @@
+/**
+ * workflow-engine.ts — WorkflowEngine interface.
+ *
+ * Defines the contract every engine implementation must satisfy.
+ * Imports only from the leaf-node engine-types.
+ */
+export {};

package/dist/resources/extensions/gsd/workflow-templates.js

@@ -7,8 +7,20 @@
 import { readFileSync, existsSync } from "node:fs";
 import { join, dirname } from "node:path";
 import { fileURLToPath } from "node:url";
-const __extensionDir = dirname(fileURLToPath(import.meta.url));
+import { homedir } from "node:os";
+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() {
+    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;
+}
 // ─── Registry Cache ──────────────────────────────────────────────────────────
 let cachedRegistry = null;
 /**

package/dist/resources/extensions/gsd/worktree-manager.js

@@ -206,10 +206,24 @@ export function listWorktrees(basePath) {
  * If the process is currently inside the worktree, chdir out first.
  */
 export function removeWorktree(basePath, name, opts = {}) {
-    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;
@@ -226,15 +240,15 @@ export function removeWorktree(basePath, name, opts = {}) {
         }
         return;
     }
-    // Remove worktree (force if requested, to handle dirty worktrees)
+    // Remove worktree using the resolved path (force if requested, to handle dirty worktrees)
     try {
-        nativeWorktreeRemove(basePath, wtPath, force);
+        nativeWorktreeRemove(basePath, resolvedWtPath, force);
     }
     catch { /* may fail */ }
     // If the directory is still there (e.g. locked), try harder with force
-    if (existsSync(wtPath)) {
+    if (existsSync(resolvedWtPath)) {
         try {
-            nativeWorktreeRemove(basePath, wtPath, true);
+            nativeWorktreeRemove(basePath, resolvedWtPath, true);
         }
         catch { /* may fail */ }
     }

package/dist/resources/extensions/gsd/worktree-resolver.js

@@ -253,7 +253,18 @@ export class WorktreeResolver {
             if (roadmapPath) {
                 const roadmapContent = this.deps.readFileSync(roadmapPath, "utf-8");
                 const mergeResult = this.deps.mergeMilestoneToMain(originalBase, 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
@@ -275,9 +286,9 @@ export class WorktreeResolver {
             });
             // Surface a clear, actionable error. The worktree and milestone branch are
             // intentionally preserved — nothing has been deleted. The user can retry
-            // /complete-milestone or merge manually once the underlying issue is fixed
+            // /gsd dispatch complete-milestone or merge manually once the underlying issue is fixed
             // (e.g. checkout to wrong branch, unresolved conflicts). (#1668)
-            ctx.notify(`Milestone merge failed: ${msg}. Your worktree and milestone branch are preserved — retry /complete-milestone or merge manually.`, "warning");
+            ctx.notify(`Milestone merge failed: ${msg}. Your worktree and milestone branch are preserved — retry /gsd dispatch complete-milestone or merge manually.`, "warning");
             // Clean up stale merge state left by failed squash-merge (#1389)
             try {
                 const gitDir = join(originalBase || this.s.basePath, ".git");
@@ -339,7 +350,13 @@ export class WorktreeResolver {
             const mergeResult = this.deps.mergeMilestoneToMain(this.s.basePath, milestoneId, roadmapContent);
             // 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/dist/resources/extensions/gsd/worktree.js

@@ -48,14 +48,14 @@ export function setActiveMilestoneId(basePath, milestoneId) {
  * record when the user starts from a different branch (#300). Always a no-op
  * if on a GSD slice branch.
  */
-export function captureIntegrationBranch(basePath, milestoneId, options) {
+export function captureIntegrationBranch(basePath, milestoneId) {
     // In a worktree, the base branch is implicit (worktree/<name>).
     // Writing it to META.json would leave stale metadata after merge back to main.
     if (detectWorktreeName(basePath))
         return;
     const svc = getService(basePath);
     const current = svc.getCurrentBranch();
-    writeIntegrationBranch(basePath, milestoneId, current, options);
+    writeIntegrationBranch(basePath, milestoneId, current);
 }
 // ─── Pure Utility Functions (unchanged) ────────────────────────────────────
 /**

package/dist/resources/extensions/mcp-client/index.js

@@ -108,7 +108,8 @@ async function getOrConnect(name, signal) {
         });
     }
     else if (config.transport === "http" && config.url) {
-        transport = new StreamableHTTPClientTransport(new URL(config.url));
+        const resolvedUrl = config.url.replace(/\$\{([^}]+)\}/g, (_, name) => process.env[name] ?? "");
+        transport = new StreamableHTTPClientTransport(new URL(resolvedUrl));
     }
     else {
         throw new Error(`Server "${name}" has unsupported transport: ${config.transport}`);

package/dist/resources/extensions/search-the-web/tool-search.js

@@ -259,9 +259,9 @@ export function registerSearchTool(pi) {
             // with brief interruptions every MAX_CONSECUTIVE_DUPES+1 calls.
             if (cacheKey === lastSearchKey) {
                 consecutiveDupeCount++;
-                if (consecutiveDupeCount >= MAX_CONSECUTIVE_DUPES) {
+                if (consecutiveDupeCount > MAX_CONSECUTIVE_DUPES) {
                     return {
-                        content: [{ type: "text", text: `⚠️ Search loop detected: the query "${params.query}" has been searched ${consecutiveDupeCount + 1} times consecutively with identical results. The information you need is already in the previous search results above. Stop searching and use those results to proceed with your task.` }],
+                        content: [{ type: "text", text: `⚠️ Search loop detected: the query "${params.query}" has been searched ${consecutiveDupeCount} times consecutively with identical results. The information you need is already in the previous search results above. Stop searching and use those results to proceed with your task.` }],
                         isError: true,
                         details: { errorKind: "search_loop", error: "Consecutive duplicate search detected" },
                     };
@@ -269,7 +269,7 @@ export function registerSearchTool(pi) {
             }
             else {
                 lastSearchKey = cacheKey;
-                consecutiveDupeCount = 0;
+                consecutiveDupeCount = 1;
             }
             const cached = searchCache.get(cacheKey);
             if (cached) {

package/dist/resources/extensions/subagent/index.js

@@ -409,12 +409,16 @@ async function runSingleAgentInCmuxSplit(cmuxClient, directionOrSurfaceId, defau
         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) => 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)}`);
         if (!sent) {

package/dist/resources/extensions/voice/index.js

@@ -1,6 +1,6 @@
 import { shortcutDesc } from "../shared/mod.js";
 import { isKeyRelease, Key, matchesKey, truncateToWidth, visibleWidth } from "@gsd/pi-tui";
-import { spawn, execSync } from "node:child_process";
+import { spawn, execFileSync } from "node:child_process";
 import * as fs from "node:fs";
 import * as os from "node:os";
 import * as path from "node:path";
@@ -22,7 +22,7 @@ function ensureBinary() {
     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;
@@ -42,7 +42,7 @@ function ensureLinuxReady(ctx) {
     }
     // 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");
@@ -51,7 +51,7 @@ function ensureLinuxReady(ctx) {
     // Check that sounddevice is importable
     const py = linuxPython();
     try {
-        execSync(`${py} -c "import sounddevice"`, {
+        execFileSync(py, ["-c", "import sounddevice"], {
             stdio: "pipe",
             timeout: 10000,
         });

package/dist/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>