Skip to content

Build stages

/ritual build walks a feature through six named stages. The names are the same in the CLI’s progress header, the landing-page walkthrough, and this reference — one source of truth.

context → scope → discovery → recommendations → build brief → implementation (your agent)

The CLI renders the live progress like this:

Ritual build
● Context  ○ Scope  ○ Discovery  ○ Recommendations  ○ Build brief  ○ Implementation (Your agent)

Each stage has a clear user touchpoint (active interaction, passive wait, or background work) and a defined output the next stage consumes. Sync is no longer a separate stage — closing the loop back to the workspace KG happens as a built-in side effect of build brief + implementation, not as a user-visible step.

Why stages?

A coding agent given a vague prompt jumps to implementation immediately. It writes plausible code that reviewers later find missing huge chunks of product judgment. The stage loop forces that judgment to happen before code is written — and makes it visible as a measurable score (Reasoning Readiness climbing from ~18% to ~88% over the loop).

01 — Context

What happens: The agent scans the codebase for files relevant to the feature description, maps candidate paths, identifies existing primitives that may be reused, and queries the workspace KG for prior decisions on related files. If /ritual context-pulse was used as a Mode B pre-build seed, the resulting CONTEXT-<slug>.md is read here.

Your touchpoint: Mostly passive. The agent surfaces a codebase_context_packet (facts, evidence, hypotheses, confidence) and may ask clarifying questions if the codebase signal is ambiguous.

Output: Annotated file list + prior-decision summary. Feeds into scope generation.

Typical duration: 10–60 seconds.

Readiness impact: Bumps Repo grounding dimension. Doesn’t move other dimensions much on its own.

02 — Scope

What happens: The agent turns the raw ask into a structured problem statement, generates a list of candidate sub-problems, and asks you to pick which to solve for. It then produces a developer-oriented problem frame — a short, constraint-loaded statement of what the build should optimize for — and surfaces references (RBs / decisions / prior explorations) that constrain the scope. You either lock the frame or iterate (tighten, broaden, focus on outbox, drop dashboard, etc.).

Your touchpoint: Active. You pick which sub-problems shape the build, then accept or refine the problem frame.

Output: Locked problem statement + selected sub-problems. Exploration is created in the workspace immediately after lock.

Typical duration: 1–5 minutes.

Readiness impact: Moves Feature clarity sharply (acceptance signals become scorable) and Assumption safety (anti-goals declared via “drop X” instructions).

03 — Discovery

What happens: For each discovery area, the agent generates a structured set of questions classified by risk:

  • 🔴 Blocking — must be answered or the agent will guess wrong
  • 🟡 Uncertain — answer would improve quality but agent can pick a reasonable default
  • 🟢 Answerable — agent can answer from codebase / KG / public docs without asking

You pick which questions to engage with. The agent answers the 🟢 ones from context; pauses for you on the 🔴 and 🟡 ones it can’t safely default.

Your touchpoint: Active. You read the questions, pick the ones that matter, supply answers. This is where the biggest readiness gain happens — typically 38% → 60%.

Output: Answered questions + classification of unpicked ones (deferred vs out-of-scope vs unreviewed).

Typical duration: 5–20 minutes — depends on how many blocking questions exist and how quickly you can answer.

Readiness impact: Biggest single-stage jump. Moves Decision resolution substantially.

04 — Recommendations

What happens: The agentic pipeline takes the answered discovery questions + the codebase context and generates structured recommendations across each open decision (model choice, data scope, integration boundaries, rollout sequence, etc.). For each recommendation it produces rationale + rejected alternatives + impact. You then accept, refine, or reject each one — locking an approved snapshot before the build brief is generated. Acceptance is part of this stage, not a separate “Review” stage.

Your touchpoint: Mixed. Passive wait while the pipeline runs (the CLI shows progress); active when the recs land and you accept or iterate. Collaborators (PM, security, eng lead) weigh in here if needed.

Output: An approved snapshot — a locked-in, immutable version of the recommendations that the build brief and implementation reference. Updates create a new snapshot version.

Typical duration: 3–8 minutes for the pipeline; 5–15 minutes for acceptance (longer if a collaborator handoff is needed — then /ritual resume picks it up when answers come back).

Readiness impact: Locks in Decision resolution at near-maximum. Moves the Context Surface tier from “Exploration-safe” to “Recommendation-ready.”

05 — Build brief

What happens: The agent generates BUILD-BRIEF.md — the implementation-ready delivery context the implementation stage will work from. The brief contains:

  • Numbered review-blocking items (RB-001, RB-002, …) with acceptance criteria
  • Rationale for each decision (links to the approved recommendations)
  • Rejected alternatives (so reviewers can see what was considered + why declined)
  • Files expected to change
  • Anti-goals (what’s explicitly OUT of scope)
  • Phase-2 candidates (deferred items, not debt)

Your touchpoint: Passive wait. You can read the brief while it generates if you want a preview.

Output: BUILD-BRIEF.md written to the repo root, committed to the feature branch.

Typical duration: 30 seconds – 2 minutes (longer in the cold-start case when the requirement set has to be synthesized inline — up to ~90 seconds).

Readiness impact: Moves Context Surface to “Implementation-ready” (typically 88%+). Implementation now has unambiguous targets to verify against.

06 — Implementation (Your agent)

This stage runs in your coding agent, not in Ritual. Ritual orchestrates stages 1–5 and hands off BUILD-BRIEF.md. Your agent (Claude Code / Cursor / Codex / Kiro / etc.) does the actual code-writing against the brief and writes back to the knowledge graph via sync_implementation.

What happens: The coding agent codes from the brief. Review-blocking (RB) items first, in order. Each commit references the RB it addresses. As implementation lands, the agent writes back to the workspace KG what shipped — commits, files touched, RBs verified, decisions implemented, deferrals confirmed, any drift between the brief and the actual code. This is what makes /ritual lineage <file> work later, and what gives future /ritual build runs a warmer start.

Your touchpoint: Varies. Some agents/teams prefer to watch and intervene; others let it run autonomously and review at the end. The brief is structured so a reviewer can verify any commit against a numbered RB.

Output: Implementation commits on the feature branch + KG entries for each implemented decision, with lineage links from the new files back to the exploration that shaped them.

Typical duration: Hugely variable — minutes for a small feature, hours for a complex one. Independent of stage ordering.

Readiness impact: Doesn’t move readiness for the current exploration (readiness is about pre-implementation grounding). But the KG writebacks are the mechanism by which future explorations in the same workspace start with higher initial readiness — the KG remembers what was decided.

How stages interact with the rest of the workflow

  • /ritual context-pulse can fire against any of the six stages as a checkpoint — see the Context Pulse reference for the “inline pulse” mode.
  • /ritual resume can pick up at any stage boundary. The exploration’s current stage is persisted; the next /ritual build (or /ritual resume) continues from there.
  • /ritual lineage <file> queries the KG that the implementation stage populates as code lands.