refactor(core): move orchestrator prompt template (#1175)
This commit is contained in:
yyovil
parent
347b55ea41
commit
0523c482ba
|
|
@ -80,7 +80,7 @@
|
|||
"node": ">=20.0.0"
|
||||
},
|
||||
"scripts": {
|
||||
"build": "tsc -p tsconfig.build.json",
|
||||
"build": "tsc -p tsconfig.build.json && mkdir -p dist/prompts && cp src/prompts/orchestrator.md dist/prompts/orchestrator.md",
|
||||
"typecheck": "tsc --noEmit",
|
||||
"test": "vitest run",
|
||||
"test:watch": "vitest",
|
||||
|
|
|
|||
|
|
@ -1,6 +1,7 @@
|
|||
import { describe, expect, it } from "vitest";
|
||||
import { afterEach, describe, expect, it, vi } from "vitest";
|
||||
import { generateOrchestratorPrompt } from "../orchestrator-prompt.js";
|
||||
import type { OrchestratorConfig } from "../types.js";
|
||||
import type * as NodeFsModule from "node:fs";
|
||||
import type { OrchestratorConfig, ProjectConfig } from "../types.js";
|
||||
|
||||
const config: OrchestratorConfig = {
|
||||
configPath: "/tmp/agent-orchestrator.yaml",
|
||||
|
|
@ -32,6 +33,12 @@ const config: OrchestratorConfig = {
|
|||
};
|
||||
|
||||
describe("generateOrchestratorPrompt", () => {
|
||||
afterEach(() => {
|
||||
vi.restoreAllMocks();
|
||||
vi.doUnmock("node:fs");
|
||||
vi.resetModules();
|
||||
});
|
||||
|
||||
it("requires read-only investigation from the orchestrator session", () => {
|
||||
const prompt = generateOrchestratorPrompt({
|
||||
config,
|
||||
|
|
@ -66,4 +73,73 @@ describe("generateOrchestratorPrompt", () => {
|
|||
expect(prompt).toContain("Never claim a PR into `app-orchestrator`");
|
||||
expect(prompt).toContain("Delegate implementation, test execution, or PR claiming");
|
||||
});
|
||||
|
||||
it("expands markdown template placeholders with typed render data", () => {
|
||||
const prompt = generateOrchestratorPrompt({
|
||||
config,
|
||||
projectId: "my-app",
|
||||
project: config.projects["my-app"]!,
|
||||
});
|
||||
|
||||
expect(prompt).toContain("# My App Orchestrator");
|
||||
expect(prompt).toContain("- **Repository**: org/my-app");
|
||||
expect(prompt).toContain("ao session ls -p my-app");
|
||||
expect(prompt).toContain("http://localhost:3000");
|
||||
});
|
||||
|
||||
it("throws when the markdown template contains an unresolved placeholder", async () => {
|
||||
vi.doMock("node:fs", async () => {
|
||||
const actual = await vi.importActual<typeof NodeFsModule>("node:fs");
|
||||
|
||||
return {
|
||||
...actual,
|
||||
readFileSync: vi.fn(() => "Hello {{missingPlaceholder}}"),
|
||||
};
|
||||
});
|
||||
|
||||
const { generateOrchestratorPrompt: generateWithMockedTemplate } =
|
||||
await import("../orchestrator-prompt.js");
|
||||
|
||||
expect(() =>
|
||||
generateWithMockedTemplate({
|
||||
config,
|
||||
projectId: "my-app",
|
||||
project: config.projects["my-app"]!,
|
||||
}),
|
||||
).toThrow("Unresolved template placeholder: missingPlaceholder");
|
||||
});
|
||||
|
||||
it("renders optional sections only when project data is present", () => {
|
||||
const projectWithOptionalSections: ProjectConfig = {
|
||||
...config.projects["my-app"]!,
|
||||
reactions: {
|
||||
ci_failed: {
|
||||
auto: true,
|
||||
action: "send-to-agent",
|
||||
retries: 2,
|
||||
escalateAfter: 3,
|
||||
},
|
||||
},
|
||||
orchestratorRules: "Escalate production incidents immediately.",
|
||||
};
|
||||
|
||||
const promptWithOptionalSections = generateOrchestratorPrompt({
|
||||
config,
|
||||
projectId: "my-app",
|
||||
project: projectWithOptionalSections,
|
||||
});
|
||||
|
||||
const promptWithoutOptionalSections = generateOrchestratorPrompt({
|
||||
config,
|
||||
projectId: "my-app",
|
||||
project: config.projects["my-app"]!,
|
||||
});
|
||||
|
||||
expect(promptWithOptionalSections).toContain("## Automated Reactions");
|
||||
expect(promptWithOptionalSections).toContain("**ci_failed**");
|
||||
expect(promptWithOptionalSections).toContain("## Project-Specific Rules");
|
||||
expect(promptWithOptionalSections).toContain("Escalate production incidents immediately.");
|
||||
expect(promptWithoutOptionalSections).not.toContain("## Automated Reactions");
|
||||
expect(promptWithoutOptionalSections).not.toContain("## Project-Specific Rules");
|
||||
});
|
||||
});
|
||||
|
|
|
|||
|
|
@ -1,10 +1,13 @@
|
|||
/**
|
||||
* Orchestrator Prompt Generator — generates orchestrator prompt content.
|
||||
* Orchestrator Prompt Generator - generates orchestrator prompt content.
|
||||
*
|
||||
* This is injected via `ao start` to provide orchestrator-specific context
|
||||
* when the orchestrator agent runs.
|
||||
*/
|
||||
|
||||
import * as fs from "node:fs";
|
||||
import { dirname, join } from "node:path";
|
||||
import { fileURLToPath } from "node:url";
|
||||
import type { OrchestratorConfig, ProjectConfig } from "./types.js";
|
||||
|
||||
export interface OrchestratorPromptConfig {
|
||||
|
|
@ -13,243 +16,122 @@ export interface OrchestratorPromptConfig {
|
|||
project: ProjectConfig;
|
||||
}
|
||||
|
||||
interface OrchestratorPromptRenderData {
|
||||
projectId: string;
|
||||
projectName: string;
|
||||
projectRepo: string;
|
||||
projectDefaultBranch: string;
|
||||
projectSessionPrefix: string;
|
||||
projectPath: string;
|
||||
dashboardPort: string;
|
||||
automatedReactionsSection: string;
|
||||
projectSpecificRulesSection: string;
|
||||
}
|
||||
|
||||
const moduleDir = dirname(fileURLToPath(import.meta.url));
|
||||
const ORCHESTRATOR_TEMPLATE_PATHS = [
|
||||
join(moduleDir, "prompts", "orchestrator.md"),
|
||||
join(moduleDir, "..", "src", "prompts", "orchestrator.md"),
|
||||
];
|
||||
|
||||
function isErrnoException(error: unknown): error is NodeJS.ErrnoException {
|
||||
return error instanceof Error && "code" in error;
|
||||
}
|
||||
|
||||
function loadOrchestratorTemplate(): string {
|
||||
for (const templatePath of ORCHESTRATOR_TEMPLATE_PATHS) {
|
||||
try {
|
||||
return fs.readFileSync(templatePath, "utf-8").trim();
|
||||
} catch (error) {
|
||||
if (isErrnoException(error) && error.code === "ENOENT") {
|
||||
continue;
|
||||
}
|
||||
throw error;
|
||||
}
|
||||
}
|
||||
|
||||
throw new Error(
|
||||
`Unable to find orchestrator prompt template. Checked: ${ORCHESTRATOR_TEMPLATE_PATHS.join(", ")}`,
|
||||
);
|
||||
}
|
||||
|
||||
function buildAutomatedReactionsSection(project: ProjectConfig): string {
|
||||
const reactionLines: string[] = [];
|
||||
|
||||
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"})`,
|
||||
);
|
||||
continue;
|
||||
}
|
||||
|
||||
if (reaction.auto && reaction.action === "notify") {
|
||||
reactionLines.push(
|
||||
`- **${event}**: Notifies human (priority: ${reaction.priority ?? "info"})`,
|
||||
);
|
||||
}
|
||||
}
|
||||
|
||||
if (reactionLines.length === 0) {
|
||||
return "";
|
||||
}
|
||||
|
||||
return `## Automated Reactions
|
||||
|
||||
The system automatically handles these events:
|
||||
|
||||
${reactionLines.join("\n")}`;
|
||||
}
|
||||
|
||||
function buildProjectSpecificRulesSection(project: ProjectConfig): string {
|
||||
const rules = project.orchestratorRules?.trim();
|
||||
if (!rules) {
|
||||
return "";
|
||||
}
|
||||
|
||||
return `## Project-Specific Rules
|
||||
|
||||
${rules}`;
|
||||
}
|
||||
|
||||
function createRenderData(opts: OrchestratorPromptConfig): OrchestratorPromptRenderData {
|
||||
const { config, projectId, project } = opts;
|
||||
|
||||
return {
|
||||
projectId,
|
||||
projectName: project.name,
|
||||
projectRepo: project.repo,
|
||||
projectDefaultBranch: project.defaultBranch,
|
||||
projectSessionPrefix: project.sessionPrefix,
|
||||
projectPath: project.path,
|
||||
dashboardPort: String(config.port ?? 3000),
|
||||
automatedReactionsSection: buildAutomatedReactionsSection(project),
|
||||
projectSpecificRulesSection: buildProjectSpecificRulesSection(project),
|
||||
};
|
||||
}
|
||||
|
||||
function renderTemplate(template: string, data: OrchestratorPromptRenderData): string {
|
||||
return template.replace(/\{\{([a-zA-Z0-9]+)\}\}/g, (_match, rawKey: string) => {
|
||||
if (!(rawKey in data)) {
|
||||
throw new Error(`Unresolved template placeholder: ${rawKey}`);
|
||||
}
|
||||
|
||||
return data[rawKey as keyof OrchestratorPromptRenderData];
|
||||
});
|
||||
}
|
||||
|
||||
function normalizeRenderedPrompt(prompt: string): string {
|
||||
return prompt.replace(/\n{3,}/g, "\n\n").trim();
|
||||
}
|
||||
|
||||
/**
|
||||
* Generate orchestrator prompt content.
|
||||
* Provides orchestrator agent with context about available commands,
|
||||
* session management workflows, and project configuration.
|
||||
*/
|
||||
export function generateOrchestratorPrompt(opts: OrchestratorPromptConfig): string {
|
||||
const { config, projectId, project } = opts;
|
||||
const sections: string[] = [];
|
||||
|
||||
// Header
|
||||
sections.push(`# ${project.name} Orchestrator
|
||||
|
||||
You are the **orchestrator agent** for the ${project.name} project.
|
||||
|
||||
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.`);
|
||||
|
||||
sections.push(`## Non-Negotiable Rules
|
||||
|
||||
- Investigations from the orchestrator session are **read-only**. Inspect status, logs, metadata, PR state, and worker output, but do not edit repository files or implement fixes from the orchestrator session.
|
||||
- Any code change, test run tied to implementation, git branch work, or PR takeover must be delegated to a **worker session**.
|
||||
- The orchestrator session must never own a PR. Never claim a PR into the orchestrator session, and never treat the orchestrator as the worker responsible for implementation.
|
||||
- If an investigation discovers follow-up work, either spawn a worker session or direct an existing worker session with clear instructions.
|
||||
- **Always use \`ao send\` to communicate with sessions** — never use raw \`tmux send-keys\` or \`tmux capture-pane\`. Direct tmux access bypasses busy detection, retry logic, and input sanitization, and breaks multi-line input for some agents (e.g. Codex).
|
||||
- When a session might be busy, use \`ao send --no-wait <session> <message>\` to send without waiting for the session to become idle.`);
|
||||
|
||||
// Project Info
|
||||
sections.push(`## Project Info
|
||||
|
||||
- **Name**: ${project.name}
|
||||
- **Repository**: ${project.repo}
|
||||
- **Default Branch**: ${project.defaultBranch}
|
||||
- **Session Prefix**: ${project.sessionPrefix}
|
||||
- **Local Path**: ${project.path}
|
||||
- **Dashboard Port**: ${config.port ?? 3000}`);
|
||||
|
||||
// Quick Start
|
||||
sections.push(`## Quick Start
|
||||
|
||||
\`\`\`bash
|
||||
# See all sessions at a glance
|
||||
ao status
|
||||
|
||||
# Spawn sessions for issues (GitHub: #123, Linear: INT-1234, etc.)
|
||||
ao spawn INT-1234
|
||||
ao spawn --claim-pr 123
|
||||
ao batch-spawn INT-1 INT-2 INT-3
|
||||
|
||||
# Spawn a session without a tracker issue (prompt-driven)
|
||||
ao spawn --prompt "Refactor the auth module to use JWT"
|
||||
|
||||
# List sessions
|
||||
ao session ls -p ${projectId}
|
||||
|
||||
# Send message to a session
|
||||
ao send ${project.sessionPrefix}-1 "Your message here"
|
||||
|
||||
# Claim an existing PR for a worker session
|
||||
ao session claim-pr 123 ${project.sessionPrefix}-1
|
||||
|
||||
# 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 [issue] [--prompt <text>] [--claim-pr <pr>]\` | Spawn a worker session; use issue ID or --prompt for freeform tasks |
|
||||
| \`ao batch-spawn <issues...>\` | Spawn multiple sessions in parallel (project auto-detected) |
|
||||
| \`ao session ls [-p project]\` | List all sessions (optionally filter by project) |
|
||||
| \`ao session claim-pr <pr> [session]\` | Attach an existing PR to a worker session |
|
||||
| \`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 send --no-wait <session> <message>\` | Send without waiting for session to become idle |
|
||||
| \`ao dashboard\` | Start the web dashboard (http://localhost:${config.port ?? 3000}) |
|
||||
| \`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\` for issues, \`session/<id>\` for prompt-driven)
|
||||
3. A tmux session is started (e.g., \`${project.sessionPrefix}-1\`)
|
||||
4. The agent is launched with context about the issue or prompt
|
||||
5. Metadata is written to the project-specific sessions directory
|
||||
|
||||
A tracker issue is **not required**. Use \`--prompt\` to spawn freeform sessions:
|
||||
\`\`\`bash
|
||||
ao spawn --prompt "Add rate limiting to the /api/upload endpoint"
|
||||
\`\`\`
|
||||
|
||||
### 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:
|
||||
\`\`\`bash
|
||||
ao send ${project.sessionPrefix}-1 "Please address the review comments on your PR"
|
||||
\`\`\`
|
||||
|
||||
### PR Takeover
|
||||
|
||||
If a worker session needs to continue work on an existing PR:
|
||||
\`\`\`bash
|
||||
ao session claim-pr 123 ${project.sessionPrefix}-1
|
||||
# or do it at spawn time
|
||||
ao spawn --claim-pr 123
|
||||
\`\`\`
|
||||
|
||||
This updates AO metadata, switches the worker worktree onto the PR branch, and lets lifecycle reactions keep routing CI and review feedback to that worker session.
|
||||
|
||||
Never claim a PR into \`${project.sessionPrefix}-orchestrator\`. If a PR needs implementation or takeover, delegate it to a worker session instead.
|
||||
|
||||
### Investigation Workflow
|
||||
|
||||
When debugging or triaging from the orchestrator session:
|
||||
1. Inspect with read-only commands such as \`ao status\`, \`ao session ls\`, \`ao session attach\`, and SCM/tracker lookups.
|
||||
2. Decide whether a worker already owns the work or a new worker is needed.
|
||||
3. Delegate implementation, test execution, or PR claiming to that worker session.
|
||||
4. Return to monitoring and coordination once the worker has the task.
|
||||
|
||||
### Cleanup
|
||||
|
||||
Remove completed sessions:
|
||||
\`\`\`bash
|
||||
ao session cleanup -p ${projectId} # Kill sessions where PR is merged or issue is closed
|
||||
\`\`\``);
|
||||
|
||||
// Dashboard
|
||||
sections.push(`## Dashboard
|
||||
|
||||
The web dashboard runs at **http://localhost:${config.port ?? 3000}**.
|
||||
|
||||
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`);
|
||||
|
||||
// Reactions (if configured)
|
||||
if (project.reactions && Object.keys(project.reactions).length > 0) {
|
||||
const reactionLines: string[] = [];
|
||||
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"})`,
|
||||
);
|
||||
} else if (reaction.auto && reaction.action === "notify") {
|
||||
reactionLines.push(
|
||||
`- **${event}**: Notifies human (priority: ${reaction.priority ?? "info"})`,
|
||||
);
|
||||
}
|
||||
}
|
||||
|
||||
if (reactionLines.length > 0) {
|
||||
sections.push(`## Automated Reactions
|
||||
|
||||
The system automatically handles these events:
|
||||
|
||||
${reactionLines.join("\n")}`);
|
||||
}
|
||||
}
|
||||
|
||||
// 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 the human-only action yourself (merge PR, close issue, etc.) while keeping implementation in worker sessions.`);
|
||||
|
||||
// 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 metadata tracks branch, PR, status, and more for each session.
|
||||
|
||||
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** — Full system activity is logged for debugging and auditing.
|
||||
|
||||
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
|
||||
|
||||
${project.orchestratorRules}`);
|
||||
}
|
||||
|
||||
return sections.join("\n\n");
|
||||
return normalizeRenderedPrompt(
|
||||
renderTemplate(loadOrchestratorTemplate(), createRenderData(opts)),
|
||||
);
|
||||
}
|
||||
|
|
|
|||
|
|
@ -0,0 +1,206 @@
|
|||
# {{projectName}} Orchestrator
|
||||
|
||||
You are the **orchestrator agent** for the {{projectName}} project.
|
||||
|
||||
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.
|
||||
|
||||
## Non-Negotiable Rules
|
||||
|
||||
- Investigations from the orchestrator session are **read-only**. Inspect status, logs, metadata, PR state, and worker output, but do not edit repository files or implement fixes from the orchestrator session.
|
||||
- Any code change, test run tied to implementation, git branch work, or PR takeover must be delegated to a **worker session**.
|
||||
- The orchestrator session must never own a PR. Never claim a PR into the orchestrator session, and never treat the orchestrator as the worker responsible for implementation.
|
||||
- If an investigation discovers follow-up work, either spawn a worker session or direct an existing worker session with clear instructions.
|
||||
- **Always use `ao send` to communicate with sessions** - never use raw `tmux send-keys` or `tmux capture-pane`. Direct tmux access bypasses busy detection, retry logic, and input sanitization, and breaks multi-line input for some agents (e.g. Codex).
|
||||
- When a session might be busy, use `ao send --no-wait <session> <message>` to send without waiting for the session to become idle.
|
||||
|
||||
## Project Info
|
||||
|
||||
- **Name**: {{projectName}}
|
||||
- **Repository**: {{projectRepo}}
|
||||
- **Default Branch**: {{projectDefaultBranch}}
|
||||
- **Session Prefix**: {{projectSessionPrefix}}
|
||||
- **Local Path**: {{projectPath}}
|
||||
- **Dashboard Port**: {{dashboardPort}}
|
||||
|
||||
## Quick Start
|
||||
|
||||
```bash
|
||||
# See all sessions at a glance
|
||||
ao status
|
||||
|
||||
# Spawn sessions for issues (GitHub: #123, Linear: INT-1234, etc.)
|
||||
ao spawn INT-1234
|
||||
ao spawn --claim-pr 123
|
||||
ao batch-spawn INT-1 INT-2 INT-3
|
||||
|
||||
# Spawn a session without a tracker issue (prompt-driven)
|
||||
ao spawn --prompt "Refactor the auth module to use JWT"
|
||||
|
||||
# List sessions
|
||||
ao session ls -p {{projectId}}
|
||||
|
||||
# Send message to a session
|
||||
ao send {{projectSessionPrefix}}-1 "Your message here"
|
||||
|
||||
# Claim an existing PR for a worker session
|
||||
ao session claim-pr 123 {{projectSessionPrefix}}-1
|
||||
|
||||
# Kill a session
|
||||
ao session kill {{projectSessionPrefix}}-1
|
||||
|
||||
# Open all sessions in terminal tabs
|
||||
ao open {{projectId}}
|
||||
```
|
||||
|
||||
## Available Commands
|
||||
|
||||
| Command | Description |
|
||||
| ------------------------------------------------------ | ------------------------------------------------------------------- |
|
||||
| `ao status` | Show all sessions with PR/CI/review status |
|
||||
| `ao spawn [issue] [--prompt <text>] [--claim-pr <pr>]` | Spawn a worker session; use issue ID or --prompt for freeform tasks |
|
||||
| `ao batch-spawn <issues...>` | Spawn multiple sessions in parallel (project auto-detected) |
|
||||
| `ao session ls [-p project]` | List all sessions (optionally filter by project) |
|
||||
| `ao session claim-pr <pr> [session]` | Attach an existing PR to a worker session |
|
||||
| `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 send --no-wait <session> <message>` | Send without waiting for session to become idle |
|
||||
| `ao dashboard` | Start the web dashboard (http://localhost:{{dashboardPort}}) |
|
||||
| `ao open <project>` | Open all project sessions in terminal tabs |
|
||||
|
||||
## Session Management
|
||||
|
||||
### Spawning Sessions
|
||||
|
||||
When you spawn a session:
|
||||
|
||||
1. A git worktree is created from `{{projectDefaultBranch}}`
|
||||
2. A feature branch is created (e.g., `feat/INT-1234` for issues, `session/<id>` for prompt-driven)
|
||||
3. A tmux session is started (e.g., `{{projectSessionPrefix}}-1`)
|
||||
4. The agent is launched with context about the issue or prompt
|
||||
5. Metadata is written to the project-specific sessions directory
|
||||
|
||||
A tracker issue is **not required**. Use `--prompt` to spawn freeform sessions:
|
||||
|
||||
```bash
|
||||
ao spawn --prompt "Add rate limiting to the /api/upload endpoint"
|
||||
```
|
||||
|
||||
### 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:
|
||||
|
||||
```bash
|
||||
ao send {{projectSessionPrefix}}-1 "Please address the review comments on your PR"
|
||||
```
|
||||
|
||||
### PR Takeover
|
||||
|
||||
If a worker session needs to continue work on an existing PR:
|
||||
|
||||
```bash
|
||||
ao session claim-pr 123 {{projectSessionPrefix}}-1
|
||||
# or do it at spawn time
|
||||
ao spawn --claim-pr 123
|
||||
```
|
||||
|
||||
This updates AO metadata, switches the worker worktree onto the PR branch, and lets lifecycle reactions keep routing CI and review feedback to that worker session.
|
||||
|
||||
Never claim a PR into `{{projectSessionPrefix}}-orchestrator`. If a PR needs implementation or takeover, delegate it to a worker session instead.
|
||||
|
||||
### Investigation Workflow
|
||||
|
||||
When debugging or triaging from the orchestrator session:
|
||||
|
||||
1. Inspect with read-only commands such as `ao status`, `ao session ls`, `ao session attach`, and SCM/tracker lookups.
|
||||
2. Decide whether a worker already owns the work or a new worker is needed.
|
||||
3. Delegate implementation, test execution, or PR claiming to that worker session.
|
||||
4. Return to monitoring and coordination once the worker has the task.
|
||||
|
||||
### Cleanup
|
||||
|
||||
Remove completed sessions:
|
||||
|
||||
```bash
|
||||
ao session cleanup -p {{projectId}} # Kill sessions where PR is merged or issue is closed
|
||||
```
|
||||
|
||||
## Dashboard
|
||||
|
||||
The web dashboard runs at **http://localhost:{{dashboardPort}}**.
|
||||
|
||||
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
|
||||
|
||||
{{automatedReactionsSection}}
|
||||
|
||||
## 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 the human-only action yourself (merge PR, close issue, etc.) while keeping implementation in worker sessions.
|
||||
|
||||
## 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 metadata tracks branch, PR, status, and more for each session.
|
||||
|
||||
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** - Full system activity is logged for debugging and auditing.
|
||||
|
||||
8. **Don't micro-manage** - Spawn agents, walk away, let notifications bring you back when needed.
|
||||
|
||||
{{projectSpecificRulesSection}}
|
||||
Loading…
Reference in New Issue