Skip to content

Refactor: move lifecycle enforcement into PreToolUse hooks (roadmap §3) #48

@ramdhanyk

Description

@ramdhanyk

Summary

Move AADM's lifecycle-stage enforcement (test-marker checks, sprint-lock checks, next-sprint-directory bans) out of individual skill files and into PreToolUse hooks, in the same architectural shape as tooling/scripts/sprint_gate.py.

This is queued as §3 of docs/roadmap/extension-framework.md and is independently valuable — it ships regardless of whether the extension framework itself (§2 of that roadmap) is ever built.

Why now (not waiting for §4 graduation)

§3 hardens AADM against two scenarios that exist in today's runtime, not just in a future plugin world:

  1. Agent-driven raw Edit / Write calls that bypass slash-command skills entirely. Current skill-embedded lifecycle checks don't fire because no skill was invoked.
  2. Any future or third-party skill that does similar work to a native AADM skill but doesn't carry the check (e.g., an engineering/write-impl from a third-party bundle bypassing /dev-test/dev-impl marker discipline).

Case (1) alone justifies the refactor. Case (2) is a bonus that unlocks the extension-framework roadmap later.

Scope

  • Design doc (prerequisite): new file under method/ with stable IDs for each lifecycle gate, migration plan skill-by-skill, test strategy.
  • Implementation: one hook per lifecycle gate, migration of check logic from each affected skill, Category E architecture-guard tests proving native skills and raw Edit calls are gated identically.
  • Backward compatibility: skill files retain their in-prompt checks during migration — hooks become source of truth, skill checks become redundant-but-harmless. Remove skill-level checks only after hook coverage is proven equivalent.

Estimated: ~6–10 sprint tasks. Risk: low (generalizes a pattern that's already shipped in sprint_gate.py).

Not doing in this issue

  • Any of §2 (the third-party skill extension framework itself) — those items are gated on the §4 graduation signal in the roadmap doc and should not be picked up alongside §3.
  • Marketplace / registry / plugin SDK work — out of scope per §5 non-goals.

Entry criteria

  • Control Tower webapp has reached Stage 0 usable state (so we're not context-switching across two architectural initiatives).
  • No active client-engagement sprint is in /dev-impl phase that would be disrupted by the refactor.

Exit criteria

  • All AADM-native lifecycle skills have their checks migrated to hooks.
  • Category E tests prove hook-gated enforcement is at least as strict as the prior skill-embedded checks.
  • tooling/README.md and handbook/Developer_Handbook.md updated to describe the new enforcement shape.
  • Method doc (method/AI_Assisted_Development_Method_v3_2_1.md) reflects the hook-based enforcement surface.

References

  • Roadmap doc: docs/roadmap/extension-framework.md (§3 is the full rationale; §4 is the graduation signal for the parent framework)
  • Shape to follow: tooling/scripts/sprint_gate.py
  • Migration source: tooling/scripts/dev_session.py (test-marker mechanism)

Metadata

Metadata

Assignees

No one assigned

    Labels

    No labels
    No labels

    Type

    No type
    No fields configured for issues without a type.

    Projects

    No projects

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions