wavves
Version: 0.5.0.
Route durable multi-agent work through a moderator layer, with alignment
packets, disk gate captures and handoff files saved beside the work.
wavves is a Cursor plugin for managed distributed sessions. Skills help
a single operator prepare bounded work, dispatch parallel runners and rotate
overloaded threads while the shared record lives in files on disk.
The core ideas:
- Alignment packets. Each lane gets a home directory with scope, grounded
facts, locked decisions, file boundaries and acceptance checks.
- Bounded waves. O0 background-dispatches a wave orchestrator that
fans out charge workers (one Task per charge) with strict file
ownership while the operator-facing thread stays small.
- Disk gate captures. A lane advances after a runnable harness writes
pass or block evidence under
gate-captures/, graded by someone who did
not author the work under review. Failed gates are reported as failed,
with capped remediation loops.
- Proof-before-accept. Product lanes declare a named proof job;
process-only ACCEPT cannot clear when
proof_required: yes.
- Paragraph tunnel. Mid-render structural gate for one outbound field
(adversarial + capped rewrite + mechanical fixtures), not a voice-clone.
- Rotation with term identity. When a thread gets heavy, the orchestrator
hands off to a fresh one via a rotation file that assigns the successor a
monotonic term identity (
r<NN>). The naming uses analogies to Raft
terms, Kubernetes StatefulSet ordinals and Erlang incarnation numbers (not
protocol isomorphisms): house fences are handoff files, stamps and etiquette.
- A standing home. Any fresh instance hydrates from files (an index, a home
contract, a rotations directory, a registry, a step log), never from
transcripts.
- Authority propagation. After mod-decide, locks sync to
waveset.md,
dispatch-w{N}.md and the registry so W2+ runners do not re-litigate
settled decisions. Scoped mod-check verdicts (blocks_w2…blocks_w5) and
/wavves proceed execute ordered recommended actions.
wavves is a community plugin by aimez and is not affiliated with or endorsed
by Cursor.
Installation
From the Cursor plugin marketplace after listing:
/add-plugin wavves
Or install locally by copying this directory to:
~/.cursor/plugins/local/wavves/
Copy the plugin contents, not the .git directory. A release directory or a
plain copy of .cursor-plugin/, skills/, examples/, README.md and
LICENSE is the safest local install path.
Safety defaults
wavves writes its own working records under wavves/ by default. An
existing root AGENTS.md is treated as repo governance and is not overwritten.
Setup and lane preparation do not commit, push, deploy or mutate external
services unless the operator explicitly asks for that action or the repo
governance says wavves owns those writes.
Usage
Type /wavves at the start of a task. It reads your request, checks the home,
picks a playbook and runs the leaf skill. Like /poteto-mode in pstack.
just use /wavves
| playbook | for |
|---|
| bootstrap | first time in repo, repair home, no wavves/ yet |
| charter-lane | bounded work: bug fix, audit, refactor, flaky CI, overnight lane |
| check | adversarial sanity-check of a landed spec or plan before build |
| decide | lock open product/design calls after a check return, before BUILD |
| layover | preflight a multi-repo desktop workspace (audit report; cloud stays per-repo) |
| paragraph-tunnel | mid-render structural gate for a named outbound paragraph |
| proof-before-accept | named proof job + host/blank-canvas checks before ACCEPT |
| rotate | hand off to a fresh moderator thread |
| kick | cross-environment exit: publish allowlist + paste for another machine |
| pickup | resume from rotation paste, "where are we"; mandatory yield vs return_to_O0 remeasure |
| proceed | execute recommended_actions from a verdict (proceed as recommended); all-standing mode on closed phrases only |
| shrug | /shrug alias for emoji shrug; bare → AUTH-10 proceed; with closed all-standing phrase → proceed-all-standing |
What wavves tracks
| Piece | Where it lives | What it is |
|---|
| O0 | the operator-facing thread | charters lanes, background-dispatches wave orchestrators, reconciles on notify, lands git; then O0_release_window |
| wave orchestrator | background Task under O0 | fans out charge workers; integrates; writes rollup+gate (or hard FAIL / operator_gate). No early return_to_O0. Yield requires findings/<wave>-orch-checkpoint.md; O0 same-turn remeasures and resumes yield (not fail-remediation-only) |
| charge worker | one background Task per charge id | one bounded disjoint task; never git; never solicit the operator |
| Home | <repo>/wavves/ | standing hydration contract that outlives any one chat |
| Lane | wavves/lanes/<date>_<label>/ | one bounded workstream with its own charter and findings |
| Charter | lanes/.../waveset.md | alignment packet: scope, locked decisions, waves, gates |
| Dispatch | lanes/.../dispatch-w{N}.md | per-wave paste block; active_dispatch in registry |
| Registry | wavves/registry.yml | map of every chartered lane and its status |
| Rotation | wavves/rotations/ | handoff files with term identity (r01, r02, ...) |
| Gates | lanes/.../gate-captures/ | runnable checks with JSON + log evidence on disk |
Orchestration fail ids (skill text; append to wavves/failure_log.yml only
when observed in a real run): PROC-ORCH-EARLY-EXIT,
PROC-ORCH-LAUNCH-AND-EXIT, PROC-ORCH-NO-RESUME-CONTRACT,
PROC-ORCH-SOLO-BUILD, PROC-ORCH-ROLE-COLLAPSE, PROC-ORCH-DEP-OVERCLAIM,
PROC-ORCH-FOREGROUND-HOLD, PROC-MOD-FOREGROUND-HOLD,
PROC-MOD-PROGRESS-THEATER. Checker:
python3 evals/check_wave_orchestrator_fanout.py. Canonical Roles:
skills/charter/SKILL.md.
Fresh instances hydrate from the home files, never from chat transcripts.
Skills
| skill | use it when |
|---|
/wavves | default entry. routes to bootstrap, charter, check, decide, layover, set-key, rotate, kick, pickup, proceed or shrug |
/wavves-init | you only need home setup |
/charter | you only need a new lane chartered |
/mod-check | you only need an adversarial spec/plan sanity-check wave |
/mod-decide | you only need to lock open calls before a BUILD charter |
/layover | you only need the workspace preflight audit |
/set-key | open Terminal.app paste helper for a server-only env secret |
/shrug | alias for emoji shrug; bare → AUTH-10 proceed; with closed all-standing phrase → proceed-all-standing |
/mod-rotate | you only need rotation |
/mod-kick | you only need a cross-environment kick exit |
Most operators type /wavves plus the task. Reach for the leaf skills when you
know exactly which step you need.
examples
default: /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.
flaky ci: /wavves three integration tests flake on main. fix root causes
and prove stability.
overnight: /wavves i'm stepping away. land the auth hardening lane with
captured gates. no deploy without my approval.
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>.
decide: /mod-decide navigate open calls from the check return.
one decision at a time. write decisions/*.md. no BUILD yet.
Mid-queue: answer Pick: … only. Do not re-slash each time.
layover: /wavves preflight ~/my.code-workspace. read-only audit;
I will open one cloud agent myself afterward.
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.
proceed: /wavves proceed as recommended after mod-check or mod-decide return.
all-standing: /wavves proceed all standing
(or: all still standing / queue all standing and move)
shrug: /shrug
(bare → AUTH-10 proceed; add a closed all-standing phrase to widen)
setup only: /wavves-init set up wavves in this repo. Do not commit.
charter only: /charter migrate every callsite to the async config store.
check only: /mod-check the landed spec. GO / REVISE / BLOCK with named gaps.
decide only: /mod-decide lock the open calls. emit Locked decisions paste.
layover only: /layover audit ~/my.code-workspace. report untracked,
unpushed and stashed state per sibling repo.
set-key only: /set-key open Terminal.app paste helper for klosr
GOOGLE_MAPS_API_KEY (never put the secret in chat).
rotate only: /mod-rotate token velocity is too high. give me the one-line paste.
kick only: /mod-kick publish allowlist and give me the paste for another environment.
Spec → BUILD lifecycle (/mod-check → /mod-decide → /charter) plus four
worked examples: examples/usage.md.
What each skill does
/wavves matches a playbook, reads the leaf skill and executes. If the
home is missing, bootstrap runs first./wavves-init creates <repo>/wavves/ with INDEX.md, AGENTS.md,
registry.yml, step-log.md and rotations/./charter writes the lane home, registers the lane and dispatches a
background wave orchestrator with runnable gates in gate-captures/.
Multi-repo lanes declare a repos table and commit plan; each dispatch
carries an authority precedence block./mod-check charters a read-only adversarial wave against a landed
spec or plan and returns a scoped verdict (GO / REVISE / BLOCK,
blocks_w2…blocks_w5) with recommended_actions./mod-decide walks open product/design calls one at a time, writes
decisions/*.md, syncs authority surfaces on completion and emits a
Locked decisions paste for BUILD./layover reads a bespoke multi-root .code-workspace file (or an
explicit folder list) and writes a read-only audit of every sibling
repo's remotes, branch sync state, uncommitted changes, untracked files
and stashes. Audit-only: one report file, never mutates an audited repo.
Does not start cloud agents or autoconfigure wavves elsewhere./set-key opens Terminal.app with a paste-and-return helper that
writes a server-only env secret (default klosr GOOGLE_MAPS_API_KEY).
Never echoes the secret; remeasures set/nchars only; reject leaves the
env file unchanged./shrug is a thin alias for emoji shrug. Bare /shrug → AUTH-10
proceed; with a closed all-standing phrase → proceed-all-standing./mod-rotate writes a rotation file with term identity and emits a
one-line paste for a fresh thread./mod-kick publishes a lane allowlist to a kick-target remote, writes
a wavves/handoffs/KICK_*.md receipt, and emits a paste for another
environment. Not a substitute for /mod-rotate or the pickup playbook.
/wavves proceed executes ordered recommended_actions from a verdict
(commit, dispatch, operator gates). Closed all-standing phrases
(all still standing, queue all standing and move, proceed all standing,
/wavves proceed all standing) route to proceed-all-standing. Bare shrug or
bare /shrug stays AUTH-10 proceed only. On orch
yield_awaiting_children, pickup / O0 same-turn remeasures disk and resumes
(or treats rollup+gate as return_to_O0); fail-remediation-only is for true
fails.
/wavves pairs well with Cursor's /loop for long lanes with captured gates
on disk beside the lane home.
Project layout
Default new-repo layout:
wavves/
INDEX.md
AGENTS.md
registry.yml
step-log.md
failure_log.yml
rotations/
rotation-r01-YYYYMMDD-HHMM.md
lanes/
YYYYMMDD_lane-label/
waveset.md
dispatch.md # W1 or historical
dispatch-w{N}.md # active wave dispatch
README.md
findings/
gate-captures/
decisions/
layovers/
<workspace-name>-YYYYMMDD.md
skills/
proposed/
accepted/
evals/
run_fixtures.py
fixtures/
INDEX.md is the fast pickup surface, pointing a fresh moderator to the
current rotation file, active lanes, blocked decisions and next files to read.
AGENTS.md is the stable contract. registry.yml is the lane map.
step-log.md is append-only. Lane files carry the detailed work.
Moderator and skill flow
The moderator owns wavves/INDEX.md, wavves/registry.yml and
wavves/step-log.md. Lane orchestrators own their lane homes under
wavves/lanes/ and return proposed project skills when a repeated local
practice appears.
Project skills are drafts first. A lane may write a proposal under
wavves/skills/proposed/, with the evidence and lane that justified it. The
moderator reviews the proposal and asks the operator before saving it as a
repo skill, Cursor IDE skill or plugin update. Runners never install skills
directly.
Model and Cost Discipline
Each waveset.md includes a model routing table. The table records the
moderator's recommended model tier for the lane orchestrator and for each wave:
role model tier reason
lane orchestrator high-reasoning cross-file planning and gate design
discovery runners fast broad search, summaries, inventory
build runners balanced bounded edits with local validation
adversarial gate high-reasoning defect finding and risk judgment
acceptance gate high-reasoning final verification and caveat review
When the environment exposes a model parameter for subagents, the moderator
sets that parameter at dispatch time. If the environment does not expose one,
the dispatch prompt still carries the recommendation so the receiving agent can
report the mismatch.
The table is a cost-control surface, not a measured savings claim. Cost is
auditable when the charter records runner count, expected file reads, expected
gate cost and model tier before execution. A later accounting pass can compare planned
tiers with actual token or billing records when the environment exposes them.
Manual harness inspection
Gate evidence lives beside the lane:
wavves/lanes/YYYYMMDD_lane-label/
gate-captures/
<gate>.json
<gate>.log
Inspect a gate by opening the JSON summary, reading the paired log and checking
the verdict in findings/ against both files. A hand-written summary is not a
gate capture. The command that produced each capture should be named in the
finding so another operator can rerun it.
Public copy gates
Universal outbound prose rules ship with the plugin (AFFIRM, DASH, FILLER,
OXFORD, NO_LONGER). wavves story rules are manual (docs/purpose-gates.md).
python3 evals/check_public_copy.py
See docs/public-copy-gates.md. Project-specific rules (internal naming
tokens, colon ban on full UI pages) stay in the separate prose-gates repo.
Self-improvement loop
Lane orchestrators can propose edits to installed skill files. Any such edit
is gated: evals/run_fixtures.py must pass 3 consecutive times before the
moderator applies it live. Confirmed regressions append to wavves/failure_log.yml.
Workspace preflight (/layover)
/layover audits every sibling repo in a bespoke .code-workspace and writes
one report under wavves/layovers/. It never mutates an audited repo.
Known boundary: Cursor cloud agents remain single-repo. /layover does
not start a cloud agent. It does not make cloud multi-root. It does not
autoconfigure wavves in another thread. After the report, open one cloud
agent on the chosen repo and hydrate wavves there by hand.
Paragraph tunnel and proof-before-accept
- Playbook:
skills/wavves/playbooks/paragraph-tunnel.md
Checker: python3 evals/check_paragraph_tunnel.py
- Playbook:
skills/wavves/playbooks/proof-before-accept.md
Checker: python3 evals/check_proof_before_accept.py
Host probe: python3 skills/charter/scripts/proof_host_probe.py --self-check
Components
Skills
| Skill | Description |
|---|
wavves (/wavves) | Main entry. Routes to bootstrap, charter, check, decide, layover, rotate, kick, pickup or proceed. |
wavves-init (/wavves-init) | Bootstrap the standing home a fresh moderator hydrates from. |
charter (/charter) | Charter a lane and dispatch waves behind runnable gates. Multi-repo profile, dispatch-w{N}.md, authority precedence. |
mod-check (/mod-check) | Adversarial parallel sanity-check of a landed spec or plan. Scoped verdict + recommended_actions. |
mod-decide (/mod-decide) | Lock open product/design calls; authority sync on complete; emit Locked decisions for BUILD. |
layover (/layover) | Read-only multi-repo workspace preflight audit. Does not configure cloud agents. |
set-key (/set-key) | Terminal.app paste helper for a server-only env secret. Never agent-shells the secret. |
shrug (/shrug) | Thin alias for emoji shrug. Bare → AUTH-10 proceed; with closed all-standing phrase → proceed-all-standing. |
mod-rotate (/mod-rotate) | Hand the moderator or one lane to a fresh thread. |
mod-kick (/mod-kick) | Cross-environment exit: publish allowlist + paste. Not rotate / pickup. |
Examples on disk
examples/usage.md has the spec → BUILD lifecycle
(/mod-check → /mod-decide → /charter), quick-reference prompts, and
four worked walkthroughs plus a /layover preflight audit example.
The paths and metrics in those examples are fictional. The skills ship no
hard-coded paths from any particular project.
Read more
The launch article and companion whitepaper are omitted here until public URLs
exist.
License
Copyright 2026 Gil Raitses. All rights reserved. The wavves package is sold under a buyer license, with one LICENSE file for the whole package.
