{"id":49785983,"url":"https://github.com/blackwell-systems/polywave","last_synced_at":"2026-05-12T01:01:35.662Z","repository":{"id":341104781,"uuid":"1168877000","full_name":"blackwell-systems/polywave","owner":"blackwell-systems","description":"Parallel AI agents that don't break each other's code. Every file belongs to one agent. Every agent gets its own worktree. You review the plan before any code is written.","archived":false,"fork":false,"pushed_at":"2026-05-11T22:59:54.000Z","size":20337,"stargazers_count":2,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-05-12T00:26:04.871Z","etag":null,"topics":["agent-orchestration","agent-skills","agent-skills-standard","agentic-coding","agentic-workflow","ai","ai-agents","claude","claude-code","coordination-protocol","git-worktree","llm-agents","llm-orchestration","multi-agent","parallel-agents","prompt-engineering","protocol","workflow-automation"],"latest_commit_sha":null,"homepage":"","language":"Shell","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"other","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/blackwell-systems.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":".github/CODEOWNERS","security":null,"support":null,"governance":null,"roadmap":"ROADMAP.md","authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2026-02-27T22:37:14.000Z","updated_at":"2026-05-11T22:55:14.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/blackwell-systems/polywave","commit_stats":null,"previous_names":["blackwell-systems/scout-and-wave","blackwell-systems/polywave"],"tags_count":15,"template":false,"template_full_name":null,"purl":"pkg:github/blackwell-systems/polywave","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/blackwell-systems%2Fpolywave","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/blackwell-systems%2Fpolywave/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/blackwell-systems%2Fpolywave/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/blackwell-systems%2Fpolywave/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/blackwell-systems","download_url":"https://codeload.github.com/blackwell-systems/polywave/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/blackwell-systems%2Fpolywave/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":32919142,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-11T17:09:15.040Z","status":"ssl_error","status_checked_at":"2026-05-11T17:08:45.420Z","response_time":120,"last_error":"SSL_connect returned=1 errno=0 peeraddr=140.82.121.5:443 state=error: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["agent-orchestration","agent-skills","agent-skills-standard","agentic-coding","agentic-workflow","ai","ai-agents","claude","claude-code","coordination-protocol","git-worktree","llm-agents","llm-orchestration","multi-agent","parallel-agents","prompt-engineering","protocol","workflow-automation"],"created_at":"2026-05-12T01:00:46.625Z","updated_at":"2026-05-12T01:01:35.540Z","avatar_url":"https://github.com/blackwell-systems.png","language":"Shell","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Polywave\n\n\u003cp align=\"center\"\u003e\n  \u003cimg src=\"assets/logo.png\" alt=\"Polywave\" width=\"600\" /\u003e\n\u003c/p\u003e\n\n[![Blackwell Systems™](https://raw.githubusercontent.com/blackwell-systems/blackwell-docs-theme/main/badge-trademark.svg)](https://github.com/blackwell-systems)\n![Version](https://img.shields.io/badge/version-0.9.3-blue)\n[![Agent Skills](assets/badge-agentskills.svg)](https://agentskills.io)\n\nPolywave is published as an [Agent Skill](https://agentskills.io) — a portable, tool-agnostic package for adding capabilities to AI coding agents.\n\n**Parallel AI agents that don't break each other's code.**\n\nOther multi-agent frameworks run fast and merge chaos. Polywave gives every agent its own worktree, assigns every file to exactly one agent, and shows you the full plan before any agent touches your code. Conflicts are resolved at planning time - not at merge time, after two agents have already built divergent solutions.\n\n\u003e Follows the [Agent Skills](https://agentskills.io) open standard - compatible with Claude Code, Cursor, GitHub Copilot, and other Agent Skills-compatible tools. See [`implementations/`](implementations/) for reference implementations.\n\n\u003e **New to Polywave?** Follow this path:\n\u003e 1. Read this README (15 min) - understand \"why\" and \"how\" at a high level\n\u003e 2. Read [implementations/claude-code/QUICKSTART.md](implementations/claude-code/QUICKSTART.md) (20 min) - see a real example with output\n\u003e 3. Try it yourself: `/polywave scout \"feature\"` on a test project\n\u003e 4. Deep dive: [protocol/](protocol/) specification when building a new implementation\n\n## Why\n\nYou've run parallel agents before. You know what happens: two agents edit the same file, the merge produces garbage, and you spend longer fixing it than if you'd done the work sequentially. Or worse - the merge succeeds silently because both agents touched different functions in the same file, but they made contradictory assumptions about shared state. You find out at runtime.\n\nMost frameworks try to solve this with better prompts. Polywave solves it with structure:\n\n- **Disjoint file ownership.** The Scout assigns every file to exactly one agent before any code is written. Two agents in the same wave cannot produce edits to the same file. Merge conflicts become structurally impossible.\n- **Per-agent worktree isolation.** Each agent works in its own git worktree - a separate directory with an independent file tree. Concurrent builds, tests, and tool-cache writes don't race on shared state.\n- **Human review before execution.** You see the full plan - file assignments, interface contracts, wave structure - and approve it before any agent launches. This is the last point where changing the architecture is cheap.\n- **Suitability gate.** Polywave says \"no\" when the work doesn't decompose cleanly. A poor-fit assessment prevents bad decompositions from producing expensive failures.\n\nThe system has seven participant roles, but you interact with two: the **Orchestrator** (your Claude Code session — coordinates everything) and the **Scout** (analyzes codebase, assigns files, writes the plan). The other five — Scaffold Agent, Wave Agents, Integration Agent, Critic Agent, Planner — run automatically when needed. See [protocol/participants.md](protocol/participants.md) for the full role breakdown.\n\n## How\n\n**What happens when you run Polywave:**\n\n1. You run `/polywave scout \"feature\"` → Scout analyzes codebase, assigns files to agents\n2. Scout writes IMPL doc (implementation document — a YAML coordination artifact that defines file ownership, interface contracts, and wave structure for the feature) → You review the wave structure (waves are groups of agents that execute in parallel)\n3. You run `/polywave wave` → Scaffold Agent creates scaffold files (type/interface definitions shared across agents, created before any wave launches) if needed\n4. Wave Agents launch in parallel → Each works in isolated worktree on disjoint files\n5. Orchestrator merges → Runs tests → Cleans up worktrees\n\n**Key mechanisms:**\n\n- **Orchestrator:** Synchronous coordination agent in your session. Launches Polywave Agents, enforces file ownership, executes merge procedure, runs verification gates. Human reviews and approves through it directly.\n\n- **Scout:** Asynchronous agent. Analyzes codebase, produces IMPL doc with dependency graph, interface contracts, file ownership table, and wave structure. Every file assigned to exactly one agent. Resolves ownership conflicts at planning time or declares work NOT SUITABLE.\n\n- **Scaffold Agent:** Asynchronous agent. Runs once before Wave 1 if the IMPL doc specifies shared types that multiple agents need (e.g., interface definitions). Creates shared type files (called \"scaffolds\") from IMPL doc contracts, verifies compilation, commits to HEAD. Runs once before any Wave Agent launches. If compilation fails, wave stops before worktrees are created.\n\n- **Wave Agents:** Asynchronous agents running in parallel. Each owns disjoint files, implements against frozen interface contracts, runs verification gate, commits work, writes completion report.\n\n- **Integration Agent:** Asynchronous agent running after wave merge. Wires new exports from wave agents into caller code. Restricted to `integration_connectors` files. Non-fatal — gaps are reported to the human if wiring fails.\n\nThe protocol has a built-in **suitability gate** that answers five questions before producing any agent prompts. If preconditions don't hold, the scout emits NOT SUITABLE and stops. **Polywave isn't for everything.** A poor-fit assessment prevents bad decompositions.\n\nThe five questions assess whether the work:\n1. Decomposes into independent files\n2. Avoids investigation-first blockers\n3. Has discoverable interfaces\n4. Has been pre-scanned for already-implemented items (from audit/findings lists)\n5. Provides value from parallelization\n\nSee [protocol/preconditions.md](protocol/preconditions.md) for details.\n\n\u003cpicture\u003e\n  \u003csource media=\"(prefers-color-scheme: dark)\" srcset=\"assets/diagrams/polywave-scout-wave-dark.svg\"\u003e\n  \u003cimg src=\"assets/diagrams/polywave-scout-wave-light.svg\" alt=\"Polywave scout + wave execution flow\"\u003e\n\u003c/picture\u003e\n\n## Quick Start\n\n\u003e **⚠️ BEFORE YOU START:** Add `\"Agent\"` to your allow list in `~/.claude/settings.json` or you'll need to manually approve each agent launch. See [implementations/claude-code/README.md](implementations/claude-code/README.md#step-1-configure-permissions-required) for details.\n\n\u003e **ℹ️ Claude Code implementation shown below.** The `/polywave` commands use Claude Code's Agent Skills syntax. Other Agent Skills-compatible tools (Cursor, GitHub Copilot, etc.) use their own invocation syntax - see [`implementations/`](implementations/) for the appropriate guide.\n\n```bash\n# 1. Clone and install\ngit clone https://github.com/blackwell-systems/polywave.git ~/code/polywave\n\n# Quick install\n~/code/polywave/install.sh\n\n# Or manually (see implementations/claude-code/README.md for full install):\nmkdir -p ~/.claude/skills/polywave/agents\nln -sf ~/code/polywave/implementations/claude-code/prompts/polywave-skill.md ~/.claude/skills/polywave/SKILL.md\nln -sf ~/code/polywave/implementations/claude-code/prompts/polywave-bootstrap.md ~/.claude/skills/polywave/polywave-bootstrap.md\nln -sf ~/code/polywave/implementations/claude-code/prompts/agent-template.md ~/.claude/skills/polywave/agent-template.md\nln -sf ~/code/polywave/implementations/claude-code/prompts/agents ~/.claude/skills/polywave/agents\n\n# 2. Install polywave-tools CLI (pick one)\nbrew install blackwell-systems/tap/polywave-tools                                     # Homebrew\ngo install github.com/blackwell-systems/polywave-go/cmd/polywave-tools@latest   # Go install\n# Or download binary: https://github.com/blackwell-systems/polywave-go/releases/latest\n\n# 3. Initialize your project (auto-detects language, build, and test commands)\ncd your-project\npolywave-tools init\n\n# 4. Restart Claude Code, then in any session on any project:\n/polywave scout \"add a caching layer to the API client\"\n# → Scout analyzes the codebase, assigns files to agents, writes docs/IMPL/IMPL-caching-layer.yaml\n# → Orchestrator shows you the wave structure and interface contracts for review\n# → You review the IMPL doc. This is the last chance to change interfaces.\n\n/polywave wave\n# → If shared types are needed, Scaffold Agent creates them automatically\n# → Parallel agents implement their assigned files concurrently\n# → Orchestrator merges, runs tests, reports result\n\n# Or collapse both steps into one command:\n/polywave auto \"add a caching layer to the API client\"\n# → Scout analyzes, writes IMPL doc, shows wave structure\n# → You confirm (\"Proceed? [y/N]\") -- this is the human checkpoint\n# → On Y: all waves execute automatically\n\n# When you have multiple IMPLs queued — run them all in parallel:\n/polywave program --impl feature-a feature-b feature-c\n# → Checks for file ownership conflicts across all three\n# → If disjoint (no overlapping files), assigns all to Tier 1\n# → All three IMPLs execute simultaneously; sequential tiers only when files overlap\n/polywave program execute\n```\n\n**Subcommands:**\n\n| Command | Purpose |\n|---------|---------|\n| `/polywave scout \"\u003cfeature\u003e\"` | Analyze codebase, produce IMPL doc |\n| `/polywave wave` | Execute next pending wave |\n| `/polywave wave --auto` | Execute all remaining waves unattended |\n| `/polywave auto \"\u003cfeature\u003e\"` | Scout + confirm + wave in one command |\n| `/polywave status` | Show current wave and agent progress |\n| `/polywave bootstrap \"\u003cproject\u003e\"` | Design new project structure from scratch |\n| `/polywave interview \"\u003cdescription\u003e\"` | Structured requirements gathering |\n| `/polywave program --impl \u003cslug\u003e ...` | Bundle queued IMPLs into a parallel program (auto tier-assigns by file ownership) |\n| `/polywave program plan/execute/status/replan` | Top-down multi-feature planning and tier-gated execution |\n| `/polywave amend --add-wave/--redirect-agent/--extend-scope` | Modify active IMPL |\n\nThe scout produces an **Implementation Document (IMPL doc)** (`docs/IMPL/IMPL-\u003cfeature\u003e.yaml`): a structured YAML coordination document that defines which files each agent will modify, what interfaces they'll implement, and how they'll work in parallel. You review it before any agent writes code. This is the human checkpoint that makes parallel execution safe.\n\n**First time using Polywave?** See [implementations/claude-code/QUICKSTART.md](implementations/claude-code/QUICKSTART.md) for step-by-step guidance with example output.\n\n## Ways to Use Polywave\n\nPolywave has three interfaces backed by separate repositories, all implementing the same protocol.\n\n| Interface | Repository | Description |\n|-----------|------------|-------------|\n| Claude Code skill (`/polywave`) | [polywave](https://github.com/blackwell-systems/polywave) (this repo) | Runs inside Claude Code as a slash command. The orchestrator is Claude itself. Fastest way to get started. |\n| Go engine + `polywave-tools` CLI | [polywave-go](https://github.com/blackwell-systems/polywave-go) | Protocol SDK, 75+ CLI commands, and LLM-agnostic engine. Supports Anthropic, OpenAI, and local (Ollama) backends. |\n| Web UI (`polywave serve`) | [polywave-web](https://github.com/blackwell-systems/polywave-web) | Browser-based dashboard with real-time SSE updates. Imports polywave-go as dependency. |\n\nAll implement the same Polywave protocol and produce identical IMPL docs. Use the Claude Code skill to start quickly. Use `polywave-tools` for programmatic orchestration, or the Web UI for a browser-based dashboard with real-time monitoring.\n\n## Documentation\n\n### Protocol Specification\n\nThe protocol is defined independent of any implementation. Read these to understand how Polywave works:\n\n- **[protocol/README.md](protocol/README.md)** - Protocol overview and navigation guide\n- **[protocol/participants.md](protocol/participants.md)** - Seven participant roles and their responsibilities\n- **[protocol/preconditions.md](protocol/preconditions.md)** - Five preconditions for suitability gate\n- **[protocol/invariants.md](protocol/invariants.md)** - Six invariants (I1–I6) — formal correctness rules that every implementation must satisfy (e.g., I1: disjoint file ownership, I2: interface contracts precede parallel implementation)\n- **[protocol/execution-rules.md](protocol/execution-rules.md)** - 47 execution rules (E1–E47) governing the full lifecycle: state transitions, agent launches, merge procedures, verification gates, failure recovery, integration, and hook-based enforcement. You don't need to read these to use Polywave — the tooling enforces them automatically.\n- **[protocol/state-machine.md](protocol/state-machine.md)** - Protocol states and transitions\n- **[protocol/message-formats.md](protocol/message-formats.md)** - IMPL doc and completion report schemas\n- **[protocol/procedures.md](protocol/procedures.md)** - Step-by-step merge and verification procedures\n\n### Implementations\n\nPolywave can be executed in different ways:\n\n- **[implementations/claude-code/](implementations/claude-code/)** - Fully automated implementation using Claude Code\n\nSee **[implementations/README.md](implementations/README.md)** for details.\n\n## When to Use It\n\nPolywave pays for itself when the work has clear file seams, interfaces can be defined before implementation starts, and each agent owns enough work to justify running in parallel. The build/test cycle being \u003e30 seconds amplifies the savings further.\n\nIf the work doesn't decompose cleanly, the Scout says so. It runs a suitability gate first and emits NOT SUITABLE rather than forcing a bad decomposition.\n\n## How Parallel Safety Works\n\nPolywave enforces two independent constraints that together make parallel execution correct:\n\n**Disjoint file ownership** prevents merge conflicts. Every file that will change is assigned to exactly one agent in the IMPL doc. No two agents in the same wave can produce edits to the same file, so the merge step is always conflict-free regardless of what agents do during execution.\n\n**Worktree isolation** prevents execution-time interference. Each agent works in its own git worktree - a separate directory that shares the same git history but has an independent file tree. This means concurrent `go build`, `go test`, and tool-cache writes don't race on shared build caches, lock files, or intermediate object files.\n\nNeither constraint substitutes for the other. Disjoint ownership without worktrees: merge is safe, but concurrent builds are flaky. Worktrees without disjoint ownership: execution is clean, but merge produces unresolvable conflicts. Both must hold for a wave to be correct and reproducible.\n\n**Cascade failures:** These happen when Agent A changes a function signature and Agent B's code breaks at integration time, even though both passed isolated tests. The post-merge verification gate catches these cross-package issues that individual agents can't see in their isolated worktrees.\n\n### Worktree Isolation Defense (6 layers)\n\nAgents don't always respect isolation instructions. Polywave treats worktree isolation as an infrastructure problem, not a cooperation problem, with hook-based enforcement (E43) as the primary mechanism.\n\n(Layers numbered 0-4, plus E43 hook-based enforcement. Layer 0 is the foundational prevention layer; higher layers add defense-in-depth.)\n\n| Layer | Mechanism | Type |\n|-------|-----------|------|\n| **E43** | **Hook-based enforcement** - Claude Code lifecycle hooks (SubagentStart, PreToolUse:Bash, PreToolUse:Write/Edit, SubagentStop) automatically inject environment variables, prepend cd commands to bash calls, and block out-of-bounds writes at the tool boundary. Violations become impossible rather than merely detected. See E43 in `protocol/execution-rules.md`. | **Prevention (Primary)** |\n| 0 | **Pre-commit hook** - installed automatically by `polywave-tools create-worktrees` (embedded in Go SDK at `pkg/worktree/manager.go`). Blocks commits to main during active waves. Agents receive an instructive error. Orchestrator bypasses via `POLYWAVE_ALLOW_MAIN_COMMIT=1`. | Prevention |\n| 1 | **Manual worktree pre-creation** - Orchestrator creates all worktrees before any agent launches | Deterministic |\n| 2 | **`isolation: \"worktree\"` parameter** - each agent launch specifies worktree isolation at the tool level. **Omitted for cross-repo waves** (would create worktrees in the wrong repo); Layer 1 and Layer 3 provide isolation instead. See `saw-worktree.md` Cross-Repo Mode. | Tool-level |\n| 3 | **Field 0 self-verification** - agents confirm branch via brief check (primary enforcement is the `validate_worktree_isolation` SubagentStart hook) | Cooperative |\n| 4 | **Merge-time trip wire** - Orchestrator counts commits per worktree branch before merging. Zero commits = isolation failure. Stops with recovery options. | Deterministic |\n\nE43 (hook-based enforcement) and Layers 0 and 4 are the structural guarantees: E43 prevents violations at the tool boundary, Layer 0 prevents agents from committing to main, Layer 4 detects if isolation failed by any mechanism. Layers 1-3 are defense-in-depth.\n\n## Building a New Implementation\n\nTo implement Polywave in a different runtime (Python, Rust, TypeScript, etc.):\n\n1. Read protocol docs in order: [participants](protocol/participants.md) → [preconditions](protocol/preconditions.md) → [invariants](protocol/invariants.md) → [execution-rules](protocol/execution-rules.md) → [state-machine](protocol/state-machine.md) → [message-formats](protocol/message-formats.md) → [procedures](protocol/procedures.md)\n2. Identify which participant roles your runtime will support (minimum: Orchestrator + Wave Agent)\n3. Choose an isolation mechanism that satisfies I1 (disjoint file ownership): git worktrees, filesystem snapshots, containers, etc.\n4. Use the [protocol/](protocol/) specification as reference for orchestrator logic\n5. Use [protocol/message-formats.md](protocol/message-formats.md) as reference for IMPL doc structure and message schemas\n6. Verify your implementation satisfies all six invariants (I1–I6) defined in [protocol/invariants.md](protocol/invariants.md)\n\nSee [protocol/README.md](protocol/README.md) for the full adoption guide.\n\n## Polywave-Teams (Experimental)\n\n[`docs/proposals/polywave-teams/`](docs/proposals/polywave-teams/) is an alternate execution layer using Claude Code Agent Teams. Same protocol, same IMPL doc, same Scout. Different wave plumbing: teammates replace background Agent tool calls, providing inter-agent messaging and real-time deviation alerts. Trade-off: better visibility during execution, worse crash recovery. See [`docs/proposals/polywave-teams/README.md`](docs/proposals/polywave-teams/README.md) for setup and usage.\n\n## Blog Post\n\nFour-part series on the pattern, the lessons learned from dogfooding it, and how the protocol evolved:\n\n1. [Polywave: A Coordination Pattern for Parallel AI Agents](https://blog.blackwell-systems.com/posts/polywave/). The pattern: failure modes of naive parallelism, the scout deliverable, wave execution, and a worked example from brewprune.\n2. [Polywave, Part 2: What Dogfooding Taught Us](https://blog.blackwell-systems.com/posts/polywave-part2/). The audit-fix-audit loop, overhead measurement (88% slower when ignored), Quick mode, and the bootstrap problem for new projects.\n3. [Polywave, Part 3: Five Failures, Five Fixes](https://blog.blackwell-systems.com/posts/polywave-part3/). How the skill file decomposed from a 400-line monolith, why version headers matter, and five scout prompt fixes driven by real failures.\n4. [Polywave, Part 4: Trust Is Structural](https://blog.blackwell-systems.com/posts/polywave-part4/). The Scaffold Agent, the 5-layer worktree isolation defense, and why correctness belongs in infrastructure rather than cooperation.\n\n## License\n\n[MIT OR Apache-2.0](LICENSE)\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fblackwell-systems%2Fpolywave","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fblackwell-systems%2Fpolywave","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fblackwell-systems%2Fpolywave/lists"}