Initial commit

2025-11-29 17:59:29 +08:00
commit 681c2e46c0
31 changed files with 6218 additions and 0 deletions
--- a/commands/save.md
+++ b/commands/save.md
@@ -0,0 +1,215 @@
+You are managing a session memory system. The user wants to manually save a snapshot of the current session state.
+
+**CRITICAL - Command Format:**
+All session plugin commands use the `/session:` prefix. DO NOT suggest commands without this prefix.
+- ✅ Correct: `/session:list`, `/session:start`, `/session:continue`, `/session:status`
+- ❌ Wrong: `/session list`, `/session start`, `/session continue`, `/session status`
+Use ONLY the exact command formats specified in this template.
+
+## Task: Save Session Snapshot
+
+Capture the current context and save it as a timestamped snapshot.
+
+**CRITICAL OPTIMIZATION:** This command now uses CLI for snapshot writes, enabling plan mode support.
+
+### Step 1: Validate Active Session
+
+1. Check if `.claude/sessions/.active-session` file exists
+2. If NOT exists, show error:
+   ```
+   ❌ Error: No active session
+   💡 Use /session:start [name] to create a new session
+   💡 Or use /session:continue [name] to resume an existing session
+   ```
+   Then STOP.
+3. Read the active session name from `.active-session`
+4. Verify the session directory `.claude/sessions/{active_session}/` exists
+5. If NOT exists, show error:
+   ```
+   ❌ Error: Active session directory not found
+   The session may have been deleted. Please start a new session.
+   ```
+   Then STOP.
+
+### Step 2: Capture Conversation Context
+
+Analyze the recent conversation (last 10-20 exchanges) and create a summary:
+- What topics were discussed
+- What problems were solved
+- What decisions were made
+- What tasks were attempted or completed
+
+Keep this summary concise but informative (3-5 sentences).
+
+### Step 3: Capture Completed Todos
+
+Look for any todos that were marked as completed in this conversation:
+- Check for completed checkboxes in messages
+- Check for explicit "completed" or "done" mentions
+- List them in checkbox format: `- [x] Task description`
+
+If no todos were completed, write: `- No todos completed in this segment`
+
+### Step 4: Capture Files Modified
+
+Identify all files that were modified in this conversation:
+- Files written with Write tool
+- Files edited with Edit tool
+- Files created or modified
+
+For each file, capture:
+- File path
+- Brief description of changes made (1-2 lines)
+
+Format:
+```markdown
+### path/to/file.ts
+- Added authentication middleware
+- Updated error handling
+```
+
+If no files were modified, write: `No files modified in this segment`
+
+### Step 5: Capture Current State
+
+Describe the current state of the work:
+- What's working now
+- What's in progress
+- What's blocked
+- What's next
+
+Format as bullet points (3-5 items).
+
+### Step 6: Capture Key Code Snippets (Optional)
+
+If any particularly important code was written or discussed, include a representative snippet:
+- Limit to 20-30 lines maximum
+- Include language identifier for syntax highlighting
+- Add brief explanation
+
+Only include if genuinely important. Skip if no critical code.
+
+### Step 7: Generate Snapshot Content
+
+Create the snapshot content in this structure (but DON'T write it yet):
+
+```markdown
+# Snapshot: {session_name}
+**Timestamp**: {full_timestamp_YYYY-MM-DD_HH:MM:SS}
+**Format Version**: 2.0
+
+## Topics Discussed
+1. **[Category]**: {topic_1_brief_description}
+2. **[Category]**: {topic_2_brief_description}
+{continue_for_all_topics}
+
+## Suggestions & Recommendations
+1. **[Category]**: {suggestion} - {rationale}
+{if_any_suggestions_given}
+
+## Decisions Made
+1. **[Decision]**: {rationale}
+{if_any_decisions_made}
+
+## Tasks Completed
+1. {completed_task_1}
+2. {completed_task_2}
+{or_write_"No_tasks_completed"}
+
+## Files Modified
+1. `{file_path}`: {what_changed_and_why}
+{or_write_"No_files_modified"}
+
+## Current Status
+- **Progress**: {where_things_stand}
+- **Next Steps**: {what_should_be_done_next}
+- **Blockers**: {issues_or_"None"}
+
+## Notes
+{any_additional_important_observations}
+```
+
+### Step 8: Write Snapshot via CLI (CRITICAL - Plan Mode Support)
+
+**Instead of using the Write tool**, use the CLI with stdin to write the snapshot.
+This enables snapshot saves even in plan mode where Write tool is blocked.
+
+Run this command, piping the snapshot content via stdin:
+
+```bash
+echo "{snapshot_content}" | node ${CLAUDE_PLUGIN_ROOT}/cli/session-cli.js write-snapshot {session_name} --stdin --type manual
+```
+
+**IMPORTANT:** Escape any special characters in the content appropriately for the shell.
+
+Alternative approach if echo has escaping issues:
+```bash
+cat <<'EOF' | node ${CLAUDE_PLUGIN_ROOT}/cli/session-cli.js write-snapshot {session_name} --stdin --type manual
+{snapshot_content}
+EOF
+```
+
+The CLI will:
+- Write the snapshot file with timestamp
+- Update the index automatically
+- Return success with filename
+
+### Step 9: Update context.md
+
+1. Read current `.claude/sessions/{active_session}/context.md`
+2. If any key decisions were made in this conversation, add them to "Key Decisions" section:
+   ```markdown
+   ### {current_timestamp}
+   - Decision: {what_was_decided}
+   - Rationale: {why_this_approach}
+   - Impact: {what_this_affects}
+   ```
+3. If any important discoveries were made, add to "Important Discoveries" section
+4. If any blockers were encountered or resolved, update "Blockers & Resolutions" section
+5. Update the "Summary" section with a running summary including this snapshot
+6. Write the updated context.md back (use Edit tool for this - it's allowed in plan mode for session files)
+
+### Step 10: Update session.md Timestamp
+
+1. Read `.claude/sessions/{active_session}/session.md`
+2. Update the "Last Updated" field to current timestamp
+3. If any new files were involved, add them to "Files Involved" section
+4. Write back the updated session.md (use Edit tool)
+
+### Step 11: Display Success Message
+
+Show confirmation:
+
+```
+✓ Session snapshot saved
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+📁 .claude/sessions/{session_name}/{timestamp}.md
+📝 Captured:
+   - Conversation summary
+   - {X} completed todos
+   - {Y} file changes
+   - Current state and next steps
+   {if_decisions: "- {Z} key decisions"}
+
+💾 Context updated in context.md
+⏰ Session timestamp updated
+```
+
+---
+
+**CRITICAL BENEFITS - PLAN MODE SUPPORT:**
+- **Problem:** In plan mode, Write tool is blocked (prevents accidental code changes)
+- **Impact:** Snapshots couldn't be saved, causing data loss on `/clear`
+- **Solution:** CLI delegation via Bash bypasses Write tool restrictions
+- **Result:** Zero data loss in plan mode, seamless user experience
+
+**PERFORMANCE BENEFITS:**
+- **Before:** 15-25K tokens for snapshot analysis and writes
+- **After:** 8-15K tokens, CLI handles write operations
+- **Improvement:** ~40-50% token reduction, instant index update
+
+**IMPORTANT NOTES:**
+- Use heredoc (cat <<'EOF') for reliable content piping, avoids escaping issues
+- CLI write-snapshot automatically updates index, no separate step needed
+- Edit tool can still be used for session.md and context.md (they're documentation, not code)
+- This approach works in BOTH normal mode and plan mode