{"_id":"@avivkaplan/beads-orchestration","_rev":"6-b3227a34e8c6467cb57996b3a7520c81","name":"@avivkaplan/beads-orchestration","dist-tags":{"latest":"1.4.0"},"versions":{"1.0.0":{"name":"@avivkaplan/beads-orchestration","version":"1.0.0","keywords":["claude","claude-code","orchestration","ai-agents","task-management","beads"],"author":{"name":"Aviv Kaplan"},"license":"MIT","_id":"@avivkaplan/beads-orchestration@1.0.0","maintainers":[{"name":"avivk5498","email":"aviv@avivkaplan.com"}],"homepage":"https://github.com/AvivK5498/Claude-Code-Beads-Orchestration#readme","bugs":{"url":"https://github.com/AvivK5498/Claude-Code-Beads-Orchestration/issues"},"os":["darwin","linux"],"bin":{"beads-orchestration":"scripts/cli.js"},"dist":{"shasum":"40d2b508bfd6c99c190a10a03f3455a89c3970ed","tarball":"https://registry.npmjs.org/@avivkaplan/beads-orchestration/-/beads-orchestration-1.0.0.tgz","fileCount":35,"integrity":"sha512-gs6c62TiBusnpTe0lWlw0wewpOj+5kJROUJ1YBpWWcQP0nOwxYqCC5zJSBM9swFMNTzgjaCNEkrbhi2kgfVZhw==","signatures":[{"sig":"MEUCIQDY2mnHuQ3xJ5OJHbdIeB1hJy6N4BgZkkBBjTj0WPzFrwIgch0Ceo47NB+hshQ33Xz0I3f+nfiQ+odU60G2Wrsbwg8=","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"unpackedSize":137319},"gitHead":"b5e2f1d6b7105d5f19c1f15ccc07e8abd8482ac8","scripts":{"postinstall":"node scripts/postinstall.js"},"_npmUser":{"name":"avivk5498","email":"aviv@avivkaplan.com"},"repository":{"url":"git+https://github.com/AvivK5498/Claude-Code-Beads-Orchestration.git","type":"git"},"_npmVersion":"10.9.4","description":"Multi-agent orchestration for Claude Code with automatic task management","directories":{},"_nodeVersion":"22.21.1","_hasShrinkwrap":false,"_npmOperationalInternal":{"tmp":"tmp/beads-orchestration_1.0.0_1769018519629_0.3940800651694023","host":"s3://npm-registry-packages-npm-production"}},"1.0.1":{"name":"@avivkaplan/beads-orchestration","version":"1.0.1","keywords":["claude","claude-code","orchestration","ai-agents","task-management","beads"],"author":{"name":"Aviv Kaplan"},"license":"MIT","_id":"@avivkaplan/beads-orchestration@1.0.1","maintainers":[{"name":"avivk5498","email":"aviv@avivkaplan.com"}],"homepage":"https://github.com/AvivK5498/Claude-Code-Beads-Orchestration#readme","bugs":{"url":"https://github.com/AvivK5498/Claude-Code-Beads-Orchestration/issues"},"os":["darwin","linux"],"bin":{"beads-orchestration":"scripts/cli.js"},"dist":{"shasum":"8d27cc87b732a1af2fa0f9e86e8f650378040d9e","tarball":"https://registry.npmjs.org/@avivkaplan/beads-orchestration/-/beads-orchestration-1.0.1.tgz","fileCount":36,"integrity":"sha512-EfABewFj5uA3ZgH6gEsCLFZtV9JRu5pfDiYs6ULo6eMqReBsk9BsThl9FoyG89/ZPNzPXj08SCcZxX/kjKzCCg==","signatures":[{"sig":"MEUCIQC7bVSbxToSu5En22Wx/eeiFoknWVC2ymDADOwTT6ONrgIgL2a42ij8oYKXUTrsZdPz1PkOZY3EeXCMmB3JeeRGxX8=","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"unpackedSize":139009},"gitHead":"cf8ff2cfd9a856608a0ea0d0e78d6293aff14bcf","scripts":{"postinstall":"node scripts/postinstall.js"},"_npmUser":{"name":"avivk5498","email":"aviv@avivkaplan.com"},"repository":{"url":"git+https://github.com/AvivK5498/Claude-Code-Beads-Orchestration.git","type":"git"},"_npmVersion":"10.9.4","description":"Multi-agent orchestration for Claude Code with automatic task management","directories":{},"_nodeVersion":"22.21.1","_hasShrinkwrap":false,"_npmOperationalInternal":{"tmp":"tmp/beads-orchestration_1.0.1_1769069614453_0.8251358850572923","host":"s3://npm-registry-packages-npm-production"}},"1.1.0":{"name":"@avivkaplan/beads-orchestration","version":"1.1.0","keywords":["claude","claude-code","orchestration","ai-agents","task-management","beads"],"author":{"name":"Aviv Kaplan"},"license":"MIT","_id":"@avivkaplan/beads-orchestration@1.1.0","maintainers":[{"name":"avivk5498","email":"aviv@avivkaplan.com"}],"homepage":"https://github.com/AvivK5498/Claude-Code-Beads-Orchestration#readme","bugs":{"url":"https://github.com/AvivK5498/Claude-Code-Beads-Orchestration/issues"},"os":["darwin","linux"],"bin":{"beads-orchestration":"scripts/cli.js"},"dist":{"shasum":"a73ae3cd7aa0992724c2f4ad9d284cb2af0c3acd","tarball":"https://registry.npmjs.org/@avivkaplan/beads-orchestration/-/beads-orchestration-1.1.0.tgz","fileCount":36,"integrity":"sha512-R3PudxApsQPUex5JzXpt2qDDggQfI9WyFbUNhjiDLzLmkLQbp28S4CHjQA+XA57D95Uy6ENdvxmEC9YBzUG5Eg==","signatures":[{"sig":"MEUCIDq3MvZxhPQCb0kTjyhAhL6ituobf6+nadVizOPlxOAyAiEA62cRck++f5Tl8HvCep0Y6/e4+WKo26SZcSkNPboRyQw=","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"unpackedSize":150968},"gitHead":"b08f491ee15d9167fb212e0142b08df89b410549","scripts":{"postinstall":"node scripts/postinstall.js"},"_npmUser":{"name":"avivk5498","email":"aviv@avivkaplan.com"},"repository":{"url":"git+https://github.com/AvivK5498/Claude-Code-Beads-Orchestration.git","type":"git"},"_npmVersion":"10.9.4","description":"Multi-agent orchestration for Claude Code with automatic task management","directories":{},"_nodeVersion":"22.21.1","_hasShrinkwrap":false,"_npmOperationalInternal":{"tmp":"tmp/beads-orchestration_1.1.0_1769177171659_0.01352756831585622","host":"s3://npm-registry-packages-npm-production"}},"1.2.0":{"name":"@avivkaplan/beads-orchestration","version":"1.2.0","keywords":["claude","claude-code","orchestration","ai-agents","task-management","beads"],"author":{"name":"Aviv Kaplan"},"license":"MIT","_id":"@avivkaplan/beads-orchestration@1.2.0","maintainers":[{"name":"avivk5498","email":"aviv@avivkaplan.com"}],"homepage":"https://github.com/AvivK5498/Claude-Code-Beads-Orchestration#readme","bugs":{"url":"https://github.com/AvivK5498/Claude-Code-Beads-Orchestration/issues"},"os":["darwin","linux"],"bin":{"beads-orchestration":"scripts/cli.js"},"dist":{"shasum":"44086d4f615ba1e807aa23c8c598d7131c0b3a5d","tarball":"https://registry.npmjs.org/@avivkaplan/beads-orchestration/-/beads-orchestration-1.2.0.tgz","fileCount":37,"integrity":"sha512-ZgyxejxCdQ4MxKbo6l9AfagdvObeso70feeSqZ+7/RtkPjt6fVJfaJzuyIPnHiaTzpOmgU8qovx9mDbTnwjnQg==","signatures":[{"sig":"MEYCIQD02dYinhY/i5xxk51ycrKoJoGi4tBz3/IATfnpxfx7awIhAMrTrP369pXZq0km/KC/c09T9TcmZUy/n6rf3grRa/FW","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"unpackedSize":160552},"gitHead":"b08f491ee15d9167fb212e0142b08df89b410549","scripts":{"postinstall":"node scripts/postinstall.js"},"_npmUser":{"name":"avivk5498","email":"aviv@avivkaplan.com"},"repository":{"url":"git+https://github.com/AvivK5498/Claude-Code-Beads-Orchestration.git","type":"git"},"_npmVersion":"10.9.4","description":"Multi-agent orchestration for Claude Code with automatic task management","directories":{},"_nodeVersion":"22.21.1","_hasShrinkwrap":false,"_npmOperationalInternal":{"tmp":"tmp/beads-orchestration_1.2.0_1769506846112_0.3886281297399383","host":"s3://npm-registry-packages-npm-production"}},"1.3.0":{"name":"@avivkaplan/beads-orchestration","version":"1.3.0","keywords":["claude","claude-code","orchestration","ai-agents","task-management","beads"],"author":{"name":"Aviv Kaplan"},"license":"MIT","_id":"@avivkaplan/beads-orchestration@1.3.0","maintainers":[{"name":"avivk5498","email":"aviv@avivkaplan.com"}],"homepage":"https://github.com/AvivK5498/Claude-Code-Beads-Orchestration#readme","bugs":{"url":"https://github.com/AvivK5498/Claude-Code-Beads-Orchestration/issues"},"os":["darwin","linux"],"bin":{"beads-orchestration":"scripts/cli.js"},"dist":{"shasum":"33ffbb79cf64fe6046ef7e61746971c2843f292e","tarball":"https://registry.npmjs.org/@avivkaplan/beads-orchestration/-/beads-orchestration-1.3.0.tgz","fileCount":39,"integrity":"sha512-e0bCoRnCX3hxAgnzMEcBmsYoxEMIOCJzleOQ7P43B75LCHxVBfRlgvMi2f9YsHjRuzS9LrGs14tOPwJgxxl2PA==","signatures":[{"sig":"MEYCIQC//wfdVns06cbOJz2jPw97Ddm5LK8NUJJTojabKiSFiQIhAO2NRNiUoQ4d2xmItBXSTGULcpZowci4v+sF+XOSmbvt","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"unpackedSize":171882},"gitHead":"6d7ab9ecb8aa66ffdac21839df019e63cf2bbb5a","scripts":{"postinstall":"node scripts/postinstall.js"},"_npmUser":{"name":"avivk5498","email":"aviv@avivkaplan.com"},"repository":{"url":"git+https://github.com/AvivK5498/Claude-Code-Beads-Orchestration.git","type":"git"},"_npmVersion":"10.9.4","description":"Multi-agent orchestration for Claude Code with automatic task management","directories":{},"_nodeVersion":"22.21.1","_hasShrinkwrap":false,"_npmOperationalInternal":{"tmp":"tmp/beads-orchestration_1.3.0_1769507498236_0.41784510645502526","host":"s3://npm-registry-packages-npm-production"}},"1.4.0":{"name":"@avivkaplan/beads-orchestration","version":"1.4.0","description":"Multi-agent orchestration for Claude Code with automatic task management","author":{"name":"Aviv Kaplan"},"license":"MIT","repository":{"type":"git","url":"git+https://github.com/AvivK5498/Claude-Code-Beads-Orchestration.git"},"keywords":["claude","claude-code","orchestration","ai-agents","task-management","beads"],"os":["darwin","linux"],"scripts":{"postinstall":"node scripts/postinstall.js"},"bin":{"beads-orchestration":"scripts/cli.js"},"_id":"@avivkaplan/beads-orchestration@1.4.0","gitHead":"84bfc88fa14036d59ac5f53128d688e10bde4ae2","bugs":{"url":"https://github.com/AvivK5498/Claude-Code-Beads-Orchestration/issues"},"homepage":"https://github.com/AvivK5498/Claude-Code-Beads-Orchestration#readme","_nodeVersion":"22.21.1","_npmVersion":"10.9.4","dist":{"integrity":"sha512-EvNEoZxF7N11YED+f5YPnnv4z+zVY2zYfMxYuSmILl6F2C6xQNJ686j57LSb5PPkNlRdqykvOTCGrGp3JRB+mg==","shasum":"5d837520a34bc8dccd7260aec288a063eeadb321","tarball":"https://registry.npmjs.org/@avivkaplan/beads-orchestration/-/beads-orchestration-1.4.0.tgz","fileCount":40,"unpackedSize":176291,"signatures":[{"keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U","sig":"MEUCIDf8hZtJXXZP4FH+BHjkNdfFOH7EXvK1KEDA1WoZ3Q2EAiEAwLEUHvy0qR//ga/LtgFnf3p7vYshF5JvmsaByMPtf4Y="}]},"_npmUser":{"name":"avivk5498","email":"aviv@avivkaplan.com"},"directories":{},"maintainers":[{"name":"avivk5498","email":"aviv@avivkaplan.com"}],"_npmOperationalInternal":{"host":"s3://npm-registry-packages-npm-production","tmp":"tmp/beads-orchestration_1.4.0_1769549861667_0.9998192934963066"},"_hasShrinkwrap":false}},"time":{"created":"2026-01-21T18:01:59.574Z","modified":"2026-01-27T21:37:41.939Z","1.0.0":"2026-01-21T18:01:59.785Z","1.0.1":"2026-01-22T08:13:34.616Z","1.1.0":"2026-01-23T14:06:11.834Z","1.2.0":"2026-01-27T09:40:46.265Z","1.3.0":"2026-01-27T09:51:38.370Z","1.4.0":"2026-01-27T21:37:41.823Z"},"bugs":{"url":"https://github.com/AvivK5498/Claude-Code-Beads-Orchestration/issues"},"author":{"name":"Aviv Kaplan"},"license":"MIT","homepage":"https://github.com/AvivK5498/Claude-Code-Beads-Orchestration#readme","keywords":["claude","claude-code","orchestration","ai-agents","task-management","beads"],"repository":{"type":"git","url":"git+https://github.com/AvivK5498/Claude-Code-Beads-Orchestration.git"},"description":"Multi-agent orchestration for Claude Code with automatic task management","maintainers":[{"name":"avivk5498","email":"aviv@avivkaplan.com"}],"readme":"# Beads Orchestration\n\nMulti-agent orchestration for Claude Code. An orchestrator investigates issues, manages tasks automatically, and delegates implementation to specialized supervisors.\n\n**[Beads Kanban UI](https://github.com/AvivK5498/Beads-Kanban-UI)** — Visual task management fully compatible with this workflow. Supports tasks, epics, subtasks, dependencies, and design docs.\n\n## Installation\n\n```bash\nnpx skills add AvivK5498/Claude-Code-Beads-Orchestration\n```\n\nOr via npm:\n\n```bash\nnpm install -g @avivkaplan/beads-orchestration\n```\n\n> macOS and Linux only.\n\n## Quick Start\n\n```bash\n# In any Claude Code session\n/create-beads-orchestration\n```\n\nThe skill walks you through setup, runs the bootstrap via `npx`, then creates tech-specific supervisors based on your codebase.\n\n### Requirements\n\n- Claude Code with hooks support\n- Node.js (for npx)\n- Python 3 (for bootstrap)\n- beads CLI (installed automatically by bootstrap)\n\n## Key Features\n\n🔍 **Investigate → Delegate** — Orchestrator reads code, supervisors implement. Hooks enforce separation.\n\n🌳 **Worktree isolation** — Every task gets its own worktree. Main stays clean. Parallel work without conflicts.\n\n📋 **Auto task tracking** — [Beads](https://github.com/steveyegge/beads) create, track, and close tasks automatically.\n\n🔗 **Epics & dependencies** — Cross-domain work becomes epics with enforced child dependencies. Independent children dispatch in parallel.\n\n🔁 **Follow-up traceability** — Closed beads stay closed. Bug fixes become new beads linked via `bd dep relate` — full history, no reopening.\n\n🧠 **Knowledge base** — Agents capture conventions and gotchas into `.beads/memory/`. Enforced, searchable, surfaced at session start.\n\n🔒 **13 enforcement hooks** — Every workflow step is guarded. See [Hooks](#hooks).\n\n🔎 **Tech stack discovery** — Scans your codebase, creates the right supervisors with best practices injected.\n\n## How It Works\n\n```\n┌─────────────────────────────────────────┐\n│            ORCHESTRATOR                 │\n│  Investigates with Grep/Read/Glob       │\n│  Manages tasks automatically (beads)    │\n│  Delegates implementation via Task()    │\n└──────────────────┬──────────────────────┘\n                   │\n       ┌───────────┼───────────┐\n       ▼           ▼           ▼\n  ┌─────────┐ ┌─────────┐ ┌─────────┐\n  │ react-  │ │ python- │ │ nextjs- │\n  │supervisor│ │supervisor│ │supervisor│\n  └────┬────┘ └────┬────┘ └────┬────┘\n       │           │           │\n  .worktrees/ .worktrees/ .worktrees/\n  bd-BD-001   bd-BD-002   bd-BD-003\n```\n\n**Orchestrator:** Investigates the issue, identifies root cause, logs findings to bead, delegates with brief fix instructions.\n\n**Supervisors:** Read bead comments for context, create isolated worktrees, execute the fix confidently. Created by discovery agent based on your tech stack.\n\n## Knowledge Base\n\nAgents build a persistent knowledge base as they work. No extra steps — it piggybacks on `bd comment`.\n\n```bash\n# Supervisor finishes a task and records what it learned\nbd comment BD-001 \"LEARNED: TaskGroup requires @Sendable closures in strict concurrency mode.\"\n\n# Orchestrator logs investigation findings\nbd comment BD-002 \"INVESTIGATION: Root cause: SparkleAdapter.swift:45 - nil SUFeedURL crashes XMLParser.\"\n```\n\nAn async hook intercepts these comments and extracts them into `.beads/memory/knowledge.jsonl`. Each entry is auto-tagged by keyword and attributed to its source (orchestrator vs supervisor).\n\n**Why this works:**\n- Zero friction — agents already use `bd comment`, they just add a prefix\n- No database, no embeddings, no external services — one JSONL file, grep + jq to search\n- Enforced — supervisors are blocked from completing without a `LEARNED:` comment\n- Surfaces automatically — session start shows recent knowledge so agents don't re-investigate solved problems\n\n```bash\n# Search the knowledge base\n.beads/memory/recall.sh \"concurrency\"\n.beads/memory/recall.sh --recent 10\n.beads/memory/recall.sh --stats\n```\n\nSee [docs/memory-architecture.md](docs/memory-architecture.md) for the full design.\n\n## Bug Fixes & Follow-Up Work\n\nClosed beads are immutable. When a bug is found after a task was completed, a new bead is created and linked to the original:\n\n```bash\nbd create \"Fix: button click handler race condition\" -d \"Follow-up to BD-001\"\n# Returns: BD-005\n\nbd dep relate BD-005 BD-001   # Bidirectional \"see also\" — no dependency\n```\n\nThe `relates_to` link gives full traceability without reopening anything. A PreToolUse hook enforces this — dispatching a supervisor to a closed or done bead is blocked automatically, with instructions to create a new bead instead.\n\n**Why this matters:**\n- Merged branches don't get reused — avoids SHA conflicts from squash/rebase merges\n- Each fix gets its own worktree, PR, and LEARNED comment\n- Audit trail stays clean — one bead = one unit of work\n\n## What Gets Installed\n\n```\n.claude/\n├── agents/           # Supervisors (discovery creates tech-specific ones)\n├── hooks/            # Workflow enforcement (13 hooks)\n├── skills/           # subagents-discipline, react-best-practices\n└── settings.json\nCLAUDE.md             # Orchestrator instructions\n.beads/               # Task database\n  memory/             # Knowledge base (knowledge.jsonl + recall.sh)\n.worktrees/           # Isolated worktrees for each task (created dynamically)\n```\n\n## Hooks\n\n13 hooks enforce the workflow at every step. Grouped by lifecycle event:\n\n**PreToolUse** — Block before action happens:\n\n| Hook | Trigger | Purpose |\n|------|---------|---------|\n| `block-orchestrator-tools.sh` | Edit, Write | Orchestrator can't modify code directly |\n| `enforce-bead-for-supervisor.sh` | Task | Supervisors require BEAD_ID in prompt |\n| `enforce-branch-before-edit.sh` | Edit, Write | Must be in a worktree, not main |\n| `enforce-sequential-dispatch.sh` | Task | Blocks closed/done beads and epic children with unresolved deps |\n| `validate-epic-close.sh` | Bash | Can't close epic with open children |\n| `inject-discipline-reminder.sh` | Task | Injects discipline skill context |\n| `inject-memory-recall.sh` | Task | Reminds supervisors to search knowledge base before implementing |\n| `remind-inprogress.sh` | Task | Warns about existing in-progress beads |\n\n**PostToolUse** — React after action completes:\n\n| Hook | Trigger | Purpose |\n|------|---------|---------|\n| `enforce-concise-response.sh` | Task | Limits supervisor response verbosity |\n| `memory-capture.sh` | Bash | Captures LEARNED/INVESTIGATION into knowledge base |\n\n**SubagentStop** — Validate before supervisor exits:\n\n| Hook | Trigger | Purpose |\n|------|---------|---------|\n| `validate-completion.sh` | Any | Verifies worktree, push, bead status, LEARNED comment |\n\n**SessionStart** — Run when a new session begins:\n\n| Hook | Trigger | Purpose |\n|------|---------|---------|\n| `session-start.sh` | Any | Shows task status, recent knowledge, cleanup suggestions |\n\n**UserPromptSubmit** — Filter user input:\n\n| Hook | Trigger | Purpose |\n|------|---------|---------|\n| `clarify-vague-request.sh` | Any | Prompts for clarification on ambiguous requests |\n\n## Advanced: External Providers\n\nBy default, all agents run via Claude's Task(). If you want to delegate read-only agents (scout, detective, etc.) to Codex/Gemini instead:\n\n```bash\n/create-beads-orchestration --external-providers\n```\n\n**Additional requirements:**\n- Codex CLI: `codex login`\n- Gemini CLI (optional fallback)\n- uv: [install](https://github.com/astral-sh/uv)\n\nThis creates `.mcp.json` with provider-delegator config.\n\n## License\n\nMIT\n\n## Credits\n\n- [beads](https://github.com/steveyegge/beads) - Git-native task tracking by Steve Yegge\n- [sub-agents.directory](https://github.com/ayush-that/sub-agents.directory) - External agent templates\n","readmeFilename":"README.md"}