Compaction: Structured BUILD-mode handoff summary prompt

[riatzukiza]

Epic: #46

Summary

Replace the “concise summary” with a structured BUILD‑mode handoff that reliably carries context needed to continue work.

Problem

• Current prompt is too light; compaction leads to context loss and poor continuation.

Proposal

Adopt a compact, structured handoff format with sections:

1. Primary Request and Intent
2. Key Technical Concepts
3. Files and Code Sections (include snippets when essential)
4. Errors and Fixes
5. Problem Solving
6. All user messages (non‑tool) recap
7. Pending Tasks
8. Current Work (last active step)
9. Rules & Constraints (tie‑in with rules preservation)
10. Optional Next Step (strictly aligned with the latest user request)

Code Refs

• packages/opencode/src/session/compaction.ts:169 (user content for summary message)
• packages/opencode/src/session/system.ts (SystemPrompt.summarize)

Tasks

• Implement new summary content (token‑aware; keep concise but structured)
• Ensure compatibility with smaller context windows
• Add config guard to toggle “verbose handoff” vs “lite” modes if necessary

Acceptance Criteria

• After compaction, model resumes work accurately in BUILD mode without re‑asking for context.
• Summary includes “Current Work” and “Rules & Constraints” reliably.

[riatzukiza]

Related Issues & Context

This Structured Handoff issue is the cornerstone of several related compaction improvements:

Critical Dependencies:

• Compaction: Preserve rules/constraints across compaction #48 - Rules Preservation: The handoff format DEPENDS on reliable rules preservation. The "Rules & Constraints" section is only useful if rules actually survive the compaction process.
• Compaction: Smarter boundary selection and cross-session guard #47 - Boundary Selection: Handoff effectiveness depends on keeping the right context. Poor boundary selection means the handoff document loses key recent work context.

Cross-Impact:

• Compaction: Pruning/soft compaction and selective tool-output deletion #50 - Pruning/Soft Compaction: Better pruning reduces frequency of full compaction, making the expensive handoff generation less frequent. The handoff quality becomes less critical when pruning handles more token pressure.
• Compaction: Configurable preserved turns and prune thresholds #55 - Configurable Options: Need config for handoff verbosity ("handoff" vs "lite" modes) to balance context richness vs token cost.

Strategic Importance:

• Epic: Subagent State Handoff & Context Boundary Resilience #56 - Subagent State Handoff: This is CRUCIAL. The structured handoff format developed for compaction can be REUSED for subagent state recovery. Same document structure, same sections, same purpose - just different context boundaries.

Technical Dependencies:

• Compaction: Telemetry and /status for context + decisions #52 - Telemetry: Need visibility into handoff quality and token cost
• Compaction: Tests – boundary, rules, pruning, integration #54 - Tests: Handoff quality is a primary integration test case
• Compaction: Provider options flow and accurate usage accounting #51 - Usage Accounting: Handoff generation is token-intensive - need accurate cost tracking

Implementation Synergy:

The 10-section handoff format (Primary Request → Optional Next Step) provides a template that solves TWO problems:

1. Compaction recovery - agent continues work after context reset
2. Subagent handoff - parent gets rich context from completed subagent

This makes the handoff work HIGH LEVERAGE - solving both compaction AND subagent state transfer with the same structured format.