/run

name: "Specs: Run"
description: Execute the workflow.yaml step graph via delegated agents (Experimental)
category: Workflow
tags: [workflow, orchestration, agents, experimental]

Execute the `workflows/workflow.yaml` step graph end-to-end via delegated agents: complexity gate, IMPL/REVIEW issue graph, retry loops, and a final integration review.

**When to use which:** `/specs:run` delegates the full multi-agent graph (analyst -> researcher -> architect -> developer/reviewer pairs -> tech-writer -> gitops) and is the only one of the three that runs retry loops and an integration review. `/specs:ff` generates the three artifacts (`proposal.md`, `design.md`, `tasks.md`) inline in the main agent with no delegation and no execution. `/specs:apply` implements an *existing* `tasks.md` checklist inline; it does not run the propose/design/review graph. Use `/specs:run` when you want the whole pipeline driven for you; use `/specs:ff` + `/specs:apply` when you want to inspect/edit artifacts between phases.

This is an LLM following markdown instructions that reads `workflow.yaml` as data — not a real scheduler. See **Limitations**.

**Input**: The argument after `/specs:run` is a description of what to build (minus flags). Bare `/specs:run <description>` with no flags is the primary form.

• `--conversation <uuid>` (optional) — reuse an existing conversation's specs directory
• `--complexity small|medium|large` (optional) — skip inference; `small` takes the light

path (developer directly), anything else runs the full pipeline

Flags are stripped from the description before it is used as `{description}`.

UUID Enforcement

**CRITICAL**: The `conversation_id` MUST be a UUID (format: `xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx`, pattern `[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}`). NEVER use descriptive names, slugs, or human-readable strings as the conversation_id. If `--conversation` fails this pattern, reject it, generate a real UUID with `uuidgen` or `python3 -c "import uuid; print(uuid.uuid4())"`, and announce the substitution.

**Steps**

1. **Resolve inputs**

• `description`: if no argument was given, use the **AskUserQuestion tool** (open-ended,

no preset options) with the same wording as `/specs:new` step 1: "What change do you want to work on? Describe what you want to build or fix." Do not proceed without one.

• `conversation_id`: from `--conversation <uuid>` (validated) or the current conversation's

UUID; generate one if neither is available.

• `complexity`: from `--complexity`, else infer from the `CLAUDE.md` decision tree (single

file + clear scope -> `small`; multi-file / new system / ambiguous -> not small), then confirm the inferred value and the branch it implies with the user via **AskUserQuestion** before running `propose` or `implement-direct`.

• If `{specs_path}` already contains a populated `tasks.md`, warn and ask (AskUserQuestion)

whether to continue in place or start fresh with a new UUID — mirrors `/specs:ff`.

2. **Derive `specs_path` and create it**

`.scaffolding/conversations/{conversation_id}/specs/` — always with a trailing slash.

   mkdir -p .scaffolding/conversations/{conversation_id}/specs/

3. **Read the workflow definition**

Read `workflows/workflow.yaml` as data. This is the only workflow file read — no other YAML in the repo is interpreted by this command.

`settings.timeout_minutes: 120` is a stated **advisory** budget for the whole run — state it once in the run header. It is not enforced; there is no scheduler to enforce it.

4. **Evaluate step conditions by table lookup, never by general expression parsing**

| Condition string | Steps | True when | |---|---|---| | `inputs.complexity != 'small'` | `propose`, `design`, `implement` | resolved `complexity` is anything other than `small` (including unset) | | `inputs.complexity != 'small' and steps.propose.needs_research == True` | `research` | the above AND `proposal.md` contains the literal `**Research Needed**: Yes` field (`agents/analyst.md`'s proposal template); if that field is absent, fall back to the `spec-workflow` skill's "When Researcher Is Needed" prose, defaulting to false and recording the default in the trace | | `inputs.complexity == 'small'` | `implement-direct` | resolved `complexity` is exactly `small` |

Steps with no `condition` (`review`, `document`, `push`) always run. If `workflow.yaml` ever contains a condition string outside this table, HALT and report the unrecognised expression and step id — never guess.

5. **Substitute placeholders before every `Task` call**

| Placeholder | Value | |---|---| | `{description}` | resolved `description`, verbatim | | `{conversation_id}` | the validated UUID | | `{specs_path}` | `.scaffolding/conversations/{conversation_id}/specs/` — concatenates directly (`{specs_path}proposal.md`); keep the trailing slash | | `{original_prompt}` | the user's full original `/specs:run` invocation text, unedited — captured once at run start, reused for every step | | `{language_instruction}` | the response-language directive for this session, or empty string when none applies — an empty value renders as nothing, never as the literal placeholder |

Always additionally pass `conversation_id` and `specs_path` in every delegation per the `spec-workflow` skill, even where a template omits them. Never send an unsubstituted `{...}` token to an agent.

6. **Execute the step graph in dependency order**

A dependency is satisfied when its status is `succeeded`, `skipped`, or `failed (max_loops exhausted)`; it blocks only while `pending`/`running`. This is load-bearing: `review` declares `depends_on: [implement, implement-direct]`, and exactly one of those two is always skipped by the complexity gate — a naive "all deps must succeed" reading deadlocks every run.

A plain `failed` status (no `max_loops`