Repository: rjmurillo/ai-agents
Author: rjmurillo
## Summary
Add lifecycle hook infrastructure (SessionStart, PreToolUse, PostToolUse, PreCompact, Stop) to automate quality gates and prevent recurring failure patterns documented in 80+ retrospectives.
## Motivation
**Retrospective analysis** shows 52/80 files cite hallucination/laziness/drift/false completion/premature merge. Root causes map to missing automation:
1. **95.8% context reading failure** — agents skip CLAUDE.md/AGENTS.md/HANDOFF.md before acting (#1672)
2. **44 mentions of false completion** — agents claim "done" without verification (#1673)
3. **Continuation reset after compaction** — plan position/TODO status lost (#1691)
4. **Inconsistent retro generation** — manual process, often skipped
**Hook automation** (inspired by [Claude Code harness setup](https://www.reddit.com/r/ClaudeAI/comments/1spehot/)) eliminates compliance drift by enforcing gates in the harness instead of relying on prompt instructions.
## Proposed Hooks (by ROI)
### 1. SessionStart (HIGHEST impact)
- **Auto-loads**: CLAUDE.md, AGENTS.md, HANDOFF.md, latest retro
- **Activates**: Serena MCP (strategic memory)
- **Logs**: Session init to audit trail
- **Fixes**: 95.8% context reading failure
### 2. PreToolUse (verification gate)
- **Blocks**: Completion claims ("done", "fixed") without prior verification
- **Checks**: Recent tool history for test/build runs
- **Fixes**: 44 false completion mentions
### 3. Stop (auto-retro)
- **Generates**: Retrospective on session end
- **Updates**: `docs/retros/INDEX.md`
- **Extracts**: Failure patterns for HexMachina crystallization
- **Fixes**: Inconsistent learning capture
### 4. PostToolUse (state persistence)
- **Saves**: Plan position, TODO status after edits/writes
- **Auto-verifies**: Syntax on code edits (`tsc --noEmit`)
- **Fixes**: Continuation reset after compaction
### 5. PreCompact (checkpoint)
- **Snapshots**: Work-in-progress state before context loss
- **Generates**: Mini-retro for resume context
- **Safety net**: Before compaction
## Implementation Plan
1. **Define hook interface** in `.agents/hooks/`
- `IHookContext` interface with tool history, state persistence, file loading
- Hook registration system
2. **Prototype SessionStart** in OpenClaw foundry extension
- Test on ai-agents repo
- Refine based on failure logs
3. **Port to ai-agents** once proven
4. **Add remaining hooks** (PreToolUse, Stop, PostToolUse, PreCompact)
5. **HexMachina integration** — hooks feed failure patterns to crystallization
## Acceptance Criteria
- [ ] Hook interface defined in `.agents/hooks/README.md`
- [ ] SessionStart hook implemented and tested
- [ ] PreToolUse verification gate blocks false completion
- [ ] Stop hook generates retros automatically
- [ ] Hook execution logged to audit trail
- [ ] Zero new context reading failures after SessionStart deployment
## References
- Issue #1672 (session-start gate)
- Issue #1691 (anti-drift protocol)
- Issue #1690 (failure modes doc)
- ADR-007 (memory-first architecture)
- [Claude Code Hook Automation](https://www.reddit.com/r/ClaudeAI/comments/1spehot/)
- Analysis: `/tmp/hook-analysis.md` (80 retrospectives, 52 failure pattern mentions)