bkinnightskytw
/
agent-orchestrator
mirror of https://github.com/ComposioHQ/agent-orchestrator.git
1
0
Fork 0
Code Issues Packages Projects Releases Wiki Activity

docs: add parallel implementation plan with 7-agent work breakdown 

Maps dependency graph, identifies 7 truly independent work streams
after Phase 0 (scaffold + types), with Linear tickets and spawn
commands ready to go.

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
This commit is contained in:
Prateek 2026-02-13 16:41:06 +05:30
parent 3eecca8460
commit 36b0792eb6
1 changed files with 261 additions and 0 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

261
artifacts/implementation-plan.md Normal file
View File

@ -0,0 +1,261 @@
# 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 <project> [issue]` | Spawn single session | `claude-spawn` |
| `ao batch-spawn <project> <issues...>` | Batch spawn with dedup | `claude-batch-spawn` |
| `ao session ls\|kill\|cleanup` | Session management | `claude-ao-session` ls/kill/cleanup |
| `ao send <session> <message>` | 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).