The agent harness performance optimization system. Skills, instincts, memory, security, and research-first development for Claude Code, Codex, Opencode, Cursor and beyond.
fix: pass transcript_path via stdin JSON in integration tests (#209)
Affaan Mustafae4f4c2c36d7b
diff --git a/skills/strategic-compact/SKILL.md b/skills/strategic-compact/SKILL.mdindex 394a86b1b..562119bb3 100644--- a/skills/strategic-compact/SKILL.md+++ b/skills/strategic-compact/SKILL.md@@ -7,6 +7,14 @@ description: Suggests manual context compaction at logical intervals to preserveSuggests manual `/compact` at strategic points in your workflow rather than relying on arbitrary auto-compaction.+## When to Activate++- Running long sessions that approach context limits (200K+ tokens)+- Working on multi-phase tasks (research → plan → implement → test)+- Switching between unrelated tasks within the same session+- After completing a major milestone and starting new work+- When responses slow down or become less coherent (context pressure)+## Why Strategic Compaction?Auto-compaction triggers at arbitrary points:@@ -15,17 +23,17 @@ Auto-compaction triggers at arbitrary points:- Can interrupt complex multi-step operationsStrategic compaction at logical boundaries:-- **After exploration, before execution** - Compact research context, keep implementation plan-- **After completing a milestone** - Fresh start for next phase-- **Before major context shifts** - Clear exploration context before different task+- **After exploration, before execution** — Compact research context, keep implementation plan+- **After completing a milestone** — Fresh start for next phase+- **Before major context shifts** — Clear exploration context before different task## How It WorksThe `suggest-compact.sh` script runs on PreToolUse (Edit/Write) and:-1. **Tracks tool calls** - Counts tool invocations in session-2. **Threshold detection** - Suggests at configurable threshold (default: 50 calls)-3. **Periodic reminders** - Reminds every 25 calls after threshold+1. **Tracks tool calls** — Counts tool invocations in session+2. **Threshold detection** — Suggests at configurable threshold (default: 50 calls)+3. **Periodic reminders** — Reminds every 25 calls after threshold## Hook Setup@@ -48,16 +56,44 @@ Add to your `~/.claude/settings.json`:## ConfigurationEnvironment variables:-- `COMPACT_THRESHOLD` - Tool calls before first suggestion (default: 50)+- `COMPACT_THRESHOLD` — Tool calls before first suggestion (default: 50)++## Compaction Decision Guide++Use this table to decide when to compact:++| Phase Transition | Compact? | Why |+|-----------------|----------|-----|+| Research → Planning | Yes | Research context is bulky; plan is the distilled output |+| Planning → Implementation | Yes | Plan is in TodoWrite or a file; free up context for code |+| Implementation → Testing | Maybe | Keep if tests reference recent code; compact if switching focus |+| Debugging → Next feature | Yes | Debug traces pollute context for unrelated work |+| Mid-implementation | No | Losing variable names, file paths, and partial state is costly |+| After a failed approach | Yes | Clear the dead-end reasoning before trying a new approach |++## What Survives Compaction++Understanding what persists helps you compact with confidence:++| Persists | Lost |+|----------|------|+| CLAUDE.md instructions | Intermediate reasoning and analysis |+| TodoWrite task list | File contents you previously read |+| Memory files (`~/.claude/memory/`) | Multi-step conversation context |+| Git state (commits, branches) | Tool call history and counts |+| Files on disk | Nuanced user preferences stated verbally |## Best Practices-1. **Compact after planning** - Once plan is finalized, compact to start fresh-2. **Compact after debugging** - Clear error-resolution context before continuing-3. **Don't compact mid-implementation** - Preserve context for related changes-4. **Read the suggestion** - The hook tells you *when*, you decide *if*+1. **Compact after planning** — Once plan is finalized in TodoWrite, compact to start fresh+2. **Compact after debugging** — Clear error-resolution context before continuing+3. **Don't compact mid-implementation** — Preserve context for related changes+4. **Read the suggestion** — The hook tells you *when*, you decide *if*+5. **Write before compacting** — Save important context to files or memory before compacting+6. **Use `/compact` with a summary** — Add a custom message: `/compact Focus on implementing auth middleware next`## Related-- [The Longform Guide](https://x.com/affaanmustafa/status/2014040193557471352) - Token optimization section-- Memory persistence hooks - For state that survives compaction+- [The Longform Guide](https://x.com/affaanmustafa/status/2014040193557471352) — Token optimization section+- Memory persistence hooks — For state that survives compaction+- `continuous-learning` skill — Extracts patterns before session endsdiff --git a/tests/integration/hooks.test.js b/tests/integration/hooks.test.jsindex a9e935518..19fab8665 100644--- a/tests/integration/hooks.test.js+++ b/tests/integration/hooks.test.js@@ -307,8 +307,7 @@ async function runTests() {try {const result = await runHookWithInput(path.join(scriptsDir, 'evaluate-session.js'),- {},- { CLAUDE_TRANSCRIPT_PATH: transcriptPath }+ { transcript_path: transcriptPath });// Should not crash, just skip processing@@ -364,8 +363,7 @@ async function runTests() {try {const result = await runHookWithInput(path.join(scriptsDir, 'evaluate-session.js'),- {},- { CLAUDE_TRANSCRIPT_PATH: transcriptPath }+ { transcript_path: transcriptPath });assert.ok(result.stderr.includes('15 messages'), 'Should process session');