orchestrator-agent-kit

A 4-agent coding pipeline — Architect → Developer → Tester → Reviewer — driven by an Orchestrator, that coordinates entirely through plain files in .agent-memory/. No vendor lock-in: install it into opencode, Claude Code, or GitHub Copilot Chat (VS Code) with a single command.

npx orchestrator-agent-kit install --target all

Why

AI coding tools are good at single-shot edits but weak at disciplined, multi-step feature work: planning gets skipped, tests mirror the implementation, and reviews rubber-stamp whatever was written.

This kit fixes that by imposing a pipeline with hard gates and separation of concerns:

• The planner never codes, the coder never tests, the tester never fixes, and the reviewer approves nothing silently.
• A mandatory plan-approval gate stops the pipeline until you sign off.
• All coordination happens through plain markdown/JSON files on disk — no proprietary APIs, no server, no lock-in. Any tool that reads/writes files can participate.

How it works

            ┌─────────────────────────────────────────────┐
            │                 ORCHESTRATOR                │
            │  (coordinates, manages state, enforces gate)│
            └──────┬──────────┬──────────┬──────────┬─────┘
                   ▼          ▼          ▼          ▼
              ┌────────┐ ┌─────────┐ ┌────────┐ ┌──────────┐
              │ARCHITECT│→│DEVELOPER│→│ TESTER │→│ REVIEWER │─┐
              └────────┘ └─────────┘ └────────┘ └──────────┘ │
                   ▲                                         │ changes-requested
                   └────────────── loop (max 3 iters) ───────┘

1. Orchestrator takes your feature request, writes it to .agent-memory/plan.md, initializes state.json, and delegates to the Architect.
2. Architect turns the requirement into a concrete plan — scope (in/out), design grounded in your actual codebase (path:line references), task breakdown, risks, acceptance criteria.
3. Hard gate — the orchestrator stops and shows you the plan. Nothing gets built until you explicitly approve.
4. Once approved: Developer implements surgically, Tester writes real behavior-driven (non-mirror) tests and runs them, Reviewer inspects the actual diff and returns a verdict (approved / changes-requested).
5. On changes-requested, the orchestrator loops back to the developer with the review findings — up to 3 iterations — then surfaces outstanding blockers to you for a decision.

Every handoff happens via files in .agent-memory/:

| File | Written by | Read by | Purpose | |------|------------|---------|---------| | state.json | Orchestrator | all | Machine-readable handoff pointer (phase, iteration, verdict) | | plan.md | Architect | Dev, Tester, Reviewer | Requirement, scope, design, tasks, acceptance criteria | | progress.md | Developer | Tester, Reviewer | What changed, decisions, deviations, open questions | | tests.md | Tester | Reviewer, Developer | Test strategy, cases, coverage rationale, how to run | | review.md | Reviewer | Orchestrator, Developer | Findings table + verdict |

Only the owner overwrites their own file; others may append clarifications under a > NOTE (<agent>): line. This "shared memory" protocol is what makes the pipeline work identically across every supported tool.

Install

Requires Node.js ≥ 16.

# everywhere at once (project-scoped)
npx orchestrator-agent-kit install --target all

# just one tool
npx orchestrator-agent-kit install --target opencode
npx orchestrator-agent-kit install --target claude
npx orchestrator-agent-kit install --target copilot

# opencode / Claude Code agents globally (available in every project)
npx orchestrator-agent-kit install --target opencode --scope global
npx orchestrator-agent-kit install --target claude --scope global

Where files land

| Target | Project scope | Global scope | |----------|--------------------------------------|-------------------------------------| | opencode | ./.opencode/agent/*.md | ~/.config/opencode/agent/*.md | | claude | ./.claude/agents/*.md | ~/.claude/agents/*.md | | copilot | ./.github/chatmodes/*.chatmode.md | not available (VS Code requirement) |

Each installed file = tool-specific frontmatter (name/description/mode/ permissions) + a shared agent body + a pointer to the shared memory protocol.

Using it

opencode & Claude Code

Both support agent-to-agent delegation, so the full loop runs automatically. Just address the orchestrator:

@orchestrator add rate limiting to the /login endpoint

It plans → pauses for your approval → develops → tests → reviews → (loops if needed) → done, narrating each phase transition along the way.

GitHub Copilot Chat

Copilot chat modes are personas you switch between manually; Copilot has no built-in agent-to-agent delegation. Drive the loop yourself:

1. Switch to the orchestrator mode and state your request — it sets up .agent-memory/ and gives you instructions.
2. Switch through architect → developer → tester → reviewer modes in order.
3. Approve the plan when the orchestrator-mode output asks you to.
4. Carry the .agent-memory/ files between steps (they live in your repo, so they're just there).

The agents

| Agent | Role | Writes | Never does | |-------|------|--------|------------| | Orchestrator | Coordinates phases, owns state.json, enforces the plan gate, caps iterations at 3 | state.json, scaffolding | Feature code, plan body, reviews | | Architect | Scopes and designs; grounds the plan in real code | plan.md | Code, tests | | Developer | Implements surgically per plan; logs decisions/deviations | source code, progress.md | Tests, unrelated refactors | | Tester | Derives tests from acceptance criteria & business use cases; runs them | tests, tests.md | Fixes source bugs (reports instead) | | Reviewer | Reviews the real diff for bugs, null-safety, edge cases, standards; issues verdict | review.md | Edits code or tests |

Customizing

• Edit the installed agent files directly — they're plain markdown with tool-specific frontmatter. Change models, permissions, tone, or add rules.
• Project-specific commands: add a "Project-specific build & test commands" section to your installed agent-memory-protocol.md (e.g. "use npm run build, never raw tsc"). Every agent reads this section before running build/test commands.
• Max iterations: the default loop cap is 3 review rounds before blockers escalate to you. Edit the orchestrator file to change it.

FAQ

Does this need an API key or server? No. It's just markdown agent definitions plus a file-based coordination protocol. Your existing AI tool runs the agents.

Can my team share the installed agents? Yes — project-scoped installs write into .opencode/, .claude/, or .github/ inside your repo, so committing them shares the setup with the whole team. Add .agent-memory/ to .gitignore if you don't want working state committed.

Does it work with other tools? Any tool that supports custom agent/persona files can use the shared bodies in templates/shared/bodies/ as-is — they're framework-agnostic markdown.

Where does the state go after a feature is done? .agent-memory/ stays on disk. Delete it, archive it, or commit it as a record of what was built and why.

Repository layout

bin/cli.js                          # installer CLI
templates/
  shared/
    agent-memory-protocol.md       # the file schema every agent reads
    bodies/                         # framework-agnostic agent bodies
      orchestrator.md
      architect.md
      developer.md
      tester.md
      reviewer.md

Contributing

Issues and PRs welcome. The agent bodies are intentionally short and strict — if you improve a prompt, keep it terse: long personas dilute model attention.

License

MIT