convez.ai
AgenteAutomaçãoAvançado
ManasHardas

AgentWaves

ManasHardas/agentwaves

Orquestração disciplinada de agentes especialistas em ondas de trabalho

Ver no GitHub
InicialPluginScore · de 0 a 100

Framework de disciplina para orquestração de agentes especialistas em fases de cadência de ondas (waves) dentro do Claude Code. Modela o ciclo de vida completo de projetos multi-mês, multi-fase e multi-sessão, desde congelamento de contrato até dogfood, com guardrails de coerência e controle de orçamento entre sessões.

Instalação

$npx convez-ai ManasHardas/agentwaves

1 comando no terminal: detecta o formato do repositório (marketplace ou plugin avulso) e instala via Claude Code. Requer Node 18+ e o Claude Code instalado.

Métricas

Estrelas
3
Forks
0
Acompanhando
0
Saúde
42%
Último commit
há 2 meses
Versão
—
Issues abertas
0
Contribuidores
1

Casos de uso

  • Coordenar múltiplos agentes especialistas em roadmaps de produção de longa duração
  • Manter coerência de dispatch e rastreabilidade entre sessões de trabalho
  • Implementar fases estruturadas (planejamento, build, QA, documentação, dogfood)
  • Monitorar orçamento de tokens e velocidade entre waves

Veredito

Framework robusto e bem-documentado para times que precisam de governança séria em projetos Claude Code de longa duração. Defende contra falhas críticas de coerência em dispatch multi-agente através de protocolos explícitos (wave-state, session handoff, guardrails). Recomendado para produção em équipes, não para prototipagem rápida.

README

A tradução para o português deste README ainda está na fila.

agentwaves

A discipline framework for orchestrating dispatched specialist agents through wave-cadence phases in Claude Code (or any agent harness with a comparable dispatch primitive).

agentwaves answers a different question from most Claude Code skill collections: how do you keep multi-agent dispatch coherent across a multi-month, multi-phase, multi-session production roadmap? It models the lifecycle — phases, waves, session handoffs, budget watchdogs, calibration — not just a single feature workflow.


The wave cadence

Wave 0    — Contract Freeze              (orchestrator alone)
Wave 0.5  — Issue Planning               (Backend + Frontend + Infra in parallel)
Wave 1    — Build (loop)                 (specialist agents per filed issue)
Wave 2    — QA                           (QA agent: planning pass + build loop)
Wave 3    — Phase close                  (Docs agent + tag + roadmap update)
Wave 3.5  — Dogfood pass                 (real-data end-to-end exercise)

Wave 0 + Wave 0.5 produce the filed-issue ready-set that drives Wave 1 build dispatch. The orchestrator never synthesizes dispatch briefs from memory; every Wave 1 dispatch references a filed GitHub issue. This is the discipline-failure mode the framework most aggressively defends against.

Full operating manual: agents/orchestrator.md.


What's in the box

PathWhat it contains
agents/11 specialist role docs: orchestrator, PM, PM-Designer, Code Review, Security, SRE, Backend, Frontend, Infra, QA, Docs
dispatch-templates/Permanent + conditional dispatch-brief clauses (test-file-in-initial-commit, reviewer-trio composition, verification environment, close-keyword convention, CI-quota-constrained mode)
templates/Starter files for wave-state.md, capacity-log.md, velocity.json, phase-spec.md, next-session.md (SHD), runbook.md
scripts/Session-start checklist printer, session-close checklist printer, and the session-close guardrails enforcement script (17 invariants)
CLAUDE.md.snippetPaste into your project's CLAUDE.md to auto-load operating-mode rules into every conversation

Key sub-documents


How agentwaves compares

agentwaves sits in a different layer from the other major Claude Code frameworks. They're not mutually exclusive — agentwaves coexists with Superpowers (e.g. using superpowers:brainstorming for pre-Wave-0 ideation) and is orthogonal to GSD's context-engineering and gstack's role-governance.

DimensionagentwavesSuperpowersGSD (Get Shit Done)gstack
What it constrainsDispatch sequencing of specialist agents through phase-cadence wavesThe development process within a feature (mandatory phase gates)The execution environment (fresh context per task)Decision-making perspective (which role you're acting as)
Primary problem solvedCoherence of multi-agent dispatch across a multi-session, multi-phase roadmapLack of methodology / ad-hoc developmentContext-window degradation ("context rot") on large workUnclear decision authority for solo founder-engineers
Core abstractionPhase + wave + filed-issue + specialist-agent dispatchComposable skills with mandatory triggersAtomic tasks each receiving a fresh 200k contextRole-bound slash commands (CEO, EM, designer, QA, …)
Workflow shapeWave 0 → 0.5 → 1 → 2 → 3 → 3.5, per phase, per sessionBrainstorm → Spec → Plan → TDD → Subagent Dev → Review → FinalizePlan → Execute (parallel waves) → Verify → ShipThink → Plan → Build → Review → Ship
Multi-agent dispatch model11 named specialist roles with explicit scope fences; orchestrator-led with parallel-within-wave + sequential-across-wavesSubagent-driven-development skill; agents invoked per phaseAtomic tasks dispatched to fresh subagentsRole-skills invoked sequentially; no parallel dispatch primitive
Cross-session statewave-state.md (authoritative) + next-session.md (SHD cache) + velocity.json + capacity-log.mdNone built-in; per-sessionPROJECT.md, REQUIREMENTS.md, ROADMAP.md, STATE.md, CONTEXT.md, .planning/config.jsonNone built-in; relies on git + role-output chaining
Budget / token disciplineT-A/T-G/T-D budget watchdogs + T-M/T-X/T-Y coordination watchdogs + per-class velocity model with Bayesian updateNone (process-focused, not budget-focused)Avoids the problem structurally via fresh contextsNone explicit
Quality gatesDispatch-template clauses: test-file-in-initial-commit, reviewer-trio composition (5 default-keep / default-prune rules), verification environment HARD CONSTRAINT, close-keyword conventionMandatory TDD (RED-GREEN-REFACTOR; deletes code written before tests)Manual verify phase/review and /ship skills at end of pipeline
Session-close enforcementscripts/check-session-close-guardrails.sh — 17 invariants enforced as BLOCKER (exit 1) or WARN (exit 2)n/an/an/a
Operating modesACTIVE (full PM discipline) vs DEGRADED (PM-skip; allowed only when ALL narrow-fix conditions hold)n/an/an/a
Calibrationvelocity.json per-class observations → Bayesian update of priors over timen/an/an/a
Project lifecycle targetMulti-month, multi-phase production roadmap (8+ phases, 50+ PRs typical)Single feature / single bugfixSingle complex project that exceeds one context windowSolo founder-engineer wearing multiple hats
InstallationCopy/submodule the repo into your project; paste CLAUDE.md.snippet/plugin install superpowers@claude-plugins-officialnpx get-shit-done-cc@latestSlash-command skills installed individually
Composability with the othersCoexists with Superpowers (use its brainstorming/TDD skills inside Wave 1); orthogonal to GSD/gstackComposable; agentwaves uses it for pre-Wave-0 ideationComposableComposable
What it deliberately is NOTA code generator; a within-session methodology; a single-implementer patternA multi-session roadmap framework; a budget trackerA multi-agent dispatch systemA multi-session roadmap framework

Short version: Superpowers gives you discipline within a feature. GSD gives you clean context per atomic task. gstack gives you a role to think from. agentwaves gives you the dispatch + lifecycle scaffolding to coordinate many specialist agents across many sessions toward a shipped product.

If you're solo and shipping a single feature, Superpowers is the right tool. If your project keeps blowing through context windows, GSD is the right tool. If you're a founder doing both eng and product, gstack is the right tool. If you're running a multi-phase roadmap with parallel specialist-agent dispatch and you need cross-session memory + budget discipline + reviewer-trio calibration, that's what agentwaves was extracted to solve.


Adoption

Three steps:

  1. Clone or submodule the repo into your project as .orchestrator/ (or any path you prefer).
  2. Customize placeholders in agents/*.md for your stack (search for <api-routes-dir>, <frontend-app-dir>, <migrations-versions-dir>, etc.).
  3. Paste CLAUDE.md.snippet into your project's CLAUDE.md to auto-load operating-mode rules into every Claude Code session.

Then in a fresh Claude Code conversation in your project's directory:

Read .orchestrator/agents/orchestrator.md. We're starting Phase 1 of <project>. I'll be the user; you're the Orchestrator. Run the Session-start ritual.


Environment variables

VariablePrefixDefaultEffect
AW_CI_QUOTA_CONSTRAINEDAW_* (protocol-wide)unsetWhen 1, activates the CI-quota-constrained mode (skip-CI-on-every-commit + admin-merge + label-gate expensive jobs). Reactive recovery; rarely needed if Clause #9 — CI workflow hygiene is applied to every workflow as the mandatory prevention.
GUARDRAIL_CC_SESSION_GATEGUARDRAIL_* (guardrails-script)99999 (off)Minimum session number from which the cc_session_id invariant is enforced
GUARDRAIL_MAIN_CI_GATEGUARDRAIL_* (guardrails-script)99999 (off / WARN-only)Minimum session number from which check #18 (main CI green at session-close) escalates from WARN to BLOCKER. The check fetches origin/main's check-runs via gh api; sub-10s failures are auto-classified as INFO (likely billing-block, not a real red)

AW_* is for cross-protocol knobs; GUARDRAIL_* is for guardrails-script-specific gates. Add new knobs to whichever scope they belong to.


Provenance

agentwaves was extracted from a real production project that ran enough phases, sessions, and PRs through the wave-cadence pattern for the failure modes to surface, retrospect, and harden into rules.

What that looks like in concrete terms:

  • The operating-mode rule (ACTIVE vs DEGRADED) exists because PM-skip was wrongly applied to a session introducing new contract surfaces; the orchestrator-synthesized dispatch brief conflated already-shipped endpoints with future ones, the reviewer agents fired multiple Blockers, and a substantial fix-cycle tax was paid in tokens that should have been spent on feature work. The retro produced the rule; the rule was promoted to a permanent clause in both the orchestrator role doc and the auto-loaded CLAUDE.md snippet.
  • The session-close guardrails script exists because 8 of its 17 invariants drifted silently across a multi-phase stretch. Velocity-log rollups stopped happening, SHDs grew stale, working trees shipped with uncommitted state — none of which surface in normal development because agents follow stale memory and the spec keeps living in the doc unaltered. The script makes that drift impossible to miss at close-time.
  • The reviewer-trio composition matrix exists because dispatching the wrong reviewer set either over-burns budget (full trio on a narrow-fix sibling) or escapes Blockers (CR-only on an endpoint with new HTTP attack surface). The default-keep / default-prune bifurcations were calibrated across many sessions of paired observation, with zero escaped Security findings on Security-pruned slots in the validation window.
  • The SHD protocol (plans/next-session.md) exists because the legacy session-start ritual — re-derive priors at session-start, dispatch PM for capacity planning, then dispatch the first real slot — was paying 100-140k tokens per session-start for context the prior session already knew. Pre-rendering the playbook at session-close cut that overhead to 5-15k.
  • The coordination watchdogs T-M / T-X / T-Y exist because plan-template references silently went stale, parallel-lane file overlaps silently produced merge conflicts, and post-merge auto-close silently fired on wrong issues. Each was caught and made into a pre-dispatch / post-merge ritual after the failure was named.

Every clause in dispatch-templates/ traces back to a specific recurring failure mode with a measured token cost. The framework is not aspirational; it is the residue of mistakes that hurt enough to encode.

Names, paths, session numbers, and project-specific examples have been genericized for cross-project reuse. The discipline itself is what's portable.


License

MIT. See LICENSE.

Ver o original no GitHub

Bom para

Relacionados