Technology
leanwheel-skills, Round Three: Skip the Docs, Keep the Discipline
Round three of leanwheel-skills: a doc-free single-goal lane that keeps the verification discipline, some context-debt paydown, and two proposals I wrote down instead of building.
This is the third post about leanwheel-skills. The first one covered why I built it: a token-lean port of the BMAD planning flywheel that better aligns to Claude Pro's context budget. The second one covered the month after: plugin packaging, a pre-planning layer, autonomous epics.
Since then I've kept running it daily on real projects. Here's what changed - including two ideas I wrote down and deliberately did not build.
Not everything is a project
A recent chat with a coworker led me to a realization: leanwheel assumed every piece of work lived inside a project. Every lane started from docs/prd.md and docs/architecture.md, every story traced back to an epic, every change updated the docs. That's part of what led me to BMAD to begin with. As a prolific documentarian, I loved all the documentation built and consumed by BMAD. That's the right shape for building a large project from nothing. It's the wrong shape for most of what a working week actually looks like: a fix in a coworker's repo, a one-off script in a folder that will never have a PRD, a quick change in a fresh clone you'll touch exactly once.
For that work, the honest answer used to be "leanwheel has nothing for you," and I'd freestyle it. And freestyling is exactly where agentic coding quietly goes wrong - no requirements pass, no plan you approved, no verification gate, just vibes and a diff. And a fix... and another fix... and another... As Bon Jovi said... "Livin' on a Prayer!"
So the new dev-single-goal skill is a doc-free entry lane. Drop into any folder, state one goal, and it runs the same core loop the project lanes use - it just refuses to bring the paperwork along:
| Keeps | Deliberately drops |
|---|---|
| Grilling for intent before any plan exists | PRD / architecture prerequisites |
| A written, approved plan with testable ACs | Doc-update obligations after the work |
| Build & Test Gate: verify by running | GitHub issue/milestone tracking |
| Inline review passes (correctness, edges, over-engineering) | The deferred-items ledger |
| HALT conditions instead of pushing through | Any new files in your repo (the spec self-ignores in git) |
The part I care most about is the grilling. For anything stateful (a state machine, a multi-step flow, async lifecycle, real failure handling), the skill enumerates a Behavior Contract before writing the plan. In that contract? Every flow including the alternate paths, legal and illegal state transitions, edge cases (empty inputs, duplicate actions, partial failure, retries), and the invariants that must always hold. Then a Clarification Gate splits what it found into two piles: ambiguities with one sensible default get recorded as assumptions, and material forks (which state wins on conflict? is partial success allowed?) stop the whole thing and ask me. It never writes a speculative plan around an unresolved fork.
That said, the skill scales the ceremony to the goal. A simple fix gets a one-line contract or none at all - the instruction in the skill is literally "do not manufacture ceremony," and simple goals with no real ambiguity skip straight to the plan. Rigor where the state lives, nothing where it doesn't.
At the other end, done still means the same thing it means in the project lanes: the toolchain ran and came back green (swift test, npm run build && npm test, pytest, whatever the folder detects), every invariant has evidence in the form of a test or a cited assertion, and a red build is never reported as done.
Building this clarified something for me. The planning docs were never the point of leanwheel - the discipline was. The docs are just where the discipline lives when the work is big enough to need shared memory. dev-single-goal is proof the discipline detaches cleanly from the doc tree, and the README now leads with both quickstarts - project and single-goal - as equal entry points.
Paying down context debt
The framework kept growing, and the token math that justifies its existence needed defending. Three changes since July:
- CLAUDE.md went lazy. The project-conventions file had bloated to 69k characters, loaded into every session whether relevant or not. It's now split into scoped files that load on demand, with 4.6k characters always-loaded. Same guidance, about 93% less standing overhead.
- epics.md stopped growing without bound. The new epic-archive operations collapse a closed epic's story detail down to a summary row and cut shipped releases out to archive files, so the file every planning session reads stays proportional to active work.
- A second routing axis: effort. Model routing (Haiku for mechanical doc sync, Opus for Swift dev) has been in place for a while. The docs-sync agent is now also pinned to low reasoning effort, because grounded-in-diff doc writing doesn't benefit from deep thinking. So there are two static knobs per task now: which model, and how hard it thinks. Cheap work should be cheap on both.
Verify by running, not by reading
One principle kept showing up in otherwise unrelated changes: if the agent didn't observe it happen, it didn't happen.
The iOS simulator automation got rebuilt around deep links instead of coordinate tapping - drive the app to a known screen deterministically, then screenshot and assert. In fairness, the first version wasn't right either: adopting it on a real project surfaced five bugs, including two silent failures that only appeared under real use. The wrapper script also now refuses to launch a stale build, because a screenshot of last week's binary is worse than no screenshot.
The same principle hit the flywheel's own bookkeeping. The epic context cache (a small file that saves each story from re-reading the planning docs) turned out to be exactly the kind of thing an agent will claim to have written without writing. It's now a verifiable output: the orchestrator checks the file exists and isn't a stub before proceeding. The gates that actually work are file-existence checks, not vibes. Same story with subagent delegation - "I'll now delegate this to the reviewer" is narration, not delegation, so the skills now require the explicit Agent tool call.
Two smaller ones in the same spirit: the review pass gained a simplicity ladder and a deletion lens (every review now ends with "here's what could be deleted" or "lean already"), and a real project's epic retrospective fed its findings back into the framework - the flywheel improving the flywheel, which was always the goal.
Two ideas I wrote down instead of building
The repo now has a Discussions tab, and the two most interesting things in it are proposals I haven't implemented. That's deliberate. Writing the assessment first is a lot cheaper than writing the code first, and both of these are big enough to be expensive to get wrong.
Twin native development
Discussion #17 proposes adding a third platform guidance surface - native Android with Kotlin and Jetpack Compose - and on top of it, a twin-development mode: the Apple and Android versions of the same app built side-by-side as two fully native codebases driven by one shared spec.
The reason this might not be crazy is that agents flip the cost structure of "write it twice." Cross-platform layers (KMP, React Native, Flutter) exist because writing two native apps was too expensive for humans - and in exchange they reintroduce interop quirks, bridge debugging, and a third toolchain. But with agents doing the implementation, the expensive artifact isn't the code anymore. It's the spec: the Behavior Contract, the edge cases, the design tokens. leanwheel already treats the spec as the first-class deliverable, and the Behavior Contract is already written in platform-neutral vocabulary (flows, states, invariants). Two dev agents implementing one contract natively, with a parity pass at review, may honestly be cheaper and safer than one agent translating idioms across a bridge.
The proposal also forces a product question early that I've seen discovered too late: if one user's data needs to roam between an iPhone and an Android tablet, platform-native sync is a dead end (CloudKit has no Android client), and you're signing up for a shared backend before Android work even starts. Better to ask that at PRD time than mid-epic.
Prototype-first design, parked
Discussion #12 came out of a real post-mortem: on a recent project, early SwiftUI mockups got built and then largely thrown away once the real data model arrived. The durable outputs were the flow map and the design spec - the prototype code was not. The costly mistake was high fidelity arriving before the information architecture had hardened.
Claude Design (Anthropic's prototyping tool) looks like a fix: click-testable wireframes to falsify the flow map before any spec gets written. So I assessed it against every surface of the framework and gave each one a verdict: integrate, reject, or defer until the capability actually exists. Every capability claim is sourced, and the ones I couldn't verify are marked as exactly that. And then I parked the whole thing, because the product is a research preview and the open question is whether click-testing my own wireframes solo actually beats the text-based IA walk the UX skill already does.
The assessment cost an evening. Building it into five skills and unwinding it later would have cost a lot more. If you have opinions on either proposal, the discussion threads are open - that's genuinely what they're for.
The repo is at github.com/rterakedis/leanwheel-skills. Still MIT licensed. Comments welcome!