loop-orchestrator

English | 한국어

Throw it one natural-language goal, and the orchestrator splits the work into multiple independent tmux Claude Code sessions working in parallel; each session drives its task to completion through a verification loop grounded in real development methodologies; after an integration test, the merge goes through your review. A Claude Code plugin.

It runs autonomously, with human gates at exactly the two points where accidents live: task decomposition and merging.

Quick start

1. Prerequisites

• macOS or Linux (depends on tmux)
• Claude Code installed and logged in
• git, tmux, jq — if missing, the plugin tells you how to install them (it never auto-installs)

2. Install

/plugin marketplace add choiyounggi/loop-orchestrator
/plugin install loop-orchestrator@loop-orchestrator

Installed as a Claude Code plugin, from the git repo (not npm).

3. Use

Ask in a Claude Code conversation, in natural language:

"Implement this goal with the orchestrator: <what to build>"

The orchestrator fills in what it needs by asking questions, then splits the work and runs it in parallel.

How it works

natural-language goal
  → [clarify]        pin down goal/scope/constraints/done-criteria via questions
  → [detect env]     git repo → feature branch + per-task worktrees / none → git init (after preflight)
  → [decompose]      N independent tasks + conflict/dependency analysis → Waves
  → 🚦 decomposition approval  "I split it into N tasks. Proceed?"   ← you confirm
  → [launch]         a claude session per worktree → each implements via the verification loop
  → [review/rework]  the orchestrator reviews each result (up to 3 rework rounds)
  → [integration]    verify end-to-end behavior at the integration point
  → 🚦 merge review   the full integration diff is presented           ← you confirm
  → [cleanup/merge]  sub-branches → feature branch, then worktrees/sessions are cleaned up

You are involved at exactly four points: clarifying questions, follow-ups on ambiguity, decomposition approval, and merge review. Everything else is autonomous.

The verification loop (loop-implement)

The closed loop each session runs for one task. The steps are not arbitrary — each is grounded in a recognized methodology:

0. define done (DoD / acceptance criteria)   1. analyze   2. plan/design
3. write tests (Red, test-first)             4. implement (Green)   5. run tests
6. self-review + refactor
6.5 independent audit (test-quality-auditor — no one grades their own tests)
7. judge against done → pass: done / fail: reflect and retry (max 3)

Grounding: TDD Red-Green-Refactor / test-first (Kent Beck), PDCA (Shewhart/Deming), code review (Google eng-practices), Definition of Done (Scrum) / acceptance criteria (XP), self-verification (Self-Refine, Reflexion, Anthropic Building Effective Agents), bounded retry.

Safety rails

• Two gates: decomposition approval + pre-merge integration-diff review (forced stops in an autonomous flow)
• Destructive-work guard (safe-cleanup.sh): refuses to remove worktrees with uncommitted changes (never uses --force), kills tmux sessions by exact name only (no prefix/grep matching), aborts and reports on conflict
• git init preflight: refuses when nested inside a parent repo or when secret files (.env/*.pem/*credential*) are detected
• Anti-gaming: the session that wrote the code never grades its own test quality — a separate read-only agent judges it

Tool profile (plug in your own tools)

By default the plugin depends on no specific tools (nothing external beyond the bundled test-quality-auditor — no MCPs, skills, or agents). You plug your environment's tools into a few capability roles and the verification loop uses them; leave them unset and it runs with generic defaults — it works with zero config.

Role	Purpose	Unset (default)
intake	Work source — issue tracker (parent issue → children = tasks)	the orchestrator decomposes the natural-language goal itself
knowledge	Domain facts, policy, code values (step 1)	generic analysis (no forced lookups)
tacit	Past incidents, edge cases, danger zones (steps 1·6)	skip
plan	Planning for non-trivial tasks (step 2)	loop-implement's built-in step 2
verify	The test/build/QA command (step 5)	generic test run
explore	Code/symbol search, read-only (step 1)	Grep/Read

A role is a tool, not a loop. It must be a tool/information source injected into one step — never plug in a tool that runs its own implement/verify/retry loop, or another orchestrator — loop-implement is the implementation loop, and nesting one muddies who owns retries, the done verdict, and the auditor gate. plan only produces and returns a plan, so it is safe; an implement role deliberately does not exist (implementation is solely owned by step 4).

Issue-tracker intake (intake): plug your tracker into intake and hand over a parent issue key/URL — the orchestrator reads the issue and its children and decomposes children into tasks (the parent = overall goal / architecture). Without intake, or with a natural-language goal, it decomposes by itself — no tracker required. Jira / GitHub / Linear all fit the same slot.

Partial resume (one child already done): if some children are already done, they are excluded and the rest proceeds. A child counts as done when you name its key or the tracker status is Done (when intake exposes status). A done child gets no task/session, but its output (exposed signatures) enters the dependency graph as base output, so downstream tasks that depend on it receive the signatures (plain exclusion is forbidden — the downstream would lose its premises). setup-worktrees.sh is idempotent, so already-created branches/worktrees are detected and kept.

Copy-paste prompt for naming a done child (use real signatures):

Implement this parent issue with the orchestrator: RNR-1000
But child RNR-1003 is already done. Don't create a task/session for it — exclude it.
What RNR-1003 exposed (the contract downstream tasks assume):
  - getBuildingArea(pnu: string): Promise<number>   (apps/api/src/building/area.ts)
  - type BuildingArea { pnu: string; grossM2: number }
It's already merged into the integration branch → put these signatures into the
<dependencies> of the dependent children's briefs, and decompose the remaining
children into Waves from there.

If writing signatures out is a hassle, you can shorten it to "RNR-1003 is done and on the integration branch — read its output as the premise and start from the rest" (the orchestrator extracts the signatures from the integration branch; naming them explicitly is more reliable).

Wave predecessor-signature injection: when dependencies split the work into Waves, the orchestrator fills the downstream briefs with the exact signatures (functions, types, components) the previous Wave exposed before launching the next one. Downstream sessions plan against that contract, which cuts drift (no textual approximations).

Config files merge layered, like git config (low → high priority):

built-in defaults  <  ~/.claude/loop-orchestrator/tools.json  <  <repo>/.loop-orchestrator/tools.json

• per-user (~/.claude/...) — your machine's tools, for every project
• per-repo (<repo>/.loop-orchestrator/tools.json) — commit it to share a team mapping; overrides per-user
• Merging is per-role, per-field — a repo file can override one role (or one field) and inherit the rest

Example (examples/tools.example.json — wiki-rag / rtb-lore / rtb:plan):

{
  "knowledge": { "kind": "mcp",   "ref": "wiki-rag", "how": "wiki_search -> wiki_get_document", "when": "domain terms, policy, code values" },
  "tacit":     { "kind": "mcp",   "ref": "rtb-lore", "how": "lore_query, lore_list_danger_zones", "when": "edge cases, past incidents, danger zones" },
  "plan":      { "kind": "skill", "ref": "rtb:plan", "when": "non-trivial multi-file planning" }
}

Schema, precedence, and resolution details: references/tool-profile.md. Roles are optional and extensible; each skill only uses the roles it knows.

Components

Kind	Name	Role
Skill	orchestrate	Decompose, distribute, review, integrate, merge (the orchestrator)
Skill	loop-implement	Single-task verification loop (per session; usable standalone)
Agent	test-quality-auditor	Independent test-quality audit (read-only)
Script	scripts/resolve-tools.sh	Layered tool-profile resolution (role → tool/default)
Hook	preflight (SessionStart)	Detect git/tmux/jq + guidance
Hook	loop-gate (Stop)	Blocks ending a session with an unfinished verification loop

Known limits

• macOS / Linux only — depends on tmux and a POSIX shell (no Windows)
• No automated remote push / PR / merge — it stops at the local feature-branch merge; the rest is yours
• Sessions run with bypassPermissions. The receiving environment may have no destructive-command guard of its own — use it only on work you trust.

Release automation (maintainer)

1. Bump version in .claude-plugin/plugin.json.
2. git tag vX.Y.Z && git push origin vX.Y.Z
3. GitHub Actions (release.yml) verifies the tag matches the version and auto-creates the GitHub Release + release notes. (No npm publishing.)

License

MIT