@rune-kit/rune 2.13.0 → 2.15.0

package/skills/ba/references/explore-first.md

@@ -0,0 +1,107 @@
+# Explore-First Gate
+
+The explore-first rule: **never ask the user a question whose answer is in the codebase, the user's message, or the project metadata.** Every question burns user attention; an inferable question burns it for nothing.
+
+This is enforced as a HARD-GATE at Step 2.0 of `ba`, before any of the 5 elicitation questions are emitted.
+
+## The 4-item pre-check
+
+For each question the agent intends to ask, walk through this checklist:
+
+1. **Is the answer in `package.json` / `pyproject.toml` / `Cargo.toml` / `go.mod` / `pom.xml`?**
+   - Stack, framework, language version, dependencies, scripts → all live here.
+2. **Is the answer in `README.md` or `CLAUDE.md` or `docs/`?**
+   - Project description, target audience, conventions, deploy process.
+3. **Is it inferable from file extensions, directory structure, or config files?**
+   - `.tsx` files → React frontend. `Dockerfile` → containerized deploy. `.github/workflows/*` → CI exists.
+4. **Has the user answered it earlier in this conversation?**
+   - Read back through the conversation; cached answers are reusable.
+
+If ANY of the 4 checks would yield the answer, the question is inferable. **Don't ask it.** Read the source, infer, and proceed.
+
+## Tool-call evidence requirement (HARD-GATE)
+
+For every question Q the agent emits, there MUST be prior tool-call evidence in the same session:
+
+- At least 1 `Read`, `Glob`, or `Grep` related to Q's domain, OR
+- An explicit declaration: *"Q cannot be answered from project artifacts because [specific reason]."*
+
+Without one of these, Q is BLOCKED. The receiving validator (preflight, completion-gate) checks the tool-call log for evidence before allowing the question to count toward the 5-question budget.
+
+This prevents lazy questioning. The gate is "tried to infer" — not "must succeed in inferring." If the file simply doesn't have the answer, that's fine; the attempt is the gate.
+
+## Worked examples
+
+### ❌ Wrong — skips inference
+
+User: "I want to add a payment integration."
+
+Agent: "What language and framework are you using?"
+
+Failure: `package.json` (or equivalent) answers this. No grep needed.
+
+### ✅ Right — infers first
+
+User: "I want to add a payment integration."
+
+Agent: *(reads `package.json` — sees `"react": "^18"`, `"next": "^14"`)*
+Agent: "I see you're on Next.js 14 with React 18. For the payment integration, are you targeting Stripe, PayPal, or something else?"
+
+The first question is now non-trivial — it's the question only the user can answer.
+
+### ❌ Wrong — re-asks cached answer
+
+Earlier in the session: User said "the deadline is end of Q2."
+
+Agent (later): "What's the timeline for this?"
+
+Failure: cached answer exists. Re-asking is redundant.
+
+### ✅ Right — uses cached answer
+
+Agent: "Given the Q2 deadline you mentioned, [follow-up question that builds on it]."
+
+### ❌ Wrong — asks shape questions for inferable values
+
+User: "Build me a CLI tool that..."
+
+Agent: "Are you using TypeScript or JavaScript?"
+
+Failure: check `tsconfig.json` and `package.json`'s `type: "module"`. Or check existing files' extensions.
+
+### ✅ Right — narrow to genuine unknowns
+
+Agent: *(checks tsconfig + sample file)*
+Agent: "I see you're on TypeScript with strict mode. For the CLI tool, are you targeting Node 20+ or do we need to support older runtimes?"
+
+## What questions ARE worth asking
+
+Questions that survive the explore-first filter typically:
+
+- **Reveal user intent** that's not in the code ("what's the success metric for this feature?")
+- **Choose between credible alternatives** the code doesn't disambiguate ("auth: JWT vs session cookies?")
+- **Set scope** that the user hasn't yet bounded ("should this also handle anonymous users?")
+- **Capture domain expertise** the codebase doesn't encode ("when an Order is cancelled, do we refund automatically or wait for review?")
+
+These are the high-leverage questions. Aim for 5 of them, not 5 of "what stack are you using?"
+
+## Caching results
+
+When explore-first finds an inferable answer, record it in the requirements doc as a cached fact:
+
+```
+**Inferred from package.json**: TypeScript 5.4, Next.js 14.2, React 18.3
+**Inferred from .github/workflows/**: CI runs on PRs targeting main
+**Inferred from CLAUDE.md**: Strict TypeScript, no `any`, semantic commits
+```
+
+Future BA sessions reuse these without re-running grep.
+
+## When the rule relaxes
+
+Two narrow exceptions:
+
+1. **Stack/conventions are not yet in the repo** (greenfield, brand-new project) — explore-first finds nothing, so questions are necessary. Note "no project metadata available" in the question rationale.
+2. **User explicitly asked a redundant question themselves** — sometimes the user wants confirmation. "Yes, you're on TypeScript — the `tsconfig.json` confirms it. Anything else to verify?"
+
+Otherwise, the rule applies. Burn no user attention on questions agents can answer alone.

package/skills/ba/references/out-of-scope-format.md

@@ -0,0 +1,152 @@
+# `.out-of-scope/` Knowledge Base — Format & Matching
+
+A persistent record of rejected feature requests so AI agents stop re-litigating the same decision across sessions. Project-scoped, version-controlled, durable.
+
+## Where it lives
+
+```
+<repo-root>/
+├── .out-of-scope/
+│   ├── dark-mode.md
+│   ├── plugin-system.md
+│   └── graphql-api.md
+```
+
+One file per **concept**, not per issue. Multiple incoming requests for the same thing are appended to a single concept file's `prior_requests` list.
+
+## File format
+
+YAML frontmatter (for machine parsing) + Markdown body (for humans).
+
+```markdown
+---
+concept: dark-mode
+aliases: [night-theme, dark-theme, theme-switcher]
+decision: rejected
+rejected_at: 2026-04-27
+rejected_by: review-intake
+priority_to_revisit: low      # low | medium | high
+prior_requests:
+  - id: gh-issue-42
+    summary: Add dark mode support
+    closed_at: 2025-08-01
+  - id: discord-thread-2026-02-14
+    summary: Night theme for accessibility
+    closed_at: 2026-02-15
+conflicts_with: []            # paths to ADRs that this rejection contradicts
+revisit_if:
+  - "team adds front-end engineer"
+  - "user count crosses 50k"
+---
+
+# Dark Mode
+
+This project does not support runtime dark mode.
+
+## Why out of scope
+
+[Substantive reasoning — references project scope, technical constraints, or strategic decisions. NOT temporary circumstances ("we're busy now" — that's a deferral, not a rejection).]
+
+The rendering pipeline assumes a single color palette resolved at build time. Adding runtime theming would require:
+
+- A theme context provider wrapping every render
+- Per-component theme-aware style resolution
+- A persistence layer for user theme preferences
+
+This is a significant architectural change that conflicts with the project's focus on author-time content and downstream-consumer flexibility.
+
+## What would change our mind
+
+- A user paying for theme switcher specifically (revenue signal)
+- A team member with deep expertise on theme-aware CSS pipelines
+- A platform requirement (e.g., partner integration mandates dark mode)
+```
+
+## Frontmatter fields
+
+| Field | Type | Required | Description |
+|-------|------|----------|-------------|
+| `concept` | string | ✅ | kebab-case slug; matches filename without `.md` |
+| `aliases` | string[] | ✅ | Other phrasings of the same concept; used by similarity matcher |
+| `decision` | enum | ✅ | `rejected` (only — deferrals do not belong here) |
+| `rejected_at` | ISO date | ✅ | When the decision was made |
+| `rejected_by` | enum | ✅ | `ba` \| `review-intake` \| `incident` \| `cook` |
+| `priority_to_revisit` | enum | optional | `low` \| `medium` \| `high`; default `low` |
+| `prior_requests` | object[] | ✅ | At least one entry; appended on every re-request |
+| `conflicts_with` | string[] | optional | Paths to ADRs this contradicts (rare, surface for review) |
+| `revisit_if` | string[] | optional | Concrete signals that should trigger re-evaluation |
+
+## Slug rules
+
+- kebab-case, lowercase
+- max 40 chars
+- recognizable without opening the file (`dark-mode` good; `feature-x-v2` bad)
+- distinct from existing concepts — if a new slug has ≥0.7 alias overlap with an existing one, the writer MUST prompt: merge or pick distinct slug.
+
+## Concept-similarity matching
+
+When `ba` Step 1.5 runs intake on a new request, it builds a hash-keyed map:
+
+```
+Map<lowercased_token, [concept_slugs]>
+```
+
+For each `.out-of-scope/*.md` file, it indexes:
+- `concept` field tokens (split on `-`)
+- `aliases` field tokens
+- 1–3-word phrases from the body's title and first paragraph
+
+For incoming request, it tokenizes the same way, computes overlap with each indexed concept, and returns:
+
+| Confidence | Range | Action |
+|------------|-------|--------|
+| Exact match | ≥0.8 | Surface immediately: "This matches a prior rejection (`<slug>`). Do you still feel the same way?" |
+| Similar | 0.5–0.79 | Mention as similar prior decision, offer to read the file together |
+| Weak / no match | <0.5 | Ignore (don't pollute conversation with low-confidence matches) |
+
+The matcher is purely lexical — agents do NOT call out to a model to compute similarity. Lexical is fast (~1ms per file), deterministic, and good enough for the ≥0.8 threshold. Domain-specific concept clustering is a future enrichment.
+
+## When to write a new file
+
+Only when:
+1. An **enhancement** (not a bug) is rejected as `wontfix` / `out of scope`
+2. The reasoning is **durable** (project-scope, technical constraint, strategic decision) — NOT a temporary deferral
+3. A future similar request would benefit from finding this record
+
+If the rejection reason is "we're busy this quarter" → that's a deferral, route to a backlog issue, not `.out-of-scope/`.
+
+## When to append to an existing file
+
+When the matcher finds an exact concept match, append to `prior_requests`:
+
+```yaml
+prior_requests:
+  - id: gh-issue-42
+    summary: Add dark mode support
+    closed_at: 2025-08-01
+  - id: gh-issue-87        # <-- new
+    summary: Night theme for accessibility
+    closed_at: 2026-02-15  # <-- new
+```
+
+Do NOT create a duplicate file. Update the existing one.
+
+## When to delete a file
+
+When the maintainer decides to actually build the rejected feature. The file gets deleted in the same commit that opens the new tracking issue. Historical issues (in `prior_requests`) are not reopened — they're snapshots.
+
+## Conflicts with ADRs
+
+If a rejection contradicts an existing ADR (e.g., ADR says "we use REST" but a request asks for GraphQL and the rejection cites different reasons), populate `conflicts_with: [docs/adr/0007-rest-only.md]`. `audit` later flags this for cross-reference.
+
+## Validation (compiler test)
+
+`compiler/__tests__/out-of-scope-format.test.js` validates:
+- Frontmatter parses as YAML
+- Required fields present
+- `decision == "rejected"`
+- `concept` matches filename
+- `prior_requests` has ≥1 entry
+- Slug rules pass
+
+Failures here block the merge that introduced the broken file.

package/skills/brainstorm/SKILL.md

@@ -1,9 +1,9 @@
 ---
 name: brainstorm
-description: Creative ideation and solution exploration. Generates multiple approaches with trade-offs, uses structured frameworks (SCAMPER, First Principles), and hands off to plan for structuring.
+description: "Creative ideation and solution exploration. Generates multiple approaches with trade-offs, uses structured frameworks (SCAMPER, First Principles), and hands off to plan for structuring."
 metadata:
   author: runedev
-  version: "0.5.0"
+  version: "0.6.0"
   layer: L2
   model: opus
   group: creation
@@ -43,6 +43,23 @@ Activated for product-level rethinks — not "how to implement X" but "should we
 3. MUST apply the "10-star experience" lens: what would a 1-star, 5-star, and 10-star version look like?
 4. MUST challenge assumptions: "why does this need to be a page?" "why does the user need to do this at all?"
 
+### Design-It-Twice Mode
+Activated when exploring alternative *interface shapes* for a deepening candidate. Spawns N=3-4 parallel subagents, each pinned to a radically different design constraint (minimize / maximize-flexibility / optimize-common-case / ports-and-adapters), computes a diversity score over feature vectors, and presents sequentially with an opinionated recommendation. Used by `improve-architecture` when a deepened module's interface is non-obvious.
+
+**Design-It-Twice triggers:**
+- `improve-architecture` (Step 7 hand-off) when the picked candidate has multiple credible interface shapes
+- User says "design it twice", "explore interfaces", "what are the API options"
+- Manual: `/rune brainstorm design-it-twice <module>`
+
+**Design-It-Twice constraints:**
+1. MUST spawn N=3 (minimum) or N=4 (when dependency category is remote-owned or true-external) parallel subagents
+2. Each subagent pinned to exactly ONE of the 4 standard constraints — enforced via prompt template
+3. Diversity score MUST be >= 0.4 before presenting (re-spawn once if below)
+4. Recommendation MUST be opinionated with a concrete hedge condition — "it depends" is BLOCKED
+5. Hybrid synthesis (Step 4.5) is opt-in when 2 designs have complementary strengths
+
+Full doctrine: [references/design-it-twice.md](references/design-it-twice.md).
+
 ### Rescue Mode
 Activated when an approach has been tried and **fundamentally failed** — not a bug, but a wrong approach. Rescue mode forces **category-diverse** alternatives instead of variants of the failed approach.
 
@@ -102,6 +119,7 @@ Direct API call ≠ Wrapper/middleware layer ≠ Reverse engineering ≠ Browser
 - User: `/rune brainstorm <topic>` direct invocation (Discovery Mode)
 - User: `/rune brainstorm rescue <context>` manual rescue (Rescue Mode)
 - `ba` (L2): when multiple requirement approaches exist
+- `improve-architecture` (L2): when a deepened module's interface needs Design-It-Twice exploration
 
 ## Cross-Hub Connections
 
@@ -143,6 +161,7 @@ CRAZY 8s         — 8 ideas in 8 minutes (rapid ideation)
 ### Step 0 — Detect Mode
 
 Check the invocation context:
+- If `mode="design-it-twice"` is set, or caller is `improve-architecture` Step 7, or user says "design it twice / explore interfaces" → **Design-It-Twice Mode** (jump to Step 2.5 directly)
 - If `mode="vision"` is set, or user says "rethink/reimagine/step back" → **Vision Mode**
 - If `mode="rescue"` is set, or caller is Approach Pivot Gate / 3-Fix Escalation → **Rescue Mode**
 - Otherwise → **Discovery Mode**
@@ -209,6 +228,7 @@ When Step 1 or Step 1.5 reveals gaps, ask structured clarifying questions using
 
 **Discovery Mode**: Produce exactly 2–3 distinct approaches.
 **Rescue Mode**: Produce exactly 3–5 approaches, each a **different category** from the failed approach.
+**Design-It-Twice Mode**: skip to Step 2.5.
 
 Each approach must be meaningfully different — not just variations of the same idea. For each approach provide:
 - **Name**: short memorable label
@@ -220,6 +240,21 @@ Each approach must be meaningfully different — not just variations of the same
 
 If the domain is unfamiliar or data is needed, invoke `rune:research` before generating options. For product/market context, invoke `rune:trend-scout`.
 
+### Step 2.5 — Constraint Matrix Spawn (Design-It-Twice Mode only)
+
+Spawn N=3 parallel subagents (or N=4 if dependency category is `remote-owned` / `true-external`). Each is pinned to exactly one constraint via Task tool spawn:
+
+| Constraint ID | Pinning |
+|---------------|---------|
+| C1 | "Minimize the interface — aim for 1–3 entry points. Maximize leverage per entry point." |
+| C2 | "Maximize flexibility — support many use cases, extension surface." |
+| C3 | "Optimize for the most common caller — make the default case trivial. Rare cases pay cost." |
+| C4 | "Design around ports and adapters for cross-seam dependencies." (only when applicable) |
+
+Use the spawn prompt template from [references/design-it-twice.md](references/design-it-twice.md). Include CONTEXT.md domain terms in the prompt so each design names things consistently with project domain language.
+
+Each subagent returns a YAML block: interface, usage example, what's hidden, dependency strategy/adapters, tradeoffs.
+
 ### Step 3 — Evaluate
 
 **Discovery Mode** — Apply the most relevant framework:
@@ -243,6 +278,26 @@ Additionally in Rescue Mode:
 
 For approaches with many interacting variables, invoke `rune:sequential-thinking` to reason through trade-offs systematically.
 
+### Step 3.5 — Diversity Gate (Design-It-Twice Mode only)
+
+After subagents return, compute the diversity score:
+
+```
+feature_vector(design) = [
+  count(methods), count(return_types), count(adapter_kinds),
+  count(dependencies), paradigm_tag, has_async, has_streaming
+]
+diversity = 1 - mean(pairwise_jaccard(feature_vectors))
+```
+
+| Diversity | Action |
+|-----------|--------|
+| ≥ 0.6 | Proceed to Step 4 |
+| 0.4 – 0.59 | Surface to user: "designs are similar in [shared trait] — re-spawn with different constraints?" |
+| < 0.4 | Re-spawn once with rotated constraints; if still <0.4, give up and present what's there with a diversity-low warning |
+
+Emit `diversity_score` in chain_metadata.
+
 ### Step 4 — Recommend
 
 Select ONE approach as the recommendation. State:
@@ -288,6 +343,20 @@ For product-level brainstorming (Vision Mode or when approaches have strategic i
 - Skip this step for pure technical brainstorming (no product/strategy dimension)
 - If all tiers look equally expensive → approach may be too complex for Quick Win
 
+### Step 4.5 — Hybrid Synthesis (Design-It-Twice Mode, optional)
+
+If two designs have complementary strengths (e.g., C1's leverage + C4's seam discipline), propose a 4th option that combines them. Skip this step when no two designs have clear complementary strengths.
+
+```
+Option D (Hybrid C1 + C4):
+  - Interface: 3 methods (from C1's minimization)
+  - Adapters: HttpAdapter + InMemoryAdapter (from C4's port discipline)
+  - Pros: small surface AND testable across the seam
+  - Cons: more upfront design work; locks the port early
+```
+
+The hybrid is the recommended default in many cases. Be opinionated.
+
 ### Step 5 — Return to Plan
 Pass the recommended approach back to `rune:plan` for structuring into an executable implementation plan. Include:
 - The chosen option name
@@ -306,6 +375,9 @@ If the user rejects the recommendation, return to Step 2 with adjusted constrain
 6. [Rescue Mode] MUST NOT generate variants of the failed approach — each approach must be a different CATEGORY
 7. [Rescue Mode] MUST use Collision-Zone or Inversion framework — conventional thinking already failed
 8. [Rescue Mode] MUST include at least 1 unconventional/hacky approach — sometimes the "dirty" solution is the only one that works
+9. [Design-It-Twice Mode] MUST spawn parallel subagents with one constraint pinned per agent — fake diversity (one agent producing N options) is BLOCKED
+10. [Design-It-Twice Mode] MUST emit `diversity_score` and re-spawn (once) if below 0.4 floor
+11. [Design-It-Twice Mode] MUST NOT produce "it depends" recommendations — pick one design with a concrete hedge condition
 
 ## Output Format
 
@@ -363,6 +435,10 @@ Known failure modes for this skill. Check these before declaring done.
 | [Rescue] All approaches are "clean/proper" — no hacky option | MEDIUM | At least 1 must be unconventional — wrappers, reverse-engineering, debug mode abuse, proxy layers |
 | Calling plan directly instead of presenting options first | CRITICAL | Steps 2-3 are mandatory — present options, get approval, THEN call plan |
 | "Creative" options that ignore stated constraints | MEDIUM | Every option must satisfy the constraints declared in Step 1 |
+| [Design-It-Twice] Single agent producing N options instead of N parallel subagents | HIGH | Step 2.5 — constraint pinning happens at spawn, not in a loop. Each constraint = one Task call |
+| [Design-It-Twice] Diversity score below 0.4 ignored | HIGH | Step 3.5 gate — re-spawn once; if still low, present with explicit "low-diversity" warning |
+| [Design-It-Twice] "It depends" recommendation | HIGH | Step 4 — must pick one with a hedge; if genuinely tied, propose hybrid (Step 4.5) and recommend that |
+| [Design-It-Twice] Forgetting to include CONTEXT.md domain terms in subagent prompt | MEDIUM | Step 2.5 spawn template requires domain glossary be passed through |
 
 ## Done When
 

package/skills/brainstorm/references/design-it-twice.md

@@ -0,0 +1,155 @@
+# Design-It-Twice Mode
+
+Force genuine architectural diversity when exploring alternative interfaces or module shapes. Spawns parallel subagents, each pinned to a *radically different* design constraint, then computes a diversity score before presenting results.
+
+## When to use
+
+| Situation | Use Design-It-Twice |
+|-----------|---------------------|
+| Multiple credible interface shapes for a deepening candidate (from `improve-architecture`) | ✅ |
+| User asked "what are the options for designing X?" | ✅ |
+| Ports vs no-ports decision is itself a design question | ✅ |
+| Cross-seam dependencies (remote-owned, true-external) where adapter choice matters | ✅ |
+| One obvious interface shape — translation of existing public functions | ❌ Skip; go directly to surgeon/fix |
+| Single-method utility | ❌ Skip; not enough surface to design twice |
+
+## The four standard constraints
+
+Each parallel subagent is pinned to exactly one constraint via the spawn prompt. The constraints are deliberately incompatible — that's where the diversity comes from.
+
+| ID | Constraint | What it produces |
+|----|------------|------------------|
+| `C1` | **Minimize interface** — aim for 1–3 entry points; maximize leverage per entry | Smallest interface; deep impl; few callers learn the surface |
+| `C2` | **Maximize flexibility** — support many use cases, plugin/extension surface | Wide interface; configurable; extension points |
+| `C3` | **Optimize common case** — make default trivial; rare cases pay cost | Tiny default; opt-in complexity for power users |
+| `C4` | **Ports & adapters** — design seams for cross-boundary swap | Explicit ports; multiple adapter slots |
+
+For most cases pick 3 of 4. Add C4 only when the dependency category (from `improve-architecture/references/deepening.md`) is `remote-owned` or `true-external`.
+
+## Subagent spawn template
+
+```
+You are designing an interface for: <module description>
+
+Current state:
+  files: <file list>
+  callers: <caller summary>
+  current_depth: <1-5>
+  dependency_category: <in-process | local-substitutable | remote-owned | true-external>
+  what_to_hide: <state, lifecycle, retry, error transformation>
+
+Constraint: <C1 | C2 | C3 | C4>
+  <constraint description from the table above>
+
+Output (YAML):
+  interface:
+    name: <DeepenedModuleName>
+    methods:
+      - signature: <method signature>
+        invariants: [<invariant 1>, <invariant 2>]
+        errors: [<error case 1>, <error case 2>]
+  usage_example: |
+    <code showing how a caller invokes the interface>
+  hides_behind_seam:
+    - <complexity 1 hidden inside the implementation>
+    - <complexity 2>
+  dependency_strategy:
+    category: <category>
+    adapters: [<adapter1>, <adapter2>]
+    seam_real: <true if adapters >= 2, false if 1 (downgrade to internal seam)>
+  tradeoffs:
+    leverage: <1-5 + 1-line justification>
+    flexibility: <1-5 + 1-line justification>
+    common_case_simplicity: <1-5 + 1-line justification>
+
+Vocabulary: use the controlled terms from rune:improve-architecture/references/language.md
+  (module, interface, seam, adapter, leverage, locality)
+  Do NOT use "boundary", "component", "service", or "layer" in narrative.
+
+Domain terms: <if CONTEXT.md present, list its glossary terms here so the design uses them>
+```
+
+## Diversity gate (machine-checked)
+
+After all subagents return, compute pairwise similarity over feature vectors:
+
+```
+feature_vector(design) = [
+  count(interface.methods),
+  count(distinct_return_types),
+  count(unique_adapter_kinds),
+  count(unique_dependencies),
+  paradigm_tag,           // "minimal" | "extensible" | "default-light" | "ports-adapters"
+  has_async_methods,      // bool → 0/1
+  has_streaming,          // bool → 0/1
+]
+```
+
+Diversity score:
+```
+similarity(d_i, d_j) = jaccard(feature_vector(d_i), feature_vector(d_j))
+diversity = 1 - mean(similarity(d_i, d_j) for all i < j)
+```
+
+| Diversity | Action |
+|-----------|--------|
+| ≥ 0.6 | Proceed to presentation |
+| 0.4 – 0.59 | Marginal; surface to user — "designs are similar in [shared trait]; want me to re-spawn with different constraints?" |
+| < 0.4 | Re-spawn with rotated constraints (e.g., swap C2 → C4); 1 retry max before giving up |
+
+`diversity_floor = 0.4` is conservative; tune in v0.7+ once usage telemetry exists.
+
+## Presentation order
+
+1. Each design alone (sequential, so user can absorb each in isolation)
+2. Comparison table contrasting designs by:
+   - **Depth** — leverage at the interface
+   - **Locality** — where change concentrates
+   - **Seam placement** — internal vs external; ports yes/no
+   - **Common-case trivial-ness** — how much work for the default path
+3. **Opinionated recommendation** — strongest design + concrete hedge condition for when to pick a different one
+4. **Hybrid synthesis (optional Step 4.5)** — if 2 designs have complementary strengths, propose a 4th synthesized option that combines them
+
+Skip the comparison table if N=2 (just 1 contrast, prose handles it).
+
+## "It depends" is BLOCKED
+
+The recommendation step requires a concrete recommendation with a hedge:
+
+✅ "Recommend C1 (minimize interface). Choose C3 (optimize common case) if you discover most callers only need the default path."
+
+❌ "It depends on your priorities."
+
+If you genuinely can't pick between two designs, propose the hybrid (Step 4.5) and recommend that as the default.
+
+## Hybrid synthesis (Step 4.5 — optional)
+
+When two designs have complementary strengths (e.g., C1's leverage + C4's seam discipline), propose a 4th option that combines them:
+
+```
+Option D (Hybrid C1 + C4):
+  - Interface: 3 methods (from C1's minimization)
+  - Adapters: HttpAdapter + InMemoryAdapter (from C4's port discipline)
+  - Pros: small surface AND testable across the seam
+  - Cons: more upfront design work; locks the port early
+```
+
+Hybrid synthesis is **opt-in**. If no two designs have clear complementary strengths, skip this step.
+
+## Cost note
+
+4 parallel opus subagents is the most expensive thing this skill does. Use Design-It-Twice mode only when `improve-architecture` flags a candidate worth deepening (multiple credible interfaces). Default Discovery mode is cheaper for ordinary brainstorming.
+
+## Output schema (chain_metadata)
+
+```yaml
+chain_metadata:
+  skill: "rune:brainstorm"
+  mode: "design-it-twice"
+  exports:
+    designs: [<yaml-per-design>]
+    diversity_score: 0-1
+    constraints_used: [C1, C2, C4]
+    recommendation: <design-id>
+    hybrid_proposed: <true|false>
+```

package/skills/browser-pilot/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: browser-pilot
-description: Playwright browser automation. Navigates URLs, takes screenshots, checks accessibility tree, interacts with UI elements, and reports findings.
+description: "Playwright browser automation. Navigates URLs, takes screenshots, checks accessibility tree, interacts with UI elements, and reports findings."
 metadata:
   author: runedev
   version: "0.2.0"

package/skills/completion-gate/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: completion-gate
-description: "Validates agent claims against evidence trail. Catches 'done' without proof, 'tests pass' without output, 'fixed' without verification. Called by cook and team at workflow end."
+description: "Validates agent claims against evidence trail. Use when verifying an agent has actually done what it claims — auto-fires at workflow end. Catches 'done' without proof, 'tests pass' without output, 'fixed' without verification. Called by cook and team."
 user-invocable: false
 metadata:
   author: runedev

package/skills/constraint-check/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: constraint-check
-description: "Meta-validator for HARD-GATEs. Verifies that skills' mandatory constraints were followed during a workflow. Called by cook, team, and audit to audit discipline compliance."
+description: "Meta-validator for HARD-GATEs. Use when auditing whether a skill's mandatory constraints were actually followed during a workflow (not just claimed). Called by cook, team, and audit for discipline compliance."
 user-invocable: false
 metadata:
   author: runedev