feat(handoff): add compact format for reduced token usage

- Default to compact format (~50% smaller)
- Add --verbose flag for full output
- Truncate decisions/files for minimal context

Author: jonathanpeterwu

src/cli/commands/handoff.ts

@@ -21,6 +21,9 @@ import { LinearTaskManager } from '../../features/tasks/linear-task-manager.js';
 import { logger } from '../../core/monitoring/logger.js';
 import { EnhancedHandoffGenerator } from '../../core/session/enhanced-handoff.js';
 
+// Simple token estimation (avg 3.5 chars per token for English)
+const countTokens = (text: string): number => Math.ceil(text.length / 3.5);
+
 // Handoff versioning - keep last N handoffs
 const MAX_HANDOFF_VERSIONS = 10;
 
@@ -92,6 +95,7 @@ export function createCaptureCommand(): Command {
     .option('--no-commit', 'Skip git commit')
     .option('--copy', 'Copy the handoff prompt to clipboard')
     .option('--basic', 'Use basic handoff format instead of enhanced')
+    .option('--verbose', 'Use verbose handoff format (default is compact)')
     .action(async (options) => {
       try {
         const projectRoot = process.cwd();
@@ -311,8 +315,15 @@ Generated by stackmemory capture at ${timestamp}
           // Use high-efficacy enhanced handoff generator (default)
           const enhancedGenerator = new EnhancedHandoffGenerator(projectRoot);
           const enhancedHandoff = await enhancedGenerator.generate();
-          handoffPrompt = enhancedGenerator.toMarkdown(enhancedHandoff);
-          console.log(`Estimated tokens: ~${enhancedHandoff.estimatedTokens}`);
+          // Use compact format by default, verbose if requested
+          handoffPrompt = options.verbose
+            ? enhancedGenerator.toMarkdown(enhancedHandoff)
+            : enhancedGenerator.toCompact(enhancedHandoff);
+          // Recalculate tokens for actual output format
+          const actualTokens = countTokens(handoffPrompt);
+          console.log(
+            `Estimated tokens: ~${actualTokens}${options.verbose ? ' (verbose)' : ' (compact)'}`
+          );
         }
 
         // 7. Save handoff prompt (both latest and versioned)

src/core/session/enhanced-handoff.ts

@@ -13,7 +13,7 @@ import {
   writeFileSync,
   mkdirSync,
 } from 'fs';
-import { join, basename } from 'path';
+import { basename, join } from 'path';
 import { homedir, tmpdir } from 'os';
 import { globSync } from 'glob';
 
@@ -825,7 +825,7 @@ export class EnhancedHandoffGenerator {
   }
 
   /**
-   * Convert handoff to markdown
+   * Convert handoff to markdown (verbose format)
    */
   toMarkdown(handoff: EnhancedHandoff): string {
     const lines: string[] = [];
@@ -935,4 +935,91 @@ export class EnhancedHandoffGenerator {
 
     return lines.join('\n');
   }
+
+  /**
+   * Convert handoff to compact format (~50% smaller)
+   * Optimized for minimal context window usage
+   */
+  toCompact(handoff: EnhancedHandoff): string {
+    const lines: string[] = [];
+
+    // Header: single line
+    lines.push(`# Handoff: ${handoff.project}@${handoff.branch}`);
+
+    // Active Work: condensed
+    const status =
+      handoff.activeWork.status === 'in_progress'
+        ? 'WIP'
+        : handoff.activeWork.status;
+    lines.push(`## Work: ${handoff.activeWork.description} [${status}]`);
+    if (handoff.activeWork.keyFiles.length > 0) {
+      // Use basenames only, limit to 5
+      const files = handoff.activeWork.keyFiles
+        .slice(0, 5)
+        .map((f) => basename(f))
+        .join(', ');
+      const progress = handoff.activeWork.progress
+        ? ` (${handoff.activeWork.progress.replace(' in current session', '')})`
+        : '';
+      lines.push(`Files: ${files}${progress}`);
+    }
+
+    // Decisions: single line each with arrow notation
+    if (handoff.decisions.length > 0) {
+      lines.push('');
+      lines.push('## Decisions');
+      for (const d of handoff.decisions.slice(0, 7)) {
+        // Truncate long decisions
+        const what = d.what.length > 40 ? d.what.slice(0, 37) + '...' : d.what;
+        const why = d.why ? ` → ${d.why.slice(0, 50)}` : '';
+        lines.push(`- ${what}${why}`);
+      }
+    }
+
+    // Blockers: terse format
+    if (handoff.blockers.length > 0) {
+      lines.push('');
+      lines.push('## Blockers');
+      for (const b of handoff.blockers) {
+        const status = b.status === 'open' ? '!' : '✓';
+        const tried = b.attempted.length > 0 ? ` → ${b.attempted[0]}` : '';
+        lines.push(`${status} ${b.issue}${tried}`);
+      }
+    }
+
+    // Review Feedback: only if present, condensed
+    if (handoff.reviewFeedback && handoff.reviewFeedback.length > 0) {
+      lines.push('');
+      lines.push('## Feedback');
+      for (const r of handoff.reviewFeedback.slice(0, 2)) {
+        lines.push(`[${r.source}]`);
+        for (const p of r.keyPoints.slice(0, 3)) {
+          lines.push(`- ${p.slice(0, 60)}`);
+        }
+        for (const a of r.actionItems.slice(0, 2)) {
+          lines.push(`→ ${a.slice(0, 60)}`);
+        }
+      }
+    }
+
+    // Next Actions: only top 3
+    if (handoff.nextActions.length > 0) {
+      lines.push('');
+      lines.push('## Next');
+      for (const a of handoff.nextActions.slice(0, 3)) {
+        lines.push(`- ${a.slice(0, 60)}`);
+      }
+    }
+
+    // Skip: Architecture, Patterns (can be inferred from codebase)
+
+    // Compact footer
+    lines.push('');
+    lines.push(`---`);
+    lines.push(
+      `~${handoff.estimatedTokens} tokens | ${handoff.timestamp.split('T')[0]}`
+    );
+
+    return lines.join('\n');
+  }
 }