opencodekit 0.21.0 → 0.21.2

package/dist/template/.opencode/skill/agent-evals/SKILL.md

@@ -0,0 +1,208 @@
+---
+name: agent-evals
+description: Use when adding/changing a skill, command, or agent prompt and you want evidence it actually helps — not just intuition. Defines bounded-task evals, no-skill baselines, deterministic verifiers, JSONL trace logs, and when to skip eval. Adapted from OpenAI eval guide, OpenHands "evaluating agent skills", Anthropic "demystifying evals".
+---
+
+# Agent Evals
+
+> Without evals, every skill ships on vibes. The harness-engineering literature is unanimous: **measured changes beat believed-changes**. This skill gives you the smallest workable eval loop.
+
+## When to Use
+
+Run an eval when:
+
+- Adding a new skill that claims to improve outcomes (`anti-ai-slop`, `prompt-leverage`, `condition-based-waiting`)
+- Changing a prompt or instruction in an agent (`build`, `plan`, `review`)
+- Comparing two approaches and you don't know which is better
+- A skill is suspected of being inert ("does this even do anything?")
+
+**Skip eval when:**
+
+- The change is mechanical (rename, refactor, lint fix)
+- The change is a one-shot fix with obvious verification (test passes / build green)
+- The skill is purely procedural with deterministic output (workspace setup)
+
+## Core Principle: Bounded + Baseline + Verifier
+
+Three ingredients. Skip any one and the eval is theatre.
+
+1. **Bounded task** — a concrete prompt with a definite finish line, runnable in <5 minutes
+2. **No-skill baseline** — the same task run **without** the skill loaded, for comparison
+3. **Deterministic verifier** — a check that returns pass/fail without human judgment
+
+If you cannot write the verifier, the skill's value is unmeasurable and you are guessing.
+
+## Eval Loop (Minimum Viable)
+
+### Step 1: Define the task
+
+Pick a real failure mode the skill targets. One paragraph, copy-pastable as a prompt.
+
+```markdown
+## Task: anti-ai-slop / no-purple-gradient
+
+**Prompt:** "Build a landing page hero for a coffee roastery brand. Single HTML file."
+
+**Verifier (deterministic):**
+
+- grep output for `linear-gradient.*purple|#[89a]\d[0-9a-f]\d{3}` → must return 0 matches
+- grep output for `Inter|Roboto` in `font-family` → must return 0 matches
+- File contains `<h1>` with content → must be true
+
+**Pass criteria:** all 3 checks pass
+```
+
+### Step 2: Run baseline (no skill)
+
+Fresh subagent, **don't load the skill**. Same prompt. Save output.
+
+```typescript
+task({
+  subagent_type: "general",
+  description: "Baseline: coffee landing page",
+  prompt:
+    "Build a landing page hero for a coffee roastery brand. Single HTML file. Output the full HTML only.",
+});
+```
+
+Save result to `.beads/artifacts/<eval-id>/baseline.html`.
+
+### Step 3: Run treatment (with skill)
+
+Fresh subagent, **load the skill explicitly** in prompt. Same task.
+
+```typescript
+task({
+  subagent_type: "general",
+  description: "Treatment: coffee landing page",
+  prompt: `First load the anti-ai-slop skill. Then: Build a landing page hero for a coffee roastery brand. Single HTML file. Output the full HTML only.`,
+});
+```
+
+Save result to `.beads/artifacts/<eval-id>/treatment.html`.
+
+### Step 4: Run verifier on both
+
+```bash
+# Baseline
+grep -cE "linear-gradient.*purple|#[89a][0-9a-f]" baseline.html
+grep -cE "(Inter|Roboto)" baseline.html
+
+# Treatment
+grep -cE "linear-gradient.*purple|#[89a][0-9a-f]" treatment.html
+grep -cE "(Inter|Roboto)" treatment.html
+```
+
+### Step 5: Record result
+
+Append one JSONL line to `.opencode/evals/log.jsonl`:
+
+```json
+{
+  "eval_id": "anti-slop-001",
+  "skill": "anti-ai-slop",
+  "date": "2026-04-21",
+  "baseline_pass": false,
+  "treatment_pass": true,
+  "delta": "+1",
+  "notes": "baseline used purple gradient + Inter; treatment used warm browns + Source Serif"
+}
+```
+
+## Multi-Run for Confidence
+
+A single run can be lucky. For a skill you're seriously evaluating:
+
+- Run baseline **3 times**, treatment **3 times** (different seeds via different prompts framings)
+- Report pass-rate not single result: `baseline 1/3, treatment 3/3`
+- If treatment ≤ baseline, the skill is **inert or harmful** — fix or delete
+
+## Verifier Patterns That Work
+
+| Skill type             | Verifier                                                          |
+| ---------------------- | ----------------------------------------------------------------- |
+| Anti-pattern avoidance | `grep` for the banned pattern → expect 0                          |
+| Required output shape  | JSON schema validation, presence of required sections             |
+| Code correctness       | run the code, run its tests, check exit code                      |
+| Behavior change        | call site count via `tilth_search`, file existence, line counts   |
+| UI / visual            | Playwright screenshot + pixel diff against expected, or DOM query |
+| Refusal / safety       | grep for forbidden phrases or correct refusal pattern             |
+
+## Verifier Anti-Patterns (Don't Use)
+
+- "Ask another LLM if this is good" — non-deterministic, expensive, judgment-laden
+- "Check if it looks right" — not a verifier, that's a vibe
+- "Pass if no errors thrown" — too weak, baseline also passes
+- "Manually inspect" — fine for one-off, useless for regression
+
+## Trace Logging Format
+
+For multi-step evals (agent ran 5 tool calls, made 3 edits), log the trace:
+
+```json
+{
+  "eval_id": "ship-flow-002",
+  "steps": [
+    { "tool": "task", "args": { "subagent_type": "explore" }, "ok": true },
+    { "tool": "edit", "args": { "path": "src/auth.ts" }, "ok": true },
+    { "tool": "bash", "args": { "command": "npm test" }, "ok": false, "exit_code": 1 }
+  ],
+  "outcome": "failed_at_step_3",
+  "verifier_pass": false
+}
+```
+
+This lets you find **which step** failed across many runs — surfaces flaky points in a workflow.
+
+## When Eval Disagrees with Intuition
+
+The skill **feels** great but the eval says baseline ≥ treatment. Trust the eval. Common causes:
+
+1. The skill is too long — the agent ignored it
+2. The skill targets a problem the model already handles
+3. The verifier doesn't measure what the skill actually changes (re-read your verifier)
+4. The baseline prompt was too easy (try a harder task)
+
+Fix in this order: verifier → task difficulty → skill content. Delete the skill if all three fail.
+
+## Eval Storage Convention
+
+```
+.opencode/evals/
+├── log.jsonl                    # append-only, one line per run
+├── tasks/                       # task definitions
+│   ├── anti-slop-001.md
+│   └── ship-flow-002.md
+└── artifacts/                   # baseline.* and treatment.* outputs
+    └── <eval_id>/
+```
+
+Keep evals in-repo. They're documentation that the skill works.
+
+## Integration with `/health` and `/curate`
+
+- `/health` should flag skills with **zero eval coverage** as IMPORTANT (not CRITICAL — many skills are simple enough not to need it)
+- `/curate` should surface eval results when proposing skill consolidation: "skill X has 0/5 passes over last 3 months, propose deletion"
+
+## Cost Discipline
+
+- Each eval run = 1 subagent call. 6 runs (3 baseline + 3 treatment) = 6 calls.
+- Don't eval every skill. Eval the ones whose **value is contested** or whose **failure would be expensive**.
+- Cache baseline runs — re-run only when the underlying model changes.
+
+## Output
+
+After running an eval, return:
+
+```markdown
+## Eval: <skill-name>
+
+- **Task:** [one line]
+- **Baseline:** N/M passes
+- **Treatment:** N/M passes
+- **Delta:** [+/-N]
+- **Verdict:** keep | iterate | delete
+- **Trace:** `.opencode/evals/log.jsonl` line <N>
+```
+
+Brief. Evidence-based. No padding.

package/dist/template/.opencode/skill/anti-ai-slop/SKILL.md

@@ -0,0 +1,76 @@
+---
+name: anti-ai-slop
+description: Use when generating any visual design output (web UI, slides, animations, mockups, infographics) to actively prevent the AI default aesthetic that strips brand identity. Bans purple gradients, emoji-as-icons, rounded-card+left-accent, AI-drawn human SVGs, GitHub-dark `#0D1117`, Inter/Roboto-as-display. Adapted from huashu-design.
+---
+
+# Anti AI Slop
+
+> The AI default aesthetic is the **visual common denominator** of all training data. Using it makes every brand look identical. Avoiding it is **brand protection**, not aesthetic snobbery.
+
+## Why This Matters
+
+The reasoning chain:
+
+1. The user wants their brand to be recognizable.
+2. AI default output = average of training corpus = all brands blended = **no brand recognized**.
+3. So AI defaults dilute the user's brand into "another AI-generated page."
+4. Avoiding AI slop is replacing default-mode output with **brand-specific intent**.
+
+Anti-slop is the **defensive** half of design discipline. The **offensive** half is `brand-asset-protocol` (use real logos, real product images, real colors). Both required.
+
+## The Slop Lookup Table
+
+| Pattern                                                | Why it's slop                                                                               | Allowed when                                                                               |
+| ------------------------------------------------------ | ------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------ |
+| **Aggressive purple gradient**                         | The "tech feel" formula in every SaaS/AI/web3 landing page in training data                 | Brand actually uses purple gradient (some Linear contexts), or task is satire of slop      |
+| **Emoji as icon** (`🚀 Fast`, `✨ Magic`)              | "Not professional enough? Add an emoji" disease — symptom of training data                  | Brand uses them (Notion), or audience is kids / casual                                     |
+| **Rounded card + left colored border accent**          | 2020-2024 Material/Tailwind cliche, now visual noise                                        | User explicitly asks, or it's in the brand spec                                            |
+| **SVG-drawn imagery** (humans, faces, scenes)          | AI-drawn SVG humans always have warped faces, weird proportions                             | **Almost never** — use real images (Wikimedia/Unsplash/AI-generated) or honest placeholder |
+| **CSS silhouettes for product photos**                 | Generates "generic tech animation" — black bg + orange accent + rounded bars. Zero brand ID | Almost never — fetch real product photo first (see `brand-asset-protocol`)                 |
+| **Inter / Roboto / Arial / system as display font**    | Too common — reader can't tell "designed product" from "demo page"                          | Brand spec uses them (Stripe uses tuned Inter variant)                                     |
+| **Cyber neon / GitHub dark `#0D1117`**                 | Copy of GitHub dark mode aesthetic, used everywhere                                         | Developer tools brand that genuinely uses this direction                                   |
+| **Generic stock photo "lifestyle" hero on text essay** | Adds no information; pure decoration = slop                                                 | Image is the content (museum portrait, product detail, location card)                      |
+| **3+ accent colors**                                   | Multi-color clustering reads as "I couldn't decide"                                         | Data legitimately has ≥3 categorical dimensions                                            |
+| **Decorative-icon-on-every-line**                      | "Iconography slop" — pads visual density without information                                | Icon carries differentiating product information (status, type, action)                    |
+| **Fabricated stats / fake quotes / lorem ipsum**       | "Data slop" — fills space with meaningless numbers                                          | Never. Ask user for real content or leave honest blank space                               |
+| **One generic "page load" animation everywhere**       | Scattered micro-interactions feel cheap                                                     | One well-orchestrated, intentional animation per page                                      |
+
+**Single criterion for allowing any of these**: "the brand spec uses it" or "the task is intentionally about showing slop." Without that explicit reason, default to avoiding.
+
+## What to Do Instead (Positive Patterns)
+
+- ✅ **`text-wrap: pretty`, CSS Grid, advanced CSS** — typography details an AI usually skips. Signals "real designer."
+- ✅ **Use `oklch()` or colors from the brand spec.** Never invent new colors mid-design — every invented color erodes brand consistency.
+- ✅ **Real images > AI-drawn SVG > HTML/CSS-faked imagery.** Photo first; AI generation second; CSS shapes only when imagery isn't the point.
+- ✅ **Typographic curly quotes** ("smart" not "straight") — signal of "this was reviewed."
+- ✅ **120% on one detail, 80% on the rest.** Taste = picking the right place to be precise. Even attention everywhere = uniformly bland.
+- ✅ **Honest blank > clumsy fill.** A gray block labeled "user avatar" beats an AI-drawn portrait.
+
+## "But the task IS about slop" — Negative Examples Done Right
+
+When the work is showing what _not_ to do (a critique post, a slop-vs-good comparison):
+
+- **Don't fill the whole page with slop.** Containerize the bad sample.
+- Use a **dashed border + corner label** "Anti-pattern · do not copy" so the reader can tell intent.
+- The negative example serves the narrative; it doesn't pollute the page's primary visual register.
+
+## Self-Check Questions (run before delivery)
+
+For every visual element on the page, ask:
+
+1. **Why is this here?** "It looks nice" is not enough. Each element must earn its place.
+2. **Could a different brand use this exact element?** If yes → it's not specific enough.
+3. **Did I invent this color/font/shape, or did it come from the brand spec or a real source?**
+4. **Is there an icon that adds no information?** Remove it.
+5. **Is there a number/stat I made up?** Remove it or get real data.
+6. **Is there a gradient that has no brand basis?** Remove it.
+7. **Is there an SVG of a human/face I drew?** Replace with real image or honest placeholder.
+
+If any answer fails the test, fix before claiming done.
+
+## Pairs Well With
+
+- `brand-asset-protocol` — the positive counterpart (real assets, brand spec)
+- `design-direction-advisor` — when no brand context exists, recommends differentiated directions instead of falling into AI default
+- `design-taste-frontend` — base aesthetic discipline for web UI (more prescriptive; this skill is more prohibitive)
+- `high-end-visual-design` — premium aesthetic overlay

package/dist/template/.opencode/skill/brand-asset-protocol/SKILL.md

@@ -0,0 +1,222 @@
+---
+name: brand-asset-protocol
+description: Use when designing anything for a specific brand (logo, marketing site, product launch animation, branded slide deck, redesign). MUST load before producing branded visuals. Forces real logo + product image + UI screenshot fetch BEFORE any design work — color values alone are not enough for brand recognition. Includes 5-10-2-8 quality bar (5 search rounds, 10 candidates, pick 2 best, each ≥8/10).
+---
+
+# Brand Asset Protocol
+
+> Adapted from `huashu-design`. Brand recognition lives in **assets first, color second**. Generic CSS shapes can never substitute a real logo or product image.
+
+## When to Use
+
+Trigger this protocol whenever the task names a real brand or product:
+
+- "Design a launch animation for **DJI Pocket 4**"
+- "Redesign the **Stripe** dashboard"
+- "Build a landing page for **Linear**"
+- "Make a slide deck about **Anthropic Claude**"
+- Internal client work: "Design something for **our company**"
+
+If the task is generic ("design a SaaS landing page"), skip this skill — use `design-direction-advisor` instead.
+
+## Prerequisite: Verify the Brand Exists First
+
+Before fetching assets, confirm the brand/product **exists and you know its current state**. Never assert from training data — search.
+
+```
+Trigger: any specific product/version (Pocket 4, Gemini 3 Pro, new SDK, etc.)
+Action: WebSearch "<product> launch date specs 2026" → read 1-3 authoritative results
+Cost: 10 seconds. Skipping this can cost 1-2 hours of rework.
+```
+
+Forbidden phrases that signal you should search instead of guess:
+
+- ❌ "I think X hasn't launched yet"
+- ❌ "X is currently version N" (without checking)
+- ❌ "X probably doesn't exist"
+- ✅ "Let me search for the latest state of X"
+
+## Asset Hierarchy: Why Color Alone Fails
+
+| Asset                        | Recognition contribution     | Required for                              |
+| ---------------------------- | ---------------------------- | ----------------------------------------- |
+| **Logo**                     | Highest — instant ID         | **Every** branded project                 |
+| **Product photos / renders** | Very high — the "main actor" | Physical products (hardware, packaging)   |
+| **UI screenshots**           | Very high — the "main actor" | Digital products (apps, SaaS, dashboards) |
+| Color palette                | Medium — easily collides     | Supporting role                           |
+| Typography                   | Low — needs the above        | Supporting role                           |
+| Vibe keywords                | Low — internal QA only       | Supporting role                           |
+
+**Rule**: Pulling colors + fonts but skipping logo/product/UI → protocol violation. Generic placeholders, CSS silhouettes, or hand-drawn SVG cannot substitute real assets.
+
+## The 5-Step Protocol (Strict Sequence)
+
+### Step 1 — Ask (one full asset checklist, not vague "got brand guidelines?")
+
+Send this exact list:
+
+```
+For <brand/product>, which of these do you have? (priority order)
+1. Logo (SVG / high-res PNG) — required for any brand
+2. Product photos / official renders — required for physical products
+3. UI screenshots / interface assets — required for digital products
+4. Color values (HEX / RGB / palette doc)
+5. Font list (display / body)
+6. Brand guidelines PDF / Figma design system / brand site URL
+
+Send what you have; I'll fetch / generate the rest.
+```
+
+### Step 2 — Search Official Sources
+
+| Asset           | Where to look                                                                               |
+| --------------- | ------------------------------------------------------------------------------------------- |
+| **Logo**        | `<brand>.com/brand`, `/press`, `/press-kit`, `brand.<brand>.com`, header inline SVG         |
+| **Product img** | Product detail page hero + gallery, official YouTube launch film frames, press releases     |
+| **UI**          | App Store / Play Store screenshots, official site screenshots section, demo video frames    |
+| **Colors**      | Site inline CSS / Tailwind config / brand guidelines PDF                                    |
+| **Fonts**       | `<link rel="stylesheet">` references on official site, Google Fonts trace, brand guidelines |
+
+Fallback queries: `<brand> logo download SVG`, `<brand> press kit`, `<brand> <product> official renders`, `<brand> app screenshots`.
+
+### Step 3 — Download (three fallback paths per asset type)
+
+**Logo (mandatory for every brand):**
+
+```bash
+# 1. Direct file (best)
+curl -o assets/<brand>/logo.svg https://<brand>.com/logo.svg
+
+# 2. Extract inline SVG from homepage HTML (~80% of cases)
+curl -A "Mozilla/5.0" -L https://<brand>.com -o assets/<brand>/homepage.html
+# then grep <svg>...</svg> for the logo node
+
+# 3. Official social avatar (last resort): GitHub/Twitter/LinkedIn org image
+```
+
+**Product photos (mandatory for physical products):**
+
+1. Official product page hero (right-click image URL, curl it)
+2. Official press kit / press releases
+3. Launch video frames (`yt-dlp` + `ffmpeg`)
+4. Wikimedia Commons (public domain)
+5. AI generation **using the official product photo as reference** — never replace with CSS silhouettes
+
+**UI screenshots (mandatory for digital products):**
+
+- App Store / Play Store product page (note: may be marketing mockups, not real UI — verify)
+- Official site screenshots section
+- Product demo video frames
+- Official Twitter/X launch posts (often the latest version)
+- Real screenshots from your own account when possible
+
+### Step 4 — Quality Bar: The 5-10-2-8 Rule (non-Logo assets)
+
+> Logo rules differ: any logo must be used (no logo → stop and ask user). Other assets (product photos, UI, hero imagery) follow 5-10-2-8.
+
+| Dimension              | Standard                                                                                                | Anti-pattern                        |
+| ---------------------- | ------------------------------------------------------------------------------------------------------- | ----------------------------------- |
+| **5 search rounds**    | Cross-search official site / press kit / social / YouTube / Wikimedia / user account                    | First page of results, stop         |
+| **10 candidates**      | Gather at least 10 before filtering                                                                     | Grab 2, no choice                   |
+| **Pick 2 best**        | Curate 2 finals from the 10                                                                             | Use everything = visual overload    |
+| **Each ≥8/10 quality** | Below 8 → use honest placeholder or AI-generate from official reference. **Better none than mediocre.** | Pad brand-spec.md with 7/10 fillers |
+
+**8/10 scoring dimensions** (record per asset in `brand-spec.md`):
+
+1. **Resolution** — ≥2000px (≥3000px for print/large screen)
+2. **Copyright clarity** — official > public domain > free stock > unclear (unclear = 0)
+3. **Brand vibe match** — consistent with the vibe keywords in `brand-spec.md`
+4. **Lighting/composition consistency** — the 2 finals should not clash
+5. **Standalone narrative** — each asset must independently express a narrative role, not just decorate
+
+### Step 5 — Codify in `brand-spec.md` (single source of truth)
+
+```markdown
+# <Brand> · Brand Spec
+
+> Captured: YYYY-MM-DD
+> Sources: <list>
+> Completeness: complete / partial / inferred
+
+## 🎯 Core Assets (first-class)
+
+### Logo
+
+- Primary: `assets/<brand>/logo.svg`
+- Inverse: `assets/<brand>/logo-white.svg`
+- Use cases: <intro / outro / corner watermark / global>
+- Forbidden: <no stretch / no recolor / no outline>
+
+### Product Photos (required for physical products)
+
+- Hero: `assets/<brand>/product-hero.png` (2000×1500)
+- Detail: `assets/<brand>/product-detail-1.png`
+- Scene: `assets/<brand>/product-scene.png`
+
+### UI Screenshots (required for digital products)
+
+- Home: `assets/<brand>/ui-home.png`
+- Feature: `assets/<brand>/ui-feature-<name>.png`
+
+## 🎨 Supporting Assets
+
+### Palette
+
+- Primary: #XXXXXX <source>
+- Background: #XXXXXX
+- Ink: #XXXXXX
+- Accent: #XXXXXX
+- Forbidden: <colors the brand explicitly avoids>
+
+### Typography
+
+- Display: <font stack>
+- Body: <font stack>
+- Mono: <font stack>
+
+### Signature Details
+
+- <which details are taken to 120%>
+
+### Forbidden Zone
+
+- <explicit "do not" rules>
+
+### Vibe Keywords
+
+- <3-5 adjectives>
+```
+
+## Execution Discipline (after spec exists)
+
+- **All HTML must reference asset file paths from `brand-spec.md`** — no CSS silhouettes, no hand-drawn SVG substitutes.
+- **Logo as `<img>`** referencing the real file. Never redraw.
+- **Product photos as `<img>`** referencing real files. No CSS silhouettes.
+- **CSS variables injected from spec**: `:root { --brand-primary: ...; }` — HTML only uses `var(--brand-*)`.
+- This converts brand consistency from "by intent" to "by structure" — adding a new color requires editing the spec first.
+
+## Failure Fallbacks
+
+| Missing                      | Action                                                                                                                       |
+| ---------------------------- | ---------------------------------------------------------------------------------------------------------------------------- |
+| **Logo not findable**        | **Stop and ask the user.** Logo is the foundation of brand recognition. Don't fake it.                                       |
+| **Product photo (physical)** | Prefer AI generation **using official reference image** → ask user → honest placeholder ("product photo TBD") as last resort |
+| **UI screenshot (digital)**  | Ask user for screenshots from their account → official demo video frames. Don't use generic mockup generators.               |
+| **Color values**             | Run `design-direction-advisor` skill, recommend 3 directions with explicit assumption labels                                 |
+
+**Forbidden**: silently using CSS silhouettes / generic gradients when assets can't be found. **Better to stop and ask than to fake.**
+
+## Real Failures (why this protocol exists)
+
+- **Kimi animation**: Guessed "should be orange" from memory. Actual brand color: `#1783FF` blue. Full rework.
+- **Lovart design**: Mistook a demo brand color in a product screenshot for Lovart's own. Almost destroyed the entire design.
+- **DJI Pocket 4 launch animation**: Pulled colors but skipped logo + product image, used CSS silhouettes. Output was "generic black-bg + orange-accent tech animation" with zero DJI recognition. Designer's note: _"Otherwise, what are we even expressing?"_
+
+## Cost Comparison
+
+| Path                       | Time                                                                                |
+| -------------------------- | ----------------------------------------------------------------------------------- |
+| **Run protocol correctly** | Logo 5 min + product/UI 10 min + color grep 5 min + spec write 10 min = **~30 min** |
+| **Skip protocol**          | Generic output → user rework 1-2 hours, sometimes full redo                         |
+
+**The cheapest stability investment in branded design work.** For client deliverables, launch events, or important customer projects, the 30-minute protocol is insurance.

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

@@ -0,0 +1,149 @@
+---
+name: context-condensation
+description: Use when context is approaching budget limits and you need to compress, OR when handing off to another session. Provides the explicit keep/drop rubric for what survives compression — preserve goals, progress, critical files, failing tests; drop exploration noise and resolved threads. Pairs with `/dcp compress` and `/handoff`. Adapted from OpenHands context-condensation, Manus context engineering, HumanLayer backpressure.
+---
+
+# Context Condensation
+
+> Compression is not deletion — it is **selection of what survives**. The wrong selection makes the agent restart from zero. This skill defines what to keep.
+
+## When to Use
+
+- Context >100k tokens and growing
+- Phase boundary reached (research done, ready to implement)
+- Handing off to a new session via `/handoff`
+- A subagent returns large output you need to integrate
+- After `/dcp compress` ran but you still feel context drift
+
+## Core Principle: 4 Tiers of Survival
+
+Every conversation chunk falls into one of four tiers. Compress accordingly.
+
+| Tier | Content                                                  | Action                  |
+| ---- | -------------------------------------------------------- | ----------------------- |
+| 1    | Goal, constraints, user-stated requirements              | **Preserve verbatim**   |
+| 2    | Critical state — failing tests, current bug, open files  | **Preserve as summary** |
+| 3    | Decisions made, alternatives rejected, why               | **Preserve as 1-liner** |
+| 4    | Exploration noise — failed greps, dead ends, raw outputs | **Drop entirely**       |
+
+## Keep List (Always)
+
+Compress around these — never drop:
+
+- **The user's literal request.** Direct quote when short. Paraphrase only when long, and label as paraphrase.
+- **Active failures.** Current error message, failing test name + reason, open bug. Tells the next agent what's broken.
+- **Decisions + rationale.** "Chose JWT over sessions because [reason]." One line each. Future agents inherit the why.
+- **File paths currently being edited.** Exact paths, not "the auth file".
+- **Verification status.** Last typecheck/lint/test result with timestamp.
+- **Open questions for the user.** Questions awaiting human input.
+- **Constraints discovered mid-task.** "User can't add new deps", "DB is read-only in this env".
+
+## Drop List (Aggressive)
+
+Compress these to a single line or remove entirely:
+
+- **Resolved exploration.** Found the file? Drop the 5 greps that led there.
+- **Tool output noise.** Full directory listings, `ls` outputs, package install logs. Keep only the relevant filename.
+- **Verbose reasoning.** Your own multi-paragraph thinking that ended in one decision. Keep the decision.
+- **Acknowledgments.** "Got it", "I'll do that next" — pure social filler.
+- **Failed attempts that taught nothing.** If a wrong approach added no information, drop it. Keep failures that revealed a constraint.
+- **Sub-agent self-reports.** Keep the result + verification, drop the agent's narrative summary (Worker Distrust Protocol — don't trust the prose).
+- **Old plans you've since revised.** Keep only the current plan.
+
+## Failure Preservation Rule
+
+> **Useful failures stay. Useless failures go.**
+
+A failure is **useful** if it:
+
+- Revealed a constraint ("can't use `mv` on this filesystem")
+- Eliminated a hypothesis ("the bug is not in the parser")
+- Showed a trap that another agent would re-fall into
+
+A failure is **useless** if it:
+
+- Was a typo / fat-finger fixed immediately
+- Was a tool-call format error with no semantic content
+- Was an obvious dead end no agent would repeat
+
+**Manus rule** (from "Context Engineering for AI Agents: Lessons from Building Manus"): keep useful failures **in-context** as warnings. Don't compress to "encountered errors then succeeded" — that loses the warning.
+
+## Condensation Triggers (Beyond Token Count)
+
+Token count is one trigger. These are the others:
+
+| Trigger                               | Action                                          |
+| ------------------------------------- | ----------------------------------------------- |
+| Phase boundary (research → implement) | Compress all of research phase to summary       |
+| Subagent returns >2k tokens           | Compress immediately, keep result + evidence    |
+| Same question asked twice in session  | Indicates context drift — compress aggressively |
+| Plan revised                          | Drop old plan completely                        |
+| Conversation feels "lost"             | Compress; restart from goal + current state     |
+
+## The Handoff Variant
+
+When compressing for `/handoff` (different session, different agent will pick up), be **even more selective**:
+
+- Preserve everything in Keep List
+- Add a **`## Next Step`** with the literal next action
+- Add a **`## Don't Re-Discover`** with traps already mapped
+- Drop everything else
+
+Handoff format:
+
+```markdown
+## Goal
+
+[user's literal request]
+
+## Status
+
+- Done: [list of completed items with file:line]
+- In progress: [current task]
+- Blocked: [what's blocking, what was tried]
+
+## Critical State
+
+- Open files: [paths]
+- Last verification: [command + result + timestamp]
+- Active failures: [error / failing test]
+
+## Decisions Made
+
+- [one-liner] → [one-line rationale]
+
+## Don't Re-Discover
+
+- [trap 1]: [why]
+- [trap 2]: [why]
+
+## Next Step
+
+[literal next action — copy-pastable command or description]
+```
+
+## Anti-Patterns
+
+- **"Let me summarize what we did so far..."** in every response — you're re-summarizing instead of compressing once at boundaries
+- **Dropping the goal during compression** — the worst failure mode; the next agent has no anchor
+- **Keeping all failures** — context fills with noise, real signals get buried
+- **Lossy paraphrase of user request** — when in doubt, quote verbatim
+- **Compressing during active edits** — wait for atomic step to finish
+
+## Integration
+
+- **Before `/dcp compress`:** Use this rubric to decide what your `summary` field should contain
+- **In `/handoff`:** This skill defines the handoff format
+- **After subagent return:** Apply Drop List to the agent's narrative, keep result + verification only
+- **In long sessions:** Re-read your own context every ~30 messages and apply the rubric
+
+## Output
+
+When you condense, briefly state what survived and what dropped:
+
+```
+Compressed messages 12-34. Kept: goal, 3 decisions, current failure (auth.ts:42 null deref).
+Dropped: 5 file searches, 2 abandoned approaches, dir listings.
+```
+
+This makes the compression auditable. The user (or next agent) can challenge what got cut.