orchestration OS · Beta / testflight · v0.5.0
When context is summarized or a thread is replaced, the alignment record from the last dispatch remains trapped in the old scrollback, while every fresh session must rebuild governing constraints from the stream where settled decisions already sit beside tool output and abandoned runs. wavves captures that alignment state as versioned files under wavves/, turning operator intent into packets before runners start, persisting disk gate captures and rotation handoffs beside each lane while hydrating every successor from the home record when a fresh thread opens.
The player in the header is a recorded walk of a live wavves/ home so you can see INDEX and lane folders, then one campaign (DMP) down through waveset, dispatch, findings, gate-captures, locked decisions and a rotation handoff. The same cut is on YouTube.
MAGAT Analyzer experiments stay as MATLAB objects until magatfairy writes them to HDF5, and that convert ran under wavves so MATLAB Engine and bundled MAGAT classes stayed on disk, with spatial/no-FID flags recorded beside the lane. Documentation and usage live on the public magatfairy page.
After listing, install from the Cursor plugin marketplace:
/add-plugin wavves
Or copy this repo to ~/.cursor/plugins/local/wavves/, then reload plugins.
Type slash commands in Cursor chat. Start with /wavves for most work, like /poteto-mode in pstack.
| Command | Use it when |
|---|---|
/wavves | Default entry. Reads your request, picks a playbook, runs the leaf skill. |
/wavves-init | Home setup only. First time in a repo or repair the standing home. |
/charter | Charter a bounded lane, dispatch background waves, multi-repo commit plans. |
/mod-check | Adversarial parallel check; scoped verdict (blocks_w2…blocks_w5) plus recommended_actions. |
/mod-decide | Lock open product/design calls after a check return; sync authority surfaces on complete. |
/layover | Read-only multi-repo workspace preflight audit. Cloud agents stay per-repo; you still open one cloud thread by hand. |
/set-key | Terminal.app paste helper for a server-only env secret (default klosr GOOGLE_MAPS_API_KEY). Never echoes the secret. |
/shrug | Thin alias for emoji shrug. Bare /shrug → AUTH-10 proceed. /shrug plus a closed all-standing phrase → proceed-all-standing. Never widens bare shrug. |
/mod-rotate | Rotate the moderator to a fresh thread with a handoff file. |
/mod-kick | Cross-environment exit: publish lane allowlist to a kick-target remote and emit a paste for another machine or modality. |
/wavves routes to| Playbook | Routes to | For |
|---|---|---|
| bootstrap | /wavves-init | First time in repo, no wavves/ home yet |
| charter-lane | /charter | Bug fix, audit, refactor, flaky CI, overnight lane |
| check | /mod-check | Adversarial review of a landed spec or plan before the implementation plan |
| decide | /mod-decide | Lock open calls after a check return, before BUILD charter |
| layover | /layover | Preflight a multi-repo desktop workspace (audit report; cloud stays per-repo) |
| set-key | /set-key | External Terminal paste helper for server-only env secrets |
| paragraph-tunnel | dispatch STEPS | Mid-render structural gate for a named outbound paragraph |
| proof-before-accept | dispatch STEPS | Named proof job + host/blank-canvas checks before ACCEPT |
| rotate | /mod-rotate | Hand off when context is heavy (same O0 family) |
| kick | /mod-kick | Hand to another environment / machine / readback elsewhere |
| pickup | hydrate | Resume from rotation paste; mandatory same-turn remeasure on yield_awaiting_children vs return_to_O0 / hard FAIL (rotate-hydrate only) |
| proceed | hydrate + execute | proceed as recommended, /wavves proceed; all-standing on closed phrases (all still standing, queue all standing and move, proceed all standing); bare shrug / bare /shrug stay AUTH-10 only |
Each command is invoked after the matched skill is read in full so charter, check, decide, layover, rotation and kick steps stay bound to the file even inside a repeat session.
Spec work lands through /mod-check then /mod-decide then /charter so BUILD starts after product forks are locked.
Type /wavves plus a bounded task so the router can match a playbook from the request itself while the skill file stays the source of steps.
/wavves the checkout webhook creates duplicate invoices under retries. reproduce, fix and verify with gate captures. do not deploy.
Call /wavves-init once when a repo needs a standing home or a broken home needs repair, and the command adopts an existing home without silently overwriting INDEX.md or AGENTS.md.
/wavves-init set up wavves in this repo. do not commit.
Use /charter when the work is already bounded and you want to skip the router, pasting Locked decisions first so BUILD waits until named product forks are closed.
/charter migrate every callsite from the sync config store to the async one. behavior must stay identical.
Run /mod-check on a landed spec so an adversarial parallel wave can return GO / REVISE / BLOCK with scoped blocks_w2…blocks_w5 and recommended_actions before anyone writes the implementation plan.
/mod-check review docs/specs/2026-07-08-example.md before we write the implementation plan. adversarial parallel wave. read-only. landing_commit_hash <hash>
Invoke /mod-decide once after a check leaves open product calls, then answer each pick in the same thread until locks complete and authority surfaces sync, so the Locked decisions paste is ready for /charter or /wavves proceed.
/mod-decide navigate open calls from the check return. one decision at a time. write decisions/*.md. no BUILD until locks are complete.
Pick: dedicated button. Record as DSO-01. Next decision when ready. No BUILD yet.
Run /layover to inventory untracked, unpushed and stashed state across sibling repos in a desktop .code-workspace, writing one report under wavves/layovers/ while you open the cloud thread by hand.
/layover audit ~/my.code-workspace. report untracked, unpushed and stashed state per sibling. read-only, audit-only.
Use /set-key so a wave can receive a server-only env secret through an external Terminal paste, with reject leaving .env.local unchanged and densify follow-ups going to background runners.
/set-key open Terminal paste helper for klosr GOOGLE_MAPS_API_KEY. remeasure set/nchars only.
After a verdict names recommended_actions, run /wavves proceed as recommended so commit, dispatch and operator gates execute in order, widening to all-standing only on a closed phrase.
/wavves proceed as recommended /wavves proceed all standing
Type /shrug as the discoverable AUTH-10 proceed alias, and pair it with a closed all-standing phrase when you want the wider inventory.
/shrug /shrug queue all standing and move
Use /mod-rotate when the thread is genuinely heavy so the rotation file can assign O0.R<N+1> and the successor can verify claimed commits from HEAD.
/mod-rotate token velocity is too high. give me the one-line paste for a fresh thread.
Use /mod-kick when handing a stream to another environment that shares git remotes, publishing the lane allowlist first and emitting a paste while pickup stays rotate-hydrate only.
/mod-kick publish the lane allowlist and give me the paste for another environment.
Resume with /wavves pickup so the successor hydrates from wavves/INDEX.md and the newest rotation file, remeasuring yield_awaiting_children against return_to_O0 on disk in the same turn.
/wavves hydrate from the rotation paste and tell me what's active.
Copy any prompt into Cursor chat after installing the plugin.
first session
/wavves set up in this repo, then audit our README for drift. read-only, no commits.
bug fix
/wavves our checkout webhook sometimes creates duplicate invoices. reproduce, fix and verify with gate captures. do not deploy.
flaky ci
/wavves three integration tests flake on main. fix root causes and prove stability with a rerun gate.
overnight lane
/wavves i'm stepping away. land the auth hardening lane with captured gates. no deploy without my approval.
layover
/wavves preflight ~/my.code-workspace. read-only audit of sibling repos; I will open one cloud agent myself afterward.
proceed
/wavves proceed as recommended
rotate
/wavves rotate this thread. write a handoff for active lanes.
kick
/wavves kick this stream to another environment. ask kick target.
pickup
/wavves hydrate from the rotation paste and tell me what's active.
leaf: setup only
/wavves-init set up wavves in this repo. do not commit.
leaf: charter only
/charter migrate every callsite to the async config store. behavior must stay identical.
leaf: spec check
/mod-check review docs/superpowers/specs/2026-07-08-example.md before we write the implementation plan. adversarial parallel wave. read-only. landing_commit_hash <hash>.
leaf: decide
/mod-decide navigate open calls from the check return. one decision at a time. write decisions/*.md. no BUILD yet.
leaf: layover
/layover audit ~/my.code-workspace. read-only.
leaf: rotate only
/mod-rotate token velocity is too high. give me the one-line paste.
leaf: kick only
/mod-kick publish allowlist and give me the paste for another environment.
/add-plugin wavves or a local copy under ~/.cursor/plugins/local/wavves/./mod-check then /mod-decide then /charter so BUILD starts after forks are locked./wavves plus a plain task description. If the home is missing, bootstrap runs first./wavves proceed as recommended runs commit, dispatch and operator gates in order./wavves rotate or /mod-rotate and paste the one-liner into a fresh chat. To leave for another environment that only shares git remotes, use /mod-kick./loop for long lanes that need runnable gates on disk beside the lane home.wavves/
INDEX.md
AGENTS.md
registry.yml
step-log.md
rotations/
rotation-r01-YYYYMMDD-HHMM.md
lanes/
YYYYMMDD_lane-label/
README.md
waveset.md
dispatch.md
dispatch-w{N}.md
findings/
gate-captures/
decisions/
layovers/
<workspace-name>-YYYYMMDD.md
skills/
proposed/
accepted/
Creates the lane, records model choices and keeps the operator-facing thread small.
Runs bounded waves, writes findings and returns decisions to the moderator.
Advances only after a disk gate capture under gate-captures/. Product lanes can also require a named proof job before ACCEPT.
| Role | Recommended tier | Reason |
|---|---|---|
| Lane orchestrator | high-reasoning | Cross-file plan and gate design. |
| Discovery runners | fast | Search, inventory and mechanical scans. |
| Build runners | balanced | Bounded edits with local validation. |
| Adversarial gate | high-reasoning | Risk and defect judgment. |
| Acceptance gate | high-reasoning | Final verification with captured evidence. |