refactor: rewrite piyaz skill as router and modernize agents

[FrkAk]

Summary

Task Reference: [PYZ-379]

Final tranche of the Claude 5 plugin modernization, stacked on #278. Rewrites the piyaz skill as a compact router over kind-split references, modernizes the seven legacy agents.

• skills/piyaz/SKILL.md rewritten as a ~1,500 word router: triggers, hard rules, a workflow index where every entry ends with a user-orientation cue, an escalation index, and a read-when table. Doctrine moved behind on-demand references.
• New reference files, each the sole owner of its kind: role.md (persona and voice), tools.md (tool catalog and costs), workflows.md (full workflow steps), specs/contracts.md (dual-audience formats for plans, execution records, decisions, notes, PR bodies, and phase-agent returns), specs/review.md (verdict schema, severity anchors, the five lenses, rework intake).
• artifacts.md, lifecycle.md, conventions.md, resilience.md slimmed; moved sections leave one-line redirects so existing section citations resolve.
• artifacts.md §5 granularity resized to the reviewable-PR bar: a task is one PR an agent can understand, research, clarify, and deliver (hours become the symptom, not the test); starting counts calibrate instead of flooring; decompose.md adds a visible-horizon rule and decompose-feature.md cites the same bar. A/B vs this tranche's plugin: mean delta -0.009 Opus / -0.018 Sonnet (CI spans zero on both), zero illegal transitions in 108 runs; a same-prompt decompose probe dropped from a 34-task to an 11-task graph.
• Seven agents (brainstorm, decompose, decompose-task, decompose-feature, manage, onboarding, review) rewritten to the composer-phase style: bodies cut 65% (21,664 to 7,597 words), descriptions at 279-299 chars use-case first, every gate and branch preserved, each closes by telling the user where things stand.
• lib/mcp/schemas.ts: piyaz_note description restructured critical-details-first and cut from 2,549 to 1,828 chars (under the 2KB truncation limit); piyaz_create description and three field descriptions swept from numeric prose caps to coverage recipes; the other seven descriptions already compliant.
• scripts/check-plugins.ts: sync-map entries for the five new reference files.

Plugin static totals for this tranche: 51,598 to 38,856 words (-24.7%); the always-loaded skill surface drops from ~6,900 to ~1,500 words.

Behavioral A/B against the tranche 2 plugin (15 scenarios, 51 runs per arm, paired scoring, two added artifact-quality judges): mean delta -0.007, 95% CI [-0.043, 0.031]; note-writing quality improved, zero illegal status transitions across the arm.

Type of change

• Bug fix
• New feature
• Refactor / cleanup
• Documentation

Testing

• Tested locally with bun run dev
• Linting passes (bun run lint)
• Typecheck passes (bun run typecheck)
• Workers smoke passes (bun run build:cf && bun run smoke:cf) — required when this PR touches app/api/**, middleware.ts, worker-cf.ts, or a .node.ts / .workers.ts pair

Notes for reviewer

bun run test passes (2,222 tests) with the schemas change. Brand plugin directories are intentionally untouched; #281 at the stack tail carries the generated sync, so check:plugins reports drift here and passes at the tip.

Docs impact

• MCP tool reference (piyaz_note description) and the skills/agents catalog regenerate via the Docs Sync workflow.

Compliance impact

• none