apm: Skill for Claude Code

APM Spec Guardian -- Four-Panel Advisory Review for OpenAPM

This skill institutionalizes the two-round adversarial spec review that produced OpenAPM v0.1 by hand. The panel is FAN-OUT + SYNTHESIZER. Each panelist 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 spec-editor-synthesizer (also a task thread, returns JSON matching assets/synthesizer-return-schema.json), runs the linter checklist in assets/linter-checklist.md, then renders ONE comment from assets/comment-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 ships.

Activation scope

This skill activates ONLY when the PR diff touches at least one of:

• docs/src/content/docs/specs/openapm-*.md (the normative spec artifact, current and future versions)
• docs/src/content/docs/specs/schemas/*.schema.json (sidecar JSON Schemas, if/when the inline Appendix-A schemas are extracted to files)
• tests/fixtures/spec-conformance/** (the conformance fixture seed)

Edits to any OTHER documentation page MUST NOT trigger this skill. The maintainer's general docs-sync skill covers those.

Architecture invariants

• Advisory regime, not gate regime. There is no APPROVE / REJECT, no spec-approved / spec-rejected label, no deterministic verdict computation. The synthesizer returns a ship_decision (fold_and_ship / needs_revision / next_brief); this is prose for the human reviewer, never auto-applied as a label or status check.
• Ship-meter floor. ship_decision: fold_and_ship REQUIRES shocked_meter_avg >= 7.0. Below 7.0 the synthesizer MUST emit needs_revision (single drafter pass on the existing artifact) or next_brief (another round of panel review with a new brief). The floor is advisory wording in the comment, not a status check.
• Blocker veto. If ANY panelist returns new_blocking_findings[].length > 0, the synthesizer MUST emit ship_decision: next_brief regardless of the shocked_meter_avg. A blocking finding from one panel is not outweighed by three panels rating the artifact 9/10.
• Single-writer interlock. Only the orchestrator writes to the PR: exactly one add-comment call and one remove-labels call. The remove-labels call sweeps spec-review (trigger idempotency). NO add-labels call -- there are no verdict labels. Panelist subagents and the synthesizer subagent return JSON only and MUST NOT call any gh write command, post comments, apply labels, or touch PR state.
• Single-emission discipline. Exactly one comment per panel run, rendered from assets/comment-template.md after all subagents return and the linter checklist runs.
• ASCII-only artifact. Every byte the skill writes (the comment, the synthesizer prose, any rendered fold instruction) MUST be within printable ASCII (U+0020 - U+007E). The skill inherits the repo encoding rule from .github/instructions/encoding.instructions.md (if present) and additionally enforces it on the spec artifact via linter check 1.
• No-vendor-foundation language ban. The spec artifact MUST NOT contain "CNCF", "Linux Foundation", "Sandbox", "Incubation", "W3C Process", or "IETF RFC stream". The persona prompts MAY reference these as pedigree (a panelist's credibility comes from having edited OpenAPI; that does not put OpenAPI's foundation affiliation in the spec text). Linter check 2 greps the artifact for the forbidden token list AFTER any fold.