flywheel

Bootstrap, maintain, and continuously improve a coding-agent workspace so each session adds momentum the next session inherits. Workspace-level meta-skill for Claude Code, Codex CLI, or any agent runtime that loads Agent Skills.

What it does

Three modes:

• bootstrap — first-time setup. Walks you through identity (USER.md), workspace shape, single vs multi-agent, optional issue tracker, heartbeat cadence. Then writes SOUL.md, USER.md, AGENTS.md, MEMORY.md, and (optionally) agents/inbox/, agents/group-chat.md, memory/agents/shared-agent-contract.md, docs/sops/bug-risk-playbook.md using inline templates.
• heartbeat — periodic audit. Light flavor (read-only findings report, daily) or deep flavor (interactive cleanup, weekly). Surfaces stale folders, cross-project bleed, skill candidates, automation hygiene, dead skills nobody invokes.
• self-improvement — three sub-procedures: bug-risk playbook updates (when something keeps biting), third-strike skill rule + scaffolding (when a workflow has fired three times), workflow-plugin packaging (when a skill needs scripts + hooks + automations bundled into a plugin).

Plus: explicit proactivity rules (act-without-asking / ask-before / stop-and-write-handoff), multi-agent coordination conventions, and a workflow-plugin threshold for going beyond a skill into a full bundle.

Install

1. Copy this folder into your project at .agents/skills/flywheel/ (Codex CLI / general) or .claude/skills/flywheel/ (Claude Code).
2. Reference it from your project's AGENTS.md or CLAUDE.md if you want it loaded explicitly. Otherwise it triggers via description match.

Schedule it

Once installed, set up two recurring runs:

• Daily light heartbeat:

  Run the flywheel skill in mode: heartbeat, light flavor. Write the report to heartbeat-reports/. DM me only if something is critical.

• Weekly deep cleanup:

  Run the flywheel skill in mode: heartbeat, deep flavor. Walk me through findings interactively.

For Codex CLI: configure as scheduled tasks. For Claude Code: same. The skill is the same in either runtime.

Files

• SKILL.md — the skill itself (this is what the agent loads first)
• references/bootstrap.md — first-time workspace setup procedure with inline file templates
• references/heartbeat.md — 9-section audit checklist + report format + scheduled run recipes
• references/self-improvement.md — three procedures: bug-risk playbook, third-strike skill rule, workflow-plugin packaging

Scope

This skill is for multi-agent local workspaces — Claude Code, Codex CLI, or both running in one project with per-agent runtime memory and a shared contract.

For Zo Computer (single cloud agent, no inbox/group-chat patterns), see the companion repo: dreaming.

Conventions

The skill follows Matt Pocock's Agent Skills conventions — frontmatter with name + description, body opens with purpose, references one level deep, ~100-line SKILL.md with deeper procedures in references/. Description triggers carry the keyword phrases the user actually says ("tend the workspace", "run flywheel", "audit the workspace", "set up the workspace", "run a heartbeat").

License

MIT — use as you like. If you adapt it, please share back what worked.

Author

Jeff Kazzee — @jeffkazzee