valent-pipeline 0.4.2 → 0.4.3

package/README.md

@@ -217,9 +217,12 @@ Invoked as slash commands inside Claude Code:
 | Skill | Description |
 |---|---|
 | `/valent-configure` | Interactive configuration wizard |
-| `/valent-run-story STORY-ID` | Execute a single story |
-| `/valent-run-epic EPIC-ID` | Execute an epic with sprint planning |
-| `/valent-run-project` | Execute a full project across all epics |
+| `/valent-run-story STORY-ID` | Execute a single story (prose-Lead orchestrator) |
+| `/valent-run-epic EPIC-ID` | Execute an epic with sprint planning (prose-Lead orchestrator) |
+| `/valent-run-project` | Execute a full project across all epics (prose-Lead orchestrator) |
+| `/valent-run-story-workflow STORY-ID` | Execute a single story via the native Claude Code **Workflow** orchestrator (experimental) |
+| `/valent-run-epic-workflow EPIC-ID` | Execute an epic via the **Workflow** orchestrator (experimental) |
+| `/valent-run-project-workflow` | Execute a full project via the **Workflow** orchestrator (experimental) |
 | `/valent-setup-backlog` | Convert epics/stories into pipeline backlog |
 | `/valent-run-retrospective` | Trigger a standalone retrospective |
 | `/valent-run-deferred-tests` | Run deferred iOS tests on Mac |
@@ -298,6 +301,11 @@ The **Retrospective** agent (triggered every N stories) is the sole gatekeeper f
 
 ## Execution Modes
 
+Each mode ships in two orchestrator flavors, as separate linear skills (no in-skill branching):
+
+- **Prose-Lead** (`/valent-run-story`, `/valent-run-epic`, `/valent-run-project`) — the supported default. A persistent Lead agent assembles a team and orchestrates the pipeline in prose.
+- **Workflow** (`/valent-run-story-workflow`, `/valent-run-epic-workflow`, `/valent-run-project-workflow`) — experimental, Claude Code only. A deterministic Workflow script (`pipeline/orchestrators/claude-code/{plan,sprint,retro}.workflow.js`) drives the pipeline with schema-validated gates, a code-owned rejection cap, parallel CRITIC passes, and journal-based resume (`resumeFromRunId`). Validated by `scripts/test-workflow.js` but not yet exercised end-to-end against a live story — validate against a fixture before relying on it. See `pipeline/orchestrators/claude-code/README.md`.
+
 ### Single Story
 
 ```

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "valent-pipeline",
-  "version": "0.4.2",
+  "version": "0.4.3",
   "description": "v3 multi-agent AI pipeline for software development lifecycle",
   "type": "module",
   "bin": {

package/skills/valent-run-epic-workflow/SKILL.md

@@ -0,0 +1,119 @@
+---
+name: valent-run-epic-workflow
+description: 'Run all stories in an epic through the v3 pipeline using the native Claude Code Workflow orchestrator (deterministic plan→sprint→retro, schema-validated gates, journal resume). Use when the user says "run epic workflow" or "run epic with the workflow orchestrator".'
+argument-hint: '<epic-id>'
+---
+
+# valent-run-epic-workflow
+
+Run all stories tagged with an epic through the v3 pipeline using the **native Claude Code Workflow orchestrator**. Each sprint is driven by three composed Workflow scripts — `plan.workflow.js` (groom → size → pack → validate), `sprint.workflow.js` (execute the batch through the per-story pipeline with schema-validated gates), and `retro.workflow.js` (calibrate + learn) — looped until the epic's stories are shipped, blocked, or cancelled.
+
+This is the Workflow path. There is **no prose Lead** and **no per-agent orchestration in this skill** — the agent spawning, quality gates, rejection cap, and monitoring all live inside the Workflow scripts. This skill only sequences the three workflows per sprint and checks remaining work. For the prose-Lead orchestrator, use `/valent-run-epic` instead.
+
+> **Status — experimental.** The orchestrators' control flow is validated (`scripts/test-workflow.js`, incl. a resume-safety lint) but **not yet exercised end-to-end against a live story/epic**, and no `sprint-cycle` wrapper exists yet — this skill sequences `plan → sprint → retro` itself. Validate against a `testResources/*` fixture before relying on it. The prose-Lead path (`/valent-run-epic`) remains the supported default.
+
+## Arguments
+
+The user provides an epic ID (e.g., `KANBAN-MVP`), matched against the `epic` field on backlog items. If no argument is provided, ask the user for the epic ID.
+
+## Context Window Advisory
+
+Use the standard 200k context window. Workflow `agent()` calls run in their own sub-contexts, so the orchestrating context stays small — but still re-read backlog/progress from disk at the top of each sprint rather than trusting in-context memory.
+
+## Execution Steps
+
+### Step 0: Pre-Flight — runtime + MCP
+
+1. **Runtime guard.** Read `.valent-pipeline/pipeline-config.yaml`. The Workflow tool is Claude Code only — if `runtime.provider` is not `claude-code`, **STOP** with: `The Workflow orchestrator requires runtime.provider: claude-code. This project uses {provider}. Run /valent-run-epic for the prose-Lead orchestrator instead.`
+2. **Visual validation MCP.** If `project.type` is `fullstack-web` or `frontend-only`, verify `{tech_stack.browser_automation_mcp}` is accessible. If not → **STOP** with the install instruction (`npx valent-pipeline init --force` or `npm install -g @playwright/mcp`). *(The Workflow path has no PMCP/visual-validation stage yet — this guard is forward-looking.)*
+
+### Step 1: Load Pipeline Config
+
+Read and follow `.valent-pipeline/steps/orchestration/load-pipeline-config.md`. Set `{epic_id}` from the argument.
+
+### Step 2: Validate Epic
+
+Read `{backlog_path}`. Filter items where `epic` matches `{epic_id}`.
+
+- If no items match, stop: "No backlog items found for epic `{epic_id}`. Add `epic: {epic_id}` to stories in `{backlog_path}`."
+- Count total / pending / shipped / blocked / cancelled. Present the summary and confirm: "Epic `{epic_id}`: {total} stories ({pending} pending, {shipped} shipped, {blocked} blocked). Start the workflow run?"
+
+### Step 3: Initialize or Resume Epic Progress
+
+Read `{epic_progress_path}`.
+
+**If it exists and `epic_id` matches:** this is a **resume**. Display prior progress (completed / remaining / current sprint) and confirm before continuing.
+
+**Otherwise:** create the initial `epic-progress.md` (same shape as `/valent-run-epic` Step 3): `epic_id`, `stories_completed: []`, `stories_remaining: [pending IDs for this epic]`, `current_sprint`, `total_completed`, `last_updated`. Keep it under 50 lines — it is the crash-recovery substrate.
+
+### Step 4: Sprint Loop (plan → sprint → retro)
+
+Loop sprints until no pending epic stories with met dependencies remain. Each iteration:
+
+#### 4a. Re-read state from disk
+**ALWAYS** read `{epic_progress_path}` and `{backlog_path}` from disk at the top of each sprint. Never trust in-context memory.
+
+#### 4b. Check for remaining work
+Filter `{backlog_path}` by `{epic_id}`. If no `pending` stories with met dependencies remain, exit the loop → Step 5. Collect the eligible pending story IDs (with `projectType` from config and each story's `testing_profiles`) into a candidate list for this sprint.
+
+#### 4c. Plan the sprint
+Invoke `plan.workflow.js` via the **Workflow tool**:
+
+```js
+Workflow({
+  scriptPath: '.valent-pipeline/orchestrators/claude-code/plan.workflow.js',
+  args: { stories: [{ storyId, projectType }, ...candidates], sprintId: '{epic_id}-sprint-{n}', velocity: {sprint.initial_velocity_points or current calibrated velocity} }
+})
+```
+
+It grooms, sizes (calibrated Fibonacci), packs to velocity, and validates — returning `{ sprintId, stories: [{ storyId, projectType, profiles }, ...] }`. Record its `runId`.
+
+#### 4d. Execute the sprint
+Feed the planned batch straight into `sprint.workflow.js`:
+
+```js
+Workflow({
+  scriptPath: '.valent-pipeline/orchestrators/claude-code/sprint.workflow.js',
+  args: { stories: <plan output .stories>, maxRejectionCycles: {quality.max_rejection_cycles or 5} }
+})
+```
+
+It runs each story through the per-story pipeline (deterministic graph resolve, READINESS/CRITIC/JUDGE gates, 3-pass parallel CRITIC, code-owned rejection cap) **sequentially on a shared branch**, rolling over any story that JUDGE rejects or that trips the cap. Returns `{ shipped, stories_shipped, stories_rolled_over, results: [{ storyId, shipped, verdict, skipped }] }`. Record its `runId`.
+
+#### 4e. Update progress
+For each shipped story: move it from `stories_remaining` to `stories_completed` in `epic-progress.md` with a compact one-line outcome; update `total_completed` and `last_updated`; keep the file under 50 lines. Then read and follow `.valent-pipeline/steps/orchestration/update-backlog-status.md`. Rolled-over stories stay `pending` for a later sprint (or are surfaced as blocked if they keep failing).
+
+#### 4f. Retrospective (mandatory, blocking)
+Invoke `retro.workflow.js`:
+
+```js
+Workflow({
+  scriptPath: '.valent-pipeline/orchestrators/claude-code/retro.workflow.js',
+  args: { batchNumber: {n}, sprintId: '{epic_id}-sprint-{n}' }
+})
+```
+
+It calibrates estimates, runs a loop-until-dry aggregate review, gates directives (auto-apply vs. approval), and embeds curated knowledge. Record its `runId`. Retro runs every sprint — this is what tightens future sizing.
+
+#### 4g. Continue
+Increment `{n}` and return to Step 4a. **Do NOT ask permission to continue between sprints** — the user opted into the full epic run at Step 2.
+
+### Step 5: Epic Complete
+
+When no pending epic stories with met dependencies remain, write `epic-report.md` (same content as `/valent-run-epic` Step 5a: totals, sprint summary, velocity trend, aggregate bug/rejection counts, estimation accuracy, per-story one-liners, outstanding cross-epic bugs) and present the completion summary to the user, listing any blocked/cancelled stories with reasons.
+
+## Resume (do NOT restart from scratch)
+
+Two layers of durability:
+
+1. **Within a single Workflow run** (a plan, a sprint, or a retro): every invocation returns a `runId`. If one is interrupted, relaunch **that** workflow with `Workflow({ scriptPath, resumeFromRunId: <runId> })` — the journal replays the unchanged prefix instantly and re-runs only from the first changed/new `agent()` call. Already-shipped stories and passed gates are not redone.
+2. **Across the sprint loop**: `epic-progress.md` + `{backlog_path}` record which stories shipped and which sprint is current. On a full conversation reset, re-run `/valent-run-epic-workflow {epic_id}`; Step 3 detects the existing progress file and resumes at the next unfinished sprint. Shipped stories are not re-run.
+
+Do **not** hand-edit state files to "resume" a Workflow — pass `resumeFromRunId`.
+
+## Notes
+
+- The **journal is the state of record** inside each Workflow; `epic-progress.md` / `sprint-{n}-status.yaml` / handoffs are derived human-readable views agents write for visibility.
+- **Known simplifications:** a CRITIC rejection re-runs ALL dev agents (not just the targeted one); no PMCP/visual-validation stage yet; no PM review/audit stage in the Workflow path (that remains agent-driven in `/valent-run-epic`). See `.valent-pipeline/orchestrators/claude-code/README.md`.
+- Do **not** adopt the Lead persona or read `lead.md` — that is the prose-Lead path. Orchestration here is the three Workflow scripts.
+- Correction directives may not exist yet for new pipelines — the workflows proceed without them gracefully.

package/skills/valent-run-project-workflow/SKILL.md

@@ -0,0 +1,126 @@
+---
+name: valent-run-project-workflow
+description: 'Run all stories across all epics through the v3 pipeline using the native Claude Code Workflow orchestrator (deterministic plan→sprint→retro per sprint, cross-epic dependency resolution, journal resume). Use when the user says "run project workflow" or "run project with the workflow orchestrator".'
+---
+
+# valent-run-project-workflow
+
+Run every pending story in the backlog, across all epics, using the **native Claude Code Workflow orchestrator**. Each sprint is driven by three composed Workflow scripts — `plan.workflow.js` (groom → size → pack → validate), `sprint.workflow.js` (execute the batch through the per-story pipeline with schema-validated gates), and `retro.workflow.js` (calibrate + learn) — looped with cross-epic dependency resolution until everything ships or is blocked.
+
+This is the Workflow path. There is **no prose Lead** and **no per-agent orchestration in this skill** — agent spawning, quality gates, rejection cap, and monitoring live inside the Workflow scripts. This skill sequences the three workflows per sprint, resolves cross-epic dependencies between sprints, and checks remaining work. For the prose-Lead orchestrator, use `/valent-run-project` instead.
+
+> **Status — experimental.** The orchestrators' control flow is validated (`scripts/test-workflow.js`, incl. a resume-safety lint) but **not yet exercised end-to-end against a live run**, and no `sprint-cycle` wrapper exists yet — this skill sequences `plan → sprint → retro` itself. Validate against a `testResources/*` fixture before relying on it. The prose-Lead path (`/valent-run-project`) remains the supported default.
+
+## Context Window Advisory
+
+Use the standard 200k context window. Workflow `agent()` calls run in their own sub-contexts, so the orchestrating context stays small — but still re-read backlog/progress from disk at the top of each sprint rather than trusting in-context memory.
+
+## Execution Steps
+
+### Step 0: Pre-Flight — runtime + MCP
+
+1. **Runtime guard.** Read `.valent-pipeline/pipeline-config.yaml`. The Workflow tool is Claude Code only — if `runtime.provider` is not `claude-code`, **STOP** with: `The Workflow orchestrator requires runtime.provider: claude-code. This project uses {provider}. Run /valent-run-project for the prose-Lead orchestrator instead.`
+2. **Visual validation MCP.** If `project.type` is `fullstack-web` or `frontend-only`, verify `{tech_stack.browser_automation_mcp}` is accessible. If not → **STOP** with the install instruction (`npx valent-pipeline init --force` or `npm install -g @playwright/mcp`). *(The Workflow path has no PMCP/visual-validation stage yet — this guard is forward-looking.)*
+
+### Step 1: Load Pipeline Config
+
+Read and follow `.valent-pipeline/steps/orchestration/load-pipeline-config.md`.
+
+### Step 2: Build Cross-Epic Dependency Map
+
+Read `{backlog_path}`. Load ALL items (not filtered by epic).
+
+1. For each item, record its `depends_on` and `blocked_by_bugs` lists.
+2. Identify cross-epic dependencies.
+3. Validate for circular dependencies — if found, report and stop.
+
+Present the execution plan (N stories across M epics; shipped / pending / blocked counts; cross-epic dependency list) and confirm: "Run all {N} pending stories with workflow sprint planning?"
+
+### Step 3: Initialize or Resume Project Progress
+
+Read `{epic_progress_path}`.
+
+**If it exists and `epic_id` is `"project"`:** this is a **resume**. Display prior progress and current sprint, and confirm before continuing.
+
+**Otherwise:** create the initial progress file with `epic_id: "project"`, `stories_remaining: [all pending IDs]`, `current_sprint`, `total_completed`, `last_updated` (same shape as `/valent-run-project` Step 3).
+
+### Step 4: Sprint Loop (plan → sprint → retro)
+
+Loop sprints until all stories are shipped, blocked, or cancelled. Each iteration:
+
+#### 4a. Re-read state from disk
+**ALWAYS** read `{epic_progress_path}` and `{backlog_path}` from disk at the top of each sprint.
+
+#### 4b. Check for remaining work (cross-epic)
+Read `{backlog_path}` (all epics). If no `pending` stories with met dependencies remain:
+- all remaining `shipped`/`cancelled` → project complete, go to Step 5;
+- remaining `blocked`/`blocked-on-user` → report blockers, go to Step 5;
+- remaining `pending` but all with unmet `depends_on` → circular/missing prerequisite, report and stop.
+
+Otherwise collect the eligible pending story IDs across ALL epics whose dependencies are met (with `projectType` from config and each story's `testing_profiles`) as this sprint's candidate list.
+
+#### 4c. Plan the sprint
+Invoke `plan.workflow.js` via the **Workflow tool**:
+
+```js
+Workflow({
+  scriptPath: '.valent-pipeline/orchestrators/claude-code/plan.workflow.js',
+  args: { stories: [{ storyId, projectType }, ...candidates], sprintId: 'project-sprint-{n}', velocity: {sprint.initial_velocity_points or current calibrated velocity} }
+})
+```
+
+Returns `{ sprintId, stories: [{ storyId, projectType, profiles }, ...] }`. Record its `runId`.
+
+#### 4d. Execute the sprint
+Feed the planned batch straight into `sprint.workflow.js`:
+
+```js
+Workflow({
+  scriptPath: '.valent-pipeline/orchestrators/claude-code/sprint.workflow.js',
+  args: { stories: <plan output .stories>, maxRejectionCycles: {quality.max_rejection_cycles or 5} }
+})
+```
+
+Runs each story sequentially through the per-story pipeline on a shared branch, rolling over any story JUDGE rejects or that trips the cap. Returns `{ shipped, stories_shipped, stories_rolled_over, results: [...] }`. Record its `runId`.
+
+#### 4e. Update progress + re-resolve dependencies
+For each shipped story: move it to `stories_completed` with a compact one-line outcome tagged with its epic; update `total_completed` / `last_updated`; **FIFO at 80 lines** (evict oldest). Read and follow `.valent-pipeline/steps/orchestration/update-backlog-status.md`. Then **re-check whether any previously blocked stories are now unblocked** (their `depends_on` / `blocked_by_bugs` may have been resolved by what just shipped) — these become eligible for the next sprint's candidate list.
+
+#### 4f. Retrospective (mandatory, blocking)
+Invoke `retro.workflow.js`:
+
+```js
+Workflow({
+  scriptPath: '.valent-pipeline/orchestrators/claude-code/retro.workflow.js',
+  args: { batchNumber: {n}, sprintId: 'project-sprint-{n}' }
+})
+```
+
+Record its `runId`. Retro runs every sprint and tightens future sizing.
+
+#### 4g. Continue
+Increment `{n}` and return to Step 4a. **Do NOT ask permission to continue between sprints** — the project loop is autonomous.
+
+### Step 5: Project Complete
+
+When all stories are shipped (or remaining are all blocked/cancelled), write `project-report.md` (same content as `/valent-run-project` Step 5a: totals, sprint history, per-epic summary, estimation accuracy, blocked stories with recommended actions, outstanding cross-epic bugs) and present the completion summary, highlighting blocked stories, pending conditional-ship bugs, and the velocity/accuracy trend.
+
+### All Stories Blocked
+
+If the loop finds no unblocked stories but pending stories remain, list each blocked story with its unmet dependencies and ask the user how to proceed (fix blockers and re-run / cancel blocked stories / override a dependency). Do NOT loop forever waiting on blockers.
+
+## Resume (do NOT restart from scratch)
+
+Two layers of durability:
+
+1. **Within a single Workflow run** (a plan, sprint, or retro): every invocation returns a `runId`. If one is interrupted, relaunch **that** workflow with `Workflow({ scriptPath, resumeFromRunId: <runId> })` — the journal replays the unchanged prefix instantly and re-runs only from the first changed/new `agent()` call.
+2. **Across the sprint loop**: the progress file (`epic_id: "project"`) + `{backlog_path}` record what shipped and which sprint is current. On a full conversation reset, re-run `/valent-run-project-workflow`; Step 3 detects the existing progress file and resumes at the next unfinished sprint. Shipped stories are not re-run.
+
+Do **not** hand-edit state files to "resume" a Workflow — pass `resumeFromRunId`.
+
+## Notes
+
+- The **journal is the state of record** inside each Workflow; the progress file / `sprint-{n}-status.yaml` / handoffs are derived human-readable views.
+- **Known simplifications:** a CRITIC rejection re-runs ALL dev agents (not just the targeted one); no PMCP/visual-validation stage yet; no PM review/audit stage in the Workflow path (that remains agent-driven in `/valent-run-project`). See `.valent-pipeline/orchestrators/claude-code/README.md`.
+- Do **not** adopt the Lead persona or read `lead.md` — orchestration here is the three Workflow scripts.
+- Correction directives may not exist yet for new pipelines — the workflows proceed without them gracefully.

package/skills/valent-run-story/SKILL.md

@@ -57,17 +57,7 @@ Set `{is_epic_run}` = false. Set `{is_sprint_mode}` = false. This is a standalon
 
 Enter monitoring mode — follow `.valent-pipeline/prompts/lead.md` for monitoring, exception handling, and ship/teardown.
 
-### Step 5 (alternative): Claude Code native Workflow — experimental, opt-in
-
-When `runtime.provider` is `claude-code` **and** the user has opted into the native Workflow orchestrator, skip the prose Lead (Step 5) and instead invoke the Workflow at `.valent-pipeline/orchestrators/claude-code/sprint.workflow.js` via the Workflow tool. Pass either `args: { storyId, projectType, profiles, maxRejectionCycles }` for a single story, or `args: { stories: [{ storyId, projectType, profiles }, ...], maxRejectionCycles }` for a planned sprint batch (run sequentially — see below). It resolves each story's task graph deterministically (`resolve-graph`), runs READINESS/CRITIC/JUDGE as schema-validated gates with a code-owned rejection cap, runs CRITIC's three passes as independent parallel agents (3b) before a triage barrier, and gains journal-based resume (`resumeFromRunId`). A story that JUDGE rejects (or that trips the rejection cap) is recorded as rolled-over and the batch continues.
-
-To plan a sprint first, invoke `plan.workflow.js` (`args: { stories: [{ storyId, projectType }], sprintId, velocity }`) — it grooms/sizes/packs and returns a `{ sprintId, stories: [...] }` batch you pass straight to `sprint.workflow.js`. After a batch ships, invoke `retro.workflow.js` (`args: { batchNumber, sprintId }`) to learn from it.
-
-**Resume (do not restart from scratch).** Every Workflow invocation returns a `runId`. If a run is interrupted — context limit, crash, manual stop, or a mid-run edit — **relaunch it with `Workflow({ scriptPath, resumeFromRunId: <that runId> })`**, not a fresh invocation. The journal replays the unchanged prefix of `agent()` calls instantly (same script + same args → 100% cache hit) and only re-runs from the first changed/new call onward, so already-shipped stories and passed gates are not redone. This is the durability the prose Lead approximated by re-reading `pipeline-state.json` and re-deciding; here it is exact. Do **not** hand-edit state files to "resume" — pass `resumeFromRunId`.
-
-**State model.** In the Workflow path the **journal is the state of record.** `pipeline-state.json`, `sprint-{n}-status.yaml`, and the markdown handoffs are **derived, human-readable views** that agents write for visibility — the orchestrator never reads them back to make control-flow decisions (its state lives in JS variables captured by the journal). This is why the non-atomic multi-file desync the prose Lead can hit is structurally impossible here: there is no multi-file state of record to desync. (The prose Lead path still uses `pipeline-state.json` as its mechanism — that's correct for that runtime.)
-
-**Status:** the orchestrators' control flow is validated (`scripts/test-workflow.js`, incl. a resume-safety lint) but it is **not yet the default** — it has not been exercised end-to-end against a live story. Until it has, the prose Lead (Step 5 above) remains the default for `claude-code`, and Codex always uses the prose Lead. See `.valent-pipeline/orchestrators/claude-code/README.md`.
+> **Want the native Workflow orchestrator instead?** This skill is the prose-Lead path. The deterministic Claude Code Workflow orchestrator (schema-validated gates, code-owned rejection cap, journal resume) is a separate, linear skill — run **`/valent-run-story-workflow`**. Epic and project runs have Workflow variants too: `/valent-run-epic-workflow` and `/valent-run-project-workflow`.
 
 ## Notes
 

package/skills/valent-run-story-workflow/SKILL.md

@@ -0,0 +1,76 @@
+---
+name: valent-run-story-workflow
+description: 'Run a story through the v3 pipeline using the native Claude Code Workflow orchestrator (deterministic control flow, schema-validated gates, journal resume). Use when the user says "run story workflow", "workflow run", or "run story with the workflow orchestrator".'
+argument-hint: '<story-id or path>'
+---
+
+# valent-run-story-workflow
+
+Run a single story through the v3 pipeline using the **native Claude Code Workflow orchestrator** — a deterministic Workflow script that resolves the task graph in code, runs READINESS/CRITIC/JUDGE as schema-validated gates with a code-owned rejection cap, runs CRITIC's three passes as independent parallel agents before a triage barrier, and gains journal-based resume.
+
+This is the Workflow path. There is **no prose Lead** here and **no branching** — the orchestration logic lives in `sprint.workflow.js`, not in this skill. For the prose-Lead orchestrator, use `/valent-run-story` instead.
+
+> **Status — experimental.** The orchestrator's control flow is validated (`scripts/test-workflow.js`, incl. a resume-safety lint) but has **not yet been exercised end-to-end against a live story**. Validate against a `testResources/*` fixture before relying on it. The prose-Lead path (`/valent-run-story`) remains the supported default.
+
+## Arguments
+
+The user provides a story ID or path as the argument:
+- Story ID: `STORY-042` (resolved to `{story_directory}/STORY-042`)
+- Relative path: `./stories/STORY-042` (used directly)
+
+If no argument is provided, resolve the next work item from the backlog (see Step 1b).
+
+## Execution Steps
+
+### Step 0: Pre-Flight — runtime + MCP
+
+1. **Runtime guard.** Read `.valent-pipeline/pipeline-config.yaml`. The Workflow tool is Claude Code only — if `runtime.provider` is not `claude-code`, **STOP** with: `The Workflow orchestrator requires runtime.provider: claude-code. This project uses {provider}. Run /valent-run-story for the prose-Lead orchestrator instead.`
+2. **Visual validation MCP.** If `project.type` is `fullstack-web` or `frontend-only`, verify `{tech_stack.browser_automation_mcp}` is accessible (e.g., `npx @anthropic-ai/playwright-mcp --version`, or check `.claude/settings.json` for the MCP registration). If not accessible → **STOP** with: `Browser automation MCP ({tech_stack.browser_automation_mcp}) is not installed. Install it with: npx valent-pipeline init --force (or npm install -g @playwright/mcp). Then re-run.` *(Note: the Workflow path has no PMCP/visual-validation stage yet — this guard is forward-looking and matches the prose-Lead skill's prerequisite.)*
+
+### Step 1: Load Pipeline Config
+
+Read and follow `.valent-pipeline/steps/orchestration/load-pipeline-config.md`. Capture `project.type` and the story's `testing_profiles` — these become the Workflow's `projectType` and `profiles` args.
+
+### Step 1b: Resolve Next Work Item (when no argument provided)
+
+Read and follow `.valent-pipeline/steps/orchestration/resolve-next-work-item.md`.
+
+Do NOT set `{epic_filter}` — standalone story runs use the full backlog.
+
+### Step 2: Resolve Story Path
+
+Read and follow `.valent-pipeline/steps/orchestration/resolve-story-path.md`.
+
+### Step 3: Validate Story Inputs
+
+Read and follow `.valent-pipeline/steps/orchestration/validate-story-inputs.md`.
+
+### Step 4: Invoke the Workflow
+
+Invoke the Workflow at `.valent-pipeline/orchestrators/claude-code/sprint.workflow.js` via the **Workflow tool** with single-story args:
+
+```js
+Workflow({
+  scriptPath: '.valent-pipeline/orchestrators/claude-code/sprint.workflow.js',
+  args: { storyId: '<resolved story id>', projectType: '<project.type>', profiles: [/* testing_profiles */], maxRejectionCycles: <quality.max_rejection_cycles or 5> }
+})
+```
+
+It resolves the story's task graph deterministically (`resolve-graph`), runs the per-story pipeline inline with schema-validated gates, and returns:
+
+```js
+{ shipped, stories_shipped, stories_rolled_over, results: [{ storyId, shipped, verdict, skipped }] }
+```
+
+Report the returned verdict and the `runId` to the user. A story that JUDGE rejects (or that trips the rejection cap) is recorded as rolled-over — surface that outcome; do not silently retry.
+
+### Step 5: Resume (do NOT restart from scratch)
+
+Every Workflow invocation returns a `runId`. If a run is interrupted — context limit, crash, manual stop, or a mid-run script edit — **relaunch with `Workflow({ scriptPath, resumeFromRunId: <that runId> })`**, not a fresh invocation. The journal replays the unchanged prefix of `agent()` calls instantly (same script + same args → 100% cache hit) and re-runs only from the first changed/new call onward, so already-shipped stories and passed gates are not redone. Do **not** hand-edit state files to "resume" — pass `resumeFromRunId`.
+
+## Notes
+
+- **State model.** The **journal is the state of record.** `pipeline-state.json`, `sprint-{n}-status.yaml`, and the markdown handoffs are **derived, human-readable views** that agents write for visibility — the orchestrator never reads them back to make a control-flow decision (its state lives in JS variables the journal captures). The non-atomic multi-file desync the prose Lead can hit is structurally impossible here.
+- **Planned sprint batches.** To run a planned batch instead of one story, pass `args: { stories: [{ storyId, projectType, profiles }, ...], maxRejectionCycles }`. Produce that batch by running `plan.workflow.js` first (`args: { stories: [{ storyId, projectType }], sprintId, velocity }`), then feed its `{ sprintId, stories: [...] }` straight into `sprint.workflow.js`. After a batch ships, run `retro.workflow.js` (`args: { batchNumber, sprintId }`) to learn from it. There is no `sprint-cycle` wrapper yet — run the three in sequence.
+- **Known simplifications.** A CRITIC rejection currently re-runs ALL dev agents (not just the targeted one); there is no PMCP/visual-validation stage in the Workflow path yet. See `.valent-pipeline/orchestrators/claude-code/README.md`.
+- Do **not** adopt the Lead persona or read `lead.md` in this skill — that is the prose-Lead path. The orchestration here is the Workflow script.