PM Agent — product management over agentflare items

Two arms, one contract boundary

• Reporting (default, Part 1 below): /pm:standup, /pm:groom, /pm:plan, /pm:health, /pm:portfolio — always read-only, never mutate.
• PM mode (Part 2 below — explicit activation only: "act as project manager", "PM mode", "e2e project management", or /pm with no args / /pm mode on): the execution arm. Creates items, hands work off to real agents, and implements inline only small mechanical changes (Part 2, Contract rule 1). Typing the literal /pm (bare) or /pm mode on//pm mode off also flips a session-scoped flag in agentflare's UserPromptSubmit hook (mirrors flare-code's own session-mode flag) — once set, every subsequent turn in this session gets a "PM MODE ACTIVE" reminder injected automatically, so the mode survives context compaction instead of depending on the model remembering a skill instruction. Only /pm mode off clears it; it does not expire on its own.

Never treat a reporting workflow's inputs as license to mutate, and never slip into PM mode's mutating behavior without one of the explicit triggers above.

The pm MCP tool

Every workflow in Part 1, plus mode_on/mode_off/mode_status, is also reachable as one first-class tool call — pm (action= standup|groom|plan|health|portfolio|mode_on|mode_off|mode_status) — instead of composing item/project calls by hand. It's a thin wrapper (same underlying item action=groom|standup|health / project action=list calls this skill already teaches, just pre-shaped: groom/plan fix state_group="backlog,unstarted", plan forces a capacity bucket, portfolio does the per-project loop itself). Use whichever is more convenient — a client with no skill support (not Claude Code, or PM mode's mode_on/off without the literal /pm mode on/off prompt) has no other way to reach this. Scoring frameworks (RICE/WSJF/...) still live in this skill's reference/rubric.md, not in the tool — it never becomes the caller's judgment call.

Scope

Default: one project — whichever project the current repo resolves to. /pm:portfolio is the one reporting exception: it loops the read-only reports across every project in the workspace via the project override param (still read-only, still one workspace). PM mode's dispatch actions likewise default to the current repo's linked project unless told otherwise.

Part 1 — Reporting workflows (read-only, non-negotiable)

Never call item with any of: create, update, update_state, delete, claim, heartbeat, release, done, cancel, add_label, remove_label — nor comment create/edit/delete. Only read (item list/get/search/groom/standup/health, comment list, handoff inbox, memory). Output is suggestions for a human, never actions taken.

All content authored from public PM methodologies (RICE, ICE, WSJF, Value-Effort, MoSCoW, Now/Next/Later). No third-party notices required.

Before any workflow, read reference/read-recipe.md. Grooming, planning, and health additionally use reference/rubric.md.

/pm:standup — daily activity digest

Arg: cutoff (default: items with updated_at within the last 24h).

1. One call: item action="standup" cutoff_hours=<hours, default 24>. The server returns done (completed within cutoff_hours), in_progress (grouped by assignee, "unassigned" as its own group), and stuck (in-progress items older than staleness_days, default 7) — already bucketed, no hand-sorting a flat list result.
2. For each item print FIX-NN · <name> · <assignee or unassigned>.
3. Print the read-recipe time-signal caveat. Read-only: never change item state.

/pm:groom — backlog grooming + prioritization

Args: staleness threshold in days (default 14); framework (rice default, wsjf, value-effort — see reference/rubric.md's Framework selection).

1. One call: item action="groom" state_group="backlog,unstarted" staleness_days=<threshold> limit=15. This replaces the old list + N×get + hand-computed flags — the server already returns the shortlist (priority + recency ranked, full description) with stale, unassigned, blocked_by, depended_on_by_count, possible_duplicates, size/unestimated precomputed per item, plus pull_next and the summary counts. Do not re-derive these by eyeballing timestamps or text — they're already computed.
2. Score each shortlisted item with reference/rubric.md using the requested framework (RICE using the returned size where present, ICE fallback where unestimated=true; wsjf/value-effort when explicitly requested, marking ? per item instead of ICE-falling-back when unestimated=true) — your judgment is only needed for Reach/Confidence (RICE) or the equivalent qualitative factors the other frameworks reuse, none of which the server can infer from free text. Print a ranked table: rank · FIX-NN · name · score · one-line reason.
3. Flag lists — read straight from the response, no recomputation:
   • Stale: items with stale=true.
   • Unassigned: items with unassigned=true (unassigned_count for the total).
   • Blocked: items with non-empty blocked_by.
   • Likely duplicates: items with non-empty possible_duplicates.
   • Unestimated: items with unestimated=true (unestimated_count for the total) — recommend adding metadata={"size":"S"|"M"|"L"} via item(update).
4. Pull next: the response's pull_next (top 3 unassigned/not-stale/unblocked by rank) — cross-check against your RICE ranking and note if they diverge.
5. Print the time-signal caveat. Read-only — groom only reads.

/pm:plan — Now / Next / Later bucketing

Args: capacity hint like "~8" (optional; caps the Now bucket); framework (rice default, wsjf, value-effort — see reference/rubric.md's Framework selection).

1. One call: item action="groom" state_group="backlog,unstarted" capacity=<hint or a sane default like 5>. The server does the bucketing: now (top-capacity ready items — unblocked, has a size), next (remaining ready items), later (blocked items), needs_estimation (unestimated — excluded from planning). No hand-bucketing.
2. Score each item with reference/rubric.md for the printed rationale, using the requested framework (RICE using size, ICE fallback for unestimated ones; wsjf/value-effort when explicitly requested) — your judgment covers the qualitative factors, the buckets themselves are already computed.
3. Print each bucket as an ordered list of FIX-NN · name · score.
4. Print the time-signal caveat. Read-only — this proposes a plan, it does not assign or move items.

/pm:health — team health scorecard

Arg: window in weeks (default 4).

1. One call: item action="health" window_weeks=<N, default 4>. The server returns velocity (oldest→newest weekly series + velocity_trend: up/down/flat), wip (list + count), stuck (WIP older than staleness_days, default 7), and bottlenecks/bottleneck_note.
2. bottlenecks lists items handed between different agents ≥2× inside the window, computed server-side from the persisted assignment log (written on every claim/reassignment). Print each entry as returned (#N name — K handoffs (owner chain)), plus bottleneck_note — it carries the one caveat that matters: history starts at the assignment-log migration, so older transitions are invisible.
3. One-glance scorecard: Velocity · WIP · Stuck · Bottlenecks.
4. Print the time-signal caveat. Read-only.

/pm:portfolio — cross-project roll-up

Args: which report (health default, or standup); the report's own args pass through (window weeks / cutoff hours).

1. One call: project action="list" — every project in the linked workspace.
2. For each project, one call: item action="<health|standup>" project=<project name> — the project override is honored only by the read-only reporting actions, so this stays mutation-free by construction.
3. Print one roll-up table, one row per project:
   • health: project · velocity trend · WIP · stuck · bottleneck count.
   • standup: project · done · in-progress · stuck counts. Follow with a short "needs attention" list: any project with stuck items, a down velocity trend, or non-empty bottlenecks, and why.
4. Print the time-signal caveat once (it applies to every row). Read-only.

Part 2 — PM mode (mutating — explicit activation only)

In this mode you manage work. Every substantial task becomes a tracked item, handed off to a real agent, worked autonomously by the daemon's own supervisor. Small mechanical changes are the exception: you do those yourself (Contract rule 1), because the dispatch round trip costs more than the fix.

When to use

• User says "act as project manager", "PM mode", "e2e project management", or otherwise asks you to delegate rather than implement.
• NOT for /pm:standup//pm:groom//pm:plan//pm:health//pm:portfolio — those are Part 1's read-only reporting workflows and stay read-only even while PM mode is active for other tasks. PM mode is the execution arm: it mutates (creates items, hands off work), Part 1 never does.

Contract

1. Delegate by default; do small changes yourself. Diagnose/scope the work, then hand it off — except a small change, which you make directly. A change is small only if ALL of these hold:

   • it is mechanical or unambiguous (formatting, a rename, a typo, docs, a config value, a one-line fix whose correct form is not in question), touches about 2 files or fewer and ~30 changed lines, and needs no design decision or new behavior;
   • you can verify it locally in minutes (cargo fmt --all --check, the exact CI clippy command, the targeted tests);
   • it is not security-sensitive or destructive, and not in claim/lease/dispatch/auth/protocol code.

   A small change is still real work: claim the item (or create one), make the change in the claimed worktree on a branch — never on master — open a PR, wait for CI, and report it in the status table as "done directly (small)". If a dispatched agent already failed to land a small fix once (exited 0 with nothing pushed), do it yourself instead of redispatching. When unsure whether a change is small, dispatch it.

2. Validate the recipient before handoff. Check agentflare agents list (or agent_registry) first — a typo'd or thematic recipient (e.g. "gastown", a codename, not an agent) silently orphans the item since nothing will ever claim it. Only real registered agents, or the reserved "github" recipient, are valid.
3. Classify the task type, then shape the handoff content for it. Diagnosis already tells you what kind of work this is — decide the framing before writing the handoff content, using the table below. This is not about picking a different recipient (only claude-code and opencode are real registered agents today) — it's about how the dispatched session should read the prompt once it claims the item. A diff dumped with no ask gets worked generically; a framed request gets the deliverable you actually want.
4. Use handoff, not raw item update. mcp__flare__handoff with recipient + name + content + completed + remaining (both required) — creates or targets an item and attaches the work as a versioned asset. item action=update assignee_agent=... skips the asset trail.
5. Let the daemon dispatch it — don't run agentflare work <id> yourself. A freshly-handed-off item to a real agent gets auto-labeled ready-for-work; the daemon's own agentflare-supervisor discovery tick claims and dispatches it autonomously. Manually running agentflare work defeats the point of this mode.
6. Monitor, don't poll blindly. agentflare daemon logs [--follow] for live activity; item get/list for state/assignee — an instance-suffixed assignee_agent like claude-code:abc123 confirms real dispatch, not just a queued handoff. The agent_jobs table (state + output.exit_code) is ground truth for success/failure — state=exited alone does not mean success, always check exit_code.
7. Report as a status table, not a raw dump: item · state · assignee · one-line note. Flag anything stuck or orphaned.

Task-type routing heuristic

Before calling handoff, match the diagnosed work to a shape and frame the content accordingly. The recipient stays whichever real agent is being used — this only changes how the prompt inside the handoff is written.

A handoff that just pastes a diff or a one-line title forces the dispatched session to guess the task type from content alone — it'll often default to "implement", which is wrong for review/research/design work.

Quick reference

Common mistakes

• Trusting handoff's recipient field without checking it's real — creates an orphaned item nobody will ever work.
• Dispatching manually via agentflare work "to save time" — defeats the point of dogfooding the daemon; only do this if the daemon is confirmed down.
• Reading state=exited as success — check exit_code.
• Dispatching a trivial mechanical fix (formatting, a typo, a one-line change). The round trip costs more than the fix, and a dispatched agent builds its task from the item description, not from a comment posted before dispatch, so a vague instruction can exit 0 having done nothing. Do it yourself under Contract rule 1.
• Stretching "small" to cover a design decision, a multi-file change, or claim/lease/dispatch/auth code. When in doubt, dispatch.
• Dumping a diff or a bare title into content without task-type framing — the dispatched session guesses "implement" by default and does the wrong thing for review/research/design work.