proposal: auto-review primitive for skills

[JoshSalomon]

Summary

Adds a proposal for an opt-in auto-review mechanism as a new primitive for skills. Any skill can include a review.md alongside SKILL.md to enable automatic worker→reviewer→fix loops.

Key Design Points

• Opt-in: review.md alongside SKILL.md — no file means no review, current behavior preserved
• Any skill: works for planning skills (PRD, spec) and execution skills (implementation, CI fix)
• Separate reviewer agent: avoids confirmation bias — reviewer is a different agent than the worker
• Per-skill retry config: max_retries in review.md frontmatter, global default fallback
• File-based observability: container writes per-cycle JSON files, orchestrator polls for near-real-time Prometheus metrics and Jira comments

Maintainer Input Needed

The proposal presents two approaches for where the review loop lives:

• Approach A (recommended): Container-internal loop with file-based observability — fast to implement, good context preservation, near-real-time metrics/Jira via filesystem polling
• Approach B: Orchestrator-managed loop — full checkpoint persistence and human intervention mid-loop, but significantly more complex

See the comparison table in the proposal for the full tradeoff analysis.

Files Changed

• proposals/auto-review-primitive.md — full proposal
• proposals/README.md — index entry added

🤖 Generated with Claude Code