Beads integration, settings, sync, and epic label

[acreeger]

Summary

Build the foundational layer for swarm mode: Beads CLI integration, swarm settings, GitHub/Linear → Beads sync, and iloom-epic label auto-application.

Context

This is the foundation for the Autonomous Swarm Mode epic (#557). All other swarm issues depend on this infrastructure being in place.

Scope

1. Swarm Settings Schema

Add swarm section to SettingsManager Zod schema in src/lib/SettingsManager.ts:

swarm: {
  maxConcurrent: z.number().min(1).max(10).default(3),
  maxRetries: z.number().min(0).max(5).default(1),
  maxConflictRetries: z.number().min(0).max(10).default(3),
  beadsDir: z.string().default('~/.config/iloom-ai/beads'),
  autoInstallBeads: z.boolean().default(false)
}

2. Beads Install Detection & Auto-Install

• Check if bd is on PATH (which bd)
• If missing:
  • Interactive (TTY): Prompt "Swarm mode requires Beads. Install now? [Y/n]"
  • Non-interactive (no TTY or --swarm flag): Auto-install silently
  • autoInstallBeads: true in settings: Auto-install without prompting
• Install via official script: curl -fsSL https://raw.githubusercontent.com/steveyegge/beads/main/scripts/install.sh | bash
• Verify installation succeeded after running script

3. Beads Init Wrapper

Initialize Beads with proper environment:

BEADS_DIR=<settings.swarm.beadsDir>/<project-hash> BEADS_NO_DAEMON=1 \
  bd init --quiet --skip-hooks --skip-merge-driver

• Idempotent (safe to re-run)
• Project-hash derived from project path to avoid collisions
• All subsequent bd calls must set BEADS_DIR and BEADS_NO_DAEMON=1

4. Beads CLI Wrapper Class

Create src/lib/BeadsManager.ts with methods:

• ensureInstalled() — install detection + auto-install
• init(projectPath: string) — init with proper env vars
• create(title: string, options?: { priority?: number }) — create a task
• addDependency(child: string, parent: string) — add blocking dependency
• ready() — list tasks with no open blockers (returns parsed JSON)
• claim(taskId: string) — atomically claim a task
• close(taskId: string, reason?: string) — mark task complete
• releaseClaim(taskId: string) — release a claimed task (for failure recovery)

All methods set BEADS_DIR + BEADS_NO_DAEMON=1 in the environment. Use execa for CLI invocation. Parse JSON output where available.

5. GitHub/Linear → Beads Sync

Create sync logic (could be a method on BeadsManager or separate class):

• Fetch epic's child issues via IssueTracker.getChildIssues(epicNumber)
• Fetch dependency graph via IssueManagementProvider.getDependencies()
• For each child issue: bd create "<title>" --id <issue-number>
• For each dependency: bd dep add <child-id> <parent-id> (blocking relationship)
• Handle re-sync: skip tasks that already exist in Beads (for resume scenarios)
• Store mapping between GitHub/Linear issue IDs and Beads task IDs

6. Auto-Apply iloom-epic Label in il plan

• When PlanCommand creates the parent issue via mcp__issue_management__create_issue, include iloom-epic in the labels array
• Update the plan prompt template (templates/prompts/plan-prompt.txt) to instruct the Architect to apply the label
• Ensure the label exists (create via API if missing)

Acceptance Criteria

• swarm settings are validated by Zod schema and accessible via SettingsManager
• BeadsManager.ensureInstalled() correctly detects, prompts, and installs Beads
• BeadsManager.init() creates a Beads database at the configured BEADS_DIR
• All bd CLI wrapper methods work correctly with proper env vars
• Sync correctly maps child issues and dependencies from GitHub/Linear to Beads
• Re-sync is idempotent (doesn't create duplicates)
• il plan auto-applies iloom-epic label to parent issues
• Unit tests cover all BeadsManager methods with mocked CLI calls
• Unit tests cover sync logic with mocked issue tracker

Scope Boundaries

• Does NOT include the supervisor loop or agent spawning
• Does NOT include epic detection in il start (that's a separate issue)
• Does NOT include prompt/template changes for swarm mode

Dependencies

None — this is the foundational issue.