pipeline

Pipeline Skill

Orchestrate parallel agent teams with structured mandates, test validation gates, and machine-readable state tracking. Prevents the three core failure modes: wrong assumptions, context blowouts, and workflow violations.

Overview

The pipeline system provides:

1. Mandate Templates -- Constrain each agent's scope and require test validation
2. Pipeline Formula -- Enforce lifecycle (pre-flight, baseline, dispatch, validate, merge)
3. Validation Hook -- Detect test regressions introduced by agents
4. Pipeline State -- Machine-readable tracking in .session/state.json

Architecture

Mechanism	Role	Location
Formula	Pipeline lifecycle enforcement	.beads/formulas/pipeline-execute.formula.toml
Template	Agent behavior constraints	.claude/templates/agent-mandate.md
Hook	Regression detection	.claude/hooks/validate-agent-output.ts
State	Progress tracking	.session/state.json (pipeline section)
Types	TypeScript interfaces	.claude/hooks/lib/pipeline-types.ts
Helpers	State read/write	.claude/hooks/lib/session-state.ts

Quick Start

Pour the pipeline formula

bd mol wisp pipeline-execute --var feature_id=diary-xxx --var test_command="bun test"

Check pipeline status

bun run .claude/skills/pipeline/scripts/status.ts

Retry a failed agent

bun run .claude/skills/pipeline/scripts/retry-agent.ts --agent impl-alpha

Pipeline Lifecycle

pre-flight --> capture-baseline --> dispatch --> validate-pipeline --> merge

1. Pre-flight: Verify feature tasks, check dependencies
2. Capture baseline: Run test suite, record pass/fail counts
3. Dispatch: Create agent team, assign mandates from template
4. Validate: Run tests after agents complete, compare to baseline
5. Merge: Commit results, close tasks, clean up team

Agent Mandate Template

Located at .claude/templates/agent-mandate.md. Template variables:

Variable	Description
{{title}}	Task title
{{agent_name}}	Agent name (e.g., impl-alpha)
{{task_id}}	Beads task ID
{{feature_id}}	Parent feature ID
{{epic_id}}	Parent epic ID
{{description}}	Task description
{{files_to_create}}	Files agent may create
{{files_to_modify}}	Files agent may modify
{{test_command}}	Test validation command
{{max_retries}}	Maximum retry attempts

Pipeline State

Tracked as a section in .session/state.json:

{
  "pipeline": {
    "pipelineId": "pipeline-1234",
    "featureId": "diary-xxx",
    "status": "dispatching",
    "baseline": { "passed": 530, "failed": 0, "total": 530 },
    "agents": {
      "impl-alpha": { "status": "success", "handoff": { ... } },
      "impl-beta": { "status": "in_progress" }
    }
  }
}

Concurrency Guidelines

Based on 540-session analysis:

• 2-3 agents: Optimal for most features
• 4 agents: Maximum recommended — higher risks context blowout
• 1 agent: Use for tightly coupled tasks with many dependencies

Scripts

Script	Purpose
status.ts	Read pipeline state, display dashboard
retry-agent.ts	Re-dispatch failed agent with error context