@apralabs/apra-fleet 0.2.2

package/skills/pm/plan-prompt.md

@@ -0,0 +1,94 @@
+# Plan Generation Prompt
+
+Send this to the member (via `execute_prompt`) before writing any plan:
+
+---
+
+You are generating an implementation plan. Read requirements.md for what needs to be built.
+
+### PHASE 0 — EXPLORE (before writing any plan)
+
+1. Read relevant source files for this task
+2. Read existing tests — understand conventions and framework
+3. `git log --oneline -20` — recent changes in the area
+4. List assumptions about how the code works
+5. For every assumption you listed, answer: "How do I know this is currently true?" Then verify it.
+   Two categories to check:
+   - **Existence:** Does the thing you are building on top of actually exist right now? (e.g. a named entity, interface, resource, capability, configuration, or path your plan depends on)
+   - **Accessibility:** Can the part of the system that needs it actually reach it? (e.g. is it exposed, connected, permitted, or in scope for the component that will use it)
+   If you cannot verify an assumption, it becomes a risk register entry, not a task precondition.
+6. Report: what you found, what patterns exist, what constraints matter
+
+### PHASE 1 — DRAFT
+
+For each task include:
+- What file(s) to create or change
+- What the change does — specific, not vague ("add X method to Y class" not "implement feature")
+- What "done" means — test passes, output appears, API returns expected response
+- What could block — missing dependency, unclear API, native code issue
+
+Rules:
+- **Phase boundaries by cohesion, not count** — a phase is a coherent unit of work that produces a reviewable, testable increment. Group tasks into a phase when they share a data model, code path, or design decision — splitting them would produce an incoherent intermediate state or require touching the same code twice. Place a VERIFY at the natural completion boundary of that unit, not at an arbitrary task count. Phases may have 4-5 tasks (a coherent subsystem) or just 1-2 (a genuinely isolated change).
+- Each task completable in one session, results in one commit
+- Tasks ordered so dependencies are satisfied
+- **Model tier assignment:** Assign a tier (`cheap`, `standard`, or `premium`) to every work task based on complexity:
+  - `cheap` — mechanical changes with no ambiguity (rename, move, simple config edit)
+  - `standard` — typical implementation work (new function, test suite, moderate refactor)
+  - `premium` — high-ambiguity design tasks, architectural decisions, or tasks requiring deep multi-file reasoning
+  - Write the tier into the task entry in PLAN.md (e.g. `- **Tier:** standard`)
+  - When the PM creates progress.json from the plan, it copies each task's tier into `tasks[i].tier`
+  - During dispatch, the PM reads `tasks[i].tier` and passes `model: <tier>` to `execute_prompt` for doer dispatches
+  - **Constraint:** Reviewer dispatches always use `model: premium` regardless of the task tier — this is not configurable by the planner
+- **The plan is the elaboration, not the summary:** requirements.md uses terse human language with intentional ambiguity. PLAN.md must resolve that ambiguity — every edge case decided, every behaviour specified, every acceptance criterion precise enough that two developers would implement the same thing. Referencing requirements.md for background is fine; deferring a decision to it is not.
+- **Monotonically non-decreasing tiers within a phase:** Within a phase, order tasks cheap → standard → premium. The PM resumes the same session across tasks in a phase — a premium task can build a large context that a cheap model cannot load. The PM may group consecutive same-tier tasks into a single dispatch streak; tier transitions trigger a new dispatch. If a dependency forces a higher-tier task before a lower-tier task within a phase, split the phase at that boundary. Cross-phase tier order does not matter — each phase starts a fresh session.
+  ```
+  cheap → cheap → standard → standard → premium → VERIFY  [VALID]
+  cheap → standard → cheap → VERIFY  [INVALID]  (downgrade within phase — split into two phases)
+re  ```
+
+### PHASE 2 — FRONT-LOAD FOUNDATIONS
+
+Two things go first:
+1. Key abstractions and shared interfaces — later tasks build on these. If the foundation is wrong, everything above it is wasted.
+2. Riskiest assumption — the thing that, if it doesn't work, invalidates everything else.
+
+Later tasks MUST follow DRY — reuse the abstractions from early tasks, never reinvent. If two tasks duplicate logic, the plan is sliced wrong.
+
+Examples: "Does the native addon run a pipeline?" — Task 1, not Task 15. "Define the shared auth interface" — Task 1, not scattered across 5 tasks.
+
+### PHASE 3 — SELF-CRITIQUE
+
+Golden rule: high cohesion within each task, low coupling between tasks. If a task needs the whole project to make sense, it's sliced wrong.
+
+Check your draft against these failure modes:
+- Low cohesion — does this task touch unrelated areas? Split by component boundary.
+- High coupling — does task N depend heavily on task M's internals? Decouple via interfaces.
+- Vague task — could two developers interpret this differently?
+- Too large — more than ~50 tool calls? Split it.
+- Hidden dependency — does task N assume something from task M that isn't explicit?
+- Late verification — 5+ tasks before checking if the approach works?
+- Wrong ordering — could the riskiest assumption be validated earlier?
+- Missing "done" criteria — how does the member know the task is complete?
+- Phase boundary at wrong place — does this phase mix unrelated subsystems that could be reviewed independently? Or does it split a cohesive unit across two phases?
+- Untracked work — re-read every task description, note, and comment in your draft. Does any sentence say "X will also need to change", "X must be updated", or "X is a prerequisite"? If yes and there is no task that does that work, either add the task or explicitly state it is out of scope.
+- Missing blocker — does this task depend on anything that another task produces or puts in place? If yes, that task must be listed in Blockers, even if the phase order implies it.
+- Tier downgrade within a phase — does any task have a lower tier than the task before it in the same phase? If yes, either reorder (if dependencies allow) or split the phase at the downgrade point. Cross-phase tier order does not matter — each phase starts with a fresh session.
+
+### PHASE 4 — REFINE
+
+Rewrite incorporating critique:
+- Move risky/uncertain tasks earlier
+- Split vague tasks into specific ones
+- VERIFY checkpoint at the natural completion boundary of each cohesive phase
+- Every task has clear "done" criteria
+
+### PHASE 5 — BRANCH & COMMIT
+
+1. Read requirements.md for the base branch (default: `main`)
+2. `git fetch origin && git checkout -b <feature-branch> origin/<base-branch>`
+3. Commit the plan files to the feature branch — NEVER commit to the base branch
+4. `git push -u origin <feature-branch>`
+
+Output the final plan in tpl-plan.md format.
+
+---

package/skills/pm/simple-sprint.md

@@ -0,0 +1,42 @@
+# Simple Sprint
+
+A simple sprint is a short, focused task that a single member can complete in one or a few sessions. Use this when the work is small enough that a full task harness (PLAN.md, progress.json) is unnecessary overhead.
+
+## When to use
+
+- 1–3 tasks, completable in a single session
+- No complex phasing or cross-phase dependencies
+- Low risk, well-understood scope
+
+Use the full sprint lifecycle (single-pair-sprint.md) for anything larger.
+
+## Flow
+
+**Branch naming:** choose a name that makes the purpose immediately clear — `feat/<description>`, `bug_fix/<short_description>`, `chore/<description>`, etc. PM records this as `{{branch}}` in the agent context file before dispatch.
+
+1. Write `<project>/requirements.md` — keep it concise but complete
+2. Dispatch doer via ad-hoc `execute_prompt` — include requirements inline or reference the file
+3. Doer completes work, commits, and pushes
+4. PM dispatches reviewer (fresh session, `resume=false`) — send requirements + diff context
+5. Reviewer outputs verdict: APPROVED or CHANGES NEEDED
+6. On APPROVED: create low-priority Beads tasks for any unresolved findings or deferred items (see `backlog-item.md`), then cleanup and raise PR (see cleanup.md). STOP: Do not merge — surface the PR URL and CI status to the user and await explicit instruction.
+7. On CHANGES NEEDED: send feedback to doer, re-dispatch, repeat from step 3
+
+## Rules
+
+- Still requires permissions, pre-flight checks, and doer/reviewer pairing (see doer-reviewer.md)
+- No progress.json or PLAN.md — status is tracked in `<project>/status.md` by PM
+- Agent context file is still required for doer and reviewer (see context-file.md)
+
+## Recovery After PM Restart
+
+No progress.json — recovery relies on git history and status.md.
+
+1. `execute_command → git log --oneline -5` on member — any commits since last known state?
+2. `execute_command → git status` — uncommitted changes?
+3. Compare against `<project>/status.md` — what did PM last know?
+
+- **Work committed, next step clear** → resume doer with `resume=true` or dispatch reviewer
+- **At review checkpoint** → dispatch reviewer with `resume=false`
+- **Uncommitted changes of unknown origin** → escalate to user: "commit and resume, or discard?"
+- **No progress** → re-dispatch from scratch

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

@@ -0,0 +1,178 @@
+# Running a Sprint
+
+A sprint is a focused unit of work executed by a doer/reviewer pair against a codebase. This document covers the full lifecycle from initiation to PR raise.
+
+## Lifecycle
+
+```
+vision → requirements → design → plan → development → testing → deployment
+```
+
+PM drives work through these phases in order. Don't skip, don't stall between them.
+
+---
+
+## Phase 1 — Requirements
+
+Write `<project>/requirements.md`. Quality bar:
+- Include full issue details — code locations, root causes, impact data
+- Never summarize into 2-3 line descriptions — include full issue text, code locations, root causes
+- Front-load risk — the riskiest assumption must be validated in Task 1 of the plan
+
+---
+
+## Phase 2 — Plan Generation
+
+**Branch naming:** choose a name that makes the purpose of the branch immediately clear — `sprint/<description>`, `feat/<description>`, `bug_fix/<short_description>`, etc. PM records this as `{{branch}}` in the agent context file before dispatch.
+
+1. Send `requirements.md` and `tpl-plan.md` to doer via `send_files`
+2. Dispatch `plan-prompt.md` via `execute_prompt` (wrapped in background Agent)
+3. Run doer-reviewer loop (see `doer-reviewer.md`) using `tpl-reviewer-plan.md` for the reviewer
+4. Iterate until plan passes quality criteria
+5. Once APPROVED: save `planned.json` in `<project>/` — this is the immutable original, never modify it
+6. **Beads: push plan tasks** — for each task in PLAN.md, create a Beads task and wire dependencies:
+   ```bash
+   bd create "T1.1: <title>" -p 1 --parent <epic-id> --assignee <doer>   # → task-id
+   bd create "T1.2: <title>" -p 2 --parent <epic-id> --assignee <doer>   # → 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` Beads section. See `beads.md`.
+7. Proceed to Phase 3
+
+---
+
+## Phase 3 — Execution
+
+### Task Harness
+
+The task harness is the set of files sent to the doer's `work_folder` root via `send_files` to bootstrap execution:
+
+1. **Agent context file** — from `tpl-doer.md`. See `context-file.md` for filename and delivery rules.
+2. **PLAN.md** — implementation plan with phases and tasks
+3. **progress.json** — task tracker (generated from PLAN.md per `tpl-progress.json`)
+4. **Project docs** — `requirements.md`, `design.md`, and any other docs the doer needs. Doer commits these to the branch. Re-send via `send_files` if PM-side docs are updated mid-sprint.
+
+`progress.json` is the living state. Always query it for current status.
+
+### Per-Task Dispatch Algorithm
+
+Before each doer dispatch, PM reads `planned.json` and `progress.json`:
+
+```
+nextTask = planned.json.tasks.find(t => t.status === "pending")
+tier     = nextTask.tier
+resume   = (nextTask.phase === lastDispatchedPhase)   // from status.md
+```
+
+Dispatch ONE task at `model: <tier>`. PM records `lastDispatchedPhase = nextTask.phase` in `status.md` after each dispatch.
+
+### Execution Loop
+
+```
+PM sends task harness → dispatches doer (resume per data-driven rule, model=nextTask.tier)
+  → bd update <task-id> --status in_progress --assignee <doer>
+  → doer reads progress.json → executes next pending task → commits → updates progress.json
+  → hits VERIFY checkpoint → STOPS → PM reads progress.json
+  → bd close <verify-id>
+  → PM dispatches REVIEWER (model=premium) → reviewer reads deliverables + diff → commits verdict to feedback.md → pushes
+  → APPROVED: PM dispatches doer for next task (resume=true if same phase) → repeat
+  → CHANGES NEEDED: bd create "<finding>" -p 0 --parent <epic-id> --assignee <doer> per HIGH finding → PM sends feedback to doer → doer fixes → bd close <finding-id> → PM re-dispatches REVIEWER → repeat
+  → all tasks done → move to next phase or completion
+```
+
+### Session Rules
+
+| Dispatch | resume |
+|----------|--------|
+| New phase (`nextTask.phase !== lastDispatchedPhase`) | `false` |
+| Same phase (`nextTask.phase === lastDispatchedPhase`) | `true` |
+| After reviewer CHANGES NEEDED → doer fix | `true` |
+| Initial review dispatch | `false` |
+| Re-review after fixes | `true` |
+| Role switch (doer↔reviewer) | `false` |
+
+**Data-driven resume rule** — derived from `planned.json` phase numbers, 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` |
+
+### Permissions
+
+Before kicking off execution, compose and deliver permissions for each member's role (see the fleet skill, `permissions.md`). Recompose on every role switch.
+
+**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`.
+
+### Monitoring
+
+- Check progress: `execute_command → cat progress.json`
+- Check git: `execute_command → git log --oneline -10`
+- Members may blow past VERIFY checkpoints if context gets large — dispatch a review immediately when caught
+- Long-running branches: check drift with `git log <branch>..origin/main --oneline`. If main moved, instruct rebase + retest
+- After every review verdict: create low-priority Beads tasks for unaddressed MEDIUM/LOW findings and deferred scope items (`bd create "<item>" -p 3 --parent <epic-id>` — see `backlog-item.md` for required description fields)
+- Deferred items from user ("add to backlog", "defer this"): `bd create "<description>" -p 3 --parent <epic-id>`
+
+### Safeguards
+
+| Safeguard | Trigger | PM Action | Limit |
+|-----------|---------|-----------|-------|
+| Max-turns budget | Every 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 + 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 + flag user | 3 cycles per phase |
+| Model escalation | Zero progress after resets | Reset and resume; after 2 resets with zero progress: escalate model (`cheap`→`standard`→`premium`). Still zero? Flag user | 2 resets per model tier |
+
+---
+
+## Phase 4 — Deployment
+
+Run `<project>/deploy.md` steps on the member via `execute_command`. Verification and rollback steps must be defined in `deploy.md` by the user — follow them exactly. On failure, execute the rollback steps in `deploy.md` and flag the user.
+
+---
+
+## Sprint Completion
+
+When all phases are APPROVED:
+
+1. **Documentation Harvest** — Dispatch a member to extract long-term knowledge from `requirements.md`, `design.md`, and `PLAN.md` into `docs/`. Structure inside `docs/` is content-driven (e.g. `docs/architecture.md`, `docs/features/<name>.md`). Extract: architecture decisions, feature design, key trade-offs, API contracts. Do NOT extract: task lists, code-line references, debug notes, implementation steps. Member commits the docs/ output to the branch. Then dispatch reviewer to review the harvest — verify it captures durable knowledge and nothing transient slipped in. Iterate until APPROVED.
+
+2. **Cleanup and raise PR** — See cleanup.md.
+
+   STOP: Sprint is complete. Do not merge the PR. Surface the PR URL and CI status to the user and await explicit instruction to merge.
+
+3. **Deferred items** — any unresolved MEDIUM/LOW findings or deferred scope from this sprint should already be in Beads as low-priority tasks. Verify with `bd list --all --pretty`.
+
+4. **Update status.md** — mark sprint complete, record member states. Clear `lastDispatchedPhase`.
+
+---
+
+## Recovery After PM Restart
+
+When the PM session ends unexpectedly, remote agent CLI processes are killed (SSH channel close → SIGHUP). Partial work may be uncommitted.
+
+**Step 0 — Global triage:** Run `bd list --all --pretty` first for PM dispatch state across all projects (no file reads needed for orientation). Then `fleet_status` to check member connectivity. **Important:** Beads reflects PM actions (dispatch/close), not member execution — always follow up with `cat progress.json` per member to confirm actual completion state. A task marked `in_progress` in Beads may be incomplete on disk if the member crashed mid-task.
+
+For each member in the project:
+1. `execute_command → cat progress.json` — what tasks are completed/pending/blocked?
+   - **On reviewer members:** progress.json is not authoritative — it reflects the doer's task state at last sync. Check `git log --oneline -- feedback.md` for reviewer progress instead.
+2. `execute_command → git log --oneline -5` — any commits since last known state?
+3. `execute_command → git status` — uncommitted changes?
+4. Compare against local `<project>/status.md` — what did PM last know? Check `lastDispatchedPhase` to determine resume vs. fresh-session for next dispatch.
+
+Present a per-member state summary before acting:
+
+| Member | PM last knew | Actual state | Delta | Action |
+|--------|-------------|--------------|-------|--------|
+| <name> | <phase/task from status.md> | <last commit + progress summary> | <what changed> | auto-resume / escalate |
+
+**Auto-resume** (PM acts immediately, no user input needed):
+- **Checkpoint reached, review pending** → dispatch reviewer now
+- **Mid-task with commits, clear next step** → resume doer with `resume=true`
+- **No progress, member idle** → re-dispatch from last known state
+
+**Escalate to user** (ambiguous or risky — present options and wait):
+- **Uncommitted changes of unknown origin** → "member has uncommitted work not matching any known task. Commit and resume, or discard?"
+- **Conflicting state** (progress.json says complete but git shows no commits) → "state inconsistency detected. Investigate or reset?"
+- **Zero progress after re-dispatch** → "member made no progress after re-dispatch. Escalate model or reassign?"

package/skills/pm/tpl-deploy.md

@@ -0,0 +1,24 @@
+# {{PROJECT_NAME}} — Deploy
+
+## Steps
+<!-- Replace with your project's deploy sequence. PM executes these via execute_command on the member. -->
+
+<!-- Example: Node.js app -->
+<!-- git pull origin main -->
+<!-- npm install -->
+<!-- npm run build -->
+<!-- pm2 restart app -->
+
+<!-- Example: GitHub release -->
+<!-- gh release download latest -p '*.tar.gz' -->
+<!-- tar xzf *.tar.gz -->
+<!-- ./install.sh -->
+
+<!-- Example: Serverless -->
+<!-- cd deploy && sls deploy --stage prod -->
+
+## Verify
+<!-- How to confirm the deploy worked. PM runs this after deploy steps. -->
+<!-- curl -s http://localhost:3000/health -->
+<!-- sls info --stage prod -->
+<!-- systemctl status app -->

package/skills/pm/tpl-design.md

@@ -0,0 +1,29 @@
+# Design — {{BACKLOG_ID}} {{TITLE}}
+
+## Problem
+- {{symptom}} — {{specific example}}
+- {{root cause}} — {{technical explanation}}
+
+## Solution
+{{2-4 sentences: what changes, what stays, key architectural shift}}
+
+## Data Model
+`{{file_path}}`:
+```json
+{{concrete example with real values, 3-5 entries}}
+```
+
+## API Changes
+| Method | Path | Body | Purpose |
+|--------|------|------|---------|
+
+## What Gets Deleted
+| File / Symbol | Why |
+|---------------|-----|
+
+## What Stays / Adapts
+| What | Change |
+|------|--------|
+
+## Out of Scope
+- {{thing NOT to build}} — {{why not now}}

package/skills/pm/tpl-doer.md

@@ -0,0 +1,43 @@
+# {{PROJECT_NAME}} - Plan Execution
+
+## Context Recovery
+Before starting any work: `git log --oneline -10`
+
+## Execution Model
+You are executing a plan defined in PLAN.md. Progress tracked in progress.json.
+
+On each invocation:
+1. Read progress.json — find next task with status "pending"
+2. Read PLAN.md — get full details for that task
+3. Execute — write code, run tests, fix issues
+4. Commit with descriptive message referencing the task ID
+5. Update progress.json — set task to "completed", add notes
+6. Continue to next pending task
+
+## Verify Checkpoints
+Tasks with type "verify" are checkpoints. When you reach one:
+1. Run the project build step (e.g. `npm run build`, `tsc`, `cargo build`) and linter check (e.g. `npm run lint`, `eslint`, `cargo clippy` if configured) first, then run the full test suite (unit, integration, e2e). All of them must pass.
+2. Confirm all prior tasks in the group work correctly
+3. Update progress.json with test results and issues found
+4. `git push origin {{branch}}` - code must be on origin before PM reviews
+5. STOP - do not continue. Report status so the PM can review.
+
+## Branch Hygiene
+- Before creating a branch: `git fetch origin && git checkout origin/{{base_branch}}`
+- Before pushing a PR or at PM's request: `git fetch origin && git rebase origin/{{base_branch}}`, rerun tests after rebase
+
+## Secrets & API Keys
+
+If this task requires secrets, API keys, or tokens (e.g., external API calls, private registry pushes, third-party service authentication), check whether the PM has pre-loaded them via the credential store before you start. Use `{{secure.NAME}}` tokens only in `execute_command` — never in prompts or log messages. Fleet resolves and redacts them automatically in commands. Do not ask for raw secret values in conversation; if a required `sec://NAME` handle is missing, report it as a blocker so the PM can store it OOB.
+
+## Rules
+- ONE task at a time, then commit, then continue
+- After every commit: run fast/unit tests and linter checks. If they fail, fix before moving to the next task.
+- Always update progress.json after each task
+- Blocker? Set status to "blocked" with notes, then STOP
+- NEVER skip tasks - execute in order
+- Read PLAN.md before starting each task
+- Commit and push PLAN.md, progress.json, and all project docs (design.md, feedback-*.md) at every turn - reviewers depend on them
+- NEVER commit this agent context file (CLAUDE.md / GEMINI.md / AGENTS.md / COPILOT.md / AGY.md) - it is role-specific and not shared
+- NEVER push to the base branch (main, master, or integration branch) - always work on feature branches
+- NEVER stage or commit `.fleet-task.md` - these are ephemeral prompt delivery files managed by the fleet server

package/skills/pm/tpl-plan.md

@@ -0,0 +1,72 @@
+# {{PROJECT_NAME}} — Implementation Plan
+
+> {{PLAN_SUMMARY}}
+
+---
+
+## Tasks
+
+### Phase 1: {{PHASE_1_NAME}}
+
+#### Task 1: {{TASK_TITLE}}
+- **Change:** {{what to do}}
+- **Files:** {{which files}}
+- **Tier:** cheap | standard | premium
+- **Done when:** {{acceptance criteria}}
+- **Blockers:** {{potential blockers}}
+
+#### Task 2: {{TASK_TITLE}}
+- **Change:** {{what to do}}
+- **Files:** {{which files}}
+- **Tier:** cheap | standard | premium
+- **Done when:** {{acceptance criteria}}
+- **Blockers:** {{potential blockers}}
+
+#### Task 3: {{TASK_TITLE}}
+- **Change:** {{what to do}}
+- **Files:** {{which files}}
+- **Tier:** cheap | standard | premium
+- **Done when:** {{acceptance criteria}}
+- **Blockers:** {{potential blockers}}
+
+#### VERIFY: {{PHASE_1_NAME}}
+- Run full test suite
+- Confirm all Phase 1 changes work together
+- Report: tests passing, any regressions, any issues found
+
+---
+
+### Phase 2: {{PHASE_2_NAME}}
+
+#### Task 4: {{TASK_TITLE}}
+{{TASK_DETAILS}}
+
+...
+
+#### VERIFY: {{PHASE_2_NAME}}
+
+---
+
+## Risk Register
+
+| Risk | Impact | Mitigation |
+|------|--------|------------|
+| {{risk}} | {{high/med/low}} | {{mitigation}} |
+
+Cover at minimum: backward compat (changed interfaces, renamed items), security (trust boundaries, input validation), external constraints (no new dependencies, min runtime version), partial failure (one path works, another doesn't).
+
+## Phase Sizing Rules
+
+**Phase boundaries by cohesion, not count.** A phase is a coherent unit of work that produces a reviewable, testable increment. Group tasks into a phase when they share a data model, code path, or design decision — splitting them would produce an incoherent intermediate state or require touching the same code twice. Place a VERIFY at the natural completion boundary of that unit, not at an arbitrary task count. Phases may have 4-5 tasks (a coherent subsystem) or just 1-2 (a genuinely isolated change).
+
+**Monotonically non-decreasing tiers within a phase.** Within a phase, order tasks cheap → standard → premium. The PM resumes the same session across tasks in a phase — a premium task can build a large context that a cheap model cannot load. The PM may group consecutive same-tier tasks into a single dispatch streak; tier transitions trigger a new dispatch. If a dependency forces a higher-tier task before a lower-tier task within a phase, split the phase at that boundary rather than violating the ordering rule. Cross-phase tier order does not matter — each phase always starts a fresh session.
+```
+cheap → cheap → standard → standard → premium → VERIFY  [VALID]
+cheap → standard → cheap → VERIFY  [INVALID]  (downgrade within phase — split into two phases)
+```
+
+## Notes
+- Each task should result in a git commit
+- Verify tasks are checkpoints — stop and report after each one
+- Base branch: {{base_branch}}
+- Implementation branch: {{impl_branch}}

package/skills/pm/tpl-pm.md

@@ -0,0 +1,2 @@
+# PM — Project Manager
+Read @projects.md for active projects, then follow the pm skill.

package/skills/pm/tpl-progress.json

@@ -0,0 +1,28 @@
+{
+  "_schema": {
+    "type": "work | verify",
+    "status": "pending | completed | blocked"
+  },
+  "project": "{{PROJECT_NAME}}",
+  "plan_file": "PLAN.md",
+  "created": "{{DATE}}",
+  "tasks": [
+    {
+      "id": 1,
+      "step": "{{TASK_TITLE}}",
+      "type": "work",
+      "status": "pending",
+      "tier": "standard",
+      "commit": "",
+      "notes": ""
+    },
+    {
+      "id": 2,
+      "step": "VERIFY: {{PHASE_NAME}}",
+      "type": "verify",
+      "status": "pending",
+      "commit": "",
+      "notes": ""
+    }
+  ]
+}

package/skills/pm/tpl-projects.md

@@ -0,0 +1,4 @@
+# Active Projects
+
+| Project | Folder | Members | Phase | Status |
+|---------|--------|---------|-------|--------|

package/skills/pm/tpl-requirements.md

@@ -0,0 +1,21 @@
+# Requirements — {{BACKLOG_ID}} {{TITLE}}
+
+## Base Branch
+`{{main | v020_dev | etc}}` — branch to fork from and merge back to
+
+## Goal
+{{1-2 sentences: what the user wants and why}}
+
+## Scope
+- {{specific deliverable}}
+- {{specific deliverable}}
+
+## Out of Scope
+- {{thing NOT to build}} — {{why not now}}
+
+## Constraints
+- {{technical, timeline, or compatibility constraint}}
+
+## Acceptance Criteria
+- [ ] {{observable outcome that proves the goal is met}}
+- [ ] {{observable outcome}}

package/skills/pm/tpl-reviewer-plan.md

@@ -0,0 +1,53 @@
+# Plan Review
+
+You are reviewing a plan in PLAN.md against requirements.md and any design docs in the work folder.
+
+## Check each item
+
+1. Does every task have clear "done" criteria?
+2. High cohesion within each task, low coupling between tasks?
+3. Are key abstractions and shared interfaces in the earliest tasks?
+4. Is the riskiest assumption validated in Task 1?
+5. Later tasks reuse early abstractions (DRY)?
+6. Are phase boundaries drawn at cohesion boundaries — each phase is a coherent unit producing a reviewable, testable increment (tasks share a data model, code path, or design decision)?
+7. Are tiers monotonically non-decreasing within each phase (cheap → standard → premium, never downgrading mid-phase)?
+8. Each task completable in one session?
+9. Dependencies satisfied in order?
+10. Any vague tasks that two developers would interpret differently?
+11. Any hidden dependencies between tasks?
+12. Does the plan include a risk register? If missing or incomplete, identify the risks yourself and add them as findings
+13. Does the plan align with requirements.md intent — solving the right problem, not just a technically clean plan?
+
+## Output
+
+If this is a re-review: run `git log --oneline -- feedback.md` then `git show <sha>` on prior versions to understand what was previously flagged and how the doer addressed it. Incorporate those responses into your new write-up.
+
+Overwrite feedback.md with this structure:
+
+```
+# {{sprint_name}} — Plan Review
+
+**Reviewer:** {{member_name}}
+**Date:** YYYY-MM-DD HH:MM:SS+TZ
+**Verdict:** APPROVED | CHANGES NEEDED
+
+> See the recent git history of this file to understand the context of this review.
+
+---
+
+## <Review section>
+
+<Detailed narrative. PASS/FAIL/NOTE inline. Explain what you found, where, and why it matters.>
+
+---
+
+## Summary
+
+<Synthesize what passed, what must change, what is deferred.>
+```
+
+For each check: PASS or FAIL with narrative — not one-liners.
+
+If verdict is CHANGES NEEDED: the doer annotates each relevant section with `**Doer:** fixed in commit <sha> — <what changed>` before requesting re-review.
+
+Commit feedback.md and push.