Skip to content

feat: add STATUS.md as session handoff document#40

Open
meketreve wants to merge 1 commit into
cytostack:mainfrom
meketreve:feat/status-md-handoff
Open

feat: add STATUS.md as session handoff document#40
meketreve wants to merge 1 commit into
cytostack:mainfrom
meketreve:feat/status-md-handoff

Conversation

@meketreve
Copy link
Copy Markdown

@meketreve meketreve commented May 11, 2026

Summary

Adds .wolf/STATUS.md as the single source of truth for resuming work across sessions. Reduces session-resume cost from ~6 file reads (memory.md + cerebrum.md + plan files + code) to a single read.

The pattern emerged from real use: at the end of a quest, the AI moves done items to ✅ and writes the next quest in 🚀. Next session: /clear + "read .wolf/STATUS.md" → context ready in ~2k tokens instead of ~10k.

Changes

File Change
src/templates/STATUS.md (new) Template with sections: ✅ Concluído, 🚀 Próxima fase, 📁 Arquitetura ativa, ⚠️ Pendências, 🔧 Comandos
src/templates/OPENWOLF.md New top-level "STATUS.md — Single Source of Truth" section (MANDATORY rules); Session End checklist now lists STATUS.md update first
src/templates/claude-rules-openwolf.md Two new rules: read STATUS.md first when resuming, update it when quest finishes or before /clear
src/cli/init.ts Register STATUS.md in CREATE_IF_MISSING + embedded fallback in generateTemplate()
src/hooks/stop.ts New checkStatusFreshness() — emits stderr nudge when 3+ code writes happen but STATUS.md mtime predates session.started (or when STATUS.md is missing)

Diffstat: 5 files changed, +127 −3.

Why

Existing files in .wolf/ capture history (memory.md), learnings (cerebrum.md), bugs (buglog.json), structure (anatomy.md). None of them answer the most-asked resume question: "where did we stop and what's next?" Today the user has to grep memory.md, hunt for plan files, and re-read code to reconstruct that.

STATUS.md is the missing handoff doc. It is short, structured, and trivially updated.

Behavior

  • Fresh init: STATUS.md is created from template (in CREATE_IF_MISSING, never overwritten on upgrade).
  • End of session with code writes but stale STATUS.md: stop.js emits a single-line stderr nudge so Claude updates it on the next turn. Same threshold as the existing buglog/cerebrum nudges (3+ writes).
  • Existing projects upgrading: STATUS.md created on next openwolf init or first session that triggers the nudge — no destructive action.

Test plan

  • Fresh openwolf init creates .wolf/STATUS.md from template
  • Re-run openwolf init (upgrade) does NOT overwrite an existing STATUS.md
  • Session with 3+ code writes outside .wolf/ and stale STATUS.md triggers the stderr nudge
  • Session with no code writes does NOT trigger the nudge
  • tsc and tsc -p tsconfig.hooks.json pass (verified locally — clean)

Notes

Real-world validation: this exact pattern (template + hook + protocol entry) was used in a project this week and dropped resume cost from ~10k tokens to ~2k. Copying the convention upstream so every OpenWolf project gets it by default.

Adds a `.wolf/STATUS.md` file that acts as the single source of truth for
resuming work across sessions. Reduces session-resume cost from ~6 file
reads (memory.md + cerebrum.md + plan files + code) to a single read.

Changes:
- New template `src/templates/STATUS.md` with sections for ✅ Concluído,
  🚀 Próxima fase, 📁 Arquitetura ativa, ⚠️ Pendências, 🔧 Comandos.
- `src/templates/OPENWOLF.md`: new "STATUS.md — Single Source of Truth"
  section at top + bumped step in Session End to update STATUS.md first.
- `src/templates/claude-rules-openwolf.md`: rules to read STATUS.md first
  and to update it when a quest finishes or before /clear.
- `src/cli/init.ts`: register STATUS.md in CREATE_IF_MISSING and add an
  embedded fallback in generateTemplate.
- `src/hooks/stop.ts`: new `checkStatusFreshness()` — emits a stderr
  reminder when 3+ code writes happen but STATUS.md mtime predates the
  session start (or when STATUS.md is missing entirely).

Result: at the end of a quest the AI moves done items to ✅ and writes
the next quest in 🚀, so /clear is cheap and resumes in 1 read.
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant