valent-pipeline 0.2.20 → 0.2.22

package/README.md

@@ -0,0 +1,438 @@
+# valent-pipeline
+
+A multi-agent AI pipeline that takes user stories and ships tested, reviewed, committed code. Built on Claude Code agent teams.
+
+You write the story. The pipeline handles requirements analysis, UX specification, test planning, implementation, adversarial code review, test execution, and a final evidence-based ship decision -- producing a full artifact trail for every story.
+
+## Quick Start
+
+```bash
+# Install globally
+npm install -g valent-pipeline
+
+# Initialize in your project
+cd your-project
+valent-pipeline init
+
+# Run the interactive configuration wizard
+/valent-configure
+
+# Execute a story
+/valent-run-story STORY-001
+```
+
+## How It Works
+
+A persistent **Lead** agent reads your story, assembles a team of specialist agents, and orchestrates them through a dependency-driven pipeline:
+
+```
+REQS -> UXA -> QA-A -> READINESS -> BEND + FEND -> CRITIC -> QA-B -> JUDGE -> SHIP
+```
+
+1. **REQS** translates acceptance criteria into an implementation brief
+2. **UXA** converts UX specs into component specifications (frontend projects)
+3. **QA-A** writes behavioral test specifications *before any code exists*
+4. **READINESS** gate validates the spec chain -- stops on first failure
+5. **BEND + FEND** implement production code and tests in parallel
+6. **CRITIC** runs a 3-pass adversarial code review (blind hunt, edge cases, acceptance audit)
+7. **QA-B** executes tests against real infrastructure, files bugs, builds traceability matrix
+8. **JUDGE** makes an evidence-based SHIP or REJECT decision
+9. **Lead** commits code, writes the story report, and picks the next story
+
+Two quality gates (**READINESS** and **JUDGE**) enforce pass/fail checkpoints. Rejection loops send work back to the responsible agent with specific corrections, with a circuit breaker to prevent infinite cycles.
+
+## Project Types
+
+The pipeline supports 7 project types, each with a tailored task graph and specialized developer agent:
+
+| Project Type | Developer Agent | Agents Skipped |
+|---|---|---|
+| `fullstack-web` | BEND + FEND | *(none)* |
+| `backend-api` | BEND | UXA, FEND, PMCP |
+| `frontend-only` | FEND | BEND |
+| `data-pipeline` | DATA | UXA, FEND, PMCP |
+| `mcp-server` | MCP-DEV | UXA, FEND, PMCP |
+| `document-generation` | DOCGEN | UXA, FEND, PMCP |
+| `library` | LIBDEV | UXA, FEND, PMCP |
+| `mobile-app` | MOBILE | *(conditional)* |
+
+The Lead selects which agents to spawn based on `project.type` in your `pipeline-config.yaml` and the story's `testing_profiles`.
+
+## Agent Roster
+
+### Per-Story Agents (10)
+
+Spawned fresh per story, torn down after ship or cancel.
+
+| Agent | Model | Role | Output |
+|---|---|---|---|
+| REQS | Sonnet | Requirements analyst | `reqs-brief.md` |
+| UXA | Sonnet | UX specification | `uxa-spec.md` |
+| QA-A | Sonnet | Test specification | `qa-test-spec.md`, `visual-validation-checklist.md` |
+| READINESS | Sonnet | Spec quality gate | `readiness-review.md` |
+| BEND | Sonnet | Backend developer | `bend-handoff.md` |
+| FEND | Sonnet | Frontend developer | `fend-handoff.md` |
+| CRITIC | Opus | Adversarial code reviewer | `critic-review.md` |
+| QA-B | Sonnet | Test executor | `execution-report.md`, `bugs.md`, `traceability-matrix.md` |
+| JUDGE | Sonnet | Final quality gate | `judge-review.md`, `judge-decision.md` |
+| Knowledge | Haiku | Knowledge retrieval | *(inbox only)* |
+
+### Domain Developer Agents
+
+Specialized agents that replace BEND for non-API project types:
+
+| Agent | Model | Project Type | Output |
+|---|---|---|---|
+| DATA | Sonnet | `data-pipeline` | `data-handoff.md` |
+| MCP-DEV | Sonnet | `mcp-server` | `mcp-dev-handoff.md` |
+| LIBDEV | Sonnet | `library` | `libdev-handoff.md` |
+| DOCGEN | Sonnet | `document-generation` | `docgen-handoff.md` |
+| IAC | Sonnet | Cross-cutting (any type) | `iac-handoff.md` |
+| MOBILE | Sonnet | `mobile-app` | `mobile-handoff.md` |
+
+### Persistent & Ephemeral Agents
+
+| Agent | Model | Lifecycle | Trigger |
+|---|---|---|---|
+| Lead | Opus | Persistent across stories | Always running |
+| PMCP | Sonnet | Ephemeral | QA-B requests visual validation |
+| Embed | Haiku | Ephemeral | After Retrospective curates |
+| Retrospective | Sonnet | Ephemeral | Every N stories (configurable) |
+| Help | Haiku | Ephemeral | User request |
+
+## Installation
+
+### Prerequisites
+
+- Node.js >= 18
+- Claude Code CLI
+- npm account (for publishing)
+
+### Install
+
+```bash
+npm install -g valent-pipeline
+```
+
+### Initialize a Project
+
+```bash
+cd your-project
+valent-pipeline init
+```
+
+The init command:
+1. Runs an interactive wizard to set project type, tech stack, and model assignments
+2. Copies pipeline infrastructure to `.valent-pipeline/`
+3. Generates `pipeline-config.yaml` from your answers
+4. Creates knowledge directories and initializes the backlog
+5. Installs Claude Code skills for story/epic/project execution
+
+### Upgrade
+
+```bash
+valent-pipeline upgrade
+valent-pipeline upgrade --dry-run   # preview changes without applying
+```
+
+Upgrades pipeline infrastructure (prompts, templates, task graphs, scripts) while preserving your project-specific files (config, knowledge, backlog).
+
+### Validate Configuration
+
+```bash
+valent-pipeline config validate
+```
+
+## Configuration
+
+All configuration lives in `.valent-pipeline/pipeline-config.yaml`. Run `/valent-configure` to edit interactively, or edit the file directly.
+
+### Key Sections
+
+```yaml
+project:
+  type: fullstack-web              # Project type (determines agent roster)
+  root: .                          # Project root directory
+  story_directory: ./stories       # Where story inputs live
+  backlog_path: ./pipeline-backlog.yaml
+
+tech_stack:
+  language: TypeScript
+  backend_framework: Express
+  frontend_framework: React
+  test_framework_unit: Vitest
+  test_framework_e2e: Playwright
+  browser_automation_mcp: playwright-mcp
+
+models:
+  opus: [BEND, FEND, CRITIC]      # Complex code generation, review
+  sonnet: [REQS, UXA, QA-A, ...]  # Analysis, spec writing, judgment
+  haiku: [Knowledge, Embed, Help]  # Retrieval, indexing, lookups
+
+quality:
+  max_rejection_cycles: 5          # Circuit breaker for rejection loops
+  retrospective_every_n_stories: 5 # Retrospective trigger frequency
+  stall_threshold_minutes: 15      # Agent stall detection timeout
+
+git:
+  target_branch: ""                # Base branch for story branches
+  story_branch_prefix: story/      # Branch naming convention
+
+knowledge:
+  mode: sqlite                     # none | sqlite | local-docker | connect-to-existing
+  sqlite_db_path: ./.valent-pipeline/pipeline.db
+
+sprint:                            # Only used in epic/project mode
+  duration_minutes: 480
+  initial_velocity_points: 60
+  estimation_model: calibrated     # calibrated | baseline
+  fibonacci_scale: [1, 2, 3, 5, 8, 13, 21]
+```
+
+## CLI Commands
+
+### Pipeline Management
+
+| Command | Description |
+|---|---|
+| `valent-pipeline init` | Initialize pipeline in current project |
+| `valent-pipeline upgrade` | Upgrade pipeline infrastructure |
+| `valent-pipeline upgrade --dry-run` | Preview upgrade changes |
+| `valent-pipeline config validate` | Validate pipeline-config.yaml |
+
+### Database Commands
+
+| Command | Description |
+|---|---|
+| `valent-pipeline db init` | Initialize SQLite knowledge database |
+| `valent-pipeline db rebuild` | Drop and recreate all tables |
+| `valent-pipeline db index <story-dir>` | Index a story's artifacts |
+| `valent-pipeline db query <text>` | Full-text search across artifacts |
+| `valent-pipeline db embed <file>` | Generate and store embeddings |
+
+### Claude Code Skills
+
+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-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 |
+| `/valent-debug-export` | Export diagnostic dump |
+| `/valent-help` | Pipeline documentation and FAQ |
+
+## Story Inputs
+
+Create a story directory with at least a `story.md` file:
+
+```
+stories/
+  STORY-001/
+    story.md                      # Required: user story + acceptance criteria
+    ux-spec.md                    # Optional: UX specification
+    trigger-map.md                # Optional: interaction flows
+    scenarios.md                  # Optional: behavioral scenarios
+    architecture-notes.md         # Optional: constraints and decisions
+```
+
+The pipeline writes all output to `stories/STORY-001/output/`.
+
+## Pipeline Output
+
+For each story, the pipeline produces 15+ artifacts in `stories/{story-id}/output/`:
+
+| Artifact | Agent | Purpose |
+|---|---|---|
+| `reqs-brief.md` | REQS | Implementation brief from ACs |
+| `uxa-spec.md` | UXA | Component specs from UX spec |
+| `qa-test-spec.md` | QA-A | Behavioral test specifications |
+| `visual-validation-checklist.md` | QA-A | Browser automation checklist |
+| `{dev}-handoff.md` | BEND/FEND/etc. | Implementation summary |
+| `critic-review.md` | CRITIC | 3-pass code review findings |
+| `execution-report.md` | QA-B | Test execution results |
+| `bugs.md` | QA-B | Filed bugs with priorities |
+| `traceability-matrix.md` | QA-B | AC-to-test coverage map |
+| `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 |
+
+Plus committed, tested production code in your project source tree.
+
+## Communication Model
+
+All inter-agent communication follows the [Distilled Communication Standard](pipeline/docs/communication-standard.md):
+
+- **Handoff documents** -- structured artifacts with YAML frontmatter, orchestrator summary, and facts-only content. Every handoff follows a [template skeleton](pipeline/docs/template-skeleton.md).
+- **Inbox messages** -- terse coordination messages (~500 tokens max) with file pointers. Types include `[HANDOFF]`, `[BLOCKER]`, `[REVISION]`, `[CRITIC-REJECTION]`, `[BUG]`, `[DESIGN-COUNCIL]`, `[ESCALATION]`.
+- **Design Council** -- structured deliberation protocol for contested design decisions with position statements, synthesis, and escalation to user if consensus fails.
+- **Human Escalation** -- when agent deliberation is insufficient, the Lead surfaces the issue to the user with full context.
+
+## Knowledge System
+
+The pipeline learns from its own output through a [knowledge system](pipeline/docs/knowledge-system.md) with three data sources:
+
+| Source | Location | Purpose |
+|---|---|---|
+| Correction directives | `knowledge/correction-directives.yaml` | Behavioral changes for agents from past patterns |
+| Curated knowledge | `knowledge/curated/` | Conventions, validated patterns, known pitfalls |
+| SQLite / ChromaDB | `.valent-pipeline/pipeline.db` | Embedding-based retrieval (optional) |
+
+The **Retrospective** agent (triggered every N stories) is the sole gatekeeper for what enters persistent knowledge. It analyzes batch outputs, writes correction directives, and produces indexing instructions for the **Embed** agent. The **Knowledge** agent reads all sources and responds to teammate queries during story execution.
+
+### Knowledge Modes
+
+| Mode | Dependencies | Description |
+|---|---|---|
+| `none` | None | Curated files + correction directives only |
+| `sqlite` | better-sqlite3 | Local SQLite with FTS5 and vector search |
+| `local-docker` | Docker | ChromaDB via Docker Compose + curated files |
+| `connect-to-existing` | Network | Remote ChromaDB instance + curated files |
+
+## Execution Modes
+
+### Single Story
+
+```
+/valent-run-story STORY-001
+```
+
+Executes one story through the full pipeline.
+
+### Epic (Sprint-Based)
+
+```
+/valent-run-epic 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.
+
+### Full Project
+
+```
+/valent-run-project
+```
+
+Executes all epics in the backlog with cross-epic dependency resolution.
+
+### Backlog Setup
+
+```
+/valent-setup-backlog
+```
+
+Converts your epics and stories documents into a prioritized `pipeline-backlog.yaml` with vertical slice ordering and knowledge base initialization.
+
+## Quality Gates
+
+### READINESS Gate
+
+Validates the spec chain before any code is written:
+- REQS brief completeness and accuracy
+- UXA spec consistency (frontend projects)
+- QA test spec coverage and depth
+
+Stops on first failure. The responsible upstream agent must rework before the pipeline proceeds.
+
+### JUDGE Gate
+
+Makes the final ship decision based on evidence:
+- Bug priority review (can reclassify P4 bugs to P1-P3)
+- Test execution results verification
+- Traceability matrix completeness
+- PMCP visual evidence (UI projects)
+- Applies "evidence over assertion" -- independently verifies every upstream claim
+
+Verdicts: **SHIP** (commit and close), **SHIP-PARTIAL** (mobile: ship Android, defer iOS), **REJECT** (send back with corrections).
+
+### Rejection Loops
+
+When CRITIC or JUDGE rejects work:
+1. Lead re-queues the responsible agent with the specific rejection findings
+2. Agent reworks and resubmits
+3. Circuit breaker (`max_rejection_cycles`, default 5) prevents infinite loops
+4. After max cycles, Lead escalates to user
+
+## Crash Recovery
+
+All pipeline state is persisted to disk:
+- `pipeline-state.json` -- current story, backlog, phase timing, team roster
+- Handoff files with YAML frontmatter tracking step progress
+- Git working directory preserves code state
+- Inbox files preserve communication history
+
+If the Lead crashes, it can reconstruct the full pipeline state from these artifacts on restart.
+
+## Directory Structure
+
+After initialization, the pipeline installs to `.valent-pipeline/` in your project:
+
+```
+.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)
+    bend/                     #   Backend developer steps
+    fend/                     #   Frontend developer steps
+    critic/                   #   Code review steps
+    qa-a/                     #   Test spec steps (domain-specific)
+    qa-b/                     #   Test execution steps (domain-specific)
+    reqs/                     #   Requirements analysis steps
+    readiness/                #   Readiness gate steps
+    judge/                    #   Judge gate steps
+    orchestration/            #   Lead orchestration steps
+    retrospective/            #   Retrospective analysis steps
+    common/                   #   Shared agent protocols
+    data/                     #   Data pipeline developer steps
+    docgen/                   #   Document generation steps
+    fend/                     #   Frontend developer steps
+    iac/                      #   Infrastructure-as-code steps
+    libdev/                   #   Library developer steps
+    mcp-dev/                  #   MCP server developer steps
+    mobile/                   #   Mobile developer steps
+    uxa/                      #   UX specification steps
+  spawn-templates/            # Agent spawn configuration
+  scripts/                    # Pipeline utility scripts
+  docs/                       # Pipeline reference documentation
+  knowledge/
+    curated/                  # Curated knowledge files
+    correction-directives.yaml
+  pipeline.db                 # SQLite knowledge database
+```
+
+## Documentation
+
+Full reference documentation lives in `pipeline/docs/`:
+
+| Document | Description |
+|---|---|
+| [Pipeline Overview](pipeline/docs/pipeline-overview.md) | Architecture, flow, artifact map |
+| [Agent Reference](pipeline/docs/agent-reference.md) | All agents, models, inputs/outputs |
+| [Communication Standard](pipeline/docs/communication-standard.md) | Handoff format, inbox protocol, Design Council |
+| [Lead Lifecycle](pipeline/docs/lead-lifecycle.md) | Kick-off, monitoring, ship, crash recovery |
+| [Task Graph Specification](pipeline/docs/task-graph.md) | Dependencies, task states, claiming |
+| [Pipeline State Schema](pipeline/docs/pipeline-state-schema.md) | JSON schema for pipeline-state.json |
+| [Knowledge System](pipeline/docs/knowledge-system.md) | RAG assessment, correction directives, curation |
+| [Template Skeleton](pipeline/docs/template-skeleton.md) | Universal handoff document structure |
+| [NPX Packaging](pipeline/docs/npx-packaging.md) | Package distribution and init workflow |
+
+### Reference
+
+| Document | Description |
+|---|---|
+| [Refactor Checklist](pipeline/docs/design/refactor-checklist.md) | Every location to update when changing agents, config, tables, or phases |
+
+## License
+
+MIT

package/package.json

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

package/pipeline/agents-manifest.yaml

@@ -50,7 +50,7 @@ agents:
     prompt_template: .valent-pipeline/prompts/uxa.md
     reads_from: [reqs-brief.md, ux-spec, trigger-map, scenarios]
     writes_to: [uxa-spec.md]
-    project_types: [fullstack-web, frontend-only]
+    project_types: [fullstack-web, frontend-only, mobile-app]
     degraded_without: [trigger-map, scenarios]  # runs translation-only without these
 
   qa_a:
@@ -80,6 +80,7 @@ agents:
     prompt_template: .valent-pipeline/prompts/bend.md
     reads_from: [reqs-brief.md, qa-test-spec.md]
     writes_to: [bend-handoff.md]
+    project_types: [backend-api, fullstack-web]
 
   fend:
     name: FEND
@@ -91,6 +92,65 @@ agents:
     writes_to: [fend-handoff.md]
     project_types: [fullstack-web, frontend-only]
 
+  mobile:
+    name: MOBILE
+    model: sonnet
+    lifecycle: per-story
+    role: "Mobile developer — implements RN/Flutter screens, components, Maestro E2E flows"
+    prompt_template: .valent-pipeline/prompts/mobile.md
+    reads_from: [reqs-brief.md, uxa-spec.md, qa-test-spec.md]
+    writes_to: [mobile-handoff.md]
+    project_types: [mobile-app]
+
+  data:
+    name: DATA
+    model: sonnet
+    lifecycle: per-story
+    role: "Data pipeline developer — implements ETL, transforms, data quality, checkpointing"
+    prompt_template: .valent-pipeline/prompts/data.md
+    reads_from: [reqs-brief.md, qa-test-spec.md]
+    writes_to: [data-handoff.md]
+    project_types: [data-pipeline]
+
+  mcp_dev:
+    name: MCP-DEV
+    model: sonnet
+    lifecycle: per-story
+    role: "Protocol developer — implements MCP server tools, JSON-RPC handlers, transport"
+    prompt_template: .valent-pipeline/prompts/mcp-dev.md
+    reads_from: [reqs-brief.md, qa-test-spec.md]
+    writes_to: [mcp-dev-handoff.md]
+    project_types: [mcp-server]
+
+  libdev:
+    name: LIBDEV
+    model: sonnet
+    lifecycle: per-story
+    role: "Library developer — implements public API, exports, packaging, type declarations"
+    prompt_template: .valent-pipeline/prompts/libdev.md
+    reads_from: [reqs-brief.md, qa-test-spec.md]
+    writes_to: [libdev-handoff.md]
+    project_types: [library]
+
+  docgen:
+    name: DOCGEN
+    model: sonnet
+    lifecycle: per-story
+    role: "Document generation developer — implements templates, render pipeline, output formatting"
+    prompt_template: .valent-pipeline/prompts/docgen.md
+    reads_from: [reqs-brief.md, qa-test-spec.md]
+    writes_to: [docgen-handoff.md]
+    project_types: [document-generation]
+
+  iac:
+    name: IAC
+    model: sonnet
+    lifecycle: per-story
+    role: "Infrastructure developer — implements IaC definitions, deployment configs, infrastructure tests"
+    prompt_template: .valent-pipeline/prompts/iac.md
+    reads_from: [reqs-brief.md, qa-test-spec.md]
+    writes_to: [iac-handoff.md]
+
   critic:
     name: CRITIC
     model: opus

package/pipeline/docs/agent-reference.md

@@ -1,28 +1,48 @@
 # V3 Agent Reference
 
-> Quick reference for all 15 agents in the v3 pipeline.
+> Quick reference for all agents in the v3 pipeline.
 > Definitive source: `.valent-pipeline/agents-manifest.yaml`
 
 ---
 
 ## Agent Roster
 
-### Per-Story Agents (10)
+### Core Per-Story Agents (10)
 
-Spawned fresh for each story and torn down after the story ships or is cancelled.
+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.
 
 | 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; escalates only when options have genuinely competing tradeoffs |
+| 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; tests are specified, not implemented |
-| 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 |
-| BEND | Opus | 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 |
-| FEND | Opus | 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; skipped for backend-only projects |
-| 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 |
-| 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; can request PMCP spawn for visual validation |
+| 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 |
+| 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 |
+|-------|-------|------|-------------|-------|--------|------------|
+| 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 |
+| 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.
+- See the agent prompts in `pipeline/prompts/` and step files in `pipeline/steps/` for full implementation details.
 
 ### Persistent Agent (1)
 
@@ -47,26 +67,65 @@ Spawned on-demand by the Lead when triggered by specific events.
 
 ## Project-Type Agent Selection
 
-Not all agents run for every project type. The Lead reads `project_type` from `pipeline-config.yaml` and skips agents that don't apply.
+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.
 
-| Project Type | Agents Skipped |
-|-------------|----------------|
-| fullstack-web | _(none -- all agents active)_ |
-| backend-api | UXA, FEND, PMCP |
-| frontend-only | BEND |
-| data-pipeline | UXA, FEND, PMCP |
-| mcp-server | UXA, FEND, PMCP |
-| document-generation | UXA, FEND, PMCP |
-| library | UXA, FEND, PMCP |
+| Project Type | Developer Agent(s) | Agents Skipped | Task Graph |
+|---|---|---|---|
+| `fullstack-web` | BEND + FEND | _(none)_ | `fullstack-web.yaml` |
+| `backend-api` | BEND | UXA, FEND, PMCP | `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` |
+
+**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`
 
 ---
 
 ## Model Tier Summary
 
+Default assignments from `config-schema.js`:
+
 | Tier | Agents | Use Case | Cost |
 |------|--------|----------|------|
-| Opus | Lead, BEND, FEND, CRITIC | Complex code generation, orchestration, nuanced multi-pass review | Highest |
-| Sonnet | REQS, UXA, QA-A, QA-B, READINESS, JUDGE, PMCP, Retrospective | Analysis, spec writing, test execution, judgment, coordination | Balanced |
+| 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 |
 
 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.
+
+---
+
+## 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.
+
+### Shared Steps (`common/`)
+
+| Step File | Purpose |
+|---|---|
+| `agent-protocol.md` | Universal agent communication rules |
+| `distilled-handoff-format.md` | How to write distilled handoff documents |
+| `no-api-passthrough.md` | Constraint: no passthrough API endpoints |
+| `no-ui-passthrough.md` | Constraint: no passthrough UI components |
+| `quality-standards.md` | Cross-cutting quality standards for all agents |
+
+### 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`:
+
+| Profile | QA-A Step | QA-B Step | CRITIC Step | REQS Step |
+|---|---|---|---|---|
+| `api` | `qa-a/api.md` | `qa-b/api.md` | *(standard)* | *(standard)* |
+| `ui` | `qa-a/ui.md` | `qa-b/ui.md` | *(standard)* | *(standard)* |
+| `data-pipeline` | `qa-a/data-pipeline.md` | `qa-b/data-pipeline.md` | `critic/data-pipeline.md` | `reqs/data-pipeline.md` |
+| `mcp-server` | `qa-a/mcp-server.md` | `qa-b/mcp-server.md` | `critic/mcp-server.md` | `reqs/mcp-server.md` |
+| `library` | `qa-a/library.md` | `qa-b/library.md` | `critic/library.md` | `reqs/library.md` |
+| `document-generation` | `qa-a/document-generation.md` | `qa-b/document-generation.md` | `critic/document-generation.md` | `reqs/document-generation.md` |
+| `iac` | `qa-a/iac.md` | `qa-b/iac.md` | `critic/iac.md` | `reqs/iac.md` |
+| `mobile-app` | `qa-a/mobile-app.md` | `qa-b/mobile-app.md` | `critic/mobile-app.md` | `reqs/mobile-app.md` |