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

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

@@ -0,0 +1,134 @@
+/**
+ * run-manager.ts — Create and list isolated workflow run directories.
+ *
+ * Each run lives under `.gsd/workflow-runs/<name>/<timestamp>/` and contains:
+ * - DEFINITION.yaml — frozen snapshot of the workflow definition at run-creation time
+ * - GRAPH.yaml — initialized step graph with all steps pending
+ * - PARAMS.json — (optional) parameter overrides used for this run
+ *
+ * Observability:
+ * - All run state is on disk in human-readable YAML/JSON — inspectable with cat/less.
+ * - `listRuns()` returns structured metadata including step counts and overall status.
+ * - Timestamp directory names are filesystem-safe (ISO with hyphens replacing colons).
+ * - Errors include the full path context for diagnosis.
+ */
+import { mkdirSync, writeFileSync, existsSync, readdirSync, statSync } from "node:fs";
+import { join } from "node:path";
+import { stringify } from "yaml";
+import { loadDefinition, substituteParams } from "./definition-loader.js";
+import { initializeGraph, writeGraph, readGraph } from "./graph.js";
+// ─── Constants ───────────────────────────────────────────────────────────
+const RUNS_DIR = "workflow-runs";
+const DEFS_DIR = "workflow-defs";
+// ─── Helpers ─────────────────────────────────────────────────────────────
+/**
+ * Generate a filesystem-safe timestamp: `YYYY-MM-DDTHH-MM-SS`.
+ * Replaces colons with hyphens so the string is safe as a directory name
+ * on all platforms (Windows forbids colons in paths).
+ */
+function makeTimestamp(date = new Date()) {
+    return date.toISOString().replace(/:/g, "-").replace(/\.\d{3}Z$/, "");
+}
+/**
+ * Derive overall status from a graph's step statuses.
+ */
+function deriveStatus(graph) {
+    const hasActive = graph.steps.some((s) => s.status === "active");
+    const allDone = graph.steps.every((s) => s.status === "complete" || s.status === "expanded");
+    if (allDone)
+        return "complete";
+    if (hasActive)
+        return "running";
+    return "pending";
+}
+// ─── Public API ──────────────────────────────────────────────────────────
+/**
+ * Create a new isolated run directory for a workflow definition.
+ *
+ * 1. Loads the definition from `<basePath>/.gsd/workflow-defs/<defName>.yaml`
+ * 2. Applies parameter substitution if overrides are provided
+ * 3. Creates `<basePath>/.gsd/workflow-runs/<defName>/<timestamp>/`
+ * 4. Writes frozen DEFINITION.yaml, initialized GRAPH.yaml, and optional PARAMS.json
+ *
+ * @param basePath — project root directory
+ * @param defName — definition filename (without .yaml extension)
+ * @param overrides — optional parameter overrides (merged with definition defaults)
+ * @returns Full path to the created run directory
+ * @throws Error if the definition file doesn't exist or is invalid
+ */
+export function createRun(basePath, defName, overrides) {
+    const defsDir = join(basePath, ".gsd", DEFS_DIR);
+    // Load and validate the definition
+    const rawDef = loadDefinition(defsDir, defName);
+    // Apply parameter substitution if overrides provided
+    const def = overrides
+        ? substituteParams(rawDef, overrides)
+        : substituteParams(rawDef); // still resolve default params if any
+    // Create the run directory
+    const timestamp = makeTimestamp();
+    const runDir = join(basePath, ".gsd", RUNS_DIR, defName, timestamp);
+    mkdirSync(runDir, { recursive: true });
+    // Freeze the definition as DEFINITION.yaml
+    writeFileSync(join(runDir, "DEFINITION.yaml"), stringify(def), "utf-8");
+    // Initialize and write GRAPH.yaml
+    const graph = initializeGraph(def);
+    writeGraph(runDir, graph);
+    // Write PARAMS.json if overrides were provided
+    if (overrides && Object.keys(overrides).length > 0) {
+        writeFileSync(join(runDir, "PARAMS.json"), JSON.stringify(overrides, null, 2), "utf-8");
+    }
+    return runDir;
+}
+/**
+ * List existing workflow runs with metadata.
+ *
+ * Scans `<basePath>/.gsd/workflow-runs/` for run directories. Each run's
+ * GRAPH.yaml is read to derive step counts and overall status.
+ *
+ * @param basePath — project root directory
+ * @param defName — optional filter: only list runs for this definition name
+ * @returns Array of run metadata, sorted newest-first within each definition
+ */
+export function listRuns(basePath, defName) {
+    const runsRoot = join(basePath, ".gsd", RUNS_DIR);
+    if (!existsSync(runsRoot))
+        return [];
+    const results = [];
+    // Get workflow name directories
+    const nameDirs = defName ? [defName] : readdirSync(runsRoot).filter((entry) => {
+        const full = join(runsRoot, entry);
+        return statSync(full).isDirectory();
+    });
+    for (const name of nameDirs) {
+        const nameDir = join(runsRoot, name);
+        if (!existsSync(nameDir))
+            continue;
+        const timestamps = readdirSync(nameDir).filter((entry) => {
+            const full = join(nameDir, entry);
+            return statSync(full).isDirectory();
+        });
+        // Sort newest-first (ISO strings sort lexicographically)
+        timestamps.sort().reverse();
+        for (const ts of timestamps) {
+            const runDir = join(nameDir, ts);
+            try {
+                const graph = readGraph(runDir);
+                const total = graph.steps.length;
+                const completed = graph.steps.filter((s) => s.status === "complete").length;
+                const pending = graph.steps.filter((s) => s.status === "pending").length;
+                const active = graph.steps.filter((s) => s.status === "active").length;
+                results.push({
+                    name,
+                    timestamp: ts,
+                    runDir,
+                    steps: { total, completed, pending, active },
+                    status: deriveStatus(graph),
+                });
+            }
+            catch {
+                // Skip runs with invalid/missing GRAPH.yaml
+            }
+        }
+    }
+    return results;
+}

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

@@ -0,0 +1,138 @@
+/**
+ * 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";
+// ─── 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",
+            "",
+            "Only affects gpt-5.4 models.",
+        ].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",
+        "",
+        "Only affects gpt-5.4 models.",
+    ].join("\n");
+}
+// ─── 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.notify("Service tier set to priority (2x cost, faster responses). Only affects gpt-5.4 models.", "info");
+        return;
+    }
+    if (trimmed === "off") {
+        await writeGlobalServiceTier(ctx, undefined);
+        ctx.ui.notify("Service tier disabled.", "info");
+        return;
+    }
+    if (trimmed === "flex") {
+        await writeGlobalServiceTier(ctx, "flex");
+        ctx.ui.notify("Service tier set to flex (0.5x cost, slower responses). Only affects gpt-5.4 models.", "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/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
@@ -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/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>