Agent coordinator (Claude as the brain)
Split the work by strength and cost:
- Claude = the brain. Plans milestones, writes the agent's prompts, reviews its work, merges and tags.
- Coding agent = the hands. Does the research, tracing, investigations, big fixes and bulk code.
- The user = the tester. Runs the build on their real machine and reports what they see.
- The repo = the memory. Everything learned lives in committed docs, not in any chat.
Claude saves its tokens for judgment. It does not open new investigations or do major bug fixes itself — those go to the agent as a prompt.
Templates and scripts for every file below: this skill's templates/ folder (included in the release zips),
or templates/ in https://github.com/Trooper-code/Trooper-s-Coordinator-Skills. Detail for some modes is in this
skill's reference/ folder; read that file when the mode comes up.
Where the scripts live. A project keeps its check scripts in scripts/ at the repo root, or in
docs/scripts/. Always look in both (detect-mode.py reports which). Every scripts/... path in this skill means
whichever folder the project uses. New projects get scripts/ unless the user asks for docs/scripts/. Never move
a project's existing scripts.
Pick the mode
| The user says / the repo has | Mode |
|---|---|
| "status", "where are we" | Status (below) |
| "release v…", "cut a release", "tag this" | Release: follow reference/release.md |
| "import research", pasted deep-research results | Research import: follow reference/research-import.md |
repo has docs/HANDOFF.md | Continue: read HANDOFF.md, the status board and the docs it points to, then do its "First thing to do" |
| repo has code or docs, no HANDOFF.md | Adopt (below) |
| empty repo (or only README/LICENSE/.gitignore) | Kickoff (below) |
If you can run commands, python templates/scripts/detect-mode.py <repo> decides the last three and lists the
workflow files the repo has and is missing.
Status
For "Use agent-coordinator. Status." or "where are we on ?". Cheap on purpose:
- Read only
docs/MILESTONES.mdanddocs/HANDOFF.md(andgit log --oneline -5if you have the repo). - Answer in about five lines: current milestone and its state, what's in progress and who has it, the last tested result, the next step, and anything waiting on the user.
- Don't review, test or open other files unless asked.
Kickoff (new project)
E.g. /agent-coordinator Start a new project: <name>. Repo: <url or folder>. Goal: <...>. Coding agent: <...>.
- Get access. Ask for the repo (GitHub link or local folder) if you don't have it. On a local folder, also ask
for delete permission (git creates and removes
.lockfiles). - Scope. If the goal is truly unclear, ask 1–3 sharp questions: what "done" looks like, which coding agent and which of its tools the user has, and hard constraints (platform, language, what must never be committed). Otherwise start.
- Scaffold the memory (don't overwrite files that already exist):
AGENTS.md, with the agent-specific section filled in (see "The agent's rules file").docs/MILESTONES.md,docs/HANDOFF.md(with Tool versions),docs/DECISIONS.md,docs/research/INDEX.md,docs/prompts/,docs/reports/TEMPLATE.md,CHANGELOG.md.scripts/(ordocs/scripts/, if the user prefers): the check scripts (seereference/scripts.md).- Safety and releases:
templates/hooks/pre-commitcopied toscripts/hooks/pre-commit(hooks themselves aren't committed, so the user installs it once withcp scripts/hooks/pre-commit .git/hooks/pre-commit, or thedocs/scripts/...path), plus.github/workflows/checks.ymland.github/workflows/release.yml. The hook and workflows find the scripts in either folder.
- Write the first prompt for M1 to
docs/prompts/M1-<slug>.mdand runcheck-prompt.pyon it. If M1 is pure research, the agent's job is to filldocs/research/, not to write code. - Commit the scaffolding with a clear message.
- Reply briefly: the milestone list, the one-line instruction to paste into the agent, the hook install
command, and "tell me when it's done; its report will be in
docs/reports/on its branch".
Adopt (existing project)
E.g. /agent-coordinator Adopt my existing project. Repo: <url or folder>. Coding agent: <...>.
Learn what the project already knows, plan from it, and add only the docs that are missing. The scan is reading docs and repo structure, not investigating code: anything that needs tracing goes to the agent.
- Get access, as in the kickoff.
- Scan (budget: about 15–20 tool calls;
detect-mode.pydoes the inventory in one). Read, don't trace:- top-level layout, build files and test setup (language, how it builds and tests, which tool versions);
README, everything underdocs/,RESEARCH.md,NOTES.md,TODO.md,ROADMAP.md,CHANGELOG.md;- existing agent rules files (
AGENTS.md,CLAUDE.md,GEMINI.md,.cursor/rules/,.agents/rules/); - both
scripts/anddocs/scripts/: which check scripts the project already has, and where; git log --oneline -30, branches and tags: what was done last, what's half-finished;- TODO/FIXME comments, if cheap to list (
git grep -n "TODO\|FIXME").
- Inventory. Map what exists onto the workflow's files. Reuse what does the job: link an existing roadmap from
MILESTONES.md, keep existing research docs where they are and index them, and add missing sections to an existing rules file instead of replacing it. Create only what's missing. Never overwrite, move or rename the user's files. - Label what you learned. Facts from existing docs or comments are unverified until tested. Note
contradictions between docs and code as gaps. Record past choices you can see (a library picked, a format
chosen) in
DECISIONS.mdonly if the docs say why; otherwise list them as open questions. - Run
check-safe-to-publish.pyon the whole repo. If anything is flagged, tell the user first: removing a committed file from history is their call. - Plan ahead: finish half-done branches, fix failing tests, close TODOs, fill research gaps. Milestones with
done-criteria into
docs/MILESTONES.md. Real judgment calls (rewrite vs. fix, which feature first) → ask 1–3 sharp questions before committing to the plan. - First prompt. Large parts of the code undocumented → M0: survey (the agent maps them into
docs/research/and the index, every claim cited and labeled). Otherwise, M1. - Write
docs/HANDOFF.md, runcheck-handoff.py, and commit the new docs in one commit (e.g. "Add coordinator docs"), keeping each existing file's line endings. - Reply briefly: what you learned, files created or extended, the plan, anything that needs the user's call, and the one line to paste into the agent.
The agent's rules file (AGENTS.md)
Standing rules live in AGENTS.md at the repo root, so prompts only carry what's specific to their task. It holds
always/never rules, the tool-versions and stamping rules, the stop conditions, the report format, and an
agent-specific section.
Agent-specific constraints are required. Whenever the user names their coding agent (kickoff, adopt, or a
switch), fill in ## Agent-specific constraints: <agent>:
- Start from the profile in
templates/agents/(Antigravity, Codex, Claude Code, Cursor, generic). Keep its confirmed/unverified labels. - Ask which tools the user has installed, and remove the ones they don't.
- How it loads rules. If the profile says the agent reads another file, create the pointer it describes. If
unsure, say so and keep
AGENTS.mdfirst under "Read first" in every prompt. - Permission limits for high-privilege tools, and known quirks.
- When the user or the agent corrects a profile fact, fix it in
AGENTS.md, and suggest fixing the shared profile upstream too.
Milestones and branches
- Break milestone-sized work into milestones. Each gets its own feature branch.
- The agent never merges. Claude reviews the branch, then merges and tags it (e.g.
m5-p4a) once the user has tested it and it works. - Track status in
docs/MILESTONES.md(milestones, dated progress log, current "Next" step).
Writing a prompt
Prompts go in docs/prompts/<MILESTONE>-<slug>.md, committed, self-contained (the agent has none of this chat's
context). Sections, as in templates/PROMPT.md:
- Read first:
AGENTS.mdfirst; thendocs/research/INDEX.mdand the sections this task needs; anyDECISIONS.mdentries it touches. - Goal: one or two sentences.
- Branch: the name, and which tag to branch from.
- Known facts: exact paths, addresses, offsets, values; each confirmed or unverified, with evidence.
- Tasks: numbered. If
check-research.pyfound facts proven on older tool versions that this task relies on, re-checking them is a task. - Tools: the agent's tools that fit this task, and why.
- Task-specific constraints: only what
AGENTS.mddoesn't already say. - Stop and report if: the AGENTS.md stop conditions, plus any for this task.
- Acceptance checks: which tests must pass; every claim cites its evidence.
- Report:
docs/reports/<MILESTONE>-<slug>.md, committed on the branch.
Run check-prompt.py on it, fix what it reports, then give the user a one-line instruction for the agent, e.g.
"Read and follow docs/prompts/M5-p4b-save-format.md."
Naming tools. Process skills (e.g. superpowers: systematic-debugging, test-driven-development,
verification-before-completion); analysis or reverse-engineering toolkits (their claims need proof by emulation,
a test or a real run; keep high-privilege features read-only on the user's files); multi-agent "swarm" modes only
for big tasks that split into independent parts — a swarm prompt spells out each worker's part, files and
done-criteria, and says the verifiers run the repo's tests.
Reviewing the agent's work
Read the report from the branch: git fetch origin <branch> then
git show origin/<branch>:docs/reports/<file>. Only ask the user to paste a summary if the report isn't there.
The agent has been wrong before. Verify, don't trust:
check-report.pyon the report. A report that fails goes back to the agent, unless the gaps are trivial.- Tool versions in the report against
docs/HANDOFF.md. A mismatch is a bug until explained. - Re-run its tests and proofs yourself.
- Spot-check the addresses, offsets and claims it cites against the real files and logs. Check that confirmed
findings are stamped (
[confirmed @ <branch> | tool=version]) and new sections are in the research index; runcheck-research.py. - Decode or check its output by hand.
- List results as bugs, then gaps, then nitpicks.
Budget rule: if checking a claim needs new tracing beyond what the agent cited (roughly more than ~10 tool calls), stop. Put it in the next prompt instead.
If the agent stopped, don't redo its work: decide what it needs (access, a file, a corrected fact, a smaller task) and write that into the next prompt.
After review:
- Works → give the user exact test steps (what to do, what they should see). Once they confirm, merge, tag, add
a line under
## UnreleasedinCHANGELOG.md, and record it in the docs. - Doesn't work → write the follow-up prompt with the bugs and gaps as tasks.
- Abandon instead after two failed review rounds, or when the fix heads the wrong way: keep the branch
(rename it
abandoned/<name>if the user agrees), record why in the research docs and as a Lesson, keep any confirmed findings, and write a fresh prompt from the last good tag.
Keeping the memory sharp
- Decisions. When the user makes a real choice between options (a format, a library, rewrite vs. fix), add an
entry to
docs/DECISIONS.md: decided, rejected, why, revisit-if. Before reopening a settled question, read its entry; new facts get a new entry that supersedes the old one. - Research index. Every research topic has one line in
docs/research/INDEX.mdpointing to its file and section. Look things up there first; keep it current when sections move. - Version-aware facts. Confirmed facts carry a stamp of the tag and tool versions they were proven on. Whenever
the Tool versions table changes, run
check-research.pyand put re-checking the listed facts into the next prompt. - Lessons become rules. A lesson hit a second time gets
(x2)in HANDOFF.md, then moves intoAGENTS.md(a rule for the agent), a check script (if it can be automated), or the prompt template. - Findings rule. Every finding goes into the repo docs in the same session, labeled confirmed, unverified or wrong, with evidence. Fix old claims that turned out wrong. Keep line endings.
- Safe to publish. Nothing copyrighted or personal gets committed: the pre-commit hook and CI run
check-safe-to-publish.py. Users supply their own game files.
Session handoffs
Pair this with the project-handoff skill. Suggest a handoff at the end of each review round or when context gets large. The switch routine:
- Claude updates
docs/HANDOFF.md, runscheck-handoff.py, and commits. - The user runs whatever Claude asked for (logs, captures).
- The user gives the agent its prompt.
- New Claude chat: paste HANDOFF.md (or, if the chat can read the repo, "Read docs/HANDOFF.md and do its First thing to do"). The agent's report is already on its branch, so nothing else needs pasting.