Prime

Prime — Orchestrator

Complete startup checklist for new agent sessions.

Pattern: This skill uses the orchestrator-subagent pattern. Each phase runs in a fresh context for optimal multi-agent coordination. See docs/guides/ORCHESTRATOR_SUBAGENT_PATTERN.md.

When This Applies

Tool Reference

Agent Mail (MCP)

Bash Commands

Message Subjects

Architecture

┌─────────────────────────────────────────────────────────────────┐
│                      PRIME ORCHESTRATOR                          │
│  - Creates session: sessions/prime-{timestamp}/                  │
│  - Manages TodoWrite state                                       │
│  - Spawns subagents with minimal context                         │
│  - Passes agent_name between phases                              │
└─────────────────────────────────────────────────────────────────┘
                              │
         ┌────────────────────┼────────────────────┐
         │                    │                    │
         ▼                    ▼                    ▼
┌─────────────────┐  ┌─────────────────┐  ┌─────────────────┐
│    Identity     │  │     Orient      │  │   Coordinate    │
│  agents/        │  │  agents/        │  │  agents/        │
│  identity.md    │  │  orient.md      │  │  coordinate.md  │
└────────┬────────┘  └────────┬────────┘  └────────┬────────┘
         │                    │                    │
    01_identity.md       02_orientation.md   03_coordination.md
         │                    │                    │
         │      agent_name    │    active_agents   │    blocked_files
         └────────────────────┼────────────────────┘
                              │
                              ▼
                    ┌─────────────────┐
                    │    Discover     │ → Recommends task
                    │  agents/        │
                    │  discover.md    │
                    └────────┬────────┘
                             │
                        04_discovery.md

Subagents

Execution Flow

1. Setup (Orchestrator)

1. Create session directory:
   mkdir -p sessions/prime-{timestamp}

2. Initialize TodoWrite with phases:
   - [ ] Phase 1: Identity
   - [ ] Phase 2: Orient
   - [ ] Phase 3: Coordinate
   - [ ] Phase 4: Discover

3. Gather inputs:
   - project_path: Absolute path to project
   - program: "claude-code"
   - model: "opus-4.5"

2. Phase 1: Identity

Spawn: agents/identity.md

Input:

{
  "project_path": "/abs/path/to/project",
  "session_dir": "sessions/prime-{timestamp}",
  "program": "claude-code",
  "model": "opus-4.5"
}

Output:

{
  "agent_name": "BlueLake",
  "registered": true
}

3. Phase 2: Orient

Spawn: agents/orient.md

Input:

{
  "project_path": "/abs/path/to/project",
  "session_dir": "sessions/prime-{timestamp}",
  "agent_name": "BlueLake"
}

Output:

{
  "active_agents": ["GreenCastle", "RedStone"],
  "recent_sessions_summary": "Auth module, rate limiting",
  "git_branch": "feature/user-auth"
}

4. Phase 3: Coordinate

Spawn: agents/coordinate.md

Input:

{
  "project_path": "/abs/path/to/project",
  "session_dir": "sessions/prime-{timestamp}",
  "agent_name": "BlueLake",
  "active_agents": ["GreenCastle", "RedStone"]
}

Output:

{
  "urgent_messages": 0,
  "blocked_files": ["src/api/**", "migrations/**"],
  "greeting_sent": true
}

5. Phase 4: Discover

Spawn: agents/discover.md

Input:

{
  "project_path": "/abs/path/to/project",
  "session_dir": "sessions/prime-{timestamp}",
  "agent_name": "BlueLake",
  "blocked_files": ["src/api/**", "migrations/**"],
  "requires_response": []
}

Output:

{
  "recommended_task": {
    "id": "bd-125",
    "title": "JWT validation",
    "files": ["src/auth/**"]
  },
  "can_claim": true
}

6. Finalize (Orchestrator)

1. Update TodoWrite (all phases complete)
2. Present startup summary to user
3. If task recommended and user approves, proceed to claim

Configuration

Set these for your project:

PROJECT_PATH="/abs/path/to/your/project"  # Agent Mail project_key
PROJECT_NAME="Your Project Name"

If working across repos, use ONE canonical "coordination root" for Agent Mail + Beads.

Step 1: Announce Identity

echo -ne "\033]0;[AgentName] | PROJECT_NAME\007"

Update after registration with your actual name.

Step 2: Register with Agent Mail

PREFERRED: Use macro_start_session for simplicity:

result = macro_start_session(
  human_key="PROJECT_PATH",
  program="claude-code",
  model="opus-4.5",
  file_reservation_paths=["src/**"],  # Optional: reserve files upfront
  inbox_limit=10
)
agent_name = result["agent"]["name"]
# Includes: project, agent_name, file_reservations, inbox

ALTERNATIVE: Manual steps:

ensure_project(human_key="PROJECT_PATH")

register_agent(
  project_key="PROJECT_PATH",
  program="claude-code",
  model="opus-4.5",
  task_description="Agent - [your focus]"
)
# SAVE YOUR AGENT NAME from response (e.g., "BlueLake")

set_contact_policy(
  project_key="PROJECT_PATH",
  agent_name="YOUR_AGENT_NAME",
  policy="open"
)

Update terminal:

echo -ne "\033]0;[YOUR_AGENT_NAME] | PROJECT_NAME\007"

Step 3: Orient

Read AGENTS.md:

Read("AGENTS.md")

Check recent session history:

cass search "PROJECT_NAME" --workspace "PROJECT_PATH" --robot --days 7 --limit 5

Get learned patterns for context:

cm context "starting work on PROJECT_NAME" --json

This returns relevant rules, anti-patterns, and historical context to inform your work.

Step 4: Coordinate

Check inbox:

fetch_inbox(
  project_key="PROJECT_PATH",
  agent_name="YOUR_AGENT_NAME",
  include_bodies=true,
  limit=20
)

Discover other agents:

ReadMcpResourceTool(
  server="mcp-agent-mail",
  uri="resource://agents/PROJECT_PATH"
)

Send greeting:

send_message(
  project_key="PROJECT_PATH",
  sender_name="YOUR_AGENT_NAME",
  to=["OtherAgent1", "OtherAgent2"],
  subject="Agent Online",
  body_md="I'm online. Focusing on: [task]. What needs attention?",
  importance="normal"
)

Step 5: Discover Work

git status
git log --oneline -5
bd ready --json
bv --robot-triage

For multi-agent, use track grouping:

bv --robot-triage --robot-triage-by-track

Step 6: Claim Task

PREFERRED: Use bd-claim for atomic claim + reserve:

bd-claim <task-id> --paths "app/services/**"

This atomically:

1. Validates you're registered
2. Checks the bead is claimable
3. Reserves the files
4. Updates the bead status
5. Updates your local state

If file reservation fails, nothing is changed. If bead update fails after reservation, files are automatically released.

ALTERNATIVE: Manual steps (use bd-claim instead):

bd update <task-id> --status in_progress --assignee YOUR_AGENT_NAME

file_reservation_paths(
  project_key="PROJECT_PATH",
  agent_name="YOUR_AGENT_NAME",
  paths=["app/services/**"],
  ttl_seconds=3600,
  exclusive=true,
  reason="<task-id>: brief description"
)

Step 7: Output Summary

## Agent Initialized

**Name:** [YOUR_AGENT_NAME]
**Focus:** [task description]
**Repo:** PROJECT_NAME

### Context
- Recent sessions: [summary from CASS]
- Inbox: [X messages, Y requiring response]
- Active agents: [list]

### Task Claimed
- **ID:** [task-id]
- **Title:** [task title]
- **Files reserved:** [list]

### Ready to Work
[State your plan for the task]

After Priming

When done or switching tasks:

1. Run tests / builds
2. Run ubs --staged (MANDATORY GATE)
   • Zero high/critical findings required
   • Medium findings require documented justification
   • This is NOT optional—~40% of LLM code has vulnerabilities
3. Commit (include .beads/issues.jsonl) and push
4. Release file reservations
5. Close sub-beads first, then parent
6. Run /next-bead for next task

Mandatory Rules (2025 Research)

See bead-workflow/ for full details on these gates.

See Also

• bead-workflow/ — Claiming and closing beads
• project-memory/ — Past session context

Converted and distributed by TomeVault — claim your Tome and manage your conversions.