pi-messenger-crew

name	pi-messenger-crew
description	Orchestrator reference for pi-messenger Crew planning, task management, configuration, and agent coordination. Crew workers already have the pi_messenger actions they need in crew-worker.md.

Pi-Messenger Crew Skill

Crew workers do not need this skill. crew-worker.md already contains every pi_messenger action workers need for task execution.

Orchestrators and humans can use this as the full reference for planning, task management, configuration, and Crew internals.

Use pi-messenger for multi-agent coordination and Crew task orchestration.

Quick Reference

Join or Leave the Mesh

pi_messenger({ action: "join" })
pi_messenger({ action: "leave" })

Check Status

pi_messenger({ action: "status" })
pi_messenger({ action: "list" })  // See other agents
pi_messenger({ action: "feed" })  // Activity feed

Crew Workflow

1. Check Crew Agents

pi_messenger({ action: "crew.agents" })  // Verify 5 agents
pi_messenger({ action: "crew.install" }) // Informational: shows discovered sources

2. Plan from PRD

// Auto-discover PRD.md in current directory
pi_messenger({ action: "plan" })

// Or specify path
pi_messenger({ action: "plan", prd: "path/to/PRD.md" })

// Or pass an inline prompt (no PRD file needed)
pi_messenger({ action: "plan", prompt: "Scan the codebase for bugs focusing on error handling" })

// Re-plan with a steering prompt (wipes existing tasks, preserves progress notes)
pi_messenger({ action: "plan", prompt: "Split the auth module into login and registration" })

// Steer first-time planning (prompt injected into progress notes before planner runs)
pi_messenger({ action: "plan", prd: "docs/PRD.md", prompt: "focus on backend first" })

// Plan + auto-start autonomous work when planning completes
pi_messenger({ action: "plan" })  // auto-starts workers (default)

// Cancel active or stale planning
pi_messenger({ action: "plan.cancel" })

Re-planning rejects if any tasks are in_progress — stop or complete them first. The steering prompt is injected into planning-progress.md's Notes section where the planner reads it on every pass.

Optional: Activate Team Context

pi_messenger({ action: "team.setup", name: "migration-squad" })
pi_messenger({ action: "team.setup", name: "review-squad" })
pi_messenger({ action: "team.setup", name: "research-squad", message: "Research first, then plan the implementation." })
pi_messenger({ action: "team.memory.note", type: "decision", message: "Use cursor pagination for task history" })
pi_messenger({ action: "team.roles" })
pi_messenger({ action: "team.status" })

Team is optional. Use team.setup for first-run setup: it activates a profile, saves editable JSON if needed, creates a starter charter when missing, and returns next steps. Crew remains the execution engine. Team role names follow the packaged pi-subagents vocabulary where possible (context-builder, delegate, oracle, planner, researcher, reviewer, scout, worker). pi-messenger may read subagent markdown metadata from disk when present, but it does not require or invoke subagents. Active Team profiles let the planner tag tasks with role and riskLabels, then inject role, charter, and memory context into worker prompts. High-risk tasks wait for task.approve; task.reject records feedback and rejected tasks surface task.revise / task.revise-tree next steps.

3. Work on Tasks

// Single wave (runs ready tasks once)
pi_messenger({ action: "work" })

// Autonomous (keeps running until done/blocked)
pi_messenger({ action: "work", autonomous: true })

// Override concurrency or model for this wave
pi_messenger({ action: "work", autonomous: true, concurrency: 4 })
pi_messenger({ action: "work", model: "claude-sonnet-4-20250514" })

4. Task Management

pi_messenger({ action: "task.list" })
pi_messenger({ action: "task.ready" })  // Tasks with no pending deps
pi_messenger({ action: "task.show", id: "task-1" })
pi_messenger({ action: "task.start", id: "task-1" })
pi_messenger({ action: "task.progress", id: "task-1", message: "Implemented auth middleware" })
pi_messenger({ action: "task.done", id: "task-1", summary: "What was done" })
pi_messenger({ action: "task.block", id: "task-1", reason: "Why blocked" })
pi_messenger({ action: "task.unblock", id: "task-1" })
pi_messenger({ action: "task.reset", id: "task-1" })
pi_messenger({ action: "task.reset", id: "task-1", cascade: true })  // Reset dependents too

// Create tasks manually
pi_messenger({ action: "task.create", title: "Implement auth", content: "Detailed spec...", dependsOn: ["task-1"] })
pi_messenger({ action: "task.create", title: "Change auth API", role: "worker", riskLabels: ["auth", "api-contract"] })
pi_messenger({ action: "task.approve", id: "task-2" })

// Split a task into subtasks (two-phase: inspect then execute)
pi_messenger({ action: "task.split", id: "task-3" })  // Inspect: shows spec, deps, dependents
pi_messenger({ action: "task.split", id: "task-3", subtasks: [
  { title: "Subtask A", content: "..." },
  { title: "Subtask B", content: "..." }
] })  // Execute: creates subtasks, parent becomes milestone

5. Task Revision

// Revise a single task's spec (planner rewrites based on your prompt)
pi_messenger({ action: "task.revise", id: "task-3", prompt: "add error handling for network failures" })

// Revise a task and all its transitive dependents (subtree revision)
// Planner sees the full subtree and can add/remove/modify tasks
pi_messenger({ action: "task.revise-tree", id: "task-3", prompt: "split this into separate API and CLI tasks" })

Single revision rewrites one task's spec. Tree revision rewrites an entire subtree — the planner can modify existing tasks, add new ones (capped at 2x subtree size), remove pending ones, and rewire dependencies. Done tasks in the subtree are preserved; revisable tasks reset to todo.

Both revisions are mutually exclusive (only one revision at a time).

6. Review

// Review a task implementation
pi_messenger({ action: "review", target: "task-1" })

// Review the overall plan
pi_messenger({ action: "review", target: "plan", type: "plan" })

Overlay Keybindings

The Crew overlay (accessible via /messenger then tab to Crew) supports these keybindings:

Global: [+/-] Adjust worker concurrency (1-10), [c] Cancel active planning, [Esc] Close/back

Task list view: [↑/↓] Navigate, [Enter] Detail view

Task actions (list and detail):

• [s] Start task (todo only)
• [r] Reset task, [R] Cascade reset (reset + all dependents)
• [u] Unblock task (blocked only)
• [b] Block with reason (in_progress only)
• [q] Stop worker (in_progress with live worker)
• [m] Message worker (in_progress with live worker)
• [S] Split task (shows hint with command)
• [p] Revise task spec, [P] Revise subtree (not in_progress, not milestone)
• [x] Delete task (not while worker is active)
• [←/→] Navigate between tasks in detail view

File Coordination

// Reserve files before editing
pi_messenger({ action: "reserve", paths: ["src/index.ts", "src/types.ts"], reason: "Working on core" })

// Release when done
pi_messenger({ action: "release" })

Agent Communication

// Rename yourself
pi_messenger({ action: "rename", name: "MyAgentName" })

// Send message to specific agent
pi_messenger({ action: "send", to: "OtherAgent", message: "Hello!" })

// Broadcast to all
pi_messenger({ action: "broadcast", message: "Announcement" })

Messages are logged to the feed and visible in the overlay. DMs interrupt only the target agent (delivered as steering); broadcasts interrupt all agents.

Typical Crew Session

// 1. Join
pi_messenger({ action: "join" })

// 2. Plan (spawns planner agent)
pi_messenger({ action: "plan" })

// 3. Check tasks
pi_messenger({ action: "task.list" })

// 4. Work
pi_messenger({ action: "work", autonomous: true })

// 5. Status
pi_messenger({ action: "status" })

Data Storage

Crew stores data in .pi/messenger/crew/:

.pi/messenger/crew/
├── config.json              # Project config (concurrency, models, coordination, etc.)
├── plan.json                # Plan metadata
├── planning-progress.md     # Planner output log (Notes section for steering)
├── planning-outline.md      # Latest plan outline
├── planning-state.json      # Current planning phase/pass
├── agents/                  # Optional: project-level crew agent overrides
│   └── crew-worker.md
├── tasks/
│   ├── task-1.json          # Task metadata (status, deps, summary)
│   ├── task-1.md            # Task spec (planner-generated)
│   ├── task-1.progress.md   # Worker progress log
│   └── ...
├── blocks/
│   └── task-N.md            # Block context
└── artifacts/               # Debug artifacts (agent input/output)

Team stores active project state in .pi/messenger/team/:

.pi/messenger/team/
├── team.json        # Active team/profile
├── charter.md       # Project team charter
├── memory.jsonl     # Structured memory source of truth
├── decisions.md     # Human-readable memory rollups
├── interfaces.md
├── risks.md
└── handoffs.md

Reusable profiles are JSON files under ~/.pi/agent/messenger/team-profiles/.

The activity feed lives at .pi/messenger/feed.jsonl (project-scoped, shared across all agents in the project).

Each crew agent ships with a default model:

Agent	Role	Default Model
crew-planner	planner	anthropic/claude-opus-4-6
crew-worker	worker	anthropic/claude-haiku-4-5
crew-reviewer	reviewer	anthropic/claude-opus-4-6
crew-plan-sync	analyst	anthropic/claude-haiku-4-5

Override via crew.models.<role> in config. To customize an agent for a project, copy it from ~/.pi/agent/extensions/pi-messenger/crew/agents/ to .pi/messenger/crew/agents/ and edit the frontmatter — project-level agents override extension defaults by name. Agents support thinking: <level> in frontmatter (off, minimal, low, medium, high, xhigh). Config thinking.<role> overrides the frontmatter value.

Configuration

User-level config goes in ~/.pi/agent/pi-messenger.json under a crew key. Project-level config goes in .pi/messenger/crew/config.json. Project overrides user, both override defaults.

Crew spawns multiple LLM sessions in parallel — start with a cheap worker model and scale up. Add this to ~/.pi/agent/pi-messenger.json:

{ "crew": { "models": { "worker": "claude-haiku-4-5" } } }

Model strings accept provider/model format for explicit provider selection and :level suffix for inline thinking control:

{ "crew": { "models": { "worker": "anthropic/claude-haiku-4-5", "planner": "openrouter/anthropic/claude-sonnet-4:high" } } }

The :level suffix and the thinking.<role> config are independent — if both are set, the suffix takes precedence.

Full example (~/.pi/agent/pi-messenger.json):

{
  "crew": {
    "concurrency": { "workers": 3, "max": 6 },
    "models": { "worker": "claude-haiku-4-5", "planner": "claude-sonnet-4-6" },
    "coordination": "chatty",
    "work": { "maxAttemptsPerTask": 5 }
  }
}

Project-level (.pi/messenger/crew/config.json):

{
  "concurrency": { "workers": 4 },
  "coordination": "moderate",