valent-pipeline 0.5.6 → 0.6.0

package/README.md

@@ -17,7 +17,7 @@ npx valent-pipeline init
 /valent-configure
 
 # Execute a story
-/valent-run-story STORY-001
+/valent-run-story-workflow STORY-001
 ```
 
 > **No global install required.** `npx valent-pipeline init` copies the CLI (`bin/` + `src/`)
@@ -224,14 +224,10 @@ Invoked as slash commands inside Claude Code:
 | Skill | Description |
 |---|---|
 | `/valent-configure` | Interactive configuration wizard |
-| `/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-story-workflow STORY-ID` | Execute a single story via the Claude Code **Workflow** orchestrator |
+| `/valent-run-epic-workflow EPIC-ID` | Execute an epic (sprint planning + execution) via the **Workflow** orchestrator |
+| `/valent-run-project-workflow` | Execute a full project across all epics via the **Workflow** orchestrator |
 | `/valent-run-deferred-tests` | Run deferred iOS tests on Mac |
 | `/valent-debug-export` | Export diagnostic dump |
 | `/valent-help` | Pipeline documentation and FAQ |
@@ -270,9 +266,7 @@ For each story, the pipeline produces 15+ artifacts in `stories/{story-id}/outpu
 | `readiness-review.md` | READINESS | Spec gate results |
 | `judge-review.md` | JUDGE | Bug review findings |
 | `judge-decision.md` | JUDGE | Ship/reject decision with evidence |
-| `pmcp-evidence.md` | PMCP | Visual validation screenshots |
-| `story-report.md` | Lead | Story completion summary |
-| `decisions.md` | *(any)* | Design Council deliberation log |
+| `story-report.md` | orchestrator | Story completion summary |
 
 Plus committed, tested production code in your project source tree.
 
@@ -308,15 +302,14 @@ 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):
+The pipeline runs on a single orchestration path: the **Claude Code Workflow** path. 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`). Control flow lives in JavaScript and the journal — not in a model interpreting prose. 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`.
 
-- **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`.
+> Requires Claude Code (the Workflow tool). `runtime.provider` must be `claude-code`.
 
 ### Single Story
 
 ```
-/valent-run-story STORY-001
+/valent-run-story-workflow STORY-001
 ```
 
 Executes one story through the full pipeline.
@@ -324,7 +317,7 @@ Executes one story through the full pipeline.
 ### Epic (Sprint-Based)
 
 ```
-/valent-run-epic EPIC-001
+/valent-run-epic-workflow EPIC-001
 ```
 
 Runs an epic with sprint planning: grooms stories, estimates sizing using calibrated Fibonacci points, plans sprints, executes stories in priority order, and runs retrospectives between sprints.
@@ -332,7 +325,7 @@ Runs an epic with sprint planning: grooms stories, estimates sizing using calibr
 ### Full Project
 
 ```
-/valent-run-project
+/valent-run-project-workflow
 ```
 
 Executes all epics in the backlog with cross-epic dependency resolution.
@@ -392,12 +385,12 @@ After initialization, the pipeline installs to `.valent-pipeline/` in your proje
 ```
 .valent-pipeline/
   pipeline-config.yaml        # Your project configuration
-  pipeline-state.json         # Pipeline runtime state
-  agents-manifest.yaml        # Agent definitions and dependencies
-  prompts/                    # Agent prompt templates (21 files)
-  templates/                  # Handoff document templates (27 files)
-  task-graphs/                # Task dependency graphs per project type (8 files)
-  steps/                      # Agent step files (114 files)
+  pipeline-state.json         # Pipeline runtime state (derived, human-readable view)
+  orchestrators/claude-code/  # Workflow orchestrator scripts (plan/sprint/retro)
+  prompts/                    # Agent prompt templates
+  templates/                  # Handoff document templates
+  task-graphs/                # Task dependency graphs per project type
+  steps/                      # Agent step files
     bend/                     #   Backend developer steps
     fend/                     #   Frontend developer steps
     critic/                   #   Code review steps
@@ -406,7 +399,7 @@ After initialization, the pipeline installs to `.valent-pipeline/` in your proje
     reqs/                     #   Requirements analysis steps
     readiness/                #   Readiness gate steps
     judge/                    #   Judge gate steps
-    orchestration/            #   Lead orchestration steps
+    orchestration/            #   Shared orchestration steps (config, story resolution, status)
     retrospective/            #   Retrospective analysis steps
     common/                   #   Shared agent protocols
     data/                     #   Data pipeline developer steps

package/package.json

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

package/pipeline/docs/agent-reference.md

@@ -1,109 +1,130 @@
-# V3 Agent Reference
+# Agent Reference
 
-> Quick reference for all agents in the v3 pipeline.
-> Definitive source: `.valent-pipeline/agents-manifest.yaml`
+> Quick reference for all agents in the pipeline.
+> Definitive source: `pipeline-config.yaml` `models:` (per-agent model tier) and
+> `pipeline/task-graphs/*.yaml` (which agents run per project type).
+
+---
+
+## Orchestration
+
+There is one orchestration path: the Claude Code **Workflow** path. It requires Claude Code
+(`runtime.provider` must be `claude-code`). The workflow scripts in
+`pipeline/orchestrators/claude-code/` own all control flow — they spawn agents as subagents,
+wire dependencies, and manage each story's lifecycle. There is no "Lead" agent or persona that
+spawns or monitors a team.
+
+| Workflow | Script | Responsibility |
+|---|---|---|
+| Plan | `plan.workflow.js` | Backlog grooming, sizing, sprint packing |
+| Sprint | `sprint.workflow.js` | Runs the per-story agent graph for each story in the sprint |
+| Retro | `retro.workflow.js` | Post-sprint retrospective → correction directives |
+
+Per-story agent selection is deterministic. The Sprint workflow reads `project_type` and the
+story's `testing_profiles`, then resolves the task graph for that type via
+`node .valent-pipeline/bin/cli.js resolve-graph --type <project_type> --profiles <list>` over
+`pipeline/task-graphs/<type>.yaml`. The resolver evaluates `conditional` / `skip_when`
+predicates and prunes dropped refs from every dependency, so no dangling dependency survives a
+skip. Per-agent model tier comes from `pipeline-config.yaml` `models:` (a tier→roles map for
+`opus` / `sonnet` / `haiku`), which the workflow passes to each spawned subagent.
+
+> Removed in v0.6.0: the Lead agent (orchestration is now the JS workflow), the PM and PMCP
+> agents (archived for a future Workflow stage, not currently run), the Help agent (use the
+> `/valent-help` skill), the Embed agent (embedding is now the `db embed` CLI step), the Codex
+> runtime, and `agents-manifest.yaml`.
 
 ---
 
 ## Agent Roster
 
-### Core Per-Story Agents (10)
+### Spec & Gate Agents
 
-Spawned fresh for each story and torn down after the story ships or is cancelled. These agents form the standard pipeline flow regardless of project type.
+Run once per story, in dependency order, before and around implementation.
 
 | Agent | Model | Role | Reads | Writes | Key Behavior |
 |-------|-------|------|-------|--------|--------------|
-| REQS | Sonnet | Requirements analyst -- translates ACs into implementation brief | story-input (ACs, trigger-map, architecture-decisions, UX spec) | `reqs-brief.md` | Brainstorms ambiguity resolutions; loads domain-specific step files per testing profile; escalates only when options have genuinely competing tradeoffs |
-| UXA | Sonnet | UX specification -- translates UX spec into component specs | `reqs-brief.md`, ux-spec, trigger-map, scenarios | `uxa-spec.md` | Runs translation-only mode without trigger-map or scenarios; skipped for backend-only projects |
-| QA-A | Sonnet | QA spec writer -- produces behavioral test specifications | `reqs-brief.md`, `uxa-spec.md` | `qa-test-spec.md`, `visual-validation-checklist.md` | Writes test specs before code exists; risk-based test depth (P0-P3); domain-specific step files per project type |
-| READINESS | Sonnet | Spec quality gate -- validates specs before execution begins | `reqs-brief.md`, `uxa-spec.md`, `qa-test-spec.md` | `readiness-review.md` | Sequential review: stops on first failure; routes rejection to responsible upstream agent |
-| BEND | Sonnet | Backend developer -- implements production code and tests | `reqs-brief.md`, `qa-test-spec.md` | `bend-handoff.md` | Implements to QA-A test spec; coordinates with FEND via inbox for shared files; fullstack-web and backend-api only |
-| FEND | Sonnet | Frontend developer -- implements UI components and tests | `reqs-brief.md`, `uxa-spec.md`, `qa-test-spec.md` | `fend-handoff.md` | Implements to UXA component spec; fullstack-web and frontend-only only |
-| CRITIC | Opus | Code reviewer -- 3-pass adversarial review | git-diff, `reqs-brief.md`, `qa-test-spec.md` | `critic-review.md` | 3-pass sequential review (blind hunt, edge-case hunt, acceptance audit) + triage; domain-specific review steps per project type |
-| QA-B | Sonnet | Test executor -- runs tests, validates spec alignment, files bugs | `qa-test-spec.md`, `critic-review.md`, `reqs-brief.md` | `execution-report.md`, `bugs.md`, `traceability-matrix.md` | Runs tests against real infrastructure; domain-specific execution steps; can request PMCP spawn for visual validation |
-| JUDGE | Sonnet | Final quality gate -- bug review + ship decision | `execution-report.md`, `traceability-matrix.md`, `pmcp-evidence.md`, `bugs.md`, `qa-test-spec.md` | `judge-review.md`, `judge-decision.md`, `story-report.md` | Evidence over assertion -- independently verifies every upstream claim |
-| Knowledge | Haiku | Knowledge retrieval -- answers queries from persistent data sources | chromadb, curated-knowledge-files, correction-directives | _(none -- inbox only)_ | Responds via inbox only; no file output; uses CLI db commands for SQLite queries |
-
-### Domain Developer Agents (6)
-
-Specialized developer agents that replace or supplement BEND/FEND for specific project types. Each has its own prompt, step files, handoff template, and domain-specific QA-A/QA-B/CRITIC steps.
-
-| Agent | Model | Role | Project Type | Reads | Writes | Key Domain |
-|-------|-------|------|-------------|-------|--------|------------|
+| REQS | Sonnet | Requirements analyst — translates ACs into implementation brief | story-input (ACs, trigger-map, architecture-decisions, UX spec) | `reqs-brief.md` | Brainstorms ambiguity resolutions; loads domain-specific step files per testing profile; escalates only when options have genuinely competing tradeoffs |
+| UXA | Sonnet | UX specification — translates UX spec into component specs | `reqs-brief.md`, ux-spec, trigger-map, scenarios | `uxa-spec.md` | Translation-only mode without trigger-map or scenarios; skipped when `testing_profiles` excludes `ui` |
+| QA-A | Sonnet | QA spec writer — produces behavioral test specifications | `reqs-brief.md`, `uxa-spec.md` | `qa-test-spec.md`, `visual-validation-checklist.md` | Writes test specs before code exists; risk-based test depth (P0–P3); domain-specific step files per project type |
+| READINESS | Opus | Spec quality gate — validates specs before execution begins | `reqs-brief.md`, `uxa-spec.md`, `qa-test-spec.md` | `readiness-review.md` | Sequential review: stops on first failure; routes rejection to responsible upstream agent |
+| CRITIC | Opus | Code reviewer — 3 independent parallel review passes + triage | git-diff, `reqs-brief.md`, `qa-test-spec.md` | `critic-review.md` | Three parallel review passes (blind hunt, edge-case hunt, acceptance audit) feed a triage step that produces a single verdict; domain-specific review steps per project type |
+| QA-B | Sonnet | Test executor — runs tests, validates spec alignment, files bugs | `qa-test-spec.md`, `critic-review.md`, `reqs-brief.md` | `execution-report.md`, `bugs.md`, `traceability-matrix.md` | Runs tests against real infrastructure; domain-specific execution steps |
+| JUDGE | Opus | Final quality gate — bug review + ship decision | `execution-report.md`, `traceability-matrix.md`, `bugs.md`, `qa-test-spec.md` | `judge-review.md`, `judge-decision.md`, `story-report.md` | Evidence over assertion — independently verifies every upstream claim |
+
+### Developer Agents
+
+The Sprint workflow selects implementation agents from the resolved task graph based on the
+story's `testing_profiles`. Each has its own prompt, step files, handoff template, and
+domain-specific QA-A / QA-B / CRITIC steps.
+
+| Agent | Model | Role | Selected when | Reads | Writes | Key Domain |
+|-------|-------|------|---------------|-------|--------|------------|
+| BEND | Sonnet | Backend developer | `api` profile (fullstack-web, backend-api) | `reqs-brief.md`, `qa-test-spec.md` | `bend-handoff.md` | Production backend code + tests; coordinates with FEND on shared files |
+| FEND | Sonnet | Frontend developer | `ui` profile (fullstack-web, frontend-only) | `reqs-brief.md`, `uxa-spec.md`, `qa-test-spec.md` | `fend-handoff.md` | UI components + tests; implements to UXA component spec |
 | DATA | Sonnet | Data pipeline developer | `data-pipeline` | `reqs-brief.md`, `qa-test-spec.md` | `data-handoff.md` | ETL/transforms, idempotency, checkpointing, row-level logging |
 | MCP-DEV | Sonnet | Protocol developer | `mcp-server` | `reqs-brief.md`, `qa-test-spec.md` | `mcp-dev-handoff.md` | JSON-RPC/stdio, two-tier error model, tool registration |
 | LIBDEV | Sonnet | Library developer | `library` | `reqs-brief.md`, `qa-test-spec.md` | `libdev-handoff.md` | Public API, exports/packaging, CJS/ESM, semver, type declarations |
 | DOCGEN | Sonnet | Document generation developer | `document-generation` | `reqs-brief.md`, `qa-test-spec.md` | `docgen-handoff.md` | Template engine, render pipeline, encoding, assets |
-| IAC | Sonnet | Infrastructure developer | Cross-cutting (any type) | `reqs-brief.md`, `qa-test-spec.md` | `iac-handoff.md` | Terraform/Pulumi/CloudFormation, K8s, CI/CD, IAM |
+| IAC | Sonnet | Infrastructure developer | `iac` profile (cross-cutting, any type) | `reqs-brief.md`, `qa-test-spec.md` | `iac-handoff.md` | Terraform/Pulumi/CloudFormation, K8s, CI/CD, IAM |
 | MOBILE | Sonnet | Mobile developer | `mobile-app` | `reqs-brief.md`, `uxa-spec.md`, `qa-test-spec.md` | `mobile-handoff.md` | React Native/Flutter, Maestro E2E, emulator lifecycle, iOS deferral |
 
 **Notes:**
 - DATA, MCP-DEV, LIBDEV, DOCGEN each replace BEND in their dedicated task graph.
-- IAC is cross-cutting -- it slots into ANY task graph when `iac` is in `testing_profiles`, running in parallel with the primary developer agent.
-- MOBILE replaces BEND for mobile-app projects; BEND can still be conditionally included if `testing_profiles` includes `api`.
-- Each domain agent has 5 standard steps: read-inputs, implement, write-tests, handoff, estimate.
+- IAC is cross-cutting — it slots into ANY task graph when `iac` is in `testing_profiles`, running in parallel with the primary developer agent.
+- MOBILE replaces BEND for mobile-app projects; BEND can still be conditionally included when `testing_profiles` includes `api`.
 - See the agent prompts in `pipeline/prompts/` and step files in `pipeline/steps/` for full implementation details.
 
-### Persistent Agent (1)
-
-Lives across stories. Manages the backlog and orchestrates each story team.
-
-| Agent | Model | Role | Reads | Writes | Key Behavior |
-|-------|-------|------|-------|--------|--------------|
-| Lead | Opus | Pipeline orchestrator -- spawns team, monitors execution, manages story lifecycle | story-input, `agents-manifest.yaml`, `pipeline-config.yaml`, `pipeline-state.json` | `story-report.md`, `pipeline-state.json` | Builds task graph from manifest; enforces circuit breaker on rejection loops; escalates to user as last resort |
-
-### Ephemeral Agents (4)
-
-Spawned on-demand by the Lead when triggered by specific events.
+### Cross-Story Agents
 
-| Agent | Model | Role | Reads | Writes | Trigger |
-|-------|-------|------|-------|--------|---------|
-| PMCP | Sonnet | Visual validation -- browser automation MCP, captures screenshots | `visual-validation-checklist.md` | `pmcp-evidence.md` | Requested by QA-B, BEND, or FEND |
-| Embed | Haiku | Knowledge indexer -- indexes curated patterns into knowledge base | _(retrospective output)_ | _(indexing instructions)_ | After Retrospective agent curates what to index |
-| Retrospective | Sonnet | Batch reviewer -- analyzes last N stories for recurring patterns | _(story reports)_ | _(retrospective report)_ | Every N stories (configurable) |
-| Help | Haiku | Pipeline help -- explains any piece of the pipeline from documentation | `.valent-pipeline/docs/` | _(inbox only)_ | User request |
+| Agent | Model | Role | Reads | Writes | When |
+|-------|-------|------|-------|--------|------|
+| Retrospective | Opus | Learns after a sprint — analyzes outcomes for recurring patterns | story reports | correction directives | Run by the Retro workflow after a sprint |
+| Knowledge | Haiku | Knowledge retrieval — answers queries during execution | chromadb, curated-knowledge-files, correction-directives | _(none — inbox only)_ | Responds via inbox only; uses CLI `db` commands for SQLite queries |
 
 ---
 
 ## Project-Type Agent Selection
 
-Not all agents run for every project type. The Lead reads `project_type` from `pipeline-config.yaml`, selects the appropriate task graph, and spawns only the agents that apply.
+The Sprint workflow resolves the task graph for the project's `project_type` and prunes agents
+the story's `testing_profiles` do not require.
 
-| Project Type | Developer Agent(s) | Agents Skipped | Task Graph |
+| Project Type | Developer Agent(s) | Typically Skipped | Task Graph |
 |---|---|---|---|
 | `fullstack-web` | BEND + FEND | _(none)_ | `fullstack-web.yaml` |
-| `backend-api` | BEND | UXA, FEND, PMCP | `backend-api.yaml` |
+| `backend-api` | BEND | UXA, FEND | `backend-api.yaml` |
 | `frontend-only` | FEND | BEND | `frontend-only.yaml` |
-| `data-pipeline` | DATA | UXA, FEND, PMCP | `data-pipeline.yaml` |
-| `mcp-server` | MCP-DEV | UXA, FEND, PMCP | `mcp-server.yaml` |
-| `document-generation` | DOCGEN | UXA, FEND, PMCP | `document-generation.yaml` |
-| `library` | LIBDEV | UXA, FEND, PMCP | `library.yaml` |
-| `mobile-app` | MOBILE (+ BEND if api profile) | *(conditional)* | `mobile-app.yaml` |
+| `data-pipeline` | DATA | UXA, FEND | `data-pipeline.yaml` |
+| `mcp-server` | MCP-DEV | UXA, FEND | `mcp-server.yaml` |
+| `document-generation` | DOCGEN | UXA, FEND | `document-generation.yaml` |
+| `library` | LIBDEV | UXA, FEND | `library.yaml` |
+| `mobile-app` | MOBILE (+ BEND if `api` profile) | _(conditional)_ | `mobile-app.yaml` |
 
 **Conditional agents (any project type):**
-- **IAC** -- spawned when `testing_profiles` includes `iac`; runs in parallel with the primary developer agent
-- **PMCP** -- spawned when `testing_profiles` includes `ui`; triggered by QA-B for visual validation
-- **UXA** -- can be conditionally skipped even for UI projects if `testing_profiles` excludes `ui`
+- **IAC** — included when `testing_profiles` includes `iac`; runs in parallel with the primary developer agent.
+- **UXA / FEND** — pruned when `testing_profiles` excludes `ui`, even for an otherwise UI-capable project type.
 
 ---
 
 ## Model Tier Summary
 
-Default assignments from `config-schema.js`:
+Default assignments from `pipeline-config.yaml` `models:` (validated by `src/lib/config-schema.js`):
 
 | Tier | Agents | Use Case | Cost |
 |------|--------|----------|------|
-| Opus | Lead, CRITIC | Orchestration, nuanced multi-pass code review | Highest |
-| Sonnet | REQS, UXA, QA-A, QA-B, READINESS, JUDGE, PMCP, Retrospective, BEND, FEND, DATA, MCP-DEV, LIBDEV, DOCGEN, IAC, MOBILE | Analysis, spec writing, implementation, test execution, judgment | Balanced |
-| Haiku | Knowledge, Embed, Help | Mechanical retrieval, indexing instructions, documentation lookups | Lowest |
+| Opus | READINESS, CRITIC, JUDGE, Retrospective | Quality gates + high-judgment review | Highest |
+| Sonnet | REQS, UXA, QA-A, QA-B, BEND, FEND, DATA, MCP-DEV, LIBDEV, DOCGEN, IAC, MOBILE | Spec writing, implementation, test execution | Balanced |
+| Haiku | Knowledge, CLI-runner steps (resolve/pack/validate/calibrate/persist) | Mechanical retrieval and IO; no reasoning | Lowest |
 
-Model assignments are configurable in `pipeline-config.yaml` under the `models` section. Move agents between tiers to adjust the quality/cost tradeoff for your project.
+Embedding runs as the `db embed` CLI step, not an agent. Model assignments are configurable in
+`pipeline-config.yaml` under the `models` section — move a role between tiers to adjust the
+quality/cost tradeoff.
 
 ---
 
 ## Step File Architecture
 
-Each agent has domain-specific step files that provide detailed execution instructions. Step files live in `pipeline/steps/{agent}/` and are referenced by the agent's prompt.
+Each agent has domain-specific step files that provide detailed execution instructions. Step
+files live in `pipeline/steps/{agent}/` and are referenced by the agent's prompt.
 
 ### Shared Steps (`common/`)
 
@@ -117,7 +138,8 @@ Each agent has domain-specific step files that provide detailed execution instru
 
 ### Domain-Specific Steps
 
-QA-A, QA-B, CRITIC, and REQS each have domain-specific step files that load based on the project's `testing_profiles`:
+QA-A, QA-B, CRITIC, and REQS each have domain-specific step files that load based on the
+story's `testing_profiles`:
 
 | Profile | QA-A Step | QA-B Step | CRITIC Step | REQS Step |
 |---|---|---|---|---|

package/pipeline/docs/communication-standard.md

@@ -1,6 +1,6 @@
-# V3 Distilled Communication Standard
+# Distilled Communication Standard
 
-> **Canonical reference for all agent-to-agent communication in the v3 pipeline.**
+> **Canonical reference for all agent-to-agent communication in the pipeline (Workflow path).**
 > Every agent prompt and every handoff template references this document.
 > If your output violates a rule below, CRITIC or JUDGE will flag it.
 
@@ -136,17 +136,17 @@ let's discuss the auth middleware.
 
 ### Rule 6: TL;DR orchestrator summary first
 
-**Rationale:** The lead agent monitors all teammates. It must be able to scan the state of any handoff in seconds. Every handoff document starts with a structured summary block (see Section 4) so the lead never needs to read the full document to know: who produced it, what story, pass/fail, what state transition occurred, and what files changed.
+**Rationale:** The workflow orchestrator collects each agent's result and sequences the pipeline. It must be able to scan the state of any handoff in seconds. Every handoff document starts with a structured summary block (see Section 4) so the orchestrator never needs to read the full document to know: who produced it, what story, pass/fail, what state transition occurred, and what files changed.
 
 **Good:** See the Orchestrator Summary Block format in Section 4.
 
-**Bad:** A handoff document that starts with three paragraphs of context before the lead can determine whether the phase passed or failed.
+**Bad:** A handoff document that starts with three paragraphs of context before the orchestrator can determine whether the phase passed or failed.
 
 ---
 
 ## 3. YAML Frontmatter Schema
 
-Every handoff file begins with this YAML frontmatter block. It is the machine-readable metadata envelope that agents and the lead use to track pipeline state.
+Every handoff file begins with this YAML frontmatter block. It is the machine-readable metadata envelope that agents and the workflow orchestrator use to track pipeline state.
 
 ```yaml
 ---
@@ -182,7 +182,7 @@ correctionsApplied: []       # (optional) correction directive IDs applied durin
 
 ## 4. Orchestrator Summary Block
 
-Immediately after the YAML frontmatter, every handoff document includes this block. It is the TL;DR that the lead agent reads to understand the state of the phase without parsing the full document.
+Immediately after the YAML frontmatter, every handoff document includes this block. It is the TL;DR that the workflow orchestrator reads to understand the state of the phase without parsing the full document. In the Workflow path, the agent's structured return (these machine-block fields, surfaced as JSON) is what the orchestrator script collects as the handoff.
 
 ```markdown
 ## Orchestrator Summary
@@ -224,30 +224,30 @@ Immediately after the YAML frontmatter, every handoff document includes this blo
 - **Verdict:** fail
 - **State transition:** critic-review -> bend-rework
 - **Files created/modified:** stories/STORY-042/output/critic-review.md
-- **Flags:** Second rejection on error handling; consider Design Council if next iteration fails
+- **Flags:** Second rejection on error handling; rework cap is approaching
 ```
 
 ---
 
-## 5. Inbox Message Format
+## 5. Inter-Agent Signal Vocabulary
 
-Inbox messages are for **coordination only**. Handoff documents are never sent via inbox -- they are written to the story output directory and discovered by consuming agents through the task system.
+This is the **signal vocabulary** agent prompts use to express coordination intent (notifications, questions, bug reports, escalation). Handoff documents are never sent as messages -- they are written to the story output directory. In the Workflow path, sequencing and coordination are performed by the orchestrator script, which collects each agent's structured return and routes work; these signals are the standardized phrasing an agent uses inside that return rather than messages relayed through a persistent inbox.
 
-### Valid message types
+### Valid signal types
 
 | Type | Purpose | Example |
 |------|---------|---------|
 | Notification | Signal task completion or state change | "BEND task `implement-api` completed. Output: `bend-handoff.md`" |
-| Question | Request specific information from a peer | "FEND -> BEND: What did you name the tenant creation endpoint?" |
+| Question | Request specific information from a peer phase | "FEND -> BEND: What did you name the tenant creation endpoint?" |
 | Bug report | Terse summary with pointer to shared file | "Bug P1: tenant creation returns 500 with unicode input. See `bugs.md#BUG-003`" |
 | Design Council | Structured deliberation (see Section 6) | Uses `[DESIGN-COUNCIL]` prefix format |
-| Escalation | Request lead intervention | "Escalation: CRITIC rejected BEND 3 times on same issue. See `critic-review.md#rejection-3`" |
+| Escalation | Surface a blocker requiring human input | "Escalation: CRITIC rejected BEND 3 times on same issue. See `critic-review.md#rejection-3`" |
 
 ### Format rules
 
-1. **Terse references with pointers.** Detail lives in shared files, not in the message body.
-2. **Max ~500 tokens.** Inbox messages are short coordination signals, not documents.
-3. **Include the file pointer.** If the message references work product, include the path: `bugs.md#BUG-003`, `bend-handoff.md#error-handling`.
+1. **Terse references with pointers.** Detail lives in shared files, not in the signal body.
+2. **Max ~500 tokens.** Signals are short coordination markers, not documents.
+3. **Include the file pointer.** If the signal references work product, include the path: `bugs.md#BUG-003`, `bend-handoff.md#error-handling`.
 
 ### Good example
 
@@ -272,7 +272,7 @@ endpoint that retrieves a tenant by ID...
 
 ## 6. Design Council Message Format
 
-Design Council is a structured deliberation protocol using existing inbox primitives. It is invoked when normal rejection cycles are insufficient to resolve a design disagreement.
+Design Council is a structured deliberation format using the signal vocabulary above. It is invoked when normal rejection cycles are insufficient to resolve a design disagreement. In the Workflow path the orchestrator script sequences the deliberation by routing the structured positions between the relevant phases.
 
 ### When to invoke
 
@@ -282,7 +282,7 @@ Design Council is a structured deliberation protocol using existing inbox primit
 
 ### Step 1: Initiator sends structured question
 
-Send to 2-3 relevant teammates via inbox:
+Direct the question at 2-3 relevant phases:
 
 ```
 [DESIGN-COUNCIL] Topic: {description}
@@ -348,15 +348,13 @@ The decision block is written to `decisions.md` in the story directory. Any agen
 
 - The **initiator decides**; others advise.
 - Design Council is **not a replacement for the rejection cycle**. CRITIC still rejects; Design Council is for when rejection alone is not resolving the issue.
-- Design Council is a **communication pattern**, not a separate mode. It uses existing inbox primitives.
+- Design Council is a **communication pattern**, not a separate mode. It uses the signal vocabulary in Section 5.
 
 ---
 
 ## 7. Headless Escalation Protocol
 
-When the lead agent encounters a blocker requiring human input, it classifies the blocker, logs it to `{story_output_dir}/escalation-log.md`, outputs the structured escalation block to CLI for visibility, and moves to the next unblocked story. The pipeline does not pause for skippable blockers. Blocking escalations (quality gate failures) stop the current story cleanly before moving on.
-
-See `lead.md#headless-escalation-protocol` for full classification rules and behavior.
+When a blocker requires human input, the workflow orchestrator classifies it, logs it to `{story_output_dir}/escalation-log.md`, outputs the structured escalation block to CLI for visibility, marks the story `blocked-on-user`, and moves to the next unblocked story. The pipeline does not pause for skippable blockers. Blocking escalations (quality gate failures) stop the current story cleanly before moving on.
 
 ### Escalation block format
 
@@ -370,7 +368,7 @@ Options:
   1. {option 1}
   2. {option 2}
   3. {option 3 — if applicable}
-Need: {what the lead needs from the user to proceed}
+Need: {what the workflow needs from the user to proceed}
 ═══════════════════════════════════════════════
 ```
 
@@ -396,11 +394,11 @@ Need: Pick an option or provide guidance
 - **Skippable** blockers (missing inputs): pipeline logs the escalation and moves to the next unblocked story
 - **Blocking** failures (quality gate exhaustion): pipeline stops cleanly on this story, persists state, then moves to the next unblocked story if safe
 - If no unblocked stories remain, the pipeline stops cleanly with persisted state
-- Escalation is the **last resort** — the lead should attempt to resolve issues autonomously first (e.g., via the 2-tier rejection circuit breaker or Design Council deliberation)
+- Escalation is the **last resort** — the workflow should exhaust autonomous resolution first (e.g., the code-owned rework cap routing rejections upstream, or Design Council deliberation)
 - All escalations are logged in both `{story_output_dir}/escalation-log.md` and `story-report.md`
 - **Resume:** user fixes inputs, sets story status to `pending` in backlog, re-runs pipeline
 
-> **V4 note:** Headless escalation is now implemented (skip-and-log). For async notification when escalations occur during headless runs, investigate Claude Dispatch (scheduled remote agents) and Slack integration (via MCP) as notification channels.
+> **Note:** Headless escalation is implemented (skip-and-log; blocked stories surface with status `blocked-on-user`). For async notification when escalations occur during headless runs, scheduled remote agents and Slack integration (via MCP) are candidate notification channels.
 
 ### Bad example
 
@@ -433,10 +431,10 @@ Agents should verify their output against this checklist before finalizing.
 - [ ] Cross-references use explicit file paths and anchors (`file.md#section`)
 - [ ] Structured data (lists, key-value pairs, YAML) used instead of paragraphs
 
-### Inbox messages
+### Inter-agent signals
 
 - [ ] Terse -- under ~500 tokens
-- [ ] Detail lives in a shared file, not the message body
+- [ ] Detail lives in a shared file, not the signal body
 - [ ] Includes file pointer when referencing work product
 - [ ] No greetings, sign-offs, or filler
 

package/pipeline/docs/index.md

@@ -2,6 +2,9 @@
 
 Reference documentation for the valent-pipeline multi-agent AI SDLC system.
 
+The pipeline runs on a single orchestration path: the **Claude Code Workflow** path
+(`orchestrators/claude-code/*.workflow.js`, driven by the `valent-run-*-workflow` skills).
+
 ## Reference
 
 Core documentation for understanding and operating the pipeline.
@@ -9,13 +12,12 @@ Core documentation for understanding and operating the pipeline.
 | Document | Description |
 |---|---|
 | [Pipeline Overview](pipeline-overview.md) | What the pipeline is, what it consumes and produces, end-to-end flow, key concepts |
-| [Agent Reference](agent-reference.md) | All 15+ agents: roles, models, inputs, outputs, project-type selection |
-| [Communication Standard](communication-standard.md) | Distilled handoff format, inbox message types, Design Council protocol, human escalation |
-| [Lead Lifecycle](lead-lifecycle.md) | Three-phase lifecycle (kick-off, monitor, ship), rejection loops, backlog management, crash recovery |
-| [Task Graph Specification](task-graph.md) | How the lead builds dependency graphs from the manifest, task states, claiming protocol, rejection re-queue |
-| [Pipeline State Schema](pipeline-state-schema.md) | JSON schema for pipeline-state.json -- crash recovery, backlog, sprint state |
-| [Knowledge System](knowledge-system.md) | Correction directives, curated knowledge, ChromaDB RAG, retrospective curation flow |
-| [Template Skeleton](template-skeleton.md) | Universal structure for all 27 handoff templates -- frontmatter, orchestrator summary, required/conditional sections |
+| [Agent Reference](agent-reference.md) | All agents: roles, models, inputs, outputs, project-type selection |
+| [Communication Standard](communication-standard.md) | Distilled handoff format, inbox message types, human escalation |
+| [Task Graph Specification](task-graph.md) | How the dev task graph is resolved (`resolve-graph`), task states, conditional pruning |
+| [Pipeline State Schema](pipeline-state-schema.md) | JSON schema for pipeline-state.json -- backlog and sprint state (derived, human-readable view) |
+| [Knowledge System](knowledge-system.md) | Correction directives, curated knowledge, RAG, retrospective curation flow |
+| [Template Skeleton](template-skeleton.md) | Universal structure for handoff templates -- frontmatter, orchestrator summary, required/conditional sections |
 
 ## Operations
 
@@ -23,19 +25,8 @@ Guides for installation, packaging, and maintenance.
 
 | Document | Description |
 |---|---|
-| [NPX Packaging](npx-packaging.md) | File classification (infrastructure vs project-specific vs runtime), init workflow, version management |
+| [NPX Packaging](npx-packaging.md) | File classification (infrastructure vs project-specific vs runtime), init/upgrade workflow, version management |
 | [NPX Implementation Plan](npx-implementation-plan.md) | Step-by-step build plan for the npm package |
-| [Lean Spawn & Human Tasks](lean-spawn-human-tasks.md) | Optimization phases, SQLite validation tasks, NPX setup tasks |
-
-## Design
-
-Design documents for pipeline extensions and architectural decisions.
-
-| Document | Description |
-|---|---|
-| [Refactor Checklist](design/refactor-checklist.md) | Every location to update when changing agents, config, tables, statuses, or phases |
-| [Codex Provider Support](design/codex-provider-support.md) | Multi-provider architecture: Codex runtime adapter, sync strategy, phased implementation plan |
-| [Provider Adapter Guide](design/provider-adapter-guide.md) | How the provider adapter pattern works, how to add provider-specific behavior, sync protocol |
 
 ## Quick Navigation
 
@@ -43,9 +34,7 @@ Design documents for pipeline extensions and architectural decisions.
 
 - **New to the pipeline?** Start with [Pipeline Overview](pipeline-overview.md), then [Agent Reference](agent-reference.md)
 - **Configuring a project?** See the [README](../../README.md) configuration section, then [NPX Packaging](npx-packaging.md)
-- **Adding or changing agents?** Read [Refactor Checklist](design/refactor-checklist.md) first, then [Agent Reference](agent-reference.md) and [Task Graph Specification](task-graph.md)
-- **Adding provider support?** Read [Provider Adapter Guide](design/provider-adapter-guide.md), then [Codex Provider Support](design/codex-provider-support.md)
-- **Debugging a stuck pipeline?** Check [Lead Lifecycle](lead-lifecycle.md) sections on stall detection, rejection loops, and crash recovery
+- **Adding or changing agents?** Read [Agent Reference](agent-reference.md) and [Task Graph Specification](task-graph.md)
 - **Understanding the knowledge system?** Read [Knowledge System](knowledge-system.md) for correction directives, curation, and RAG assessment
 - **Writing or modifying templates?** Consult [Template Skeleton](template-skeleton.md) for the universal structure
 
@@ -53,12 +42,11 @@ Design documents for pipeline extensions and architectural decisions.
 
 | File | Documentation |
 |---|---|
-| `agents-manifest.yaml` | [Agent Reference](agent-reference.md) |
 | `pipeline-config.yaml` | [README](../../README.md#configuration) |
 | `pipeline-state.json` | [Pipeline State Schema](pipeline-state-schema.md) |
 | `prompts/*.md` | [Agent Reference](agent-reference.md) |
 | `templates/*.md` | [Template Skeleton](template-skeleton.md) |
 | `task-graphs/*.yaml` | [Task Graph Specification](task-graph.md) |
 | `steps/**/*.md` | Individual agent prompts reference their step files |
+| `orchestrators/claude-code/*.workflow.js` | [Pipeline Overview](pipeline-overview.md) |
 | `knowledge/` | [Knowledge System](knowledge-system.md) |
-| `providers/**/*` | [Provider Adapter Guide](design/provider-adapter-guide.md) |