prime

name	prime
description	New agent startup checklist for Agent Mail and Beads. Use when starting a new agent session, when the user says "prime" or "startup", or when beginning work on a multi-agent project. Use when this capability is needed.
metadata	{"author":"eaasxt"}

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

Signal	Action
New session starting	Run full checklist
User says "/prime"	Run full checklist
User says "startup" or "initialize"	Run full checklist
Multi-agent coordination needed	Run full checklist

---

Tool Reference

Agent Mail (MCP)

Tool	Purpose
macro_start_session(human_key, program, model)	PREFERRED: All-in-one startup
ensure_project(human_key)	Initialize project in Agent Mail
register_agent(project_key, program, model)	Register and get agent name
set_contact_policy(agent_name, policy)	Set to "open" for coordination
fetch_inbox(agent_name, limit)	Check for messages
send_message(to, subject, body_md)	Send greeting/announcements
file_reservation_paths(paths, exclusive)	Reserve files before editing

Bash Commands

Command	Purpose
cm context "task description" --json	Get patterns + anti-patterns before work
cass search "query" --robot --days 7	Search session history
bd ready --json	List available tasks
bv --robot-triage	Get task recommendations
bd-claim <id> --paths "..."	PREFERRED: Atomic claim + reserve
bd update <id> --status in_progress --assignee NAME	Manual claim (use bd-claim instead)
git status	Check repo state
git log --oneline -5	Recent commits

Message Subjects

Pattern	When
Agent Online	After registration
[CLAIMED] bd-XXX - Title	When claiming task

---

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

Phase	Agent	Input	Output
1	agents/identity.md	project_path	agent_name, registered
2	agents/orient.md	project_path, agent_name	context, active_agents
3	agents/coordinate.md	agent_name, active_agents	inbox, blocked_files
4	agents/discover.md	agent_name, blocked_files	recommended_task

---

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)

Rule	Why	Evidence
TDD-first	45.97% higher success	research/054-tdd-ai-code-gen.md
ubs --staged mandatory	~40% of LLM code has vulnerabilities	research/052-llm-security-vulnerabilities.md
Max 3 iterations	Security degrades with more	research/053-feedback-loop-security.md
Escalate after 3 failures	Don't waste time debugging	Stop, spike, notify operator

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.