beads-orchestration 2.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Aviv Kaplan
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,214 @@
+# Beads Orchestration
+
+Multi-agent orchestration for Claude Code. A co-pilot architect that investigates issues, discusses approach with you, then delegates implementation to specialized supervisors.
+
+**[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.
+
+## Installation
+
+```bash
+npx skills add AvivK5498/Claude-Code-Beads-Orchestration
+```
+
+Or via npm:
+
+```bash
+npm install -g beads-orchestration
+```
+
+> macOS and Linux only.
+
+## Quick Start
+
+```bash
+# In any Claude Code session
+/create-beads-orchestration
+```
+
+The skill walks you through setup, runs the bootstrap via `npx`, then creates tech-specific supervisors based on your codebase.
+
+### Requirements
+
+- Claude Code with hooks support
+- Node.js (for npx)
+- Python 3 (for bootstrap)
+- beads CLI (installed automatically by bootstrap)
+
+## Key Features
+
+🧭 **Co-pilot architect** — Investigates, presents trade-offs, waits for your confirmation before dispatching. Constructive skeptic, not a blind executor.
+
+⚡ **Quick fix path** — Trivial single-file changes skip the bead/worktree/PR overhead. Just dispatch, edit, commit, done.
+
+🌳 **Worktree isolation** — Every task gets its own worktree. Main stays clean. Parallel work without conflicts.
+
+📋 **Auto task tracking** — [Beads](https://github.com/steveyegge/beads) create, track, and close tasks automatically.
+
+🔗 **Epics & dependencies** — Cross-domain work becomes epics with enforced child dependencies. Independent children dispatch in parallel.
+
+📝 **Dispatch auto-logging** — Every supervisor dispatch prompt is automatically captured as a bead comment. Full audit trail, zero manual effort.
+
+🔁 **Follow-up traceability** — Closed beads stay closed. Bug fixes become new beads linked via `bd dep relate` — full history, no reopening.
+
+🧠 **Knowledge base** — Agents voluntarily capture conventions and gotchas into `.beads/memory/`. Searchable, surfaced at session start.
+
+🔒 **13 enforcement hooks** — Every workflow step is guarded. See [Hooks](#hooks).
+
+🔎 **Tech stack discovery** — Scans your codebase, creates the right supervisors with best practices injected.
+
+## How It Works
+
+```
+┌─────────────────────────────────────────┐
+│         ORCHESTRATOR (Co-Pilot)         │
+│  Investigates with Grep/Read/Glob       │
+│  Discusses approach with user           │
+│  Delegates implementation via Task()    │
+└──────────────────┬──────────────────────┘
+                   │
+       ┌───────────┼───────────┐
+       ▼           ▼           ▼
+  ┌─────────┐ ┌─────────┐ ┌─────────┐
+  │ react-  │ │ python- │ │ nextjs- │
+  │supervisor│ │supervisor│ │supervisor│
+  └────┬────┘ └────┬────┘ └────┬────┘
+       │           │           │
+  .worktrees/ .worktrees/ .worktrees/
+  bd-BD-001   bd-BD-002   bd-BD-003
+```
+
+**Orchestrator:** Investigates the issue, discusses with user, proposes a plan. Dispatch prompts are auto-logged to the bead as `DISPATCH_PROMPT` comments.
+
+**Supervisors:** Read bead comments for context, create isolated worktrees, execute the fix confidently. Created by discovery agent based on your tech stack.
+
+### Workflow Modes
+
+**Quick Fix** — Single file, obvious fix, fully reversible. No bead, no worktree, no PR. Git commit = audit trail.
+
+**Full Workflow** — Multi-file or uncertain changes. Investigate → discuss → confirm → create bead → dispatch supervisor → worktree → PR → merge.
+
+Default to full workflow when in doubt.
+
+## Knowledge Base
+
+Agents build a persistent knowledge base as they work. No extra steps — it piggybacks on `bd comment`.
+
+```bash
+# Agent records a useful insight (voluntary)
+bd comment BD-001 "LEARNED: TaskGroup requires @Sendable closures in strict concurrency mode."
+```
+
+An async hook intercepts `LEARNED:` comments and extracts them into `.beads/memory/knowledge.jsonl`. Each entry is auto-tagged by keyword and attributed to its source.
+
+**Why this works:**
+- Zero friction — agents already use `bd comment`, they just add a prefix
+- No database, no embeddings, no external services — one JSONL file, grep + jq to search
+- Voluntary — agents log insights when they discover something worth remembering
+- Surfaces automatically — session start shows recent knowledge so agents don't re-investigate solved problems
+
+```bash
+# Search the knowledge base
+.beads/memory/recall.sh "concurrency"
+.beads/memory/recall.sh --recent 10
+.beads/memory/recall.sh --stats
+```
+
+See [docs/memory-architecture.md](docs/memory-architecture.md) for the full design.
+
+## Bug Fixes & Follow-Up Work
+
+Closed beads are immutable. When a bug is found after a task was completed, a new bead is created and linked to the original:
+
+```bash
+bd create "Fix: button click handler race condition" -d "Follow-up to BD-001"
+# Returns: BD-005
+
+bd dep relate BD-005 BD-001   # Bidirectional "see also" — no dependency
+```
+
+The `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.
+
+**Why this matters:**
+- Merged branches don't get reused — avoids SHA conflicts from squash/rebase merges
+- Each fix gets its own worktree and PR
+- Audit trail stays clean — one bead = one unit of work
+
+## What Gets Installed
+
+```
+.claude/
+├── agents/           # Supervisors (discovery creates tech-specific ones)
+├── hooks/            # Workflow enforcement (13 hooks)
+├── skills/           # subagents-discipline, react-best-practices
+└── settings.json
+CLAUDE.md             # Orchestrator instructions
+.beads/               # Task database
+  memory/             # Knowledge base (knowledge.jsonl + recall.sh)
+.worktrees/           # Isolated worktrees for each task (created dynamically)
+```
+
+## Hooks
+
+13 hooks enforce the workflow at every step. Grouped by lifecycle event:
+
+**PreToolUse** — Block before action happens:
+
+| Hook | Trigger | Purpose |
+|------|---------|---------|
+| `block-orchestrator-tools.sh` | Edit, Write | Orchestrator can't modify code directly |
+| `enforce-bead-for-supervisor.sh` | Task | Supervisors require BEAD_ID in prompt |
+| `enforce-branch-before-edit.sh` | Edit, Write | Must be in a worktree, not main |
+| `enforce-sequential-dispatch.sh` | Task | Blocks closed/done beads and epic children with unresolved deps |
+| `validate-epic-close.sh` | Bash | Blocks bead close without merged PR; blocks epic close with open children |
+| `inject-discipline-reminder.sh` | Task | Injects discipline skill context |
+| `remind-inprogress.sh` | Task | Warns about existing in-progress beads |
+
+**PostToolUse** — React after action completes:
+
+| Hook | Trigger | Purpose |
+|------|---------|---------|
+| `enforce-concise-response.sh` | Task | Limits supervisor response verbosity |
+| `log-dispatch-prompt.sh` | Task | Auto-logs dispatch prompts as DISPATCH_PROMPT bead comments |
+| `memory-capture.sh` | Bash | Captures LEARNED comments into knowledge base |
+
+**SubagentStop** — Validate before supervisor exits:
+
+| Hook | Trigger | Purpose |
+|------|---------|---------|
+| `validate-completion.sh` | Any | Verifies worktree, push, bead status |
+
+**SessionStart** — Run when a new session begins:
+
+| Hook | Trigger | Purpose |
+|------|---------|---------|
+| `session-start.sh` | Any | Shows task status, recent knowledge, cleanup suggestions |
+
+**UserPromptSubmit** — Filter user input:
+
+| Hook | Trigger | Purpose |
+|------|---------|---------|
+| `clarify-vague-request.sh` | Any | Prompts for clarification on ambiguous requests |
+
+## Advanced: External Providers
+
+By default, all agents run via Claude's Task(). If you want to delegate read-only agents (scout, detective, etc.) to Codex/Gemini instead:
+
+```bash
+/create-beads-orchestration --external-providers
+```
+
+**Additional requirements:**
+- Codex CLI: `codex login`
+- Gemini CLI (optional fallback)
+- uv: [install](https://github.com/astral-sh/uv)
+
+This creates `.mcp.json` with provider-delegator config.
+
+## License
+
+MIT
+
+## Credits
+
+- [beads](https://github.com/steveyegge/beads) - Git-native task tracking by Steve Yegge
+- [sub-agents.directory](https://github.com/ayush-that/sub-agents.directory) - External agent templates

package/SKILL.md

@@ -0,0 +1,263 @@
+---
+name: create-beads-orchestration
+description: Bootstrap lean multi-agent orchestration with beads task tracking. Use for projects needing agent delegation without heavy MCP overhead.
+user-invocable: true
+---
+
+# Create Beads Orchestration
+
+Set up lightweight multi-agent orchestration with git-native task tracking for Claude Code.
+
+## What This Skill Does
+
+This skill bootstraps a complete multi-agent workflow where:
+
+- **Orchestrator** (you) investigates issues, manages tasks, delegates implementation
+- **Supervisors** (specialized agents) execute fixes in isolated worktrees
+- **Beads CLI** tracks all work with git-native task management
+- **Hooks** enforce workflow discipline automatically
+
+Each task gets its own worktree at `.worktrees/bd-{BEAD_ID}/`, keeping main clean and enabling parallel work.
+
+## Beads Kanban UI
+
+The setup will auto-detect [Beads Kanban UI](https://github.com/AvivK5498/Beads-Kanban-UI) and configure accordingly. If not found, you'll be offered to install it.
+
+---
+
+## Step 0: Detect Setup State (ALWAYS RUN FIRST)
+
+<detection-phase>
+**Before doing anything else, detect if this is a fresh setup or a resume after restart.**
+
+Check for bootstrap artifacts:
+```bash
+ls .claude/agents/scout.md 2>/dev/null && echo "BOOTSTRAP_COMPLETE" || echo "FRESH_SETUP"
+```
+
+**If `BOOTSTRAP_COMPLETE`:**
+- Bootstrap already ran in a previous session
+- Skip directly to **Step 4: Run Discovery**
+- Do NOT ask for project info or run bootstrap again
+
+**If `FRESH_SETUP`:**
+- This is a new installation
+- Proceed to **Step 1: Get Project Info**
+</detection-phase>
+
+---
+
+## Workflow Overview
+
+<mandatory-workflow>
+| Step | Action | When to Run |
+|------|--------|-------------|
+| 0 | Detect setup state | **ALWAYS** (determines path) |
+| 1 | Get project info from user | Fresh setup only |
+| 2 | Run bootstrap | Fresh setup only |
+| 3 | **STOP** - Instruct user to restart | Fresh setup only |
+| 4 | Run discovery agent | After restart OR if bootstrap already complete |
+
+**The setup is NOT complete until Step 4 (discovery) has run.**
+</mandatory-workflow>
+
+---
+
+## Step 1: Get Project Info (Fresh Setup Only)
+
+<critical-step1>
+**YOU MUST GET PROJECT INFO AND DETECT/ASK ABOUT KANBAN UI BEFORE PROCEEDING TO STEP 2.**
+
+1. **Project directory**: Where to install (default: current working directory)
+2. **Project name**: For agent templates (will auto-infer from package.json/pyproject.toml if not provided)
+3. **Kanban UI**: Auto-detect, or ask the user to install
+</critical-step1>
+
+### 1.1 Get Project Directory and Name
+
+Ask the user or auto-detect from package.json/pyproject.toml.
+
+### 1.2 Detect or Install Kanban UI
+
+```bash
+which bead-kanban 2>/dev/null && echo "KANBAN_FOUND" || echo "KANBAN_NOT_FOUND"
+```
+
+**If KANBAN_FOUND** → Use `--with-kanban-ui` flag. Tell the user:
+> Detected Beads Kanban UI. Configuring worktree management via API.
+
+**If KANBAN_NOT_FOUND** → Ask:
+
+```
+AskUserQuestion(
+  questions=[
+    {
+      "question": "Beads Kanban UI not detected. It adds a visual kanban board with dependency graphs and API-driven worktree management. Install it?",
+      "header": "Kanban UI",
+      "options": [
+        {"label": "Yes, install it (Recommended)", "description": "Runs: npm install -g beads-kanban-ui"},
+        {"label": "Skip", "description": "Use git worktrees directly. You can install later."}
+      ],
+      "multiSelect": false
+    }
+  ]
+)
+```
+
+- If "Yes" → Run `npm install -g beads-kanban-ui`, then use `--with-kanban-ui` flag
+- If "Skip" → do NOT use `--with-kanban-ui` flag
+
+---
+
+## Step 2: Run Bootstrap
+
+```bash
+# With Kanban UI:
+npx beads-orchestration@latest bootstrap \
+  --project-name "{{PROJECT_NAME}}" \
+  --project-dir "{{PROJECT_DIR}}" \
+  --with-kanban-ui
+
+# Without Kanban UI (git worktrees only):
+npx beads-orchestration@latest bootstrap \
+  --project-name "{{PROJECT_NAME}}" \
+  --project-dir "{{PROJECT_DIR}}"
+```
+
+The bootstrap script will:
+1. Install beads CLI (via brew, npm, or go)
+2. Initialize `.beads/` directory
+3. Copy agent templates to `.claude/agents/`
+4. Copy hooks to `.claude/hooks/`
+5. Configure `.claude/settings.json`
+6. Create `CLAUDE.md` with orchestrator instructions
+7. Update `.gitignore`
+
+**Verify bootstrap completed successfully before proceeding.**
+
+---
+
+## Step 3: STOP - User Must Restart
+
+<critical>
+**YOU MUST STOP HERE AND INSTRUCT THE USER TO RESTART CLAUDE CODE.**
+
+Tell the user:
+
+> **Setup phase complete. You MUST restart Claude Code now.**
+>
+> The new hooks and MCP configuration will only load after restart.
+>
+> After restarting:
+> 1. Open this same project directory
+> 2. Tell me "Continue orchestration setup" or run `/create-beads-orchestration` again
+> 3. I will run the discovery agent to complete setup
+>
+> **Do not skip this restart - the orchestration will not work without it.**
+
+**DO NOT proceed to Step 4 in this session. The restart is mandatory.**
+</critical>
+
+---
+
+## Step 4: Run Discovery (After Restart OR Detection)
+
+<post-restart>
+**Run this step if:**
+- Step 0 detected `BOOTSTRAP_COMPLETE`, OR
+- User returned after restart and said "continue setup" or ran `/create-beads-orchestration` again
+
+1. Verify bootstrap completed (check for `.claude/agents/scout.md`) - already done in Step 0
+2. Run the discovery agent:
+
+```python
+Task(
+    subagent_type="discovery",
+    prompt="Detect tech stack and create supervisors for this project"
+)
+```
+
+Discovery will:
+- Scan package.json, requirements.txt, Dockerfile, etc.
+- Fetch specialist agents from external directory
+- Inject beads workflow into each supervisor
+- Write supervisors to `.claude/agents/`
+
+3. After discovery completes, tell the user:
+
+> **Orchestration setup complete!**
+>
+> Created supervisors: [list what discovery created]
+>
+> You can now use the orchestration workflow:
+> - Create tasks with `bd create "Task name" -d "Description"`
+> - The orchestrator will delegate to appropriate supervisors
+> - All work requires code review before completion
+</post-restart>
+
+---
+
+## What This Creates
+
+- **Beads CLI** for git-native task tracking (one bead = one worktree = one task)
+- **Core agents**: scout, detective, architect, scribe, code-reviewer (all run via Claude Task)
+- **Discovery agent**: Auto-detects tech stack and creates specialized supervisors
+- **Hooks**: Enforce orchestrator discipline, code review gates, concise responses
+- **Worktree-per-task workflow**: Isolated development in `.worktrees/bd-{BEAD_ID}/`
+
+**With `--with-kanban-ui`:**
+- Worktrees created via API (localhost:3008) with git fallback
+- Requires [Beads Kanban UI](https://github.com/AvivK5498/Beads-Kanban-UI) running
+
+**Without `--with-kanban-ui`:**
+- Worktrees created via raw git commands
+
+## Epic Workflow (Cross-Domain Features)
+
+For features requiring multiple supervisors (e.g., DB + API + Frontend), use the **epic workflow**:
+
+### When to Use Epics
+
+| Task Type | Workflow |
+|-----------|----------|
+| Single-domain (one supervisor) | Standalone bead |
+| Cross-domain (multiple supervisors) | Epic with children |
+
+### Epic Workflow Steps
+
+1. **Create epic**: `bd create "Feature name" -d "Description" --type epic`
+2. **Create design doc** (if needed): Dispatch architect to create `.designs/{EPIC_ID}.md`
+3. **Link design**: `bd update {EPIC_ID} --design ".designs/{EPIC_ID}.md"`
+4. **Create children with dependencies**:
+   ```bash
+   bd create "DB schema" -d "..." --parent {EPIC_ID}              # BD-001.1
+   bd create "API endpoints" -d "..." --parent {EPIC_ID} --deps BD-001.1  # BD-001.2
+   bd create "Frontend" -d "..." --parent {EPIC_ID} --deps BD-001.2       # BD-001.3
+   ```
+5. **Dispatch sequentially**: Use `bd ready` to find unblocked tasks (each child gets own worktree)
+6. **User merges each PR**: Wait for child's PR to merge before dispatching next
+7. **Close epic**: `bd close {EPIC_ID}` after all children merged
+
+### Design Docs
+
+Design docs ensure consistency across epic children:
+- Schema definitions (exact column names, types)
+- API contracts (endpoints, request/response shapes)
+- Shared constants/enums
+- Data flow between layers
+
+**Key rule**: Orchestrator dispatches architect to create design docs. Orchestrator never writes design docs directly.
+
+### Hooks Enforce Epic Workflow
+
+- **enforce-sequential-dispatch.sh**: Blocks dispatch if task has unresolved blockers
+- **enforce-bead-for-supervisor.sh**: Requires BEAD_ID for all supervisors
+- **validate-completion.sh**: Verifies worktree, push, bead status before supervisor completes
+
+## Requirements
+
+- **beads CLI**: Installed automatically by bootstrap (via brew, npm, or go)
+
+## More Information
+
+See the full documentation: https://github.com/AvivK5498/Claude-Code-Beads-Orchestration