leanwheel-skills, a Month In: A Plugin, a Pile of New Skills, and Better Token Math

A few weeks ago I wrote about building leanwheel-skills, a stripped-down port of the BMAD planning flywheel that fits inside Claude Pro's context budget. The pitch was simple: keep the structured PRD → architecture → epics → stories → dev → review loop, cut the overhead that doesn't earn its token cost, come out around 55% lighter.

That was the starting point. I've been using it on real projects since, and it grew. A lot. The interesting part is that it got noticeably more capable while staying lean - the token savings actually went up, not down, even as I added whole new phases. Here's what changed.

First: it's a plugin now

The original post told you to clone the repo and pull it into each session with /add-dir, maybe wired as a startup hook. I'll be honest: that never worked reliably. The Claude Code app doesn't consistently auto-load skills from a session's additional directories, so I'd start a project, reach for /prd, and get nothing.

So I packaged it as a proper Claude Code plugin. Two lines, once, and the skills are in every session from then on:

/plugin marketplace add https://github.com/rterakedis/leanwheel-skills
/plugin install leanwheel@leanwheel

No per-project setup, no /add-dir, no settings hook to forget. (If you'd rather track main directly, you can still clone and symlink into ~/.claude/skills/ - the repo's installation guide covers that.) I also went back and updated the install section of the first post so nobody follows the old, broken instructions.

A front end for the flywheel

The original leanwheel assumed you already knew what you were building. You ran /prd, described the product in one prompt, and off you went. That's a real gap when the idea isn't formed yet, which for hobby projects is most of the time.

So there's now a pre-planning layer:

• /product-brief brainstorms with you if you don't have a formed idea, then distills the result into docs/project/brief.md - which /prd reads automatically instead of asking you to describe the product cold.
• /forge-idea adversarially pressure-tests an idea through persona cross-examination (a competitor, a buyer, a support engineer) until it either Hardens, gets Killed, or at least gets Clearer.
• /research runs cited, web-grounded research - technical, domain, or market - so planning decisions rest on real external facts instead of the model's assumptions.

And sitting above all of it is /next, which is the command I use the most now. It detects where a project is (purely from file existence and story frontmatter, so it's near-zero-token) and tells you the single next thing to run. "What do I do now?" is the question you actually have at 9pm on a side project, and /next answers it without you holding the whole lifecycle in your head.

Autonomy, with model routing

The biggest behavioral change is /epic-flywheel. The first post described /story-flywheel, which runs the create → dev → review loop for one story in isolated subagents. /epic-flywheel sits on top of that and drives an entire epic from "not started" to "implemented, reviewed, and verified together," committing after each phase, auto-advancing on green stories, and stopping at an Epic Boundary Gate that runs the whole-project build, the cumulative eval suite, and an invariant sweep before it lets the epic close.

The part I didn't expect to matter as much as it does: model routing. Each phase runs on the cheapest model that can do it well.

• Story creation and code review run on Sonnet.
• Documentation maintenance runs on Haiku (more on that below).
• Opus is reserved for the passes where a cheaper model's failed build loops would cost more than one accurate pass - Swift dev work, mostly.

Because the phases run in throwaway subagent contexts, the orchestrating thread only ever holds about 15-20K tokens of the whole project. The heavy reads - PRD, architecture, story files - live and die in disposable windows and never pile up in the main conversation.

Verification stopped being an afterthought

This is where leanwheel quietly turned into something I trust more than the manual loop. A bunch of the new skills exist to catch problems before I have to:

• A closed design loop. /create-story now extracts a per-story Design Contract (tokens, component specs, required states) from the UX docs. /dev-story implements against it and runs /design-verify, which builds the thing and screenshots it in light and dark, at different type sizes and widths, before review. /code-review runs a design-compliance pass and keeps an inventory of built components so later stories reuse them instead of reinventing them.
• A cumulative eval net. Eval cases seeded from acceptance criteria accumulate across the whole project. They run as plain shell commands (zero model tokens), and a failing case on story 3.4 that used to pass is a regression that blocks the story, exactly like a red build.
• /e2e-tests retro-fits automated API/E2E tests onto features that already exist - brownfield code, or anything shipped before the eval net did - and folds each suite into that same regression net.
• /harvest-findings closes the manual-test loop. You jot findings as bullets under each test scenario, and it triages them by kind (bug / tweak / enhancement / question) and turns the in-scope fixes into a single remediation story. It never reopens a story that's already done - the fix always lands as new work.
• A pre-mortem gate. /check-readiness now ends by assuming the project shipped and failed at month three, then works backwards to the specific causes in your plan. Unaddressed ones become blockers with mitigation stories scheduled before the first line of code.
• /doc-review reviews a planning doc as writing - structure, prose, and an adversarial pass for gaps and contradictions. Code got adversarial review from day one; the docs the model re-reads every session didn't, and tightening them saves tokens for the life of the project.

Platform brains

leanwheel learned two platforms in depth. /setup scaffolds sectioned best-practice reference docs into docs/setup/swift/ (state management, concurrency, testing, anti-patterns, plus iPad- and Mac-specific files) or docs/setup/web/ (CSS design system, accessibility, SEO, plus Astro or Hugo specifics), and the dev and review skills read the relevant sections before they act.

Two things keep that guidance honest:

• /refresh-swift and /refresh-web research current patterns from primary sources (Hacking with Swift, Apple's WWDC samples, web.dev, MDN, the Astro and Hugo docs) and update the reference files so the guidance doesn't rot.
• /swift-audit and /web-audit scan the whole project - planning docs, story files, and source - against that guidance and produce a triaged remediation file, one acceptance criterion per finding, ready to hand to /dev-story.

There's even an /appstore-preflight now that audits an iOS project against App Store submission requirements before you waste a review cycle. I built this one in the hope of preventing App Store rejections.

Living documentation, off the expensive model

The one I'm most quietly pleased with is /docs-sync. As code changes, it grows the human-facing stand-up, operations, and database guides, and at the epic boundary it promotes durable architectural learnings up into docs/architecture.md. It runs automatically after dev and review passes.

The trick is that it runs on Haiku. Documentation maintenance is mechanical, grounded-in-the-diff writing - it does not need a reasoning-heavy model, and pinning it to the cheapest one means the docs stay current without ever spending Opus tokens on prose. That's the whole philosophy in one skill: match the model to the actual difficulty of the work.

(And if you have an older leanwheel project from before any of this existed, /upgrade-project detects what's missing - hooks, stubs, eval directories, CLAUDE.md sections - shows you a plan, and syncs it without clobbering anything you've edited by hand.)

The token math, recalculated

Here's the part I was nervous about. Both leanwheel and upstream BMAD grew since the first post. BMAD's v6 rewrite roughly tripled its per-run payloads and made the activation ceremony bigger. Leanwheel grew too - the build gates, the contracts, the eval net, the flywheel orchestration are all real additions. So did the savings survive?

They did. They actually improved. I re-measured against BMAD v6.10.0 across a representative 12-story project (3 epics, 4 stories each), counting the bytes of every file each skill loads:

So: roughly a third of the tokens, up from "about 55% lighter" in the first post. And that leanwheel total buys more than the BMAD total - it includes the Behavior Contract pass, the Design Contract extraction, invariant verification, and the inline adversarial review, none of which upstream's equivalent phases run.

A few of the new layers cost nothing at all, by design, so they don't even show up in the table: the guardrail hooks are pure bash, the eval suite runs as shell commands, GitHub label transitions moved into a script, and the observability ledger is a JSONL append that never gets read back into context.

What I keep relearning

The first post ended on the idea that most workflow overhead isn't load-bearing - you only find the slack when you're forced to count tokens. A month of adding things back taught me the other half of that lesson: capability and cost aren't the same axis.

Almost everything I added made the workflow more capable while spending fewer tokens, because the additions were the right kind - a shell hook instead of a remembered rule, a Haiku subagent instead of an Opus read, a cached epic context instead of a re-read PRD, a verification pass that prevents an expensive re-fix loop. The stuff that makes an AI workflow good and the stuff that makes it cheap turn out to point in the same direction more often than I'd have guessed. You just have to be willing to measure.

The repo is at github.com/rterakedis/leanwheel-skills. Still MIT licensed. Comments welcome!