Multi-section orchestration

Real apps don't fit in one prompt. CodeLoop ships a section-aware orchestration layer so an AI agent can build a 10-screen app over many sessions without losing track of progress, regressions, or scope changes.

The shape of a multi-section project

docs/
  specs/
    _master.md              # high-level master spec
    section-1.md            # one spec per section
    section-2.md
    ...
  acceptance/
    section-1.md            # acceptance criteria per section
    section-2.md
    ...

A working sample lives at examples/multi-section-sample.

Section state machine

Each section moves through pending → in_progress → completed | blocked. The agent uses codeloop_section_status to read or update state. The state file lives next to the run artifacts and is shared across IDE sessions, so resuming work the next morning picks up exactly where it left off.

Integration checks at every checkpoint

Section A passing in isolation does not guarantee A still works after Section B ships. codeloop_integration_check re-runs verify across the affected sections and reports per-section confidence so the agent can decide whether to fix B's regression or roll forward.

Replanning when scope changes

Edit _master.md or any section spec mid-build and the next codeloop_replan call detects the drift, recalculates the dependency graph, and re-queues affected sections for verification. The agent then resumes from the right point instead of restarting from scratch.

Prompt manager (5-layer pipeline)

For larger sessions where you don't want to repeat your goal in every prompt, the prompt manager exposes context-aware templates via codeloop_get_prompt:

• master_human — top-level framing the first time a user goal is received.
• planning — translate _master.md into an ordered build plan with section boundaries.
• section_implement — per-section build prompt with acceptance criteria and verification expectations.
• repair — constrained fix loop when verify or gate-check returns failures.
• integration — cross-section verification at predefined checkpoints.

Release readiness

When every section is completed, the agent calls codeloop_release_readiness to aggregate per-section confidence into a single go / no-go recommendation.

Concrete walkthrough: a 3-section app

Suppose you're building an e-commerce app with three sections: catalog, cart, and checkout. The agent's loop looks like this:

# 1. Initialise the project + create the spec scaffolding
codeloop_init_project   # writes docs/specs/_master.md + per-section stubs

# 2. Author the master spec and per-section specs (human work)
docs/specs/
  _master.md            # "An e-commerce app with catalog, cart, checkout"
  section-1.md          # Catalog: grid, filters, search, product detail
  section-2.md          # Cart: add/remove/quantity, persisted, badge in nav
  section-3.md          # Checkout: address, payment, confirmation
docs/acceptance/
  section-1.md          # 6 testable claims (search returns N>0, etc.)
  section-2.md          # 5 claims
  section-3.md          # 8 claims (incl. Stripe success path)

# 3. Agent picks up Section 1
codeloop_section_status      # → returns "section-1: pending"
                             # agent sets state to in_progress
codeloop_get_prompt section_implement  # gets section-1 build prompt
# ... agent codes the catalog ...
codeloop_verify              # build + tests + screenshots
codeloop_diagnose            # if anything failed, get repair tasks
codeloop_capture_screenshot  # per screen × viewport
codeloop_visual_review       # diff against baselines (or seed if first run)
codeloop_design_compare      # if Figma frames are mapped
codeloop_gate_check spec=section-1.md acceptance=section-1.md
                             # → ready_for_review @ 96 → mark section completed

# 4. Agent moves to Section 2 (cart)
codeloop_section_status set state=in_progress section-2
codeloop_integration_check   # confirm section-1 still passes after cart wiring
# ... build + verify + gate ...

# 5. Agent moves to Section 3 (checkout) — same pattern

# 6. All sections completed → release readiness
codeloop_release_readiness   # aggregates per-section confidence into go/no-go

Each step writes its evidence to artifacts/runs/<run_id>/; the dashboard renders the cross-section timeline so you can see how each section's confidence evolved.

Sample repository

A working e-commerce-style multi-section sample lives at examples/multi-section-sample. Clone it, run npx codeloop verify, and watch the loop progress through every section.

Common gotchas

• Spec edited without replan. Edit _master.md after sections are completed and the agent will read stale state. Always call codeloop_replan after a spec change.
• Integration check skipped. Each new section should run codeloop_integration_checkagainst all completed sections; it's the only way to catch cross-section regressions before release.
• Section state out of sync across machines. The state file lives in the project (.codeloop/sections.json); commit it so a teammate picking up tomorrow knows where you left off.

Related

• Tool reference
• Configuration
• Core concepts — section