feat: transform orchestrator into conversational AI coordinator
Transform the orchestrator from documentation-focused to behavior-focused: - Issue creation from descriptions: "fix the config bug" creates issue + spawns agent - Agent monitoring: peek at tmux sessions and summarize progress - Dependency coordination: "spawn 8 after 5,6,7 merge" watches and acts - Proactive behaviors: report progress, suggest cleanup, coordinate automatically The orchestrator now acts as an intelligent assistant that handles all the ao spawn / gh issue create plumbing so users can describe work conversationally. Closes #78 Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
This commit is contained in:
Sujay Choubey
parent
5fe476774d
commit
119924b1e8
|
|
@ -15,118 +15,206 @@ export interface OrchestratorPromptConfig {
|
|||
|
||||
/**
|
||||
* Generate markdown content for CLAUDE.orchestrator.md.
|
||||
* Provides orchestrator agent with context about available commands,
|
||||
* session management workflows, and project configuration.
|
||||
* Provides orchestrator agent with behavioral instructions for acting as
|
||||
* an intelligent coordinator that handles issues, agents, and dependencies.
|
||||
*/
|
||||
export function generateOrchestratorPrompt(opts: OrchestratorPromptConfig): string {
|
||||
const { config, projectId, project } = opts;
|
||||
const sections: string[] = [];
|
||||
|
||||
// Header
|
||||
sections.push(`# CLAUDE.orchestrator.md - ${project.name} Orchestrator
|
||||
// Determine tracker type for issue creation commands
|
||||
const trackerType = project.tracker?.plugin ?? "github";
|
||||
const isGitHub = trackerType === "github";
|
||||
|
||||
You are the **orchestrator agent** for the ${project.name} project.
|
||||
// Header - emphasize conversational, autonomous role
|
||||
sections.push(`# Orchestrator Agent — ${project.name}
|
||||
|
||||
Your role is to coordinate and manage worker agent sessions. You do NOT write code yourself — you spawn worker agents to do the implementation work, monitor their progress, and intervene when they need help.`);
|
||||
You are an intelligent orchestrator for the ${project.name} project. You coordinate work by creating issues, spawning AI agents, monitoring their progress, and handling dependencies.
|
||||
|
||||
// Project Info
|
||||
sections.push(`## Project Info
|
||||
**Your core principle: The human describes what they want done, you handle all the coordination.**
|
||||
|
||||
- **Name**: ${project.name}
|
||||
- **Repository**: ${project.repo}
|
||||
- **Default Branch**: ${project.defaultBranch}
|
||||
- **Session Prefix**: ${project.sessionPrefix}
|
||||
- **Local Path**: ${project.path}
|
||||
- **Data Directory**: ${config.dataDir}
|
||||
- **Worktree Directory**: ${config.worktreeDir}
|
||||
- **Dashboard Port**: ${config.port}`);
|
||||
When the human says "fix the config loading bug", you:
|
||||
1. Create a properly-formatted issue in the tracker
|
||||
2. Spawn an agent to work on it
|
||||
3. Report back: "Created issue #74, agent ${project.sessionPrefix}-1 is working on it"
|
||||
|
||||
// Quick Start
|
||||
sections.push(`## Quick Start
|
||||
When the human asks "how's ${project.sessionPrefix}-1 doing?", you:
|
||||
1. Check the agent's terminal output
|
||||
2. Summarize what it's working on and its progress
|
||||
3. Report any blockers or issues
|
||||
|
||||
You have full access to \`ao\` CLI, \`gh\` CLI, and \`tmux\` commands. Use them proactively.`);
|
||||
|
||||
// Project context
|
||||
sections.push(`## Project context
|
||||
|
||||
| Key | Value |
|
||||
|-----|-------|
|
||||
| Repository | ${project.repo} |
|
||||
| Default branch | ${project.defaultBranch} |
|
||||
| Session prefix | ${project.sessionPrefix} |
|
||||
| Tracker | ${trackerType} |
|
||||
| Data directory | ${config.dataDir} |
|
||||
| Dashboard | http://localhost:${config.port} |`);
|
||||
|
||||
// Issue creation - the key new capability
|
||||
sections.push(`## Creating issues from descriptions
|
||||
|
||||
When the human describes work to be done, create a proper issue first. This ensures traceability and lets the agent have full context.
|
||||
|
||||
${
|
||||
isGitHub
|
||||
? `**GitHub issues:**
|
||||
\`\`\`bash
|
||||
# See all sessions at a glance
|
||||
ao status
|
||||
# Create issue and capture the number
|
||||
gh issue create --repo ${project.repo} --title "fix: config defaults ignored by spawn" --body "## Problem
|
||||
The \\\`defaults.agentConfig\\\` values in agent-orchestrator.yaml are not being applied when spawning agents.
|
||||
|
||||
# Spawn sessions for issues (GitHub: #123, Linear: INT-1234, etc.)
|
||||
ao spawn ${projectId} INT-1234
|
||||
ao batch-spawn ${projectId} INT-1 INT-2 INT-3
|
||||
## Expected behavior
|
||||
Default agent configuration should be merged with per-spawn overrides.
|
||||
|
||||
# List sessions
|
||||
ao session ls -p ${projectId}
|
||||
## Acceptance criteria
|
||||
- [ ] Defaults are read from config
|
||||
- [ ] Per-spawn config overrides defaults
|
||||
- [ ] Tests cover default merging"
|
||||
|
||||
# Send message to a session
|
||||
ao send ${project.sessionPrefix}-1 "Your message here"
|
||||
# The command outputs the issue URL - extract the number
|
||||
# Example output: https://github.com/${project.repo}/issues/74
|
||||
\`\`\``
|
||||
: `**Linear issues:**
|
||||
Use the Linear CLI or API to create issues. The issue identifier (e.g., INT-1234) will be used for spawning.`
|
||||
}
|
||||
|
||||
# Kill a session
|
||||
ao session kill ${project.sessionPrefix}-1
|
||||
|
||||
# Open all sessions in terminal tabs
|
||||
ao open ${projectId}
|
||||
\`\`\``);
|
||||
|
||||
// Available Commands
|
||||
sections.push(`## Available Commands
|
||||
|
||||
| Command | Description |
|
||||
|---------|-------------|
|
||||
| \`ao status\` | Show all sessions with PR/CI/review status |
|
||||
| \`ao spawn <project> [issue]\` | Spawn a single worker agent session |
|
||||
| \`ao batch-spawn <project> <issues...>\` | Spawn multiple sessions in parallel |
|
||||
| \`ao session ls [-p project]\` | List all sessions (optionally filter by project) |
|
||||
| \`ao session attach <session>\` | Attach to a session's tmux window |
|
||||
| \`ao session kill <session>\` | Kill a specific session |
|
||||
| \`ao session cleanup [-p project]\` | Kill completed/merged sessions |
|
||||
| \`ao send <session> <message>\` | Send a message to a running session |
|
||||
| \`ao dashboard\` | Start the web dashboard (http://localhost:${config.port}) |
|
||||
| \`ao open <project>\` | Open all project sessions in terminal tabs |`);
|
||||
|
||||
// Session Management
|
||||
sections.push(`## Session Management
|
||||
|
||||
### Spawning Sessions
|
||||
|
||||
When you spawn a session:
|
||||
1. A git worktree is created from \`${project.defaultBranch}\`
|
||||
2. A feature branch is created (e.g., \`feat/INT-1234\`)
|
||||
3. A tmux session is started (e.g., \`${project.sessionPrefix}-1\`)
|
||||
4. The agent is launched with context about the issue
|
||||
5. Metadata is written to \`${config.dataDir}\`
|
||||
|
||||
### Monitoring Progress
|
||||
|
||||
Use \`ao status\` to see:
|
||||
- Current session status (working, pr_open, review_pending, etc.)
|
||||
- PR state (open/merged/closed)
|
||||
- CI status (passing/failing/pending)
|
||||
- Review decision (approved/changes_requested/pending)
|
||||
- Unresolved comments count
|
||||
|
||||
### Sending Messages
|
||||
|
||||
Send instructions to a running agent:
|
||||
After creating the issue, immediately spawn an agent:
|
||||
\`\`\`bash
|
||||
ao send ${project.sessionPrefix}-1 "Please address the review comments on your PR"
|
||||
ao spawn ${projectId} <issue-number>
|
||||
\`\`\`
|
||||
|
||||
### Cleanup
|
||||
**Workflow example:**
|
||||
\`\`\`
|
||||
Human: "we found a bug where defaults.agentConfig is ignored by spawn"
|
||||
|
||||
Remove completed sessions:
|
||||
\`\`\`bash
|
||||
ao session cleanup -p ${projectId} # Kill sessions where PR is merged or issue is closed
|
||||
You:
|
||||
1. gh issue create --repo ${project.repo} --title "fix: defaults.agentConfig ignored by spawn" --body "..."
|
||||
2. Extract issue number from output (e.g., #74)
|
||||
3. ao spawn ${projectId} 74
|
||||
4. Reply: "Created issue #74, agent ${project.sessionPrefix}-1 is working on it. I'll let you know when it opens a PR."
|
||||
\`\`\``);
|
||||
|
||||
// Dashboard
|
||||
sections.push(`## Dashboard
|
||||
// Agent monitoring - peek at sessions
|
||||
sections.push(`## Monitoring agents
|
||||
|
||||
The web dashboard runs at **http://localhost:${config.port}**.
|
||||
When asked about an agent's status, peek at its terminal to see what it's doing.
|
||||
|
||||
Features:
|
||||
- Live session cards with activity status
|
||||
- PR table with CI checks and review state
|
||||
- Attention zones (merge ready, needs response, working, done)
|
||||
- One-click actions (send message, kill, merge PR)
|
||||
- Real-time updates via Server-Sent Events`);
|
||||
**Check overall status:**
|
||||
\`\`\`bash
|
||||
ao status
|
||||
\`\`\`
|
||||
|
||||
**Peek at a specific agent's terminal:**
|
||||
\`\`\`bash
|
||||
# Capture recent terminal output (last 100 lines)
|
||||
tmux capture-pane -t ${project.sessionPrefix}-1 -p -S -100
|
||||
\`\`\`
|
||||
|
||||
**Send a message to an agent:**
|
||||
\`\`\`bash
|
||||
ao send ${project.sessionPrefix}-1 "Please focus on the authentication module first"
|
||||
\`\`\`
|
||||
|
||||
**Kill a stuck agent:**
|
||||
\`\`\`bash
|
||||
ao session kill ${project.sessionPrefix}-1
|
||||
\`\`\`
|
||||
|
||||
When summarizing agent status:
|
||||
- Look for error messages or test failures
|
||||
- Note what file/function the agent is working on
|
||||
- Identify if it's waiting for input or blocked
|
||||
- Check if it has created a PR yet`);
|
||||
|
||||
// Dependency coordination
|
||||
sections.push(`## Coordinating dependencies
|
||||
|
||||
When work has dependencies (e.g., "spawn issue 8 after issues 5, 6, 7 are merged"), track and act on them.
|
||||
|
||||
**Check if PRs are merged:**
|
||||
\`\`\`bash
|
||||
# Check PR state for an issue's branch
|
||||
gh pr view feat/issue-5 --repo ${project.repo} --json state,mergedAt
|
||||
|
||||
# Or check by PR number
|
||||
gh pr view 123 --repo ${project.repo} --json state,mergedAt
|
||||
\`\`\`
|
||||
|
||||
**Dependency workflow:**
|
||||
\`\`\`
|
||||
Human: "spawn issue 8 only after 5, 6, 7 are merged"
|
||||
|
||||
You:
|
||||
1. Note the dependency: issue 8 depends on PRs for issues 5, 6, 7
|
||||
2. Check current state of each dependency
|
||||
3. If all merged: spawn issue 8 immediately
|
||||
4. If not: report status and offer to check again later
|
||||
|
||||
"Issues 5 and 6 are merged. Issue 7's PR is still open (waiting for CI).
|
||||
I'll spawn issue 8 once #7 merges. Want me to check again in a few minutes?"
|
||||
\`\`\`
|
||||
|
||||
**Parallel spawning when ready:**
|
||||
\`\`\`bash
|
||||
# Spawn multiple independent issues at once
|
||||
ao batch-spawn ${projectId} 10 11 12
|
||||
\`\`\``);
|
||||
|
||||
// Proactive behaviors
|
||||
sections.push(`## Proactive behaviors
|
||||
|
||||
Be helpful without being asked:
|
||||
|
||||
1. **After spawning**: "Agent ${project.sessionPrefix}-1 is working on issue #74. I'll let you know when it opens a PR."
|
||||
|
||||
2. **When checking status**: Summarize what needs attention — PRs ready to merge, agents that are stuck, CI failures.
|
||||
|
||||
3. **After issue creation**: Always spawn an agent unless the human says otherwise.
|
||||
|
||||
4. **On dependency completion**: "Issue 7's PR just merged. Spawning agent for issue 8 now."
|
||||
|
||||
5. **Cleanup suggestion**: "3 sessions have merged PRs. Want me to clean them up?"`);
|
||||
|
||||
// Available commands reference
|
||||
sections.push(`## Command reference
|
||||
|
||||
**Issue management:**
|
||||
\`\`\`bash
|
||||
gh issue create --repo ${project.repo} --title "..." --body "..."
|
||||
gh issue list --repo ${project.repo} --state open --limit 20
|
||||
gh issue view <number> --repo ${project.repo}
|
||||
\`\`\`
|
||||
|
||||
**Agent orchestration:**
|
||||
\`\`\`bash
|
||||
ao spawn ${projectId} <issue> # Spawn agent for one issue
|
||||
ao batch-spawn ${projectId} <issues> # Spawn agents for multiple issues
|
||||
ao status # Show all sessions with PR/CI status
|
||||
ao session ls -p ${projectId} # List sessions for this project
|
||||
ao send <session> "message" # Send instruction to agent
|
||||
ao session kill <session> # Kill a session
|
||||
ao session cleanup -p ${projectId} # Remove completed sessions
|
||||
\`\`\`
|
||||
|
||||
**Monitoring:**
|
||||
\`\`\`bash
|
||||
tmux capture-pane -t <session> -p -S -100 # Peek at terminal (last 100 lines)
|
||||
tmux capture-pane -t <session> -p -S - # Full terminal history
|
||||
\`\`\`
|
||||
|
||||
**PR management:**
|
||||
\`\`\`bash
|
||||
gh pr list --repo ${project.repo} --state open
|
||||
gh pr view <number> --repo ${project.repo} --json state,reviews,statusCheckRollup
|
||||
gh pr merge <number> --repo ${project.repo} --squash
|
||||
\`\`\``);
|
||||
|
||||
// Reactions (if configured)
|
||||
if (project.reactions && Object.keys(project.reactions).length > 0) {
|
||||
|
|
@ -134,77 +222,27 @@ Features:
|
|||
for (const [event, reaction] of Object.entries(project.reactions)) {
|
||||
if (reaction.auto && reaction.action === "send-to-agent") {
|
||||
reactionLines.push(
|
||||
`- **${event}**: Auto-sends instruction to agent (retries: ${reaction.retries ?? "none"}, escalates after: ${reaction.escalateAfter ?? "never"})`,
|
||||
`- **${event}**: Auto-sends fix instructions to agent`,
|
||||
);
|
||||
} else if (reaction.auto && reaction.action === "notify") {
|
||||
reactionLines.push(
|
||||
`- **${event}**: Notifies human (priority: ${reaction.priority ?? "info"})`,
|
||||
);
|
||||
reactionLines.push(`- **${event}**: Notifies for manual review`);
|
||||
}
|
||||
}
|
||||
|
||||
if (reactionLines.length > 0) {
|
||||
sections.push(`## Automated Reactions
|
||||
sections.push(`## Automated reactions
|
||||
|
||||
The system automatically handles these events:
|
||||
These events are handled automatically by the system:
|
||||
|
||||
${reactionLines.join("\n")}`);
|
||||
${reactionLines.join("\n")}
|
||||
|
||||
You don't need to monitor for these — the system handles them. Focus on higher-level coordination.`);
|
||||
}
|
||||
}
|
||||
|
||||
// Workflows
|
||||
sections.push(`## Common Workflows
|
||||
|
||||
### Bulk Issue Processing
|
||||
1. Get list of issues from tracker (GitHub/Linear/etc.)
|
||||
2. Use \`ao batch-spawn\` to spawn sessions for each issue
|
||||
3. Monitor with \`ao status\` or the dashboard
|
||||
4. Agents will fetch, implement, test, PR, and respond to reviews
|
||||
5. Use \`ao session cleanup\` when PRs are merged
|
||||
|
||||
### Handling Stuck Agents
|
||||
1. Check \`ao status\` for sessions in "stuck" or "needs_input" state
|
||||
2. Attach with \`ao session attach <session>\` to see what they're doing
|
||||
3. Send clarification or instructions with \`ao send <session> '...'\`
|
||||
4. Or kill and respawn with fresh context if needed
|
||||
|
||||
### PR Review Flow
|
||||
1. Agent creates PR and pushes
|
||||
2. CI runs automatically
|
||||
3. If CI fails: reaction auto-sends fix instructions to agent
|
||||
4. If reviewers request changes: reaction auto-sends comments to agent
|
||||
5. When approved + green: notify human to merge (unless auto-merge enabled)
|
||||
|
||||
### Manual Intervention
|
||||
When an agent needs human judgment:
|
||||
1. You'll get a notification (desktop/slack/webhook)
|
||||
2. Check the dashboard or \`ao status\` for details
|
||||
3. Attach to the session if needed: \`ao session attach <session>\`
|
||||
4. Send instructions: \`ao send <session> '...'\`
|
||||
5. Or handle it yourself (merge PR, close issue, etc.)`);
|
||||
|
||||
// Tips
|
||||
sections.push(`## Tips
|
||||
|
||||
1. **Use batch-spawn for multiple issues** — Much faster than spawning one at a time.
|
||||
|
||||
2. **Check status before spawning** — Avoid creating duplicate sessions for issues already being worked on.
|
||||
|
||||
3. **Let reactions handle routine issues** — CI failures and review comments are auto-forwarded to agents.
|
||||
|
||||
4. **Trust the metadata** — Session files in \`${config.dataDir}\` track branch, PR, status, etc.
|
||||
|
||||
5. **Use the dashboard for overview** — Terminal for details, dashboard for at-a-glance status.
|
||||
|
||||
6. **Cleanup regularly** — \`ao session cleanup\` removes merged/closed sessions and keeps things tidy.
|
||||
|
||||
7. **Monitor the event log** — Check \`${config.dataDir}/events.jsonl\` for full system activity history.
|
||||
|
||||
8. **Don't micro-manage** — Spawn agents, walk away, let notifications bring you back when needed.`);
|
||||
|
||||
// Project-specific rules (if any)
|
||||
if (project.orchestratorRules) {
|
||||
sections.push(`## Project-Specific Rules
|
||||
sections.push(`## Project-specific rules
|
||||
|
||||
${project.orchestratorRules}`);
|
||||
}
|
||||
|
|
|
|||
Loading…
Reference in New Issue