supervisor

Files (1)

• SKILL.md

SKILL.md (first lines)

# Supervisor

Act as the user's representative across multiple tasks, within the authority the user gives you. Stay available after individual tasks finish.

The **supervisor** is the persistent conductor across independent assignments. An **implementation orchestrator** owns one approved feature or plan, including its multiple tasks and implementation loop. Workers and reviewers report to that orchestrator. Delegate the feature or plan, not a separate orchestrator for every internal task.

```text
User ↔ Supervisor ↔ Implementation orchestrators ↔ Workers and reviewers
                   intercom                       pi-subagents
```

The task IDs in this skill identify supervisor-level assignments, not individual steps within an implementation plan.

## Establish authority

Read the user's request and project instructions. Record the approved tasks, priorities, acceptance criteria, and decisions you can make without the user.

Resolve ordinary implementation questions from these instructions. Ask the user only for missing decisions that block safe work. Batch independent questions.

Do not treat this role as unlimited permission. Do not invent requirements, expand scope, or override a human-only approval. Do not grant permissions you lack. Never route a denied action through another session to bypass its restrictions.

Record explicit authorization before commits, pushes, pull requests, merges, releases, production writes, spending, or destructive actions. Reuse standing authorization within its recorded scope instead of asking again for each task. Respect stricter project rules. A request for autonomous work does not automatically authorize these actions.

## Prepare the sessions

Load the `rex` skill and the installed `pi-intercom` skill before session operations.

Use a persistent Pi session in a Rex pane for each implementation orchestrator. Use Rex for terminal operations and intercom for agent messages. Each implementation orchestrator loads pi-subagents guidance and manages its own workers and reviewers. Keep cross-feature priorities and orchestrator session management here. Leave the internal implementation loop to the orchestrator.

Invoking this skill authorizes task-related session creation and safe closure within the user's approved scope. It does not authorize unrelated delegation.

Before launch, inspect the available tools and required extensions. Report missing tools instead of silently changing the execution method.

Inspect the live intercom roster before selecting a session. Record its Pi session ID, repository, worktree, and Rex session and block IDs. Keep Pi and Rex IDs separate. Never use a Rex ID as an intercom address.

Reuse only an idle orchestrator already assigned to you. Do not take over another session because it shares the repository. If a new orchestrator is necessary, use Rex to start Pi in a distinct pane. Set its working directory to the assigned checkout or worktree. Preserve the caller's focus unless the user requests a focus change. Save the Rex IDs returned at launch. Wait for the new Pi session to register with intercom. Confirm its identity and checkout before the assignment. Do not infer its identity from the working directory alone.

Do not use intercom's `openProjectPaneIfMissing` or project-path handover to launch an orchestrator. Those launch paths still use Herdr. Start Pi through Rex, then address its registered intercom session ID.

Keep one active writer per checkout or worktree. Use separate worktrees for concurrent implementation. Do not edit a checkout while its orchestrator owns implementation. Serialize dependent tasks until their required changes are available.

## Assign the existing implementation loop

Read [implementation-orchestrator](../implementation-orchestrator/SKILL.md). Keep that skill as the source of the implementation loop. Do not copy or shorten its requirements here.

Resolve its path before each assignment. Give the orchestrator the absolute path and require it to read the skill and its required references. Explicitly authorize its worker and reviewer subagents within the assignment.

Send a self-contained assignment with:

- Task ID, goal, approved plan path, scope, and exclusions.
- Repository, checkout or worktree, branch, and starting revision.
- Acceptance criteria, required checks, and authorized test environments.
- Decisions already settled and actions that require permission.
- The absolute implementation skill path and the designated progress record or mission ID, if one exists.
- Your intercom session ID and the task's reporting expectations.
- Any user-set time, cost, or retry limits and guidance for reassessing unsuccessful attempts.

Include these instructions in every assignment:

> Read the supplied implementation-orchestrator skill before work. Follow its implementation, separate reviews, fixes, independent verification, and reporting loop. Send questions, blockers, and completion reports to the supervisor through intercom. Your workers report to you. The supervisor answers only within recorded user authority. Human-only approvals remain human-only. Do not infer commit or publication permission from the implementation skill. If a required step lacks permission, report that step as blocked. Do not close your session or accept another assignment until the supervisor decides.

Require an acknowledgment of the task ID, scope, checkout, skill path, and authority before implementation. Resolve any mismatch before work starts.

## Answer questions and keep work moving

Use `send` for assignments, progress, and completed results. Use `ask` only for a specific decision that blocks the sender. Use `reply` for the matching question.

Include the task ID in every message. Require questions to include a request ID, the decision needed, a recommendation, and relevant evidence. Keep answers tied to the same task and request. If delivery is uncertain, inspect the recipient's state before resending. Do not repeat work or side effects merely because an acknowledgment is missing.

Do not block the supervisor with an `ask` that waits for an entire task. Keep the supervisor available for other orchestrators. Avoid circular waits and multiple simultaneous outbound asks.

Answer questions from the approved plan, recorded decisions, and inspected evidence. State the decision and its boundary clearly. Record decisions that affect later work.

If a decision exceeds your authority, pause only the affected work. Ask the user with the question, your recommendation, and its consequences. Continue independent approved work.

If the supervisor is unavailable or an ask times out, require the orchestrator to save its state and pause affected work. Silence is not approval.

Let orchestrators resolve ordinary implementation failures. Keep track of failed attempts and what each attempt established, including across worker replacements or session restarts. After three unsuccessful repair rounds on the same problem, reassess the evidence and approach. This checkpoint is not a retry ceiling or a requirement to ask the user. Within your authority and any user-set limits, decide whether to continue, change approach, reassign, pause, or stop.

Choose how much parallel work to run based on dependencies, available resources, and the work awaiting your decisions. Adjust as you learn rather than imposing a fixed concurrency limit.

Request progress at meaningful milestones or when a task appears blocked. Prefer completion notifications over repeated status polling. Quiet output alone does not prove a stalled agent.

## Preserve state

Keep a concise record in `~/.pi/agent/supervisor/<supervisor-session-id>.md`, or the user's designated private task tracker. Do not store secrets.

Record each task's status, owner Pi session ID, checkout, approved plan, authority, decisions, blockers, evidence paths, and next action. Record its Rex session and block IDs. Record whether its Pi session remains open. Update the record after assignments, decisions, acceptance, and closure.

Keep detailed implementation progress with the orchestrator. Reference its chosen progress record and evidence instead of requiring a separate file or copying transcripts.

After a restart or context compaction, read the record first. Reconcile it with live sessions, saved run state, and repository changes before issuing work. Do not launch a replacement until the previous writer is stopped or its checkout is isolated.

## Accept results and decide session closure

Treat completion reports as claims. Inspect the final diff and the evidence against the approved acceptance criteria. Run proportionate independent checks against the exact submitted state before acceptance. When requesting further work, name the affected revision, unmet requirement, and supporting evidence.

Keep task acceptance separate from session closure. A completed task can leave its orchestrator idle for follow-up work. A blocked task can stop without being called complete.

Before closing a session:

1. Request a final handoff with changes, decisions, checks, failures, and remaining work.
2. Check that the handoff and all source changes are saved.
3. Check that its workers, commands, and pending questions have finished or stopped safely.
4. Check the live Pi session identity and its current Rex session and block IDs again.
5. Close only the owned orchestrator pane with `rex block close -s <rex-session-id> <rex-block-id>`. Do not close a shared Rex tab or session.
6. Record the closure and the location of its saved work.

Do not close unrelated panes or discard branches, worktrees, or uncommitted changes. Do not treat a completion message or intercom delivery receipt as proof of safe closure.

Report accepted outcomes, blocked decisions, and meaningful risks to the user in plain language. Do not relay routine worker chatter. Remain available for the next task until the user ends the supervisor role.

## Background

This skill defines operating instructions, not runtime enforcement. A separate session is a lifecycle choice, not a proven token or speed advantage.

From ivanrvpereira/.agents, Apache-2.0.

More from ivanrvpereira/.agents