fw

Flywheel

A workflow skillset for turning repo work into a flywheel of recoverable energy.

Install

Install Flywheel with the skills CLI:

npx skills add mopeyjellyfish/flywheel --global --skill '*' --agent claude-code --agent opencode --yes

Then go to a project where you want Flywheel to help and run setup:

Claude Code:

/fw:setup

OpenCode:

fw:setup

Setup reads that project, checks the tools and workflow surfaces it actually uses, reports missing dependencies, and prepares Flywheel to guide the first real task there.

After setup, start normal work with:

Claude Code:

/fw

OpenCode:

fw

Philosophy

Each unit of development work should make the next one faster.

Traditional development leaks momentum. Ideas stay fuzzy for too long, implementation starts before the path is clear, review happens after the risky decisions are already made, and useful lessons disappear into chat history, PR comments, or memory.

Flywheel keeps the loop compact:

• shape the change before coding
• work from a reviewed plan, using TDD for behavior-bearing feature work and bug fixes unless an explicit exception applies
• review the diff before commit
• finish the branch cleanly
• spin durable lessons back into the repo

In Flywheel, docs are stored energy. Plans, solutions, workflow rules, rollout notes, and user corrections are not side artifacts. They are repo knowledge that later work can recover instead of rediscovering.

That is the point of the product: finish the current task and make the next one faster.

Workflow

shape -> work -> review -> optional spin -> commit -> repeat

fw routes a task into the earliest useful stage. Use a specific stage when the next step is already clear.

Command	Purpose
fw or fw:start	Route a repo task into the right stage.
fw:shape	Clarify an idea, compare options, write a plan, or deepen an existing plan.
fw:work	Implement the planned change against repo truth.
fw:tdd	Run strict red-green-refactor for behavior-bearing implementation slices.
fw:review	Review the finished diff for bugs, regressions, missing tests, and readiness gaps.
fw:spin	Capture durable lessons in docs/solutions/ when the work teaches something reusable.
fw:commit	Verify readiness, commit, push, and create or refresh the PR.

Common starts:

• Vague idea or new feature: fw
• Known scoped change: fw:shape
• Hard bug, stack trace, or performance regression with unclear cause: fw:debug
• Durable decision, ADR, or terminology conflict: fw:decision
• Architecture improvement, boundary, or pattern decision: fw:architecture-strategy or fw:pattern-recognition
• One bounded pass through the remaining stages: fw:run

Use the host prefix when required: /fw:work in Claude Code and fw:work in OpenCode.

---

Development

Everything below is for working on Flywheel itself.

Local development

From this checkout:

Claude Code:

make install/claude

Codex:

make install/codex

Restart the host session after either command finishes.

To install the Flywheel skills through npx skills for non-Codex skills-CLI hosts:

make install/skills/global

Do not use this as the Codex install path. Codex reads standalone global skills as unnamespaced commands such as $start; make install/codex removes those standalone Flywheel skills and installs the namespaced plugin surface instead.

To install them at project scope in another repo:

cd /path/to/target-repo
/path/to/flywheel/scripts/skills-install.sh --scope project --source local

Project scope in the skills CLI writes to the current directory's skills/ tree. Inside the Flywheel repo that path is the authored product source, so the repo-local project target validates the local source and exits without running skills add back into the same tree. Local-source targets fail instead of falling back to the published package when this checkout does not expose skills/*/SKILL.md.

make install/codex now refreshes the local Flywheel plugin install shape, enables Codex hooks and plugin_hooks, and uses the Codex-specific hook pack bundled at hooks/codex-hooks.json. It removes old user-level Flywheel hook entries while preserving unrelated hooks.

From another checkout or worktree:

Claude Code:

make install/claude/force-source

Codex:

make install/codex/force-link

For a project-scoped Claude install from this checkout:

make install/claude/refresh/project

To remove Flywheel from both hosts and retest a clean local install:

make uninstall/all