Experimental Codex port: This fork generates 11 enabled native Codex agents (plus one disabled Claude-only Fable/wingman source), 19 Codex-specific skills, MCP startup, and lifecycle adapters. See Codex setup, user-wide installer, and live validation. Only partial interactive CLI behavior has been observed; dispatch denial, read-only scout isolation, model identity and complete lifecycle acceptance are not host-verified. No Astra model is configured.
mightymodels
Context is the bottleneck of agentic coding. mightymodels manages it. A Claude Code harness that treats every subagent as a unit of context: the main session keeps its window for judgment, every task runs in a clean one, and the record of the work lives in GitHub or Jira, not your repository.
CI Supply chain Upstream releases License
Claude Code plugin Skills Claude workers Codex agents Claude hooks
Install · Requirements · How the work moves · Skills · Workers · Under the hood · Development
Scope of this README: Unless explicitly identified as Codex-specific, the descriptions below document the original Claude Code plugin, including its 12 workers, Fable/wingman, seven hooks, installation commands and model tiers. The Codex fork enables 11 roles and 19 generated skills; use Codex setup instead of the Claude plugin installer. Native Codex security and parity claims remain subject to open acceptance issues.
Every long agent session hits the same wall:
- The window fills, and the model gets worse. Context is a finite resource with diminishing returns: the more tokens in the window, the worse the model recalls what is in it (Anthropic, 2025).
- Compaction feels like a memory wipe. It rarely keeps what mattered, your instructions and the decisions you made along the way, and a session that keeps compacting gets more expensive while it gets worse.
- Specs go stale on arrival. Spec-driven development writes the context down, but a spec is legacy the moment implementation starts. It cannot adapt when the work changes, and it stays in the repository as stale context for the next agent to trip over.
mightymodels is built on one idea: a subagent is a unit of context.
- The primary session plans, routes and judges. It never fills its own window with file dumps, logs or diffs.
- Every task goes to a worker with a precise brief and a clean context window, sized to one reviewable change.
- Workers explore thoroughly in their own windows and hand back a condensed report. That is the pattern behind Anthropic's finding that an Opus lead with Sonnet subagents outperformed single-agent Opus by 90.2% on their research eval (Anthropic, 2025).
- A worker that gets it wrong breaks one task, not the workflow: the failure is caught, routed and retried inside that task's boundary.
The workers run as an org chart, not a swarm. A naive multi-agent setup passes one agent's output straight into the next, so a single hallucination compounds down the chain. In mightymodels every role has a tier, a job and a limit:
- Scouts retrieve and never diagnose.
- Implementers build against a brief written before they start.
- A separate fact-checker, in its own clean context, sets each report against what was asked.
- A worker that gets stuck escalates up a bounded ladder that always ends with you.
See An org chart, not a swarm.
State lives outside the conversation, so compaction stops being a memory wipe.
- Tickets, tasks, decisions and review findings are recorded in a state database.
- The work moves through gated phases: triage, planning, execution, review.
- Any session, fresh or compacted, resumes from what was recorded, not from what was remembered.
- The paper trail goes where it belongs: the problem and its findings to a GitHub issue or Jira ticket, the summary to the PR, the review to a PR comment.
- Your git history holds the commits and nothing else. The local working files are archived and deleted when the work merges.
Sources
- Anthropic, Effective context engineering for AI agents (September 2025): "as the number of tokens in the context window increases, the model's ability to accurately recall information from that context decreases," and specialized sub-agents "handle focused tasks with clean context windows," each returning "a condensed, distilled summary of its work."
- Anthropic, How we built our multi-agent research system (June 2025): the multi-agent system "outperformed single-agent Claude Opus 4 by 90.2% on our internal research eval," with subagents "operating in parallel with their own context windows" and providing "separation of concerns."
Important
Nothing here is decoration. Every skill, worker, hook and gate exists because I hit the problem it solves while coding with agents. The plugin ships nineteen skills, twelve worker agents, seven hooks and one MCP server that holds the state, and What it fixes maps each failure to its fix.
Table of contents
- What it fixes
- An org chart, not a swarm
- The ritual
- Nothing is tracked by git
- The names
- Requirements
- Install
- How the work moves
- Walking away: baton-pass
- Skills
- Workers
- Under the hood
- What is not there yet
- Development
What it fixes
Each row is a failure I hit in agentic coding, and the part of the harness built to stop it.
| What goes wrong | What mightymodels does |
|---|---|
| The main session fills with file dumps, logs and diffs, and quality drops as the window fills. | The primary never does the reading. Scouts retrieve, workers implement, the fact-checker verifies, and each hands back a capped report, so the primary's window stays free for decisions. |
| Compaction wipes your instructions and the decisions you made along the way. | State is recorded outside the conversation: tickets, tasks, decisions and findings in the state database, a snapshot before every compaction, and baton-pass for the facts that live nowhere else. A session resumes from the record, not from memory. |
| A worker is dispatched with a vague prompt and guesses. | Every task gets a two-half brief: what is asked, written before the worker starts, with acceptance criteria and only the files it owns. Each worker is built for one kind of work and refuses the work of the tier above it. |
| One agent's mistake derails the whole run. | A worker can only break its own task. The fact-checker compares what was asked with what was done, and the failure is routed inside that task's boundary: a residual fix, then you, then the architect, then a three-strike debugging protocol. |
| The agent starts building from a guess. | Triage comes first. Scouts answer one narrow question each, every round stops at a gate where you decide what happens next, and a ticket is cut only once the problem is understood. |
| The agent makes a decision that was yours to make. | Facts go to scouts and decisions go to you. cross-examine puts every design choice to you, the plan needs your approval before any dispatch, and no review finding is fixed unless you picked it. |
| A spec goes stale the moment the code moves, and cannot adapt when the work changes. | There is no spec. plan.md is a ledger of decisions, invariants, tasks and risks, free of code citations and revised when you change course. Citations are gathered fresh for each task, at the moment it starts. |
| "Done" is a claim nobody checked. | A task closes only through the task tool, on the primary's verdict, against its recorded commit, after the fact-checker has set the implementer's report against the brief. |
| A rule written in a prompt gets ignored. | Where it matters, the rule is code. The dispatch hook refuses a worker sent out of order, and the task tool refuses to close a task in the wrong state or against the wrong commit. |
| Specs, plans and notes pile up in git history and become context for the next agent. | Tracking goes to the tracker: the issue in GitHub or Jira, the summary in the PR body, the review in a PR comment. Nothing under .mightymodels/ is ever tracked by git, and /prune-ticket archives the ticket and deletes it when the work merges. |
What using it has been like for me:
- It is human-in-the-loop by design: the model does the work, you make the calls.
- It has cut my token consumption.
- The model gets more of the work right the first time.
- It changed the way I work with AI, and it is the plugin I cannot live without.
Note
I have no numbers for any of that yet. I plan to evaluate this release aggressively over the coming days, and what I measure will go here.
An org chart, not a swarm
Most multi-agent frameworks treat subagents as interchangeable helpers and chain their outputs together. That is how hallucinations amplify:
- one agent states a guess as a fact,
- the next builds on it,
- and by the third hand-off the error is load-bearing.
mightymodels organizes its twelve workers the way an engineering org works. Every role has:
- one job, and it refuses the rest;
- a fixed model tier: haiku retrieves and checks, sonnet builds, opus recovers, fable advises;
- a roster of the workers it may call on, enforced by a hook;
- a limit on how many times it may try before the problem goes up a level.
flowchart TD
U["You\ndesign decisions and approvals"] --> P["Primary\nplans, routes, gives verdicts"]
P -.->|"stuck on a judgment call"| W["wingman · fable\nadvisor, no tools"]
P --> S["code-scout, web-scout · haiku\nretrieve, never diagnose"]
P --> I["intern · haiku\none tiny task, one attempt"]
P --> E["engineer · sonnet\none task, up to three fixes"]
P --> A["architect · opus\nrecovery, one pass"]
P --> F["fact-checker · haiku\nchecks DONE against ASKED"]
P --> R["uncle-bob, merge-vader\nreview"]
E --> S
A --> S
R --> S
Checks and balances
- Facts and judgment are kept apart. Scouts retrieve and do not diagnose, and they mark every claim
VERIFIEDorINFERRED, with a file:line or URL citation. A guess cannot enter the workflow dressed as a fact. - What was asked is written before the work starts. The primary writes the ASKED half of the brief, the implementer appends DONE, and the fact-checker, a different agent in a clean context, checks DONE against ASKED one criterion at a time, citing file and line.
- The primary is a skeptical manager, not a second implementer. It sets the implementer's report against the fact-checker's and digs in only where they contradict each other or go vague, so its own context stays free for the verdict.
- Nobody works above their tier. Each worker refuses the work of the tier above it, and a hook refuses any dispatch outside a worker's roster, so the intern cannot quietly spin up an architect.
When a worker gets stuck
Every rung of the ladder has a limit, and every ladder ends with you.
| Who is stuck | What happens | If that fails |
|---|---|---|
| The intern | It reports blocked at the first wall, without debugging. | The engineer takes the task. |
| The engineer | agent-debugging: reproduce, record each failed fix with the failed_fix_record tool, one hypothesis at a time. | A fourth fix is refused. It reports blocked, and you decide whether the architect takes it. |
| The architect | It diagnoses the root cause and gets one pass, inside the original task's boundary. | whats-broken: evidence first, three strikes, then you. |
| The primary, on a judgment call | ask-an-adult hands the decision to wingman, the strongest reasoner in the fleet, with every fact gathered so far. | Wingman's questions come to you before any work resumes. |
The ritual
The state machine runs as a ritual, a predictable ceremony by design:
- Every piece of work goes through the same steps in the same order.
- The value comes from that sameness: a step that always happens is one the model cannot skip.
Four ideas sit under it:
- You make the design choices, and the model does not. Scouts bring facts,
cross-examineputs each decision to you, and the plan is written from your answers. - Risk is established up front and kept small.
plan.mdlists the risks with the handling you chose for each. The work is cut into small tasks, every one with a clear acceptance criterion, and a task with more than four criteria or more than three owned files is flagged with a pointer tobreak-it-down, which puts the split to you. - Your decisions are recorded so they are never forgotten.
cross-examinerestates the decisions record after every round,plan.mdkeeps it through a compaction,BATON.mdcarries the settled ones to the next session, and the archive keeps them after the ticket is deleted. - What is non-deterministic should be deterministic. Which ramp a ticket takes is read from
ticket.yml. Each worker's model is fixed. A task closes through a tool that checks its commit and the files it touched. And a hook refuses a dispatch where a rule in prose could be ignored.
Nothing is tracked by git
A unit of work, and the tasks inside it, does not belong in source control. It belongs in GitHub or Jira, where you already go to look for previous work. So mightymodels splits the record:
- The tracker gets the paper trail: the problem and its findings in the issue or Jira ticket, the summary in the PR body, the review in a PR comment.
- Git gets the work itself: the commits, and nothing else.
.mightymodels/holds the working files while the work is live, and is never tracked by git.
Important
Spec-driven development has historically left tons of slop artifacts behind, which litter the repository and confuse the agents that read them later. mightymodels keeps its working files where git cannot see them and deletes them when the work merges.
How the exclusion works:
- Nobody runs an ignore step by hand. Whenever the plugin opens the state database, it adds
.mightymodels/toinfo/excludein git's common directory. - Worktrees share it, and no commit is needed.
- The line covers the whole directory, the archives and every
ticket.ymlincluded. /prune-ticketarchives the ticket and deletes it when the work merges.
Warning
There is also a second reason for keeping the exclusion local.
briefs/andreview/carry raw command output that can hold secrets, and a local exclusion means a carelessgit add -Acannot ship them. See SECURITY.md.
The names
Some of the names are silly, and that is by design. Despite how much this plugin delivers, I promise that after a day of running it you will know every skill and subagent by heart, because they are all very memorable.
| You say | What happens |
|---|---|
lets-investigate | Scouts go and read, one narrow question each, and you decide when it is enough. |
game-plan | The plan gets written, after cross-examine has grilled you about it. |
agents-assemble | The sprint. One task at a time, each one verified before the next starts. |
ask-an-adult | A judgment call goes to wingman, the strongest reasoner in the fleet, which has no tools. |
whats-broken | Debugging from evidence, with a three-strike limit. |
stick-the-landing | The push, the PR, and gitty-up watching CI. |
review-circus | uncle-bob grades the code and merge-vader gives the merge verdict. |
baton-pass | You walk away, and the next session picks up where you stopped. |
crashout | You rant, and it writes the rant down verbatim. |
The workers have names too. terry-toolchain surveys your environment, the intern gets the one-file jobs, and the architect is who gets called when the engineer has failed. The full cast is under Skills and Workers.
Requirements
Required
| Dependency | Why | Install |
|---|---|---|
| Claude Code | The host for the skills, workers, hooks and MCP server. | Set up Claude Code |
uv, on PATH | The hooks and the state server both start through uv run --locked, against the plugin's own uv.lock. | Install uv |
| Python 3.14+ | The plugin's packages require it. uv fetches it on first run, so nothing needs installing by hand. | uv: install Python |
| git | A ticket's files live in .mightymodels/ at the git toplevel of the repository you are working in, and the hooks look up the ticket for the checked-out branch. | Install git |
| A POSIX system | The hook wrappers are sh scripts and gitty-up is bash. There is no native Windows launcher, so use WSL on Windows. | Install WSL |
| Network access, on first run | uv downloads Python and the locked dependencies the first time it builds the environment. |
Optional
| Dependency | What it unlocks | Without it | Install |
|---|---|---|---|
GitHub CLI (gh), logged in | Issues, pull requests, PR comments, and gitty-up watching CI. | open-ticket keeps the issue body as a file and shows you the command; stick-the-landing shows the command and stops. | cli.github.com |
| jq | gitty-up parses the check results with it. | gitty-up cannot report on CI. | Download jq |
jira-cli (jira) | Jira tickets, when you pick Jira as a ticket's tracker. | open-ticket writes a draft file. | ankitpokhrel/jira-cli |
Install
/plugin marketplace add rhawk117/rygentic-harness
/plugin install mightymodels@rygentic-harness
Tip
Run
/agentsin a session afterwards. The twelve workers should be listed asmightymodels:<folder>:<name>. If they are not, fix the install before debugging the loop, because the ticket routing dispatches workers by those types.
Plugin skills show up as /mightymodels:agents-assemble, and the short form /agents-assemble works whenever the name is unambiguous in your session.
How the work moves
One piece of work is split across several short sessions. Each has a narrow job and leaves a written artifact behind, so the next session starts from files and not from somebody's chat history.
The work passes through four phases in order. Inside each phase there is a loop, and every loop has a way out that goes through you.
flowchart TD
subgraph Triage
A["lets-investigate\nchat triage with scouts"] --> B["what-we-know\ncited knowns, SWOT"]
B --> C["open-ticket\ninterview, ticket.yml, issue, branch"]
end
subgraph Planning
C --> D{scope}
D -->|"sm, no plan"| E["one-shot"]
D -->|"any other combination"| F["game-plan"]
end
subgraph Execution
E --> G["agents-assemble\nper-task work loop"]
F --> G
G --> H["stick-the-landing\nPR and CI via gitty-up"]
end
subgraph Review
H --> I["review-circus\nuncle-bob and merge-vader"]
I --> J["human review"]
J --> K["prune-ticket\narchive and delete"]
end
| Phase | The loop inside it | Skills | What it leaves behind |
|---|---|---|---|
| Triage | Scout rounds, until you say it is enough | lets-investigate, what-we-know, open-ticket | A ledger of cited facts, then a ticket directory with ticket.yml |
| Planning | Question rounds, until the decisions are settled | one-shot, game-plan, cross-examine, break-it-down | A task list or an approved plan.md |
| Execution | One task at a time, until none are left and CI is green | agents-assemble, stick-the-landing | Commits, one brief per task, REPORT.md, a PR |
| Review | Findings and fixes, until none you picked are left | review-circus, prune-ticket | Review reports, a PR comment, then a 30-line archive |
Each stage reads ticket.yml before doing anything else.
Phase 1: triage
The problem here is an agent that starts building from a guess. Triage starts in chat, before any ticket exists.
flowchart LR
Q["your question"] --> S["scouts answer\none narrow question each"]
S --> L["ledger\nrestated in chat"]
L --> G{"gate\nyou choose"}
G -->|"dig further, or redirect"| S
G -->|"stop"| X["nothing staged"]
G -->|"consolidate"| W["what-we-know"]
W --> T["open-ticket"]
lets-investigate states the target plainly and sends the scouts one narrow question at a time. Scouts retrieve and do not diagnose. Every report is folded into a ledger, and the round ends at a gate where you choose what happens next. When you have enough, what-we-know turns the ledger into a table of cited knowns and a list of uncertainties, and resolves each uncertainty by asking you. open-ticket then stages the work so a fresh session can start on it.
What you will usually type:
- "let's investigate why X happens" to start, with nothing but a question.
- "what do we know" when the scouts have brought back enough and you want it consolidated.
- "cut a ticket for this" once you understand the problem.
- /one-shot when you already know the task and want to skip triage. It stages the ticket itself.
When it goes wrong:
- An investigation heads the wrong way. Every round stops at a gate, so a wrong turn costs one round.
- A judgment call cannot be settled from the facts.
ask-an-adulttakes it to wingman and brings wingman's questions back to you before work resumes. ghorjirais missing.open-ticketkeeps the body as a file and shows you the command.
Why it is built this way: retrieval is cheap-tier work, so the scouts run on the cheapest model. The ledger is saved outside the conversation so a session can end without losing it. And what-we-know is the point where the human steers, which is why it asks about each uncertainty.
Technical details: triage
- code-scout and web-scout run on
haiku. wingman runs onfableand has no tools, soask-an-adultputs the ticket's text into the packet it sends. - Scout reports separate
VERIFIEDfacts fromINFERREDones, and anything inferred names what it rests on. - The ledger is restated in chat every round and saved in the state database. Two hooks,
SubagentStopon the scouts andPostToolUseonSubagentHandback, store each scout report for similarity search. what-we-knowcites every known by file:line or URL. It has a second mode, used inside a sprint, that gathers citations for one task and asks nothing.open-ticketasks for the slug and the tracker (GitHub, Jira, both or none). Thetickettool then asks for the scope, the branch, and whether a compaction is expected.- It creates
.mightymodels/<slug>/withticket.yml, files the issue with a checked body, cuts and pushes the branch, and validates the ticket into the state database.
Phase 2: planning
The problem here is the one spec-driven development has. A plan written before the work is full of code detail that goes stale, and it carries decisions nobody put to you.
flowchart LR
T["ticket.yml"] --> R{"scope and\nplan-first"}
R -->|"sm, false"| O["one-shot\ntask list"]
R -->|"anything else"| V["scouts verify the claims\nterry-toolchain surveys"]
V --> C["cross-examine\na round of questions"]
C -->|"decisions still open"| C
C -->|"settled"| P["plan.md\nyou approve it"]
O --> S["the sprint"]
P --> S
Which ramp a ticket takes is read from ticket.yml. It is never a judgment call. one-shot is the fast one: a short interview, a scout check of the claims, and a task list with an acceptance criterion per item. game-plan is the full one. Scouts verify the ticket's claims, cross-examine interviews you in rounds at the depth you pick, and plan.md records what you decided. game-plan waits for you to approve the plan before any worker is dispatched.
What you will usually type:
- "plan this ticket" for anything that is not small.
- "just send it" or /one-shot for a small one.
- "grill me" or "stress-test this design" to run
cross-examineby itself. - "this task is too big" to run
break-it-downon one task.
When it goes wrong:
- A task is too large.
break-it-downshows you every piece in one dialog and changes nothing until you answer. You can also keep the task whole. - A compaction is likely. Saying so in
open-ticketsends even a small ticket throughgame-plan. - Nobody will be around when a task blocks.
game-planasks who answers a blocked task, and you can tell it to escalate automatically.
Why it is built this way:
plan.mdcarries no code citations, because citations go stale as soon as implementation begins (another flaw of traditional SDD), while the plan has to survive compaction.- Facts in the plan come from scouts and decisions come from you, so the plan records choices you made.
Technical details: planning
The routing rule:
| scope | plan-first | ramp |
|---|---|---|
sm | false | one-shot |
sm | true | game-plan |
med or large | either | game-plan |
- An expected compaction sets
plan-first: true. one-shotruns by itself at session start when the active ticket saysscope: smandplan-first: false. An explicit/one-shotruns on any scope, after a confirmation onmedorlarge. It reconfirms the claims at HEAD with two or three scouts, assumes no compaction, and writes no plan or handoff file.game-planhas terry-toolchain survey the environment once, onsonnet, and saves the survey astoolchain.mdin the ticket directory.cross-examinehas three depths: Skim, Standard and Relentless. It restates a decisions record after every round.plan.mdholds invariants with how each is proved, dependency-ordered tasks each with a size (tiny,sm,medorlarge) and acceptance criteria, non-goals, and risks with the handling you chose.- Only the answer "escalate automatically" writes
auto-escalate: trueintoticket.yml. - The
tasktool'stask_startwarns about a task with more than four acceptance criteria or more than three owned files and namesbreak-it-down. An engineer or architect that returnstoo-largelands there too.
Phase 3: execution
The problem here is the implementer that reports success. A model will tell you a task is done, and the only way to know is to check.
flowchart TD
N["next task"] --> B["primary writes ASKED"]
B --> D["dispatch\nintern for tiny, engineer otherwise"]
D --> F["fact-checker\nDONE against ASKED"]
F --> V{"task verify"}
V -->|"closed"| N
V -->|"bounded miss"| R["engineer residual\none attempt"]
R --> V
V -->|"failed or blocked"| U["you, then the architect"]
U -->|"architect fails too"| W["whats-broken\nthree strikes, then you"]
N -->|"no tasks left"| H["stick-the-landing"]
H --> I{"CI"}
I -->|"fail"| X["residual, or whats-broken"]
X --> H
I -->|"pass"| Y["review"]
agents-assemble runs one task at a time. The primary writes what is being asked, an implementer does the work, runs the task's checks and writes what it did, and the fact-checker compares the two halves. Only then does the primary give its verdict, the task close and the next one start. A task's size picks its worker: the intern for a tiny one, the engineer for everything else.
The sprint never pushes. stick-the-landing does that, and only you can start it. It opens the PR and has gitty-up watch CI, and a failing check goes back into the loop as a task.
What you will usually type:
- "start the sprint" or "run the loop" once the plan is approved.
- "pass the baton" when you want to stop. See Walking away.
- /stick-the-landing when every task is done.
When it goes wrong, the failure is routed. Nothing is retried blind.
| What happened | Where it goes |
|---|---|
| A bounded miss on a task | An engineer residual, with one attempt |
| The intern's task blocks | The engineer |
| The engineer fails or blocks | You first, then the architect for one pass |
| The architect fails too | whats-broken: reproduce, gather evidence, test one hypothesis at a time. After three strikes it escalates to you. There is no fourth patch. |
| An engineer's own fix keeps failing | agent-debugging. A fourth failed fix is refused and the engineer reports blocked. |
| A CI check fails | If the fix is obvious from the last screen of the log it is an engineer residual, otherwise it is whats-broken. |
| The session compacts | A PreCompact hook snapshots the ticket. Recovery reads the recorded state, never a conversation. |
| The engineer is dispatched too early | The dispatch hook refuses it until a task is started. |
Why it is built this way: the brief has two halves so that neither side's claims are taken on faith. The loop advances only after its evidence is written down, so recovery never depends on what an agent remembers. The architect sits one tier above the engineer that failed and gets one pass. When that fails too, patching stops and whats-broken starts again from evidence. And the dispatch hook holds the primary to the loop, because an instruction in prose was not enough.
Technical details: execution
- The brief is
briefs/task-NN.md, capped at 80 lines: roughly 15 for ASKED and up to 65 for DONE. ASKED holds the objective, checkable acceptance criteria, the scoped checks to run, the files the task owns and the engineer tier. The implementer appends DONE with the commit hash. - The
tasktool'stask_verifycloses a task on the primary's verdict and the recorded commit. It refuses on the task's status, its base and its owned set, and reports any change outside the owned files. - A
tinytask has one owned file. It goes to the intern onhaikufor one attempt. The engineer runs onsonnetand the architect onopus. The primary may bump the engineer one tier for a single hard task, and logs the reason in that task's ASKED stanza. - Residual fixes run as
R<n>tasks and failing CI checks asC<n>tasks. - With
auto-escalate: trueinticket.yml, a failed or blocked engineer task goes to the architect without asking you first. agent-debuggingis preloaded into the engineer. Itsfailed_fix_recordtool stores three failed fixes per task and refuses a fourth.- While the checked-out branch has exactly one unclosed ticket, the dispatch hook refuses the main thread's dispatch of the engineer or the architect until a task is started. With several unclosed tickets it warns instead. It refuses a dispatch of the intern unless the task owns exactly one file.
- gitty-up waits for the checks under a time budget: 20 minutes by default, 60 at most.
- The sprint ends with a
REPORT.mdof at most 50 lines: what shipped, what deviated, what remains.
Phase 4: review
The problem here is review that happens somewhere reviewers never look, by the same context that wrote the code, followed by fixes nobody asked for.
flowchart LR
G["one gate\ndepth, emphasis, scope"] --> M["measure the surface"]
M --> U["uncle-bob"]
M --> V["merge-vader"]
U --> F["merged findings\ncomment on the PR"]
V --> F
F --> P{"findings\nyou pick"}
P -->|"some"| X["engineer task\nor residual"]
X --> G
P -->|"none left"| H["human review"]
H --> K["prune-ticket"]
review-circus asks one question up front for the depth, the emphasis and the scope, then runs two reviewers in parallel. uncle-bob grades maintainability against SOLID, the Clean Code smells catalog and the Clean Architecture component metrics. merge-vader reads the diff for security, regressions, weakened gates and documentation drift, and ends in BLOCK, MERGE WITH CONDITIONS or CLEAR. Their findings are merged, and an abridged comment is always posted to the PR, pass or fail.
You decide each finding by id. Then the fixes are routed by risk first and by source second:
| Finding | Where it goes |
|---|---|
| Critical, or a security finding at High or above | A full engineer task, whichever reviewer found it |
| Any other uncle-bob finding | A full engineer task, because it concerns structure and abstraction |
| A single-concern merge-vader finding with usable Fix and Verify lines | An engineer residual |
After human review and merge, /prune-ticket writes the archive, proposes documentation updates as diffs, and deletes the ticket directory on your confirmation.
What you will usually type:
- "run the review circus" on a PR with green CI.
- "is this safe to merge" or "uncle-bob this module" for a quick pass by one reviewer.
- /prune-ticket after the merge.
When it goes wrong:
- A fix fails. It climbs to the architect the way a sprint task does.
- There is no PR, or no
gh. The comment is kept as a file and you get the command. - Work is still live.
prune-ticketrefuses to delete anything.
Why it is built this way: the comment goes on the PR so the review trail is documented where reviewers live. A severity that says "harm now" outranks any statement about who found the defect, which is why risk routes before source. And nothing you did not pick is fixed.
Technical details: review
review-circusruns on a diff, a branch, a ticket or the whole codebase.- The reviewers take their model from the review run:
sonnetfor a quick review,opusfor standard and deep. One run may spend a single override, throughreview_override, that moves its heavier-weighted reviewer tofable. - The
review_metricsMCP tool measures structure (fan-in, fan-out, cycles, sizes), and thesignals_code_churn,signals_change_couplingandsignals_code_hotspotstools measure git history. qualitylens, onhaiku, transcribes the numbers and judges nothing. - merge-vader may dispatch code-scout, web-scout and qualitylens. uncle-bob may dispatch code-scout and qualitylens.
- Reports land in the run's directory under
.mightymodels/<slug>/review/. Overlapping findings are severity-unified through the shared table inskills/agents-assemble/references/contracts.md. - Each fix runs under its own
R<n>task, carrying the finding's Fix and Verify lines. prune-ticketwrites an archive of at most 30 lines at.mightymodels/archives/<slug>.md, with a JSON sidecar. It refuses while there are unverified tasks, a livewhats-broken.md, undecided or unfixed review findings, or unpushed commits.
Walking away: baton-pass
This is one of my favorite features. With AI it is hard to walk away from a session cleanly. Stop in the middle and the next session starts cold, or stay and keep working in a context that has grown too long. Either way there is a penalty.
baton-pass is how you leave. It works from an active sprint or from a session with no ticket at all. It snapshots the recorded state, runs what-we-know, and asks you two things: what the next session should focus on, and what to do with uncommitted work. Then it writes handoffs/BATON.md with the facts that live nowhere else (settled decisions, dead ends, working commands, gotchas and parked threads) and prints the opening prompt for the next session.
Tip
The loop also offers it at the natural stopping points.
open-ticketends by asking whether to plan now, go straight toone-shot, or hand off.stick-the-landingasks on green whether to review now or hand off. And if a compaction arrives before you get to it, aPreCompacthook snapshots the ticket anyway.
Technical details: baton-pass
- From a session with no ticket,
baton-passrunsopen-ticketfirst, so there is a ticket directory to write into. handoffs/BATON.mdholds only what is recorded nowhere else. The ticket'scontextlines are refreshed alongside it.- The opening prompt is built from a template that
prompting-subagentsholds. - The next session starts from
ticket.yml, thetasktool and the briefs.
Skills
Claude Code picks a skill from your prompt and the skill's description, or you name it with a slash. Three run only when you start them: stick-the-landing, prune-ticket and crashout. Four are never invoked by hand, because a worker or the primary loads them: agent-debugging, becoming-uncle-bob, becoming-merge-vader and prompting-subagents. Each skill's full instructions are in skills/<name>/SKILL.md.
| Skill | Phase | What it does |
|---|---|---|
lets-investigate | Triage | Opens a chat-first investigation before any ticket exists. Scouts get one narrow question each, and every round stops at a gate where you choose to dig further, redirect, stop or consolidate. |
what-we-know | Triage | Consolidates understanding: knowns with file:line or URL citations, the uncertainties, and an analysis shaped by the question. |
open-ticket | Triage | Turns an understood problem into a staged ticket: the directory, the issue or a local draft, the branch, and ticket.yml with derived model routing. |
one-shot | Planning | The fast ramp. One dialog, a scout check of the claims at HEAD, a task list with an acceptance criterion per task, then straight into agents-assemble. It writes no plan or handoff file. |
cross-examine | Planning | Interviews you about a plan, design or decision at a depth you pick first: Skim, Standard or Relentless. |
game-plan | Planning | The large-scope ramp. Scouts verify the ticket's claims, terry-toolchain surveys the environment, cross-examine runs, and plan.md is written as a compaction-safe ledger. |
break-it-down | Planning | Splits a task that is too large into reviewable pieces. It changes nothing before you answer. |
agents-assemble | Execution | The per-task work loop: citations, the two-half brief, a dispatch, the fact-checker, then verify. It ends in a REPORT.md of at most 50 lines and never pushes. |
stick-the-landing | Execution | Closes the sprint: pushes, opens the PR from the repository's template and has gitty-up watch CI. |
whats-broken | Execution | The primary's debugging protocol: reproduce, gather evidence, test one falsifiable hypothesis at a time, then fix through a normal engineer dispatch with a regression test. Three strikes and it escalates. |
agent-debugging | Execution | The same protocol for one engineer with nobody to dispatch. A fourth failed fix is refused and the engineer reports blocked. |
review-circus | Review | The endgame review. uncle-bob and merge-vader run in parallel, and an abridged comment is always posted to the PR, pass or fail. Only the findings you pick get fixed. |
becoming-uncle-bob | Review | The uncle-bob worker's doctrine: grade a branch or a codebase against SOLID, the Clean Code smells catalog and the Clean Architecture component metrics. |
becoming-merge-vader | Review | The merge-vader worker's doctrine: an adversarial pre-merge review that ends in BLOCK, MERGE WITH CONDITIONS or CLEAR. |
prune-ticket | Review | Closes out finished work: a 30-line archive, documentation updates proposed as diffs, then deletion of the ticket directory on your confirmation. It refuses while live work remains. |
baton-pass | Any | Hands a session to the next one: handoffs/BATON.md with the facts that live nowhere else, and an opening prompt for the next session. |
ask-an-adult | Any | Takes a judgment call that cannot be decided to wingman, and carries its questions to you before work resumes. For reasoning, not for facts a scout can retrieve. |
prompting-subagents | Any | Builds, checks or repairs the dispatch packet for a worker: which worker, which template, which model alias. |
crashout | Any | The pressure valve. On an explicit /crashout it journals your rant verbatim, checks whether the failure has happened before, and turns repeated tilt into standing corrective actions. |
Workers
The twelve workers are subagent files under agents/, in three folders: triage, workers and review.
| Folder | Worker | Model | Job |
|---|---|---|---|
triage | code-scout | haiku | Repository retrieval: files and symbols, call sites, config values, dependency versions. |
triage | web-scout | haiku | Documentation retrieval: one official page, changelog or release note, cited by URL and section. |
triage | wingman | fable | The decision advisor. It has no tools and works only from the packet it is given. |
triage | terry-toolchain | sonnet | The environment surveyor, dispatched once per game-plan run. |
workers | engineer | sonnet | The default implementer. One task group or one residual fix, inside the files the dispatch owns. |
workers | architect | opus | The higher-cost recovery implementer, for a task the engineer failed or a reviewer rejected. |
workers | intern | haiku | The lowest-cost implementer, for a task the plan sizes tiny: one owned file. |
workers | gitty-up | haiku | The CI watcher. It opens or takes a pull request and waits for the checks under a time budget, 20 minutes by default and 60 at most. |
review | uncle-bob | by depth | The maintainability reviewer. |
review | merge-vader | by depth | The release-readiness reviewer. |
review | qualitylens | haiku | The measurement worker: code churn, change coupling and hotspots. |
review | fact-checker | haiku | The task verifier. It checks a brief's DONE half against its ASKED half before the task closes. |
All of them are delegation-only. Half the fleet runs on haiku, and what keeps it cheap is that each worker refuses the work of the tier above it.
Note
The model names are Claude Code aliases, and which model an alias resolves to is Claude Code's decision in your session.
The main conversation dispatches every worker. A worker dispatches only the workers its agent file names, and a hook refuses anything else.
Under the hood
Hooks: seven of them, on five events
hooks/hooks.json registers seven hooks on five events. Each runs the mightymodels-hooks package against the state database and has a timeout of 10 seconds.
| Event | Matcher | What it does |
|---|---|---|
SessionStart | any | Exports the plugin data directory to the session's commands and prunes old session pointers. |
PreToolUse | Agent | The dispatch hook. It holds a worker to the workers its agent file allows, and refuses the main thread's dispatch of the engineer or the architect until a task is in progress. |
SubagentStop | the two scouts | Stores the scout's report for similarity search. |
PostToolUse | SubagentHandback | Stores a scout report handed back mid-session. |
PostToolUse | AskUserQuestion | Records each answered question as a decision in the ledger of the investigation or ticket the session is working on. |
PostToolUse | the mighty-mcp tools that name a ticket | Points the session at that ticket or investigation, so later hooks know which ledger it is working in. |
PreCompact | any | Writes a snapshot of the ticket on the checked-out branch before a compaction. |
The hooks record and route. They are not a permission control: they do not run or approve commands, and they do not replace Claude Code's permission prompts. SECURITY.md lists exactly what the dispatch hook refuses, including what happens when the state cannot be read.
State: where a ticket lives
The state lives in two places.
A ticket's files (ticket.yml, the plan, briefs, snapshots, review runs and archives) are in the target repository's .mightymodels/ directory, at the git toplevel. None of them is tracked by git; see Nothing is tracked by git.
The rows (tickets, tasks, review runs, ledgers, crashouts, closings and stored scout reports) are in state.db, one SQLite database in the plugin data directory that Claude Code names in CLAUDE_PLUGIN_DATA. That file is outside every repository and serves all of them.
mcp-servers/mighty-mcp.json declares one stdio server named mighty-mcp, started with uv run --locked --no-dev --package mightymodels-mcp mightymodels-mcp. The skills call its tools as mcp__plugin_mightymodels_mighty-mcp__<tool>, and those tools and AskUserQuestion are the only ones a skill's allowed-tools pre-approves. No skill pre-approves Bash, Edit or Write. docs/mighty-mcp-tools.md lists all 35 tools by domain.
Contracts shared by every stage live with the skills that own them. The severity table, the verdict vocabularies and the two-half brief schema are in skills/agents-assemble/references/contracts.md. The ticket schema and the directory layout are in skills/open-ticket/references/. When a skill and a contract disagree, the contract wins and the skill gets fixed.
Startup: how the plugin runs
Nothing is installed globally. Both entry points run through uv run against the plugin's own uv.lock, with UV_PROJECT set to the plugin root and the environment kept in the plugin's .venv:
# hooks/lib.sh, sourced by hooks/hook.sh and hooks/dispatch-hook.sh
exec uv run --locked --no-dev --package mightymodels-hooks mightymodels-hooks "$@"
hooks/hook.sh wraps the recording hooks. When it cannot run, it prints mightymodels hook did nothing with the hook's name to standard error and lets the tool call through. hooks/dispatch-hook.sh wraps the dispatch hook and fails closed instead: when it cannot run, it refuses any dispatch made by a plugin worker, and any dispatch of the engineer, architect or intern while the project has a .mightymodels/ directory.
Layout: what is in the repository
.claude-plugin/plugin.json the plugin manifest
mcp-servers/mighty-mcp.json the state server
agents/ the twelve workers, in triage/, workers/ and review/
skills/ the nineteen skills
hooks/ hooks.json (the seven hooks) and the sh wrappers
bin/gitty-up the CI watcher script
packages/core/ mightymodels_core: the domain, the SQLite store, git access
packages/hooks/ mightymodels_hooks: the hook subcommands
packages/mcp/ mightymodels_mcp: the mighty-mcp server and its tools
docs/ the MCP tool reference
tests/ the test suite
pyproject.toml the mightymodels-plugin project and the uv workspace root
uv.lock the pinned dependencies
What is not there yet
- Nothing measures the token savings or the correctness yet. That is the evaluation planned for the coming days.
- No trigger datasets ship in this repository yet, so nothing measures skill selection. Until they do: a skill that runs when named but never selects itself has a description problem, and a skill the slash menu cannot find has a loading problem.
- Only one permission mode has been tested so far.
- Whether plugin agents surface, and under which names, depends on your Claude Code version behaving as the current docs describe.
Note
One thing is left out on purpose: issue-tracker sprint and board operations are outside the plugin.
Development
The plugin is the mightymodels-plugin project at the repository root, which is also the uv workspace root, with core, hooks and mcp as members under packages/. Every command goes through make:
make setup # once: install the prek git hooks and sync every package and group
make format # the prek hooks in the format group
make lint # the prek hooks in the lint group: ruff check, ty, shellcheck, hygiene checks
make check # lint, then the unit, agents and smoke tests
make quality # every prek hook, then the tests CI runs
uv run pytest # the whole test suite
Tip
make qualitymatches CI's quality job.make checkis the faster local loop, but it skips the format hooks, so it can pass where CI fails.
Security reports go through SECURITY.md. Licensed under Apache-2.0.