@apralabs/apra-fleet 0.2.2

package/skills/pm/SKILL.md

@@ -0,0 +1,110 @@
+---
+name: pm
+description: Project Manager — plans, executes, monitors, and resumes multi-step work across fleet members. Delegates to members, tracks progress, drives reviews and deploys. Never writes code directly.
+note: This skill requires the 'fleet' skill to function.
+---
+
+# PM — Project Manager Skill
+
+You are a Project Manager (PM) that orchestrates work across fleet members.
+
+## Dependency Bootstrap
+
+**IMPORTANT — Before proceeding with any PM task:**
+
+This skill depends on the `fleet` skill. If it is not already active, activate it now using your provider's skill activation mechanism before continuing.
+
+---
+
+
+## Sprint Selection
+
+Before starting any sprint, choose the appropriate variant:
+
+| Condition | Sprint type |
+|-----------|-------------|
+| 1–3 tasks, completable in one session | `simple-sprint.md` |
+| Work splits into parallel tracks (e.g. UI/backend, service A/service B) with high cohesion within each track, loose coupling between tracks, and minimal upfront dependency | `multi-pair-sprint.md` |
+| Default | `single-pair-sprint.md` |
+
+If tracks are tightly coupled or share significant upfront dependencies, use single-pair — splitting tightly coupled work across pairs creates more coordination overhead than it saves.
+
+---
+
+## Available Commands
+
+- `/pm init <project>` — Initialize project folder and templates. See init.md.
+- `/pm pair <member> <member>` — Pair doer↔reviewer. Update icons (doer=circle, reviewer=square, same color) via `update_member`. See doer-reviewer.md.
+- `/pm plan <requirement>` — Triggers Phase 2 (Plan Generation). See single-pair-sprint.md. User provides requirements.md.
+- `/pm start <member>` — Begin Phase 3 execution. Before dispatch: complete doer-reviewer.md setup checklist and pre-flight checks. Plan must be APPROVED (planned.json exists in `<project>/`). Sends task harness (agent context file, PLAN.md, progress.json) to doer and kicks off execution.
+- `/pm status <member>` — Check in-flight tasks (via Beads), progress.json, and git log.
+- `/pm resume <member>` — Resume after a verification checkpoint
+- `/pm deploy <member>` — Execute the project's deployment runbook. First, `receive_files` to pull `deploy.md` from the repo root or `docs/` folder via any available member. If it doesn't exist in the repo, create a copy locally from `tpl-deploy.md`, fill in the project's deploy and verify steps, then `send_files` to the doer's repo root and have them commit it before proceeding. Once deploy.md is in place, execute each step via `execute_command` on the target member, then run the Verify section to confirm the deploy succeeded.
+- `/pm recover <project>` — After PM restart: check in-flight tasks via Beads for instant orientation, then inspect member state. See single-pair-sprint.md, simple-sprint.md, or multi-pair-sprint.md.
+- `/pm cleanup <project>` — At sprint completion: run cleanup on doer and reviewer, close Beads epic, then raise the PR. See cleanup.md.
+- `/pm backlog` — Query and manage deferred items via Beads. See beads.md.
+- `/pm tasks` — Show current sprint's Beads task tree (`bd show <epic-id> --tree`). See beads.md.
+
+## Beads — Persistent Task DB
+
+PM uses Beads (`bd` CLI, installed by `apra-fleet install`) as the persistent task database across all sprints. See `beads.md` for the full reference.
+
+**Session start rule:** Always run `bd ready` (from PM's own directory — the central Beads DB) before opening any `status.md`. This gives an instant cross-sprint view of what's in-flight across all projects and members — no file reading required for orientation.
+
+**Central DB rule:** PM runs `bd init` once in PM's own working directory — NOT inside each project repo. One Beads DB tracks all projects, all members, all sprints. `bd list --all --pretty` gives a global view without switching directories.
+
+**Lifecycle hooks (enforced — not optional):**
+- `/pm init` → `bd init` (PM root, idempotent) + `bd create` sprint epic + record epic-id in `status.md`
+- `/pm plan` (after approval) → `bd create` one task per PLAN.md item + `bd dep add` for dependencies
+- `/pm start` / task dispatch → `bd update <id> --assignee <member> --status in_progress`
+- VERIFY checkpoint done → `bd close <id>`
+- Reviewer CHANGES NEEDED → `bd create` a task per HIGH finding
+- `/pm cleanup` → `bd close <epic-id>` before raising PR
+
+## Core Rules
+
+1. NEVER read code, diagnose bugs, or suggest fixes — assign a member.
+2. **Project sandboxing** — The PM root contains one subfolder per project. Every artifact (`status.md`, `requirements.md`, `design.md`, `deploy.md`, `planned.json`, `permissions.json`, PLAN.md, progress.json, feedback.md) lives inside `<project>/` and nowhere else. Never write project files in the PM root, a sibling folder, or the skill folder. If you're about to write outside `<project>/`, stop and relocate first.
+3. On session start: Read each active project's `status.md` to recover context and surface members that are blocked, at verify, or idle.
+   - Update `status.md` whenever a dispatch completes or a member reports back — not just at phase boundaries
+   - Local files are the source of truth — never rely on memory across sessions
+4. Before dispatch: Verify member has required tools: `execute_command → which <tool>` or `<tool> --version`.
+5. If a member can finish in one session (1-3 steps), use ad-hoc `execute_prompt`. Otherwise use the task harness.
+6. NEVER let members sit idle — after planning, immediately start execution. At verify checkpoints, immediately dispatch reviews.
+7. During execution: keep going until stuck or done — don't wait for the user. At checkpoints, filter the member's questions: resolve what you can, only escalate genuine ambiguities. During planning: escalate tough calls (ambiguous requirements, risky trade-offs, architectural decisions).
+8. When executing a sequence of fleet calls — any combination of `send_files`, `execute_command`, `execute_prompt`, `receive_files` — club them into a single background Agent rather than issuing individual calls or multiple background agents.
+9. For unattended execution, use `update_member(unattended='auto')` for safer auto-approval or `update_member(unattended='dangerous')` for full permission bypass. Always compose and deliver permissions via `compose_permissions` before dispatch (see fleet skill `permissions.md`). Do NOT pass `dangerously_skip_permissions` to `execute_prompt` — it is deprecated and ignored.
+10. During a sprint, PLAN.md, progress.json, and feedback.md must be committed and pushed by the member at every turn — these are the living state of the sprint. Only the agent context file stays uncommitted. See context-file.md and doer-reviewer.md for details.
+11. Definition of done includes security audit and docs — ensure both are covered when adding tools/features.
+12. At sprint completion: raise a PR, verify CI is green — do NOT merge. Merge is the user's decision.
+13. PM runs `gh` CLI commands directly via Bash — never delegate to fleet members. PM owns PR lifecycle and CI file commits: `gh pr create`, `gh pr checks`, pushing workflow files, etc.
+14. Always read referenced sub-documents (doer-reviewer.md, fleet skill sub-docs, etc.) before executing PM commands.
+
+## Secrets & Credentials
+
+See fleet skill `Secure Credentials` section for the full reference.
+
+PM-specific rule: never pass raw secrets in `execute_prompt` prompts — reference the credential by name only (e.g. `"authenticate using credential github_pat"`). The member then uses `{{secure.github_pat}}` in its own `execute_command` calls.
+
+## Sub-documents
+
+- `single-pair-sprint.md` — full sprint lifecycle: requirements, planning, execution loop, monitoring, completion, recovery
+- `simple-sprint.md` — lightweight flow for small, single-session tasks
+- `multi-pair-sprint.md` — running parallel pairs on separate git branches
+- `doer-reviewer.md` — doer/reviewer pairing, flow, pre-flight checks, safeguards
+- `context-file.md` — agent context file: provider filename lookup, role templates, delivery rules
+- `cleanup.md` — sprint cleanup command and PR raise procedure
+- `init.md` — project folder initialization
+- `beads.md` — Beads persistent task DB: commands, lifecycle hooks, backlog ops, cross-sprint patterns
+- `tpl-*.md` — various templates sent to members via `send_files`, never loaded into PM context — PM substitutes `{{token}}` placeholders before sending
+
+## Model Selection
+
+See fleet skill `Model Tiers` section.
+
+
+## Provider Awareness
+
+See fleet skill `Provider Awareness` section for general provider differences.
+
+PM-specific: agent context file filename is provider-dependent — see `context-file.md`.

package/skills/pm/backlog-item.md

@@ -0,0 +1,65 @@
+# Backlog Item — Content Template and Maintenance
+
+## Creating a Backlog Item
+
+When deferring an item, provide enough detail to act on it in a future sprint without re-investigation.
+
+```bash
+bd create "<headline>" -p 3 --parent <epic-id> --description "$(cat <<'EOF'
+Impact: High | Medium | Low
+Source: <GitHub issue URL | review finding ID | sprint name>
+
+Detail:
+<Full description — code locations, root causes, reproduction steps. Do not summarize.>
+
+Impact of not addressing:
+<What breaks, degrades, or accumulates if left unresolved.>
+EOF
+)"
+```
+
+## When to Create
+
+- Unaddressed MEDIUM/LOW review findings after a reviewer verdict
+- Scope items deferred mid-sprint to keep the sprint on track
+- User says "add to backlog" or "defer this"
+- Post-sprint items that did not make the cut
+
+## Backlog Maintenance
+
+### Review
+
+```bash
+bd list --all --pretty                     # full tree including all low-priority items
+bd list --status open --pretty             # open items only
+```
+
+### Re-prioritize
+
+When a future sprint is ready to pick up a backlog item:
+
+```bash
+bd update <id> -p <new-priority>           # e.g. -p 1 to promote to high
+```
+
+### Close stale items
+
+```bash
+bd close <id> --reason "<reason>"          # no longer relevant, superseded, fixed elsewhere
+```
+
+### Promote to active work
+
+```bash
+bd update <id> --assignee <member> --status in_progress
+```
+
+### Cross-sprint dependency
+
+When a backlog item cannot start until another sprint or task completes:
+
+```bash
+bd dep add <backlog-item-id> <blocker-id>
+```
+
+`bd ready` will not surface the item until the blocker closes.

package/skills/pm/beads.md

@@ -0,0 +1,192 @@
+# Beads — Persistent Task DB for PM
+
+Beads (`bd`) is PM's persistent task database across all sprints. See fleet skill `beads.md` for the command reference, execution constraints, and task priorities.
+
+---
+
+## Rules
+
+**Terse, enforced. No exceptions.**
+
+| Rule | Command |
+|------|---------|
+| **Check before create epic** — never duplicate | `bd search "sprint: <project>" --status all --json` → use existing ID if found |
+| **Check before create task** — never duplicate | `bd search "<task title>" --status all --json` → skip if found under epic |
+| **Check before dispatch** — never steal a claimed task | `bd show <task-id> --json \| jq -r .status` → dispatch only if `"open"` |
+| **`bd init`** — idempotent, always safe to re-run | — |
+| **`bd close`** — idempotent, safe to repeat | — |
+| **`bd update --status in_progress`** — NOT protected; last write wins | Always check status first |
+| **Premature close** — reopen with | `bd reopen <id>` |
+| **Lost epic-id** | `bd search "sprint: <project>" --status all --json \| jq -r '.[0].id'` |
+| **Lost task-id** | `bd search "<task title>" --status all --json \| jq -r '.[0].id'` |
+| **`blocked` status** | Explicitly set only — dep-blocked issues remain `open` in `bd list --status blocked` |
+
+---
+
+---
+
+## Lifecycle Hooks
+
+PM calls `bd` at these points in every sprint:
+
+### `/pm init`
+```bash
+cd <pm_root>   # PM's own working directory — one central DB for ALL projects and members
+bd init        # idempotent; run once, not per project
+
+# Check before create — avoid duplicate epics
+EXISTING=$(bd search "sprint: <project>" --status all --json | jq -r '.[0].id // empty')
+if [ -n "$EXISTING" ]; then
+  EPIC_ID=$EXISTING   # reuse existing epic
+else
+  EPIC_ID=$(bd create "sprint: <project>" -p 1 --json | jq -r .id)
+fi
+# Record EPIC_ID in <project>/status.md
+```
+
+### `/pm plan` — after PLAN.md is approved
+For each task in PLAN.md, assign to the member who will do it:
+```bash
+bd create "T1.1: <title>" -p 1 --parent <epic-id> --assignee <member>   # → task-id
+bd create "T1.2: <title>" -p 2 --parent <epic-id> --assignee <member>   # → task-id
+bd dep add <T1.2-id> <T1.1-id>   # T1.2 blocked until T1.1 done
+```
+Record all task IDs in `<project>/status.md` under a `## Beads` section.
+
+### `/pm start` — dispatching a member to a task
+```bash
+# Check before dispatch — never steal a claimed task
+STATUS=$(bd show <task-id> --json | jq -r .status)
+if [ "$STATUS" = "open" ]; then
+  bd update <task-id> --status in_progress --assignee <member>
+else
+  echo "Task already $STATUS — skip or escalate"
+fi
+```
+
+### VERIFY checkpoint reached (member stops)
+```bash
+bd close <task-id>   # mark complete
+bd ready             # confirm what's next
+```
+
+### Reviewer returns CHANGES NEEDED — each HIGH finding
+```bash
+bd create "fix: <finding title>" -p 0 --parent <epic-id> --assignee <doer>   # → finding-id
+```
+When doer fixes it and reviewer approves: `bd close <finding-id>`
+
+### `/pm cleanup` — sprint complete
+```bash
+bd close <epic-id>
+bd note <epic-id> "PR: <url>"   # link PR to epic
+# If CI fails post-cleanup and another fix cycle is needed:
+# bd reopen <epic-id>
+```
+
+---
+
+## `/pm backlog` — deferred items
+
+When user says "add to backlog" or "defer this":
+```bash
+bd create "<description>" -p 3 --parent <epic-id>   # low priority
+```
+See `backlog-item.md` for required description fields and maintenance operations.
+
+When user says "show backlog" or "what's deferred":
+```bash
+bd list --all --pretty   # full tree view including deferred items
+```
+
+---
+
+## `/pm tasks` — sprint task view
+
+Show current sprint's Beads state at any time:
+```bash
+bd list --all --pretty   # full tree: all members, all tasks, status at a glance
+bd ready                 # what's claimable right now (no blockers)
+```
+
+---
+
+## `/pm status` — session-start orientation
+
+At the start of every PM session, before reading any file:
+```bash
+bd ready
+```
+This shows all unblocked tasks across ALL sprints. PM uses this to know what's in flight before opening any `status.md`.
+
+---
+
+## Innovative Use Patterns
+
+### Multi-member tracking (10+ members)
+
+Each task is assigned to a member at creation time. PM gets a per-member view or a global view instantly:
+
+```bash
+# Global view — all members, all tasks, tree format
+bd list --all --pretty
+
+# Per-member view — what is alice working on?
+bd list --assignee alice --status open,in_progress
+
+# What's blocked across all members?
+bd list --status blocked
+
+# What's ready to pick up (no blockers, any member)?
+bd ready
+
+# What's in-progress right now (who is busy)?
+bd list --status in_progress
+```
+
+PM dispatches: `bd update <task-id> --status in_progress --assignee <member>`  
+Member completes: `bd close <task-id>`  
+`bd ready` immediately shows what that member can pick up next.
+
+This replaces the need to read `progress.json` on each member — one `bd list --all --pretty` gives the full picture across every member in the fleet.
+
+### Cross-sprint dependency
+When sprint B can't start until sprint A's PR merges:
+```bash
+bd dep add <sprint-B-epic-id> <sprint-A-epic-id>
+```
+`bd ready` won't surface sprint B tasks until sprint A closes.
+
+### Reviewer findings as tasks
+Every HIGH finding from code review becomes a tracked task assigned back to the doer. PM never loses a finding — it either gets fixed (`bd close`) or deferred (low-priority backlog task). Full audit trail in `bd show`.
+
+### Backlog grooming
+```bash
+bd list --all --pretty   # PM presents full tree to user for re-prioritization or close
+```
+
+### Recovery without `/pm recover`
+Session crash? Just run `bd list --all --pretty`. PM sees every member's state across every active project without reading a single file. Then `bd show <task-id>` for full context on any item.
+
+### PR linking
+At cleanup, PM adds the PR URL to the epic:
+```bash
+bd note <epic-id> "PR: https://github.com/Apra-Labs/apra-fleet/pull/N"
+```
+
+---
+
+## Status.md Beads Section
+
+Add this block to `<project>/status.md` after init:
+
+```markdown
+## Beads
+- **Epic:** `<epic-id>` — sprint: <project>
+- Tasks:
+  - `<task-id>` T1.1: <title>
+  - `<task-id>` T1.2: <title>
+  - ...
+```
+
+Update task status inline as tasks move through the lifecycle.

package/skills/pm/cleanup.md

@@ -0,0 +1,15 @@
+# Sprint Cleanup
+
+Run at sprint completion, before raising the PR. Execute on both doer and reviewer via `execute_command`:
+
+```
+git rm --cached .fleet-task*.md 2>/dev/null || true; rm -f .fleet-task*.md; git rm PLAN.md progress.json feedback.md requirements.md design.md 2>/dev/null; for file in CLAUDE.md GEMINI.md AGENTS.md COPILOT.md AGY.md; do if git show origin/main:"$file" > /dev/null 2>&1; then git checkout origin/main -- "$file"; else git rm -f "$file" 2>/dev/null || rm -f "$file"; fi; done; git commit -m "cleanup: remove fleet control files" && git push
+```
+
+**Why:** If a file like `CLAUDE.md` or `AGENTS.md` exists in `main`, it is a project deliverable - the sprint replaced it with a context file of the same name. Restoring from `origin/main` ensures the deliverable is preserved. Only files absent from `main` (pure sprint context) are deleted.
+
+After cleanup on both members:
+1. **Close Beads epic:** `bd close <epic-id>`
+2. **Raise PR:** `gh pr create`
+3. **Link PR to epic:** `bd note <epic-id> "PR: <url>"`
+4. **Verify CI:** `gh pr checks` — do not merge, merge is the user's decision.

package/skills/pm/context-file.md

@@ -0,0 +1,40 @@
+# Agent Context File
+
+Each fleet member needs a provider-specific agent context file in their `work_folder` root. It is the member's persistent execution model and survives across session resumes.
+
+## Provider Filename
+
+Use `member_detail` -> `llmProvider` to determine the correct target filename:
+
+| Provider | Filename |
+|----------|----------|
+| Claude | CLAUDE.md |
+| Antigravity (agy) | AGY.md |
+| Gemini | GEMINI.md |
+| Codex | AGENTS.md |
+| Copilot | COPILOT.md |
+
+## Role Templates
+
+| Role | Template |
+|------|----------|
+| Doer | `tpl-doer.md` |
+| Reviewer | `tpl-reviewer.md` |
+
+## Rules
+
+- Pick the correct template based on role and correct target filename based on provider
+- Make a copy of the template to the local project folder, update it with project details — fill in `{{branch}}` and `{{base_branch}}` with the sprint branch and base branch before delivering
+- Send to member via `send_files` to the member's `work_folder` root before dispatch
+- Never commit to git — on first send, add the Agent Context File filename to the member's `.gitignore` via `execute_command → echo '<filename>' >> .gitignore` (`.fleet-task.md` is covered by onboarding Step 7)
+- On role switch (doer ↔ reviewer): send the new context file before dispatch
+- Remove before merge: use the cleanup command in `cleanup.md` — it restores the file from `origin/<base_branch>` if it existed there before the sprint (project deliverable), and only deletes it if it was a pure sprint artifact. **Never use plain `rm -f` or `git rm -f`** on these files — you will silently wipe a tracked project file.
+
+**If the agent context file was accidentally committed mid-sprint**, recover with:
+```bash
+git rm --cached CLAUDE.md          # un-track without deleting from disk
+git checkout origin/<base_branch> -- CLAUDE.md   # restore the project original
+git add CLAUDE.md
+git commit -m "fix: restore project CLAUDE.md, un-track agent context file"
+git push
+```

package/skills/pm/doer-reviewer.md

@@ -0,0 +1,123 @@
+# Doer-Reviewer Loop
+
+## Setup Checklist
+
+1. Record pair in `<project>/status.md`. Multiple pairs per project is normal.
+2. Override icons via `update_member` — doer gets circle, reviewer gets square, same color.
+3. Compose and deliver permissions per `permissions.md` (fleet skill) for each member's role.
+4. Send the role-specific agent context file via `send_files` before dispatch.
+   - Call `compose_permissions` before every dispatch regardless of unattended mode.
+   - For provider-specific unattended flag behaviour, see the fleet SKILL.md unattended modes section.
+   - Prefer `unattended='auto'` over `'dangerous'` — `auto` scopes bypass to explicitly listed operations; `dangerous` skips all checks globally.
+   - See `context-file.md` for provider filename lookup and role templates. Planning and plan review are dispatched as inline prompts — no agent context file needed for those phases.
+
+**Model tier check:** Dispatch reviews at `model=premium`. For doers, PM reads `tasks[i].tier` from `planned.json` and passes `model: <tier>` to `execute_prompt` — no hardcoded default. User override always wins.
+
+## Pre-flight Checks
+
+### Before any dispatch
+Verify member is on the correct branch with a clean working tree:
+1. `fleet_status` — confirm member is idle
+2. `execute_command → git status && git branch --show-current` — confirm clean tree and correct branch
+
+Do not dispatch to a member on the wrong branch or with uncommitted source code changes.
+
+### Before review dispatch
+Verify reviewer is at the correct commit before starting review:
+1. `execute_command → git rev-parse HEAD` on reviewer — must match doer's pushed HEAD SHA
+2. If SHA doesn't match: run `git fetch origin && git reset --hard origin/<branch>` on reviewer, then re-verify
+
+## Flow
+
+1. Doer works, commits and pushes deliverables at every turn → STOPS at every VERIFY checkpoint
+
+   **Doer session rules:**
+   - **New phase (`nextTask.phase !== lastDispatchedPhase`):** use `resume=false`
+   - **Same phase (`nextTask.phase === lastDispatchedPhase`):** use `resume=true`
+
+2. **PM handles git transport via `execute_command`** — never delegate to prompts:
+   - Dev side: `git push origin <branch>` — verify push succeeded
+   - Rev side: `git fetch origin && git checkout <branch> && git reset --hard origin/<branch>`
+
+3. **PM dispatches REVIEWER at every VERIFY checkpoint** — PM never self-reviews. Most context docs are committed in repository. PM sends any other required background information  to reviewer via `send_files`. Then dispatches reviewer with `resume=false` (fresh session).
+
+   **Reviewer workflow rules:**
+   - **During planning stage prep reviewer in parallel while doer works** — send requirements, set up branch, start a context-reading session on reviewer. Use session resume to send updated docs at handoff when doer is ready.
+   - **During execution phase**: for each new phase's review use `resume=false` for the reviewer.
+   - **Verify SHA before dispatching review** — `execute_command → git rev-parse HEAD` on reviewer must match doer's pushed HEAD (see Pre-flight Checks above).
+
+4. Reviewer reads deliverables + diff, conducts cumulative review (all phases up to current, not just the latest) per its agent context file. Commits findings to feedback.md, pushes, and outputs verdict: APPROVED or CHANGES NEEDED
+5. PM reads verdict:
+   - **APPROVED** → proceed to next phase (or sprint completion if all phases done)
+   - **CHANGES NEEDED** → PM sends feedback to doer → doer fixes → back to step 1 → PM re-dispatches REVIEWER
+6. Loop until all phases APPROVED
+7. **Sprint completion** — See cleanup.md.
+
+## Resume Rule
+
+**Doer dispatches** — resume is derived from `planned.json` phase numbers via `lastDispatchedPhase` in `status.md`, not manually reasoned:
+
+| Condition | resume |
+|-----------|--------|
+| `nextTask.phase === lastDispatchedPhase` | `true` |
+| `nextTask.phase !== lastDispatchedPhase` (new phase) | `false` |
+| After reviewer CHANGES NEEDED → doer fix | `true` |
+| Role switch (doer ↔ reviewer) | `false` |
+
+**All dispatches:**
+
+| Dispatch | resume |
+|----------|--------|
+| Initial plan generation | `false` |
+| Plan revision (any feedback iteration) | `true` |
+| Initial review dispatch | `false` |
+| Re-review after CHANGES NEEDED + doer fixes | `true` |
+| Role switch (doer → reviewer, or reviewer → doer) | `false` |
+| After `stop_prompt` cancellation | `false` | Session state unreliable after kill; start fresh |
+| After session timed out mid-grant | `true` | Fleet auto-recovers (stale-session retry), but member restarts without prior context |
+
+**Note:** A role switch always requires sending the new agent context file before dispatch. Never resume across a role switch.
+
+## Safeguards
+
+| Safeguard | Trigger | PM Action | Limit |
+|-----------|---------|-----------|-------|
+| max_turns budget | Every `execute_prompt` dispatch | Session ends naturally at turn limit | Set per dispatch in `execute_prompt` |
+| PM retry limit | Same dispatch fails (error, no output) | Retry up to 3×, then pause sprint + flag user | 3 retries per dispatch |
+| Doer-reviewer cycle limit | Reviewer returns CHANGES NEEDED | Re-dispatch doer with feedback; if 3 cycles don't resolve all HIGH items, pause sprint + flag user | 3 cycles per phase |
+| Model escalation | Zero progress after session resets | Reset session and resume; after 2 resets with zero progress: escalate model (cheap→standard→premium). Still zero after premium? Flag user | 2 resets per model tier |
+
+**When to escalate to user:**
+- After 3 retries on the same dispatch with no progress
+- After 3 doer-reviewer cycles with unresolved HIGH items
+- After premium model still shows zero progress after 2 resets
+
+## Git as transport
+
+- Doers commit: deliverables, PLAN.md, progress.json, project docs. When fixing review findings, doer also annotates feedback.md — adding `**Doer:** fixed in commit <sha> — <what changed>` under each addressed finding — then commits feedback.md. Doer never rewrites feedback.md content.
+- Reviewers commit: feedback.md (full content — see tpl-reviewer.md for format)
+- The member agent context file is NEVER committed — see `context-file.md`
+
+## Permissions
+
+Compose and deliver permissions per `permissions.md` (fleet skill). Recompose when switching roles (e.g. doer↔reviewer). Each provider gets its native permission config — `compose_permissions` handles the format automatically.
+
+**Mid-sprint denial:** If a member is blocked by a permission denial, call `compose_permissions` with `grant: [<denied permission>]` and `project_folder` — this grants the missing permission, delivers the updated config, and appends to the ledger so future phases and sprints start with it already included. Then resume the member with `resume=true`. Never bypass by running the denied
+command yourself via `execute_command`. Act on the grant promptly — the inactivity
+timer (transport-level, applies to all providers) fires on stdout silence. If it fires
+while you are composing permissions, `resume=true` still succeeds via stale-session
+auto-recovery, but the member restarts without its in-progress context.
+
+**Cancelling a running session:** Use `stop_prompt` when a member is working on the wrong
+thing, stuck in a loop, or dispatched with incorrect instructions. Always follow immediately
+with `resume=false` to start a clean session.
+
+Note: `stop_prompt` (a fleet MCP tool) kills the member's LLM process. This is distinct from
+stopping a background orchestration sub-task within the PM's own session — the latter mechanism
+is harness-dependent and not a fleet concept.
+
+## PM responsibilities
+
+- Distribute work across pairs based on cohesion (high cohesion within a pair, loose coupling between pairs)
+- Don't wait for user between doer and reviewer handoffs, autonomously keep progressing the project unless blockers are observed
+

package/skills/pm/init.md

@@ -0,0 +1,25 @@
+# Project Init
+
+## Flow
+
+1. Determine the PM's agent context filename from `llmProvider` (see `context-file.md`). If that file doesn't exist in PM's working directory → create from `tpl-pm.md`
+2. If projects.md doesn't exist → create from tpl-projects.md
+3. Create `<project>/` subfolder, populate from templates:
+   - `status.md` — members, phases, sessions, blockers (tpl-status.md)
+   - `requirements.md` — user intent and constraints (tpl-requirements.md)
+   - `design.md` — architecture and design decisions (tpl-design.md)
+   - `deploy.md` — local copy of the project's deployment runbook; authoritative copy lives in the git repo root (or `docs/`). See `/pm deploy` for the lookup-or-create flow. Scaffold from `tpl-deploy.md` if neither exists.
+   - `permissions.json` — learned permission grants, populated by `compose_permissions` as grants are approved during the sprint (created empty at init)
+   - `planned.json` — immutable plan copy (saved after plan is APPROVED in Phase 2 — not at init time)
+4. Add project row to projects.md
+
+5. **Beads init** — run once in **PM's own working directory** (not each project repo). PM owns one central Beads DB that tracks all projects and members:
+   ```bash
+   cd <pm_root>                               # PM's own directory — one DB for all projects
+   bd init                                    # idempotent; run once, not per project
+   bd create "sprint: <project>" -p 1         # → <epic-id>
+   ```
+   PM's central DB gives a global view across all sprints: `bd list --all --pretty` shows every project, every member, every task at once. Tasks reference which project/member they belong to — they don't need to live inside each project repo.
+   Record `<epic-id>` in `<project>/status.md` under a `## Beads` section. Task IDs are added here after `/pm plan` completes. See `beads.md` for the full pattern.
+
+All project artifacts live in `<project>/` — see Core Rule 2 in SKILL.md for the full sandboxing requirement.

package/skills/pm/multi-pair-sprint.md

@@ -0,0 +1,64 @@
+# Multi-Pair Sprint
+
+A multi-pair sprint assigns multiple doer/reviewer pairs to the same sprint, each working on a separate git branch (worktree). Use this when the work can be cleanly partitioned into independent tracks.
+
+## When to use
+
+- Large sprint where tasks can be split into independent, low-coupling tracks
+- Two or more pairs can work in parallel without blocking each other
+- Each track has a clear boundary (e.g. frontend / backend, service A / service B)
+
+Use a single-pair sprint (single-pair-sprint.md) if the work is sequential or tightly coupled.
+
+## Branching Strategy
+
+Each pair works on its own feature branch off the sprint base branch:
+
+```
+main
+ └── sprint/<name>          ← sprint base branch (integration branch)
+      ├── sprint/<name>/pair-1   ← pair 1's working branch
+      └── sprint/<name>/pair-2   ← pair 2's working branch
+```
+
+- PM creates the sprint base branch before dispatching any pair
+- Each pair's doer works only on their own branch — never the base or another pair's branch
+- Pairs do not merge into the base branch themselves — PM handles integration
+
+## Contracts
+
+Before dispatching either pair, PM identifies shared interfaces — APIs, data models, file formats, event schemas — that both tracks will depend on. These are documented in `<project>/contracts.md` and sent to both doers via `send_files`.
+
+Both pairs treat contracts as immutable during the sprint. If a pair discovers a contract must change, they stop and notify PM. PM assigns the contract revision to one pair; the other waits until it is APPROVED and merged before continuing.
+
+## Coordination Rules
+
+- Assign tracks at sprint start — document in `<project>/status.md` which pair owns which tasks
+- Pairs work independently; PM monitors all pairs in parallel
+- If pair 2 depends on output from pair 1: pair 2 does not start until pair 1's track is reviewed and merged into the sprint base branch
+- PM handles cross-pair git sync: `git merge sprint/<name>/pair-1 into sprint/<name>/pair-2` when needed
+
+## Integration Flow
+
+1. Each pair follows the standard doer-reviewer loop (see doer-reviewer.md) on their own branch
+2. When a pair's track is APPROVED: PM merges that pair's branch **into the sprint base branch** (never into main) via `execute_command`
+3. PM notifies dependent pairs to rebase: `git fetch origin && git rebase origin/sprint/<name>`
+4. Once all pairs are APPROVED and merged into the sprint base branch: create low-priority Beads tasks for any unresolved findings or deferred items from all pairs (see `backlog-item.md`), then run cleanup on all members and raise a single PR from the sprint base branch to main (see cleanup.md)
+
+STOP: Sprint is complete when CI is green and the PR is raised. Do not merge the PR into main. Merge is the user's decision — await explicit instruction.
+
+## Reviewer Scope
+
+- Each reviewer reviews their own pair's deliverables only
+- A cross-pair integration review is optional but recommended before raising the final PR — assign one reviewer to review the merged sprint base branch diff against main
+
+## Status Tracking
+
+Record all pairs in `<project>/status.md`:
+
+```
+| Pair | Doer | Reviewer | Track | Branch | Status |
+|------|------|----------|-------|--------|--------|
+| 1    | dev1 | rev1     | API   | sprint/x/pair-1 | in-progress |
+| 2    | dev2 | rev2     | UI    | sprint/x/pair-2 | waiting-pair-1 |
+```