opm-core

OPM: a Claude Code plugin for spec-driven, test-first development

Design it. Prove it. Ship it.

OPM is a Claude Code plugin that adds a full engineering workflow: brainstorm a design, write a plan, build it test-first with fresh-context subagents, review it, and verify it before anything is called done. It measures what it costs, and CI holds it to that.

npx opm-core@latest

Start here: using-opm

Every Claude Code session with OPM installed starts with the using-opm skill already loaded. You do not have to remember any other command. It is the front door to everything else in the plugin, and it does five things for you:

• Picks the right amount of process. A 10-line fix goes straight to a test-first change. A feature gets a short design and a plan. Weeks of work get a milestone. You never pay for ceremony a small job does not need.
• Uses Claude Code's power without being asked. Wide searches and reviews go to subagents, so your main conversation stays small and cheap. Independent pieces run in parallel, in separate git worktrees when they edit files.
• Offers the big tools instead of hiding them. When a job would clearly benefit from many agents at once, it offers a multi-agent run with a rough agent count, and starts it only after you say yes.
• Tells you what it is doing. Every step up is announced in one line ("Using 3 parallel subagents to ..."), so you can stop it.
• Checks before it says done. Subagent reports are verified, tests are run, and nothing is called finished without fresh evidence.

It loads by itself through a session-start hook. Run /opm:using-opm at the start of a session when you want to be sure it is active: after a long session was compacted, in an editor where the hook did not run, or just to see the rules. Details: docs/using-opm.md.

What OPM can show

Four claims, each with its evidence. Token counts are bytes / 4 estimates from npm run tokens.

1. It costs 2,526 tokens per session. That is every skill and agent description plus the using-opm skill injected at session start. The rules add 1,401 tokens in repos that install them. CI fails if either grows past its ceiling. Evidence: the cost table. You can also check the plugin with claude plugin details opm.

2. Big skills load a small core. A skill costs nothing until it runs. The split skills then load only their core; the references/ files load when a step needs them.

Skill	Core, per run (tokens)	References, on demand (bytes)
executing-plans	1,056	18,567
flutter-patterns	856	10,754
react-patterns	828	8,849
python-patterns	797	10,166
verification-before-completion	1,371	4,814

The other skills are not split yet. The largest, milestone-planning, loads 2,911 tokens. Evidence: the per-skill table.

3. CI runs on macOS, Linux and Windows, with Node 18, 20 and 22. Nine test jobs, then a gate that validates the manifests with the Claude Code CLI. Evidence: CI and the badge above.

4. Status and safety cost no model turn, on Claude Code 2.1.287 or later. /opm-status, /opm-status --all and /opm-report are answered by code. The destructive-command hold and the hook-bypass checks run as code before a tool call. These are tested with the Claude Code test kit in CI, not yet in a live session. Evidence: Mod features and docs/threat-model.md.

What OPM cannot show yet, such as the cost of a whole task, is listed in docs/why-opm.md.

The problem, in plain terms

You open Claude Code and describe what you want. It starts writing. For twenty minutes this feels like magic.

Then it drifts. It says the tests pass, and it never ran them. It rewrites a file it already got right. It forgets a decision you made an hour ago, because that decision is now buried under forty thousand words of conversation.

Here is the part nobody mentions. Every message you send re-reads the whole conversation. Hour one, that is cheap. Hour three, you are paying to re-read the same hour-one chat again on every single turn, and the model is getting worse at its job while the cost climbs.

That is one long conversation doing everything. It is the default, and it is the expensive way.

What OPM does instead

OPM splits the work. A small main thread holds the plan. Each task goes to a fresh worker that sees only that one task and then disappears. The long work happens in the workers, so the main thread stays small.

Then it refuses to take anyone's word for anything. A reviewer reads every task's diff before the next one starts. Nothing is called done, fixed or passing without real command output. A ledger on disk survives the context being wiped, so if the session resets, the work does not restart.

	One long chat	OPM
What the model re-reads each turn	Everything so far	The current task
Quality as the day goes on	Drifts	Held by a reviewer gate
"Tests pass"	Sometimes a guess	Pasted output, or it does not count
If the session resets	Start over	The ledger picks up where it stopped

What this costs is measured above, in What OPM can show.

Two things worth trying first

🧠 /opm:brew-idea — argue with your idea before you build it

A single AI agrees with you. Ask it to build the wrong thing and it will build the wrong thing, enthusiastically, and you find out three weeks later.

Brew-idea puts four agents in a room and makes them fight:

• Product asks who this is for, and what nobody actually asked for
• Engineering asks what is cheap, what is expensive, and what breaks
• Skeptic is paid to attack it: how it fails, what makes it pointless
• Market searches the web for who already built this, and says so plainly when it could not verify a claim

Then every agent has to take a position on every other agent's idea. No fence-sitting. A judge reads the whole argument and marks each feature keep, improve, add or cut, with the reason and who argued for it. Anything the skeptic lands a serious hit on gets cut unless there is a real answer.

/opm:brew-idea A field-sales app for our reps: visit planning, GPS check-in,
order capture synced to the ERP.

A designer then turns the verdict into a design page, the same kind jump-start shows: who uses it, a wireframe per screen, how screens connect, data, architecture and a phased plan. The argument itself stays folded away at the bottom, and the chat gets three lines and a link. Why it matters: the cheapest feature is the one you talked yourself out of building.

🚀 /opm:jump-start — a whole project from one prompt

You could paste that same brief straight into Claude Code. Here is what differs.

Pasting the brief directly	/opm:jump-start
Starts writing code in the first minute	Asks only about gaps that would change the architecture
Picks your stack and data model silently	Shows you a design with flows, wireframes and the data model, then waits
You see the result once it is built	You approve the shape before a line is written
One context, filling up all day	One fresh subagent per plan, running in parallel waves
Tests if you remember to ask	Every task is a failing test first, then code, then a commit
"It's done"	Verified, reviewed, then actually started so you can open it

/opm:jump-start my-app A field-sales app for our reps: visit planning, GPS
check-in, order capture synced to our ERP, manager dashboard on web. Android
first, offline capable.

It ends by handing you a running app and a URL, or launching it on a connected device. For the build to run unattended, switch Claude Code to auto mode with Shift+Tab when it asks. OPM never changes your permission mode itself.

How the whole loop fits together

• Brew the idea, if it is not settled. Four agents argue, a judge ranks.
• Design it. One question at a time. Nothing is written until you agree the shape.
• Plan it. The spec becomes bite-sized tasks, each with a failing test and a commit.
• Execute it. One fresh subagent per task, a reviewer gate after each.
• Verify it. Build, types, lint, tests, secrets scan. Real output, or it did not happen.
• Capture what was non-obvious, so the next project starts from it.

Every step is a skill you can use on its own. You do not have to run the whole loop to get value from any one of them.

Install

npx opm-core@latest

That installs the plugin and copies the coding rules into your repo. It takes options if you want to skip a step:

npx opm-core@latest --rules typescript,react   # no questions
npx opm-core@latest --plugin-only              # skip the rules
npx opm-core@latest --rules-only ../other-repo # rules for another repo

Or the native route, two commands:

claude plugin marketplace add harshadmadaye/OPM
claude plugin install opm@opm

The rules are plain markdown that Claude Code loads from <repo>/.claude/rules/opm/. A plugin cannot ship them, which is why they are copied per repository. Keep common/ small: it loads in every session.

This repository is public, so no GitHub credentials are needed. Upgrading from an older install? Run claude plugin marketplace remove opm first, otherwise you keep pulling from wherever it pointed before. If /opm: commands are not recognised afterwards, run /reload-plugins. If your git reaches GitHub over SSH and that fails, set CLAUDE_CODE_PLUGIN_PREFER_HTTPS=1.

Nothing here phones home and nothing runs a model behind your back.

To check an install, run npx opm-core doctor. It checks Node, Claude Code, the plugin, whether the copied rules are current, the tools the hooks call, and replays each hook offline. It exits 1 only when a check fails.

Platforms

You need Node 18 or later. The installer, hooks and tests run on macOS, Linux and Windows, and CI tests all three. scripts/dev-server.sh and scripts/install-rules.sh are shell scripts, so they run on macOS, Linux and WSL only.

OPM is tested with Claude Code 2.1.273 - 2.1.289. The mod features below need 2.1.287 or later; npx opm-core doctor tells you whether yours has them.

Mod features (Claude Code 2.1.287 or later)

OPM ships a small hooks module (a "mod") beside its settings hooks. It answers some things from code, so they cost no Claude turn and no tokens. Older Claude Code ignores the module and keeps running every settings hook, so nothing breaks; you just do not get the extras. These features are tested with the Claude Code test kit (claude plugin test); they have not yet been run in a live session.

Feature	What it does	On older Claude Code
/opm-status	Prints the open plan ledger (tasks done, current task, last ruling), the milestone position and the git branch. Code answers it; Claude never sees it.	Run npx opm-core status in a terminal. It prints the same thing on any version.
/opm-status --all	Lists every open OPM plan on this machine, newest first (at most 25 rows), from small per-repo snapshots the mod keeps in its local store after each turn. Rows older than 3 days are marked "(stale)"; snapshots are pruned after 14 days.	Not available. Run npx opm-core status in each repo.
Resume line	When a plan ledger is open, session start adds one line naming it and the next task. Nothing is added when no ledger is open.	Works on every version: it comes from the SessionStart settings hook.
Destructive-command hold	Before Claude runs rm -rf on a root-like or out-of-repo path, a force-push to main or master, or git reset --hard, you are asked. Anything but "Run it" denies, and so does a session where nobody can answer, or a failure of the guard itself. Set OPM_GUARD=off to turn it off.	Not available. The settings hooks still block hook bypasses.
Hook-bypass and config checks	The same checks as the block-no-verify and config-protection settings hooks, run in process from one shared rules module: a Bash command that skips git hooks is denied, and an edit that weakens linter, formatter, typecheck or git hook config asks first (nobody answering is a deny). The mod sets OPM_MOD_ACTIVE to its session id, and the two settings-hook scripts step aside only for that session, so each check runs once.	The settings hooks run the same checks.
/opm-report	An opt-in token meter. Off by default; /opm-report --enable starts it and --disable stops it. It records each turn's token use and the skills that ran, keeps 14 days in one local store key capped at 256 KiB, and prints a summary. Nothing is sent anywhere.	Not available.

Commands are typed with a hyphen (/opm-status, not /opm:status). All output is plain text, so it also works in the VS Code chat panel.

What the mod declares, from claude plugin validate --strict .claude-plugin/plugin.json (Claude Code 2.1.289). Review it before you install, as the mods docs recommend:

	Declared
Events	session.start, command.run (opm-status, opm-report), tool.call (Bash, Edit, Write), skill.prompt, turn.complete (one with isAborted=false, one unmatched)
Calls	$.clock.now, $.command.register, $.env.get, $.env.set, $.fs.exists, $.fs.list, $.fs.read, $.fs.stat, $.process.run (via currentBranch), $.session.cwd, $.session.id, $.session.root, $.store.delete, $.store.get, $.store.keys, $.store.set, $.ui.ask, $.ui.log
Environment	reads OPM_ALLOW_CONFIG_EDITS, OPM_GUARD, OPM_HOOKS_DISABLED; writes OPM_MOD_ACTIVE

No network calls and no model calls.

Optional plugins

The marketplace carries one optional plugin beside the core. It is kept out of opm so the core stays small and ships no video toolchain.

🎬 opm-video — turn a spec into a narrated video

Point it at a spec, a brew-idea result, or any document. You get a 1920x1080 MP4 with a neural voice-over and subtitles, plus the editable storyboard and slides. It is a narrated slideshow with fades, not animation.

/opm-video:explainer-video docs/specs/2026-09-17-field-sales-brew.md

Here is the interesting part. The first version of this pipeline was run by hand, with an AI drawing every slide. Fourteen slides cost about 190,000 tokens, 77 tool calls and 22 minutes.

So the AI was taken out of the drawing. Slides are now rendered by script from a kit of nine layouts and 24 icons, filled in from the storyboard like a form. Drawing a slide now costs no AI tokens at all — it is a script, and scripts are free. What is left is writing the storyboard, which is words and genuinely needs judgement, plus hand-drawing the occasional scene no layout can express.

	Hand-drawn by AI	Layout kit
Who draws the slides	An AI, one at a time	A script, all at once
Tokens to draw them	~190,000	none
Reviewing the result	14 images, one by one	one contact sheet, looked at once
Changing one word	redraw the slide	re-render; only that scene rebuilds

It asks before any audio leaves your machine, and offers a fully offline voice if you would rather nothing did. Every fact in the video has to trace back to the source document, and a validator enforces it.

Install it after the core:

claude plugin install opm-video@opm

It needs a headless browser (Chrome, Chromium, Edge or Brave, or CHROME_PATH), and on first build it installs pinned ffmpeg, ffprobe and edge-tts into ~/.opm/explainer-video-tools. Python is needed for the neural voice. The neural voice sends the narration text to Microsoft's cloud speech service through edge-tts; pick the local OS voice and nothing leaves your machine.

Everything in the box

All 13 skills — invoked as /opm:<name>, or picked up automatically when they match the task

The loop

Skill	What it does
using-opm	Injected at session start. Tells Claude to check for an applicable skill before any other action. Its routing table picks the skill by job size, and its "Scale the approach" ladder moves to subagents, parallel work, plans or an offered multi-agent run as the job grows. See docs/using-opm.md.
brew-idea	Four agents argue the idea from product, engineering, skeptic and market angles; a judge ranks features.
brainstorming	No code before the design is agreed. One question at a time, scaled to the size of the job.
writing-plans	Turns an approved spec into bite-sized tasks, each with a failing test, implementation and commit.
executing-plans	Runs a plan with one fresh subagent per task and a reviewer gate after each. Ledger survives compaction.
verification-before-completion	No "done", "fixed" or "passing" without fresh command output as evidence. A full gate (build, types, lint, tests, secrets scan, diff review) runs before a PR or release.
compound-learnings	Captures non-obvious fixes as short docs, and reads them back before planning.

Bigger scope

Skill	What it does
milestone-planning	Multi-week work: roadmap, short STATE digest, phased plans with wave scheduling for parallel subagents.
jump-start	A whole project from one prompt.

Engineering

Skill	What it does
tdd-workflow	Strict red, green, refactor with a "fails for the right reason" gate and an evidence report.

Stack patterns

Skill	What it does
react-patterns	React 18/19 and Next.js App Router: hooks discipline, server and client boundaries, measured performance work.
python-patterns	Modern Python: typing, dataclasses and pydantic at boundaries, async basics, uv, ruff and pytest layout.
flutter-patterns	Flutter and Dart 3: widget composition, state management choice, async and streams, Firebase, tests.

5 reviewer subagents — dispatched automatically when a task matches, or ask for one by name

Agent	Model	Use it for
planner	opus	Turning an agreed spec into an implementation plan
code-reviewer	sonnet	Diff review with a confidence gate and an explicit false-positive list
typescript-reviewer	sonnet	TypeScript and Node specifics: types, async pitfalls, merge readiness
security-reviewer	sonnet	OWASP checks, dependency audits for npm, Python and Dart, Firebase rules
silent-failure-hunter	sonnet	Swallowed errors, empty catches, misleading fallbacks

6 safety hooks — dependency-free scripts that never call a model or the network

Event	Effect
SessionStart	Injects the workflow map on startup, /clear and compaction
PreToolUse on Bash	Denies git commit --no-verify and other hook bypasses
PreToolUse on Edit/Write	Asks before editing lint, format, typecheck or .husky config
PostToolUse on Edit/Write	Records edited files for the Stop hooks
Stop	Formats edited files, runs tsc, ruff or dart, blocks on type errors
Stop	Warns about leftover console.log, print or debugPrint

Set OPM_HOOKS_DISABLED=1 to turn them all off. Per-hook switches are OPM_ALLOW_CONFIG_EDITS, OPM_SKIP_FORMAT and OPM_SKIP_TYPECHECK; see hooks/README.md.

The hooks are guard rails, not a security boundary. docs/threat-model.md lists what they block, what they let through on purpose, and what is out of scope.

Repository layout

.claude-plugin/   plugin.json, marketplace.json
agents/           5 subagents
skills/           13 skills (SKILL.md plus templates/scripts where needed)
plugins/          opm-video, the optional explainer-video plugin
hooks/            hooks.json, 6 dependency-free Node scripts and mod/ (the hooks module)
rules/            copied into <repo>/.claude/rules/opm/ by the installer
bin/              the npx installer
scripts/          install-rules.sh, dev-server.sh
tests/            node --test tests/*.test.js
docs/             specs, plans and design notes

Contributing

See CONTRIBUTING.md for setup, the rules the tests enforce, and how to open a pull request. By taking part you agree to the Code of Conduct.

Licence

MIT. See LICENSE.