Agent Orchestra

⚠️ GitHub Copilot / VS Code support is frozen and retiring after 2026-08-31. Claude Code is the actively supported path. See COPILOT-DEPRECATION.md for details and the reach-out channel if you depend on Copilot support.

A multi-agent workflow system that orchestrates AI-assisted software development through specialized Claude Code agents. (GitHub Copilot/VS Code: frozen and retiring after 2026-08-31 — see COPILOT-DEPRECATION.md)

Renamed from copilot-orchestra in v2.0.0. See the migration section below for the one-time steps to switch over.

Install as Plugin (VS Code 1.110+)

⚠️ Copilot / VS Code support is frozen and retiring after 2026-08-31. Claude Code is the actively supported path — see Install as Plugin (Claude Code) below. If you depend on the Copilot/VS Code surface, start a GitHub Discussion before the deadline. See COPILOT-DEPRECATION.md for details. Experimental: Agent plugins are available in VS Code 1.110 as an experimental feature. Plugin distribution is the fastest way to get started with no cloning required.

Quick Setup (Plugin)

1. Enable plugins — Add to VS Code user settings (Ctrl+Shift+P → "Open User Settings (JSON)"):

   {
     "chat.plugins.enabled": true,
     "chat.plugins.marketplaces": ["Grimblaz/agent-orchestra"]
   }
   

2. Install — In the Extensions view (Ctrl+Shift+X), search @agentPlugins agent-orchestra and install.

3. Use — The 17-agent payload and shared skill library are immediately available in VS Code Chat.

What's included in the repo plugin payload: 17 agents, the shared skill library, and 18 command files under commands/ (/code-conductor, /design, /experience, /goal-run, /orchestrate, /spine-run, /orchestra:spine, /plan, /polish, /raw, /review-github, /setup-references, /audit-docs, /orchestra:review, /orchestra:review-lite, /orchestra:review-prosecute, /orchestra:review-defend, /orchestra:review-judge). VS Code currently ignores the plugin commands field; Claude Code and CLI consumers use it.

What requires clone/fork: Instruction files (.github/instructions/) and project templates are not distributed via the plugin — they are auto-discovered by VS Code when you clone or fork the repo. Plugin-distributed hooks are also not active when you only point VS Code at a clone via chat.agentFilesLocations; deterministic SessionStart cleanup and Claude PostToolUse release-hygiene prompts require an actual plugin install.

New here? → How Agent Orchestra works

Install as Plugin (Claude Code)

Claude Code loads agents and skills from .claude-plugin/plugin.json. Install via the built-in marketplace commands:

/plugin marketplace add Grimblaz/agent-orchestra
/plugin install agent-orchestra@agent-orchestra

All 17 agents and the shared skill library are immediately available. The marketplace command registers the source; the install command pulls the plugin into Claude Code's cache. See Documents/Decisions/0002-claude-code-plugin-schema.md for the schema rationale (agents uses an explicit registration whitelist; skills auto-discovers).

Path resolution for downstream consumers

This is zero-config for consumer repositories: after marketplace registration and plugin install, Claude Code loads the shared agent bodies and skills from its plugin cache. The repository using the plugin does not need a local agents/ directory.

See Documents/Design/hub-artifact-paths-audit.md for the full hub artifact path catalog.

For what's included in the plugin payload vs. what requires clone/fork, see the Install as Plugin (Claude Code) section above.

Related: see the Releases section in CLAUDE.md for cache invalidation behavior and the audit doc's How to Detect Staleness section for drift detection.

See also: CUSTOMIZATION.md > Script portability for plugin users.

The plugin payload includes all 17 shared agent definitions and the shared skill library. The Claude-specific command and specialist surface is outlined below.

Upstream Agents In Claude Code

The three upstream agents are first-class Claude Code citizens:

• /experience — invoke Experience-Owner for customer framing or CE Gate evidence capture
• /design — invoke Solution-Designer for technical design exploration with the 3-pass non-blocking challenge
• /plan — invoke Issue-Planner for implementation planning with the full adversarial review pipeline

Each agent reads its shared, tool-agnostic body from agents/*.agent.md and follows the named skills. Claude-native tool bindings (AskUserQuestion, Agent, gh CLI via Bash) are mapped from the shared body inside each shell at agents/{name}.md (lowercase filename for Claude; capitalized *.agent.md for Copilot). Plan persistence uses the GitHub comment marker <!-- plan-issue-{ID} --> (there is no session-memory equivalent in Claude Code — the marker is the durable record, compatible with Copilot's latest-comment-wins contract). The row-level survival and fallback rules live in skills/session-memory-contract/SKILL.md.

See CLAUDE.md for the Claude Code user guide and issue #369 for the design history.

Review Pipeline In Claude Code

The Claude review surface now ships in the orchestra-review-* command namespace:

• /review-github — deterministic GitHub review intake and proxy prosecution entry point
• /orchestra:review — canonical entry for the full prosecution → defense → judge pipeline
• /orchestra:review-lite — small-change variant with a single compact prosecution pass before defense and judge
• /orchestra:review-prosecute, /orchestra:review-defend, /orchestra:review-judge — power-user and partial-rerun entry points for individual stages

Code-Conductor Orchestration In Claude Code

• /orchestrate — Claude entry point for the full pipeline from durable issue state through implementation, validation, CE Gate, and PR readiness via Code-Conductor
• /spine-run — minimal frame-walking conductor for an issue with a persisted v2 frame-spine plan
• /code-conductor — explicit non-hub-mode free-text Code-Conductor entry point

For paused Claude orchestration work, /orchestrate is also the resume entry point. The shared workflow's /implement wording is Copilot-specific; Claude does not ship a /implement command.

Claude's code-conductor shell ships as a thin shell over the shared agents/Code-Conductor.agent.md body plus the extracted composite skills, keeping Copilot and Claude behavior aligned without duplicating the orchestration contract.

The durable handoff set for Claude orchestration is the same GitHub-marker contract used cross-tool: <!-- experience-owner-complete-{ID} -->, <!-- design-phase-complete-{ID} -->, <!-- design-issue-{ID} -->, and <!-- plan-issue-{ID} --> as applicable to the current resume tier. See Documents/Design/session-memory-contract.md for the design rationale behind that no-new-mechanism choice.

Specialist agents

Claude Code includes the implementation specialists for Code-Conductor dispatch. Code-Conductor can dispatch every currently shipped specialist shell:

• Code-Smith — implementation-focused code changes against an approved plan
• Test-Writer — test authoring and test-surface correction
• Refactor-Specialist — structure and maintainability cleanup without changing intended behavior
• Doc-Keeper — documentation finalization and stale-doc cleanup
• Process-Review — retrospective and execution-quality analysis during the orchestration workflow
• UI-Iterator — screenshot-driven UI polish and visual refinement
• Research-Agent — evidence-driven technical research and recommendation building
• Specification — formal specification drafting and refinement
• Senior-Engineer — general implementation executor for planner-designated skill adapters

/polish is the direct slash-command entry point for UI-Iterator work.

What requires clone/fork: same as the VS Code plugin — .github/instructions/ and project templates are not distributed through the plugin surface. If you only load agents from a clone, Claude will not pick up the plugin-distributed SessionStart or PostToolUse hooks; those automation paths require /plugin install.

Releases

Claude Code caches plugins by the version in .claude-plugin/plugin.json. If an entry-point file changes without a version bump, cached installs keep serving the previous snapshot even though the repo content changed.

Agent-assisted maintainer flows now route entry-point edits through the shared plugin-release-hygiene skill. Claude uses a committed PostToolUse hook, Copilot uses an auto-attached instruction file, and both mechanisms converge on one conversation-scoped version-bump decision.

PRs touching plugin entry points are also enforced by a required GitHub Actions check (release-gate.yml). The check fails if the PR lacks a monotonic version bump and a matching ## [version] CHANGELOG section. To waive only the CHANGELOG leg, add Skip-Release-Check: changelog-only as a head-commit trailer. To waive the full gate, use Skip-Release-Check: all <reason>.

Claude sessions also run an active-assist startup drift check. When the installed agent-orchestra@agent-orchestra version is behind the resolved marketplace version, startup runs claude plugin update, reports the old and new versions, and asks whether to restart now or continue under the old code until the next session.

For maintainers

claude plugin list
claude plugin marketplace list
claude plugin marketplace update
claude plugin marketplace add <source>
claude plugin marketplace remove <name>
claude plugin update <plugin@marketplace>
claude plugin install <plugin@marketplace>
claude plugin uninstall <plugin@marketplace>

Quick Start — Two Steps

Step 1: Clone or fork this template

git clone https://github.com/YOUR-ORG/YOUR-REPO.git
cd YOUR-REPO

Or click "Use this template" → "Create a new repository" on GitHub.

Note: Creating from the template is optional. /setup works in any repo via shared prompts (chat.promptFilesLocations). If your workspace is brand-new and empty, don't worry — Phase 0 will automatically create a README.md placeholder for you. (VS Code's workspace context provider crashes on zero-file workspaces; Phase 0 handles this.)

Step 2: Run the setup wizard

Type /setup in GitHub Copilot Chat. It runs in six phases with skip gates:

Recommended model: Claude Opus — the setup wizard benefits from deep reasoning for architecture and tech stack decisions. (o3 or GPT-4o also work well if Opus is unavailable.)

• Phase 0 — Auto-detects prerequisites (VS Code version, pwsh, git, gh CLI)
• Phase 1 — One-time user setup: adds agents and skills to your VS Code settings, and wires repo-local instruction files only when your clone or generated consumer setup actually uses them. Skip if already configured.
• Phase 2 — Collects project basics (name, language, framework, database). Skip if copilot-instructions.md already exists.
• Phase 3 — Collects architecture and conventions. Skip if architecture-rules.md already exists.
• Phase 4 — Collects build, run, test, lint, and quick-validate commands. Skip offered if Phases 2, 3, and 5 are all skipped.
• Phase 5 — Generates project scaffolding (.gitignore additions, .vscode/ defaults, Documents/ structure). Opt-in.

Prefer to do it manually? Create .github/copilot-instructions.md and .github/architecture-rules.md yourself. See examples/ for complete filled-in references. For user-level setup, follow CUSTOMIZATION.md.

That's it. You're ready to use agents.

Using the Agents

I want to

Core Workflow

@Experience-Owner → @Solution-Designer → @Issue-Planner → @Code-Conductor → PR

Default posture for standalone work (#957): the expected route is the open-for-work entrance — one conversation from the filed issue to a lawful brief or a continuation into design (Documents/Design/open-for-work.md) — with the pipeline above reached by explicitly requesting it (/experience or /design). The /open command ships with #957 chunk 3; until then the conversation runs manually per that document. The pipeline remains fully lawful on explicit request.

1. @Experience-Owner — frames the customer problem, defines user journeys and CE Gate scenarios (optional upstream step)
2. @Solution-Designer — picks up the issue, explores the design space, updates the issue body with a design
3. @Issue-Planner — creates a step-by-step implementation plan
4. @Code-Conductor — reads the plan, delegates to internal specialist agents, creates a merge-ready PR

Example: Start a feature from scratch

@Experience-Owner Please frame issue #42 from the customer's perspective.

Then, once the design is in the issue:

@Code-Conductor Issue #42 is designed and planned. Please implement it.

Agent Reference

Agents and runners you invoke directly (9)

Internal agents and runners (8)

These agents are hidden from the picker (user-invocable: false) and are used automatically during orchestration workflows:

Code-Smith, Test-Writer, Refactor-Specialist, Doc-Keeper, Research-Agent, Process-Review, Specification, Senior-Engineer

See agents/ (repo root) for full definitions of all 17 agents.

Skills Framework

Skills are domain-specific knowledge packages in skills/ (repo root) that agents load on demand:

VS Code 1.108+: Skills are auto-discovered from skills/ (repo root) when chat.useAgentSkills is enabled.

Configuration Files

Examples

Three complete filled-in examples showing what your config files should look like:

Global Setup (Optional): Use Agents Across All Repositories

You can make all agents available globally in VS Code — not just in repos that have cloned this template — by adding this setting to your VS Code user settings (Ctrl+, → open settings.json):

{
  "chat.agentFilesLocations": [
    "/path/to/your/agent-orchestra/agents"
  ]
}

Replace /path/to/your/agent-orchestra with the absolute path to where you cloned this repo. VS Code will load agent definitions from that folder for all workspaces.

This path-based setup only loads agent definitions. It does not load the plugin manifests or their hooks.json files, so automatic session-start cleanup and plugin release-hygiene prompts remain plugin-only behavior.

Upgrading from v1.13 or earlier? Agents lived at .github/agents/ before v1.14. If your settings.json still points at /path/to/your/agent-orchestra/.github/agents, update it to /path/to/your/agent-orchestra/agents. See CUSTOMIZATION.md — Migrating from pre-1.14 layouts.

Warning: VS Code loads agents additively from all configured sources — there is no name-based deduplication. If you add a global path and also have the plugin installed, or if a project workspace also has agents/ at the repo root, you will see duplicate agents in the chat picker. Choose one source: either set a global path (above) or install the plugin, not both. If you're seeing duplicates, see CUSTOMIZATION.md — Troubleshooting.

Customization

See CUSTOMIZATION.md for:

• How to generate or create your project config files
• Adding domain-specific skills
• Tweaking agent behaviors
• Organization-level agent setup

See CONTRIBUTING.md for recommended VS Code settings.

Repository Structure

agents/                  # Shared agent bodies + Claude shells (repo root)
skills/                  # Skill definitions (repo root)

.github/
├── copilot-instructions.md  # Your project context (generate via /setup)
├── architecture-rules.md    # Your architecture rules (generate via /setup)
├── instructions/        # Output format and PR review guidelines
├── prompts/             # Slash command prompt files
├── scripts/             # Post-merge cleanup and session detector
└── templates/           # Implementation plan template

plugin.json              # VS Code/Copilot plugin manifest at repo root (paths ./agents/ + ./skills/)

.claude-plugin/
├── plugin.json          # Claude Code plugin manifest (explicit agents whitelist + auto-discovered skills/)
└── marketplace.json     # Claude Code marketplace catalog (enables /plugin marketplace add Grimblaz/agent-orchestra)

examples/
├── spring-boot-microservice/   # Java / Spring Boot example
├── nodejs-typescript/          # TypeScript / Express example
└── python/                     # Python / FastAPI example

Documents/
├── Design/              # Design documents (created by agents)
├── Decisions/           # Architecture Decision Records
└── Development/         # Testing strategy and development guides

Migrating from copilot-orchestra

v2.0.0 renames the repo from copilot-orchestra to agent-orchestra and removes the previously-required COPILOT_ORCHESTRA_ROOT / WORKFLOW_TEMPLATE_ROOT environment variables. The session-startup script now self-resolves its repo root via $PSScriptRoot.

1. Remove the obsolete environment variables (optional cleanup)

The detector script ignores these vars now — you can leave them set or unset without effect. To clean up:

Windows (permanent):

[System.Environment]::SetEnvironmentVariable('COPILOT_ORCHESTRA_ROOT', $null, 'User')
[System.Environment]::SetEnvironmentVariable('WORKFLOW_TEMPLATE_ROOT', $null, 'User')

macOS/Linux (also remove any matching export lines from your shell profile):

unset COPILOT_ORCHESTRA_ROOT
unset WORKFLOW_TEMPLATE_ROOT

2. Update your VS Code plugin settings

1. Uninstall the old plugin: In the Extensions view (Ctrl+Shift+X), search @agentPlugins copilot-orchestra and uninstall it.
2. Update settings: Change the chat.plugins.marketplaces entry in your VS Code user settings.json to ["Grimblaz/agent-orchestra"].
3. Install the new plugin: Search @agentPlugins agent-orchestra in the Extensions view and install it.

3. Update Claude Code plugin (if installed)

Reinstall the plugin from the new marketplace path:

/plugin marketplace add Grimblaz/agent-orchestra
/plugin install agent-orchestra@agent-orchestra

4. Git remote (no action needed)

GitHub automatically redirects github.com/Grimblaz/copilot-orchestra to the new URL. Existing clones and remotes continue to work without any changes — though running git remote set-url with the new name avoids the redirect hop.

5. Rename copilot-orchestra-repo in .github/copilot-instructions.md

If your downstream repo has a copilot-orchestra-repo: field in .github/copilot-instructions.md (used by the Process-Review upstream-gotcha flow), rename it to agent-orchestra-repo:. Process-Review reads both names during the transition — the legacy key continues to work — but new injections (via /setup) use the new name, and a future release will drop the legacy fallback. One-line change:

# Before
copilot-orchestra-repo: Grimblaz/copilot-orchestra

# After
agent-orchestra-repo: Grimblaz/agent-orchestra

Contributing

See CONTRIBUTING.md. Ways to help:

• Report issues with agent definitions
• Share prompt or workflow improvements
• Add new skill definitions
• Improve the examples

License

Available under the terms in the LICENSE file.