diff --git a/src/cli/init.ts b/src/cli/init.ts index 0414bb7..a9cdc02 100644 --- a/src/cli/init.ts +++ b/src/cli/init.ts @@ -36,6 +36,7 @@ const CREATE_IF_MISSING = [ "cerebrum.md", "memory.md", "anatomy.md", + "STATUS.md", "token-ledger.json", "buglog.json", "cron-manifest.json", @@ -155,6 +156,7 @@ export async function initCommand(): Promise { createdCount++; } + const newlyCreated = new Set(); for (const file of CREATE_IF_MISSING) { const destPath = path.join(wolfDir, file); if (fs.existsSync(destPath)) { @@ -162,6 +164,7 @@ export async function initCommand(): Promise { } else { writeTemplateFile(actualTemplatesDir, wolfDir, file); createdCount++; + newlyCreated.add(file); } } @@ -171,6 +174,11 @@ export async function initCommand(): Promise { seedIdentity(wolfDir, projectRoot); } + // --- STATUS.md: substitute {{PROJECT_NAME}} / {{DATE}} when freshly created --- + if (newlyCreated.has("STATUS.md")) { + seedStatus(wolfDir, projectRoot); + } + // --- Token ledger: set created_at only if empty --- const ledgerPath = path.join(wolfDir, "token-ledger.json"); const ledger = readJSON>(ledgerPath, {}); @@ -324,7 +332,7 @@ function readTemplateContent(filename: string, templatesDir: string): string { function getEmbeddedTemplate(filename: string): string { const templates: Record = { "claude-md-snippet.md": `# OpenWolf\n\n@.wolf/OPENWOLF.md\n\nThis project uses OpenWolf for context management. Read and follow .wolf/OPENWOLF.md every session. Check .wolf/cerebrum.md before generating code. Check .wolf/anatomy.md before reading files.`, - "claude-rules-openwolf.md": `---\ndescription: OpenWolf protocol enforcement — active on all files\nglobs: **/*\n---\n\n- Check .wolf/anatomy.md before reading any project file\n- Check .wolf/cerebrum.md Do-Not-Repeat list before generating code\n- After writing or editing files, update .wolf/anatomy.md and append to .wolf/memory.md\n- After receiving a user correction, update .wolf/cerebrum.md immediately (Preferences, Learnings, or Do-Not-Repeat)\n- LEARN from every interaction: if you discover a convention, user preference, or project pattern, add it to .wolf/cerebrum.md. Low threshold — when in doubt, log it.\n- BEFORE fixing any bug or error: read .wolf/buglog.json for known fixes\n- AFTER fixing any bug, error, failed test, failed build, or user-reported problem: ALWAYS log to .wolf/buglog.json with error_message, root_cause, fix, and tags\n- If you edit a file more than twice in a session, that likely indicates a bug — log it to .wolf/buglog.json\n- When the user asks to check/evaluate UI design: run \`openwolf designqc\` to capture screenshots, then read them from .wolf/designqc-captures/\n- When the user asks to change/pick/migrate UI framework: read .wolf/reframe-frameworks.md, ask decision questions, recommend a framework, then execute with the framework's prompt`, + "claude-rules-openwolf.md": `---\ndescription: OpenWolf protocol enforcement — active on all files\nglobs: **/*\n---\n\n- Read .wolf/STATUS.md FIRST when resuming a session — it contains current quest, next steps, decisions\n- Update .wolf/STATUS.md (✅ done / 🚀 next quest) when a quest finishes or before suggesting /clear\n- Check .wolf/anatomy.md before reading any project file\n- Check .wolf/cerebrum.md Do-Not-Repeat list before generating code\n- After writing or editing files, update .wolf/anatomy.md and append to .wolf/memory.md\n- After receiving a user correction, update .wolf/cerebrum.md immediately (Preferences, Learnings, or Do-Not-Repeat)\n- LEARN from every interaction: if you discover a convention, user preference, or project pattern, add it to .wolf/cerebrum.md. Low threshold — when in doubt, log it.\n- BEFORE fixing any bug or error: read .wolf/buglog.json for known fixes\n- AFTER fixing any bug, error, failed test, failed build, or user-reported problem: ALWAYS log to .wolf/buglog.json with error_message, root_cause, fix, and tags\n- If you edit a file more than twice in a session, that likely indicates a bug — log it to .wolf/buglog.json\n- When the user asks to check/evaluate UI design: run \`openwolf designqc\` to capture screenshots, then read them from .wolf/designqc-captures/\n- When the user asks to change/pick/migrate UI framework: read .wolf/reframe-frameworks.md, ask decision questions, recommend a framework, then execute with the framework's prompt`, }; return templates[filename] ?? ""; } @@ -336,6 +344,7 @@ function generateTemplate(destPath: string, file: string): void { "cerebrum.md": `# Cerebrum\n\n> OpenWolf's learning memory.\n\n## User Preferences\n\n## Key Learnings\n\n## Do-Not-Repeat\n\n## Decision Log\n`, "memory.md": `# Memory\n\n> Chronological action log.\n`, "anatomy.md": `# anatomy.md\n\n> Project structure index. Pending initial scan.\n`, + "STATUS.md": `# STATUS\n\n> Single source of truth for resuming work. Read this FIRST when starting a session.\n> Update at the end of every quest so the next \`/clear\` resumes in 1 read.\n\n---\n\n## ✅ Concluído\n\n- (nothing yet — fill in as quests complete)\n\n---\n\n## 🚀 Próxima fase\n\n**Objetivo:** __\n\n### Critérios de aceitação\n1. __\n\n### Arquivos a criar / editar\n- __\n\n### Decisões pendentes\n- __\n\n---\n\n## 📁 Arquitetura ativa\n\n- **Stack:** __\n\n---\n\n## 🔧 Comandos úteis\n\n\`\`\`bash\n# add the most-used commands here\n\`\`\`\n`, "config.json": JSON.stringify({ version: 1, openwolf: { @@ -390,6 +399,19 @@ function seedCerebrum(wolfDir: string, projectRoot: string): void { writeText(cerebrumPath, cerebrum); } +function seedStatus(wolfDir: string, projectRoot: string): void { + const statusPath = path.join(wolfDir, "STATUS.md"); + if (!fs.existsSync(statusPath)) return; + + const projectName = detectProjectName(projectRoot) || path.basename(projectRoot); + const date = new Date().toISOString().slice(0, 10); + + let content = readText(statusPath); + content = content.replace(/\{\{PROJECT_NAME\}\}/g, projectName); + content = content.replace(/\{\{DATE\}\}/g, date); + writeText(statusPath, content); +} + function seedIdentity(wolfDir: string, projectRoot: string): void { const projectName = detectProjectName(projectRoot); if (!projectName) return; diff --git a/src/hooks/stop.ts b/src/hooks/stop.ts index 34ac845..7c1aae2 100644 --- a/src/hooks/stop.ts +++ b/src/hooks/stop.ts @@ -86,6 +86,9 @@ async function main(): Promise { // Check if cerebrum was updated this session (it should be if there were edits) checkCerebrumFreshness(wolfDir, session); + // Check if STATUS.md is stale relative to this session + checkStatusFreshness(wolfDir, session); + // Build session entry for ledger const reads = Object.entries(session.files_read).map(([file, data]) => ({ file, @@ -202,6 +205,37 @@ function checkForMissingBugLogs(wolfDir: string, session: SessionData): void { } } +/** + * Check if STATUS.md is older than the session start AND there was meaningful + * code activity (3+ writes outside .wolf/). If so, nudge Claude to update + * STATUS.md so the next /clear has fresh handoff context. + */ +function checkStatusFreshness(wolfDir: string, session: SessionData): void { + const statusPath = path.join(wolfDir, "STATUS.md"); + const codeWrites = session.files_written.filter( + (w) => !w.file.includes("/.wolf/") && !w.file.endsWith(".tmp") + ); + + try { + const stat = fs.statSync(statusPath); + const sessionStartMs = session.started ? Date.parse(session.started) : 0; + if (!sessionStartMs) return; + + if (codeWrites.length >= 3 && stat.mtimeMs < sessionStartMs) { + process.stderr.write( + `📌 OpenWolf: STATUS.md not updated this session despite ${codeWrites.length} code writes. Update .wolf/STATUS.md (✅ done / 🚀 next quest) before /clear so next session resumes in 1 read.\n` + ); + } + } catch { + // STATUS.md doesn't exist — nudge to create it if there were code writes + if (codeWrites.length >= 3) { + process.stderr.write( + `📌 OpenWolf: .wolf/STATUS.md missing. Create it with current quest summary + next steps so /clear stays cheap.\n` + ); + } + } +} + /** * Check if cerebrum.md was updated recently. If it hasn't been updated in * a while and there was significant activity, emit a gentle reminder. diff --git a/src/templates/OPENWOLF.md b/src/templates/OPENWOLF.md index aae2a47..61f9528 100644 --- a/src/templates/OPENWOLF.md +++ b/src/templates/OPENWOLF.md @@ -2,6 +2,27 @@ You are working in an OpenWolf-managed project. These rules apply every turn. +## STATUS.md — Single Source of Truth (READ FIRST) + +`.wolf/STATUS.md` is the **first file** you read when resuming a session. It contains: +- ✅ What is concluded (current quest finished) +- 🚀 Next quest (objective, files to create, decisions fixed/pending) +- 📁 Active architecture (stack, tables, patterns) +- ⚠️ External pendencies +- 🔧 Useful commands + +**At session start:** read `.wolf/STATUS.md` first. It replaces re-reading memory.md, plans, and code to reconstruct context. + +**MANDATORY — keep STATUS.md fresh:** +1. When the user signals a quest is done ("done", "complete", "ship it", "next phase", "/clear", "wrap up"): + - Move just-finished items from `🚀 Próxima fase` → `✅ Concluído`. + - Replace `🚀 Próxima fase` with the next planned quest (objective, files, decisions). + - Bump "Last updated" date. +2. After applying a migration, scaffolding a feature, or finishing a multi-file task: update STATUS.md before responding "done". +3. Before suggesting `/clear` to the user, ensure STATUS.md reflects the current state. + +**The bar is HIGH for STATUS.md.** Stale STATUS.md = wasted next session. Always treat it as the handoff document. + ## File Navigation 1. Check `.wolf/anatomy.md` BEFORE reading any file. It has a 2-3 line description and token estimate for every file in the project. @@ -131,5 +152,6 @@ When the user asks to change, pick, migrate, or "reframe" their project's UI fra Before ending or when asked to wrap up: -1. Write a session summary to `.wolf/memory.md`. -2. Review the session: did you learn anything? Did the user correct you? Did you fix a bug? If yes, update `.wolf/cerebrum.md` and/or `.wolf/buglog.json`. +1. **Update `.wolf/STATUS.md`** — move concluded work to ✅, write next quest in 🚀, bump date. This is the most important step for next session efficiency. +2. Write a session summary to `.wolf/memory.md`. +3. Review the session: did you learn anything? Did the user correct you? Did you fix a bug? If yes, update `.wolf/cerebrum.md` and/or `.wolf/buglog.json`. diff --git a/src/templates/STATUS.md b/src/templates/STATUS.md new file mode 100644 index 0000000..78ddbe4 --- /dev/null +++ b/src/templates/STATUS.md @@ -0,0 +1,64 @@ +# STATUS — {{PROJECT_NAME}} + +> Single source of truth for resuming work. Read this FIRST when starting a session. +> Update this file at the end of every quest so the next `/clear` resumes in 1 read. +> Last updated: {{DATE}} + +--- + +## ✅ Concluído + + + +- (nothing yet — fill in as quests complete) + +--- + +## 🚀 Próxima fase + +**Objetivo:** __ + +### Critérios de aceitação +1. __ +2. _<...>_ + +### Arquivos a criar / editar +| Tipo | Arquivo | Conteúdo | +|---|---|---| +| novo | `path/to/file.ts` | _what it does_ | + +### Decisões fechadas +- __ + +### Decisões pendentes +- __ + +--- + +## 📁 Arquitetura ativa + +- **Stack:** __ +- **Tabelas / módulos chave:** __ +- **Padrões:** __ + +--- + +## ⚠️ Pendências externas (não bloqueia coding) + +- __ + +--- + +## 🔧 Comandos úteis + +```bash +# add the most-used commands here so the next session has them ready +``` + +--- + +## 📚 Referências (leia SE precisar) + +- `.wolf/cerebrum.md` — User Preferences + Do-Not-Repeat + Decision Log +- `.wolf/anatomy.md` — token-efficient file index +- `.wolf/buglog.json` — known bugs + fixes diff --git a/src/templates/claude-rules-openwolf.md b/src/templates/claude-rules-openwolf.md index 9785410..de3eb07 100644 --- a/src/templates/claude-rules-openwolf.md +++ b/src/templates/claude-rules-openwolf.md @@ -3,6 +3,8 @@ description: OpenWolf protocol enforcement — active on all files globs: **/* --- +- Read .wolf/STATUS.md FIRST when resuming a session — it contains current quest, next steps, decisions +- Update .wolf/STATUS.md (✅ done / 🚀 next quest) when a quest finishes or before suggesting /clear - Check .wolf/anatomy.md before reading any project file - Check .wolf/cerebrum.md Do-Not-Repeat list before generating code - After writing or editing files, update .wolf/anatomy.md and append to .wolf/memory.md