flywheel

name

flywheel

description

Bootstrap, maintain, and continuously improve a coding-agent workspace so each session adds momentum the next session inherits. Sets up the shared brain (SOUL/USER/AGENTS/MEMORY plus agents inbox + group chat), runs periodic heartbeats to surface stale folders and skill candidates, captures lessons into a bug-risk playbook (self-healing), and proactively packages repeated work patterns into skills, hooks, commands, or workflow plugins. Use when starting a new workspace, when something keeps biting and needs to land in a playbook, when a workflow has repeated three times, or when the user says "spin up the flywheel", "run flywheel", "audit the workspace", "tend the workspace", "set up the workspace", or "run a heartbeat".

Flywheel

Each session adds momentum the next session inherits. Make every session improve the next one. When something breaks, capture the lesson somewhere that survives the session restart. When a workflow repeats, package it. When the workspace gets crufty, surface the cruft and decide per item.

Three modes. Pick the right one based on the workspace state and the request.

Modes

bootstrap — first time in a workspace

Use when SOUL.md, USER.md, AGENTS.md, or MEMORY.md are missing at the workspace root, or when the user says "set up the workspace" / "bootstrap the brain".

Procedure: explore → present → confirm → write. Full steps and file templates in references/bootstrap.md.

heartbeat — periodic audit

Use when the user says "run the heartbeat" / "audit the workspace", or when invoked by a scheduled task. Two flavors: light (read-only findings report) and deep (interactive cleanup with archive/delete/keep prompts per item).

Checklist and report format in references/heartbeat.md.

self-improvement — capture, extract, package

Use after a slice ends, after a bug, after a confusing handoff, or when the user says "this happened again" / "package this into a skill" / "make this a plugin".

Bug-risk playbook updates, the third-strike skill rule, and the workflow-plugin packaging procedure are all in references/self-improvement.md.

Proactivity rules

The workspace compounds when the agent acts on internal hygiene without asking. Some actions still require permission.

Act without asking

• Read all startup files (SOUL/USER/AGENTS/MEMORY/today's daily memory, agent inbox, shared contract).
• Create today's memory/YYYY-MM-DD.md if missing.
• Append work, decisions, blockers, and test results to today's daily memory.
• Create agents/inbox/<your-agent>.md if missing and you're a named agent.
• Run the heartbeat and write the report to heartbeat-reports/.
• Scan for stale items, unread inbox messages, and repeated workflows. Surface them.

Ask before

• Deleting any file or folder. Require the user to type the literal name to confirm.
• Archiving (moving) anything. Show source and destination paths first.
• Modifying SOUL.md, USER.md, or AGENTS.md after the initial bootstrap.
• Modifying or retiring an existing skill, hook, command, or workflow plugin.
• Creating a new SOP, skill, hook, command, or plugin — show the draft first.
• Pushing to a remote, opening a PR, or any action visible outside the local machine.

Stop and write a handoff when

• Two SOPs or skills contradict each other for the current task.
• A change would require overwriting another agent's work.
• A safety boundary is unclear (private info, external action, destructive command).
• Required context is missing and just-in-time discovery doesn't surface it.
• The user's instruction is ambiguous in a way that affects which agent should pick it up.

The handoff goes in today's memory file plus an entry in the relevant agent's inbox (agents/inbox/<agent>.md).

Multi-agent coordination

When more than one named agent operates in this workspace (Codex, Claude, Ralph, Cody, etc.):

• Each agent has its own runtime memory at memory/agents/<agent>.md. Cross-agent facts belong in MEMORY.md.
• 1:1 handoffs go to agents/inbox/<recipient>.md.
• Broadcasts affecting more than one agent go to the top of agents/group-chat.md.
• A shared contract at memory/agents/shared-agent-contract.md defines universal rules every agent follows.
• After consuming a 1:1 message, move it under ## Read at the bottom of the inbox file or delete with a one-line memory note.
• Subagents (spawned via the Task tool for bounded work) follow the lifecycle: spawn → collect → close. Idle subagents are leaks. Before ending a session, all completed subagents should be closed.

Skill promotion rule (third strike)

A workflow earns a skill on its third occurrence. First = exploration. Second = coincidence. Third = pattern.

This rule prevents .agents/skills/ from filling with speculative scaffolding nobody invokes. Detection and SKILL.md scaffolding procedure in references/self-improvement.md.

Workflow plugin threshold

A workflow becomes a plugin (skill + scripts + hooks + automations bundled together) when all three are true:

1. It has fired more than three times.
2. It coordinates multiple files, tools, or agents.
3. It would benefit from deterministic scripts (saving tokens) or hooks (enforcing invariants automatically).

A skill alone is instructions. A plugin is a skill plus the deterministic infrastructure that makes it self-enforcing. See references/self-improvement.md for the bundling procedure.

Done means

• The workspace has a discoverable shared brain that survives session restarts.
• The most recent heartbeat report is current (within the configured cadence).
• Lessons from the last session landed in bug-risk-playbook.md or the relevant skill — not just in chat.
• Any third-strike workflow detected this session has either become a skill, a plugin, or been explicitly rejected with a note.
• Al