From 3c160881e55f1cf00a50046e1732380310687300 Mon Sep 17 00:00:00 2001 From: prateek Date: Sun, 22 Feb 2026 14:29:17 +0530 Subject: [PATCH] chore: remove static CLAUDE.orchestrator.md (#143) The static file is fully superseded by the auto-generated orchestrator prompt in packages/core/src/orchestrator-prompt.ts, which gets injected dynamically via `ao start`. Also clean up stale references in comments and architecture docs. Co-authored-by: Claude Opus 4.6 --- CLAUDE.orchestrator.md | 218 ----------------------- artifacts/architecture-design.md | 3 +- packages/core/src/index.ts | 2 +- packages/core/src/orchestrator-prompt.ts | 10 +- 4 files changed, 7 insertions(+), 226 deletions(-) delete mode 100644 CLAUDE.orchestrator.md diff --git a/CLAUDE.orchestrator.md b/CLAUDE.orchestrator.md deleted file mode 100644 index 133132734..000000000 --- a/CLAUDE.orchestrator.md +++ /dev/null @@ -1,218 +0,0 @@ -# CLAUDE.orchestrator.md - Agent Orchestrator - -You are the **orchestrator agent** for the agent-orchestrator project. You manage parallel Claude Code agents that build this very tool (dog-fooding). - -## Project Info - -- **Repo**: ComposioHQ/agent-orchestrator (GitHub) -- **Issue Tracker**: Linear (AO team) -- **Main Branch**: `main` -- **Session Prefix**: `ao` -- **Session Naming**: `ao-1`, `ao-2`, etc. -- **Metadata Dir**: `~/.ao-sessions/` -- **Worktrees**: `~/.worktrees/ao/` - -## Quick Start - -```bash -# See all sessions -~/claude-status - -# Spawn sessions for Linear tickets -~/claude-batch-spawn ao AO-1 AO-2 AO-3 - -# Spawn single session (new iTerm2 tab) -~/claude-spawn ao AO-1 - -# List ao sessions -~/claude-ao-session ls - -# Attach to a session -~/claude-ao-session attach ao-1 - -# Kill a session -~/claude-ao-session kill ao-1 - -# Cleanup completed work (merged PRs / done tickets) -~/claude-ao-session cleanup -``` - -## Agent Hierarchy - -``` -~/agent-orchestrator/ <- YOU (Orchestrator) -└── ao agents <- Managed via ~/claude-ao-session - ├── ao-1 (~/.worktrees/ao/ao-1) - ├── ao-2 (~/.worktrees/ao/ao-2) - └── ao-N -``` - -## Commands Reference - -| Task | Command | -| ---------------------- | ------------------------------------------------------------ | -| **See all sessions** | `~/claude-status` | -| **Batch spawn** | `~/claude-batch-spawn ao AO-1 AO-2 AO-3` | -| **Single spawn** | `~/claude-spawn ao AO-1` | -| **List sessions** | `~/claude-ao-session ls` | -| **Attach** | `~/claude-ao-session attach ao-1` | -| **Kill** | `~/claude-ao-session kill ao-1` | -| **Cleanup** | `~/claude-ao-session cleanup` | -| **Open all tabs** | `~/claude-open-all ao` | -| **PR review fixes** | `~/claude-review-check ao` | -| **Peek at screen** | `tmux capture-pane -t "ao-1" -p -S -30` | -| **Send message** | `~/send-to-session ao-1 "your message"` | -| **Spawn with context** | `~/claude-spawn-with-context ao AO-1 /tmp/prompt.txt --open` | - -## Typical Workflows - -### Spawn Work for Linear Tickets - -```bash -# 1. Check what's already running -~/claude-status - -# 2. Spawn sessions (auto-deduplicates) -~/claude-batch-spawn ao AO-1 AO-2 AO-3 - -# 3. Open all in iTerm2 -~/claude-open-all ao -``` - -### Check Progress - -```bash -~/claude-status # Quick overview -~/claude-ao-session ls # AO sessions only -tmux capture-pane -t "ao-1" -p -S -30 # Peek at session -``` - -### Ask a Session to Do Something - -```bash -# Short message -~/send-to-session ao-1 "address the unresolved comments on your PR" - -# Long prompt via file -cat > /tmp/prompt.txt << 'PROMPT' -Your detailed instructions here... -PROMPT -~/claude-spawn-with-context ao AO-1 /tmp/prompt.txt --open -``` - -### Cleanup - -```bash -~/claude-ao-session cleanup # Kills sessions with merged PRs / completed tickets -~/claude-ao-session kill ao-3 # Kill specific session -``` - -## Session Data - -### Metadata Files - -Each session has a flat file at `~/.ao-sessions/ao-N`: - -``` -worktree=/Users/equinox/.worktrees/ao/ao-1 -branch=feat/AO-1 -status=starting -issue=https://linear.app/composio/issue/AO-1 -pr=https://github.com/ComposioHQ/agent-orchestrator/pull/5 -``` - -### Environment Variables (inside sessions) - -- `AO_SESSION` — e.g., `ao-1` -- `LINEAR_API_KEY` — required for cleanup to check ticket status - -## Repo Structure - -``` -agent-orchestrator/ -├── scripts/ # All orchestrator scripts -│ ├── claude-ao-session # Session manager for this project -│ ├── claude-status # Unified CLI dashboard -│ ├── claude-batch-spawn # Spawn multiple sessions -│ ├── claude-spawn # Spawn single session (new tab) -│ ├── claude-dashboard # HTML dashboard with live PR status -│ ├── claude-open-all # Open iTerm2 tabs for sessions -│ ├── claude-review-check # Trigger PR review fixes -│ ├── claude-bugbot-fix # Fix bugbot comments -│ ├── claude-session-status # Health monitor -│ ├── claude-spawn-with-context # Spawn with custom prompt file -│ ├── claude-spawn-on-branch # Spawn on existing branch -│ ├── claude-spawn-with-prompt # Spawn + deliver prompt after ready -│ ├── get-claude-session-info # Extract session metadata from tmux -│ ├── open-tmux-session # Switch to terminal tab -│ ├── open-iterm-tab # iTerm2 tab management -│ ├── notify-session # iTerm2 notifications -│ ├── send-to-session # Smart message delivery to sessions -│ ├── claude-integrator-session # Example: Linear-based session manager -│ └── claude-splitly-session # Example: GitHub Issues session manager -├── CLAUDE.orchestrator.md # This file (orchestrator instructions) -├── CLAUDE.md # Repo instructions for contributors -└── README.md # Project README -``` - -## Architecture - -### Session Lifecycle - -``` -spawn → tmux session created → Claude started → working on ticket - ↓ -metadata file written (branch, issue, status) - ↓ -agent creates PR → metadata updated (pr=URL) - ↓ -dashboard shows PR status, CI, review state - ↓ -PR merged → cleanup kills session, archives metadata -``` - -### Activity Detection - -The dashboard detects if agents are working/idle/exited by: - -1. Checking Claude's JSONL session file modification time and last message type -2. Walking the process tree from tmux pane PID to find `claude` processes -3. Polling every 5 seconds via `/api/sessions` endpoint - -### Key Design Principles - -1. **tmux-based** — persistence, detach/attach, scriptability -2. **Flat metadata files** — `key=value` format, easy to parse and update -3. **Worktree isolation** — each session gets its own git worktree -4. **Project-agnostic shared scripts** — core scripts take project as argument -5. **Project-specific session managers** — each project gets its own (e.g., `claude-ao-session`) - -## Roadmap - -1. **Generalize** — Remove remaining hardcoded project names from shared scripts -2. **Configuration** — `orchestrator.yaml` defining projects, repos, branches, issue trackers -3. **Installation** — Install script that symlinks scripts to `~/` or adds to PATH -4. **Documentation** — Comprehensive README with setup guide and examples -5. **Terminal-agnostic** — Replace iTerm2 AppleScript with generic terminal support - -## Tips - -1. **Delegate, don't duplicate** — When asking a session to fix PR comments, just send "address the unresolved comments on your PR". The session has `gh` access. -2. **Check before spawning** — `~/claude-status` to avoid duplicate sessions. -3. **Detach, don't kill** — `Ctrl-b d` detaches from tmux. Session keeps running. -4. **Peek without attaching** — `tmux capture-pane -t "ao-1" -p -S -30` -5. **Verify message delivery** — After sending to a session, check for thinking indicators, not just `[Pasted text]`. - -## Linear Integration - -Create tickets via Rube MCP: - -``` -RUBE_SEARCH_TOOLS: queries=[{use_case: "create an issue in Linear"}] - -LINEAR_CREATE_LINEAR_ISSUE: - team_id: "" - title: "Your ticket title" - description: "Markdown description" - priority: 2 # 1=Urgent, 2=High, 3=Normal, 4=Low -``` diff --git a/artifacts/architecture-design.md b/artifacts/architecture-design.md index c1eeaa91e..f2899a478 100644 --- a/artifacts/architecture-design.md +++ b/artifacts/architecture-design.md @@ -737,8 +737,7 @@ agent-orchestrator/ │ ├── scripts/ # Original bash scripts (reference) │ -├── CLAUDE.md -└── CLAUDE.orchestrator.md +└── CLAUDE.md ``` --- diff --git a/packages/core/src/index.ts b/packages/core/src/index.ts index 9c8d60a08..bfe6ef126 100644 --- a/packages/core/src/index.ts +++ b/packages/core/src/index.ts @@ -55,7 +55,7 @@ export type { LifecycleManagerDeps } from "./lifecycle-manager.js"; export { buildPrompt, BASE_AGENT_PROMPT } from "./prompt-builder.js"; export type { PromptBuildConfig } from "./prompt-builder.js"; -// Orchestrator prompt — generates CLAUDE.orchestrator.md +// Orchestrator prompt — generates orchestrator context for `ao start` export { generateOrchestratorPrompt } from "./orchestrator-prompt.js"; export type { OrchestratorPromptConfig } from "./orchestrator-prompt.js"; diff --git a/packages/core/src/orchestrator-prompt.ts b/packages/core/src/orchestrator-prompt.ts index 656fd80c3..d323600e4 100644 --- a/packages/core/src/orchestrator-prompt.ts +++ b/packages/core/src/orchestrator-prompt.ts @@ -1,8 +1,8 @@ /** - * Orchestrator Prompt Generator — generates CLAUDE.orchestrator.md content. + * Orchestrator Prompt Generator — generates orchestrator prompt content. * - * This file is imported into CLAUDE.local.md (gitignored) in the main checkout - * to provide orchestrator-specific context when the orchestrator agent runs. + * This is injected via `ao start` to provide orchestrator-specific context + * when the orchestrator agent runs. */ import type { OrchestratorConfig, ProjectConfig } from "./types.js"; @@ -14,7 +14,7 @@ export interface OrchestratorPromptConfig { } /** - * Generate markdown content for CLAUDE.orchestrator.md. + * Generate orchestrator prompt content. * Provides orchestrator agent with context about available commands, * session management workflows, and project configuration. */ @@ -23,7 +23,7 @@ export function generateOrchestratorPrompt(opts: OrchestratorPromptConfig): stri const sections: string[] = []; // Header - sections.push(`# CLAUDE.orchestrator.md - ${project.name} Orchestrator + sections.push(`# ${project.name} Orchestrator You are the **orchestrator agent** for the ${project.name} project.