Skip to content

sethbarrett50/mightymodels-codex

v0.1.0Apache-2.0

Experimental native Codex adaptation of MightyModels roles, skills and MCP state server

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

Python 3.14 uv Ruff ty prek

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

Each row is a failure I hit in agentic coding, and the part of the harness built to stop it.

What goes wrongWhat 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 VERIFIED or INFERRED, 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 stuckWhat happensIf that fails
The internIt reports blocked at the first wall, without debugging.The engineer takes the task.
The engineeragent-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 architectIt 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 callask-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:

  1. You make the design choices, and the model does not. Scouts bring facts, cross-examine puts each decision to you, and the plan is written from your answers.
  2. Risk is established up front and kept small. plan.md lists 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 to break-it-down, which puts the split to you.
  3. Your decisions are recorded so they are never forgotten. cross-examine restates the decisions record after every round, plan.md keeps it through a compaction, BATON.md carries the settled ones to the next session, and the archive keeps them after the ticket is deleted.
  4. 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/ to info/exclude in git's common directory.
  • Worktrees share it, and no commit is needed.
  • The line covers the whole directory, the archives and every ticket.yml included.
  • /prune-ticket archives the ticket and deletes it when the work merges.

Warning

There is also a second reason for keeping the exclusion local. briefs/ and review/ carry raw command output that can hold secrets, and a local exclusion means a careless git add -A cannot 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 sayWhat happens
lets-investigateScouts go and read, one narrow question each, and you decide when it is enough.
game-planThe plan gets written, after cross-examine has grilled you about it.
agents-assembleThe sprint. One task at a time, each one verified before the next starts.
ask-an-adultA judgment call goes to wingman, the strongest reasoner in the fleet, which has no tools.
whats-brokenDebugging from evidence, with a three-strike limit.
stick-the-landingThe push, the PR, and gitty-up watching CI.
review-circusuncle-bob grades the code and merge-vader gives the merge verdict.
baton-passYou walk away, and the next session picks up where you stopped.
crashoutYou 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

DependencyWhyInstall
Claude CodeThe host for the skills, workers, hooks and MCP server.Set up Claude Code
uv, on PATHThe 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
gitA 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 systemThe 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 runuv downloads Python and the locked dependencies the first time it builds the environment.

Optional

DependencyWhat it unlocksWithout itInstall
GitHub CLI (gh), logged inIssues, 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
jqgitty-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 /agents in a session afterwards. The twelve workers should be listed as mightymodels:<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
PhaseThe loop inside itSkillsWhat it leaves behind
TriageScout rounds, until you say it is enoughlets-investigate, what-we-know, open-ticketA ledger of cited facts, then a ticket directory with ticket.yml
PlanningQuestion rounds, until the decisions are settledone-shot, game-plan, cross-examine, break-it-downA task list or an approved plan.md
ExecutionOne task at a time, until none are left and CI is greenagents-assemble, stick-the-landingCommits, one brief per task, REPORT.md, a PR
ReviewFindings and fixes, until none you picked are leftreview-circus, prune-ticketReview 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-adult takes it to wingman and brings wingman's questions back to you before work resumes.
  • gh or jira is missing. open-ticket keeps 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 on fable and has no tools, so ask-an-adult puts the ticket's text into the packet it sends.
  • Scout reports separate VERIFIED facts from INFERRED ones, and anything inferred names what it rests on.
  • The ledger is restated in chat every round and saved in the state database. Two hooks, SubagentStop on the scouts and PostToolUse on SubagentHandback, store each scout report for similarity search.
  • what-we-know cites 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-ticket asks for the slug and the tracker (GitHub, Jira, both or none). The ticket tool then asks for the scope, the branch, and whether a compaction is expected.
  • It creates .mightymodels/<slug>/ with ticket.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-examine by itself.
  • "this task is too big" to run break-it-down on one task.

When it goes wrong:

  • A task is too large. break-it-down shows 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-ticket sends even a small ticket through game-plan.
  • Nobody will be around when a task blocks. game-plan asks who answers a blocked task, and you can tell it to escalate automatically.

Why it is built this way:

  • plan.md carries 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:

scopeplan-firstramp
smfalseone-shot
smtruegame-plan
med or largeeithergame-plan
  • An expected compaction sets plan-first: true.
  • one-shot runs by itself at session start when the active ticket says scope: sm and plan-first: false. An explicit /one-shot runs on any scope, after a confirmation on med or large. It reconfirms the claims at HEAD with two or three scouts, assumes no compaction, and writes no plan or handoff file.
  • game-plan has terry-toolchain survey the environment once, on sonnet, and saves the survey as toolchain.md in the ticket directory.
  • cross-examine has three depths: Skim, Standard and Relentless. It restates a decisions record after every round.
  • plan.md holds invariants with how each is proved, dependency-ordered tasks each with a size (tiny, sm, med or large) and acceptance criteria, non-goals, and risks with the handling you chose.
  • Only the answer "escalate automatically" writes auto-escalate: true into ticket.yml.
  • The task tool's task_start warns about a task with more than four acceptance criteria or more than three owned files and names break-it-down. An engineer or architect that returns too-large lands 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 happenedWhere it goes
A bounded miss on a taskAn engineer residual, with one attempt
The intern's task blocksThe engineer
The engineer fails or blocksYou first, then the architect for one pass
The architect fails toowhats-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 failingagent-debugging. A fourth failed fix is refused and the engineer reports blocked.
A CI check failsIf the fix is obvious from the last screen of the log it is an engineer residual, otherwise it is whats-broken.
The session compactsA PreCompact hook snapshots the ticket. Recovery reads the recorded state, never a conversation.
The engineer is dispatched too earlyThe 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 task tool's task_verify closes 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 tiny task has one owned file. It goes to the intern on haiku for one attempt. The engineer runs on sonnet and the architect on opus. 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 as C<n> tasks.
  • With auto-escalate: true in ticket.yml, a failed or blocked engineer task goes to the architect without asking you first.
  • agent-debugging is preloaded into the engineer. Its failed_fix_record tool 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.md of 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:

FindingWhere it goes
Critical, or a security finding at High or aboveA full engineer task, whichever reviewer found it
Any other uncle-bob findingA full engineer task, because it concerns structure and abstraction
A single-concern merge-vader finding with usable Fix and Verify linesAn 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-ticket refuses 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-circus runs on a diff, a branch, a ticket or the whole codebase.
  • The reviewers take their model from the review run: sonnet for a quick review, opus for standard and deep. One run may spend a single override, through review_override, that moves its heavier-weighted reviewer to fable.
  • The review_metrics MCP tool measures structure (fan-in, fan-out, cycles, sizes), and the signals_code_churn, signals_change_coupling and signals_code_hotspots tools measure git history. qualitylens, on haiku, 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 in skills/agents-assemble/references/contracts.md.
  • Each fix runs under its own R<n> task, carrying the finding's Fix and Verify lines.
  • prune-ticket writes an archive of at most 30 lines at .mightymodels/archives/<slug>.md, with a JSON sidecar. It refuses while there are unverified tasks, a live whats-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-ticket ends by asking whether to plan now, go straight to one-shot, or hand off. stick-the-landing asks on green whether to review now or hand off. And if a compaction arrives before you get to it, a PreCompact hook snapshots the ticket anyway.

Technical details: baton-pass

  • From a session with no ticket, baton-pass runs open-ticket first, so there is a ticket directory to write into.
  • handoffs/BATON.md holds only what is recorded nowhere else. The ticket's context lines are refreshed alongside it.
  • The opening prompt is built from a template that prompting-subagents holds.
  • The next session starts from ticket.yml, the task tool 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.

SkillPhaseWhat it does
lets-investigateTriageOpens 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-knowTriageConsolidates understanding: knowns with file:line or URL citations, the uncertainties, and an analysis shaped by the question.
open-ticketTriageTurns 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-shotPlanningThe 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-examinePlanningInterviews you about a plan, design or decision at a depth you pick first: Skim, Standard or Relentless.
game-planPlanningThe 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-downPlanningSplits a task that is too large into reviewable pieces. It changes nothing before you answer.
agents-assembleExecutionThe 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-landingExecutionCloses the sprint: pushes, opens the PR from the repository's template and has gitty-up watch CI.
whats-brokenExecutionThe 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-debuggingExecutionThe same protocol for one engineer with nobody to dispatch. A fourth failed fix is refused and the engineer reports blocked.
review-circusReviewThe 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-bobReviewThe 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-vaderReviewThe merge-vader worker's doctrine: an adversarial pre-merge review that ends in BLOCK, MERGE WITH CONDITIONS or CLEAR.
prune-ticketReviewCloses 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-passAnyHands 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-adultAnyTakes 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-subagentsAnyBuilds, checks or repairs the dispatch packet for a worker: which worker, which template, which model alias.
crashoutAnyThe 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.

FolderWorkerModelJob
triagecode-scouthaikuRepository retrieval: files and symbols, call sites, config values, dependency versions.
triageweb-scouthaikuDocumentation retrieval: one official page, changelog or release note, cited by URL and section.
triagewingmanfableThe decision advisor. It has no tools and works only from the packet it is given.
triageterry-toolchainsonnetThe environment surveyor, dispatched once per game-plan run.
workersengineersonnetThe default implementer. One task group or one residual fix, inside the files the dispatch owns.
workersarchitectopusThe higher-cost recovery implementer, for a task the engineer failed or a reviewer rejected.
workersinternhaikuThe lowest-cost implementer, for a task the plan sizes tiny: one owned file.
workersgitty-uphaikuThe 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.
reviewuncle-bobby depthThe maintainability reviewer.
reviewmerge-vaderby depthThe release-readiness reviewer.
reviewqualitylenshaikuThe measurement worker: code churn, change coupling and hotspots.
reviewfact-checkerhaikuThe 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.

EventMatcherWhat it does
SessionStartanyExports the plugin data directory to the session's commands and prunes old session pointers.
PreToolUseAgentThe 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.
SubagentStopthe two scoutsStores the scout's report for similarity search.
PostToolUseSubagentHandbackStores a scout report handed back mid-session.
PostToolUseAskUserQuestionRecords each answered question as a decision in the ledger of the investigation or ticket the session is working on.
PostToolUsethe mighty-mcp tools that name a ticketPoints the session at that ticket or investigation, so later hooks know which ledger it is working in.
PreCompactanyWrites 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 quality matches CI's quality job. make check is 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.