{"_id":"@apapacho/the-agentic-flow","_rev":"8-2f547926f05c1a31e14d9764ef12943e","name":"@apapacho/the-agentic-flow","dist-tags":{"latest":"2.0.10"},"versions":{"2.0.0":{"name":"@apapacho/the-agentic-flow","version":"2.0.0","keywords":["claude","claude-code","orchestration","ai-agents","task-management","beads"],"author":{"name":"Jannes Kruse"},"license":"MIT","_id":"@apapacho/the-agentic-flow@2.0.0","maintainers":[{"name":"janneskruse","email":"jannes.kruse@rwth-aachen.de"}],"homepage":"https://github.com/janneskruse/the-agentic-flow#readme","bugs":{"url":"https://github.com/janneskruse/the-agentic-flow/issues"},"os":["darwin","linux"],"bin":{"beads-orchestration":"scripts/cli.js"},"dist":{"shasum":"2b619efe3a82eeff02d49b71315fec68622f8327","tarball":"https://registry.npmjs.org/@apapacho/the-agentic-flow/-/the-agentic-flow-2.0.0.tgz","fileCount":41,"integrity":"sha512-2iBpWik+Fiz+Y5TtLrJt0uCIXmzpgdio/gn4LG660953Ndkxixvowt7KgnycXN/vhxrssa66xIp0gtZB92S7rw==","signatures":[{"sig":"MEUCIBy+FuKYyEVXCsgIiJqve8bv03zvoEjnxU0ffNssb5mLAiEAmiTrtrL1YQr3PTZ5863ZUR3OSbNlFADWJvoSlyx1Ri8=","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"unpackedSize":188020},"gitHead":"9aad41b7a3edd31803a3b63e7c38f7aab04f62ee","scripts":{"postinstall":"node scripts/postinstall.js"},"_npmUser":{"name":"janneskruse","email":"jannes.kruse@rwth-aachen.de"},"repository":{"url":"git+https://github.com/janneskruse/the-agentic-flow.git","type":"git"},"_npmVersion":"11.6.1","description":"Multi-agent orchestration for Claude Code with automatic task management","directories":{},"_nodeVersion":"22.20.0","_hasShrinkwrap":false,"_npmOperationalInternal":{"tmp":"tmp/the-agentic-flow_2.0.0_1770232487096_0.5532405806796321","host":"s3://npm-registry-packages-npm-production"}},"2.0.1":{"name":"@apapacho/the-agentic-flow","version":"2.0.1","keywords":["claude","claude-code","orchestration","ai-agents","task-management","beads"],"author":{"name":"Jannes Kruse"},"license":"MIT","_id":"@apapacho/the-agentic-flow@2.0.1","maintainers":[{"name":"janneskruse","email":"jannes.kruse@rwth-aachen.de"}],"homepage":"https://github.com/janneskruse/the-agentic-flow#readme","bugs":{"url":"https://github.com/janneskruse/the-agentic-flow/issues"},"os":["darwin","linux"],"bin":{"beads-orchestration":"scripts/cli.js"},"dist":{"shasum":"3407b9f25dcb5125b768f91caab097d1ad8afd48","tarball":"https://registry.npmjs.org/@apapacho/the-agentic-flow/-/the-agentic-flow-2.0.1.tgz","fileCount":41,"integrity":"sha512-9Kq+T3dr6TeI5+w2dfi7CNVpMyNDyVZA0ksVRKiYs9UQjUSUvV7gkuSRk3tbMKXkbnRfhcpcIu04h1g0fztFEw==","signatures":[{"sig":"MEQCIFA8qqIAYbFDhfjhDCvVEkQLUl4SQxkEfYT5GQc0N/7XAiBZLpQAaxr7Chp8ImuuHiff7JXRtasUWxUJ6dr9eS84VA==","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"unpackedSize":188387},"gitHead":"476705be5d791d92b8a7c1e94e25b43703edb18f","scripts":{"postinstall":"node scripts/postinstall.js"},"_npmUser":{"name":"janneskruse","email":"jannes.kruse@rwth-aachen.de"},"repository":{"url":"git+https://github.com/janneskruse/the-agentic-flow.git","type":"git"},"_npmVersion":"11.6.1","description":"Multi-agent orchestration for Claude Code with automatic task management","directories":{},"_nodeVersion":"22.20.0","_hasShrinkwrap":false,"_npmOperationalInternal":{"tmp":"tmp/the-agentic-flow_2.0.1_1770235230656_0.25178412616444334","host":"s3://npm-registry-packages-npm-production"}},"2.0.2":{"name":"@apapacho/the-agentic-flow","version":"2.0.2","keywords":["claude","claude-code","orchestration","ai-agents","task-management","beads"],"author":{"name":"Jannes Kruse"},"license":"MIT","_id":"@apapacho/the-agentic-flow@2.0.2","maintainers":[{"name":"janneskruse","email":"jannes.kruse@rwth-aachen.de"}],"homepage":"https://github.com/janneskruse/the-agentic-flow#readme","bugs":{"url":"https://github.com/janneskruse/the-agentic-flow/issues"},"os":["darwin","linux","win32"],"bin":{"beads-orchestration":"scripts/cli.js"},"dist":{"shasum":"26a32e5ae157dd9413fe7e765327b03a29e0dbbc","tarball":"https://registry.npmjs.org/@apapacho/the-agentic-flow/-/the-agentic-flow-2.0.2.tgz","fileCount":41,"integrity":"sha512-4Y5teDu83qz14WkkRScfsuRV8BLmK8PYOCJTcosYZ3+Eer1ArbUYd028t7Aw7qf/IXyK3PEcjFdVgT/22JSJVg==","signatures":[{"sig":"MEYCIQCAY9elwTzg+XdyST03bI83nLLOo2pB/kKNRQiE88Xu9AIhAMywsdxeeiU18/FKxx4NorJPlZtCYZ1tPF++m18Tdj1g","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"unpackedSize":192636},"gitHead":"539742fd969ef6da72c43e4eaac01fb1eb25c416","scripts":{"postinstall":"node scripts/postinstall.js"},"_npmUser":{"name":"janneskruse","email":"jannes.kruse@rwth-aachen.de"},"repository":{"url":"git+https://github.com/janneskruse/the-agentic-flow.git","type":"git"},"_npmVersion":"11.6.1","description":"Multi-agent orchestration for Claude Code with automatic task management","directories":{},"_nodeVersion":"22.20.0","_hasShrinkwrap":false,"_npmOperationalInternal":{"tmp":"tmp/the-agentic-flow_2.0.2_1770237400677_0.09489967568099145","host":"s3://npm-registry-packages-npm-production"}},"2.0.6":{"name":"@apapacho/the-agentic-flow","version":"2.0.6","keywords":["claude","claude-code","orchestration","ai-agents","task-management","beads"],"author":{"name":"Jannes Kruse"},"license":"MIT","_id":"@apapacho/the-agentic-flow@2.0.6","maintainers":[{"name":"janneskruse","email":"jannes.kruse@rwth-aachen.de"}],"homepage":"https://github.com/janneskruse/the-agentic-flow#readme","bugs":{"url":"https://github.com/janneskruse/the-agentic-flow/issues"},"os":["darwin","linux","win32"],"bin":{"beads-orchestration":"scripts/cli.js"},"dist":{"shasum":"3f9b1a1698a7ef98c8f97f1cc4c2e2ef3b58f1fc","tarball":"https://registry.npmjs.org/@apapacho/the-agentic-flow/-/the-agentic-flow-2.0.6.tgz","fileCount":41,"integrity":"sha512-iKwCUH9vccB3y2b9DCl3T/UYaYJk+iCUKYUY6yUnWCOCYfHRVowc/TV80nVeTCceyGZuT1o3K87PNEh8Gzps1g==","signatures":[{"sig":"MEYCIQDfJ6d8yGBUD573/0XEwx7cwQsHzTn7ZU4doO3Vi6oXsAIhAJvopJ7GhBAqpqz7sSleegdiOEJESg5BN4eQl18BASNF","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"unpackedSize":193068},"gitHead":"1e73823dbd69ae5684347e6f974ceb5764b594b3","scripts":{"postinstall":"node scripts/postinstall.js"},"_npmUser":{"name":"janneskruse","email":"jannes.kruse@rwth-aachen.de"},"repository":{"url":"git+https://github.com/janneskruse/the-agentic-flow.git","type":"git"},"_npmVersion":"11.6.1","description":"Multi-agent orchestration for Claude Code with automatic task management","directories":{},"_nodeVersion":"22.20.0","_hasShrinkwrap":false,"_npmOperationalInternal":{"tmp":"tmp/the-agentic-flow_2.0.6_1770237634225_0.31510429723393374","host":"s3://npm-registry-packages-npm-production"}},"2.0.7":{"name":"@apapacho/the-agentic-flow","version":"2.0.7","keywords":["claude","claude-code","orchestration","ai-agents","task-management","beads"],"author":{"name":"Jannes Kruse"},"license":"MIT","_id":"@apapacho/the-agentic-flow@2.0.7","maintainers":[{"name":"janneskruse","email":"jannes.kruse@rwth-aachen.de"}],"homepage":"https://github.com/janneskruse/the-agentic-flow#readme","bugs":{"url":"https://github.com/janneskruse/the-agentic-flow/issues"},"os":["darwin","linux","win32"],"bin":{"beads-orchestration":"scripts/cli.js"},"dist":{"shasum":"8c835fc13a777fdca2d2fa6209c9a5d655094669","tarball":"https://registry.npmjs.org/@apapacho/the-agentic-flow/-/the-agentic-flow-2.0.7.tgz","fileCount":41,"integrity":"sha512-1k8EY32+W21C5N9VnVuCYLT5aufxQpfbAGP1LkZZDVcWDgOQmZEZfollseh0JsjIwIbyoe7YyKYRHHJO6I+WmA==","signatures":[{"sig":"MEQCIETmwXhuU9eXpgYVj4zkhZzVFudVKU5xSMwuZENTRSX6AiBZJ+s6u7bX0qQHO/uhpJtx+42lYXdw79Cuji30ByiQGw==","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"unpackedSize":193284},"gitHead":"826c44c75088b91b44eb238145c5d6f95e778032","scripts":{"postinstall":"node scripts/postinstall.js"},"_npmUser":{"name":"janneskruse","email":"jannes.kruse@rwth-aachen.de"},"repository":{"url":"git+https://github.com/janneskruse/the-agentic-flow.git","type":"git"},"_npmVersion":"11.6.1","description":"Multi-agent orchestration for Claude Code with automatic task management","directories":{},"_nodeVersion":"22.20.0","_hasShrinkwrap":false,"_npmOperationalInternal":{"tmp":"tmp/the-agentic-flow_2.0.7_1770237804267_0.7046458832725089","host":"s3://npm-registry-packages-npm-production"}},"2.0.8":{"name":"@apapacho/the-agentic-flow","version":"2.0.8","keywords":["claude","claude-code","orchestration","ai-agents","task-management","beads"],"author":{"name":"Jannes Kruse"},"license":"MIT","_id":"@apapacho/the-agentic-flow@2.0.8","maintainers":[{"name":"janneskruse","email":"jannes.kruse@rwth-aachen.de"}],"homepage":"https://github.com/janneskruse/the-agentic-flow#readme","bugs":{"url":"https://github.com/janneskruse/the-agentic-flow/issues"},"os":["darwin","linux","win32"],"bin":{"beads-orchestration":"scripts/cli.js"},"dist":{"shasum":"813529ef25660390f9b5329321d40a04f88d31d9","tarball":"https://registry.npmjs.org/@apapacho/the-agentic-flow/-/the-agentic-flow-2.0.8.tgz","fileCount":43,"integrity":"sha512-ADvxK+FXZtxF8Ka2YOnbi14cTEwkdjgqAwCnx0tjRzMPjyP8U7MTngXKN3K1T5/2ODxa9LNIwq+F41dNeuGTRA==","signatures":[{"sig":"MEQCIAmOXrn0/MHhn3LSArsS8yjIFup6KVKDBXx8uBUukzLtAiA69EvGIj+OUoDf1zo9mVo2DfU5/WCYP4wEigktZEKowg==","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"unpackedSize":214485},"gitHead":"baae5b4ac60a06cee09ee123d1745e59af1f29aa","scripts":{"postinstall":"node scripts/postinstall.js"},"_npmUser":{"name":"janneskruse","email":"jannes.kruse@rwth-aachen.de"},"repository":{"url":"git+https://github.com/janneskruse/the-agentic-flow.git","type":"git"},"_npmVersion":"11.6.1","description":"Multi-agent orchestration for Claude Code with automatic task management","directories":{},"_nodeVersion":"22.20.0","_hasShrinkwrap":false,"_npmOperationalInternal":{"tmp":"tmp/the-agentic-flow_2.0.8_1770242545540_0.22075189321824462","host":"s3://npm-registry-packages-npm-production"}},"2.0.9":{"name":"@apapacho/the-agentic-flow","version":"2.0.9","keywords":["claude","claude-code","orchestration","ai-agents","task-management","beads"],"author":{"name":"Jannes Kruse"},"license":"MIT","_id":"@apapacho/the-agentic-flow@2.0.9","maintainers":[{"name":"janneskruse","email":"jannes.kruse@rwth-aachen.de"}],"homepage":"https://github.com/janneskruse/the-agentic-flow#readme","bugs":{"url":"https://github.com/janneskruse/the-agentic-flow/issues"},"os":["darwin","linux","win32"],"bin":{"beads-orchestration":"scripts/cli.js"},"dist":{"shasum":"7663abb26f83b06a3a255cab49fe8341dc68c05f","tarball":"https://registry.npmjs.org/@apapacho/the-agentic-flow/-/the-agentic-flow-2.0.9.tgz","fileCount":44,"integrity":"sha512-amPR2lAVMRXK7yl8BzhGUTx6wop6iI/zYj19W2Ruah6e/xDixWM08FtZEXHBacimzrG3qaCEpIMK9y6my3vKDA==","signatures":[{"sig":"MEYCIQD469OHdNJKlJfdoKy/Bb5g3+72zxBIQFhxxI66tIjf3AIhAKg8kn7RdbxVwo3Jd4XjQVCDOscifdUtmRd/PCcE6BSi","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"unpackedSize":217157},"gitHead":"8e61a82f40ed9e6878f38714d399d717847932ef","scripts":{"postinstall":"node scripts/postinstall.js"},"_npmUser":{"name":"janneskruse","email":"jannes.kruse@rwth-aachen.de"},"repository":{"url":"git+https://github.com/janneskruse/the-agentic-flow.git","type":"git"},"_npmVersion":"11.6.1","description":"Multi-agent orchestration for Claude Code with automatic task management","directories":{},"_nodeVersion":"22.20.0","_hasShrinkwrap":false,"_npmOperationalInternal":{"tmp":"tmp/the-agentic-flow_2.0.9_1770244474253_0.5015701482229908","host":"s3://npm-registry-packages-npm-production"}},"2.0.10":{"name":"@apapacho/the-agentic-flow","version":"2.0.10","description":"Multi-agent orchestration for Claude Code with automatic task management","author":{"name":"Jannes Kruse"},"license":"MIT","repository":{"type":"git","url":"git+https://github.com/janneskruse/the-agentic-flow.git"},"keywords":["claude","claude-code","orchestration","ai-agents","task-management","beads"],"os":["darwin","linux","win32"],"scripts":{"postinstall":"node scripts/postinstall.js"},"bin":{"beads-orchestration":"scripts/cli.js"},"gitHead":"b5e81f2647a74f92adbf30e2659c6dc7a8eab21d","_id":"@apapacho/the-agentic-flow@2.0.10","bugs":{"url":"https://github.com/janneskruse/the-agentic-flow/issues"},"homepage":"https://github.com/janneskruse/the-agentic-flow#readme","_nodeVersion":"22.20.0","_npmVersion":"11.6.1","dist":{"integrity":"sha512-sOTtSGPuSy0er9a4EGa6F69zExz4y81V5ACCePJk39PAw+LLqJZ/yO+ID1pjnXLbZS52yNSc39xe8XUj/Mv/tA==","shasum":"56251a2b1b1dce758add71c53e2a1d4ace712507","tarball":"https://registry.npmjs.org/@apapacho/the-agentic-flow/-/the-agentic-flow-2.0.10.tgz","fileCount":44,"unpackedSize":217428,"signatures":[{"keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U","sig":"MEUCIQDlLxpuavsXmH52icC4YxSs+m27SYOxSwEuqBHHBsGc6AIgcFDnShCZ0Jy/fuiMSgEK4KNi6cUjjlKtMCImEGGSDus="}]},"_npmUser":{"name":"janneskruse","email":"jannes.kruse@rwth-aachen.de"},"directories":{},"maintainers":[{"name":"janneskruse","email":"jannes.kruse@rwth-aachen.de"}],"_npmOperationalInternal":{"host":"s3://npm-registry-packages-npm-production","tmp":"tmp/the-agentic-flow_2.0.10_1770245237552_0.2422982503690867"},"_hasShrinkwrap":false}},"time":{"created":"2026-02-04T19:14:46.999Z","modified":"2026-02-04T22:47:17.856Z","2.0.0":"2026-02-04T19:14:47.319Z","2.0.1":"2026-02-04T20:00:30.772Z","2.0.2":"2026-02-04T20:36:40.823Z","2.0.6":"2026-02-04T20:40:34.370Z","2.0.7":"2026-02-04T20:43:24.422Z","2.0.8":"2026-02-04T22:02:25.719Z","2.0.9":"2026-02-04T22:34:34.391Z","2.0.10":"2026-02-04T22:47:17.723Z"},"bugs":{"url":"https://github.com/janneskruse/the-agentic-flow/issues"},"author":{"name":"Jannes Kruse"},"license":"MIT","homepage":"https://github.com/janneskruse/the-agentic-flow#readme","keywords":["claude","claude-code","orchestration","ai-agents","task-management","beads"],"repository":{"type":"git","url":"git+https://github.com/janneskruse/the-agentic-flow.git"},"description":"Multi-agent orchestration for Claude Code with automatic task management","maintainers":[{"name":"janneskruse","email":"jannes.kruse@rwth-aachen.de"}],"readme":"<div align=\"center\">\r\n\r\n# THE AGENTIC FLOW (fork from https://github.com/AvivK5498/The-Claude-Protocol)\r\n\r\n**Enforcement-first orchestration for Claude Code. Every agent tracked. Every decision logged. Nothing gets lost.**\r\n\r\n**Claude Code plans great. Without structure, nothing survives past one session.**\r\n\r\n[![npm version](https://img.shields.io/npm/v/@apapacho/the-agentic-flow?style=for-the-badge&logo=npm&logoColor=white&color=CB3837)](https://www.npmjs.com/package/@apapacho/the-agentic-flow)\r\n[![GitHub stars](https://img.shields.io/github/stars/AvivK5498/The-Claude-Protocol?style=for-the-badge&logo=github&color=181717)](https://github.com/janneskruse/the-agentic-flow)\r\n[![License](https://img.shields.io/badge/license-MIT-blue?style=for-the-badge)](LICENSE)\r\n\r\n<br>\r\n\r\n```bash\r\nnpx skills add AvivK5498/The-Claude-Protocol\r\n```\r\n\r\n**macOS, Linux, and Windows.**\r\n\r\n<br>\r\n\r\n![The Claude Protocol — Kanban UI](screenshots/kanbanui.png)\r\n\r\n<br>\r\n\r\n[Why This Exists](#why-this-exists) · [How It Works](#how-it-works) · [Getting Started](#getting-started) · [Hooks](#hooks)\r\n\r\n</div>\r\n\r\n---\r\n\r\n## Why This Exists\r\n\r\nClaude Code is the best coding agent out there. But let it run unsupervised and you get agents editing main, commits without PRs, lost context every session, and zero traceability on what was done and why.\r\n\r\nPlan mode helps — until you need to coordinate across files, track what was planned vs what shipped, or pick up a task three sessions later. Plans vanish. Context resets. Investigation gets redone from scratch.\r\n\r\nThe Claude Protocol is the enforcement layer. It wraps Claude Code with 13 hooks that physically block bad actions, isolates every task in its own git worktree, and documents everything automatically — dispatch prompts, agent knowledge, decisions, all of it. [Beads](https://github.com/steveyegge/beads) (git-native tickets) track every unit of work from creation to merge.\r\n\r\nThe complexity is in the system. What you see: Claude plans with you, you approve, agents execute in isolation, PRs get merged. Done.\r\n\r\n---\r\n\r\n## How It Works\r\n\r\n```\r\n┌─────────────────────────────────────────┐\r\n│         ORCHESTRATOR (Co-Pilot)         │\r\n│  Plans with you (Plan mode)            │\r\n│  Investigates with Grep/Read/Glob       │\r\n│  Delegates implementation via Task()    │\r\n└──────────────────┬──────────────────────┘\r\n                   │\r\n       ┌───────────┼───────────┐\r\n       ▼           ▼           ▼\r\n  ┌─────────┐ ┌─────────┐ ┌─────────┐\r\n  │ react-  │ │ python- │ │ nextjs- │\r\n  │supervisor│ │supervisor│ │supervisor│\r\n  └────┬────┘ └────┬────┘ └────┬────┘\r\n       │           │           │\r\n  .worktrees/ .worktrees/ .worktrees/\r\n  bd-BD-001   bd-BD-002   bd-BD-003\r\n```\r\n\r\n**The orchestrator** investigates, discusses with you, and plans. It never writes code. Dispatch prompts are auto-logged to the bead so nothing gets lost.\r\n\r\n**Supervisors** are created automatically based on your tech stack. They read bead comments for full context, work in isolated worktrees, and push clean PRs.\r\n\r\n**Beads** are git-native tickets. Every task, every epic, every dependency — tracked in your repo, not a third-party service. One bead = one unit of work = one worktree = one PR.\r\n\r\n### Workflow\r\n\r\n**Standalone** — Investigate → plan → approve → create bead → dispatch supervisor → worktree → PR → merge.\r\n\r\n**Epics** — Cross-domain work (DB + API + frontend) becomes an epic with enforced child dependencies. Each child gets its own worktree. Dependencies prevent dispatching out of order.\r\n\r\nEvery task goes through beads. No exceptions.\r\n\r\n### Kanban UI\r\n\r\nThe Claude Protocol pairs with the [Beads Kanban UI](https://github.com/AvivK5498/Beads-Kanban-UI) for visual task management and GitOps directly from the browser. Track epics, subtasks, dependencies, and PR status across columns — without leaving the board.\r\n\r\n---\r\n\r\n## Architecture: How Agents Work Together\r\n\r\n### Task Ownership & Responsibilities\r\n\r\n| Role | Creates Tasks? | Works on Tasks? | Creates Dependencies? |\r\n|------|----------------|-----------------|----------------------|\r\n| **Orchestrator** (Claude) | ✅ Yes (via `bd create`) | ❌ Never | ✅ Yes (via `--deps`) |\r\n| **Supervisors** | ❌ Never | ✅ Yes (in worktrees) | ❌ Never |\r\n| **Detectives/Scout** | ❌ Never | ❌ Never | ❌ Never |\r\n\r\n**The orchestrator** is the only agent that creates beads and manages dependencies. Supervisors only work on assigned tasks in isolated worktrees.\r\n\r\n### Agent Types\r\n\r\n| Agent | Type | Purpose | When Used |\r\n|-------|------|---------|-----------|\r\n| **scout** | Read-only | Quick reconnaissance | \"What files relate to X?\" |\r\n| **detective** | Read-only | Deep investigation | \"Why is X broken?\" |\r\n| **architect** | Read-only | Design docs for epics | Cross-domain features |\r\n| **scribe** | Read-only | Documentation generation | Doc updates |\r\n| **security-detective** | Read-only | Vulnerability scanning | Security audits |\r\n| **{tech}-supervisor** | Implementation | Actual code changes | Per-task execution |\r\n| **security-supervisor** | Implementation | Security fixes | Vulnerability remediation |\r\n| **code-reviewer** | Verification | 3-phase review | Optional review gate |\r\n\r\n### Bead Task Lifecycle\r\n\r\n```\r\nUser Request\r\n    ↓\r\nOrchestrator investigates (Grep, Read, Glob)\r\n    ↓\r\nPlan with user (optional: Plan mode)\r\n    ↓\r\nUser confirms approach\r\n    ↓\r\n**Interactive agent selection:**\r\n  - Orchestrator lists available agents\r\n  - Recommends best agent for each task\r\n  - User accepts or specifies different agents\r\n  - Final \"go\" confirmation\r\n    ↓\r\nOrchestrator creates bead(s)\r\n    ↓\r\nOrchestrator dispatches supervisor with BEAD_ID\r\n    ↓\r\nSupervisor works in .worktrees/bd-{BEAD_ID}/\r\n    ↓\r\nSupervisor commits, pushes, marks `inreview`\r\n    ↓\r\nOrchestrator prompts: /review, /merge, or /continue\r\n    ↓\r\nUser merges PR\r\n    ↓\r\nbd close {ID}\r\n```\r\n\r\n---\r\n\r\n## Auto-Pilot Mode (Generalized Loop)\r\n\r\nEnable autonomous task execution with automatic testing and retry logic.\r\n\r\n### How to Activate\r\n\r\nSay to Claude: **\"auto-pilot\"**, **\"watch mode\"**, or **\"run the loop\"**\r\n\r\n### The Loop\r\n\r\n```\r\n1. Run `bd ready` to find unblocked tasks\r\n2. For each ready task:\r\n   - Determine type from bead title (Implement, Test, Scan, Fix, etc.)\r\n   - Dispatch appropriate agent\r\n3. Wait for completion → agent marks `inreview`\r\n4. Auto-create test bead (if implementation task)\r\n5. If test fails:\r\n   - Create fix bead with dependency\r\n   - Loop continues\r\n6. If test passes:\r\n   - Notify user \"Task BD-XXX complete, tests passing\"\r\n7. Run `bd ready` again → repeat until empty\r\n```\r\n\r\n### Agent Routing\r\n\r\nAuto-pilot automatically selects agents based on bead title:\r\n\r\n| Bead Title Pattern | Agent Dispatched |\r\n|-------------------|------------------|\r\n| \"Implement...\", \"Add...\", \"Create...\" | `{tech}-supervisor` |\r\n| \"Test...\", \"Verify...\" | Built-in test mode OR `code-reviewer` |\r\n| \"Scan...\", \"Audit...\", \"Security...\" | `security-detective` |\r\n| \"Fix...\", \"Resolve...\" | `{tech}-supervisor` |\r\n| \"Investigate...\", \"Debug...\" | `detective` |\r\n\r\n### Safety Rails\r\n\r\n- **Max 3 retries** per original task (prevents infinite loops)\r\n- **User can interrupt** anytime with \"stop\" or \"pause\"\r\n- **Full traceability**: Each iteration creates new beads\r\n- **Retry tracking**: Stored in bead comments (`RETRY: 1/3`)\r\n\r\n### Resume After Stop\r\n\r\nWhen you say \"stop\", the currently running agent completes its work gracefully (no mid-task termination), then the loop pauses.\r\n\r\n**Resume commands:**\r\n- `\"continue\"` or `\"resume\"` → Picks up where it left off\r\n- `\"continue BD-XXX\"` → Resume specific task\r\n- `\"skip BD-XXX\"` → Mark task as skipped, continue with next\r\n\r\n**Works across sessions**: The `.beads/` database persists all state. You can:\r\n1. Stop auto-pilot\r\n2. Close Claude entirely\r\n3. Reopen later\r\n4. Say \"continue\"\r\n5. Loop resumes from where it stopped\r\n\r\n---\r\n\r\n## Custom Agents\r\n\r\nWant to add your own specialized agents? Just drop them in `.claude/agents/`.\r\n\r\n### Requirements\r\n\r\n1. **Filename**: Must end with `-supervisor` for implementation agents\r\n2. **Format**: Markdown with YAML frontmatter\r\n3. **Workflow**: Must include beads workflow (copy from `.claude/beads-workflow-injection.md`)\r\n\r\n### Example\r\n\r\n```markdown\r\n---\r\nname: my-custom-supervisor\r\ndescription: Handles custom domain logic\r\nmodel: sonnet\r\ntools: *\r\n---\r\n\r\n# My Custom Supervisor: \"Name\"\r\n\r\n[Include beads workflow here]\r\n\r\n[Your custom instructions]\r\n```\r\n\r\nThe orchestrator will automatically detect and offer your custom agent when appropriate.\r\n\r\n---\r\n\r\n## Getting Started\r\n\r\n```bash\r\nnpx skills add AvivK5498/The-Claude-Protocol\r\n```\r\n\r\nOr via npm:\r\n\r\n```bash\r\nnpm install -g @apapacho/the-agentic-flow\r\n```\r\n\r\nThen in any Claude Code session:\r\n\r\n```bash\r\n/create-beads-orchestration\r\n```\r\n\r\nThe skill walks you through setup, scans your tech stack, and creates supervisors with best practices injected.\r\n\r\n### Requirements\r\n\r\n- Claude Code with hooks support\r\n- Node.js (for npx)\r\n- Python 3 (for bootstrap)\r\n- beads CLI (installed automatically)\r\n\r\n---\r\n\r\n## Antigravity Support\r\n\r\nThis repo also supports Google's Antigravity agent.\r\n\r\n### Setup\r\n```bash\r\nnpx @apapacho/the-agentic-flow bootstrap --antigravity\r\n```\r\n\r\nThis creates an `.agent/skills/beads-orchestration` directory containing the keys to the kingdom: a `SKILL.md` that teaches Antigravity how to use the `bd` CLI.\r\n\r\n### How It Works\r\nAntigravity automatically detects skills in the `.agent/skills` directory. You don't need to \"install\" it further. When you ask Antigravity to \"check the tasks\" or \"create a task\", it will find this skill, read the instructions, and know how to call `bd list` or `bd create`.\r\n\r\n### Coexistence with Claude\r\n**Yes, they play nicely together.**\r\nBoth agents share the same source of truth: the `.beads` directory.\r\n- **Claude** uses `.claude/agents` and `.worktrees/`.\r\n- **Antigravity** uses `.agent/skills` and the same `.beads` database.\r\n- You can start a task in Claude, and Antigravity can see it via `bd list`.\r\n- You can create a task in Antigravity, and Claude can pick it up.\r\n\r\n---\r\n\r\n## What Makes This Different\r\n\r\n### Enforcement, Not Suggestions\r\n\r\n13 hooks across 5 lifecycle events. They don't warn — they block. The orchestrator can't edit code. Supervisors can't skip beads. Epics can't close with open children. PRs must be merged before a bead is closed.\r\n\r\n### Documentation That Writes Itself\r\n\r\nEvery supervisor dispatch prompt is automatically captured as a bead comment. Agents voluntarily log conventions and gotchas into a persistent knowledge base. Session start surfaces recent knowledge so agents don't re-investigate solved problems.\r\n\r\n```bash\r\n# Agent captures an insight\r\nbd comment BD-001 \"LEARNED: TaskGroup requires @Sendable closures in strict concurrency mode.\"\r\n\r\n# Search the knowledge base\r\n.beads/memory/recall.sh \"concurrency\"\r\n```\r\n\r\n### Follow-Up Traceability\r\n\r\nClosed beads are immutable. Bug fixes become new beads linked via `bd dep relate` — full history, no reopening. Merged branches don't get reused. Each fix gets its own worktree and PR.\r\n\r\n---\r\n\r\n## What Gets Installed\r\n\r\n```\r\n.claude/\r\n├── agents/           # Supervisors (auto-created for your tech stack)\r\n├── hooks/            # Workflow enforcement (13 hooks)\r\n├── skills/           # subagents-discipline, react-best-practices\r\n└── settings.json\r\nCLAUDE.md             # Orchestrator instructions\r\n.beads/               # Task database\r\n  memory/             # Knowledge base (knowledge.jsonl + recall.sh)\r\n.worktrees/           # Isolated worktrees per task (created dynamically)\r\n```\r\n\r\n---\r\n\r\n## Hooks\r\n\r\n13 hooks enforce every workflow step. They block before bad actions happen, auto-log after good ones, and validate before supervisors exit.\r\n\r\n**PreToolUse** (7 hooks) — Block orchestrator from writing code. Require beads for supervisor dispatch. Enforce worktree isolation. Block closing epics with open children. Enforce sequential dependency dispatch.\r\n\r\n**PostToolUse** (3 hooks) — Auto-log dispatch prompts as bead comments. Capture knowledge base entries. Enforce concise supervisor responses.\r\n\r\n**SubagentStop** (1 hook) — Verify worktree exists, code is pushed, bead status is updated.\r\n\r\n**SessionStart** (1 hook) — Surface task status, recent knowledge, and cleanup suggestions.\r\n\r\n**UserPromptSubmit** (1 hook) — Prompt for clarification on ambiguous requests.\r\n\r\n---\r\n\r\n## Advanced: External Providers\r\n\r\nBy default, all agents run via Claude's Task(). To delegate read-only agents (scout, detective, etc.) to Codex/Gemini:\r\n\r\n```bash\r\n/create-beads-orchestration --external-providers\r\n```\r\n\r\nRequires Codex CLI (`codex login`), optionally Gemini CLI, and [uv](https://github.com/astral-sh/uv).\r\n\r\n---\r\n\r\n## License\r\n\r\nMIT\r\n\r\n## Credits\r\n\r\n- [beads](https://github.com/steveyegge/beads) — Git-native task tracking by Steve Yegge\r\n- [sub-agents.directory](https://github.com/ayush-that/sub-agents.directory) — External agent templates\r\n","readmeFilename":"README.md"}