coordinator-claude

A PM-native operating layer for AI engineering work. An opinionated Claude Code plugin that turns product intent into scoped plans, delegated implementation, evidence, and ship/no-ship decisions. You're PM. Claude is EM. You stay technical enough to spot when something's wrong; the EM handles the rest.

v4.0.0 is a much larger system than 3.x, not a port of it. The doctrine half grew triggers and guards that run work no earlier version ran at all; the routines that used to be a written checklist the model had to notice and follow now compute their own next step from what is actually on disk. Doctrine that was hundreds of lines of prose is dozens of lines plus Python that enforces rather than suggests. The engine that does the enforcing lives in a separate repo, claude-klabauter, and is a hard dependency — which is also the release's real cost. Read What a doctrine-only install gets you before you rely on an install without it.

Who This Is For

You don't need to write code. You need to know enough to evaluate it — to spot when something smells wrong, to ask the right questions, to set direction. Amjad Masad (Replit's founder) opined that people who don't program may actually be better positioned for the LLM-coding world: they won't micromanage implementation. This plugin leans into that. It gives Claude standing authority to make engineering decisions — how to build, who to delegate to, when to refactor — while you hold product authority: what to build, what to cut, what ships. Just like an EM-PM dynamic.

What this system asks of the PM is altitude, not tactics. Architectural judgment, scope decisions, refactor-vs-patch calls, what-ships-and-what-doesn't. Slop is fought on the plan level — by treating each plan as an exhaustive software design document with named-reviewer pushback baked in, not by spot-checking commits afterward. The natural model defaults — act fast and move on, defer P2s into oblivion, size work in human-sprint timeframes — are the things this system is built to push back against. The PM sets direction; the EM and the named reviewers do the pushing.

This isn't a collection of prompt tricks. It's a decision architecture: routines (session orientation, plan review, multi-source code review, structured handoffs, daily flows) plus authority boundaries (EM owns implementation, PM owns scope/ship) plus reviewer personas that push back with fix-gates between them. Reviews are meaningful — blocking findings, not theatre. And the system actively reads its own accumulated wikis and lessons before drafting new plans (prior-art-checker pre-flight, /learn-lessons triage), so the scar tissue from past decisions informs the next one rather than sitting in a write-only memory file. It maps to how PM-EM collaboration actually feels in a real engineering team. The difference is that your "team" can work autonomously for hours, and you can review the output when you're ready.

What This Is Not

• Not another agent framework. Claude Code already has subagents, plugins, skills, hooks, and MCP. This sits on top of that infrastructure — it doesn't compete with it.
• Not a PRD-to-code pipeline. Product intent is captured inside plan mode and acceptance criteria, not in a separate PRD funnel.
• Not an autonomous coding agent. The PM is in the loop on scope, tradeoffs, and ship decisions by design. Autonomous modes (/mise-en-place, /autonomous) exist for execution sprints, not for product authority.
• Not a developer productivity tool. The target user evaluates engineering work — they don't write it. If you want to be more productive at writing code yourself, you want vanilla Claude Code; this is for managing AI engineering work, not doing it.
• Not a self-contained install any more. As of v4.0.0 the executable half is a separate repo. That is a real cost and we'd rather you learn it here than by hitting the seam.
• Not open source in the OSI sense. Apache-2.0 with a Commons Clause rider — source-available. Use it at work, modify it, redistribute derivative works; you just can't resell the software itself. Same licence on both repos. See LICENSE and COMMERCIAL.md.
• Not aimed at the fully non-technical PM (yet). The current sweet spot is a PM with technical altitude but not technical hands — someone who has architectural judgment, recognizes unwise plan-shape, and can spot when a plan, an architectural choice, or a tradeoff sounds wrong from how the EM describes it, without ever reading a diff. The PM does not review commits, does not perform code review, does not sign off on PRs. That altitude is the load-bearing constraint: code review and PR sign-off are delegated to AI peers and named-persona staff-tier reviewers (see below). Complex codebases require a PM who can tell when something looks wrong from the conversation, not from the patch.

🤖 Agents: start here → AGENTS.md

What v4 Does That 3.x Couldn't

"Who This Is For" above claims this is a decision architecture rather than a bag of prompt tricks, and that slop is fought at the plan level rather than spot-checked afterward. In 3.x that was substantially an aspiration: the architecture was described in prose, and prose only governs if the model notices it and chooses to apply it, every time, in every session. v4 is the release where most of it became mechanical. That is the leap — the bash→Python work and the two-repo split further down are how it was achieved, not what it is.

The doctrine half gained triggers that run work no earlier version ran. 87 hook scripts, all Python, wired into 42 registered hook entries across nine lifecycle events. They are not "more automation" — they do things a checklist cannot. A session routes itself: an unsized ask gets caught before it reaches implementation, and resuming work or starting an autonomous run fires from state rather than from you remembering the command. Dispatch is shaped at the moment of the call: the orchestrator gets pushed off work that belongs in a subagent, pointed at the cheapest model tier that can do the job, and caught when a dispatched agent returns having used no tools at all — a silent-failure mode that previously just looked like success. Role integrity is asserted at runtime, so a subagent that has read the doctrine cannot conclude it is the manager. Foreign-platform path assumptions are refused at the point of writing rather than found on someone else's machine. And the system polices its own doctrine: prose that has drifted into changelog-style narration, instruction files that have grown past their budget, and citations that no longer resolve are all caught by hooks rather than by a reviewer noticing.

Skills compute their own next step instead of being walked by hand. A new generation of skill moved the branching out of prose entirely: a read-only operation reads disk, git, and artifact frontmatter and returns the whole routing as one decision object, collapsing the model's job to the judgment the object could not resolve. /pickup is the first conversion and the pattern the rest of the frontage is being moved onto. Honest scope: this is a live migration, not a finished one, and the older prose decision-tree shape is not deprecated — it remains the correct shape for judgment-dense, low-frequency skills, where there is no mechanical branch inventory to compute.

Hundreds of lines of prose became dozens, plus Python that enforces. This is a quality argument before a size one. An instruction reaches an agent by one of four routes — the config files every session reads on boot, invocation, hook injection, or the prompt itself — and only the last is under a human's control at the moment it matters. The rest are text the model must notice and choose to apply, and every one of them is read on boot whether or not it gets used, so a more robust prose architecture is also a more expensive one to run. Prose is also untestable, and it drifts by copying: the same paragraph in forty agent bodies has already diverged, and fixing the bug means finding all forty. So the governing test became for every rule, what artifact discharges it? — where "the operator remembers" is not an answer. Agent bodies came down roughly 31.5% fleet-wide with a size ratchet underneath them to stop the regrowth; guard and advisory messages have a runtime-enforced length cap; per-command file-write hook processing folded from eight passes to two. The doctrine got shorter and sharper, because what was left after the bookkeeping moved out was almost entirely judgment — which is the thing large models are actually good at reading.

What this costs is on the same page as what it buys. v4 ships a materially smaller safety surface in this repo than 3.x did, and the engine is a second install. Both are set out plainly in What a doctrine-only install gets you and in CHANGELOG.md; neither is a footnote.

Two Repos, One System

This used to be one thing: a plugin full of prompt text. It is now two things, and the second one is not a plugin at all.

• coordinator-claude (this repo) — the doctrine. Skills, agents, commands, hooks, personas, wikis. Text a model reads. This is what an agent experiences.
• claude-klabauter — the engine. A Python package, coordinator_core, that produces and mutates the authoritative on-disk work-state and computes the answers doctrine would otherwise have to ask someone to remember. It owns mechanism, not meaning. It is not a successor to this repo and it does not own doctrine.

The reason for the cut is that an operating system for AI engineering work has to do two unlike things. Judgment — should this be planned or just done? is this reviewer's finding real? — is genuinely a language problem, and belongs in prompt text. Bookkeeping — claim this handoff, stamp that frontmatter, compute which commits in this range have review coverage — has exactly one correct answer, and prompt text is the wrong substrate for it: it is re-derived at full inference cost every session, it cannot be unit-tested, and it drifts by copying into forty agent bodies that have already diverged. So: if an operation has one correct answer, it belongs in code that can be tested; if it requires judgment, it belongs in text a model reads. The engine is where the first kind went.

What that buys, concretely: a bug in a state operation gets fixed once instead of in every copy of a paragraph. State becomes checkable — the engine emits files you can read, diff, and assert against, rather than a claim the model makes about what it did. Multi-OS support becomes a property of one Python codebase instead of something every shell-shaped instruction has to re-earn. And the doctrine got smaller and sharper, which we did not anticipate: once the bookkeeping left, what remained was almost entirely judgment, which is what large models are actually good at reading.

The full argument — including the cost side, and the one rule that governs the seam — is docs/wiki/manifesto.md. It is an argument, not a proof, and it says so.

What a doctrine-only install gets you

Graceful degradation here is a clean line, not a fallback mode that half-works: you lose the state machine, you keep the judgment.

Most of the mutating flows are in the right-hand column. Of the 36 bundled skills, the large majority touch engine-installed surface in some form, so the honest summary is that ceremony-cadence work expects the engine present and judgment work does not.

There is also a safety cost, and it is not cosmetic. v4.0.0 deleted roughly 20 block-* guard hooks from this repo and moved their logic into coordinator_core.write_guards, which ships in the engine. An install running only this repo has none of those guarantees — no destructive-rm guard, no destructive-git guards, no --no-verify block, no subagent write-sandbox confinement, no plan-body or archive write protection. Three block-* hooks remain here, and all three are dispatch/workflow-shape guards, not destructive-action guards. Installing the engine restores the rest. We would rather state this loudly than soften it.

Quick Start

You don't install this — your agent does. Open Claude Code in any project and paste:

Install coordinator-claude. The playbook is at
https://github.com/dbc-oduffy/coordinator-claude/blob/main/docs/agent-install.md
— read it, follow it, then install the engine from
https://github.com/dbc-oduffy/claude-klabauter (its INSTALL.md), and queue
/coordinator:repo-setup as the immediate next step after I restart Claude Code.

The order is load-bearing. This is the single thing most likely to break a new install:

1. Install this plugin. claude plugin marketplace add dbc-oduffy/coordinator-claude, then claude plugin install coordinator@coordinator-claude. The marketplace is the public GitHub repo, not your clone, so the install lives entirely under ~/.claude — delete or move the clone afterward and the plugin keeps working.
2. Restart Claude Code.
3. Run /coordinator:install. This finishes the environment wiring, including depositing the machine-local registry resolver. Until it has run, the resolver is only a forwarder that exits 127 with resolver not installed.
4. Install the engine. Clone claude-klabauter and follow its INSTALL.md — python3 <klabauter-clone>/scripts/setup.py --i-am-agent for an agent, python3 <klabauter-clone>/scripts/setup.py for a human, --check for a no-side-effects check. On Windows: python <klabauter-clone>\scripts\setup.py, same flags.
5. Run /coordinator:setup. The install-chain walker; it verifies the engine actually resolves and emits a chain-complete banner, or fails loud with remediation.
6. Run /coordinator:repo-setup. Bootstraps tracking infrastructure in your project.

Do not substitute pip install . for step 4. It works as an ordinary library-dependency install, but it skips the dependency check and registration the real installer performs, and leaves you with an engine that imports but is not set up.

Do not start at step 4. Installing the engine before this plugin's install has completed produces exit 127 and a remediation instruction that cannot succeed until step 3 is done.

Auditing & uninstall → docs/safety.md — what the install changes, what it does not do, audit commands, and exact uninstall steps.

Why it's built this way → docs/wiki/manifesto.md — why the system is split into a doctrine plugin and a separate engine, what the split buys, and what it costs.

What we actually measured → docs/evidence.md — the experiments behind the design, including the ones that reversed a position we'd already written down, and an explicit line between what was measured and what changed on a single observed failure.

Updating → /coordinator-update checks whether a newer version has been published, computes a classified delta against your live install, and advises a migration path that preserves your customizations by default (renamed reviewer personas, per-project config, any structural divergence) — it never blind-overwrites. It's PM-invoked and advisory only: it computes and recommends, it doesn't apply anything without your explicit say-so.

Prerequisites

Only two things are needed to begin — git and the Claude Code CLI. The rest are resolved as the install walks.

Claude Code version: tested with 2.1.186 via the native claude plugin CLI. A minimum has not been formally established.

Platforms: macOS, Linux, WSL, and Windows are all first-class targets. The tested matrix is macOS and Linux — Windows is supported and actively hardened but not yet in the tested matrix, so treat a Windows-only failure as a bug worth reporting rather than expected behaviour.

Upgrading from an earlier release

If you installed coordinator-claude before, you almost certainly have v2.7.0 (2026-06-01) or earlier — that is the newest release this repo ever published. There was no public v3.x release. Everything between v2.7.0 and v4.0.0 lands on you at once, so read this list rather than assuming a version-number-sized jump.

The one that will actually break your install: the distribution went from five plugins to one. v2 shipped coordinator, web-dev, data-science, deep-research, and notebooklm as separate marketplace entries. They are now folded into a single coordinator plugin at the repo root, and the separate entries are retired. You change what you install, not just your version — install coordinator@coordinator-claude and nothing else.

Then, in rough order of how likely it is to bite:

• The engine is now a separate, required repo. See Two Repos, One System. This is the largest structural change in the product's history.
• Roughly 20 block-* safety hooks were deleted from this repo, with their logic moved to the engine. A doctrine-only install is materially less guarded than v2.7.0 was. Detail above.
• Every executable path was renamed. About 360 files went from .sh to Python, and most of that surface relocated into the engine. Anything of yours that names a .sh path, or a bin/<name> location, is stale. The sh/python polyglot trampolines that briefly preserved old invocations were deleted outright — that carve-out was reconsidered and rejected.
• Handoff records changed vocabulary. status: active | consumed → status: open | claimed; consumed_at/consumed_by → claimed_at/claimed_by; deployment_state: abandoned → continued | closed, where closed carries a closed_reason of cancelled, displaced, or stale. Existing records are migrated, and the archived-handoff schema still reads the legacy values for old archived records. If you built anything that reads handoff frontmatter, it needs updating.
• The lifecycle commands were renamed, and the deprecation aliases are gone. /session-start is now /workstream-start, /session-end is /workstream-complete, /project-onboarding and /bootstrap-repos are /repo-setup (the latter with --batch), and /coordinator:setup no longer scaffolds a repo — that is /coordinator:repo-setup, and /coordinator:setup now unambiguously means the install-chain walker. The full table is in CHANGELOG.md under Upgrading from v2.7.0.
• coordinator:review-code is retired in favour of coordinator:review --surface diff. The /review-code slash command still resolves — it is a redirect shim now, not an independent pipeline.
• coordinator-schema-version went v1 → v2, and the artifact shapes were restandardized across the record family. Anything consuming coordinator record contracts should target the current schemas under schemas/ and cockpit-contract/schema/.
• superseded was retired as a handoff status (before the v4 vocabulary change above), and the code-architect agent was removed — nothing ever dispatched it, so there is no migration.

New in the same span, worth knowing about: the sizing gate (below), first-class weekly goals/OKRs, a durable priority ledger that survives across sessions, automated checks on where a plan's stated justification actually came from, and enforcement — not just documentation — of the rule that text arriving inside tool output is never a command.

Full detail, including the parts we got wrong and corrected in place: CHANGELOG.md.

How a Session Works

Most tools hand you a bag of commands and wish you luck. This system has routines — woven into the session lifecycle so you don't have to remember them. Some fire automatically via lifecycle hooks (boot orientation, the context-pressure nudge); the rest are one-keystroke ceremonies the EM runs at the right moment. The distinction matters: hooks are what actually fire on their own; the slash commands below are invoked — by you, or by the EM on your behalf.

Starting up. When Claude opens a supported project, a SessionStart hook fires automatically — loading the current branch, pending handoffs, lessons from past sessions, project vitals, and an orientation cache. No cold start. Claude lands in the middle of the context window where performance is strongest, with forward-looking state already loaded. This is deliberate: research shows LLMs degrade toward the end of their context and, to a lesser extent, at the beginning (Liu et al. 2023, "Lost in the Middle"). The orientation hook front-loads context so the working session occupies the optimal window. The cache is now fresh by construction — it self-heals at boot rather than depending on a ceremony being invoked.

Sizing, first. Before anything gets planned, shaped, or dispatched, every ask passes through a sizing gate — a cheap t-shirt-size read against disk state that decides where it goes: a tiny fix is a direct edit, a vague or multi-subsystem ask routes to /brainstorming to converge on requirements, a shaped problem with real decision weight routes to /plan, and something needing PM-side scope alignment first routes to /shape. This is the EM's first move on a novel ask, not an optional pre-check — it's how a session begins, not a separate ceremony you invoke.

Planning. You describe what you want. Claude enters plan mode — but the plan isn't just written and executed. You review it. In a real dev team, the PM doesn't just say "build auth" and disappear; they review the spec, push back on scope, ask about edge cases. That's what happens here. The coordinator:plan skill is a decision-tree super-skill (triage → substrate → compose → exit) that mechanically binds the trigger word "plan" to the full pipeline: the prior-art-checker pre-flight cross-references the plan against accumulated wikis, lessons, and improvement queues to surface conflicts before an Opus reviewer touches it; the Staff Engineer then reviews; the integrator applies findings. For bigger decisions, /staff-session spawns role-based engineers who independently develop positions and debate to consensus — like pulling your tech lead and director of engineering into a room.

Building. Claude delegates to Sonnet subagents for implementation — cheaper, faster, fresh context. A PreToolUse hook nudges Claude away from doing implementation work directly, because the orchestrator's context is too valuable to spend on writing code. This is the same principle as a real EM: you don't want your engineering manager writing production code when they should be coordinating.

Reviewing. Code review comes from named personas with rich behavioral profiles — a domain expert reviews first (e.g., a web-dev specialist for front-end work, or a data-science specialist for ML pipelines), all findings are applied, then a generalist reviews the clean artifact. Sequential, with mandatory fix gates. Research supports both the persona mechanism (literature-backed for judgment-routing tasks; for mechanical bug-finding our own controlled experiment found no recall gain — that's why bug-sweeps use bare agents) and multi-agent review gains (Anthropic's own eval showed 90.2% improvement over single-agent). Plan-review with personas — the system's main use of named reviewers — leans on industry-standard PRD/SDD review patterns; we have not separately benchmarked it. Reviewers are identified by stable role name rather than a hardcoded persona name, which fixed a real bug where renaming or removing a reviewer agent silently produced meaningless feedback.

Staying coherent. Long sessions hit a hard constraint: context compaction. When triggered, the model summarizes what it thinks happened — a retrospective reconstruction that loses intent. A PostToolUse hook monitors context pressure and prompts Claude to create a structured handoff before compaction fires: decisions made, state reached, explicit next steps. Each handoff chains forward from its predecessor. Research shows structured handoffs significantly outperform automatic summarization (Kang et al. 2025, ACON; Sourcegraph retired compaction in their Amp agent in favor of explicit handoffs after measuring degradation).

Navigating the codebase. This system invests heavily in documentation-as-navigation. Claude's natural mode is grep-heavy — searching text, reading prose, following paper trails. An architecture atlas, project tracker, orientation caches, and structured comments throughout the codebase give Claude something to find when it searches. We call this "grep bait." It's why the doc maintenance pipeline and architecture atlas exist: not bureaucracy, but navigation infrastructure that lets Claude plan from 60 lines of orientation instead of reading 20 source files cold. Research artifacts, lessons files, and handoff documents all serve double duty — they record decisions and create searchable landmarks for future sessions.

Wrapping up. /workstream-complete captures lessons, updates documentation, and commits state. /workday-complete goes further: syncs docs, merges to main via PR, and optionally hibernates the machine. The cycle is continuous — each session starts where the last one left off.

A tier above the workstream loop. Everything above operates at the level of one ask, one plan, one merge. Goals/OKRs sit a level up: a per-repo goal artifact (state/goals/<slug>.yaml) records the strategic objective an initiative serves and tracks whether the fleet is winning against it — not "did this ship" but "did it move the number." Weekly priorities are first-class goal artifacts of their own, wired into session orientation. /roadmap-planning shapes raw research or intent into a ratified, graphed roadmap of batons that later plans and workstreams draw from, so a session doesn't have to re-derive "why are we doing this" from memory. This altitude is PM-gated by design — direction lives with the PM, not something the EM infers from ticket volume.

What You Need to Remember

The EM handles most of this on its own. Your key moves:

That's it for daily use. Everything else — delegation, review routing, doc maintenance — the EM drives as part of its workflow; context-pressure management is the one piece handled automatically, by a PostToolUse hook. You don't have to ask for any of it.

Flows

Don't memorize commands; learn five flows. Most of what the system does, you'll touch through one of these.

Flow 1 — Build a feature. You describe intent → Claude enters plan mode and proposes acceptance criteria + scope mode → you review and approve → Claude delegates implementation → reviewers (domain expert first, generalist second) check the artifact with fix gates between → for user-visible work or patches that smell like they should be refactors, the VP-Product Reviewer (coordinator:vp-product) — scope challenger, naming optional via /coordinator:install Phase 6 — stress-tests the choice → /merging-to-main produces a ship verdict and you decide.

Flow 2 — Fix a bug. Reproduction first (don't trust the report) → root cause via the systematic-debugging guide → scoped fix in production-patch mode (minimal diff, no opportunistic refactors) → regression check → reviewer → merge. For codebase-wide grinds, /bug-blitz autonomously works through the bug backlog with EM-serial commits at each wave gate.

Flow 3 — Resume work. The boot SessionStart hook automatically loads orientation, lessons, and pending handoffs into context → optionally run /workstream-start for a deeper triage → you pick up via /pickup <handoff> or pick from the menu → Claude lands mid-context and starts where the last session stopped.

Flow 4 — Autonomous sprint. /mise-en-place gathers ready work, builds a compaction-proof flight recorder, and executes through the backlog without stopping. /autonomous suppresses handoff nudges when you want it to push through context pressure.

Flow 5 — Architecture change. /staff-session plan (multi-perspective debate) → migration plan with rollback → architecture mode review → implementation → verification → architecture atlas update via /update-docs.

Closing the day: /workday-complete validates, syncs, runs the daily review, and merges. /workweek-complete is the larger weekly ceremony with version bump and release notes — and it's the only place /parallel-code-review runs. That command is the pre-merge gate: it chunks the week's diff across parallel reviewer dispatches instead of one reviewer reading everything serially, then folds their findings into a single ship/no-ship verdict. It's deliberately not available outside /workweek-complete — a weekly gate invoked ad-hoc stops being a gate.

How heavy is the workflow?

The system scales — a typo fix is a two-word instruction; a system rewrite is a multi-agent pipeline. Here are three representative tiers:

The plugin ships 46 commands. Listed below are the 45 that are useful in a consumer install, grouped by where they sit in a session. The 46th, /percolate, publishes a working tree to a downstream mirror repo — it is a maintainer tool for shipping this project and has no use in an install that is the target of a publish rather than its source.

Session cadence

Intake — sizing, shaping, planning

Execution

Review and merge

Backlog and health

Install and lifecycle

Two more verbs ship as skills rather than commands, so they aren't in commands/ and don't appear in the count: /coordinator:setup (the install-chain walker — see Quick Start step 5) and /coordinator-update (see Updating above).

The one role we don't have deeply embedded in workflows: designer. Meatspace designers are still better at that, and their judgment is going to remain difficult for LLMs to replicate. There's a vibe-design functionality, but it's not gonna rock your world.

Inverted capability delegation. The coordinator sees ~8 thin MCP tools; domain agents access 40+ via proxy with full schemas. This saves ~40K tokens from the coordinator's context and forces delegation by design. A PreToolUse hook nudges the coordinator when it reaches for domain tools directly.

Proactive artifact generation. Before compaction fires,