feat: spec-aware review, in-PR plan archival, and artefact prose economy

[sebastian-iancu]

Three workflow improvements for agent-to-agent SDD, plus a small agent-doc cleanup.

Changes

• Artefact prose economy (references/artefact-prose.md) — one home per fact for commit body / PR body / changelog / review comments; cite identifiers rather than restating. Wired into the spec-driven-development router, methodology §11, the Cursor rule, and the scaffold templates so consuming repos inherit it.
• In-PR plan archival — sdd-archive now closes out the plan as the final commit of the implementing branch (same PR), not a follow-up. Methodology §9 Definition of Done and the process templates updated to match.
• Spec-aware review — new read-only sdd-spec-conformance-reviewer agent (judges code against the SPEC §/REQ acceptance criteria it cites, clause by clause) and the opt-in /sdd-review skill (dispatches the installed generic reviewers + the SDD agents, consolidates, and optionally posts findings to the PR). Delegates generic review and posting; doesn't reimplement them.
• Agent descriptions — modernized sdd-doc-reviewer / sdd-traceability-auditor to the prose-summary form (earlier commit on this branch).

Surface synced across AGENTS.md, README.md, docs/, the session hook, and the Cursor rule (Skills 6 / Agents 3).

Validation

Both ./scripts/validate.sh and claude plugin validate . pass.

🤖 Generated with Claude Code

[sebastian-iancu]

PR Review Summary

Reviewed via comprehensive diff analysis (feat/improvements → main, 17 files, +224/−37). ./scripts/validate.sh passes.

Overall: Solid PR — clean superpowers boundaries, well-formed new components, and consistent in-PR archive propagation. Fix the plan-template DoD contradiction before merge; address the Important items below for a clean release.

---

Critical (1)

plan.md DoD contradicts methodology §9

This PR updates methodology §9 and several templates for same-PR, on-branch close-out, but references/templates/plan.md still says Code + tests merged. Scaffolded repos will emit a DoD that conflicts with the canonical §9 wording ("complete and verified on the branch" + archive in the implementing PR).

Fix: Update references/templates/plan.md DoD to match development-process.md and methodology §9.

---

Important (5)

1. Stale combined-flow one-liners (3 surfaces) — sdd-with-superpowers.md was updated for optional sdd-review and in-PR archive, but AGENTS.md, README.md, and skills/spec-driven-development/SKILL.md still show the old short flow. Align with the reference diagram, e.g.:

   … → sdd-trace · sdd-review (opt-in) + verification-before-completion
      → sdd-archive (in the implementing PR) + finishing-a-development-branch
   

2. CHANGELOG Changed bullet describes work not in this PR — The agent-modernization bullet for sdd-doc-reviewer / sdd-traceability-auditor was already on main; only docs/authoring.md listing the new agent is new here. Reword or split so release notes match the diff.

3. sdd-review scope vs traceability auditor mismatch — Step 2 says the auditor covers "the touched chain", but sdd-traceability-auditor is designed for whole-tree audits and defers single-REQ work to sdd-trace. Either pass explicit scope in the Task prompt, use sdd-trace for scoped checks, or document that whole-tree is intentional for PR review.

4. sdd-archive settles lifecycle policy outside methodology — The skill introduces shipped in the same commit (de-emphasizing landed-then-shipped) and a follow-up-PR exception. Methodology §6 still treats landed and shipped as distinct; §9 says same-PR archive with no follow-up. Either amend §6/§9 or strip the policy from the skill and cite methodology only.

5. Methodology §9 DoD missing traceability checkbox — sdd-archive step 3 and development-process.md require traceability.yaml updated; methodology §9 checklist does not. Add it so §9 stays the canonical DoD list.

---

Suggestions (8)

#	Finding	Location
1	Gotcha still says "Both shipped agents" after adding a third	AGENTS.md:115
2	Plan-edit hook omits in-PR archive guidance	hooks/spec-edit-reminder.sh:36
3	ci.md scaffold template not updated for in-PR archive / optional review	references/templates/ci.md
4	GitHub issue templates missing sdd-review and sdd-spec-conformance-reviewer	.github/ISSUE_TEMPLATE/
5	sdd-archive frontmatter description omits in-PR default	skills/sdd-archive/SKILL.md:3
6	README Quick start skips optional /sdd-review and same-PR archive	README.md:87–92
7	sdd-doc-reviewer "Not for" list doesn't mention conformance agent	agents/sdd-doc-reviewer.md:9–10
8	Prose-economy rule copied in three scaffold templates — consider making development-process.md canonical and having AGENTS.md defer	templates

Release note: Manifests remain 0.2.1; this warrants a 0.3.0 minor bump at release.

---

Strengths

• Superpowers boundary is clean — sdd-review delegates generic review and PR posting; no competing generic review skill.
• New sdd-spec-conformance-reviewer agent is well-formed (prose-summary description, read-only tools:, clause-by-clause output, clear negations).
• artefact-prose.md is a strong addition — extends single-canonical-home to process prose without duplicating the full rule everywhere.
• In-PR archival is mostly consistent across methodology §9, sdd-archive, templates, session-start.sh, sdd-context.mdc, and docs/testing.md.
• Surface sync is thorough — counts (6 skills, 3 agents, 5 /sdd-* commands) match across updated surfaces.
• Public-safety holds.

---

Recommended action

1. Fix critical: update references/templates/plan.md DoD.
2. Fix important: sync flow one-liners, correct CHANGELOG, resolve auditor scope in sdd-review, reconcile landed/shipped/follow-up policy with methodology §6/§9, add traceability to §9 DoD.
3. Consider suggestions (especially AGENTS gotcha, spec-edit-reminder.sh, issue templates).
4. Re-run validation, then merge and tag 0.3.0.