claude-autopm 3.1.1 → 3.2.0

package/autopm/.claude/rules/context-compaction.md

@@ -0,0 +1,334 @@
+# Context Compaction Rules - MANDATORY
+
+> **CRITICAL**: Apply these compaction strategies to prevent context window exhaustion during long sessions.
+
+## Core Principle
+
+**Context is a finite resource.** Every token matters. Compact aggressively, preserve strategically.
+
+## Automatic Compaction Triggers
+
+### Trigger 1: Tool Result Accumulation
+
+**When**: 10+ tool results in session
+
+**Action**: Summarize older tool results
+
+```markdown
+# BEFORE (consuming ~5000 tokens per result)
+Tool Result 1: [full 500-line file]
+Tool Result 2: [full 300-line file]
+...
+Tool Result 15: [full 200-line file]
+
+# AFTER (consuming ~200 tokens per summary)
+## Compacted Tool Results
+- config.json: DB settings (PostgreSQL:5432), API keys, feature flags
+- src/auth.js: Authentication module with login/logout/validateToken
+- package.json: Node 18, React 18, Express 4, Jest testing
+...
+```
+
+### Trigger 2: Code Block Proliferation
+
+**When**: Same file read 3+ times OR 10+ different files read
+
+**Action**: Consolidate to essential references
+
+```markdown
+# BEFORE
+[src/auth.js - first read - 200 lines]
+[src/auth.js - second read after edit - 205 lines]
+[src/auth.js - third read to verify - 205 lines]
+
+# AFTER
+## src/auth.js Summary
+- Purpose: User authentication with JWT
+- Key functions: login(email, password), validateToken(jwt), refreshToken()
+- Modified sections: lines 45-60 (added MFA check)
+- Current length: 205 lines
+- Last state: MFA integrated, tests passing
+```
+
+### Trigger 3: Thinking Block Growth
+
+**When**: Multiple extended reasoning chains completed
+
+**Action**: Compress to decisions and rationale
+
+```markdown
+# BEFORE
+<thinking>
+Let me analyze this step by step...
+First, I should consider option A because...
+Actually, option B might be better since...
+On further reflection, option A is correct because...
+[500+ tokens of reasoning]
+</thinking>
+
+# AFTER
+## Decision: Option A (Authentication Strategy)
+- Choice: JWT with refresh tokens
+- Rationale: Stateless architecture, better scalability
+- Rejected: Sessions (state management complexity)
+```
+
+### Trigger 4: Conversation Length
+
+**When**: 30+ messages in session
+
+**Action**: Summarize completed topics
+
+```markdown
+# BEFORE
+[Messages 1-15: Debugging authentication issue]
+[Messages 16-25: Implementing MFA]
+[Messages 26-35: Current work on dashboard]
+
+# AFTER
+## Session Summary (Messages 1-25)
+### Completed: Authentication Debugging
+- Issue: Token validation failing on refresh
+- Fix: Updated expiry check in validateToken()
+- PR: #123 merged
+
+### Completed: MFA Implementation
+- Added TOTP support
+- Backup codes generated
+- Tests: 15/15 passing
+
+## Active Context (Messages 26+)
+[Current dashboard implementation work...]
+```
+
+## Compaction Formats
+
+### Format 1: File Summary
+
+```markdown
+## File: [path]
+- Purpose: [one-line description]
+- Key exports: [list main functions/classes]
+- Dependencies: [external dependencies]
+- Modified: [what changed, if applicable]
+- State: [current state/version]
+```
+
+### Format 2: Search Results Summary
+
+```markdown
+## Search: [query]
+- Total matches: [count]
+- Key files: [most relevant files]
+- Pattern: [what the matches reveal]
+- Action needed: [what to do with this info]
+```
+
+### Format 3: Test Results Summary
+
+```markdown
+## Tests: [suite/file]
+- Status: [PASS/FAIL] ([passed]/[total])
+- Failures: [list failing tests if any]
+- Coverage: [percentage if available]
+- Action: [what to fix/investigate]
+```
+
+### Format 4: Decision Record
+
+```markdown
+## Decision: [title]
+- Choice: [what was decided]
+- Rationale: [why, in one sentence]
+- Rejected: [alternatives not chosen]
+- Impact: [what this affects]
+```
+
+## Preservation Rules
+
+### ALWAYS Preserve
+
+1. **Active Task Context**
+   - Current file being edited
+   - Unsaved changes
+   - Active error messages
+
+2. **Critical Decisions**
+   - Architectural choices
+   - Security configurations
+   - Breaking changes
+
+3. **Blocking Issues**
+   - Current errors
+   - Failing tests
+   - Unresolved dependencies
+
+4. **User Requirements**
+   - Original request
+   - Constraints specified
+   - Preferences stated
+
+### SAFE to Compact
+
+1. **Historical Tool Results**
+   - Files read 5+ messages ago
+   - Search results already acted upon
+   - Test results from passing suites
+
+2. **Superseded Information**
+   - Old file versions
+   - Rejected approaches
+   - Fixed bugs
+
+3. **Verbose Output**
+   - Full stack traces (keep summary)
+   - Build logs (keep errors only)
+   - Long lists (keep relevant items)
+
+4. **Exploratory Work**
+   - Hypothesis testing completed
+   - Alternative approaches evaluated
+   - Research phase findings
+
+## Implementation Patterns
+
+### Pattern 1: Progressive Summarization
+
+```markdown
+# Level 0: Full content (initial read)
+[Complete file: 500 lines]
+
+# Level 1: Key sections (after analysis)
+## Key Sections in config.json
+- Database config (lines 1-50)
+- API settings (lines 51-100)
+- Feature flags (lines 101-150)
+
+# Level 2: Actionable summary (after decision)
+config.json: Using PostgreSQL on 5432, rate limit 100/min, darkMode enabled
+```
+
+### Pattern 2: Rolling Window
+
+Keep last N items in full detail, summarize older:
+
+```markdown
+## Recent (full detail)
+- Tool Result 8: [full content]
+- Tool Result 9: [full content]
+- Tool Result 10: [full content]
+
+## Historical (summarized)
+- Results 1-7: config files read, auth system analyzed,
+  tests confirmed passing, dependencies validated
+```
+
+### Pattern 3: Topic-Based Grouping
+
+Group related items for efficient summarization:
+
+```markdown
+## Authentication Work (compacted)
+Files read: src/auth.js, src/middleware/auth.js, src/models/User.js
+Changes made: Added MFA support (auth.js:45-60)
+Tests: 15/15 passing
+Outcome: MFA feature complete
+
+## Database Work (compacted)
+Files read: src/db/connection.js, migrations/*.js
+Changes made: Added index on users.email
+Tests: 8/8 passing
+Outcome: Query performance improved 40%
+```
+
+## Enforcement
+
+### Self-Check Questions
+
+Before adding new content, ask:
+1. Is this information already in context (in another form)?
+2. Will this be needed after the current operation?
+3. Can this be summarized without losing actionable details?
+4. Does this duplicate information from another tool result?
+
+### Compaction Checklist
+
+When context feels heavy:
+- [ ] Summarize tool results older than 5 messages
+- [ ] Compress completed reasoning chains
+- [ ] Consolidate multiple reads of same file
+- [ ] Remove superseded information
+- [ ] Group related items into summaries
+
+### Warning Signs
+
+**Immediate Action Needed:**
+- Response times noticeably slower
+- "Context too long" errors
+- Repetitive information in context
+- Multiple versions of same file
+- 50+ messages without compaction
+
+## Integration with /clear
+
+### When to Compact vs Clear
+
+| Situation | Action |
+|-----------|--------|
+| Same task, growing context | Compact |
+| Task complete, starting new | /clear |
+| Context heavy but continuity needed | Compact + Checkpoint |
+| Unrelated topics mixing | /clear |
+| Long research session | Compact progressively |
+
+### Handoff Pattern
+
+Before `/clear`, create transfer summary:
+
+```markdown
+## Session Transfer Summary
+
+### Completed
+- [list completed items]
+
+### In Progress
+- [current state]
+
+### Preserved Context
+- [critical information for next session]
+
+### Next Steps
+- [what to do next]
+```
+
+## Metrics
+
+### Context Efficiency Score
+
+Calculate: (Useful tokens / Total tokens) × 100
+
+- **>80%**: Excellent - minimal waste
+- **60-80%**: Good - some optimization possible
+- **40-60%**: Fair - compaction recommended
+- **<40%**: Poor - immediate compaction needed
+
+### Token Budget Guidelines
+
+| Session Type | Recommended Budget |
+|--------------|-------------------|
+| Quick fix | <20k tokens |
+| Feature implementation | <50k tokens |
+| Complex debugging | <80k tokens |
+| Full project work | <100k tokens + checkpoints |
+
+## Summary
+
+**Golden Rules:**
+1. Compact early, compact often
+2. Preserve decisions, discard deliberation
+3. Summarize verbose output immediately
+4. Use progressive summarization
+5. Create checkpoints for long work
+6. /clear between unrelated tasks
+
+**Remember**: A well-compacted context leads to better responses, faster processing, and more productive sessions.

package/autopm/.claude/templates/memory/active-work.template.json

@@ -0,0 +1,15 @@
+{
+  "current_task": {
+    "id": "",
+    "title": "",
+    "branch": "",
+    "started": "",
+    "status": "pending"
+  },
+  "recent_changes": [],
+  "blockers": [],
+  "next_steps": [],
+  "context_notes": "",
+  "decisions_made": [],
+  "files_of_interest": []
+}

package/autopm/.claude/templates/memory/checkpoint.template.md

@@ -0,0 +1,58 @@
+# Checkpoint: {{FEATURE_NAME}}
+
+**Date**: {{TIMESTAMP}}
+**Session**: {{SESSION_NUMBER}}
+
+## Status Summary
+
+- **Overall Progress**: {{PERCENTAGE}}% complete
+- **Tests**: {{TESTS_PASSING}}/{{TESTS_TOTAL}} passing
+- **Branch**: {{BRANCH_NAME}}
+- **Last Commit**: {{COMMIT_HASH}}
+
+## Completed Items
+
+- [x] {{COMPLETED_ITEM_1}}
+- [x] {{COMPLETED_ITEM_2}}
+
+## In Progress
+
+- [ ] {{IN_PROGRESS_ITEM}} - {{CURRENT_STATE}}
+
+## Pending
+
+- [ ] {{PENDING_ITEM_1}}
+- [ ] {{PENDING_ITEM_2}}
+
+## Key Decisions Made
+
+| Decision | Choice | Rationale |
+|----------|--------|-----------|
+| {{DECISION_1}} | {{CHOICE_1}} | {{RATIONALE_1}} |
+
+## Critical Context
+
+- {{CRITICAL_INFO_1}}
+- {{CRITICAL_INFO_2}}
+
+## Files Modified This Session
+
+- `{{FILE_1}}` - {{CHANGE_DESCRIPTION_1}}
+- `{{FILE_2}}` - {{CHANGE_DESCRIPTION_2}}
+
+## Commands to Resume
+
+```bash
+git checkout {{BRANCH_NAME}}
+npm install
+npm run dev
+# Then: "Continue {{FEATURE_NAME}} implementation"
+```
+
+## Notes for Next Session
+
+- {{NOTE_1}}
+- {{NOTE_2}}
+
+---
+*Generated by context-optimizer agent*