# Implementation Plan — Parallel Agent Work Breakdown ## Dependency Graph ``` ┌─────────────────────┐ │ Phase 0: Foundation │ (sequential, orchestrator does this) │ │ │ 1. Monorepo scaffold │ │ 2. types.ts │ │ 3. config.ts + Zod │ │ 4. plugin-registry │ │ 5. All package.json │ └──────────┬────────────┘ │ All Phase 1 agents work against the interfaces defined in types.ts │ ┌──────────┬──────────┬───┴────┬──────────┬──────────┬──────────┐ ▼ ▼ ▼ ▼ ▼ ▼ ▼ Agent 1 Agent 2 Agent 3 Agent 4 Agent 5 Agent 6 Agent 7 Core Runtime Agent SCM + CLI Web Notifier Services Plugins Plugins Tracker Dashboard + Terminal │ │ │ All plugins are independent of │ │ each other — pure interface impls │ │ │ └──────── CLI + Web depend on core services ─────────┘ (can code against interfaces, wire up later) ``` ## Phase 0: Foundation (Sequential — Orchestrator Does This) **Must be done first. Everything else depends on it.** Creates the monorepo scaffold and ALL type definitions. After this, every agent has: - A package to work in (with package.json, tsconfig) - All interfaces defined (they just implement them) - No ambiguity about what to build ### Deliverables 1. `pnpm-workspace.yaml` + root `package.json` + `tsconfig.base.json` 2. `packages/core/src/types.ts` — ALL interfaces (Runtime, Agent, Workspace, Tracker, SCM, Notifier, Terminal, Session, Event, Config, etc.) 3. `packages/core/src/config.ts` — Zod schemas for YAML config validation 4. `packages/core/src/plugin-registry.ts` — Plugin discovery + loading skeleton 5. `packages/core/package.json` + `tsconfig.json` 6. All plugin package scaffolds (package.json + tsconfig + src/index.ts stub) 7. `packages/cli/package.json` + `packages/web/package.json` scaffolds 8. `agent-orchestrator.yaml.example` **Estimated effort**: Medium. ~500-800 lines of types + config. --- ## Phase 1: Parallel Implementation (7 Agents) ### Agent 1: Core Services **Package**: `packages/core/src/` **Branch**: `feat/core-services` **Depends on**: Phase 0 types **Blocked by**: Nothing after Phase 0 | File | What | Reference Script | | ---------------------- | ---------------------------------------------------------------- | ----------------------------------------------- | | `metadata.ts` | Flat-file metadata read/write (key=value) | Metadata parsing in all session managers | | `event-bus.ts` | In-process pub/sub + JSONL persistence | New (inspired by OpenHands event stream) | | `tmux.ts` | tmux command wrappers (list, new, send-keys, capture-pane, kill) | All scripts that call tmux | | `session-manager.ts` | Session CRUD: spawn, list, kill, cleanup, send message | `claude-ao-session` | | `lifecycle-manager.ts` | State machine per session + reaction engine | `claude-review-check` + `claude-session-status` | **Key complexity**: session-manager.ts orchestrates Runtime + Agent + Workspace plugins together. lifecycle-manager.ts runs the polling loop and triggers reactions. **Estimated effort**: Large (~1000-1500 lines) --- ### Agent 2: Runtime + Workspace Plugins **Packages**: `packages/plugins/runtime-tmux/`, `runtime-process/`, `workspace-worktree/`, `workspace-clone/` **Branch**: `feat/runtime-workspace-plugins` **Depends on**: Phase 0 types only **Blocked by**: Nothing after Phase 0 | Plugin | What | Reference | | -------------------- | ------------------------------------------------------------------ | ---------------------------------- | | `runtime-tmux` | Create/destroy tmux sessions, send-keys, capture-pane, alive check | `claude-ao-session` new/kill | | `runtime-process` | Spawn child processes, stdin/stdout, signal handling | New (for headless `claude -p`) | | `workspace-worktree` | `git worktree add/remove/list`, branch naming, symlinks | `claude-ao-session` worktree logic | | `workspace-clone` | `git clone`, cleanup | New (for Docker/cloud runtimes) | **Key complexity**: runtime-tmux must handle send-keys with proper escaping, busy detection, and the wait-for-idle pattern from `send-to-session`. **Estimated effort**: Medium (~600-800 lines) --- ### Agent 3: Agent Plugins **Packages**: `packages/plugins/agent-claude-code/`, `agent-codex/`, `agent-aider/` **Branch**: `feat/agent-plugins` **Depends on**: Phase 0 types only **Blocked by**: Nothing after Phase 0 | Plugin | What | Reference | | ------------------- | ---------------------------------------------------------------------- | ------------------------------------------------------------------- | | `agent-claude-code` | Launch cmd, JSONL activity detection, process tree walk, introspection | `claude-status`, `get-claude-session-info`, `claude-session-status` | | `agent-codex` | Launch cmd, process detection | New | | `agent-aider` | Launch cmd, process detection | New | **Key complexity**: `agent-claude-code` has the richest activity detection — reading JSONL session files, extracting summaries, walking process trees from tmux pane PID to find `claude` process, detecting working/idle/stuck/blocked states. **Estimated effort**: Medium (~500-700 lines) --- ### Agent 4: SCM + Tracker Plugins **Packages**: `packages/plugins/scm-github/`, `tracker-github/`, `tracker-linear/` **Branch**: `feat/scm-tracker-plugins` **Depends on**: Phase 0 types only **Blocked by**: Nothing after Phase 0 | Plugin | What | Reference | | ---------------- | ------------------------------------------------------------------------------------ | ----------------------------------------------------------------- | | `scm-github` | PR detection, CI checks, review comments, automated comments, merge readiness, merge | `claude-review-check`, `claude-bugbot-fix`, dashboard PR fetching | | `tracker-github` | Issue fetch, completion check, branch naming, prompt generation | `claude-splitly-session` (GitHub Issues) | | `tracker-linear` | Issue fetch via GraphQL, completion check, branch naming | `claude-ao-session` + `claude-integrator-session` Linear checks | **Key complexity**: `scm-github` is the largest — it covers PR state, CI checks (gh pr checks), review decision (gh pr view), inline review comments (gh api), automated bot comments (cursor[bot], bugbot), and merge readiness. **Estimated effort**: Large (~800-1000 lines) --- ### Agent 5: CLI **Package**: `packages/cli/` **Branch**: `feat/cli` **Depends on**: Phase 0 types + core interfaces (codes against interfaces, wires up when core is ready) **Partially blocked by**: Agent 1 (core services) for runtime testing | Command | What | Reference Script | | -------------------------------------- | ---------------------------------------------------- | ----------------------------------- | | `ao init` | Interactive setup wizard → `agent-orchestrator.yaml` | New | | `ao status` | Colored terminal table of all sessions | `claude-status` | | `ao spawn [issue]` | Spawn single session | `claude-spawn` | | `ao batch-spawn ` | Batch spawn with dedup | `claude-batch-spawn` | | `ao session ls\|kill\|cleanup` | Session management | `claude-ao-session` ls/kill/cleanup | | `ao send ` | Smart message delivery | `send-to-session` | | `ao review-check [project]` | Trigger PR review fixes | `claude-review-check` | | `ao dashboard` | Start web server | `claude-dashboard` | | `ao open [session\|all]` | Open terminal tabs | `claude-open-all`, `open-iterm-tab` | **Key complexity**: `ao status` needs rich terminal output (colors, columns, live data). `ao batch-spawn` needs duplicate detection. **Can start immediately** by coding against core interfaces. Wire up real implementations when Agent 1 finishes. **Estimated effort**: Large (~800-1200 lines) --- ### Agent 6: Web Dashboard **Package**: `packages/web/` **Branch**: `feat/web-dashboard` **Depends on**: Phase 0 types + core interfaces **Partially blocked by**: Agent 1 (core services) for API routes | Component | What | Reference | | ----------------------------- | --------------------------------------------- | -------------------------------- | | Next.js setup | App Router, Tailwind, dark theme | New | | `GET /api/sessions` | List all sessions with full state | `claude-dashboard` /api/sessions | | `POST /api/spawn` | Spawn new session | New | | `POST /api/sessions/:id/send` | Send message to session | New | | `POST /api/sessions/:id/kill` | Kill session | New | | `POST /api/prs/:id/merge` | Merge PR | New | | `GET /api/events` | SSE stream for real-time updates | New (replaces polling) | | Dashboard page | Attention-prioritized session cards | `claude-dashboard` HTML | | Session detail page | Full session info + terminal embed | New | | Components | SessionCard, PRStatus, CIBadge, AttentionZone | `claude-dashboard` HTML | **Key complexity**: SSE endpoint that streams lifecycle events in real-time. Attention-zone layout. xterm.js terminal embed. **Can start immediately** with mock data, wire up real API when Agent 1 finishes. **Estimated effort**: Large (~1500-2000 lines) --- ### Agent 7: Notifier + Terminal Plugins **Packages**: `packages/plugins/notifier-desktop/`, `notifier-slack/`, `notifier-webhook/`, `terminal-iterm2/`, `terminal-web/` **Branch**: `feat/notifier-terminal-plugins` **Depends on**: Phase 0 types only **Blocked by**: Nothing after Phase 0 | Plugin | What | Reference | | ------------------ | ---------------------------------------------------------------- | ----------------------------------- | | `notifier-desktop` | OS notifications (node-notifier), click → deep link to dashboard | `notify-session` | | `notifier-slack` | Slack webhook messages with action buttons | New | | `notifier-webhook` | Generic HTTP POST | New | | `terminal-iterm2` | AppleScript tab management, reuse existing tabs | `open-iterm-tab`, `claude-open-all` | | `terminal-web` | xterm.js config for web-based terminal | New | **Key complexity**: `notifier-desktop` needs to be cross-platform (macOS/Linux/Windows). `terminal-iterm2` has AppleScript quirks (string length limits, tab detection). **Estimated effort**: Medium (~500-700 lines) --- ## Parallelism Summary ``` Time ──────────────────────────────────────────────────► Phase 0 (orchestrator): ████████░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░ Phase 1 (7 parallel agents): Agent 1 (core): ████████████████████████░░ Agent 2 (runtime): ██████████████░░░░░░░░░░░░ Agent 3 (agent): ██████████████░░░░░░░░░░░░ Agent 4 (scm): ████████████████████░░░░░░ Agent 5 (cli): ████████████████████████░░ ← can start on interfaces, wire later Agent 6 (web): ██████████████████████████ ← can start on UI, wire later Agent 7 (notifier): ██████████░░░░░░░░░░░░░░░░ Phase 2 (integration): after all agents done ████ ← wire everything together, test ``` ### True Independence These agents are **truly independent** after Phase 0: - Agents 2, 3, 4, 7 implement plugin interfaces → zero inter-dependency - Agent 1 (core) is the critical path - Agents 5, 6 can start with mock/interface-only imports, wire later ### Risk: Agent 1 (Core) Is the Bottleneck If core services are delayed, CLI and Web can't fully test. Mitigations: - Agent 1 gets the most experienced agent - Phase 0 writes enough core scaffolding (types, config, plugin-registry) that other agents aren't waiting - CLI and Web start with mock implementations --- ## Linear Tickets (for spawning) | Ticket | Title | Agent | | ------ | ------------------------------------------------------------------------------------- | ----- | | AO-10 | Implement core services (metadata, event-bus, session-manager, lifecycle-manager) | 1 | | AO-11 | Implement runtime + workspace plugins (tmux, process, worktree, clone) | 2 | | AO-12 | Implement agent plugins (claude-code, codex, aider) | 3 | | AO-13 | Implement SCM + tracker plugins (github SCM, github tracker, linear tracker) | 4 | | AO-14 | Implement CLI (ao init, status, spawn, session, send, review-check, dashboard, open) | 5 | | AO-15 | Implement web dashboard (Next.js, API routes, SSE, attention-zone UI, session detail) | 6 | | AO-16 | Implement notifier + terminal plugins (desktop, slack, webhook, iterm2, web) | 7 | ## Spawning Command After Phase 0 is committed to `main`: ```bash ~/claude-batch-spawn ao AO-10 AO-11 AO-12 AO-13 AO-14 AO-15 AO-16 ``` Each agent gets its own worktree branched from main (which contains the scaffold + types).