{"id":51508525,"url":"https://github.com/blackwell-systems/polywave-go","last_synced_at":"2026-07-08T03:30:36.020Z","repository":{"id":345520395,"uuid":"1175849509","full_name":"blackwell-systems/polywave-go","owner":"blackwell-systems","description":"Provider-agnostic parallel agent coordination for LLMs — Anthropic, OpenAI, Ollama, or any OpenAI-compatible endpoint. Parallel worktree isolation, interface contracts, and tier-gated execution at scale.","archived":false,"fork":false,"pushed_at":"2026-07-08T01:57:00.000Z","size":22975,"stargazers_count":2,"open_issues_count":1,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-07-08T03:26:42.342Z","etag":null,"topics":["agent-orchestration","agent-skills","agentic-coding","agentic-workflow","ai-agents","ai-coding","anthropic","autonomous-agents","claude-code","cli-tool","coordination-protocol","git-worktree","go-sdk","golang","llm-agents","llm-orchestration","multi-agent","multi-agent-systems","ollama","parallel-agents"],"latest_commit_sha":null,"homepage":null,"language":"Go","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":null,"security":null,"support":null,"governance":null,"roadmap":"docs/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-03-08T09:02:41.000Z","updated_at":"2026-07-08T01:57:06.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/blackwell-systems/polywave-go","commit_stats":null,"previous_names":["blackwell-systems/scout-and-wave-go","blackwell-systems/polywave-go"],"tags_count":8,"template":false,"template_full_name":null,"purl":"pkg:github/blackwell-systems/polywave-go","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/blackwell-systems%2Fpolywave-go","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/blackwell-systems%2Fpolywave-go/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/blackwell-systems%2Fpolywave-go/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/blackwell-systems%2Fpolywave-go/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/blackwell-systems","download_url":"https://codeload.github.com/blackwell-systems/polywave-go/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/blackwell-systems%2Fpolywave-go/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":35251015,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-26T15:22:16.424Z","status":"online","status_checked_at":"2026-07-08T02:00:06.796Z","response_time":61,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"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","agentic-coding","agentic-workflow","ai-agents","ai-coding","anthropic","autonomous-agents","claude-code","cli-tool","coordination-protocol","git-worktree","go-sdk","golang","llm-agents","llm-orchestration","multi-agent","multi-agent-systems","ollama","parallel-agents"],"created_at":"2026-07-08T03:30:35.352Z","updated_at":"2026-07-08T03:30:36.000Z","avatar_url":"https://github.com/blackwell-systems.png","language":"Go","funding_links":["https://buymeacoffee.com/blackwellsystems"],"categories":[],"sub_categories":[],"readme":"\u003cp align=\"center\"\u003e\n  \u003cimg src=\"assets/logo.png\" alt=\"Polywave\" width=\"600\"\u003e\n\u003c/p\u003e\n\n\u003ch1 align=\"center\"\u003epolywave-go\u003c/h1\u003e\n\n\u003cp align=\"center\"\u003e\n  \u003ca href=\"https://github.com/blackwell-systems\"\u003e\u003cimg src=\"https://raw.githubusercontent.com/blackwell-systems/blackwell-docs-theme/main/badge-trademark.svg\" alt=\"Blackwell Systems\" /\u003e\u003c/a\u003e\n  \u003ca href=\"https://github.com/blackwell-systems/polywave-go/actions/workflows/ci.yml\"\u003e\u003cimg src=\"https://github.com/blackwell-systems/polywave-go/actions/workflows/ci.yml/badge.svg\" alt=\"CI\" /\u003e\u003c/a\u003e\n  \u003ca href=\"https://github.com/blackwell-systems/polywave-go/releases\"\u003e\u003cimg src=\"https://img.shields.io/github/v/release/blackwell-systems/polywave-go\" alt=\"Release\" /\u003e\u003c/a\u003e\n  \u003ca href=\"https://buymeacoffee.com/blackwellsystems\"\u003e\u003cimg src=\"https://img.shields.io/badge/buy%20me%20a%20coffee-donate-yellow.svg\" alt=\"Buy Me A Coffee\" /\u003e\u003c/a\u003e\n\u003c/p\u003e\n\n\u003cp align=\"center\"\u003eGo engine, Protocol SDK, and \u003ccode\u003epolywave-tools\u003c/code\u003e CLI for Polywave: a coordination protocol for parallel AI agent development that makes merge conflicts structurally impossible when work can be decomposed safely.\u003c/p\u003e\n\n\u003e **Using Claude Code?** Start at [polywave](https://github.com/blackwell-systems/polywave) for the Agent Skill and install guide. This repo provides the engine and CLI that the skill depends on.\n\nPolywave is not a generic agent runner. It is a protocol for deciding when parallel agent work is suitable, partitioning that work by file ownership, enforcing the partition before agents start, and merging completed work through deterministic gates.\n\n---\n\n## The Core Guarantee\n\n**No two agents in the same wave own the same file** (I1: Disjoint File Ownership).\n\nThis is a hard constraint, not a convention. Polywave validates the ownership partition before creating worktrees. Branches and worktrees isolate concurrent edits, but they do not prevent two agents from independently modifying the same file and producing a merge conflict later. Polywave prevents that conflict from being possible on agent-owned files.\n\nThe result: when the suitability gate passes and invariants hold, parallel agents can work independently, commit independently, and merge mechanically.\n\n---\n\n## When To Use Polywave\n\nUse Polywave for agentic development when the work has real parallel structure:\n\n- Multi-file feature work with separable modules or components\n- Refactors that can be split by package, route, service, adapter, or UI area\n- Audit-remediation work after findings have been classified\n- Multi-feature programs where tier ordering and shared contracts matter\n- Tasks where build/test verification is expensive enough that parallelism pays for the orchestration overhead\n\nDo not use Polywave for every edit. The protocol runs a mandatory suitability gate that answers five questions before producing any agent prompts. If work does not decompose cleanly, the Scout returns `NOT_SUITABLE` and stops. This is a structural boundary, not a suggestion.\n\nPolywave is usually the wrong tool for:\n\n- Tiny one-file changes\n- Investigation-first debugging where the root cause is unknown\n- Work where cross-agent interfaces cannot be defined before implementation\n- Highly coupled edits to the same central file\n- Exploratory prototypes where discovery is more valuable than execution discipline\n\nThis is intentional. The protocol includes its own \"do not use Polywave here\" decision point.\n\n---\n\n## Install\n\n```bash\n# Homebrew (macOS/Linux)\nbrew install blackwell-systems/tap/polywave-tools\n\n# Or via Go install\ngo install github.com/blackwell-systems/polywave-go/cmd/polywave-tools@latest\n```\n\n\u003cdetails\u003e\n\u003csummary\u003eDownload a pre-built binary\u003c/summary\u003e\n\nPre-built binaries for macOS and Linux are attached to every [GitHub release](https://github.com/blackwell-systems/polywave-go/releases/latest).\n\n```bash\n# macOS Apple Silicon example\nVERSION=$(curl -sI https://github.com/blackwell-systems/polywave-go/releases/latest | grep -i location | sed 's|.*/v||;s/\\r//')\ncurl -sL \"https://github.com/blackwell-systems/polywave-go/releases/download/v${VERSION}/polywave-tools_${VERSION}_darwin_arm64.tar.gz\" | tar xz\nmkdir -p ~/.local/bin \u0026\u0026 mv polywave-tools ~/.local/bin/\n```\n\nAvailable archives:\n\n- `polywave-tools_{version}_darwin_arm64.tar.gz`\n- `polywave-tools_{version}_darwin_amd64.tar.gz`\n- `polywave-tools_{version}_linux_amd64.tar.gz`\n- `polywave-tools_{version}_linux_arm64.tar.gz`\n\u003c/details\u003e\n\n\u003cdetails\u003e\n\u003csummary\u003eBuild from source\u003c/summary\u003e\n\n```bash\ngo build -o polywave-tools ./cmd/polywave-tools\ncp polywave-tools ~/.local/bin/polywave-tools\n```\n\u003c/details\u003e\n\n---\n\n## Quickstart\n\nInitialize a repository:\n\n```bash\ncd your-project\npolywave-tools init\n```\n\nProduce or validate an IMPL manifest:\n\n```bash\npolywave-tools run-scout \"Add rate limiting to the API\" --repo-dir \"$PWD\"\npolywave-tools validate docs/IMPL/IMPL-rate-limiting.yaml\n```\n\nPrepare and finalize the first wave:\n\n```bash\npolywave-tools prepare-wave docs/IMPL/IMPL-rate-limiting.yaml --wave 1 --repo-dir \"$PWD\"\n\n# Agents run in their assigned worktrees, commit, and write completion reports.\n\npolywave-tools finalize-wave docs/IMPL/IMPL-rate-limiting.yaml --wave 1 --repo-dir \"$PWD\"\n```\n\nClaude Code users normally invoke the higher-level `/polywave` AgentSkills workflow. This repository provides the Go engine and CLI that make the protocol executable.\n\n---\n\n## How It Works\n\nPolywave execution has three core phases.\n\n**Scout:** An agent analyzes the repository, runs the suitability gate, designs the file ownership partition, defines cross-agent interface contracts, and writes an IMPL manifest.\n\n**Wave:** Parallel agents execute concurrently. Each agent owns a disjoint set of files, works in its own git worktree, implements against pre-committed scaffold files, commits its changes, and writes a completion report back to the IMPL manifest.\n\n**Merge + Verify:** `finalize-wave` verifies commits, checks completion reports, predicts conflicts, scans for stubs, runs quality gates, merges agent branches, verifies the merged build, records integration gaps, and cleans up worktrees.\n\nWave N+1 does not launch until Wave N has merged and passed post-merge verification. Later waves coordinate through committed code, not direct agent-to-agent communication.\n\n---\n\n## The IMPL Manifest\n\nThe IMPL manifest is the single source of truth for a feature. Chat output is not protocol state.\n\nIt records:\n\n- Suitability verdict and reasoning\n- File ownership by agent, wave, and repository\n- Interface contracts and scaffold status\n- Quality gates\n- Wave structure and agent prompts\n- Completion reports\n- Stub, wiring, and integration reports\n- Protocol state\n\nAbbreviated example:\n\n```yaml\ntitle: \"API rate limiting\"\nfeature_slug: \"rate-limiting\"\nrepository: \"/path/to/repo\"\nstate: \"REVIEWED\"\nverdict: \"SUITABLE\"\ntest_command: \"go test ./...\"\nlint_command: \"go vet ./...\"\n\nfile_ownership:\n  - file: \"pkg/ratelimit/limiter.go\"\n    agent: \"A\"\n    wave: 1\n    action: \"new\"\n  - file: \"internal/api/middleware.go\"\n    agent: \"B\"\n    wave: 1\n    action: \"modify\"\n\ninterface_contracts:\n  - name: \"Limiter\"\n    location: \"pkg/ratelimit/limiter.go\"\n    definition: \"type Limiter interface { Allow(key string) bool }\"\n\nwaves:\n  - number: 1\n    agents:\n      - id: \"A\"\n        task: \"Implement the limiter package.\"\n        files: [\"pkg/ratelimit/limiter.go\"]\n      - id: \"B\"\n        task: \"Wire the limiter into API middleware.\"\n        files: [\"internal/api/middleware.go\"]\n        dependencies: []\n```\n\nAll structural operations on this manifest are deterministic Go code. LLMs analyze and implement; the SDK validates, gates, and records.\n\n---\n\n## What This Repo Provides\n\n- **Protocol SDK:** Importable Go package for manifests, invariants, validation, state transitions, conflict prediction, gates, and program-level manifests.\n- **Engine:** High-level lifecycle entrypoints for Scout, Planner, wave preparation, wave finalization, tier execution, autonomy, retry, and integration validation.\n- **CLI:** `polywave-tools`, a command-line interface over the protocol and engine.\n- **Agent runtime:** Complete agentic tool-use loop in native Go. Sends prompts with tool schemas, parses tool-call responses, executes tools (file I/O, shell commands, git operations), feeds results back, and iterates until the agent signals completion. This is a self-contained agent SDK; no external framework (LangGraph, CrewAI, AutoGen) is required.\n- **Agent backends:** Provider routing for Anthropic, OpenAI-compatible APIs, AWS Bedrock, Ollama, LM Studio, and local CLI execution. Any model behind an OpenAI-compatible endpoint works, including local models via Ollama or vLLM.\n- **Program layer:** Tier-gated execution of multiple IMPLs with shared contract freezing.\n\nProvider routing uses model prefixes:\n\n| Prefix | Backend |\n|--------|---------|\n| `anthropic:` | Anthropic API |\n| `openai:` | OpenAI-compatible endpoint |\n| `bedrock:` | AWS Bedrock |\n| `ollama:` | Ollama OpenAI-compatible endpoint |\n| `lmstudio:` | LM Studio OpenAI-compatible endpoint |\n| `cli:` | Local CLI binary |\n| *(none)* | Auto-detect from environment |\n\nEach agent may specify its own `model:` in the IMPL manifest, so one wave can mix providers and model sizes without changing orchestration code.\n\nFor fully local execution, point at an Ollama instance:\n\n```bash\npolywave-tools run-scout \"add rate limiting\" --model ollama:qwen2.5-coder:32b --repo-dir \"$PWD\"\n```\n\nNo API keys, no external services, no Python dependencies. The engine drives the full tool-use loop natively in Go.\n\n---\n\n## No External Agent Framework Required\n\nMost multi-agent systems depend on Python agent SDKs (LangGraph, CrewAI, AutoGen, Pydantic AI) to provide the tool-use loop: the cycle of sending a prompt, parsing tool calls, executing tools, feeding results back, and iterating until completion.\n\npolywave-go implements this loop natively in Go. The `pkg/agent` package is a complete agent runtime:\n\n- **Tool schema generation:** file read/write, shell execution, git operations, formatted as model-native tool definitions\n- **Response parsing:** extracts tool calls from streaming model responses (Anthropic tool_use blocks, OpenAI function_call format)\n- **Tool execution:** runs the requested operation in the agent's assigned worktree\n- **Result feeding:** appends tool results to the conversation and re-prompts\n- **Termination detection:** recognizes when the agent signals completion\n- **Streaming:** real-time output via callback for observability and web UI integration\n\nThis means:\n- **Zero Python in the stack.** Single static Go binary. No virtualenvs, no pip, no dependency conflicts.\n- **Any model works.** Anthropic, OpenAI, Bedrock, or any local model via Ollama/LM Studio/vLLM. Same tool-use loop regardless of provider.\n- **Fully programmatic execution.** Import `pkg/engine` into your own Go code and run waves without a CLI or interactive session.\n- **Unattended operation.** `polywave-tools daemon` processes queued IMPLs with no human in the loop.\n\nThe protocol validates all output regardless of which model produced it. A local 7B model's scout output goes through the same validation gates as Claude Opus. Bad decompositions fail structurally; they don't produce unsafe merges.\n\n---\n\n## Essential CLI Commands\n\n| Command | Purpose |\n|---------|---------|\n| `init` | Detect project language and default build/test commands |\n| `run-scout` | Launch Scout and produce an IMPL manifest |\n| `validate` | Validate IMPL manifest structure and invariants |\n| `prepare-wave` | Run baseline gates, create worktrees, extract briefs, initialize journals |\n| `finalize-wave` | Verify, gate, merge, build, and clean up a wave |\n| `check-conflicts` | Enforce I1 file ownership disjointness |\n| `validate-scaffolds` | Verify scaffold files are committed before launch |\n| `freeze-check` | Enforce interface contract freeze |\n| `validate-integration` | Detect wiring and integration gaps |\n| `set-completion` | Record an agent completion report |\n| `set-impl-state` | Apply a protocol state transition |\n| `resume-detect` | Detect interrupted sessions |\n| `daemon` | Run queued IMPLs under autonomy settings |\n\nThe CLI contains many more single-purpose commands for advanced validation, program execution, review, retry, observability, and recovery. See [`cmd/polywave-tools/README.md`](cmd/polywave-tools/README.md) for command-level reference.\n\n---\n\n## Protocol SDK\n\nThe `pkg/protocol` package is the deterministic core. It has no LLM dependency.\n\n```go\nimport \"github.com/blackwell-systems/polywave-go/pkg/protocol\"\n\nmanifest, err := protocol.Load(ctx, \"docs/IMPL/IMPL-feature.yaml\")\nif err != nil {\n    return err\n}\n\nerrs := protocol.Validate(manifest)\ni1Errs := protocol.ValidateI1DisjointOwnership(manifest, 1)\nwave := protocol.CurrentWave(manifest)\n\n_ = i1Errs\n_ = wave\n\nprotocol.SetCompletionReport(manifest, \"A\", protocol.CompletionReport{\n    Status:       protocol.StatusComplete,\n    Commit:       \"abc123\",\n    Branch:       \"polywave/my-feature/wave1-agent-A\",\n    FilesCreated: []string{\"pkg/cache/cache.go\"},\n})\n\nsave := protocol.Save(ctx, manifest, \"docs/IMPL/IMPL-feature.yaml\")\nif save.IsFatal() {\n    return fmt.Errorf(\"save failed: %v\", save.Errors)\n}\n```\n\nInvariant enforcement:\n\n| Invariant | Enforcement |\n|-----------|-------------|\n| I1: Disjoint file ownership | `Validate`, `check-conflicts`, prepare-wave fast-fail, merge prediction |\n| I2: Interface contracts precede implementation | Scaffold validation and freeze checks before worktree launch |\n| I3: Wave sequencing | Prepare-wave blocks later waves until prior waves complete |\n| I4: IMPL manifest is source of truth | Completion reports and state transitions are manifest writes |\n| I5: Agents commit before reporting | Completion report validation and `verify-commits` gate |\n| I6: Role separation | Agent role boundaries, Scout write-boundary checks, and orchestration discipline |\n\n---\n\n## Program Layer\n\nFor larger work, a PROGRAM manifest coordinates multiple IMPL manifests through tiers.\n\n- Same-tier IMPLs must be independent.\n- Later tiers may depend on earlier tiers.\n- Program contracts are materialized and frozen before downstream Scouts consume them.\n- Tier gates block advancement on failure.\n- IMPL branches isolate in-progress tier work until the tier is finalized.\n\nThis extends the same idea as waves: tiers are to IMPLs what waves are to agents.\n\n---\n\n## Architecture\n\nFive repositories separate the protocol, skills, engine, and UI:\n\n| Repository | Purpose |\n|-----------|---------|\n| [polywave-protocol](https://github.com/blackwell-systems/polywave-protocol) | Normative protocol specification: invariants, execution rules, state machine, message formats |\n| [polywave](https://github.com/blackwell-systems/polywave) | Claude Code implementation: Agent Skill, hooks, agent prompts |\n| [polywave-codex](https://github.com/blackwell-systems/polywave-codex) | Codex CLI implementation: same protocol, different platform |\n| **polywave-go** | Go engine, Protocol SDK, and `polywave-tools` CLI |\n| [polywave-web](https://github.com/blackwell-systems/polywave-web) | Web UI and HTTP/SSE server using this engine |\n\nThe protocol repo defines the semantics. This repo implements them. The skill repos (polywave, polywave-codex) shape agent behavior on their respective platforms. The web repo provides an operator interface.\n\nPackage map:\n\n```text\npkg/\n├── protocol/       # Manifest types, validation, invariants, gates, merge logic\n├── engine/         # RunScout, PrepareWave, FinalizeWave, program/tier execution\n├── orchestrator/   # Wave orchestration, backend routing, event flow\n├── agent/          # Agent runtime and backend interface\n├── analyzer/       # Dependency, cascade, wiring, and shared-type analysis\n├── hooks/          # Boundary and prelaunch checks\n├── journal/        # Append-only execution trace and context recovery\n├── observability/  # Event model, metrics, SQLite store\n├── retry/          # Failure classification and retry support\n├── worktree/       # Git worktree management\n└── result/         # Canonical Result[T] error model\n\ninternal/\n└── git/            # Git command wrappers\n```\n\nSee [`pkg/README.md`](pkg/README.md) for a deeper package map.\n\n---\n\n## Development\n\n```bash\ngo build ./...\ngo test ./...\ngolangci-lint run\n```\n\nIf `go.work` points at local repositories that are not present on your machine, run package commands with workspace mode disabled:\n\n```bash\nGOWORK=off go test ./...\n```\n\n---\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-go","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fblackwell-systems%2Fpolywave-go","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fblackwell-systems%2Fpolywave-go/lists"}