Worked Example: A Feature End to End

This walkthrough takes a single small feature — api-key-auth (authenticate API requests with an X-API-Key header) — through all six stages of the pipeline. Each section shows the command you run, what you approve, and a short illustrative artifact.

Before you start, make sure the project is initialized — run /feature-forge:forge-init once if you haven’t. You can check status at any point with /feature-forge:forge api-key-auth, and the verify gate is available after any stage. This walkthrough invokes verify by hand to show it; for real work, consider setting autoVerify: true so each stage is verified for you automatically.

Stage 1 — PRD

Run the PRD stage:

/feature-forge:forge-1-prd api-key-auth

You answer a short interview about scope and behavior, then approve the result. The stage writes specs/api-key-auth/PRD.md with numbered requirement IDs:

## Functional Requirements
- REQ-AUTH-01: Requests must include an `X-API-Key` header.
- REQ-AUTH-02: Requests with a missing or invalid key receive HTTP 401.

Stage 2 — Tech Spec

Run the tech spec stage:

/feature-forge:forge-2-tech api-key-auth

You confirm the technical approach, which references the PRD requirement IDs:

Decision: a middleware validates the header against a hashed key store
before the request reaches any handler — satisfies REQ-AUTH-01, REQ-AUTH-02.

This produces specs/api-key-auth/tech-spec.md and sets stack and testCommand in forge.config.json.

Stage 3 — Implementation Specs

Run the implementation specs stage:

/feature-forge:forge-3-specs api-key-auth

It produces a set of numbered spec documents — 00-core-definitions.md, 01-architecture-layout.md, and so on — plus a TRACEABILITY.md that maps each requirement to where it’s implemented:

| Requirement  | Spec section                          |
| ------------ | ------------------------------------- |
| REQ-AUTH-01  | 02-middleware.md — Header extraction  |

Stage 4 — Backlog

Run the backlog stage:

/feature-forge:forge-4-backlog api-key-auth

It turns the specs into discrete, verifiable work items. A single item looks like this:

{
  "id": "001",
  "type": "feature",
  "priority": 1,
  "title": "Add X-API-Key validation middleware",
  "description": "Implement middleware that reads the X-API-Key header and validates it against the key store; reject missing/invalid keys with 401.",
  "acceptanceCriteria": [
    "Requests without X-API-Key return 401",
    "Requests with a valid key reach the handler",
    "Test command passes"
  ],
  "status": "pending",
  "completedAt": null,
  "specReferences": ["specs/api-key-auth/02-middleware.md"]
}

type is one of bug, bugfix, refactor, feature, chore, or test. status is one of pending, in_progress, done, or blocked.

Stage 5 — Loop

Run the loop stage:

/feature-forge:forge-5-loop api-key-auth

The loop runner (rauf) works through the backlog one item at a time. It implements each item in a fresh context, runs the test command, and commits per item. You watch it run and step in only when it pauses for input.

Stage 6 — Docs

Run the docs stage:

/feature-forge:forge-6-docs api-key-auth

This produces docs/architecture/api-key-auth/ with a README, an architecture document, and an api-reference.

What you end up with

• specs/api-key-auth/PRD.md — requirements with IDs
• specs/api-key-auth/tech-spec.md — the technical approach, plus stack/testCommand in forge.config.json
• Numbered implementation specs and TRACEABILITY.md
• A validated backlog.json of discrete items
• Implemented, tested, committed code — one commit per backlog item
• docs/architecture/api-key-auth/ developer documentation

At any point you can re-check progress with /feature-forge:forge api-key-auth or run the verify gate. For the bigger picture, see the pipeline overview and core concepts.