assemble 🦸

The Avengers, but for your codebase. A multi-agent dev workflow orchestrator: Plan → Design → Implement → Release, with a different AI model cast for every role — and gates that agents cannot skip, because the state machine lives in a CLI (the Director), not in prose.

Successor to TRIP-workflow: same philosophy (writer ≠ reviewer, long-term ARCHI.md memory, few commands), but models are config, gates are code, and any provider CLI can join the team.

Fury (orchestrator) never writes code. He assembles the team, hands out missions, guards the gates, keeps the ledger — and calls you (the World Security Council) when a mission needs a human decision.

Contents

• The roster
• The mission loop
• How a hero gets cast (config resolution)
• The review loop (why agents can't skip gates)
• Quick start
  • Build & run from source (local)
• Cast any model into any role
• Budget caps
• Design docs

The roster

Agent	Mission	Default casting
🕶️ fury (orchestrator)	The Director — the CLI engine itself. Orchestrates, enforces, never fights	deterministic code
🤖 stark (architect)	Plans the mission & designs the architecture	strongest reasoning model
🧬 shuri (UI designer)	UI/product design (flavor: ui)	strong + fast
🔮 strange (plan/design reviewer)	Reviews plans & designs — checks 14,000,605 futures, approves the one that works	cross-provider reviewer, effort: xhigh
🟡 vision (code reviewer)	Delta code-review on each batch — precise, worthy	mid-tier
✨ danvers (final reviewer)	Final full-tree code review — flies in fresh, zero context contamination	big-context model
🔨 thor (implementer) / 💪 hulk (refactorer)	Heavy implementation batches & big refactors	strong workers
🕷️ spidey (small batches) / 🏹 hawkeye (minor edits)	Fast small batches / precision minor edits	cheap + fast
🛡️ cap (release)	Release: assembles notes, holds the line — ship order comes from you	reliable mid-tier
🧠 jarvis (memory)	memory-sync: keeps ARCHI.md (long-term memory) current, compacts it	cheap
💼 pepper (ledger)	The ledger: every token & dollar. Budget breached → Pepper freezes the card (run pauses)	deterministic code
🌈 heimdall (gates)	The gates. Nothing crosses without a recorded verdict	deterministic code
🥷 ronin (ad-hoc)	Ad-hoc off-book missions (--adhoc): review anything, mutate nothing	any
🧹 Damage Control (cleanup)	assemble clean — dead worktrees, stale sessions	deterministic code
🏛️ You (human)	World Security Council: human gates, escalations, budget overrides	human

Hero names are agent roles in config — cast any provider/model into any role. Protocol constants stay boring (APPROVED, plan-review) so tooling never depends on flavor.

Theme disclaimer: this project is not affiliated with, endorsed by, or sponsored by Marvel or Disney. The MCU character names are just the default, fully swappable display theme; protocol constants and machine-readable identifiers are unthemed.

The mission loop

flowchart TD
    subgraph P["/assemble-plan"]
        plan["🤖 stark (architect)<br/>plan (interactive)"] --> pr["🔮 strange (plan/design reviewer)<br/>plan-review"]
        pr -->|REQUEST_CHANGES ≤ max_rounds| plan
        pr -->|APPROVED| HGATE{{"🏛️ Council (human)<br/>approve-to-implement"}}
        HGATE -->|approved| design["🤖 stark (architect) / 🧬 shuri (UI designer)<br/>design (auto · skippable)"]
        design --> dr["🔮 strange (plan/design reviewer)<br/>design-review"]
        dr -->|REQUEST_CHANGES| design
    end
    dr -->|APPROVED| GATE1{{"🌈 heimdall (gates)<br/>plan-review APPROVED<br/>design-review APPROVED"}}
    GATE1 --> subI

    subgraph subI["/assemble-implement"]
        direction TB
        dag["batch DAG from stark (architect)'s manifest"] --> w1["🔨 thor (implementer)<br/>batch A · worktree"]
        dag --> w2["🕷️ spidey (small batches)<br/>batch B · worktree"]
        w1 --> t1["✅ tests/lint"] --> cr1["🟡 vision (code reviewer)<br/>delta review"]
        w2 --> t2["✅ tests/lint"] --> cr2["🟡 vision (code reviewer)<br/>delta review"]
        cr1 -->|REQUEST_CHANGES| w1
        cr2 -->|REQUEST_CHANGES| w2
        cr1 -->|APPROVED| merge["merge in dependency order"]
        cr2 -->|APPROVED| merge
        merge --> full["✨ danvers (final reviewer)<br/>full review · fresh thread"]
    end
    full --> GATE2{{"🌈 heimdall (gates)<br/>code-review APPROVED<br/>tests PASS"}}
    GATE2 --> subR

    subgraph subR["/assemble-release"]
        rel["🛡️ cap (release)<br/>release · 🏛️ Council (human) approves"] --> mem["🧠 jarvis (memory)<br/>memory-sync → ARCHI.md"]
    end
    subI -.every invocation.-> pepper["💼 pepper (ledger)<br/>ledger + budget caps"]

Loading

How a hero gets cast (config resolution)

flowchart LR
    S["stages:<br/>code-review:<br/>&nbsp;&nbsp;agent: vision"] --> A["agents:<br/>vision:<br/>&nbsp;&nbsp;profile: sol-reviewer"]
    A --> M["models:<br/>sol-reviewer:<br/>&nbsp;&nbsp;provider: codex<br/>&nbsp;&nbsp;model: gpt-5.6-sol<br/>&nbsp;&nbsp;effort: xhigh"]
    M --> PR["providers:<br/>codex:<br/>&nbsp;&nbsp;adapter: codex"]
    PR --> CLI["codex exec --json<br/>-c model=gpt-5.6-sol<br/>--sandbox read-only"]
    ENV["ASSEMBLE_STAGE_code-review_MODEL=…"] -.overrides.-> S

Loading

Recast one hero (edit one profile) and every stage they work changes. Or pin a stage inline: code-review: {provider: claude, model: claude-haiku-4-5-20251001}.

The review loop (why agents can't skip gates)

sequenceDiagram
    participant F as 🕶️ fury (orchestrator)
    participant T as 🔨 thor (implementer)
    participant V as 🟡 vision (code reviewer)
    participant C as 🏛️ Council (human — you)
    F->>V: batch diff + docs (read-only sandbox)
    V-->>F: JSON verdict {REQUEST_CHANGES, findings[]}
    F->>T: findings (resumed session)
    T-->>F: fixes applied
    F->>V: re-review (same thread, remembers round 1)
    V-->>F: {APPROVED}
    Note over F: APPROVED → machine gate opens automatically, no human needed
    Note over F,C: max_rounds exhausted → escalate to human gate:<br/>assemble gate approve / reject

Loading

Each review stage carries a two-phase gate:

1. Machine gate — the reviewer emits a schema-validated verdict (APPROVED, REQUEST_CHANGES, or BLOCKED). APPROVED opens the gate automatically — no human in the loop. Anything else routes the implementer back to needs_rework (carrying the reviewer's concerns) and re-runs the loop. Reviewers are read-only and never commit; a malformed or missing verdict line is recorded as REQUEST_CHANGES, so a run never auto-approves on an agent that ignored the protocol.
2. Human gate — the loop is bounded by the stage's max_rounds. When the reviewer and implementer can't converge in that budget, the run escalates to you (the World Security Council) to approve the work as-is or reject it for another round. Any stage marked gate: human also pauses here.

Both the reviewer and the implementer resume their own sessions across rounds: the reviewer re-examines only what changed since its last verdict, and the implementer addresses the feedback in-thread rather than re-drafting cold. No verdict on file → the next stage refuses to start. A disobedient agent can stall — never skip.

Quick start

npm i -g @bugbeast/assemble        # installs the `assemble` command
cd your-repo && assemble init      # scaffold assemble.config.yaml (MCU theme)
assemble run                       # run the full pipeline serially:
                                   #   stark (architect) plans → strange (plan/
                                   #   design reviewer) reviews → you approve the
                                   #   plan → thor (implementer) builds in gated
                                   #   batches → cap (release) ships
assemble status                    # mission board · who's working
assemble cost                      # token cost by worker and stage
assemble budget                    # per-scope spend vs caps · pepper (ledger)'s books

Human gate points pause the run for your decision:

assemble gate approve <stage>      # World Security Council says go
assemble gate reject  <stage>      # send it back for rework

By default two stages wait for you: plan-review (your approve-to-implement sign-off, once strange has APPROVED the plan) and release (ship order). Add gate: human to any other stage to pause there too.

assemble init also drops the assemble protocol at the repo root so any worker that opens the repo follows the same gates: a CLAUDE.md skill for Claude and a mirrored AGENTS.md for codex (and other AGENTS.md-aware CLIs). Both are refreshed in place inside a marked block on re-init and never clobber your own notes.

Build & run from source (local)

No npm release needed — build it yourself and put the assemble command on your PATH:

git clone https://github.com/basant-kumar/assemble.git
cd assemble
npm install            # install deps
npm run build          # tsc → compiles src/ to dist/ (produces dist/cli.js)
npm link               # symlink the `assemble` command onto your PATH

# now use it in any repo, backed by your local build:
cd /path/to/your-repo
assemble init
assemble run

Prefer not to touch your PATH? Run the built entrypoint directly instead of npm link:

node /path/to/assemble/dist/cli.js init      # equivalent to `assemble init`

Iterating on the code:

npm run build          # recompile after editing src/
npm test               # run the vitest suite

Requires Node ≥ 18. npm link is undone with npm unlink -g @bugbeast/assemble.

Example board mid-mission:

run 2026-07-20-dark-mode          budget $9.40 / $25
  plan-review    APPROVED  (strange (plan/design reviewer), round 2)
  design-review  APPROVED  (strange (plan/design reviewer), round 1)
  implement      RUNNING
    🔨 thor (implementer)        batch auth-api    round 2 · vision (code reviewer) reviewing
    🕷️ spidey (small batches)    batch ui-toggle   merged ✓
  code-review    pending → danvers (final reviewer)

Cast any model into any role

Copy profiles from templates/assemble.config.example.yaml — a catalog of ready-made profiles for Claude (fable, opus, sonnet, haiku), Codex (gpt-5.6 family, codex-mini), Gemini, OpenCode and Mistral Vibe, with knobs and $/Mtok pricing for pepper (ledger)'s books.

A mode: at the top of assemble.config.yaml is a shorthand that seeds an agents block and rewires every stage at load time — pick one instead of hand-casting the whole roster:

mode:	seeds	stage wiring
solo	solo — claude/fable-5	every stage → solo (cheapest, no cross-check)
duo	writer — claude/fable-5 · reviewer — codex/gpt-5.6-sol (effort high)	review stages (code/plan/design-review) → reviewer, all others → writer (cross-provider, TRIP's proven setup)
full	nothing — your agents: block is used as written	the roster, each hero tuned separately (omit mode: for the same effect)

An agents: entry with the same name (solo/writer/reviewer) overrides the preset's profile — e.g. redefine reviewer to bump its model. To pin individual stages, use mode: full (or omit it). The configure wizard asks which shape you want and writes the chosen mode: for you.

Budget caps

Give pepper (ledger) a spending limit. Drop a budget: block into assemble.config.yaml — every cap is optional and scoped to a single run's ledger (the $9.40 / $25 on the board above is a total cap):

budget:
  policy: pause          # warn | pause | block
  total: 25.00           # $ ceiling across the whole run
  perStage:
    implement: 15.00     # $ cap for one stage
  perWorker:
    thor: 10.00          # $ cap for one worker

A scope breaches only when spend is strictly over its cap. On a breach the policy decides what happens after the running stage records its cost:

policy:	on breach
warn	log the overspend, keep going
pause	freeze at a human gate (the World Security Council) — approve the overspend to continue, or stop
block	halt the run, writing a budget_abort event to the ledger

Enforcement is pure and deterministic — decisions replay from the ledger with no model calls, so block and pause outcomes are reproducible. Leave budget: out and behavior is unchanged.

Check headroom any time:

assemble budget    # per-scope spent vs cap, with remaining headroom
assemble cost      # gains a remaining column when a budget is set

Design docs

Full architecture & decisions: docs/superpowers/specs/2026-07-20-assemble-orchestrator-design.md