beads-orchestration 2.0.0

package/package.json

@@ -0,0 +1,37 @@
+{
+  "name": "beads-orchestration",
+  "version": "2.0.0",
+  "description": "Multi-agent orchestration for Claude Code with automatic task management",
+  "author": "Aviv Kaplan",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/AvivK5498/Claude-Code-Beads-Orchestration"
+  },
+  "keywords": [
+    "claude",
+    "claude-code",
+    "orchestration",
+    "ai-agents",
+    "task-management",
+    "beads"
+  ],
+  "os": [
+    "darwin",
+    "linux"
+  ],
+  "scripts": {
+    "postinstall": "node scripts/postinstall.js"
+  },
+  "files": [
+    "scripts/",
+    "skills/",
+    "templates/",
+    "bootstrap.py",
+    "SKILL.md",
+    "README.md"
+  ],
+  "bin": {
+    "beads-orchestration": "./scripts/cli.js"
+  }
+}

package/scripts/cli.js

@@ -0,0 +1,64 @@
+#!/usr/bin/env node
+
+const { execSync } = require('child_process');
+const path = require('path');
+const fs = require('fs');
+
+const args = process.argv.slice(2);
+const command = args[0];
+
+const packageDir = path.dirname(__dirname);
+const bootstrapScript = path.join(packageDir, 'bootstrap.py');
+
+function showHelp() {
+  console.log(`
+beads-orchestration - Multi-agent orchestration for Claude Code
+
+Usage:
+  beads-orchestration <command> [options]
+
+Commands:
+  install          Run postinstall to copy skill to ~/.claude/
+  bootstrap        Run bootstrap.py directly (advanced)
+  help             Show this help message
+
+Examples:
+  beads-orchestration install
+  beads-orchestration bootstrap --project-dir /path/to/project --claude-only
+
+After installing, use /create-beads-orchestration in Claude Code.
+`);
+}
+
+function runInstall() {
+  const postinstall = path.join(__dirname, 'postinstall.js');
+  require(postinstall);
+}
+
+function runBootstrap() {
+  const bootstrapArgs = args.slice(1).join(' ');
+  try {
+    execSync(`python3 "${bootstrapScript}" ${bootstrapArgs}`, { stdio: 'inherit' });
+  } catch (err) {
+    process.exit(err.status || 1);
+  }
+}
+
+switch (command) {
+  case 'install':
+    runInstall();
+    break;
+  case 'bootstrap':
+    runBootstrap();
+    break;
+  case 'help':
+  case '--help':
+  case '-h':
+  case undefined:
+    showHelp();
+    break;
+  default:
+    console.error(`Unknown command: ${command}`);
+    showHelp();
+    process.exit(1);
+}

package/scripts/postinstall.js

@@ -0,0 +1,71 @@
+#!/usr/bin/env node
+
+const fs = require('fs');
+const path = require('path');
+const os = require('os');
+
+const SKILL_NAME = 'create-beads-orchestration';
+
+// Get paths
+const homeDir = os.homedir();
+const claudeDir = path.join(homeDir, '.claude');
+const claudeSkillsDir = path.join(claudeDir, 'skills', SKILL_NAME);
+const packageDir = path.dirname(__dirname);
+const sourceSkillDir = path.join(packageDir, 'skills', SKILL_NAME);
+
+console.log('\n📦 Installing beads-orchestration skill...\n');
+
+// Check OS
+if (process.platform === 'win32') {
+  console.log('⚠️  Windows is not supported. Use WSL or macOS/Linux.');
+  process.exit(0);
+}
+
+// Create ~/.claude/skills/create-beads-orchestration/
+try {
+  fs.mkdirSync(claudeSkillsDir, { recursive: true });
+} catch (err) {
+  console.error(`❌ Failed to create directory: ${claudeSkillsDir}`);
+  console.error(err.message);
+  process.exit(1);
+}
+
+// Copy SKILL.md
+const sourceFile = path.join(sourceSkillDir, 'SKILL.md');
+const destFile = path.join(claudeSkillsDir, 'SKILL.md');
+
+try {
+  if (!fs.existsSync(sourceFile)) {
+    console.error(`❌ Source skill not found: ${sourceFile}`);
+    process.exit(1);
+  }
+
+  fs.copyFileSync(sourceFile, destFile);
+  console.log(`✅ Installed skill to: ${claudeSkillsDir}`);
+} catch (err) {
+  console.error(`❌ Failed to copy skill: ${err.message}`);
+  process.exit(1);
+}
+
+// Save package location for bootstrap.py
+const configFile = path.join(claudeDir, 'beads-orchestration-path.txt');
+try {
+  fs.writeFileSync(configFile, packageDir);
+  console.log(`✅ Saved package path to: ${configFile}`);
+} catch (err) {
+  console.error(`⚠️  Could not save package path: ${err.message}`);
+}
+
+console.log(`
+🎉 Installation complete!
+
+Package location: ${packageDir}
+
+Usage:
+  In any Claude Code session, run:
+
+    /create-beads-orchestration
+
+  The skill will guide you through setting up orchestration for your project.
+
+`);

package/skills/create-beads-orchestration/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

package/skills/subagents-discipline/SKILL.md

@@ -0,0 +1,158 @@
+---
+name: subagents-discipline
+description: Invoke at the start of any implementation task to enforce verification-first development
+---
+
+# Implementation Discipline
+
+**Core principle:** Test the FEATURE, not just the component you built.
+
+---
+
+## Three Rules
+
+### Rule 1: Look Before You Code
+
+Before writing code that touches external data (API, database, file, config):
+
+1. **Fetch/read the ACTUAL data** - run the command, see the output
+2. **Note exact field names, types, formats** - not what docs say, what you SEE
+3. **Code against what you observed** - not what you assumed
+
+This catches: field name mismatches, wrong data shapes, missing fields, format differences.
+
+```
+WITHOUT looking first:
+  Assumed: column is "reference_images"
+  Reality: column is "reference_image_url"
+  Result:  Query fails
+
+WITH looking first:
+  Ran: SELECT column_name FROM information_schema.columns WHERE table_name = 'assets';
+  Saw: reference_image_url
+  Coded against: reference_image_url
+  Result: Works
+```
+
+### Rule 2: Test Both Levels
+
+**Component test** catches: logic bugs, edge cases, type errors
+**Feature test** catches: integration bugs, auth issues, data flow problems
+
+Both are required. Component test alone is NOT sufficient.
+
+| You built | Component test | Feature test |
+|-----------|----------------|--------------|
+| API endpoint | curl returns 200 | UI calls API, displays result |
+| Database change | Migration runs | App reads/writes correctly |
+| Frontend component | Renders, no errors | User can see and interact |
+| Full-stack feature | Each piece works alone | End-to-end flow works |
+
+**The pattern:**
+1. Build the thing
+2. Component test - verify your piece works in isolation
+3. Feature test - verify the integrated feature works end-to-end
+4. Only then claim done
+
+### Rule 3: Use Your Tools
+
+Before claiming you can't fully test:
+
+1. **Check what MCP servers you have access to** - list available tools
+2. **If any tool can help verify the feature works**, use it
+3. **Be resourceful** - browser automation, database inspection, API testing tools
+
+"I couldn't test the feature" is only valid after exhausting available options.
+
+---
+
+## DEMO Block (Required)
+
+Every completion must include evidence. Code reviewer will verify this.
+
+```
+DEMO:
+  COMPONENT:
+    Command: [what you ran to test the component]
+    Result: [what you observed]
+
+  FEATURE:
+    Steps: [how you tested the integrated feature]
+    Result: [what you observed - screenshot, output, etc.]
+```
+
+### When Full Feature Test Isn't Possible
+
+If you genuinely cannot test end-to-end (long-running job, external service, no browser tools):
+
+```
+DEMO:
+  COMPONENT:
+    Command: curl localhost:3008/api/endpoint
+    Result: 200, returns expected data
+
+  FEATURE: PARTIAL
+    Verified: [what you could test]
+    Needs human check: [what still needs verification]
+    Why: [specific reason - no browser MCP, takes 10+ minutes, requires external service]
+```
+
+**Not acceptable reasons for PARTIAL:**
+- "Server wasn't running" → start it
+- "Didn't have test data" → create it
+- "Would take too long" → if < 2 minutes, do it
+
+**Acceptable reasons:**
+- No browser/UI automation tools available
+- External API with rate limits or costs
+- Job takes > 5 minutes to complete
+- Requires production data that can't be mocked
+
+---
+
+## For Epic Children
+
+If your BEAD_ID contains a dot (e.g., BD-001.2), you're implementing part of a larger feature:
+
+1. **Check for design doc**: `bd show {EPIC_ID} --json | jq -r '.[0].design'`
+2. **Read it if it exists** - this is your contract
+3. **Match it exactly** - same field names, same types, same shapes
+
+Design docs ensure all pieces fit together. If you deviate, integration fails.
+
+---
+
+## Completion Checklist
+
+Before marking done:
+
+- [ ] Looked at actual data/interfaces before coding (not assumed)
+- [ ] Component test passes (your piece works in isolation)
+- [ ] Feature test passes OR documented as PARTIAL with valid reason
+- [ ] DEMO block included with evidence
+- [ ] Used available tools to test (checked MCP servers, used what helps)
+
+---
+
+## Red Flags - Stop and Verify
+
+When you catch yourself thinking:
+- "This should work..." → run it and see
+- "I assume the field is..." → look at the actual data
+- "I'll test it later..." → test it now
+- "It's too simple to break..." → verify anyway
+
+When you're about to say:
+- "Done!" / "Fixed!" / "Should work now!" → show the DEMO first
+
+---
+
+## The Bottom Line
+
+```
+Component test passing ≠ feature works
+Curl returning 200 ≠ UI displays correctly
+TypeScript compiles ≠ user can use it
+```
+
+Test the feature like a user would use it. Then show evidence. Then claim done.