claude-context-auto-handoff 1.0.2 → 1.0.4

package/.claude-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "claude-context-handoff",
-  "version": "1.0.0",
+  "version": "1.0.4",
   "description": "Automatically saves session context and generates handoff manifests before Claude compacts or stops.",
   "author": {
     "name": "Ethualo",

package/build/index.js

@@ -17,15 +17,15 @@ server.tool('generate_handoff_manifest', {
     failedApproaches: z.array(z.string()).optional().describe('Already-failed attempts. Format each: "Approach: X → Result: Y → Lesson: Z". Prevents repeating mistakes. Write in English.'),
     blockers: z.string().optional().describe('Unresolved errors or blockers. Write in English.'),
     modifiedFiles: z.array(z.string()).optional().describe('Changed files with delta notes. Format: "path/to/file: what changed" — NO code snippets, path+delta only.'),
-    implicitRules: z.array(z.string()).optional().describe('Tech stack, naming conventions, env vars, implicit project rules — anything not derivable from reading code. Write in English.')
-}, async ({ summary, nextSteps, taskDescription, currentStatus, keyDecisions, failedApproaches, blockers, modifiedFiles, implicitRules }) => {
+    implicitRules: z.array(z.string()).optional().describe('Tech stack, naming conventions, env vars, implicit project rules — anything not derivable from reading code. Write in English.'),
+    workingDirectory: z.string().optional().describe('Absolute path to the project root where handoff.md should be written. Required on Windows where process.cwd() may return System32.')
+}, async ({ summary, nextSteps, taskDescription, currentStatus, keyDecisions, failedApproaches, blockers, modifiedFiles, implicitRules, workingDirectory }) => {
     try {
-        const claudeDir = path.join(process.cwd(), '.claude');
+        const projectRoot = workingDirectory || process.env['CLAUDE_PROJECT_DIR'] || process.cwd();
+        const claudeDir = path.join(projectRoot, '.claude');
         const handoffsDir = path.join(claudeDir, 'handoffs');
-        if (!fs.existsSync(claudeDir))
-            fs.mkdirSync(claudeDir, { recursive: true });
-        if (!fs.existsSync(handoffsDir))
-            fs.mkdirSync(handoffsDir, { recursive: true });
+        fs.mkdirSync(claudeDir, { recursive: true });
+        fs.mkdirSync(handoffsDir, { recursive: true });
         const now = new Date();
         const displayTime = now.toLocaleString();
         const timestamp = now.toISOString().replace(/[:.]/g, '-');

package/hooks/hooks.json

@@ -5,7 +5,8 @@
         "hooks": [
           {
             "type": "prompt",
-            "prompt": "CRITICAL: Context compaction imminent. Call 'generate_handoff_manifest' NOW before compaction. Fill all fields: summary (full session recap), taskDescription (goal), currentStatus (done vs remaining), keyDecisions (architecture choices + why), failedApproaches (already-failed — do NOT retry), nextSteps (next session tasks), blockers (unresolved errors). Write ALL field values in English. Do NOT allow compaction without calling this tool."
+            "prompt": "Evaluate whether context compaction should proceed.\n\nContext: $ARGUMENTS\n\nRules:\n- If 'generate_handoff_manifest' has already been called in this session, respond: {\"ok\": true}\n- If the session has minimal context (just started, no significant work done), respond: {\"ok\": true}\n- If there is meaningful session context worth preserving (decisions, progress, failures) and 'generate_handoff_manifest' was NOT called yet, respond: {\"ok\": false, \"reason\": \"Context compaction imminent. Call 'generate_handoff_manifest' to preserve session state. Fill all fields: summary (full session recap), taskDescription (goal), currentStatus (done vs remaining), keyDecisions (architecture choices + why), failedApproaches (already-failed — do NOT retry), nextSteps (next session tasks), blockers (unresolved errors). Write ALL field values in English.\"}\n\nIMPORTANT: Respond ONLY with a single JSON object. No markdown formatting, no explanation, no code blocks.",
+            "timeout": 15
           }
         ]
       }
@@ -15,7 +16,8 @@
         "hooks": [
           {
             "type": "prompt",
-            "prompt": "If a work unit just completed (feature done, tests passed, commit made), call 'generate_handoff_manifest'. Fill taskDescription, keyDecisions, and failedApproaches so the next session has full context. Write ALL field values in English."
+            "prompt": "Evaluate whether Claude should stop working.\n\nContext: $ARGUMENTS\n\nRules:\n- If 'generate_handoff_manifest' has already been called in this session, respond: {\"ok\": true}\n- If no meaningful work was done (e.g., simple Q&A, clarification, no code changes), respond: {\"ok\": true}\n- If meaningful work was completed (code changes, feature implementation, bug fix, tests) but 'generate_handoff_manifest' was NOT called yet, respond: {\"ok\": false, \"reason\": \"A work unit was completed. Call 'generate_handoff_manifest' with taskDescription, keyDecisions, failedApproaches, and nextSteps so the next session has full context. Write ALL field values in English.\"}\n\nIMPORTANT: Respond ONLY with a single JSON object. No markdown formatting, no explanation, no code blocks.",
+            "timeout": 15
           }
         ]
       }
@@ -25,7 +27,8 @@
         "hooks": [
           {
             "type": "prompt",
-            "prompt": "On session start: if .claude/handoff.md exists, read it and briefly brief the user (in their language) on Task Description, Current Status, Key Decisions, Failed Approaches, Blockers, Next Steps. If absent, stay silent."
+            "prompt": "On session start: if .claude/handoff.md exists, read it and briefly brief the user (in their language) on Task Description, Current Status, Key Decisions, Failed Approaches, Blockers, Next Steps. If absent, stay silent.",
+            "timeout": 10
           }
         ]
       }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "claude-context-auto-handoff",
-  "version": "1.0.2",
+  "version": "1.0.4",
   "description": "A Claude Code plugin to automate session handoffs before context compaction.",
   "type": "module",
   "main": "build/index.js",
@@ -12,6 +12,7 @@
     "build",
     ".claude-plugin",
     "hooks",
+    "skills",
     "templates",
     "scripts",
     "README.md",

package/skills/handoff/SKILL.md

@@ -0,0 +1,37 @@
+---
+description: Save current session context to handoff file. Use when user runs /handoff or asks to save session state before ending.
+---
+
+Save session context to `.claude/handoff.md` and timestamped archive to `.claude/handoffs/`.
+
+## Content Generation Rules (STRICT)
+
+Write all field values using telegraphese — drop articles, pronouns, polite words. Maximize density.
+
+- **NO code snippets** in any field. Reference file paths + line-level delta notes only.
+- **WHY over WHAT**: Every decision/status must state the reason, not just the action.
+- **failedApproaches**: Format each entry as `"Approach: X → Result: Y → Lesson: Z"`. This prevents the next session from repeating mistakes.
+- **taskDescription**: Include both Goal and Core Intent (why this matters to the project).
+- **implicitRules**: Capture tech stack, naming conventions, env vars — anything not derivable from reading the code.
+
+## Steps
+
+1. Gather from current session:
+   - taskDescription: final goal + core intent (why)
+   - summary: terse session recap (telegraphese)
+   - currentStatus: done vs remaining
+   - keyDecisions: architecture choices + why (prevents post-compaction amnesia)
+   - failedApproaches: already-failed attempts in `Approach→Result→Lesson` format
+   - blockers: unresolved errors
+   - modifiedFiles: changed files with delta notes (no code, path + what changed)
+   - implicitRules: stack, conventions, env vars
+
+2. Call `generate_handoff_manifest`:
+   - `summary`, `nextSteps` — required
+   - `taskDescription`, `currentStatus`, `keyDecisions`, `failedApproaches`, `modifiedFiles`, `implicitRules` — recommended
+   - `blockers` — optional
+
+3. Confirm to user:
+   - Latest: `.claude/handoff.md`
+   - Archive: `.claude/handoffs/handoff-{timestamp}.md`
+   - Next session: run `/resume` or SessionStart hook auto-restores

package/skills/resume/SKILL.md

@@ -0,0 +1,16 @@
+---
+description: Restore previous session context from handoff file. Use when user runs /resume or asks to continue from last session.
+---
+
+Reads `.claude/handoff.md`. Falls back to latest file in `.claude/handoffs/`.
+
+## Steps
+
+1. Read `.claude/handoff.md`
+2. If missing, find latest `handoff-*.md` in `.claude/handoffs/`
+3. If neither found: tell user "No handoff file. Run /handoff first."
+4. If found:
+   - Parse: Task Description, Current Status, Key Decisions, Failed Approaches, Blockers, Next Steps
+   - Brief user in their language
+   - Never retry Failed Approaches
+   - Start from first Next Step immediately