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

# 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

npm install -g valent-pipeline

Initialize a Project

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

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

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

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:

• Handoff documents -- structured artifacts with YAML frontmatter, orchestrator summary, and facts-only content. Every handoff follows a template skeleton.
• 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 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 | Architecture, flow, artifact map | | Agent Reference | All agents, models, inputs/outputs | | Communication Standard | Handoff format, inbox protocol, Design Council | | Lead Lifecycle | Kick-off, monitoring, ship, crash recovery | | Task Graph Specification | Dependencies, task states, claiming | | Pipeline State Schema | JSON schema for pipeline-state.json | | Knowledge System | RAG assessment, correction directives, curation | | Template Skeleton | Universal handoff document structure | | NPX Packaging | Package distribution and init workflow |

Reference

| Document | Description | |---|---| | Refactor Checklist | Every location to update when changing agents, config, tables, or phases |

License

MIT