Create Workflow

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:

• Project plugins: .gsd/workflows/<name>.yaml (preferred — checked into repo).
• Global plugins: ~/.gsd/workflows/<name>.yaml (private to the machine). Use this when the user says "global" or "--global".
• Legacy location .gsd/workflow-defs/<name>.yaml still works but is being phased out — only write there if the user explicitly asks.
• After writing, tell the user to validate with /gsd workflow validate <name> and run with /gsd workflow <name>.

Execution mode:

Workflow plugins declare a mode: field in their top-level YAML (or <template_meta> block for markdown) that controls runtime behavior:

• oneshot — prompt-only, no state, no artifact dir. For one-pass tasks like reviews, reports, or one-off scripts. Default for YAML with a single step when iteration isn't needed.
• yaml-step — full engine with GRAPH.yaml, iterate, and verify. Default for YAML. Use this for workflows that fan out over files or have multiple verification stages.
• markdown-phase — phased markdown-driven workflows with STATE.json and phase-approval gates. For multi-session projects. Markdown-only.
• auto-milestone — hooks into the full /gsd auto pipeline. Reserved for the bundled full-project template; not normally authored by users.

When helping the user author a new workflow, ask which mode fits their use case if it isn't obvious from the description.

"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.

• 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.

• 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.

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, mode, description, params, steps.
5. Include a mode: field (oneshot or yaml-step). Default to yaml-step.
6. Order step fields: id, name, prompt, requires, produces, context_from, verify, iterate.
7. Write to .gsd/workflows/<name>.yaml by default, or ~/.gsd/workflows/<name>.yaml when the user says "global" or passes --global.
8. After writing, tell the user: "Run /gsd workflow validate <name> to check the definition, then /gsd workflow <name> to run it."