Key Concepts & Glossary

A short glossary of the terms you’ll meet across the pipeline. Each links to the stage where it’s used.

Pipeline & artifacts

Pipeline — the fixed sequence of stages that takes a feature from idea to shipped code: PRD → tech spec → implementation specs → backlog → loop → docs. See the pipeline overview. Progress is tracked in .pipeline-state.json, so the pipeline is resumable across sessions.

PRD (Product Requirements Document) — captures what the feature must do, in language a non-technical stakeholder can read. Produced by Stage 1 as PRD.md.

REQ ID — a stable identifier for a single requirement, formatted REQ-CATEGORY-NN (e.g. REQ-AUTH-01). Every later artifact traces back to these IDs, so nothing is silently dropped.

Tech spec — the technical design (how to build it), where every decision references a requirement. Produced by Stage 2 as tech-spec.md.

Implementation specs — numbered documents (00-core-definitions.md, 01-architecture-layout.md, …) with complete type definitions, error handling, and examples — everything needed to build the feature. Produced by Stage 3.

Traceability — the mapping from every requirement to the spec section that covers it, recorded in TRACEABILITY.md. It’s how the pipeline proves the specs cover the PRD.

Backlog — a backlog.json queue of self-contained work items the autonomous loop implements one at a time. Produced by Stage 4.

Acceptance criteria — the verifiable conditions on each backlog item that define “done” for that item. The loop must satisfy them before marking the item complete.

The verification gate

Verify & Fix gate — after any stage you can run forge-verify to analyze the artifacts for gaps, inconsistencies, and errors; it writes a findings document. forge-fix then applies those fixes. Because verify runs in a fresh, read-only subagent (clean-room by construction), it’s safe to run unattended: set autoVerify: true and the navigator verifies each stage for you. See Verify & Fix.

Auto-verify — the recommended default for hands-off runs: config-driven verification that fires automatically after a stage completes, costing your session only a compact digest. Fixing stays human-gated unless you also opt into autoFix.

The autonomous loop

Loop (Stage 5) — an autonomous coding loop (the default runner is rauf) that implements the backlog item by item, runs your tests, and commits each item. See Stage 5.

Fresh context per item — the loop starts each backlog item from a clean slate, with no memory of previous items. That’s why every backlog item must be self-contained — its description is the whole brief. Fresh context prevents drift in long autonomous runs.

Loop signals — what the per-item agent reports back: RAUF_DONE (the item passed; continue), RAUF_BLOCKED (a missing dependency or unclear requirement; set aside), and RAUF_NEEDS_HUMAN (a decision or secret is needed; awaits your answer).

Epics (large changes)

Epic — an optional Stage 0 wrapper that decomposes a change too large for one feature into several member features. Recorded in epic-manifest.json + EPIC.md.

Member feature — one feature inside an epic. Each runs the normal pipeline.

Charter — a one-paragraph statement of a member feature’s scope and obligations (not a full PRD).

Contracts — the structured interfaces between members: exposes (what a member provides) and consumes (what it needs from a sibling). With dependsOn edges, they define the epic’s dependency graph.

Parking decisions & concerns

Notes — free-form reminders on a feature’s .pipeline-state.json, surfaced on the dashboard. The catch-all parking lot.

Deferred decision — a decision that legitimately belongs to a later stage, recorded as a structured deferredDecisions[] entry (tagged with the stage that should resolve it) rather than buried in a note or decided prematurely. The owning stage picks it up when it runs.

Epic change request — a structured signal, raised from a member feature, that the epic decomposition must change (add or split a feature, move a boundary, fix a dependency). Routed back to Stage 0 to reconcile. See if the epic decomposition looks wrong.

Configuration

forge.config.json — project-root configuration (specs/docs locations, commit behavior, stack, loop runner, …). Full key reference: forge.config.json.