valent-pipeline 0.1.1 → 0.1.2

package/package.json

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

package/pipeline/agents-manifest.yaml

@@ -0,0 +1,170 @@
+# =============================================================================
+# V3 Agent Manifest — Lead Agent's Primary Reference for Team Composition
+# =============================================================================
+#
+# This manifest defines every agent the lead can spawn, their models, roles,
+# dependencies, and outputs. The lead reads this file at pipeline start to:
+#
+#   1. Phase 1 kick-off: Filter by lifecycle: per-story, check degraded_without
+#      to determine which optional inputs are available, and spawn teammates.
+#   2. Task dependency graph: Built from reads_from / writes_to — if agent B
+#      reads from what agent A writes, B is blockedBy A.
+#   3. Communication: All teammates can message any other living teammate via
+#      inbox. No routing restrictions.
+#   4. Model selection: Centralized here, not scattered across prompt templates.
+#      Changing an agent's model is a one-line YAML edit.
+#   5. Ephemeral spawning: The ephemeral_agents section tells the lead what it
+#      can spawn on-demand and what triggers the spawn.
+#
+# IMPORTANT — Communication & Access:
+#   - All teammates can message any other living teammate. There are NO
+#     communication restrictions.
+#   - reads_from indicates PRIMARY DEPENDENCIES for task sequencing, not access
+#     restrictions. All agents can read any file in the story folder.
+# =============================================================================
+
+agents:
+  lead:
+    name: Lead
+    model: opus
+    lifecycle: persistent
+    role: "Pipeline orchestrator — spawns team, monitors execution, manages story lifecycle"
+    prompt_template: v3/prompts/lead.md
+    reads_from: [story-input, agents-manifest.yaml, pipeline-config.yaml, pipeline-state.json]
+    writes_to: [pipeline-state.json]
+
+  reqs:
+    name: REQS
+    model: sonnet
+    lifecycle: per-story
+    role: "Requirements analyst — translates ACs into implementation brief"
+    prompt_template: v3/prompts/reqs.md
+    reads_from: [story-input]  # all story folder contents: ACs, trigger-map, architecture-decisions, UX spec when available
+    writes_to: [reqs-brief.md]
+
+  uxa:
+    name: UXA
+    model: sonnet
+    lifecycle: per-story
+    role: "UX specification agent — translates UX spec into component specs"
+    prompt_template: v3/prompts/uxa.md
+    reads_from: [reqs-brief.md, ux-spec, trigger-map, scenarios]
+    writes_to: [uxa-spec.md]
+    project_types: [fullstack-web, frontend-only]
+    degraded_without: [trigger-map, scenarios]  # runs translation-only without these
+
+  qa_a:
+    name: QA-A
+    model: sonnet
+    lifecycle: per-story
+    role: "QA spec writer — produces behavioral test specifications"
+    prompt_template: v3/prompts/qa-a.md
+    reads_from: [reqs-brief.md, uxa-spec.md]
+    writes_to: [qa-test-spec.md, visual-validation-checklist.md]
+
+  judge_g1:
+    name: JUDGE-G1
+    model: sonnet
+    lifecycle: per-story
+    role: "Quality gate — validates reqs, UXA spec, test specs (Pass 1) and bug priorities (Pass 2)"
+    prompt_template: v3/prompts/judge-g1.md
+    passes:
+      pass1_review_order: [reqs-validation, uxa-validation, qa-spec-validation]  # sequential, stop on first failure
+      pass2: bug-review
+    reads_from: [reqs-brief.md, uxa-spec.md, qa-test-spec.md, bugs.md, execution-report.md]
+    writes_to: [judge-g1-review.md]
+
+  bend:
+    name: BEND
+    model: sonnet
+    lifecycle: per-story
+    role: "Backend developer — implements production code and tests"
+    prompt_template: v3/prompts/bend.md
+    reads_from: [reqs-brief.md, qa-test-spec.md]
+    writes_to: [bend-handoff.md]
+
+  fend:
+    name: FEND
+    model: sonnet
+    lifecycle: per-story
+    role: "Frontend developer — implements UI components and tests"
+    prompt_template: v3/prompts/fend.md
+    reads_from: [reqs-brief.md, uxa-spec.md, qa-test-spec.md]
+    writes_to: [fend-handoff.md]
+    project_types: [fullstack-web, frontend-only]
+
+  critic:
+    name: CRITIC
+    model: opus
+    lifecycle: per-story
+    role: "Code reviewer — 3-pass adversarial review of production and test code"
+    prompt_template: v3/prompts/critic.md
+    review_passes: [blind-hunt, edge-case-hunt, acceptance-audit, triage]
+    reads_from: [git-diff, reqs-brief.md, qa-test-spec.md]
+    writes_to: [critic-review.md]
+
+  qa_b:
+    name: QA-B
+    model: sonnet
+    lifecycle: per-story
+    role: "Test executor — runs tests, validates spec alignment, files bugs"
+    prompt_template: v3/prompts/qa-b.md
+    reads_from: [qa-test-spec.md, critic-review.md, reqs-brief.md]
+    writes_to: [execution-report.md, bugs.md, traceability-matrix.md]
+    can_request_spawn: [pmcp]  # asks lead to spawn PMCP
+
+  judge_g2:
+    name: JUDGE-G2
+    model: sonnet
+    lifecycle: per-story
+    role: "Final ship gate — evidence-based approval or rejection"
+    prompt_template: v3/prompts/judge-g2.md
+    reads_from: [execution-report.md, traceability-matrix.md, pmcp-evidence.md, bugs.md, judge-g1-review.md, qa-test-spec.md]  # critic-review.md intentionally excluded — G2 validates test/execution evidence, not code review; qa-test-spec.md used as reference for assertion cross-check
+    writes_to: [judge-g2-decision.md, story-report.md]
+
+  knowledge:
+    name: Knowledge
+    model: haiku
+    lifecycle: per-story
+    role: "Knowledge retrieval — answers queries from persistent data sources"
+    prompt_template: v3/prompts/knowledge.md
+    data_sources: [chromadb, curated-knowledge-files, correction-directives]
+    context_variables: [knowledge_mode, chromadb_host, chromadb_collection_prefix, curated_files_path, correction_directives]
+    # No writes_to — Knowledge Agent responds via inbox only, no file output
+
+ephemeral_agents:
+  pmcp:
+    name: PMCP
+    model: sonnet
+    role: "Visual validation — executes browser automation MCP checklist, captures screenshots"
+    prompt_template: v3/prompts/pmcp.md
+    reads_from: [visual-validation-checklist.md]
+    writes_to: [pmcp-evidence.md]
+    spawned_by: lead
+    spawn_trigger: qa_a_checklist  # Lead spawns idle when QA-A writes visual-validation-checklist.md
+    execution_trigger: qa_b        # QA-B sends [PMCP-TRIGGER] with dev server URL to start execution
+
+  embed:
+    name: Embed
+    model: haiku
+    role: "Knowledge indexer — indexes curated patterns into knowledge base"
+    prompt_template: v3/prompts/embed.md
+    spawned_by: lead
+    triggered_by: retrospective  # only runs after Retrospective Agent curates what to index
+
+  retrospective:
+    name: Retrospective
+    model: sonnet
+    role: "Batch reviewer — analyzes last N stories for recurring patterns"
+    prompt_template: v3/prompts/retrospective.md
+    spawned_by: lead
+    triggered_by: every-n-stories
+
+  help:
+    name: Help
+    model: haiku
+    role: "Pipeline help — explains any piece of the pipeline from documentation"
+    prompt_template: v3/prompts/help.md
+    reads_from: [v3/docs/]
+    spawned_by: lead
+    triggered_by: user-request

package/pipeline/docker-compose.chromadb.yml

@@ -0,0 +1,15 @@
+services:
+  chromadb:
+    image: chromadb/chroma:latest
+    ports:
+      - "8000:8000"
+    volumes:
+      - ./chromadb-data:/chroma/chroma
+    environment:
+      IS_PERSISTENT: "TRUE"
+      ANONYMIZED_TELEMETRY: "FALSE"
+    healthcheck:
+      test: ["CMD-SHELL", "curl -f http://localhost:8000/api/v1/heartbeat || exit 1"]
+      interval: 10s
+      timeout: 5s
+      retries: 5

package/pipeline/docs/agent-reference.md

@@ -0,0 +1,72 @@
+# V3 Agent Reference
+
+> Quick reference for all 15 agents in the v3 pipeline.
+> Definitive source: `v3/agents-manifest.yaml`
+
+---
+
+## Agent Roster
+
+### Per-Story Agents (10)
+
+Spawned fresh for each story and torn down after the story ships or is cancelled.
+
+| 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 |
+| 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 |
+| JUDGE-G1 | Sonnet | Quality gate -- validates specs (Pass 1) and bug priorities (Pass 2) | `reqs-brief.md`, `uxa-spec.md`, `qa-test-spec.md`, `bugs.md`, `execution-report.md` | `judge-g1-review.md` | Sequential review: stops on first failure in Pass 1 |
+| 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 |
+| JUDGE-G2 | Sonnet | Final ship gate -- evidence-based approval or rejection | `execution-report.md`, `traceability-matrix.md`, `pmcp-evidence.md`, `bugs.md`, `judge-g1-review.md` | `judge-g2-decision.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 |
+
+### 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.
+
+| 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 | `v3/docs/` | _(inbox only)_ | User request |
+
+---
+
+## 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.
+
+| 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 |
+
+---
+
+## Model Tier Summary
+
+| 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, JUDGE-G1, JUDGE-G2, PMCP, Retrospective | Analysis, spec writing, test execution, judgment, coordination | 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.