PIPELINE.md

The Printing Press Pipeline

This document is the portable contract for the 9-phase generation pipeline the Printing Press runs when producing a CLI for an API. It describes what each phase consumes, what it produces, what gates it has to pass, and what artifacts it leaves behind. Everything here is implementation-agnostic: anyone porting this flow to another tool, another language, or another agent host should be able to follow this document without reading the Go source.

Two views of the same work

The Printing Press has a fast path and a managed path.

The fast path is the /printing-press skill. It runs the flow end to end in one session, produces a CLI plus an MCP server, and reports back. The high-level step list lives in README.md under "How It Works."

The managed path is the 9-phase pipeline. It breaks the same work into phases the user can stop at, resume, re-run, and inspect. Each phase has its own plan file, its own artifacts directory, and its own gate. This is what printing-press pipeline creates. It is also how this contract should be read: the fast path compresses these phases, it does not replace them.

Both paths converge on the same quality bar. A CLI produced by the fast path should score the same as one produced by the managed path.

Phase order

preflight  ->  research  ->  scaffold  ->  enrich  ->  regenerate  ->  review  ->  agent-readiness  ->  comparative  ->  ship

Phase names and ordering are defined in internal/pipeline/state.go (PhaseOrder). Phase numbering for plan-file prefixes lives in the same file (phaseNumber) and uses gaps (0, 10, 20 ...) so future phases can slot in without renaming existing files. The per-phase seed plans that describe each phase to the operator live in internal/pipeline/seeds.go.

Shared run directory layout

Every managed run gets three sibling directories under the run root:

• pipeline/ per-phase plan files, state.json, and phase-produced JSON artifacts
• research/ research-phase artifacts and discovery snapshots
• proofs/ review-phase artifacts: dogfood, verification, scorecard

The working CLI tree lives separately under the API's output directory until ship promotes it.

Phase status model

Every phase has two orthogonal status fields:

Field	Values
Status	pending, planned, executing, completed, failed
PlanStatus	seed, expanded, completed

Status tracks the execution state of the phase. PlanStatus tracks the state of the phase's plan file: a freshly-initialized phase has a seed plan; once expanded by the planner it becomes expanded; once the phase finishes it becomes completed. Both are defined in internal/pipeline/state.go.

LoadState and save() defensively initialize the on-disk phases map to an empty object when it is unmarshaled as nil. Phase names, ordering, transitions, and the version-migration semantics described in this document are unaffected by that guard.

Phases

Each phase below lists four fields: what it consumes, what it produces, what gates it must pass, and which artifacts it leaves on disk.

1. preflight

Purpose: confirm the local environment and the source inputs are fit for a pipeline run.

Inputs:

• Operator intent (API name, spec source)
• Local Go toolchain
• Printing Press binary

Outputs:

• Verified Go environment
• Verified printing-press binary
• Downloaded and validated OpenAPI spec for the target API
• conventions.json in the pipeline directory

Gates:

• Spec parses cleanly as OpenAPI 3.0+ (or the configured alternate format)
• printing-press binary version is recent enough for the pipeline features in use

Artifacts:

• pipeline/conventions.json
• Downloaded spec under the research directory

2. research

Purpose: discover and score the existing CLI landscape for the target API before committing to generation.

Inputs:

• Validated spec URL from preflight

Outputs:

• research.json in the pipeline directory with:
  • Discovered alternative CLIs (name, URL, language, stars)
  • Novelty score (1-10)
  • Recommendation: proceed, proceed-with-gaps, or skip
  • Gap analysis: what alternatives miss
  • Pattern analysis: what alternatives do well

Gates:

• If the novelty score is 3 or lower, the phase flags "an official or mature CLI already exists; consider whether this CLI adds value." The operator can still proceed.

Artifacts:

• pipeline/research.json
• Any competitor-identification notes under the research directory

3. scaffold

Purpose: generate the first working CLI from the validated spec.

Inputs:

• conventions.json from preflight
• Validated spec URL and downloaded spec source

Outputs:

• Generated CLI source tree under the API's output directory
• Root AGENTS.md operating guide for shell agents working inside the generated CLI tree
• Working CLI binary for the target API

Freshness ownership:

• Store-backed CLIs that opt into cache.enabled get a generated command-path freshness registry. Generated syncable resource read commands are registered automatically; hand-authored commands must opt in explicitly with command-path coverage.
• --data-source auto may run a bounded pre-read refresh for registered paths. --data-source local never refreshes. --data-source live reads the API and must not mutate the local store.
• Freshness metadata belongs in the existing JSON provenance envelope at meta.freshness. It describes current-cache freshness for the covered path only; it must not be described as full historical backfill or API-specific enrichment.

Gates:

• All eight generator quality gates pass: go mod tidy, default-mode govulncheck, go vet, go build, binary build, --help, version, doctor

Artifacts:

• Full CLI source tree in the output directory
• Compiled binary

4. enrich

Purpose: capture the spec enrichments missed by the first generation pass, without editing the source spec directly.

Inputs:

• conventions.json from preflight
• Scaffold-generated CLI in the output directory

Outputs:

• overlay.yaml in the pipeline directory
• At least one verified enrichment over the source spec
• Overlay content valid for downstream merge

Gates:

• Overlay merges cleanly against the source spec (checked in the regenerate phase before merge is committed)

Artifacts:

• pipeline/overlay.yaml

5. regenerate

Purpose: merge the enrichments into the source spec and regenerate the CLI without losing quality.

Inputs:

• overlay.yaml from enrich
• Original scaffolded CLI in the output directory

Outputs:

• Merged spec artifact
• Re-generated CLI in the output directory

Gates:

• Overlay merge completes without conflicts
• All eight generator quality gates pass again after regeneration, including default-mode govulncheck

Artifacts:

• Merged spec (format follows the source spec)
• Updated CLI source tree and binary

6. review

Purpose: evaluate the regenerated CLI with one shipcheck block - dogfood, runtime verification, and scorecard together.

Inputs:

• Working CLI binary from regenerate (or from scaffold if regenerate was skipped)
• Spec used to generate the CLI

Outputs:

• dogfood-results.json in the pipeline directory
• verification-report.json in the output directory
• scorecard.md in the pipeline directory
• review.md summarizing the combined shipcheck result

Gates:

• Dogfood: structural checks (path validity, auth, dead flags, wiring, MCP surface parity) pass at the configured tier. The mcp_surface_parity check requires generated MCP files to use the runtime Cobra-tree mirror; stale static novel-feature lists fail with a printing-press mcp-sync <cli-dir> remediation.
• Verify: runtime behavioral checks against the real API or a mock server return PASS (or WARN after an auto-remediation pass)
• Scorecard: overall grade clears the operator's configured threshold. Tier-1 dimensions include three MCP-shape dimensions (mcp_remote_transport, mcp_tool_design, mcp_surface_strategy) added in the April 2026 MCP production-readiness pass — opt-in via the (score, bool) pattern so CLIs without the relevant surface remain unscored.

Artifacts:

• pipeline/dogfood-results.json
• proofs/verification-report.json
• pipeline/scorecard.md
• pipeline/review.md

7. agent-readiness

Purpose: run the compound-engineering:cli-agent-readiness-reviewer against the generated CLI and apply its recommended fixes in a severity-gated loop (two passes at most).

Inputs:

• Runtime verification results from review
• Working CLI binary in the output directory

Outputs:

• Reviewer scorecard across seven principles and three severities
• Fix implementation log (which fixes were applied, which were skipped or reverted)
• Phase verdict: Pass, Warn, or Degrade
• pipeline/agent-readiness.md with a parseable Phase verdict: Pass|Warn|Degrade line and remaining Blocker/Friction findings as bullets or table rows

Gates:

• Pass - zero Blockers and zero Frictions
• Warn - Frictions remain but no Blockers
• Degrade - Blockers remain; phase fails

Artifacts:

• pipeline/agent-readiness.md
• Fix log in the pipeline directory

8. comparative

Purpose: score the generated CLI against the discovered alternatives on six dimensions.

Inputs:

• research.json from research
• dogfood-results.json from review
• Working CLI binary

Outputs:

• comparative-analysis.md in the pipeline directory with:
  • Score table (this CLI vs each alternative, 100 points maximum)
  • Gap summary
  • Advantage summary
  • Ship recommendation: ship, ship-with-gaps, or hold

Scoring dimensions:

Dimension	Points	How measured
Breadth	20	Command count ratio vs the best alternative
Install friction	20	Single binary = 20, clone+build = 15, runtime = 10
Auth UX	15	env var + config = 15, env only = 10, manual = 5
Output formats	15	5 per format (JSON, table, plain)
Agent friendliness	15	--json (5) + --dry-run (5) + non-interactive (5)
Freshness	15	under 30d = 15, under 90d = 10, under 1yr = 5, older = 0

Gates:

• Ship recommendation is ship or ship-with-gaps (hold fails the phase)

Artifacts:

• pipeline/comparative-analysis.md

9. ship

Purpose: package the generated CLI output and produce the final handoff report.

Inputs:

• Review score and review.md from the review phase
• Agent-readiness verdict from agent-readiness.md
• Working CLI binary ready for handoff

Outputs:

• Git repository initialized in the output directory
• Morning report written in the pipeline directory
• .printing-press.json provenance manifest at the CLI's root

Gates:

• All prior phases are completed
• agent-readiness.md reports Pass, unless a maintainer records an explicit override in the handoff
• Output directory contains a valid CLI source tree and compiled binary

Artifacts:

• Initialized git repo in the output directory
• Morning report in the pipeline directory
• Provenance manifest at the CLI root

Related flows

Two other Printing Press entrypoints run flows that share structure with the managed pipeline:

• printing-press run drives MakeBestCLI in internal/pipeline/fullrun.go. It compresses the full flow into one call and reports a single FullRunResult. Its internal step list (research, generate, polish, coverage, dogfood, verification, workflow-verify, scorecard, fix plans, publish) maps to the managed phases but does not use the phase state machine.
• The /printing-press skill uses its own high-level Phase 0..5 layout documented in README.md. That layout is a compression of the same work, not a competing contract.

Both flows should produce artifacts that match the shape described here for the phases they cover.

Shipcheck and phase gates

The review phase is where the shipcheck block runs - dogfood, verify, and scorecard together. These three checks also exist as standalone subcommands (printing-press dogfood, printing-press verify, printing-press scorecard) for operators who want to re-run a single check without advancing the pipeline. See AGENTS.md glossary entries for dogfood, verify, scorecard, and shipcheck for the canonical definitions.

Keeping this document in sync

Phase names, ordering, and numbering are authoritative in internal/pipeline/state.go. Per-phase intent, inputs, outputs, and pointers are authoritative in internal/pipeline/seeds.go. When those files change, update this document in the same PR. A future follow-up may generate this document from those sources automatically.