watzup

Codex compatibility note:

• Invoke $skill-name: load the registered .agents/skills/<name>/SKILL.md and execute it with Codex tools; no separate Skill tool or Claude mode switch is needed. Author .claude/**; mirrors are generated.
• Track steps before execution and keep progress/evidence current. Explicit skill requests execute their protocol. Use the native question tool for required questions.
• Map foreign tool names to available host capabilities. A name mismatch needs no approval; an actually unavailable required capability stops with its step/evidence and a user question before adaptation.
• Subagent authorization: when a skill is user-invoked or AI-detected and its protocol requires subagents, that skill activation authorizes use of the required spawn_agent subagent(s) for that task.
• Preserve protocol order unless the user approves a deviation. Workflows use $start-workflow: gates stay fixed; other steps may flex with logged reasons and evidence.

[BLOCKING] Execute skill steps in declared order. NEVER skip, reorder, or merge steps without explicit user approval. Inside a workflow run, $start-workflow → Workflow-step mode bounds this rule. [BLOCKING] Before each step or sub-skill call, update todo tracking: set in_progress when step starts, set completed when step ends. [BLOCKING] Every completed/skipped step MUST include brief evidence or explicit skip reason. [BLOCKING] If Task tools are unavailable, create and maintain an equivalent step-by-step plan tracker with the same status transitions.

Quick Summary

Goal: Hand the developer an evidence-backed wrap-up of the session — a Session summary first (Done · Key changes · Why · How it works), then the detail, doc/spec staleness flags and root-cause lessons — delivered as a self-contained HTML report opened for them, WITHOUT changing any repository file, so they understand the work and decide the next step from full context.

Summary:

• READ-ONLY contract — review, summarize and FLAG only; NEVER edit, fix, implement, or update the docs or specs you flag. The only write is the git-ignored session report — why: watzup is a handoff, not an edit pass.
• Scope is the session, not only recent commits: uncommitted working-tree changes plus the commits made in this session, bounded by the session's task list, plan and prompt ledger when present — why: most session work is still uncommitted at wrap-up.
• Main steps in order: (1) Scope the session's work; (2) Session summary — Done, Key changes, Why, How it works, then the detail; (3) Doc-staleness gate; (4) Spec-driven health check (business code only); (5) Root-cause lesson extraction; (6) HTML session report, auto-opened; (7) ask user question tool Next Steps.
• HTML report: the four parts plus Flags and Next steps go into tmp/reports/watzup-{YYMMDD}-{HHmm}-{slug}.html, built from references/session-report-template.html and opened with node .claude/scripts/open-report.cjs <path>; chat gets a short summary plus the path — why: the reader should come away understanding what was done, why and how it works, not skimming a chat scroll.
• Proportion rule: the session summary and lesson gate always run. When no code changed (research, diagram or docs-only runs), the doc-staleness and spec-health gates record skipped — no code changed with evidence. The wrap-up never adds a second comprehension workflow — why: the four-part summary and report already own the handoff.
• Lessons go to $learn ONLY after user confirmation; surface-level "always check file X" notes are noise, not lessons.

Workflow:

1. Scope — Collect the session's work: git status and git diff / git diff --staged for uncommitted changes, plus commits made in this session (git log from the session's base commit, taken from the task list, plan or ledger when present). Read the task list, plan and prompt ledger (tmp/prompt-ledger/<session>/ledger.md) when present. State the boundary used and whether any code changed.
2. Session summary — Write the four labelled parts first (see Session Summary), then the detail: what was modified, added or removed, and the impact and quality of the change.
3. Doc Check — Cross-reference changed paths against docs for staleness, or record skipped — no code changed with evidence.
4. Spec Health — Run when business code changed; otherwise record skipped — no code changed (or no business code changed) with evidence.
5. Lesson Learned — Analyze AI mistakes/issues during the session and capture lessons.
6. Session Report — Write the HTML report and open it (see Session Report (HTML)); post a short chat summary plus the report path.
7. Next Steps — ask user question tool (see Next Steps).