opencodekit 0.21.9 → 0.22.0

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

@@ -1,208 +0,0 @@
----
-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

@@ -1,76 +0,0 @@
----
-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/augment-context-engine/SKILL.md

@@ -1,122 +0,0 @@
----
-name: augment-context-engine
-description: Semantic codebase search via Augment Context Engine MCP. Use when you need to understand code relationships, find relevant implementations, or explore unfamiliar codebases beyond keyword matching.
-version: 1.0.0
-tags: [research, context]
-dependencies: []
----
-
-# Augment Context Engine (MCP)
-
-## When to Use
-
-- When you need semantic search to understand code relationships or find implementations beyond keyword matching.
-
-## When NOT to Use
-
-- When exact string matching or known file paths can be handled by grep/read/LSP locally.
-
-
-## Available Tools
-
-- `augment_code_search` - Semantic search across indexed GitHub repositories
-
-**Parameters:**
-
-- `repo_owner` (string, required) - GitHub org or username (e.g. `"augmentcode"`)
-- `repo_name` (string, required) - Repository name (e.g. `"test-repo"`)
-- `query` (string, required) - Natural language description of what you're looking for
-- `branch` (string, optional) - Branch to search (defaults to `"main"`)
-- `max_results` (integer, optional) - Max code snippets to return (defaults to 5)
-
-## Quick Start
-
-```
-# Search a GitHub repo for authentication code
-skill_mcp(skill_name="augment-context-engine", tool_name="augment_code_search", arguments='{"repo_owner": "myorg", "repo_name": "myapp", "query": "authentication middleware that validates JWT tokens"}')
-
-# Search a specific branch with more results
-skill_mcp(skill_name="augment-context-engine", tool_name="augment_code_search", arguments='{"repo_owner": "myorg", "repo_name": "myapp", "query": "error handling patterns", "branch": "develop", "max_results": 10}')
-```
-
-> **Tip:** Get `repo_owner` and `repo_name` from git: `git remote get-url origin`
-
-## Setup
-
-### 1. Install the Augment GitHub App
-
-Install at [github.com/apps/augmentcode](https://github.com/apps/augmentcode/installations/new) and grant access to the repos you want to index.
-
-### 2. Add the remote server
-
-The skill's `mcp.json` uses `mcp-remote` to bridge the remote API via stdio.
-
-For global access, add to `~/.config/opencode/opencode.json`:
-
-```json
-{
-  "$schema": "https://opencode.ai/config.json",
-  "mcp": {
-    "auggie": {
-      "type": "remote",
-      "url": "https://api.augmentcode.com/mcp",
-      "enabled": true
-    }
-  }
-}
-```
-
-### 3. Authenticate
-
-Sign in at [app.augmentcode.com](https://app.augmentcode.com) when prompted by `mcp-remote` on first use.
-
-## Query Tips
-
-Good queries (natural language, conceptual):
-
-- `"function that handles user authentication"`
-- `"database connection setup code"`
-- `"tests for the payment processing module"`
-
-Bad queries (use grep instead):
-
-- `"foo_bar"` — exact symbol search
-- `"TODO"` — keyword search
-- `"code that deals with everything"` — too vague
-
-## When to Use
-
-| Scenario                 | Use This              | Instead Of                 |
-| ------------------------ | --------------------- | -------------------------- |
-| Find code by meaning     | `augment_code_search` | `grep` (text only)         |
-| Understand relationships | `augment_code_search` | `@explore` agent (heavier) |
-| Unfamiliar codebase      | `augment_code_search` | Manual file exploration    |
-| Cross-repo dependencies  | `augment_code_search` | LSP references (narrower)  |
-
-## When NOT to Use
-
-- **Exact string matching** — Use `grep` instead (faster, free)
-- **Known file paths** — Use `read` directly
-- **Symbol definitions** — Use LSP `goToDefinition` (precise)
-- **Local-only work** — This searches GitHub-indexed repos, not local files
-
-## Tool Priority Integration
-
-```
-grep (text) → semantic search (meaning) → read (full file) → LSP (symbols) → edit
-```
-
-Use grep first for exact matches. Escalate to semantic search when grep results are noisy or you need conceptual understanding.
-
-## Cost
-
-- ~40-70 credits per query
-- Not free — use judiciously
-- Prefer grep for simple lookups
-
-## Resources
-
-- Docs: https://docs.augmentcode.com/context-services/mcp/overview
-- OpenCode Quickstart: https://docs.augmentcode.com/context-services/mcp/quickstart-open-code
-- GitHub App: https://github.com/apps/augmentcode/installations/new
-- Product: https://www.augmentcode.com/product/context-engine-mcp

package/dist/template/.opencode/skill/augment-context-engine/mcp.json

@@ -1,6 +0,0 @@
-{
-	"augment-context-engine": {
-		"command": "npx",
-		"args": ["-y", "mcp-remote", "https://api.augmentcode.com/mcp"]
-	}
-}

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

@@ -1,222 +0,0 @@
----
-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.