apm-review-panel

# APM Review Panel - Fan-Out Advisory Review

The panel is FAN-OUT + SYNTHESIZER. Each persona runs in its own agent
thread (via the `task` tool) and returns JSON matching
`assets/panelist-return-schema.json`. The orchestrator schema-validates
each return, hands all returns to the apm-ceo synthesizer (also a task
thread, returns JSON matching `assets/ceo-return-schema.json`), then
renders ONE recommendation comment from `assets/recommendation-template.md`.

This skill is ADVISORY by design. It does not compute a binary verdict, it
does not apply verdict labels, and it does not gate merge. The panel
surfaces findings; the maintainer and the PR author decide ship.

## Architecture invariants

- **Advisory regime, not gate regime.** There is no `APPROVE` / `REJECT`,
  no `panel-approved` / `panel-rejected` label, no deterministic verdict
  computation. The CEO returns a `ship_recommendation.stance` (`ship_now`
  / `ship_with_followups` / `needs_discussion` / `needs_rework`); this is
  prose for the human reviewer, never auto-applied as a label or status
  check. This is the architectural fix for the previous regime's
  over-strictness: removing the binary gate removes the incentive for
  panelists to inflate `required[]` defensively.
- **Three severity buckets, none of them gate.** Findings carry
  `severity: blocking | recommended | nit`. `blocking` is the highest
  signal a panelist can send and renders prominently in the comment; it
  still does not block merge. `recommended` is the default for substantive
  feedback. `nit` is one-line polish. The orchestrator never reads
  severity to gate anything.
- **Single-writer interlock.** Only the orchestrator writes to the PR:
  exactly one `add-comment` and one `remove-labels` call. The
  `remove-labels` call always sweeps `panel-review` (trigger
  idempotency) AND defensively removes `panel-approved` /
  `panel-rejected` if present (legacy verdict labels from the
  pre-advisory regime; they have no meaning here and would mislead
  readers if left on a PR after a fresh advisory pass). NO `add-labels`
  call -- there are no verdict labels to apply. Panelist subagents and
  the CEO subagent return JSON only and MUST NOT call any `gh` write
  command, post comments, apply labels, or touch the PR state.
- **Single-emission discipline.** Exactly one comment per panel run,
  rendered from `assets/recommendation-template.md` after all subagents
  return.
- **Non-empty turn exit (the run's hard contract).** gh-aw decides
  success by inspecting `agent_output` AFTER your turn ends: a turn that
  ends with zero safe outputs (`agent_output = {"items":[]}`) is detected
  as a failure, the safe-output detection job is skipped, the
  `add-comment` job never runs, and the workflow opens a "No Safe Outputs
  Generated" issue. Therefore your turn MUST end with at least one safe
  output -- the rendered comment on success (step 7), or an explicit
  `noop` if the run genuinely cannot produce one. NEVER end the turn
  empty.
- **Synchronous fan-out -- never spawn-and-forget.** Every `task` spawn
  (each panelist AND the CEO synthesizer) is BLOCKING: spawn it, WAIT for
  its JSON return, then continue. Use the `task` tool's synchronous mode;
  do NOT use its background/detached mode -- the variant that returns an
  `agent_id` immediately and runs the subagent in the background -- for
  any panelist or the CEO. Their returns are LOAD-BEARING: the comment
  cannot be rendered without them. Spawning the CEO (or a panelist)
  detached and then ending the turn while it is still running is the
  documented cause of the empty-output failure above.

## Agent roster

| Agent | Role | Always active? |
|-------|------|----------------|
| [Python Architect](../../agents/python-architect.agent.md) | Architectural Reviewer + supplies mermaid diagrams | Yes |
| [CLI Logging Expert](../../agents/cli-logging-expert.agent.md) | Output UX Reviewer | Yes |
| [DevX UX Expert](../../agents/devx-ux-expert.agent.md) | Package-Manager UX | Yes |
| [Supply Chain Security Expert](../../agents/supply-chain-security-expert.agent.md) | Threat-Model Reviewer | Yes |
| [OSS Growth Hacker](../../agents/oss-growth-hacker.agent.md) | Adoption Strategist | Yes |
| [Auth Expert](../../agents/auth-expert.agent.md) | Auth / Token Reviewer | Conditional (see below) |
| [Doc Writer](../../agents/doc-writer.agent.md) | Documentation Reviewer | Conditional (see below) |
| [Test Coverage Expert](../../agents/test-coverage-expert.agent.md) | Test-Presence Reviewer (paired with DevX UX) | Yes (skipped only on docs-only PRs -- see below) |
| [Performance Expert](../../agents/performance-expert.agent.md) | Package-Manager Performance Reviewer | Conditional (see below) |
| [APM CEO](../../agents/apm-ceo.agent.md) | Strategic Arbiter / Synthesizer | Yes |

## Topology

```
   apm-review-panel SKILL (orchestrator thread)
                      |
   FAN-OUT via task tool (panelists in parallel)
                      |
   +-----+-------+-------+-----+-----+------+-----------+----------+
   v     v       v       v     v     v      v           v          v (cond.)
  py    cli     dx-ux   sec   grw   auth   doc-writer  test-cov
   |     |       |       |     |     |      |           |
   |   each returns JSON per panelist-return-schema.json
   +-----+-------+-------+-----+-----+------+-----------+----------+
                      |
                      v   <-- S4 schema-validate
                      v   <-- on malformed: re-spawn that persona
                      v
   task: apm-ceo synthesizer
   - aggregates findings across panelists
   - resolves dissent
   - emits headline + arbitration prose + principle alignment
   - emits curated recommended_followups (prioritized)
   - emits ship_recommendation (stance + prose)
   - returns ceo-return-schema.json
                      |
                      v   <-- S4 schema-validate
                      v
   orchestrator (sole writer)
            |               |