opencodekit 0.19.5 → 0.20.0

package/dist/template/.opencode/skill/context-management/SKILL.md

@@ -1,119 +1,346 @@
 ---
 name: context-management
-description: Unified protocol for context health and session lifecycle management using DCP tools, thresholds, handoff, and resume workflows
-version: 2.0.0
+description: Unified protocol for context health and session lifecycle management using DCP tools, thresholds, handoff, resume workflows, and post-compaction restoration.
+version: 3.0.0
 tags: [context, workflow, session]
 dependencies: []
 ---
 
 # Context Management
 
-> **Replaces** manual context tracking and ad-hoc session management — unified protocol for context health across a session lifecycle
+> Unified protocol for context health across start, active execution, compression, restoration, handoff, and resume.
 
-Use this skill to keep context useful from first turn to final handoff.
+Use this skill to keep context high-signal while preserving edit safety and execution continuity.
 
 ## When to Use
 
-- Context size is growing and you need to reduce noise without losing critical details
-- You are finishing a work phase and want to compress completed exploration/implementation
-- You are preparing `/handoff` or resuming a prior session
-- You need to recover relevant prior context with `find_sessions`, `read_session`, and memory files
-
-## When NOT to Use
-
-- You are actively editing files whose raw content must remain exact
-- You are in a short, single-step task that will finish before context pressure appears
+- Context is growing and signal quality is dropping
+- A phase is complete and should be compressed
+- You are preparing `/handoff` or resuming prior work
+- You need deterministic restoration after compaction
+- You need reusable summary templates for exploration/implementation/debugging
 
 ## Core Principle
 
-Prefer **phase-level compression** over reactive cleanup.
+Prefer **phase-level context hygiene** over emergency cleanup.
 
 ```text
 compress > sweep > handoff
 ```
 
-- **compress**: Best default when a phase is complete
-- **sweep**: Use `/dcp sweep` to clean stale/noisy content after completion
-- **handoff**: Use when context pressure remains high even after compression
+- **compress**: shrink closed chapters while preserving decisions
+- **sweep**: remove stale/noisy residue from closed chapters
+- **handoff**: reset in a fresh session when compression is insufficient
 
 ## DCP Command Usage
 
+### `/dcp context`
+
+Run at session start and major boundaries to detect pressure early.
+
 ### `/dcp compress`
 
-Use for completed chapters of work (research, implementation wave, review sweep).
+Primary action for completed chapters.
 
-- Best for large ranges of now-stable outputs
-- Lowest cognitive overhead on later turns
-- Usually lowest risk of deleting needed details
+Use when:
+
+- exploration has stable conclusions
+- implementation wave is complete and verified
+- review output has been synthesized
 
 ### `/dcp sweep`
 
-Use after a phase is complete to let DCP remove stale/noisy content automatically.
+Secondary cleanup after chapter closure.
 
-Good candidates for sweep-driven cleanup:
+Sweep candidates:
 
 - wrong-target searches
-- failed dead-end exploration no longer needed
-- duplicate or superseded junk output
+- superseded logs
+- duplicate tool output
+- dead-end exploration replaced by synthesis
+- large terminal dumps no longer needed
 
-Do **not** sweep because output is merely "long". Length alone is not noise.
+Do not sweep active material needed for immediate edits.
 
 ## Session Lifecycle Protocol
 
 ### 1) Start Session
 
-1. Load task spec and essential policy docs only
-2. Check context health (`/dcp context`)
-3. Pull prior work only if needed:
+1. Load task + essential policy docs only
+2. Run `/dcp context`
+3. Rehydrate prior state only if needed:
    - `find_sessions({ query })`
    - `read_session({ session_id, focus })`
-   - `memory-read({ file })` or `memory-search({ query })`
+   - `memory-search({ query })` / `memory-read({ file })`
+4. Verify git position before edits
 
 ### 2) During Active Work
 
-- Keep active files readable until edits are done
-- At each natural boundary, evaluate compress candidates
-- Compress completed phases before starting the next chapter
+- Keep active file outputs readable until edit + verification finish
+- Reclassify context at boundaries: active vs closed
+- Compress closed chapters before opening a new major chapter
+- Sweep only after synthesis exists
 
 ### 3) Pre-Handoff / Closeout
 
-1. Compress completed phase ranges
-2. Persist key decisions/learnings to memory (observation or memory-update)
-3. Create concise handoff summary (what changed, what is pending, known risks)
+1. Compress closed phases
+2. Sweep stale/noisy residue
+3. Persist decisions/learnings to memory
+4. Write concise handoff (changed, pending, risks)
 
 ### 4) Resume Session
 
-1. Rehydrate only relevant context (don’t replay everything)
-2. Validate assumptions against current files/git state
-3. Continue with fresh context budget, not accumulated clutter
+1. Rehydrate only relevant context
+2. Validate assumptions against files + git state
+3. Continue with fresh budget and explicit priorities
 
 ## Context Budget Thresholds
 
-Use these thresholds as operational triggers:
-
-| Threshold | Interpretation | Required Action |
-| --- | --- | --- |
-| <50k | Healthy start | Keep inputs minimal, avoid unnecessary reads |
-| 50k–100k | Moderate growth | Compress completed phases, keep active files intact |
-| >100k | High pressure | Aggressively compress by phase; run `/dcp sweep` on stale noise |
-| >150k | Near capacity | Perform handoff and resume in a fresh session |
-
-Secondary guardrails:
+| Threshold | Interpretation  | Required Action                    |
+| --------- | --------------- | ---------------------------------- |
+| <50k      | Healthy start   | Keep inputs minimal                |
+| 50k-100k  | Moderate growth | Compress completed phases          |
+| >100k     | High pressure   | Aggressive compress + `/dcp sweep` |
+| >150k     | Near capacity   | Handoff + resume fresh session     |
 
-- ~70%: Consolidate and drop stale exploration
-- ~85%: Plan handoff window at next natural break
-- ~95%: Immediate cleanup or restart required
+Guardrails: ~70% consolidate closed exploration, ~85% schedule handoff, ~95% immediate cleanup/restart.
 
 ## Phase Boundary Triggers
 
 Compress at these boundaries:
 
-- Research complete → compress exploration + search outputs
-- Implementation wave complete → compress completed read/edit/test cycles
-- Review complete → compress raw reviewer outputs, keep synthesized findings
-- Before `/handoff` → compress everything non-essential since last checkpoint
+- Research complete -> compress exploration/search output
+- Implementation wave complete -> compress read/edit/test cycle output
+- Review complete -> compress raw reviewer output; keep synthesis
+- Pre-handoff -> compress non-essential context since last checkpoint
+
+Rule: **Closed phases should not remain uncompressed for long.**
+
+## Compaction Decision Tree
+
+Use this before each cleanup action.
+
+```text
+Is context pressure increasing materially?
+├── NO
+│   └── Continue work; reassess at next phase boundary
+└── YES
+    ├── Is there a completed phase with stable conclusions?
+    │   ├── YES -> /dcp compress completed range
+    │   └── NO
+    │       ├── Is growth mostly stale/noisy closed-phase output?
+    │       │   ├── YES -> /dcp sweep
+    │       │   └── NO
+    │       │       ├── Is most remaining context still active/relevant?
+    │       │       │   ├── YES -> Prepare handoff + resume fresh session
+    │       │       │   └── NO -> Reclassify content, then compress/sweep
+    │       └── If uncertain, preserve active content until closure
+```
+
+## Custom Summarization Templates
+
+Use these templates to keep summaries dense and recoverable.
+
+### A) Code Exploration Template
+
+```markdown
+## Exploration Summary: [Component/Module]
+
+### Objective
+
+- [What was investigated]
+
+### Architecture Map
+
+- Entry points: `path/to/entry.ts`
+- Core modules: `A`, `B`, `C`
+- Data flow: [input -> transform -> output]
+- Dependencies/services: [list]
+
+### Verified Findings
+
+- [Finding with evidence]
+- [Finding with evidence]
+- [Finding with evidence]
+
+### Constraints
+
+- [Technical/policy/runtime constraints]
+
+### Decisions
+
+- [Decision] -> [Rationale]
+- [Decision] -> [Rationale]
+
+### Next Step
+
+- [Immediate next action]
+```
+
+### B) Implementation Template
+
+```markdown
+## Implementation Summary: [Feature/Fix]
+
+### Scope
+
+- [What this wave covered]
+
+### Completed
+
+- [x] `path/to/file.ts` -> [change]
+- [x] `path/to/file.test.ts` -> [coverage]
+- [x] [other completed work]
+
+### Verification Evidence
+
+- Typecheck: [command + result]
+- Lint: [command + result]
+- Tests: [command + result]
+
+### Remaining
+
+- [ ] [pending item]
+- [ ] [pending item]
+
+### Key Decisions
+
+- [Decision + reason]
+- [Decision + reason]
+
+### Resume Anchor
+
+- Resume from: `path/to/file.ts` [function/region]
+```
+
+### C) Debugging Template
+
+```markdown
+## Debug Summary: [Issue]
+
+### Symptoms
+
+- Error: [exact error]
+- Trigger: [request/action]
+- Location: `path:line`
+
+### Root Cause
 
-Rule: **Completed phases should not remain uncompressed for long.**
+- [causal chain with evidence]
+
+### Fix Applied
+
+- `path/to/file.ts` -> [exact fix]
+- `path/to/test.ts` -> [new/updated coverage]
+
+### Verification
+
+- [test command + result]
+- [manual check + result]
+
+### Next Step
+
+- [if unresolved, next investigation/fix]
+```
+
+## DCP Plugin Integration
+
+This project uses `@tarquinen/opencode-dcp` via `experimental.chat.system.transform`.
+
+### DCP Responsibilities (Always On)
+
+- context budget monitoring + threshold cues
+- `/dcp` command surface (`context`, `compress`, `sweep`, `stats`)
+- prunable-tools guidance + token-aware nudges
+- critical-limit warnings
+
+### Context-Management Responsibilities (This Skill)
+
+- timing policy for compress/sweep/handoff
+- summary quality and template selection
+- post-compaction restoration protocol
+- cross-session rehydration sequence
+
+### Division of Responsibility
+
+- **DCP plugin**: measures/surfaces pressure, exposes cleanup commands
+- **context-management skill**: decides when to apply commands and how to preserve continuity
+
+### Custom Prompt Overrides
+
+Custom DCP prompts are enabled (`experimental.customPrompts: true`).
+
+Override precedence:
+
+1. `.opencode/dcp-prompts/overrides/` (project)
+2. config directory overrides
+3. `~/.config/opencode/dcp-prompts/overrides/` (global)
+
+Key file: `compress-message.md` (structured compression schema). Recommended blocks: Primary Request, Key Technical Concepts, Files/Code, Errors/Fixes, Problem Solving, User Messages, Pending Tasks, Current Work, Next Step.
+
+## Post-Compaction Restoration Protocol (Critical)
+
+After any compaction (server-side or `/dcp compress`), execute all 5 steps before editing.
+
+### Step 1 — Re-read Active Files (max 5)
+
+Re-read files active before compaction.
+
+- prioritize most recent edits first
+- cap at 5 files
+- use targeted reads (`offset`/`limit`) for precision
+
+Example:
+
+```text
+read({ filePath: "src/auth.ts", offset: 30, limit: 80 })
+```
+
+Why: restores exact local code context and satisfies read-before-edit safety requirements.
+
+### Step 2 — Restore Active Skills
+
+Reload any skills active before compaction.
+
+```typescript
+skill({ name: "<active-skill>" });
+```
+
+Why: skill instructions are prompt-injected and may be dropped by compaction.
+
+### Step 3 — Reconcile Todo State
+
+Rebuild exact task status:
+
+- what was `in_progress`
+- what remains `pending`
+- what is `completed`
+
+Why: prevents duplicate work and missed subtasks.
+
+### Step 4 — Verify Git Position
+
+```bash
+git branch --show-current
+git status --short
+```
+
+Why: confirms branch correctness and re-anchors uncommitted file state.
+
+### Step 5 — Scan Memory / Session Artifacts
+
+If compaction was heavy, recover nuance using:
+
+- `memory-search({ query, limit: 3 })`
+- `memory-read({ file })`
+- `find_sessions({ query, limit })`
+- `read_session({ session_id, focus })`
+
+Why: restores rationale/constraints often missing from short summaries.
+
+### Restoration Exit Criteria
+
+Do not resume edits until active targets are re-read, required skills are reloaded, todo state is reconciled, git position is confirmed, and critical rationale is recovered when needed.
 
 ## Context Transfer Sources (Cross-Session)
 
@@ -121,43 +348,43 @@ Use in priority order:
 
 1. Memory artifacts (`memory-search`, `memory-read`, observations)
 2. Session history (`find_sessions`, `read_session`)
-3. Task tracker state (`br show <id>` when applicable)
+3. Task tracker state (`br show <id>`)
 4. Git evidence (`git diff`, `git log`, test output)
 
-Carry forward decisions and constraints, not every intermediate log.
+Carry forward decisions, constraints, and next actions — not transcript bulk.
 
 ## Anti-Patterns
 
-| Anti-Pattern | Why It Hurts | Correct Pattern |
-| --- | --- | --- |
-| Compressing active work areas (losing precision needed for edits) | Removes exact lines needed for safe edits | Keep active file/tool outputs until edit + verification complete |
-| Sweeping content you still need | Forces rework and increases error risk | Keep active files/tool outputs until phase is complete |
-| Not compressing completed exploration phases | Bloats context and degrades later turns | Compress immediately at phase completion |
-| Session handoff without persisting key decisions to memory | Next session loses rationale and constraints | Write observations/memory updates before handoff |
+| Anti-Pattern                          | Why It Hurts                           | Correct Pattern                                |
+| ------------------------------------- | -------------------------------------- | ---------------------------------------------- |
+| Compressing active edit context       | Loses exact data needed for safe edits | Keep active outputs until edit+verify complete |
+| Sweeping still-live content           | Causes rework and precision loss       | Sweep only stale/noisy closed-phase outputs    |
+| Leaving closed phases uncompressed    | Context bloat degrades later turns     | Compress at each phase boundary                |
+| Handoff without memory persistence    | Next session loses rationale           | Persist decisions before handoff               |
+| Skipping restoration after compaction | Edit failures, skill drift, task drift | Run 5-step restoration before resuming         |
 
 ## Verification
 
-Check context health: are completed phases compressed? Are active files still readable?
-
-Before claiming cleanup done, confirm:
+Before claiming context cleanup complete, verify:
 
-- Active edit targets are still present in readable form
-- Completed phases are compressed or intentionally kept for active work
-- No critical decision exists only in transient tool output
-- Handoff includes next actions and blockers
+- active edit targets are still readable
+- closed chapters are compressed or intentionally retained
+- no critical decision exists only in transient output
+- restoration protocol completed after compaction
+- handoff includes next actions and blockers
 
 ## Quick Playbook
 
 ```text
-1) Start turn: /dcp context
-2) Identify completed phase ranges
-3) /dcp compress completed ranges
-4) /dcp sweep stale/noisy outputs after phase completion
-5) persist key decisions to memory
-6) handoff/resume with focused rehydration
+1) /dcp context
+2) classify context: active vs closed
+3) /dcp compress on closed chapters
+4) /dcp sweep stale/noisy closed outputs
+5) if compaction happened: run 5-step restoration
+6) persist key decisions to memory
+7) handoff/resume with focused rehydration
 ```
 
 ## See Also
 
 - `memory-system`
-- `compaction`

package/dist/template/.opencode/skill/core-data-expert/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: core-data-expert
-description: "Expert Core Data guidance (iOS/macOS): stack setup, fetch requests & NSFetchedResultsController, saving/merge conflicts, threading & Swift Concurrency, batch operations & persistent history, migrations, performance, and NSPersistentCloudKitContainer/CloudKit sync."
+description: "Use when writing, debugging, or optimizing Core Data code on iOS/macOS — fetch requests, migrations, merge conflicts, threading, CloudKit sync. MUST load before any Core Data schema changes or performance work."
 version: 1.0.0
 tags: [apple, integration]
 dependencies: []

package/dist/template/.opencode/skill/design-system-audit/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: design-system-audit
-description: Unified design audit workflow for UI pattern analysis, design token auditing, and visual comparison against specs
+description: Use when auditing an existing design system for consistency — token audits, pattern analysis, visual comparison against design specs. Load AFTER implementation to review, not during initial build.
 version: 2.0.0
 tags: [design, audit, ui]
 dependencies: []

package/dist/template/.opencode/skill/design-taste-frontend/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: design-taste-frontend
-description: Senior UI/UX Engineer. Architect digital interfaces overriding default LLM biases. Enforces metric-based rules, strict component architecture, CSS hardware acceleration, and balanced design engineering.
+description: Use as the BASE aesthetic skill for any web UI to override default LLM design biases. Enforces strict typography, color, spacing, and component architecture rules. Load BEFORE frontend-design when premium visual quality is required.
 ---
 
 # High-Agency Frontend Skill

package/dist/template/.opencode/skill/figma/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: figma
-description: Access Figma design data via Framelink MCP. Fetch layout, styles, components from Figma files/frames. Use when implementing UI from Figma designs, extracting design tokens, or downloading assets.
+description: Use when implementing UI from Figma designs, extracting design tokens, or downloading assets via Framelink MCP. MUST load when user shares a Figma URL or references Figma files. Requires API token.
 mcp:
   figma:
     command: npx

package/dist/template/.opencode/skill/figma-go/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: figma-go
-description: Use figma-mcp-go (plugin bridge, no API token). Read/write Figma data via MCP.
+description: Use for Figma read/write access WITHOUT an API token, via figma-mcp-go plugin bridge. Prefer over figma skill when no API token is available. MUST load when user needs Figma data and has the desktop plugin installed.
 mcp:
   figma-mcp-go:
     command: npx

package/dist/template/.opencode/skill/frontend-design/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: frontend-design
-description: Create distinctive, production-grade frontend interfaces. Use when building web components, pages, or applications with React-based frameworks. Includes Tailwind CSS v4, shadcn/ui components, Motion animations, and visual design philosophy for avoiding generic AI aesthetics.
+description: MUST load when building any web UI with React-based frameworks — components, pages, or full applications. Covers Tailwind CSS v4, shadcn/ui, Motion animations. Base UI implementation skill; combine with aesthetic overlays (minimalist-ui, high-end-visual-design) for specific styles.
 version: 1.1.0
 tags: [ui, design]
 dependencies: []

package/dist/template/.opencode/skill/full-output-enforcement/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: full-output-enforcement
-description: Overrides default LLM truncation behavior. Enforces complete code generation, bans placeholder patterns, and handles token-limit splits cleanly. Apply to any task requiring exhaustive, unabridged output.
+description: MUST load when generating complete files, long code blocks, or any output where truncation or placeholder comments like '// ... rest of code' would be harmful. Bans all placeholder patterns and enforces exhaustive, unabridged output.
 ---
 
 # Full-Output Enforcement

package/dist/template/.opencode/skill/high-end-visual-design/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: high-end-visual-design
-description: Teaches the AI to design like a high-end agency. Defines the exact fonts, spacing, shadows, card structures, and animations that make a website feel expensive. Blocks all the common defaults that make AI designs look cheap or generic.
+description: Use INSTEAD OF design-taste-frontend when user explicitly requests premium, agency-quality, or luxury visual design. Defines exact fonts, spacing, shadows, and animations that make websites feel expensive. Blocks cheap AI defaults.
 ---
 
 # Agent Skill: Principal UI/UX Architect & Motion Choreographer (Awwwards-Tier)

package/dist/template/.opencode/skill/index-knowledge/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: index-knowledge
-description: Generate hierarchical AGENTS.md knowledge base for a codebase. Creates root + complexity-scored subdirectory documentation.
+description: Use when generating or refreshing AGENTS.md knowledge bases for a codebase. MUST load before creating hierarchical documentation or complexity-scored subdirectory guides.
 version: 1.0.0
 tags: [documentation, workflow]
 dependencies: []

package/dist/template/.opencode/skill/industrial-brutalist-ui/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: industrial-brutalist-ui
-description: Raw mechanical interfaces fusing Swiss typographic print with military terminal aesthetics. Rigid grids, extreme type scale contrast, utilitarian color, analog degradation effects. For data-heavy dashboards, portfolios, or editorial sites that need to feel like declassified blueprints.
+description: Use INSTEAD OF design-taste-frontend when user requests brutalist, military-terminal, or raw mechanical aesthetics. Swiss typographic print meets utilitarian color. For data-heavy dashboards or editorial sites needing declassified-blueprint energy.
 ---
 
 # SKILL: Industrial Brutalism & Tactical Telemetry UI

package/dist/template/.opencode/skill/jira/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: jira
-description: Jira and Confluence integration via official Atlassian MCP. Search issues, create tickets, update status, and access Confluence docs. Uses OAuth 2.1 authorization with Rovo Search.
+description: Use when interacting with Jira issues or Confluence docs — searching tickets, creating issues, updating status, or reading wiki pages. MUST load before any Atlassian integration. Requires network access to Atlassian MCP.
 version: 1.0.0
 tags: [integration, mcp, workflow]
 dependencies: []

package/dist/template/.opencode/skill/minimalist-ui/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: minimalist-ui
-description: Clean editorial-style interfaces. Warm monochrome palette, typographic contrast, flat bento grids, muted pastels. No gradients, no heavy shadows.
+description: Use INSTEAD OF design-taste-frontend when user requests clean, editorial, or minimalist aesthetics. Warm monochrome palette, typographic contrast, flat bento grids, muted pastels. No gradients, no heavy shadows.
 ---
 
 # Protocol: Premium Utilitarian Minimalism UI Architect

package/dist/template/.opencode/skill/mqdh/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: mqdh
-description: Meta Quest Developer Hub MCP for VR/AR development. Access Meta Horizon OS docs, ADB tools, device management. Use when building Quest apps or need Meta XR documentation.
+description: Use when building Meta Quest VR/AR apps, accessing Meta Horizon OS docs, or managing Quest devices via ADB. MUST load before any Meta XR development or documentation lookup.
 mcp:
   mqdh:
     command: "${MQDH_MCP_PATH}"