gsd-pi 2.41.0-dev.cac69f9 → 2.42.0-dev.97e9e30

package/dist/resources/extensions/gsd/dev-execution-policy.js

@@ -0,0 +1,24 @@
+/**
+ * dev-execution-policy.ts — DevExecutionPolicy implementation.
+ *
+ * Stub policy for the dev engine. All methods return safe defaults.
+ * Real verification/closeout continues running through phases.ts via LoopDeps.
+ * Wiring this policy into the loop is S04's responsibility.
+ */
+export class DevExecutionPolicy {
+    async prepareWorkspace(_basePath, _milestoneId) {
+        // no-op — workspace preparation handled by existing GSD logic
+    }
+    async selectModel(_unitType, _unitId, _context) {
+        return null; // use default model selection
+    }
+    async verify(_unitType, _unitId, _context) {
+        return "continue";
+    }
+    async recover(_unitType, _unitId, _context) {
+        return { outcome: "retry" };
+    }
+    async closeout(_unitType, _unitId, _context) {
+        return { committed: false, artifacts: [] };
+    }
+}

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

@@ -0,0 +1,82 @@
+/**
+ * dev-workflow-engine.ts — DevWorkflowEngine implementation.
+ *
+ * Implements WorkflowEngine by delegating to existing GSD state derivation
+ * and dispatch logic. This is the "dev" engine — it wraps the current GSD
+ * auto-mode behavior behind the engine-polymorphic interface.
+ */
+import { deriveState } from "./state.js";
+import { resolveDispatch } from "./auto-dispatch.js";
+import { loadEffectiveGSDPreferences } from "./preferences.js";
+// ─── Bridge: DispatchAction → EngineDispatchAction ────────────────────────
+/**
+ * Map a GSD-specific DispatchAction (which carries `matchedRule`, `unitType`,
+ * etc.) to the engine-generic EngineDispatchAction discriminated union.
+ *
+ * Exported for unit testing.
+ */
+export function bridgeDispatchAction(da) {
+    switch (da.action) {
+        case "dispatch":
+            return {
+                action: "dispatch",
+                step: {
+                    unitType: da.unitType,
+                    unitId: da.unitId,
+                    prompt: da.prompt,
+                },
+            };
+        case "stop":
+            return {
+                action: "stop",
+                reason: da.reason,
+                level: da.level,
+            };
+        case "skip":
+            return { action: "skip" };
+    }
+}
+// ─── DevWorkflowEngine ───────────────────────────────────────────────────
+export class DevWorkflowEngine {
+    engineId = "dev";
+    async deriveState(basePath) {
+        const gsd = await deriveState(basePath);
+        return {
+            phase: gsd.phase,
+            currentMilestoneId: gsd.activeMilestone?.id ?? null,
+            activeSliceId: gsd.activeSlice?.id ?? null,
+            activeTaskId: gsd.activeTask?.id ?? null,
+            isComplete: gsd.phase === "complete",
+            raw: gsd,
+        };
+    }
+    async resolveDispatch(state, context) {
+        const gsd = state.raw;
+        const mid = gsd.activeMilestone?.id ?? "";
+        const midTitle = gsd.activeMilestone?.title ?? "";
+        const loaded = loadEffectiveGSDPreferences();
+        const prefs = loaded?.preferences ?? undefined;
+        const dispatchCtx = {
+            basePath: context.basePath,
+            mid,
+            midTitle,
+            state: gsd,
+            prefs,
+        };
+        const result = await resolveDispatch(dispatchCtx);
+        return bridgeDispatchAction(result);
+    }
+    async reconcile(state, _completedStep) {
+        return {
+            outcome: state.isComplete ? "milestone-complete" : "continue",
+        };
+    }
+    getDisplayMetadata(state) {
+        return {
+            engineLabel: "GSD Dev",
+            currentPhase: state.phase,
+            progressSummary: `${state.currentMilestoneId ?? "no milestone"} / ${state.activeSliceId ?? "—"} / ${state.activeTaskId ?? "—"}`,
+            stepCount: null,
+        };
+    }
+}

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

@@ -0,0 +1,40 @@
+/**
+ * engine-resolver.ts — Route sessions to engine/policy pairs.
+ *
+ * Routes `null` and `"dev"` engine IDs to the DevWorkflowEngine/DevExecutionPolicy
+ * pair. Any other non-null engine ID is treated as a custom workflow engine that
+ * reads its state from an `activeRunDir`. Respects `GSD_ENGINE_BYPASS=1` kill
+ * switch to skip the engine layer entirely.
+ */
+import { DevWorkflowEngine } from "./dev-workflow-engine.js";
+import { DevExecutionPolicy } from "./dev-execution-policy.js";
+import { CustomWorkflowEngine } from "./custom-workflow-engine.js";
+import { CustomExecutionPolicy } from "./custom-execution-policy.js";
+/**
+ * Resolve an engine/policy pair for the given session.
+ *
+ * - `null` or `"dev"` → DevWorkflowEngine + DevExecutionPolicy
+ * - any other non-null ID → CustomWorkflowEngine(activeRunDir) + CustomExecutionPolicy()
+ *   (requires activeRunDir to be a non-empty string)
+ *
+ * Note: `GSD_ENGINE_BYPASS=1` is checked in autoLoop before calling this function.
+ */
+export function resolveEngine(session) {
+    const { activeEngineId, activeRunDir } = session;
+    if (activeEngineId === null || activeEngineId === "dev") {
+        return {
+            engine: new DevWorkflowEngine(),
+            policy: new DevExecutionPolicy(),
+        };
+    }
+    // Any non-null, non-"dev" engine ID is a custom workflow engine.
+    // activeRunDir is required — the engine reads GRAPH.yaml from it.
+    if (!activeRunDir || typeof activeRunDir !== "string") {
+        throw new Error(`Custom engine "${activeEngineId}" requires activeRunDir to be a non-empty string, ` +
+            `got: ${JSON.stringify(activeRunDir)}`);
+    }
+    return {
+        engine: new CustomWorkflowEngine(activeRunDir),
+        policy: new CustomExecutionPolicy(activeRunDir),
+    };
+}

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

@@ -0,0 +1,8 @@
+/**
+ * engine-types.ts — Engine-polymorphic type contracts.
+ *
+ * LEAF NODE: This file must have ZERO imports from any GSD module.
+ * Only `node:` imports are permitted. All engine/policy interfaces
+ * depend on these types; nothing here depends on GSD internals.
+ */
+export {};

package/dist/resources/extensions/gsd/execution-policy.js

@@ -0,0 +1,8 @@
+/**
+ * execution-policy.ts — ExecutionPolicy interface.
+ *
+ * Defines the policy layer that governs model selection, verification,
+ * recovery, and closeout for each execution step. Imports only from
+ * the leaf-node engine-types.
+ */
+export {};

package/dist/resources/extensions/gsd/graph.js

@@ -0,0 +1,225 @@
+/**
+ * graph.ts — Pure data module for GRAPH.yaml workflow step tracking.
+ *
+ * Provides types and functions for reading, writing, and querying the
+ * step graph that drives CustomWorkflowEngine. Zero engine dependencies.
+ *
+ * GRAPH.yaml lives in a run directory and tracks step statuses
+ * (pending → active → complete) with optional dependency edges.
+ *
+ * Observability:
+ * - readGraph/writeGraph use YAML on disk — human-readable, diffable,
+ *   inspectable with `cat` or any YAML viewer.
+ * - Each GraphStep has status, startedAt, finishedAt fields visible in GRAPH.yaml.
+ * - writeGraph uses atomic write (tmp + rename) for crash safety.
+ * - All operations are immutable — callers always get a new graph object.
+ */
+import { parse, stringify } from "yaml";
+import { readFileSync, writeFileSync, renameSync, existsSync, mkdirSync } from "node:fs";
+import { join } from "node:path";
+// ─── YAML schema mapping ─────────────────────────────────────────────────
+const GRAPH_FILENAME = "GRAPH.yaml";
+// ─── Functions ───────────────────────────────────────────────────────────
+/**
+ * Read and parse GRAPH.yaml from a run directory.
+ *
+ * @param runDir — directory containing GRAPH.yaml
+ * @returns Parsed workflow graph
+ * @throws Error if file doesn't exist or YAML is malformed
+ */
+export function readGraph(runDir) {
+    const filePath = join(runDir, GRAPH_FILENAME);
+    if (!existsSync(filePath)) {
+        throw new Error(`GRAPH.yaml not found: ${filePath}`);
+    }
+    const raw = readFileSync(filePath, "utf-8");
+    const yaml = parse(raw);
+    if (!yaml?.steps || !Array.isArray(yaml.steps)) {
+        throw new Error(`Invalid GRAPH.yaml: missing or invalid 'steps' array in ${filePath}`);
+    }
+    return {
+        steps: yaml.steps.map((s) => ({
+            id: s.id,
+            title: s.title,
+            status: s.status,
+            prompt: s.prompt,
+            dependsOn: s.depends_on ?? [],
+            ...(s.parent_step_id != null ? { parentStepId: s.parent_step_id } : {}),
+            ...(s.started_at != null ? { startedAt: s.started_at } : {}),
+            ...(s.finished_at != null ? { finishedAt: s.finished_at } : {}),
+        })),
+        metadata: {
+            name: yaml.metadata?.name ?? "unnamed",
+            createdAt: yaml.metadata?.created_at ?? new Date().toISOString(),
+        },
+    };
+}
+/**
+ * Write a workflow graph to GRAPH.yaml in a run directory.
+ * Creates the directory if it doesn't exist. Write is atomic (write + rename).
+ *
+ * @param runDir — directory to write GRAPH.yaml into
+ * @param graph — the workflow graph to serialize
+ */
+export function writeGraph(runDir, graph) {
+    if (!existsSync(runDir)) {
+        mkdirSync(runDir, { recursive: true });
+    }
+    const yamlData = {
+        steps: graph.steps.map((s) => ({
+            id: s.id,
+            title: s.title,
+            status: s.status,
+            prompt: s.prompt,
+            depends_on: s.dependsOn.length > 0 ? s.dependsOn : undefined,
+            parent_step_id: s.parentStepId ?? undefined,
+            started_at: s.startedAt ?? undefined,
+            finished_at: s.finishedAt ?? undefined,
+        })),
+        metadata: {
+            name: graph.metadata.name,
+            created_at: graph.metadata.createdAt,
+        },
+    };
+    const filePath = join(runDir, GRAPH_FILENAME);
+    const tmpPath = filePath + ".tmp";
+    const content = stringify(yamlData);
+    writeFileSync(tmpPath, content, "utf-8");
+    // Atomic rename for crash safety
+    renameSync(tmpPath, filePath);
+}
+/**
+ * Get the next pending step whose dependencies are all complete.
+ *
+ * Returns the first step (in array order) with status "pending" where
+ * every step in its `dependsOn` list has status "complete".
+ *
+ * @param graph — the workflow graph to query
+ * @returns The next dispatchable step, or null if none available
+ */
+export function getNextPendingStep(graph) {
+    const statusMap = new Map(graph.steps.map((s) => [s.id, s.status]));
+    for (const step of graph.steps) {
+        if (step.status !== "pending")
+            continue;
+        const depsComplete = step.dependsOn.every((depId) => statusMap.get(depId) === "complete");
+        if (depsComplete)
+            return step;
+    }
+    return null;
+}
+/**
+ * Return a new graph with the specified step marked as "complete".
+ * Immutable — does not mutate the input graph.
+ *
+ * @param graph — the current workflow graph
+ * @param stepId — ID of the step to mark complete
+ * @returns New graph with the step's status set to "complete"
+ * @throws Error if stepId is not found in the graph
+ */
+export function markStepComplete(graph, stepId) {
+    const found = graph.steps.some((s) => s.id === stepId);
+    if (!found) {
+        throw new Error(`Step not found: ${stepId}`);
+    }
+    return {
+        ...graph,
+        steps: graph.steps.map((s) => s.id === stepId
+            ? { ...s, status: "complete", finishedAt: new Date().toISOString() }
+            : s),
+    };
+}
+// ─── Iteration expansion ─────────────────────────────────────────────────
+/**
+ * Expand an iterate step into concrete instances. Pure and deterministic —
+ * identical inputs always produce identical output.
+ *
+ * Given a parent step with status "pending" and an array of matched items,
+ * creates one instance step per item, marks the parent as "expanded", and
+ * rewrites any downstream dependsOn references from the parent ID to the
+ * full set of instance IDs.
+ *
+ * @param graph — the current workflow graph (not mutated)
+ * @param stepId — ID of the iterate step to expand
+ * @param items — matched items from the source artifact
+ * @param promptTemplate — template with {{item}} placeholders
+ * @returns New WorkflowGraph with instances inserted and deps rewritten
+ * @throws Error if stepId not found or step is not pending
+ */
+export function expandIteration(graph, stepId, items, promptTemplate) {
+    const parentIndex = graph.steps.findIndex((s) => s.id === stepId);
+    if (parentIndex === -1) {
+        throw new Error(`expandIteration: step not found: ${stepId}`);
+    }
+    const parentStep = graph.steps[parentIndex];
+    if (parentStep.status !== "pending") {
+        throw new Error(`expandIteration: step "${stepId}" has status "${parentStep.status}", expected "pending"`);
+    }
+    // Create instance steps
+    const instanceIds = [];
+    const instances = items.map((item, i) => {
+        const instanceId = `${stepId}--${String(i + 1).padStart(3, "0")}`;
+        instanceIds.push(instanceId);
+        return {
+            id: instanceId,
+            title: `${parentStep.title}: ${item}`,
+            status: "pending",
+            prompt: promptTemplate.replace(/\{\{item\}\}/g, () => item),
+            dependsOn: [...parentStep.dependsOn],
+            parentStepId: stepId,
+        };
+    });
+    // Build new steps array: copy everything, mark parent as expanded,
+    // insert instances right after the parent, rewrite downstream deps.
+    const newSteps = [];
+    for (let i = 0; i < graph.steps.length; i++) {
+        if (i === parentIndex) {
+            // Mark parent as expanded
+            newSteps.push({ ...parentStep, status: "expanded" });
+            // Insert instances immediately after parent
+            newSteps.push(...instances);
+        }
+        else {
+            const step = graph.steps[i];
+            // Rewrite dependsOn: replace parent ID with all instance IDs
+            const hasDep = step.dependsOn.includes(stepId);
+            if (hasDep) {
+                const rewritten = step.dependsOn.flatMap((dep) => dep === stepId ? instanceIds : [dep]);
+                newSteps.push({ ...step, dependsOn: rewritten });
+            }
+            else {
+                newSteps.push(step);
+            }
+        }
+    }
+    return {
+        ...graph,
+        steps: newSteps,
+    };
+}
+// ─── Definition → Graph conversion ──────────────────────────────────────
+/**
+ * Convert a parsed WorkflowDefinition into a WorkflowGraph with all
+ * steps in "pending" status. Used by run-manager to generate the initial
+ * GRAPH.yaml for a new run.
+ *
+ * @param def — a validated WorkflowDefinition from definition-loader
+ * @returns WorkflowGraph with pending steps and metadata from the definition
+ */
+export function initializeGraph(def) {
+    return {
+        steps: def.steps.map((s) => ({
+            id: s.id,
+            title: s.name,
+            status: "pending",
+            prompt: s.prompt,
+            dependsOn: s.requires ?? [],
+        })),
+        metadata: {
+            name: def.name,
+            createdAt: new Date().toISOString(),
+        },
+    };
+}
+/** @deprecated Use initializeGraph instead. Kept for backward compatibility. */
+export { initializeGraph as graphFromDefinition };

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