@dleangen/cage-coordinator

Agent orchestration system and default agent methodology for CAGE-enabled projects.

Part of the CAGE ecosystem.

In the CAGE ecosystem, content ships with the package whose capability it serves: cage-coordinator provides the default agent roles and skills for the orchestration methodology, while other packages ship the skills specific to their own capabilities. Consumers override any of these defaults through the flavour model (see docs/migration-guide.md), and once the CAGE Chart contribution surface lands, every package will contribute agents and skills through the same mechanism — no single package is the content home.

Installation

npm install @dleangen/cage-coordinator

Prerequisites

The agent definitions' issue-tracking steps (.claude/agents/{coordinator,manager,worker,tester}/agent.md) call the cage-issues MCP server directly — get_issue, update_issue, and related tools. Without cage-issues configured as an MCP server, those steps have no write target. See docs/migration-guide.md for the CLI/MCP relationship and the filesystem-permission enforcement mechanism (topics/ at 555, issue files at 444).

Skills

Skills are behavioral rule sets loaded by agents at session start.

| Skill | Description | |-------|-------------| | autonomous-mode | Coordinator gate auto-advance, CR filing, and Manager lean path rules for mode: autonomous and mode: supervised-lean sessions. | | memory | Rules governing what belongs in agent memory vs. git — methodology improvements must be committed, not stored in memory. | | session-handover | Rules for producing and consuming session handover documents so a fresh agent can resume mid-task work without re-deriving context. | | issue-briefing | How to brief the Business Engineer before executing an issue. Load before presenting any issue for review or execution. | | backlog-presentation | How the agent presents the backlog and issues to the Business Engineer at the start of a session or on request. | | backlog-reporting | How the Manager agent presents the current backlog to the Business Engineer. Apply whenever a full backlog view is requested or appropriate. | | backlog-track-analysis | How to analyse the backlog by track, assess dependency chains, and propose a reordered Up Next queue. Apply when the Business Engineer asks for a backlog review or prioritisation pass. | | retrospective | How to run a pre-merge retrospective on a feature branch — what to capture, which metrics to compute, and how to convert findings into action. | | codex-conduct | How the agent communicates with the Business Engineer. This is the H2A register — everything that crosses the boundary to or from the BE follows these rules. A mandatory Coordinator pre-read. | | presenting-findings | How to surface validator findings, staged diff summaries, and gate outcomes to the Business Engineer. Read at bootstrap — do not defer to "when needed." |

Agent definitions

Agent definitions live in .claude/agents/{role}/agent.md and are loaded by Claude Code when that role is invoked.

| Role | Description | |------|-------------| | coordinator | Orchestrates the full issue lifecycle: pre-flight, Worker dispatch, Tester dispatch, and merge. | | manager | Manages a single issue end-to-end: reads the spec, dispatches Worker and Tester, handles deviations, and closes the issue. | | worker | Executes narrowly-scoped implementation tasks defined in a single issue; stages but does not commit. | | tester | Validates Worker output against the spec through static analysis, test execution, and dynamic spot-checks; produces a binary Pass/Fail verdict. | | thinker | Strategic reasoning partner for ambiguities, direction forks, and design questions; explores without dispatching work. | | test-author | Produces BDD scenarios from the spec independently of the Code Author, before implementation begins. | | test-validator | Receives Code Author and Test Author outputs after completion and surfaces any spec-to-implementation disagreement. | | critic | Reviews staged or committed changes for correctness, completeness, and spec fidelity; does not fix. | | architect | Owns architecture decisions, ADRs, and technical direction; gates structural changes before implementation begins. | | auditor | Performs cross-cutting audits (security, compliance, quality) independently of the active issue. | | project-manager | Owns one Initiative across phases, blockers, and Thinking-session gates; stateless, never dispatches work or writes code. |

Initiative + Project Manager

For work with enough substance to need a plan — multiple phases, real non-code blockers, prerequisite design work — see docs/initiative-and-pm.md for the Initiative Brief schema, the full initiative CLI command surface, and the Project Manager agent's role and boundaries.

Migration

If you maintain a private methodology repo with hand-copied agent definitions, see docs/migration-guide.md for how to migrate to a thin flavour that depends on this package.

Protocol spec

See @dleangen/cage-core for the base protocol spec, build mode taxonomy, issue classification levels, and Change Request format.