oa-quality-guardians

name: oa-quality-guardians user-invocable: false description: "Automatically update core documentation after agent work completes. Use when Claude needs to spawn guardian agents to update LESSONS.md, ROADMAP.md, or DECISIONS.md after a batch or session. Activates for: batch done, session end, guardian, update docs, lessons learned."

oa-quality-guardians

Quick Reference

Critical Rules

Spawn guardians after a successful batch or session — never before output is validated — because guardians read agent outputs and premature spawning captures incomplete state.

Use APPEND semantics when guardians update docs because guardians add to existing docs and overwriting them would destroy accumulated knowledge from previous sessions.

Delegate LESSONS.md, ROADMAP.md, and DECISIONS.md updates to guardian agents rather than editing them directly because consistency in format and numbering requires reading the full existing file before appending.

Spawn a guardian when any significant task completes because knowledge accumulation is mandatory — skipping the guardian step means lessons are lost when the session ends.

When to Spawn Which Guardian

Guardian Agents

lessons-guardian

Trigger: session_end Target: LESSONS.md Model: claude/sonnet

Reads ~/.oa/session-log.json and adds new numbered lessons (L-NNN format). Never duplicates existing lessons.

roadmap-guardian

Trigger: batch_complete Target: docs/ROADMAP.md Model: claude/haiku

Scans recent agent outputs and marks completed ROADMAP checkboxes as [x].

handoff-guardian

Trigger: session_end Target: docs/HANDOFF-<YYYY-MM-DD>.md Model: claude/sonnet

Writes a handoff document for the next session: what was done, current status, next steps.

Essential Patterns

Pattern 1: Spawn All Guardians at Session End

# Spawn lessons guardian
oa run "Je bent een lessen-schrijver.
Lees ~/.oa/session-log.json en voeg nieuwe inzichten toe aan /mnt/c/Users/Freek Heijting/Documents/GitHub/Open-Agents/LESSONS.md.
Schrijf alleen lessen die nog NIET bestaan. Geen duplicaten.
Format: | L-NNN | **Kernles** — uitleg. | Context. |
Schrijf ./output/result.md met samenvatting en maak .done aan." \
  --name lessons-guardian --model claude/sonnet --direct

# Spawn roadmap guardian
oa run "Je bent een roadmap-updater.
Scan recente agent outputs in ~/.oa/ en update checkboxes in /mnt/c/Users/Freek Heijting/Documents/GitHub/Open-Agents/docs/ROADMAP.md.
Markeer ALLEEN voltooide items als [x]. Geen andere wijzigingen.
Schrijf ./output/result.md met samenvatting en maak .done aan." \
  --name roadmap-guardian --model claude/haiku --direct

# Spawn handoff guardian
oa run "Je bent een handoff-schrijver.
Schrijf een handoff document naar /mnt/c/Users/Freek Heijting/Documents/GitHub/Open-Agents/docs/HANDOFF-$(date +%Y-%m-%d).md
op basis van ~/.oa/session-log.json.
Beschrijf: wat is gedaan, huidige status, volgende stappen.
Schrijf ./output/result.md met samenvatting en maak .done aan." \
  --name handoff-guardian --model claude/sonnet --direct

Pattern 2: Spawn Single Guardian After Batch

Use this after any significant successful batch:

oa run "Je bent een lessen-schrijver.
## Context
Batch zojuist voltooid: <beschrijf wat er gedaan is>
Output locaties: <lijst van output bestanden>

## Taak
Lees de output bestanden en destilleer nieuwe lessen.
Voeg toe aan: /mnt/c/Users/Freek Heijting/Documents/GitHub/Open-Agents/LESSONS.md
Format: | L-NNN | **Kernles** — uitleg. | Context. |
Controleer bestaande nummering — begin bij het hoogste bestaande L-nummer + 1.

## Regels
- Alleen daadwerkelijk nieuwe inzichten toevoegen
- Nooit bestaande lessen verwijderen of wijzigen
- Geen duplicaten van bestaande lessen
Schrijf ./output/result.md met samenvatting en maak .done aan." \
  --name lessons-guardian --model claude/sonnet --direct

Pattern 3: Register Custom Guardian (Python API)

from open_agents.guardians import register_guardian

register_guardian("decisions-guardian", {
    "trigger": "session_end",
    "task": (
        "Je bent een beslissingen-schrijver. "
        "Lees ~/.oa/session-log.json en voeg nieuwe beslissingen toe aan "
        "/mnt/c/Users/Freek Heijting/Documents/GitHub/Open-Agents/docs/DECISIONS.md. "
        "Format: D-NNN | Datum | Beslissing | Rationale. "
        "Schrijf ./output/result.md met samenvatting en maak .done aan."
    ),
    "output": "/mnt/c/Users/Freek Heijting/Documents/GitHub/Open-Agents/docs/DECISIONS.md",
    "model": "claude/sonnet",
})

Pattern 4: Verify Guardian Completion

oa status | grep guardian
oa collect lessons-guardian
oa collect roadmap-guardian

Guardian Rules (from guardians.py)

Guardians are spawned via trigger_guardian(event_type) which calls oa run with --direct.

Reference

• Source: Open-Agents/oa-cli/src/open_agents/guardians.py — guardian registry and trigger logic
• Source: Open-Agents/CLAUDE.md Kerngedrag #8 "Guardian agents"
• Related: oa-quality-gates — run quality gates BEFORE spawning guardians
• Related: oa-agent-library-builder — save successful patterns as templates