{"id":49359506,"url":"https://github.com/mopeyjellyfish/flywheel","last_synced_at":"2026-04-27T15:37:54.738Z","repository":{"id":352857477,"uuid":"1214346423","full_name":"mopeyjellyfish/flywheel","owner":"mopeyjellyfish","description":"flywheel: each pass adds energy to the next","archived":false,"fork":false,"pushed_at":"2026-04-21T11:40:06.000Z","size":657,"stargazers_count":1,"open_issues_count":1,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-04-21T13:32:11.574Z","etag":null,"topics":["ai","claude-code","codex","plugin","skills"],"latest_commit_sha":null,"homepage":"","language":"JavaScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/mopeyjellyfish.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2026-04-18T12:57:24.000Z","updated_at":"2026-04-21T11:37:32.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/mopeyjellyfish/flywheel","commit_stats":null,"previous_names":["mopeyjellyfish/flywheel"],"tags_count":null,"template":false,"template_full_name":null,"purl":"pkg:github/mopeyjellyfish/flywheel","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mopeyjellyfish%2Fflywheel","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mopeyjellyfish%2Fflywheel/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mopeyjellyfish%2Fflywheel/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mopeyjellyfish%2Fflywheel/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/mopeyjellyfish","download_url":"https://codeload.github.com/mopeyjellyfish/flywheel/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mopeyjellyfish%2Fflywheel/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":32343565,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-04-26T23:26:28.701Z","status":"online","status_checked_at":"2026-04-27T02:00:06.769Z","response_time":128,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["ai","claude-code","codex","plugin","skills"],"created_at":"2026-04-27T15:37:52.749Z","updated_at":"2026-04-27T15:37:54.733Z","avatar_url":"https://github.com/mopeyjellyfish.png","language":"JavaScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Flywheel\n\nA workflow skillset for turning repo work into a flywheel of recoverable energy.\n\n## Install\n\nInstall Flywheel with the `skills` CLI:\n\n```bash\nnpx skills add mopeyjellyfish/flywheel --global --skill '*' --agent claude-code --agent opencode --yes\n```\n\nThen go to a project where you want Flywheel to help and run setup:\n\nClaude Code:\n\n```text\n/fw:setup\n```\n\nOpenCode:\n\n```text\nfw:setup\n```\n\nSetup reads that project, checks the tools and workflow surfaces it actually\nuses, reports missing dependencies, and prepares Flywheel to guide the first\nreal task there.\n\nAfter setup, start normal work with:\n\nClaude Code:\n\n```text\n/fw\n```\n\nOpenCode:\n\n```text\nfw\n```\n\n## Philosophy\n\nEach unit of development work should make the next one faster.\n\nTraditional development leaks momentum. Ideas stay fuzzy for too long,\nimplementation starts before the path is clear, review happens after the risky\ndecisions are already made, and useful lessons disappear into chat history, PR\ncomments, or memory.\n\nFlywheel keeps the loop compact:\n\n- shape the change before coding\n- work from a reviewed plan\n- review the diff before commit\n- finish the branch cleanly\n- spin durable lessons back into the repo\n\nIn Flywheel, docs are stored energy. Plans, solutions, workflow rules, rollout\nnotes, and user corrections are not side artifacts. They are repo knowledge\nthat later work can recover instead of rediscovering.\n\nThat is the point of the product: finish the current task and make the next\none faster.\n\n## Workflow\n\n```text\nshape -\u003e work -\u003e review -\u003e optional spin -\u003e commit -\u003e repeat\n```\n\n`fw` routes a task into the earliest useful stage. Use a specific stage when\nthe next step is already clear.\n\n| Command | Purpose |\n| --- | --- |\n| `fw` or `fw:start` | Route a repo task into the right stage. |\n| `fw:shape` | Clarify an idea, compare options, write a plan, or deepen an existing plan. |\n| `fw:work` | Implement the planned change against repo truth. |\n| `fw:review` | Review the finished diff for bugs, regressions, missing tests, and readiness gaps. |\n| `fw:spin` | Capture durable lessons in `docs/solutions/` when the work teaches something reusable. |\n| `fw:commit` | Verify readiness, commit, push, and create or refresh the PR. |\n\nCommon starts:\n\n- Vague idea or new feature: `fw`\n- Known scoped change: `fw:shape`\n- Bug with an unclear cause: `fw:debug`\n- Architecture or pattern decision: `fw:architecture-strategy` or `fw:pattern-recognition`\n- One bounded pass through the remaining stages: `fw:run`\n\nUse the host prefix when required: `/fw:work` in Claude Code and `fw:work` in\nOpenCode.\n\n---\n\n## Development\n\nEverything below is for working on Flywheel itself.\n\n### Local development\n\nFrom this checkout:\n\nClaude Code:\n\n```bash\nmake install/claude\n```\n\nCodex:\n\n```bash\nmake install/codex\n```\n\nRestart the host session after either command finishes.\n\nTo install the Flywheel skills through `npx skills` for non-Codex skills-CLI\nhosts:\n\n```bash\nmake install/skills/global\n```\n\nDo not use this as the Codex install path. Codex reads standalone global skills\nas unnamespaced commands such as `$start`; `make install/codex` removes those\nstandalone Flywheel skills and installs the namespaced plugin surface instead.\n\nTo install them at project scope in another repo:\n\n```bash\ncd /path/to/target-repo\n/path/to/flywheel/scripts/skills-install.sh --scope project --source local\n```\n\nProject scope in the `skills` CLI writes to the current directory's `skills/`\ntree. Inside the Flywheel repo that path is the authored product source, so the\nrepo-local project target validates the local source and exits without running\n`skills add` back into the same tree. Local-source targets fail instead of\nfalling back to the published package when this checkout does not expose\n`skills/*/SKILL.md`.\n\n`make install/codex` now refreshes the local Flywheel plugin install shape,\nturns on the experimental Codex hooks feature, and merges the Flywheel Bash\nguardrail into `~/.codex/hooks.json`.\n\nFrom another checkout or worktree:\n\nClaude Code:\n\n```bash\nmake install/claude/force-source\n```\n\nCodex:\n\n```bash\nmake install/codex/force-link\n```\n\nFor a project-scoped Claude install from this checkout:\n\n```bash\nmake install/claude/refresh/project\n```\n\nTo remove Flywheel from both hosts and retest a clean local install:\n\n```bash\nmake uninstall/all\n```\n\nThat cleanup now removes host-specific plugin installs plus Flywheel `npx skills`\nglobal installs, including stale global skill directories whose lock entries are\nmissing. From this repo root it treats project scope as source-tree metadata and\nnever deletes the authored `skills/` files.\n\n### Validation\n\n```bash\nmake verify\nmake doctor\nmake validate\nnode scripts/flywheel-doctor.js --host codex --codex-session-smoke\nnode scripts/flywheel-doctor.js --host claude --smoke\n```\n\n`make verify` is the full plugin verification pass for this repo: doctor smoke\nchecks plus eval-suite validation. In broad verification it validates repo\npackaging for both hosts, requires live smoke for the hosts currently enabled\nfrom this checkout, and skips the Claude live invocation when this repo is not\ncurrently installed in Claude or Claude's API credentials are invalid. Use\n`make install/claude` followed by `node scripts/flywheel-doctor.js --host claude --smoke`\nwhen the installed Claude path itself must be proven.\n\nFor side-by-side local comparisons between Codex and Claude Code:\n\n```bash\nnpm --prefix tools/evals install\nnpm --prefix tools/evals run doctor\nnpm --prefix tools/evals run compare -- --suite flywheel\n```\n\nSetup and troubleshooting notes:\n\n- [compatibility.md](docs/setup/compatibility.md)\n- [troubleshooting.md](docs/setup/troubleshooting.md)\n\n### Repository layout\n\n- `.agents/plugins/marketplace.json` - Codex marketplace manifest for this repo\n- `.codex-plugin/plugin.json` - Codex plugin manifest used directly and by the repo marketplace\n- `.claude-plugin/plugin.json` - Claude plugin manifest\n- `.claude-plugin/marketplace.json` - Claude marketplace manifest for this repo\n- `.flywheel/config.local.example.yaml` - local config template\n- `hooks/` - shared hook policy script and Claude plugin hook pack\n- `skills/` - shared Flywheel workflow skills\n- `docs/setup/` - compatibility and troubleshooting notes\n- `docs/solutions/` - searchable knowledge captured by `spin`\n- `scripts/` - repo-local doctor, refresh, and eval helpers\n- `tools/evals/` - isolated live-eval workspace\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmopeyjellyfish%2Fflywheel","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fmopeyjellyfish%2Fflywheel","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmopeyjellyfish%2Fflywheel/lists"}