The ARCUS Pipeline

Understanding ARCUS's full Spec → Code → Pull Request stage map

---

Where the canonical list lives

This page is the single human-readable enumeration of the ARCUS pipeline. The stateful arcus-controller orchestrator owns the session checkpoint and stage gates, driving the 6 phases by handing each capability its explicit inputs (see Modes).

Built from reusable capabilities

Each stage below is built from the three-tier capability library — atomic capabilities, thin coordinators, and the stateful orchestrator. See The Capability Library for how the pipeline's stages are assembled from reusable, plug-n-play building blocks.

The Pipeline at a Glance

ARCUS transforms a written user story into a reviewed, test-backed pull request through a sequence of stages, tracked in the session checkpoint by these ordered stage keys:

scaffold → context_pack → spec_finalizer → plan → test_plan → branch → task_1..N → code_review → context_sync → closure

The ten stages group into six human-facing phases:

1. Brainstorm — Scaffold the workspace, build the context pack, finalize the spec, and produce the implementation plan (scaffold, context_pack, spec_finalizer, plan) — the only place the pipeline stops for you, and only if a stage raises open questions
2. Test Plan — Design the verification matrix (test_plan)
3. Implementation — Create the branch, then implement & verify each task (branch, task_1..N)
4. Code Review — Two-tier holistic gate over the whole branch diff (code_review)
5. Context Sync — Reconcile the shared .context/ artifacts that the approved diff materially drifted (context_sync; automatic continuation)
6. Closure — Create the pull request (closure)

Stages produce specific artifacts. The pipeline's pausing behavior depends on mode (see Three Modes, One Pipeline): in gated mode, it pauses for open questions during Brainstorm and optionally at phase boundaries; in intelligent mode, only for Brainstorm questions; in afk mode, never. The rows below note each stage's handoff gate, where the orchestrator presents the just-finished stage's output. Within Brainstorm the scaffold, context_pack, spec_finalizer, and plan stages run back-to-back — arcus-controller runs context-pack-builder → spec-finalizer → implementation-planner directly — before any questions are surfaced. The Code Review stage can loop back to Implementation up to 3 times if changes are requested.

Skills vs agents. The participants below live on one of two surfaces (see The Capability Library): user-invocable skills (plugins/arcus/skills/) and model-only agents (plugins/arcus/agents/), dispatched by name and never user-facing. Dispatched participants — context-pack-builder, subagent-task-dispatcher, code-simplifier, the five specialist/spec reviewers, and context-drift-sync — are agents; the stage entry points (arcus-controller, code-reviewer, implementation-runner) are skills.

What The Gates Mean

Gates are explicit pause points where you review outputs before the pipeline moves to the next stage (gated experience only).

Gate	Between Stages	Meaning
Gate A	Brainstorm → Test Plan	Grounded spec and plan are ready for test design.
Gate B	Test Plan → Implementation	Test strategy is approved; the branch can be created and implementation can begin.
Gate C	Implementation → Code Review	Code and tests are complete; ready for holistic review.
Gate D	Code Review → Context Sync (or loopback)	Review decision point: approve (advances to Context Sync, which then auto-continues to Closure), or send fixes back to Implementation.

Context Sync → Closure is an automatic continuation (no user decision gate — like Test Plan auto-running): once the .context/ reconciliation is decided, the pipeline proceeds straight to Closure.

Gates are phase-boundary pauses specific to gated mode. For how modes control which gates fire and whether open questions surface, see Three Modes, One Pipeline.

---

Stage Breakdown

Scaffold

Purpose: Set up the workspace and record the planned branch — without creating actual git branch
What happens	Skills / scripts involved	Artifacts created
Scaffolds .arcus/specs/[STORY-ID]/ directory Copies story file to the workspace Initializes session-checkpoint.json recording the planned branch_name / base_branch No git branch is created — branch creation is deferred to the branch stage at the start of Implementation. See [Deferred Branch Creation](#deferred-branch-creation) Exception — linked worktrees: if the workspace is a git worktree already on a dedicated session branch, that branch is adopted as the story branch (base resolves to the repo default) and the branch stage is pre-completed	scaffold.sh (deterministic script) Branch naming via scripts/lib/branch_name.sh Driven by arcus-controller (orchestrator; interactive or autonomous)	.arcus/specs/[STORY-ID]/story.md (copy of original) .arcus/session-checkpoint.json (planned branch fields, no branch)
Scaffold flows directly into Brainstorm.

What to check:

• Story copied correctly to workspace
• Planned branch name looks right (arcus/[STORY-ID]-N)

---

Brainstorm

Purpose: Build context, resolve ambiguities, capture design decisions and produce a task-level plan
What happens	Skills involved	Artifacts created
Builds a story-specific context pack (stage key context_pack) Analyzes the story for completeness and resolves ambiguity (stage key spec_finalizer) Both capabilities always run one-shot inside subagents and always resolve every ambiguity / select an approach themselves. Each also records what it was least confident about in an ## Open Questions block in its own artifact — every entry presenting exactly one Recommended option + one-line rationale, with the reader free to answer in their own words Gated and intelligent modes: the orchestrator surfaces that block to you, all questions at once, and folds your reply back in. AFK mode: the block is recorded but never surfaced. See Three Modes, One Pipeline for the full comparison Produces the implementation plan and task list (stage key plan)	context-pack-builder (agent) spec-finalizer (one-shot subagent, all three modes) implementation-planner (one-shot subagent, all three modes) Driven by arcus-controller (orchestrator; interactive or autonomous)	context-pack.md — Story-specific context bundle grounded-spec.md — Grounded story decisions (context grounding, resolved ambiguities, open questions, dialogue answers, implementation boundary) — written by spec-finalizer plan.md — Design deliberation (approach evaluation, chosen approach, impacted files) plus the atomic ### Task N: task list — written by implementation-planner
The Brainstorm stop: if spec-finalizer or implementation-planner recorded open questions, gated and intelligent modes surface them as one batch and wait. Answer them and the pipeline runs to the PR without stopping again (unless gated mode is also configured with phase-boundary gates via stop_after). No questions raised → no stop in those modes. AFK mode never surfaces them. Resume phrase: resume <STORY-ID>.

What to check:

• Grounded decisions in grounded-spec.md align with your intent
• No missing technical constraints; error handling makes sense
• Tasks in plan.md are atomic and correctly ordered

Tip: This is the place where "make-or-break" decisions are taken before implementation. Review grounded-spec.md and plan.md carefully.

---

Test Plan

Purpose: Design comprehensive test matrix before writing code
What happens	Skills involved	Artifacts created
Reviews the task list in plan.md and the grounded decisions in grounded-spec.md Organizes cases into one ### Task N: subsection per plan task (plus a closing ### All Tasks subsection for cross-cutting regression), each case tagged with a Category: Happy Path: functional verification Edge Case: boundary conditions, null handling Error Case: validation failures, exception paths Regression: existing flows that must stay green Indexes every case in a Task-to-Test Mapping Matrix, keyed to plan.md task IDs Follows patterns from .context/testing-patterns.md	test-spec-compiler (stage key test_plan)	test-plan.md — Task-keyed test matrix (### Task N: subsections), each case categorized Happy Path / Edge Case / Error Case / Regression
Continues straight into Implementation. Resume phrase: resume <STORY-ID>.

What to check:

• Test coverage feels comprehensive
• Edge cases captured; error scenarios realistic
• Test structure follows repo patterns

Tip: Add missing test cases to test-plan.md before proceeding. This is TDD in action.

---

Implementation

Purpose: Create the branch, then implement the story with continuous verification
What happens	Skills involved	Artifacts created
Branch stage (branch): realizes the git branch that was only planned at scaffold — branch.sh creates arcus/[STORY-ID]-N from the base, bumps the index on collision, and calls checkpoint.sh set-branch if the realized name differs from the plan. Skipped when scaffold adopted a worktree's session branch (the stage is already complete) Parses ### Task N: headings from plan.md (stage keys task_1..task_N) Dispatches each task to an isolated subagent. Each task includes: Implementation Test writing (following test-plan.md) Refactor gate (code-simplifier agent): mutate toward simplicity, re-run suite — skipped on light tasks One lightweight, advisory per-task spec-compliance check (does not hard-block; unresolved issues carry forward to Code Review) Commits code incrementally (one commit per task via commit.sh) Quality is not reviewed per-task — it is owned holistically by Code Review over the whole branch diff, since isolated subagents never see prior tasks' code.	implementation-runner (the single canonical loop driver — owns the branch step + task loop; reused by gated and afk) branch.sh (deferred branch realization) subagent-task-dispatcher (agent) — per-task execution code-simplifier (agent) — per-task refactor gate, skipped on light spec-compliance-reviewer (agent) — per-task mode, advisory	Git branch arcus/[STORY-ID]-N (created here, not at scaffold) Code changes (committed to branch) Tests (committed alongside code)
Continues straight into Code Review. Resume phrase: resume <STORY-ID>.

What to check:

• All tests pass locally
• Implementation feels complete; no obvious gaps
• Commits are clean and atomic

Tip: You can edit the task list in plan.md at Gate A or Gate B before implementation begins.

---

Code Review

Purpose: The real last gate before a PR — a two-tier review over all changes, with a zero-trust persona (brutal in the hunt, fair in the verdict)
What happens	Skills involved	Artifacts created
Reviews the full branch diff (not individual tasks) Tier 1 — Deterministic Gate (runs the repo's real tooling, fails fast): executes the actual commands CI would run over the integrated branch — never simulated by reading the diff. Resolved from CI workflows first, then .context/ tables. Typecheck / compile Full test suite (per-task green ≠ whole-branch green) Build + startup smoke Secret scan Lint & format (auto-fixed and committed where a fix mode exists) Static analysis (feeds the semantic tier) Any hard block (typecheck / tests / build / secret) skips the semantic fan-out and returns changes_requested immediately. Unresolvable commands are recorded as skipped: not configured. Tier 2 — Semantic Review (only if the gate passes): fans out to specialists for judgment-grade concerns no tool can answer: Spec compliance (holistic): Does it meet all requirements? Code quality (holistic): Clean structure, maintainability, cognitive complexity, test proportionality? Security: Any exploitable vulnerabilities? Performance: Any concrete regressions? History/Context: Any load-bearing complexity removed, silently-reverted fixes, or re-added previously-reverted code? (skipped on docs-only diffs and shallow history) Consolidates findings Deduplicates and filters noise Assigns severity levels: critical - Blocks merge (outage, data loss, security breach) warning - Concrete issue (performance hit, maintainability concern) suggestion - Minor nit (non-blocking) Returns verdict: approved or changes_requested	code-reviewer (skill — coordinator) + deterministic gate; stage key code_review spec-compliance-reviewer (agent) — holistic mode code-quality-reviewer (agent) — holistic mode security-reviewer (agent) performance-reviewer (agent) history-context-reviewer (agent)	review.md - Deterministic gate results + consolidated semantic findings with verdict
Acts on the verdict without asking: approved → Context Sync (then auto-continues to Closure); changes_requested → the Loopback Protocol runs automatically, up to 3 rounds. Resume phrase: resume <STORY-ID>.

What to check:

• Review findings are accurate; severity levels appropriate
• No false positives; critical issues are genuine blockers

Tip: If you disagree with findings, you can proceed anyway (override verdict).

---

Context Sync

Purpose: Reconcile the shared .context/ artifacts that the approved branch diff materially drifted — facts-only, diff-driven, no full rescan
What happens	Skills involved	Artifacts created
Strictly assesses whether the approved branch diff materially changed any .context/ artifact (business flows, repo_map.md, repo_scope.md, testing-patterns.md, design-and-coding-patterns.md) Surgically syncs only the affected artifacts, refreshing their context-meta; updates AGENTS.md only when a flow file is added or removed Facts-only and diff-driven — no full repository rescan Gated: shows a drift assessment plus a single consolidated yes/no AFK: auto-decides Also standalone-invocable via sync context for <STORY-ID> / sync context Produces no new artifact; the rationale is persisted in the sync commit body	context-drift-sync (agent) — stage key context_sync	No new artifact — updates existing .context/ files in place; rationale lives in the sync commit body
Auto-continues to Closure once the reconciliation is decided.

What to check:

• The drift assessment correctly identifies which .context/ artifacts the diff touched
• Only materially-affected artifacts were synced (no over-reach)

For the full picture of how the shared .context/ artifacts are built, scoped, and kept current, see Context Engineering.

---

Closure

Purpose: Create pull request with evidence and context
What happens	Skills involved	Artifacts created
Runs final test suite Gathers evidence of completion Synthesizes PR description from: Original story Grounded decisions in grounded-spec.md Plan and task list (plan.md) Test results Review findings Pushes the branch and creates the pull request via pr.sh (gh pr create); the base_branch read by pr.sh has been populated in the checkpoint since scaffold time	pull-request-builder (terminal stage; stage key closure) pr.sh	PR_DESCRIPTION.md - Final PR body
Terminal stage. PR created, or ready for manual creation.

What to check:

• PR description is accurate and complete
• All tests pass
• Branch is up to date with base

---

Deferred Branch Creation

ARCUS creates the git branch late — at the start of Implementation, not during Scaffold:

1. Scaffold (scaffold.sh) creates the spec folder, copies story.md, and initializes the checkpoint recording the planned branch_name and base_branch. No git branch exists yet.
2. The branch naming convention arcus/<STORY-ID>-N is defined once in the shared scripts/lib/branch_name.sh library (sourced by both scaffold.sh and branch.sh).
3. Implementation begins with the branch stage: branch.sh (driven by the implementation-runner skill) reads the planned name, re-checks for collisions created since scaffold (bumping the index if needed), creates and checks out the branch, and calls checkpoint.sh set-branch if the realized name differs from the plan.

This keeps planning entirely on the base branch and only branches once there is actual code to commit.

Exception: adopted branches in a worktree

Deferred creation assumes ARCUS gets to choose the branch. In a linked git worktree it does not — the host already checked the workspace out on a dedicated session branch and, typically, bound its pull-request tracking to it. Creating arcus/<STORY-ID>-N off that branch would leave the story somewhere the session cannot see.

So when scaffold.sh finds a linked worktree on a non-default branch, it adopts that branch instead of planning one:

• branch_name = the current branch;
• base_branch = the repository default (origin/HEAD, falling back to main then master) — the adopted branch cannot be its own base without producing a self-targeting PR. If none of those resolve, scaffold fails and asks for --base rather than inventing one;
• the branch stage is marked complete, so Implementation skips branch.sh entirely (and branch.sh no-ops if called directly anyway).

scaffold.sh reports which path it took as BRANCH_MODE: new|adopted. Override with --new-branch to force planning, or --use-current-branch to force adoption outside a worktree. A third value, existing, means a checkpoint was already on disk so scaffold decided nothing and echoed the stored branch fields — that is a resume, not a scaffold.

---

Review Loopback Mechanism

If Code Review returns changes_requested:

1. Fix-tasks generated from review findings (appended to plan.md)
2. Loop back to Implementation (re-enters implementation-runner)
3. Subagents address issues following the fix-tasks
4. Return to Code Review for re-review
5. Bounded to 3 rounds maximum to prevent infinite loops
6. Manual intervention required if the 3rd round still fails

Why bounded? Prevents loops on subjective or unclear issues. After 3 rounds, human judgment is needed.

---

Quick Stage Reference

Phase	Stage key(s)	Entry / resume phrase	Exit condition
Brainstorm	scaffold, context_pack, spec_finalizer, plan	arcus <STORY> (gated) or plan <STORY> (alias)	Workspace + planned branch ready; grounded-spec.md and plan.md complete
Test Plan	test_plan	generate test plan for <STORY>	test-plan.md complete
Implementation	branch, task_1..N	implement <STORY> / code <STORY>	Branch created, all tasks done, tests pass
Code Review	code_review	review <STORY>	Verdict: approved / changes_requested
Context Sync	context_sync	sync context for <STORY>	Affected .context/ artifacts reconciled (auto-continues to Closure)
Closure	closure	close <STORY>	PR created

---

Artifacts

Each story produces a working area under .arcus/specs/[STORY-ID]/ with the following artifacts:

Artifact	Purpose
session-checkpoint.json	Resumable per-stage execution state (ordered stage keys + status enum), including the planned/realized branch_name and base_branch
story.md	Canonical copy of the input story
context-pack.md	Compact, token-efficient context bundle
grounded-spec.md	Grounded story decisions: context grounding, resolved ambiguities, open questions, dialogue answers, implementation boundary (written by spec-finalizer)
plan.md	Design deliberation plus the atomic task list (written by implementation-planner)
test-plan.md	Generated verification matrix and test cases
review.md	Deterministic gate results + holistic code-review findings + verdict
PR_DESCRIPTION.md	Final PR body

Treat .arcus/ as ephemeral working data - safe to inspect, commit, or discard.