@softspark/ai-toolkit 4.8.0 → 4.10.0

package/app/skills/brand-voice/SKILL.md

@@ -74,6 +74,7 @@ Also loaded when a project sets `output-mode: concise` or `output-mode: strict`
 | **Active over passive** | "The function returns X" not "X is returned by the function." |
 | **Technical over casual** | Match the audience's expertise. Never dumb down for developers. |
 | **Honest over promotional** | State limitations alongside strengths. |
+| **Accountable over apologetic** | Own a mistake once, fix it, move on. No repeated apology, self-abasement, or caving to pushback you can disprove. |
 
 ## Sentence-Level Rules
 
@@ -82,6 +83,13 @@ Also loaded when a project sets `output-mode: concise` or `output-mode: strict`
 - **One idea per sentence.** If a sentence has "and" linking two distinct ideas, split it.
 - **Use concrete subjects.** Bad: "It is important to note that..." Good: (delete the phrase, state the fact)
 
+## Formatting Discipline
+
+- **Default to prose.** Use bullets, numbered lists, or headers only when (a) the user asks for a list or ranking, or (b) the content is genuinely multifaceted and a list is the clearest form. A list of one or two items is a sentence — write the sentence.
+- **Every bullet carries content.** Each bullet is at least one full clause, usually one to two sentences. A one-word bullet is a sentence in disguise.
+- **Match format to document type.** Reports, explanations, and narrative docs default to prose; inline enumerations read as "the steps are X, Y, and Z" without breaking into bullets. Reference material, comparisons, and option tables are where lists and tables earn their place.
+- **Minimum formatting for clarity.** Reach for the lightest structure that makes the content clear. Headers, bold, and nesting are tools, not decoration.
+
 ## Before Publishing Checklist
 
 - [ ] No banned phrases from anti-trope list?
@@ -107,7 +115,7 @@ potential of your workflow.
 Good (direct, specific, active):
 
 ```
-ai-toolkit installs 99 skills and 44 agents via `npm install -g @softspark/ai-toolkit`.
+ai-toolkit installs 108 skills and 44 agents via `npm install -g @softspark/ai-toolkit`.
 After install, run `ai-toolkit doctor` to verify symlinks and hooks. Typical
 install takes under 30 seconds on a local disk.
 ```
@@ -120,6 +128,7 @@ install takes under 30 seconds on a local disk.
 - **NEVER** use em dashes or en dashes in prose — they signal LLM output. Use commas, periods, or parentheses instead
 - **CRITICAL**: one idea per sentence. If you write "and" linking two distinct ideas, split the sentence
 - **MANDATORY**: technical claims include a concrete number, name, or example — never assert quality without evidence
+- **NEVER** format a refusal, a "no", or a correction as bullet points — prose carries it with less abruptness
 
 ## Output Modes
 

package/app/skills/brand-voice/modes/concise.md

@@ -64,4 +64,7 @@ Token ratio: 76 → 25 = 33%.
 
 - If a question genuinely needs 30 lines to answer, write 30. Don't truncate facts to hit the budget.
 - If the user asks "explain", give one solid paragraph, not a one-liner.
+- A request for a long or detailed answer overrides the mode. Suspend the budget for that response and answer in full.
+- Mode quality applies to prose only. Code, diffs, configs, and generated artifacts keep full quality and completeness regardless of mode — never trade correctness for brevity.
+- Name the mode only if the user objects to the length or asks why responses are short. Then say it is `output-mode: concise` and that `/brand-voice default` resets it. Otherwise never mention the mode.
 - If unsure whether the user wants depth, ask. One question is cheaper than a wrong-length response.

package/app/skills/brand-voice/modes/strict.md

@@ -88,4 +88,6 @@ Recommend: Postgres.
 
 - Strict mode does NOT mean wrong. If a fact requires 5 lines to be correct, write 5 lines. Cut framing, never substance.
 - Strict mode does NOT mean rude. Drop pleasantries, not respect.
+- Code, diffs, configs, and generated artifacts are never abbreviated for the budget. Strict trims prose, never output the user will run or ship.
 - If the user explicitly asks for explanation, switch to concise mode for that response. Strict is the default, not a gag.
+- Name the mode only if the user objects to the terseness or asks about it. Then say it is `output-mode: strict` and that `/brand-voice default` resets it. Otherwise stay silent about the mode.

package/app/skills/deep-research/SKILL.md

@@ -0,0 +1,97 @@
+---
+name: deep-research
+description: "Multi-source web research methodology: retrieve-vs-answer gate, complexity-scaled search budget, query craft, primary-source preference, source-conflict skepticism, adversarial verification, attribution-without-reproduction. Triggers: deep research, multi-source, web research, synthesize sources, cross-reference, fact synthesis, source verification."
+user-invocable: false
+allowed-tools: Read
+---
+
+# Deep Research
+
+This is the web / multi-source counterpart to `research-mastery`. That skill is KB-first: it answers from the project's own knowledge base and only reaches outward when the KB comes up empty. This one governs what happens once you are already out on the open web pulling from many independent sources and have to weave them into one trustworthy answer. It is a method, not a fetcher — it does not retrieve anything by itself. You supply the search and fetch tools (built-in `WebSearch` / `WebFetch`, or the runtime `deep-research` command); this skill tells you how to spend them and how hard to doubt what comes back.
+
+## Retrieve-vs-Answer Gate
+
+Run this gate before you spend a single search:
+
+1. **Is the answer already in the KB or your own context?** Then this is not a deep-research job — hand it to `research-mastery` (which checks RAG-MCP first) or just answer.
+2. **Is it one stable fact** with a single obvious authority (a constant, a published spec value, a definition that does not move)? One targeted lookup, confirm, done. Do not open a research campaign.
+3. **Does it need several independent sources reconciled, or is it contested, recent, or moving?** That is the case this skill exists for. Continue.
+
+Skipping this gate is the most common failure: people fan out ten searches on a question that one source already settled, or worse, answer a contested question from memory because it "felt known."
+
+## Scale Effort to Complexity
+
+Match the search budget to the question. Burning twenty searches on a lookup wastes turns; doing two searches on a contested synthesis ships a half-checked claim.
+
+| Question shape | Plan first? | Rough search budget |
+|----------------|-------------|---------------------|
+| Single stable fact, clear authority | no | 1, maybe a second to confirm |
+| Compare a few known options / current state of one topic | light | a handful, broaden then narrow |
+| Contested, multi-faceted, or "what is the latest on…" | yes — write the plan | many, with follow-ups as conflicts surface |
+
+For anything in the bottom two rows, write a short research plan first: name the sub-questions, the kind of source that would answer each, and what "done" looks like. The plan is for you; keep it tight. Then let conflict drive the count — if sources disagree, you have not searched enough yet.
+
+## Query Craft
+
+- **Broaden, then narrow.** Open with a short, plain query to map the landscape; tighten with specific terms once you see what vocabulary the good sources actually use. Long kitchen-sink queries on the first try usually return noise.
+- **Use the real current date.** Anchor "recent", "latest", "current" to today's actual date — never to your training cutoff. For 2026-06-15, "latest" means 2026, not 2024. A query that silently assumes an old year is a wrong query.
+- **Vary the angle on a stubborn question.** If one phrasing returns thin or repetitive results, change the wording, the framing, or the assumed source type rather than re-running near-identical strings.
+
+## Source Preference and Skepticism
+
+- **Prefer primary and original sources.** Go to the spec, the paper, the official docs, the filing, the dataset, the person who actually said it — not a blog summarizing a blog summarizing it. Each hop away from the origin adds a chance for drift.
+- **A surprising-but-sourced result is usually real.** If a credible primary source says something counterintuitive, treat it as true and report it. Do not soften or discard a well-attributed fact just because it clashes with your prior.
+- **The exception: low-trust topic zones.** On SEO-spam-saturated queries, conspiracy-adjacent claims, and topics with genuinely no expert consensus, raise the bar instead of lowering it. Here a surprising claim needs strong independent corroboration before you repeat it, and "many pages say it" is not corroboration when those pages copy each other.
+- **Conflict means search more.** When two solid sources disagree, that is a signal to run additional searches and find a tie-breaker or the underlying primary source — not to average them, pick the one you like, or paper over the disagreement.
+
+## Adversarial Verification
+
+Before you emit any synthesized claim, run this self-check. Each gate has a fix; do not just notice the problem.
+
+| Self-check gate | If yes, do this |
+|-----------------|-----------------|
+| Am I mirroring one source's exact phrasing or structure? | Re-state it in your own words from the facts, not the prose. |
+| Could my output stand in for reading the original — same length, same order, same examples? | Cut it back. Summarize and point to the source; do not reproduce it. |
+| Have I already leaned on this one source for several claims? | Find an independent source, or flag the answer as single-sourced. |
+| Is each claim independently corroborated, or is one shaky source carrying the conclusion? | Corroborate it, drop it, or label it as unconfirmed. |
+
+For **high-stakes claims** — anything affecting money, health, legal exposure, security posture, or an irreversible decision — do not stop at one source. Confirm with a second, independent source or a different angle of approach before you state it as fact.
+
+## Citation Discipline
+
+- **Paraphrase by default, and attribute to a named source.** "Per the FY2025 10-K…", "the RFC's section on retries states…". The reader should always know who is behind a claim.
+- **Reserve verbatim quotes for genuinely distinctive phrasing** — a definition, a legal clause, an exact figure where the wording itself matters. Keep quotes short and clearly marked. Do not quote at length to fill space.
+- **Keep any single source's paraphrased footprint small.** No one source's material should dominate your output, and the output as a whole must never substitute for reading the originals. You are pointing readers to the sources, not republishing them.
+- **NEVER invent an attribution.** If you are not sure a source actually said something, leave the claim out. A fabricated citation is worse than a missing one — it launders a guess as a fact.
+- **Empty retrieval is a real result.** If a search returns nothing usable, say "not found in available sources" and cite nothing. Do not backfill from memory and dress it up as retrieved.
+
+## Example
+
+**Task:** "What is the current recommended approach for X, and has it changed recently?"
+
+1. **Gate.** Not in KB, contested, has a "recently" — this is a deep-research job. Write a 3-line plan: (a) current recommendation, (b) what it replaced, (c) when/why it changed.
+2. **Broaden.** Plain query anchored to the real date ("X recommended approach 2026"). Map who the authoritative voices are.
+3. **Narrow to primary sources.** Open the official docs / spec / changelog rather than roundup posts. Pull the version and date where the guidance changed.
+4. **Conflict surfaces.** One source still recommends the old approach. Run more searches; find the changelog entry that supersedes it. The disagreement was stale-vs-current, not a genuine split — note that.
+5. **Adversarial pass.** Re-check each gate: paraphrase in own words (not mirroring the docs' structure), confirm the change claim against a second independent source since it drives the answer, confirm no single source carries everything.
+6. **Synthesize with attribution.** "The official docs as of <date> recommend …; this replaced … per the <date> changelog." Short, sourced, original phrasing, none of it a stand-in for the docs themselves.
+
+## Rules
+
+- **MUST** pass the retrieve-vs-answer gate before searching — KB-answerable or single-fact questions do not start a research campaign.
+- **MUST** scale the search budget to question complexity and write a plan for contested or multi-faceted questions.
+- **MUST** anchor every "latest / current / recent" query to the real current date, never the training cutoff.
+- **MUST** prefer primary and original sources over second-hand summaries.
+- **MUST** run more searches when credible sources conflict — never average, cherry-pick, or hide the disagreement.
+- **MUST** run the adversarial self-check before emitting a synthesized claim, and apply the corrective action when a gate trips.
+- **MUST** verify high-stakes claims (money, health, legal, security, irreversible) against an independent second source or angle.
+- **NEVER** fabricate an attribution; if unsure a source said it, omit the claim.
+- **NEVER** let one source's paraphrased footprint dominate, and never let the output substitute for reading the originals.
+- **CRITICAL**: on empty retrieval, declare "not found in available sources" and cite nothing — do not backfill from memory.
+- **Authorized security work is in scope.** For sanctioned defensive analysis, CTF, vulnerability research, or pentest engagements, research and report on attack techniques, CVEs, exploit mechanics, and adversary tradecraft normally — the skepticism rules raise source quality, they do not gate legitimate security topics.
+
+## When NOT to Use
+
+- For a **single stable fact** already in the project KB or answerable in one lookup — use `research-mastery` (KB-first hierarchy) instead, or just answer.
+- For **library / framework / API documentation** — query `context7` (or `research-mastery`'s MCP tier) for current docs rather than fanning out on the open web.
+- When you need a tool that **actually fetches** — this skill is methodology only. Pair it with `WebSearch` / `WebFetch` or the runtime `deep-research` command; it retrieves nothing on its own.

package/app/skills/design-engineering/SKILL.md

@@ -16,6 +16,64 @@ Based on Emil Kowalski's design engineering philosophy — UI polish, component
 - **Invisible details create love.** Most UI refinements users never consciously register — but combined they produce something stunning.
 - **Beauty differentiates.** When functionality is table stakes, aesthetic excellence becomes genuine leverage.
 
+## Anti-Slop Visual Checklist
+
+Defaults that signal machine-generated UI. Each is a falsifiable thing to avoid:
+
+- **Avoid** full-bleed saturated gradient backgrounds (purple-to-pink hero washes). A flat surface or a near-flat tonal shift reads as intentional; a loud gradient reads as a template.
+- **Avoid** emoji as load-bearing decoration — emoji standing in for icons, bullet markers, or section badges. Use a real icon set or typographic hierarchy instead.
+- **Avoid** the rounded-card-with-left-accent-border cliche repeated across every block. If three sections share that exact treatment, vary the layout or drop the accent.
+- **Avoid** hand-drawn fake imagery in SVG (synthetic "photos", invented logos, faux screenshots). Use a real asset or an honest labeled placeholder.
+- **Avoid** the overused default font stack (Inter/Roboto on system-ui for everything with no scale or weight intent). Pick type with a reason and lift the actual stack from source when one exists.
+
+## Minimum-Scale Floors
+
+Accessibility-grounded hard thresholds. Going below these is a defect, not a style choice:
+
+| Context | Floor | Basis |
+|---|---|---|
+| Slide / presentation body text | ~24px | Readable from the back of a room |
+| Print body text | ~12pt | Legible at arm's length on paper |
+| Mobile touch targets | 44px × 44px | Apple HIG minimum tappable size |
+
+Treat these as the lower bound, not the target. Captions and footnotes may approach the floor; primary content should sit comfortably above it.
+
+## Context-First Discipline
+
+High-fidelity work MUST be rooted in real context before any pixels are produced. This mirrors the toolkit's verify-don't-recall ethos:
+
+- **Read the source first.** Inspect the codebase, design tokens, UI kit, and screenshots that already exist before generating anything.
+- **Lift exact values.** Copy real hex codes, the spacing scale, the font stack, and radii straight from source. Do NOT reconstruct token values from memory — recalled values drift.
+- **Mock from scratch only as a last resort.** Building a screen with no reference is the fallback when no codebase, kit, or screenshot exists, not the default.
+
+## Question-Budget Gate
+
+Calibrate questions to how bounded the ask is, then proceed:
+
+- **Rich context + bounded ask** → ask nothing, build. Example: "match this card to the existing dashboard" with the repo in hand.
+- **Open ask** → ask before building. Example: "prototype my onboarding" needs goals, target audience, and which dimension to diverge on (UX flow vs. visual treatment vs. copy). Resolve those three, then start.
+
+## Explore Many Variations
+
+For exploratory or open work, produce **3+ atomic variations** across distinct axes, never three tweaks of one idea:
+
+- Vary on different dimensions: layout, color, type treatment, interaction model.
+- Deliberately mix safe matches with at least one novel direction — do not converge early.
+- Order them basic → advanced so the reviewer can scan the gradient (the "Design It Twice" premise extended past two).
+
+## Match Existing Vocabulary
+
+When editing a live UI, conform to it instead of imposing a new style:
+
+- Reverse-engineer the palette, interactive states (hover/active/disabled), motion timing, and shadow/card/density treatment.
+- Match the copy tone too — terse product UI and chatty marketing copy are different vocabularies.
+- A change that introduces a foreign style is a regression even when it looks good in isolation.
+
+## No-Filler Content
+
+- **Every element earns its place.** No dummy stats, decorative sections, or lorem blocks added just to fill space. If a block has no purpose, cut it.
+- **Honest placeholder beats a bad fake.** A labeled placeholder ("[product screenshot]") is better than an invented icon or hand-drawn fake image. Do NOT fabricate assets — ask for the real ones.
+
 ## Animation Decision Framework
 
 ### Frequency determines approach
@@ -248,6 +306,13 @@ Deliberate actions stay slow (2s linear for hold-to-delete), system responses sn
 | Identical enter/exit speed | Make exit faster (e.g., 2s enter, 200ms exit) |
 | Simultaneous element appearance | Stagger 30-80ms between items |
 
+## Two-Stage Verification Handoff
+
+Visual work ships through two passes, mirroring the toolkit's verification-before-completion and subagent two-stage review ethos:
+
+1. **Cheap self-check.** Load the rendered result yourself, eyeball it, and fix the obvious breaks (broken layout, wrong token, console errors) before handing off. Never claim done on output you have not opened.
+2. **Independent verifier pass.** A separate reviewer (or fresh subagent) does the deeper check — visual fidelity against source, layout under different widths, console clean. On pass it stays silent; it surfaces ONLY on failure, with the specific defect.
+
 ## Anti-Patterns
 
 - `transition: all` — animates unintended properties, hurts performance
@@ -265,6 +330,14 @@ Deliberate actions stay slow (2s linear for hold-to-delete), system responses sn
 - **NEVER** add motion for decorative reasons alone — every animation must serve meaning (status change, spatial relationship, progress)
 - **CRITICAL**: exit is faster than enter. A 2s linear enter (hold-to-delete) needs a 200ms ease-out exit. Symmetrical durations feel sluggish.
 - **MANDATORY**: any animation longer than 300ms for UI feedback needs an explicit justification — the user perceives >300ms as "laggy", not "smooth"
+- **MUST** lift exact values (hex, spacing, font stack, radii) from the real codebase, tokens, UI kit, or screenshots before high-fidelity work — never reconstruct token values from memory; mock from scratch only when no source exists
+- **MUST** keep slide body text at ~24px+, print at ~12pt+, and mobile touch targets at 44px+ — these are accessibility floors, not preferences
+- **NEVER** ship the slop defaults — saturated full-bleed gradients, emoji as decoration, repeated rounded-card-with-accent-border, hand-drawn fake imagery in SVG, or the unconsidered default font stack
+- **NEVER** add filler (dummy stats, decorative sections, lorem) to fill space, and never fabricate assets — an honest labeled placeholder beats an invented icon or fake image; ask for the real one
+- **MUST** match the existing UI's vocabulary (palette, states, motion, shadow/density, copy tone) when editing a live surface instead of imposing a new style
+- **MUST** ask about goals, audience, and which dimension to diverge on (UX vs. visuals vs. copy) before building an open-ended ask; skip questions only when context is rich and the ask is bounded
+- **CARVE-OUT**: a sanctioned design audit, accessibility-failure demonstration, or authorized red-team mockup may deliberately reproduce a slop pattern or sub-floor scale to illustrate the defect — label it as such; the bans above target shipped UI, not sanctioned analysis
+- **SHOULD** produce 3+ atomic variations across distinct axes (layout, color, type, interaction), ordered basic → advanced, for any exploratory or open design ask
 
 ## Gotchas
 

package/app/skills/mcp-builder/SKILL.md

@@ -77,10 +77,13 @@ Example eval questions for a `github-mcp`:
 2. "Create an issue titled Y in repo Z"
 3. "Who has the most commits this month in repo X?"
 
+When a tool fails an eval, the cause is almost always the description, not the schema. Score each tool against the description rubric in `mcp-patterns` (one-line purpose, WHEN TO USE, WHEN NOT TO USE, CRITICAL, self-test). A tool with an empty **WHEN NOT TO USE** is under-specified — it will misfire the moment a second tool in the same server overlaps with it, so add the boundary before re-running the eval. See `mcp-patterns` → "How to Write a Tool Description" for the full rubric and worked example.
+
 ## Tool Design Checklist
 
 - [ ] Name has service prefix and is verb-led
 - [ ] Description mentions when to use it and includes trigger keywords
+- [ ] Description carries a non-empty **WHEN NOT TO USE** that names overlapping tools (see `mcp-patterns` rubric)
 - [ ] Input schema is strict, no free-form `object` with `additionalProperties: true`
 - [ ] Output is focused — essential fields only, with pagination cursor if applicable
 - [ ] Error responses are actionable ("API returned 403 — check `GITHUB_TOKEN` env var")

package/app/skills/mcp-patterns/SKILL.md

@@ -66,6 +66,64 @@ server.setRequestHandler(ListToolsRequestSchema, async () => ({
 
 ---
 
+## How to Write a Tool Description
+
+The `description` is the only signal the model uses to route a request. The schema constrains the *call*; the description decides *whether the call happens at all*. Treat it as a routing contract, not API prose. A good one has five parts, in this order:
+
+1. **One-line purpose** — what the tool does, in plain terms. Lead with a verb. `Search indexed knowledge-base documents and return ranked passages.` Skip the HTTP verb and endpoint; `calls GET /v2/search` tells the model nothing about intent.
+2. **WHEN TO USE** — concrete trigger phrasings the user might say, not abstract categories. List the actual shapes: *"find docs about X", "what does the KB say about Y", "look up the runbook for Z"*. Models match on surface form, so give them surface forms.
+3. **WHEN NOT TO USE** — the section that does most of the disambiguation work. Name the near-miss tools and the boundary that separates them. This is where you prevent the model from firing the wrong tool on a request that *looks* similar. Empty WHEN NOT TO USE = the tool is under-specified.
+4. **CRITICAL** — one line for the single non-obvious failure mode. The constraint a reader would not guess from the schema: a required ordering, an ID that must come from another call, a cost/irreversibility warning. One line, not a checklist.
+5. **Self-test** — close with a question the model can apply to itself to decide fit. `Ask: is the user looking up existing content, or asking me to create new content? This tool is read-only — if they want to create, stop.`
+
+### Why negative examples outweigh positive ones
+
+Positive triggers tell the model when a tool *could* apply; negative ones are what stop it firing on overlapping requests. When two tools have similar purposes (`search_kb` vs `search_code`, `get_document` vs `list_documents`), the only thing keeping the model off the wrong one is each description naming the other and drawing the line. Budget more words for the boundary than the bullseye.
+
+### Disambiguating near-miss tools
+
+When tools overlap, make each WHEN NOT TO USE point at its neighbour and state the discriminator explicitly:
+
+```text
+search_kb
+  WHEN NOT TO USE: do not use to fetch a document you already have the id for —
+    that is get_document. Use search_kb only when you need to discover *which*
+    document, by meaning or keyword.
+
+get_document
+  WHEN NOT TO USE: do not use to find a document by topic or keyword — you must
+    already hold an exact id (from search_kb results). For discovery, use search_kb.
+```
+
+### Worked example
+
+```text
+name: cancel_workflow
+description: |
+  Stop a running agent workflow and discard its in-flight results.
+
+  WHEN TO USE: the user says "cancel the workflow", "stop run abc123",
+    "kill that job", or asks to halt a workflow that get_workflow_status
+    reports as RUNNING.
+
+  WHEN NOT TO USE:
+    - To inspect progress without stopping — use get_workflow_status.
+    - To start a fresh run — use start_workflow.
+    - On a workflow already in a terminal state (COMPLETED/FAILED) — the call
+      is a no-op and signals the model misread the status.
+
+  CRITICAL: cancellation is irreversible and drops partial output. Confirm the
+    workflowId came from list_workflows or get_workflow_status — never type one
+    from memory.
+
+  Self-test: am I stopping work that is genuinely still RUNNING, or did I confuse
+  "check status" with "cancel"? If I have not seen a RUNNING status, do not call this.
+```
+
+A description that survives this rubric routes correctly without the model reading your source. One that skips WHEN NOT TO USE will misfire the moment a second, similar tool exists in the same server.
+
+---
+
 ## Transport Patterns
 
 ### 1. stdio (Default)

package/app/skills/research-mastery/SKILL.md

@@ -43,6 +43,55 @@ You MUST search in this order. Do not skip steps.
 **Why**: Fallback for general programming concepts.
 **Rule**: Use only for generic syntax/logic, NEVER for project specifics.
 
+## 🚦 Retrieve-vs-Answer Gate
+
+Before you reach for any tool, decide whether retrieval is even warranted. Two axes settle it:
+
+- **Volatility** — how fast does the true answer change?
+  - *Timeless / slow-moving* (math, definitions, settled algorithms, language syntax): answer directly from built-in knowledge. A search adds latency and noise.
+  - *Current-state / volatile* (latest version, today's price, who holds a role now, "is X still the recommended way"): retrieve. Your training data is a snapshot and will lie about the present.
+- **Recognition** — can you place the entity?
+  - If answering hinges on knowing what some named thing IS (a library, an internal project, a person, an acronym) and you cannot confidently place it, treat that as a signal to search, not to guess. An unfamiliar name is a retrieval trigger, not a hallucination prompt.
+
+When both axes say "timeless and recognized", skip the hierarchy and answer. Otherwise, enter it at Step 1.
+
+## 📊 Complexity-Scaled Retrieval Budget
+
+Match effort to the question. Over-retrieving on a one-fact lookup wastes the turn; under-retrieving on a comparison ships a half-answer.
+
+| Question shape | Rough budget |
+|---|---|
+| Single discrete fact ("which version", "default port") | ~1 lookup |
+| Medium question, one entity, a couple of angles | a few lookups |
+| Deep comparison, multiple entities or trade-offs | more lookups, broaden then narrow |
+
+**Escalation handoff** — when a question genuinely needs sustained fan-out (many sources, cross-checking, adversarial verification, a synthesized report), stop expanding inline. Hand off to the `deep-research` skill/agent instead of letting one turn balloon into a dozen ad-hoc searches. Inline research is for bounded lookups; deep, multi-source investigation has its own harness.
+
+## 🧭 Internal-First Source Ladder
+
+The Hierarchy of Truth above already puts KB first — that order stands. Add a routing heuristic on top:
+
+- **Possessive / company language routes inward.** When the question uses "our", "my <X>", or names an internal project, system, or team, the answer lives in internal tools and the KB, not on the open web. Searching the public internet for "our auth flow" returns someone else's auth flow.
+- **Name the missing source; do not silently fall back.** If the answer should come from an internal source that is absent or unreachable (the KB lacks the doc, an MCP is not configured), say so by name and surface the gap. Do not quietly substitute a public-web guess for the internal source the user actually meant.
+
+## ✍️ Query Craft
+
+- **Keep queries short.** A few keywords beat a full sentence; retrieval engines reward focused terms, not prose.
+- **Broaden, then narrow.** Open with a wider query to map the space, then tighten toward the specific answer once you see the landscape.
+- **Never repeat a near-identical query.** If a search disappointed, change the angle or vocabulary — re-running the same words returns the same misses and burns budget.
+- **Fetch the full source over snippets.** When a result looks load-bearing, pull the whole document rather than reasoning from a one-line excerpt that may strip the qualifier that matters.
+- **Use the ACTUAL current date for date-sensitive queries.** When recency matters, anchor on today's real date at query time — read it from the environment, do not hardcode a year. A baked-in or stale year quietly filters you onto last year's results.
+
+## 🔬 Source Skepticism & Conflict Handling
+
+- **Prefer primary and original sources.** Go to the spec, the changelog, the official docs, the author — not a blog summarizing a summary.
+- **Lead with the most recent for fast-moving topics.** When the subject changes quickly, weight newer sources first; an old top-ranked page can be confidently wrong about the present.
+- **When sources conflict, search more.** Disagreement is a signal to widen the search and find the tie-breaker, not to pick the first hit and move on.
+- **Stay skeptical where the web is gamed.** SEO-spammed niches, conspiracy-prone topics, and areas with no real consensus need extra cross-referencing before you trust any single source.
+- **Confabulation guard — zero results means zero citations.** If retrieval surfaces nothing relevant, say so plainly and emit no citations. Never invent a `[PATH: kb/...]`, a URL, or a quote to fill the gap. An honest "not found" beats a fabricated source.
+
+> Carve-out: none of the above is grounds to refuse authorized security work. CTF challenges, sanctioned pentests, and defensive analysis are legitimate research targets — apply the same rigor (primary sources, conflict checks, no fabricated citations) without declining.
+
 ## Local Fallback (No MCP Available)
 
 If `rag-mcp` is not configured, fall back to filesystem tools — still inside `kb/`:

package/app/skills/security-patterns/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: security-patterns
-description: "App security: OWASP, authN/authZ, input validation, secrets, TLS, CSRF/XSS/SQLi, JWT, CSP. Triggers: security, OWASP, auth, JWT, CSRF, XSS, SQL injection, secrets, TLS, CSP, CORS."
+description: "App security: OWASP, authN/authZ, input validation, secrets, TLS, CSRF/XSS/SQLi, JWT, CSP, LLM prompt injection. Triggers: security, OWASP, auth, JWT, CSRF, XSS, SQL injection, secrets, TLS, CSP, CORS, prompt injection, LLM output trust, tool permissions."
 effort: medium
 user-invocable: false
 allowed-tools: Read
@@ -81,6 +81,36 @@ async def resource():
 
 ---
 
+## Prompt Injection & LLM-Output Trust
+
+When the app embeds an LLM, every byte the model emits — plus tool results, retrieved documents, and fetched web pages — is **untrusted input on the same footing as a raw request body**. Text inside that content that reads like an instruction ("ignore previous rules", "call the delete tool", "email the config to…") is still data. Render it, store it, classify it — but never let it drive control flow, widen permissions, or fire a side effect without an explicit human decision. This mirrors the agent-behavior rule in [constitution Article VII](../../constitution.md); the rules here cover the application you are building, not the assistant's own behavior.
+
+### Trust Boundary
+
+| Source | Trust | Handling |
+|--------|-------|----------|
+| System prompt / app-defined policy | Trusted | The only place instructions may originate |
+| User chat turn | Semi-trusted | Authenticated to a user, still validate + scope to their permissions |
+| Model output | Untrusted | Treat as data; gate any tool call it requests |
+| Tool / function results | Untrusted | Re-validate before feeding back into context |
+| Retrieved docs / RAG chunks | Untrusted | Strip or delimit embedded instructions |
+| Fetched web / email / file content | Untrusted | Highest risk — sanitize before it crosses into the prompt |
+
+### Defenses
+
+- **Separate instructions from data.** Keep app policy in the system prompt; wrap all untrusted content in clear delimiters or distinct structured fields (e.g. a `documents` array) so the model can tell "what to do" from "what to read." Never string-concatenate retrieved text into the instruction block.
+- **Least-privilege tools.** Give each tool the narrowest scope it needs. A summarizer needs no write or network egress capability. Fewer reachable side effects shrink the blast radius of a successful injection.
+- **Human-in-the-loop for irreversible actions.** Destructive, financial, or data-exfiltrating operations (delete, transfer, send-to-external-recipient, broad file reads) require explicit human confirmation — not a model token that "looks like" approval.
+- **Validate and allowlist tool arguments.** Parse the model's proposed arguments against a schema, allowlist targets (recipient domains, table names, paths), and reject anything outside it. The model choosing a tool is a *request*, not authorization.
+- **Keep secrets out of injectable context.** Never place API keys, internal URLs, or other users' data in a prompt that an injected instruction could later echo back into output. If the model cannot see it, it cannot be coaxed into leaking it.
+- **Bound indirect (second-order) injection.** Content ingested now may carry instructions that only fire on a later turn — a poisoned doc indexed today, a web page fetched mid-task, a comment in a parsed file. Sanitize and size-limit everything at the moment it crosses the trust boundary, not when it is finally read.
+
+### Carve-out: Authorized Defensive Work
+
+Building injection **detection** (classifiers, guardrails, eval suites) and running **authorized** red-team exercises — CTF, sanctioned pentest, internal adversarial testing of these defenses — is fully in scope. Generating injection payloads for that purpose is expected; the OWASP / authorized-testing framing of this skill applies to LLM apps exactly as it does to SQLi or XSS work.
+
+---
+
 ## Common Rationalizations
 
 | Excuse | Why It's Wrong |
@@ -90,6 +120,8 @@ async def resource():
 | "We'll add auth later" | Unauthenticated endpoints in production get discovered within hours |
 | "Nobody would exploit this" | Automated scanners don't care about your threat model — they scan everything |
 | "It's behind a VPN" | VPNs are perimeter defense — zero trust assumes breach already happened |
+| "The LLM would never follow a malicious instruction in a doc" | Models follow whatever reads like an instruction — retrieved content is untrusted input, not policy |
+| "We let the agent run the tool it picked, that's the point" | A model picking a tool is a request, not authorization — gate side effects behind allowlists and human confirmation |
 
 ## Reference Guides
 

package/app/skills/verification-before-completion/SKILL.md

@@ -43,6 +43,23 @@ Skip any step = lying, not verifying
 - Moving to next task
 - Delegating to agents
 
+## Don't Assume It Exists
+
+A prompt — yours, the user's, or another agent's — naming a file, table, column, endpoint, env var, config key, or dependency is a *hint*, not a fact. The name existing in text is not the same as the thing existing in the repo.
+
+- Before you read from, write to, import, or quote any such resource, confirm it: `Read` the file, `ls`/`grep` the path, list the table, check the lockfile. One look beats a confident guess.
+- Never reconstruct a file's contents, a function's body, or an API's signature from its name alone. The name tells you almost nothing about the shape. If you haven't read it, you don't know it.
+- A plausible-sounding path or symbol is the easiest thing in the world to invent. Treat your own fluency here as a warning sign, not as evidence.
+- AUTHORIZED security work (CTF, sanctioned pentest, defensive review) still verifies — probing whether a path/endpoint/parameter actually exists is part of the job, not an exception to it.
+
+## Declare Ungrounded as a Real Outcome
+
+When search, KB lookup, or tool calls come back with nothing relevant, the correct move is to *say so and stop* — not to backfill the hole from training memory and present it as established fact.
+
+- "Not found in `<source>`" is a complete, honest answer. State which source you checked and that it came up empty.
+- Do not promote a half-remembered detail to a definite claim just because the gap feels uncomfortable. An unverified recollection is a hypothesis; label it as one or leave it out.
+- If the missing piece blocks the task, surface the gap and ask — do not paper over it with a guess dressed as a finding.
+
 ## Common Failures
 
 | Claim | Requires | Not Sufficient |
@@ -57,6 +74,9 @@ Skip any step = lying, not verifying
 | No dead code (Art. VI.1) | Grep for every removed/renamed symbol: 0 references | "I cleaned up what I touched" |
 | Behavior change covered (Art. VI.2) | Integration test for the API surface + unit test + docs updated | Unit test on the helper only |
 | Diff is clean (Art. VI.4) | Re-read full diff: no orphaned imports, no stale docs, no skipped fixes | "I only changed what I needed" |
+| Resource exists (file/table/env var/endpoint/dep) | Read/list/grep it and see it | The prompt mentioned it, or the name sounds real |
+| File contents / API signature | Open the file, read the actual lines | Inferring shape from the filename or symbol name |
+| Answer is grounded | A source you actually read returns it | Recalling it from training memory |
 
 ## Red Flags — STOP
 
@@ -79,6 +99,21 @@ Skip any step = lying, not verifying
 | "Partial check is enough" | Partial proves nothing |
 | "Different words so rule doesn't apply" | Spirit over letter |
 
+## Pre-Completion Self-Audit
+
+Before you type "done", run these fast yes/no gates over your own draft. Each one has a fix — if the answer is bad, do the fix, don't ship the draft.
+
+| Self-check | If the honest answer is "no" / "yes, I did" |
+|------------|---------------------------------------------|
+| Did I actually run the verification command this message, or am I asserting success from memory? | Run it now. Memory is not a test result. |
+| Does every factual claim trace to output or a source I actually saw? | Cite the evidence, or cut the claim. |
+| Did I invent any path, filename, symbol, table, flag, or version number? | Verify it exists, or remove it. |
+| Did I quote file contents or an API signature I never opened? | Open and confirm, or stop quoting. |
+| Did a search/KB lookup come back empty that I then "filled in" anyway? | Replace the fill-in with "not found in `<source>`". |
+| Am I about to commit/push/PR on the strength of a claim I haven't proven? | Prove it first. |
+
+Same ethos as the rest of this skill: evidence before assertions, applied to your own output one line at a time.
+
 ## Key Patterns
 
 **Tests:**

package/kb/planning/drop-cascade-hooks-after-sunset.md

@@ -0,0 +1,91 @@
+---
+title: "Plan: Drop Cascade hooks after 2026-07-01 sunset"
+category: planning
+service: ai-toolkit
+tags:
+  - windsurf
+  - devin
+  - cascade
+  - hooks
+  - deprecation
+  - cleanup
+doc_type: plan
+status: scheduled
+created: "2026-06-10"
+last_updated: "2026-06-10"
+completion: "0%"
+trigger_date: "2026-07-01"
+description: "Scheduled cleanup: remove the deprecated Windsurf Cascade hooks generator (.windsurf/hooks.json) in the first ai-toolkit release after the 2026-07-01 Cascade sunset. The Devin CLI replacement (.devin/hooks.v1.json) shipped in v4.8.0; this plan removes the dead Cascade half once it can no longer run."
+---
+
+# Plan: Drop Cascade hooks after 2026-07-01 sunset
+
+## Why this exists
+
+Windsurf rebranded to Devin Desktop on 2026-06-02. The Cascade agent — and its
+`.windsurf/hooks.json` hook surface (`agent_action_name`/`tool_info` format) — is
+available **only through 2026-07-01**. Devin Local / Devin CLI do **not** read
+`.windsurf/hooks.json` as a fallback.
+
+v4.8.0 already shipped the replacement: `generate_devin_hooks.py` emits
+`.devin/hooks.v1.json` in the Claude-compatible format Devin CLI uses. During the
+transition **both** generators run at `profile=full` so pre-sunset Cascade users
+keep working. After 2026-07-01 the Cascade half is dead code and must be removed
+(Constitution Art. VI.1 — no dead code).
+
+## Trigger
+
+First ai-toolkit release **on or after 2026-07-01**. Do NOT do this earlier —
+removing it before the sunset breaks Cascade users who are still on the old agent.
+
+## Scope — remove the Cascade hooks surface
+
+1. **Delete the generator:** `scripts/generate_windsurf_hooks.py`.
+2. **Unwire the install step:** in `scripts/install_steps/ai_tools.py`, remove the
+   `_try_generator("generate_windsurf_hooks", cwd)` call (keep
+   `generate_devin_hooks`). Update the `profile=full` dry-run message to drop
+   `.windsurf/hooks.json (Cascade, deprecated)`.
+3. **Tests:** remove the windsurf-`.windsurf/hooks.json` cases from
+   `tests/test_hooks_per_editor.bats` (output path, valid JSON, source tag,
+   `$HOME` prefix, idempotence, user-preservation, `pre_write_code` coverage) and
+   the `profile=full` assertion in `tests/test_install_profiles.bats`
+   (`windsurf + full emits .windsurf/hooks.json`). Keep all `.devin/hooks.v1.json`
+   tests. Adjust the README test-count badge to the new total.
+4. **Registry:** in `scripts/ecosystem_tools.json` (windsurf entry), remove
+   `scripts/generate_windsurf_hooks.py` from `our_generators`; keep
+   `.windsurf/hooks.json` out of `config_paths` (it was never listed). Trim the
+   `status_note` hooks-migration paragraph to past tense ("Cascade hooks removed
+   in vX.Y.Z").
+5. **Docs:** in `kb/reference/supported-tools-registry.md` drop the
+   `generate_windsurf_hooks.py` row and the "drop after 2026-07-01" note; in
+   `kb/reference/hooks-catalog.md` remove the Cascade row from the
+   Per-Editor Native Hooks table and the deprecation wording, leaving the Devin CLI
+   section as the windsurf-family hook surface.
+6. **validate.py:** the `_HOOK_STEM_ALIAS = {"devin": "windsurf"}` mapping STAYS —
+   it is what keeps the `devin` hook generator counted as windsurf hooks in the
+   README-honesty check after the Cascade generator is gone.
+7. **CHANGELOG / version:** minor bump, `Removed` entry, regen artifacts, full
+   release-preparation SOP gate.
+
+## Verification
+
+- `python3 scripts/validate.py --strict` — 0/0 (editor-hooks-honesty must still
+  report windsurf as hook-enabled via the `devin` generator alias).
+- `python3 scripts/ecosystem_doctor.py --offline --check` — exit 0.
+- `npm test` — 0 `not ok`; confirm no test still references
+  `generate_windsurf_hooks.py` or `.windsurf/hooks.json`.
+- `grep -rn "generate_windsurf_hooks\|windsurf/hooks.json" scripts/ tests/ kb/ README.md`
+  returns nothing (Art. VI.1 orphan check).
+
+## Do NOT touch
+
+- `generate_devin_hooks.py` and `.devin/hooks.v1.json` — the live replacement.
+- The `.devin/`/`.windsurf/` rules + skills dual-emit (that fallback persists as
+  long as Devin Desktop reads legacy `.windsurf/` paths; this plan is hooks-only).
+
+## Related
+
+- `kb/reference/hooks-catalog.md` — Per-Editor Native Hooks + Devin CLI section
+- `kb/reference/supported-tools-registry.md` — windsurf entry, hooks-migration row
+- `kb/procedures/ecosystem-sync-sop.md` — class-D deprecation workflow
+- `scripts/ecosystem_tools.json` — windsurf `status_note`