feat(pipeline): Add software lifecycle harness — requirements → design → spec

[ATMackay]

What is this?

This PR introduces a software lifecycle harness to the agent CLI — a pipeline orchestration system that takes natural language requirements from a user and drives them through structured, AI-generated artefacts with human review gates between each stage.

The goal is to automate the front-end of the software delivery pipeline: from a raw idea to a production-ready technical specification that is immediately actionable by an implementation agent (or a human developer).

---

How it works

A pipeline is defined in a declarative YAML spec (.pipeline.yaml) and executed stage-by-stage. Each stage runs a specialised LLM agent. After each stage completes, the user reviews the output and chooses to proceed, edit the artefact in $EDITOR, re-run the stage, or quit.

Natural language requirements
        ↓
[ requirements-analysis ]  →  docs/PRD.md
        ↓  (human gate)
[ technical-design ]       →  docs/DESIGN.md
        ↓  (human gate)
[ task-breakdown ]         →  docs/TASKS.md
        ↓  (human gate)
   Ready for implementation

Pipeline state is persisted to .pipeline-state/<name>.json after every stage, so interrupted runs can be resumed with --from-stage <id> without re-running completed work.

---

New CLI commands

# Generate a .pipeline.yaml spec
agent pipeline init \
  --name "my-api" \
  --requirements "Build a REST API in Go with JWT auth and PostgreSQL"

# Run the pipeline interactively
agent pipeline run --spec .pipeline.yaml

# Run non-interactively (CI mode, skip all gates)
agent pipeline run --spec .pipeline.yaml --yes-all

# Resume from a specific stage after a failure or gate rejection
agent pipeline run --spec .pipeline.yaml --from-stage technical-design

# Check stage completion status
agent pipeline status --spec .pipeline.yaml

Example pipeline status output:

Pipeline: my-api
Started:  2026-05-22 16:30:00

STAGE                   AGENT         STATUS     COMPLETED  OUTPUT
─────                   ─────         ──────     ─────────  ──────
requirements-analysis   requirements  completed  16:31:44   docs/PRD.md
technical-design        architect     running    —          —
task-breakdown          architect     pending    —          —

---

New packages

agents/requirements — RequirementsAnalyzer

Transforms informal requirements into a structured PRD containing:

• Problem statement and goals/non-goals
• User personas and user stories with Given/When/Then acceptance criteria
• Functional and non-functional requirements
• Success metrics and open questions

If a work_dir is provided, the agent explores the existing codebase first to incorporate real constraints (tech stack, existing conventions, known limitations) into the document.

agents/architect — Architect

Runs twice in the default pipeline with different tasks:

Task design — reads the PRD and produces a Technical Design Document:

• C4-inspired architecture overview with ASCII/Mermaid diagrams
• Component responsibilities and public interfaces
• Data models, API contracts, technology choices with rationale
• Security considerations and observability strategy

Task tasks — reads the design doc and produces an Implementation Task List:

• Ordered tasks with dependencies (foundational work first)
• Each task specifies files to create/modify, description, and acceptance criteria
• Every task includes TDD-framed test requirements

pipeline — Stage Orchestrator

File	Responsibility
config.go	YAML pipeline spec types; LoadConfig(), DefaultConfig(), Marshal()
state.go	JSON-persisted PipelineState / StageState; LoadState(), Save()
gate.go	Interactive approval gate with artifact preview and $EDITOR integration
pipeline.go	Pipeline.Run() — sequential executor, stage dispatch, resume logic

---

Design decisions

Persistent file-based state (.pipeline-state/) rather than in-memory ADK session state — survives CLI restarts, gives users visibility into what ran, and enables --from-stage resumption without re-incurring LLM cost for completed stages.

Stage outputs are plain markdown files on disk — human-readable, editable before the next stage consumes them, and naturally version-controlled alongside the project.

Human gates are first-class — the [e]dit option lets users correct the agent's output in their editor before the next stage reads it. This is the key mechanism for keeping humans in the loop without breaking the automation flow.

Forward-compatible stage dispatch — adding V2 (Claude Code subprocess for implementation) or V3 (git commit + PR for delivery) requires only a new case in pipeline.Pipeline.runStage() and a new agent/runner package. No orchestration changes needed.

---

Testing

• pipeline/config_test.go — YAML round-trip, validation of required fields
• pipeline/state_test.go — save/load, directory creation, data integrity
• agents/requirements/config_test.go — Config.Validate() table-driven tests
• agents/architect/config_test.go — Config.Validate() including invalid task values

All existing tests (model, tools) continue to pass.

ok  github.com/ATMackay/agent/agents/architect    1.020s
ok  github.com/ATMackay/agent/agents/requirements 1.020s
ok  github.com/ATMackay/agent/model               1.020s
ok  github.com/ATMackay/agent/pipeline            1.024s
ok  github.com/ATMackay/agent/tools               1.028s