Advisory PostToolUse hook for automatic spec-reviewer invocation

[b-coman]

Context

The OBS-09 rule audit (#2) classifies some rules as "Case C" — prose-only but enforceable. Today, spec quality rules are enforced only by prose instructions inside agent definitions. There is no automatic gate between Phase 2 (spec-writer) and Phase 3 (ingestion). The user must manually invoke /ido4dev:decompose-validate.

The ido4shape plugin (upstream) uses a two-layer validation pattern that addresses this:

• Layer 1 — deterministic structural validation via dist/spec-validator.js (bundled parser)
• Layer 2 — qualitative LLM-based content validation via parallel reviewer agents

ido4dev already has both layers in pieces:

• Layer 1: ingest_spec dry-run mode (deterministic parser, already called in decompose-validate)
• Layer 2: agents/spec-reviewer.md (currently invoked inline during decompose-validate)

What's missing is automatic invocation — neither layer runs until the user manually starts Phase 3.

Proposal — Option A (advisory, extends existing pattern)

Add a PostToolUse hook entry to hooks/hooks.json that fires after Write/Edit when the file path matches technical spec patterns. The hook runs the existing spec-reviewer agent and surfaces the verdict as a governance signal.

Behavior

• Trigger: PostToolUse on Write or Edit where the file path matches **/specs/*technical*.md
• Action: Run spec-reviewer.md protocol on the written file
• Output: Governance signal with verdict (PASS / PASS WITH WARNINGS / FAIL) and key findings
• Does NOT block — consistent with current advisory-hook pattern in hooks/hooks.json
• If verdict is FAIL, the signal recommends the user run full /ido4dev:decompose-validate before proceeding

Why advisory (Option A) not blocking (Option B)

We already have an advisory PostToolUse hook for governance signals (lines 15-34 of hooks/hooks.json — fires after task state-transition tools). The new hook follows the same pattern. This means:

• Consistent with existing architecture — no new hook types
• User learns about quality issues without being blocked mid-session
• Can upgrade to blocking (Option B) later if advisory signals are routinely ignored

Architectural context

The current hook architecture:

hooks/hooks.json
  ├─ SessionStart: MCP server install (@ido4/mcp)
  └─ PostToolUse:
     ├─ matcher: task state-transition tools → advisory governance signal
     └─ NEW: matcher: Write/Edit to specs/*technical*.md → advisory spec-reviewer

The BRE (Business Rule Engine) is not involved here. BRE governs runtime state transitions on GitHub issues, not spec authoring. This hook lives in the spec-authoring layer, before ingestion. See investigation findings in #2 (OBS-09) for the architectural boundary.

ido4shape precedent

In ido4shape, Layer 2 runs four parallel reviewer agents (spec-reviewer, technical-reviewer, scope-reviewer, dependency-auditor), each with a distinct quality lens, producing a rollup verdict. For ido4dev Round 4, we start with one reviewer (the existing spec-reviewer.md) and can expand to parallel lenses later if needed.

The key architectural lesson from ido4shape: Layer 1 (deterministic parser) and Layer 2 (LLM reviewers) are separate tools invoked by a skill, not a single pass. If we adopt this for ido4dev, the hook invokes Layer 2 (spec-reviewer), while Layer 1 (ingest_spec dry-run) stays in decompose-validate where it currently lives.

Deliverables

• New entry in hooks/hooks.json — PostToolUse matcher for spec file writes
• Hook implementation (prompt-type hook or command-type hook running spec-reviewer)
• Test: write a technical spec, verify the advisory signal fires and shows verdict
• Documentation in CLAUDE.md or README noting the automatic review behavior

Acceptance criteria

• Hook fires only on technical spec file writes (not all .md files)
• Hook runs the existing spec-reviewer.md protocol — no new agent needed
• Verdict is surfaced as a user-visible governance signal
• Hook does NOT block the session (advisory only)
• Existing PostToolUse hooks (governance signals for task transitions) still work
• claude plugin validate . passes with the new hook entry

Open questions for investigation during implementation

• Should the hook fire on every write, or only on writes that happen outside of decompose-tasks skill context? (To avoid double-review when the spec-writer is still composing)
• Should the hook call ingest_spec dry-run as a quick Layer 1 check before invoking the full Layer 2 reviewer?
• What's the latency impact of an automatic reviewer on every spec write?

Dependencies

• Blocked by: OBS-09: Rule audit across agents and decompose skills #2 (OBS-09 audit — agent definitions should be stable before the hook references them)
• Independent of: OBS-06: Build unified decompose-refine skill (canvas mode + technical-spec mode) #5 (OBS-06 decompose-refine skill)

References

• hooks/hooks.json — current hook definitions (SessionStart + PostToolUse governance signals)
• agents/spec-reviewer.md — the reviewer agent this hook invokes
• skills/decompose-validate/SKILL.md — current manual invocation path
• Claude Code hooks reference — full hook taxonomy
• ido4shape two-layer pattern: ido4shape/skills/validate-spec/SKILL.md, ido4shape/skills/review-spec/SKILL.md

[b-coman]

Reframing from architecture research (2026-04-12)

The prompt strategy investigation found that this issue should be broader than originally scoped. Three changes:

1. Stop hooks for phase-completion validation (new, simpler than PostToolUse)

Anthropic's Stop hooks block Claude from completing until criteria are met. For each decompose phase skill, a Stop hook could verify the produced artifact meets structural requirements before the skill reports success. This is simpler than PostToolUse (fires once at completion, not on every write) and aligns with Anthropic's "start simple" principle.

Example: a Stop hook on decompose-tasks verifies the technical spec has the right number of ## Capability: sections and all task refs match [A-Z]{2,5}-\d{2,3}[A-Z]? before allowing the skill to complete.

Source: Claude Code Hooks docs — Stop hooks return {"decision": "block", "reason": "..."}.

2. Cascading failure prevention strengthens the rationale

Anthropic's multi-agent research paper warns: "Minor system failures can be catastrophic for agents in stateful long-running processes where one step failure can cause agents to explore entirely different trajectories."

Our pipeline is sequential and stateful — canvas → tech spec → GitHub issues. A malformed canvas cascades into a bad spec. Validation at phase boundaries (not just Phase 3) prevents error compounding.

This suggests lightweight validation after Phase 1 (canvas) too — not just after Phase 2 (technical spec). A Stop hook on decompose could verify capability count matches, required sections are present, and no sections are empty.

3. Revised scope proposal

Tier 1 (Round 4 — simple, high value):

• Stop hook on decompose-tasks — verify technical spec structural sanity at phase completion
• Stop hook on decompose — verify canvas structural sanity at phase completion

Tier 2 (Round 4 if time permits — the original proposal):

• PostToolUse hook on technical spec writes — advisory spec-reviewer invocation (the original issue scope)

Tier 3 (Round 5+ — evaluate after calibration):

• Skill-scoped hooks on decompose-refine for incremental validation during refinement loops
• PostToolUse hooks on canvas writes

The "start simple" principle suggests Tier 1 first. Stop hooks are simpler than PostToolUse, fire once per phase (not per write), and catch the highest-impact failures (malformed artifacts reaching the next phase).

Source: ~/dev-projects/ido4-suite/docs/prompt-strategy.md — "Skill architecture patterns" section.