@rune-kit/rune 2.6.0 → 2.7.0

package/skills/completion-gate/SKILL.md

@@ -4,7 +4,7 @@ description: "Validates agent claims against evidence trail. Catches 'done' with
 user-invocable: false
 metadata:
   author: runedev
-  version: "1.6.0"
+  version: "1.7.0"
   layer: L3
   model: haiku
   group: validation
@@ -210,6 +210,29 @@ Before emitting verdict, verify evidence quality:
 | Quote matches claim exactly | CONFIRMED |
 | Quote contradicts claim | CONTRADICTED |
 
+### Step 5.5 — Plan Diff Check
+
+When validating a phase within a master plan, diff actual changes against the phase plan file:
+
+1. **Read the active phase plan** — `Glob` for `.rune/plan-*-phase*.md` matching the current phase
+2. **Extract `## Files Touched`** — build a list of expected files (new/modify/delete)
+3. **Extract `## Tasks`** — build a list of all `- [ ]` and `- [x]` items
+4. **Compare against actual changes** — `git diff --name-only` (or file system scan)
+5. **Report**:
+
+| Check | Status |
+|-------|--------|
+| Unchecked task in phase plan (`- [ ]` still exists) | **INCOMPLETE** — task was not done |
+| File in plan's "Files Touched" but not in actual diff | **MISSING** — planned file was never touched |
+| File in actual diff but NOT in plan's "Files Touched" | **UNPLANNED** — scope creep (warn, not block) |
+| All tasks `[x]` AND all planned files touched | **PLAN-ALIGNED** |
+
+```
+Plan Diff: PLAN-ALIGNED | INCOMPLETE (2 unchecked tasks) | MISSING (1 file never touched)
+```
+
+**Skip if**: No active phase plan found (single-task, no master plan). **MANDATORY** for multi-phase master plans.
+
 ## Verdict Rules
 
 ```
@@ -245,6 +268,7 @@ Completion Gate Report with status (CONFIRMED/UNCONFIRMED/CONTRADICTED), claim v
 | Rubber-stamping — all CONFIRMED without scrutiny | HIGH | Default-FAIL mindset: actively seek 3-5 issues. Zero issues = red flag, apply skeptic sweep on weakest 2 claims |
 | Partial completion claimed as full — 80% done but "implemented" | HIGH | Adversarial checklist: check for partial completion, scope mismatch, evidence-claim alignment |
 | Self-Validation skipped — skill has checks but gate ignores them | HIGH | Step 1c: extract Self-Validation from skill's SKILL.md, treat each as implicit claim. Missing = UNCONFIRMED |
+| Plan says done but phase file has unchecked tasks | HIGH | Step 5.5: diff changed files vs phase plan's Files Touched + Tasks sections |
 
 ## Done When
 
@@ -252,6 +276,7 @@ Completion Gate Report with status (CONFIRMED/UNCONFIRMED/CONTRADICTED), claim v
 - Each claim matched against tool output evidence
 - Verdict table emitted with claim/evidence/verdict for each item
 - All 3 verification axes (Completeness/Correctness/Coherence) have at least one claim checked
+- Plan diff check passed (if multi-phase): all tasks checked, all planned files touched
 - Overall verdict: CONFIRMED / UNCONFIRMED / CONTRADICTED
 - If not CONFIRMED: specific gaps listed with remediation steps
 

package/skills/context-engine/SKILL.md

@@ -4,7 +4,7 @@ description: "Context window management. Auto-triggered when context is filling
 user-invocable: false
 metadata:
   author: runedev
-  version: "0.6.0"
+  version: "0.8.0"
   layer: L3
   model: haiku
   group: state
@@ -145,6 +145,79 @@ When loading context for a task (Phase 1 of cook, or onboard), use a 4-phase ret
 
 **Key rule**: Stop at 3 high-relevance files, not 10 mediocre ones. Quality > quantity for context loading.
 
+## Compaction Technique: Structured Summary with Continuation Point
+
+When compaction is triggered (RED or approved ORANGE), generate a **structured summary** that replaces the full conversation history while preserving therapeutic continuity — the ability to resume exactly where work left off.
+
+### Summary Structure
+
+The compaction summary MUST include these sections in order:
+
+```markdown
+## Compaction Summary (generated at [tool call count])
+
+### Topics Covered
+- [bullet list of distinct topics/tasks worked on this session]
+
+### Key Decisions Made
+- [decision]: [rationale] — affects [files/modules]
+
+### Active Threads
+- [what was being worked on when compaction triggered — the "where we are now" anchor]
+- Current file: [path], current function/section: [name]
+- Partial progress: [what's done vs what remains in the immediate task]
+
+### Emotional/Priority Context
+- [user urgency level, blocking issues, deadlines mentioned]
+- [any user frustrations or preferences expressed this session]
+
+### Continuation Point
+> Resume: [exact next action to take — not vague "continue working" but specific "implement the validation logic in src/auth/validate.ts:47 using the Zod schema defined in Step 2"]
+```
+
+### Why This Structure
+
+Most compaction loses the **continuation point** — the agent knows WHAT was discussed but not WHERE to resume. The "Active Threads" and "Continuation Point" sections solve this by preserving:
+1. The exact file and function being edited
+2. What's done vs remaining in the current micro-task
+3. The specific next action (not a summary of the plan, but the next concrete step)
+
+### Rules
+
+- Summary MUST be <500 tokens — if longer, you're summarizing too much detail
+- "Active Threads" section is the most critical — get this wrong and the agent restarts from scratch
+- Never include full file contents in the summary — only paths and line references
+- Include user tone/urgency signals — these are lost in pure technical summaries
+
+## Incremental Stream Processing
+
+When processing streaming LLM output (e.g., in skills that invoke AI calls or process tool output incrementally), use **sentence-level buffering** instead of waiting for the full response:
+
+### Pattern: Buffer → Detect Boundary → Act
+
+```
+1. ACCUMULATE: Feed incoming chunks into a text buffer
+2. DETECT: Check for sentence boundaries:
+   - Primary: 40+ chars ending in . ! ? ; :
+   - Secondary: paragraph break (\n\n) with 15+ chars accumulated
+   - Never split mid-word or mid-code-block
+3. EXTRACT: Remove the complete sentence from the buffer
+4. ACT: Process the extracted sentence immediately (e.g., queue for TTS, parse for structured data, update progress display)
+5. CONTINUE: Keep accumulating the next sentence while processing the current one
+```
+
+### When to Use
+
+- **Skills that stream AI responses to the user**: process and display incrementally instead of waiting for the full response
+- **Background note-taking**: extract key points from streaming output as they arrive
+- **Progress reporting**: detect milestone keywords in streaming output to update progress
+
+### When NOT to Use
+
+- **Code generation**: wait for the full code block — partial code is useless
+- **JSON output**: accumulate until the closing brace — partial JSON can't be parsed
+- **Short responses** (<100 chars expected): overhead of boundary detection exceeds benefit
+
 ## Context Health Levels
 
 ```
@@ -182,7 +255,7 @@ When ORANGE or RED is reached, use this table to determine whether compaction is
 | Research → Planning | YES | Research findings summarize well; key decisions survive |
 | Planning → Implementation | YES | Plan is in files (.rune/plan-*.md); context can reload from artifacts |
 | Debug → Next feature | YES | Debug findings are in Debug Report; fix has the diagnosis |
-| Mid-implementation (Phase 4) | **NO** | Losing file paths, partial changes, and test state is catastrophic |
+| Mid-implementation (Phase 4) | **CONDITIONAL** | Safe ONLY at task boundaries within Phase 4 (after a file is fully written + tested). Never mid-file-edit. See Mid-Loop Compaction below |
 | After failed approach → Pivot | YES | Failed approach should be discarded; fresh context helps |
 | Quality (Phase 5) → Verify | **NO** | Quality findings reference specific file:line in current context |
 | After commit (Phase 7) | YES | Work is persisted in git; safe boundary |
@@ -190,6 +263,22 @@ When ORANGE or RED is reached, use this table to determine whether compaction is
 **What survives compaction**: Task description, file paths mentioned, key decisions, plan reference, current phase.
 **What is lost**: Full file contents read, intermediate reasoning, exact error messages, tool output details.
 
+### Mid-Loop Compaction (Phase 4 Emergency)
+
+> From goclaw (nextlevelbuilder/goclaw, 832★): "Compact during run, not just at session boundary."
+
+When context hits RED during Phase 4 (implementation), compaction IS possible at **clean split points**:
+
+1. **Find a clean boundary**: completed task within the phase (file fully written + tests pass for that file)
+2. **Flush state first**: call `session-bridge` to save progress, then call `neural-memory` to capture decisions
+3. **Split 70/30**: preserve 70% of remaining context for continuation, summarize 30% of completed work
+4. **Never break tool pairs**: compaction MUST NOT split a `tool_use` from its `tool_result` — always keep pairs together
+5. **Inject continuation marker**: after compaction, include: "Resuming Phase 4. Tasks [1-3] complete. Currently on task 4. Plan file: `.rune/plan-X-phaseN.md`"
+
+**Timeout fallback**: If clean boundary can't be found within 30 seconds, create `.rune/.continue-here.md` and pause instead.
+
+**Skip if**: Context is ORANGE (not RED), or fewer than 3 tasks remain in the phase.
+
 ## Context Budget Audit (Baseline Cost Awareness)
 
 MCP tool schemas and agent descriptions consume significant baseline context before any work begins. This section helps identify and reduce invisible context waste.
@@ -251,6 +340,8 @@ Known failure modes for this skill. Check these before declaring done.
 | Injecting stale context from previous session without marking it historical | HIGH | Constraint 3: all loaded context must include session date marker |
 | Premature compaction from over-estimated utilization | MEDIUM | Tool count is directional only — sessions with heavy Read calls may need lower thresholds; only block at confirmed RED |
 | Not activating large-file adjustment on Python/Java codebases | MEDIUM | Track Read calls returning >500 lines; if ≥3 occur, switch to adjusted (0.8x) thresholds for the session |
+| Mid-loop compaction breaks tool_use/tool_result pair | CRITICAL | Always keep tool pairs together — splitting causes orphaned results and context corruption |
+| Mid-loop compaction without flushing state first | HIGH | session-bridge + neural-memory MUST run before compaction — losing unsaved decisions is worse than hitting context limit |
 
 ## Done When
 

package/skills/cook/SKILL.md

@@ -5,7 +5,7 @@ context: fork
 agent: general-purpose
 metadata:
   author: runedev
-  version: "1.7.0"
+  version: "2.0.0"
   layer: L1
   model: sonnet
   group: orchestrator
@@ -39,14 +39,41 @@ Cook supports predefined workflow chains for common task types. Use these as sho
 /rune cook security   → Full pipeline + sentinel@opus + sast (all phases, security-escalated)
 /rune cook hotfix     → Minimal: fix → verify → commit (Phase 4 → 6 → 7, skip scout if user provides context)
 /rune cook nano       → Trivial: do → verify → done (no phases, ≤3 steps)
+/rune cook --template <name> → Load pre-built workflow template from installed Pro/Business packs
 ```
 
+### Template Workflows (Pro/Business)
+
+When `--template <name>` is provided, cook loads a pre-built workflow template instead of auto-detecting:
+
+```
+/rune cook --template product-discovery   → Pro: stakeholder interviews → problem framing → competitive → spec → validation
+/rune cook --template product-launch      → Pro: spec lock → implement → quality gates → staged rollout → announcement
+/rune cook --template product-iteration   → Pro: metrics review → feedback synthesis → re-prioritize → implement → measure
+/rune cook --template data-exploration    → Pro: data profiling → hypotheses → statistical testing → visualization → report
+/rune cook --template data-pipeline       → Pro: schema design → ETL → quality gates → deploy → monitoring
+/rune cook --template sales-outreach-campaign → Pro: prospect research → messaging → sequence → A/B test → launch
+/rune cook --template sales-deal-review   → Pro: account deep-dive → risk assessment → competitive strategy → action plan
+/rune cook --template support-incident-response → Pro: triage → diagnose → fix → verify → postmortem → KB update
+/rune cook --template support-kb-refresh  → Pro: audit → gap analysis → draft → review → publish
+```
+
+**Template resolution**: Templates are `.md` files in `extensions/pro-*/templates/` or `extensions/business-*/templates/`. Each template defines: phases, skill connections, mesh signals, and acceptance criteria. The compiler includes templates in pack output during build.
+
+**When --template is used**:
+1. Skip Phase 1.5 (auto-detection) — template pre-selects domain and pack
+2. Skip Phase 1.7 (workflow matching) — template IS the workflow
+3. Load template phases as the master plan (Phase 2 becomes "review template plan" not "create plan")
+4. Execute each template phase in order, invoking declared skills
+5. Emit template's declared signals on completion
+
 **Chain selection**: If user invokes `/rune cook` without a chain type, auto-detect from the task description:
 - Contains "bug", "fix", "broken", "error" → `bugfix`
 - Contains "refactor", "clean", "restructure" → `refactor`
 - Contains "security", "auth", "vulnerability", "CVE" → `security`
 - Contains "urgent", "hotfix", "production" → `hotfix`
 - Contains "quick", "just", "chỉ cần", "copy", "move", "rename", "bump" → `nano`
+- Contains `--template` → load template workflow (see above)
 - Default → `feature`
 
 ## Phase Skip Rules
@@ -177,7 +204,11 @@ Skip if: bug fix with clear repro steps | user said "just do it" | fast mode + <
 5. Invoke scout to scan the codebase (Glob + Grep + Read on relevant files)
 6. Summarize: what exists, project conventions, files likely to change, active decision constraints
 7. **Python async detection**: if Python project detected, `Grep` for async indicators (`async def`, `await`, `aiosqlite`, `aiohttp`, `asyncio.run`). If ≥3 matches → flag as **"async-first Python"** — new code defaults to `async def`
-8. Mark Phase 1 as `completed`
+8. **Explore-Before-Commit**: If scout reveals multiple viable approaches (e.g., 2+ libraries, 2+ architectural patterns), do NOT commit to an approach yet. Instead:
+   - List alternatives with 1-line trade-off each
+   - Flag to Phase 2 (plan) for formal comparison
+   - Separating "thinking" (Phase 1) from "committing" (Phase 2) prevents premature lock-in
+9. Mark Phase 1 as `completed`
 
 **Gate**: If scout finds the feature already exists → STOP and inform user.
 
@@ -212,7 +243,15 @@ After scout completes, check if the detected tech stack or task description matc
 
 ## Phase 0: RESUME CHECK (Before Phase 1)
 
-**Goal**: Detect if a master plan already exists for this task. If so, skip Phase 1-2 and resume from the current phase.
+**Goal**: Detect if a master plan already exists for this task, or if a `--template` was specified. If so, skip Phase 1-2 and resume/load the workflow.
+
+**Step 0.4 — Template Detection**: If user passed `--template <name>`:
+1. Search installed pack templates for the name: `Glob` for `extensions/*/templates/<name>.md` and `extensions/pro-*/templates/<name>.md`
+2. If found: `Read` the template file → parse phases, signals, connections, acceptance criteria
+3. Generate a master plan from the template: each template phase becomes a plan phase
+4. Write plan files to `.rune/plan-<template-name>.md` + `.rune/plan-<template-name>-phaseN.md`
+5. Announce "Loading template: <name> (<pack>)" → skip Phase 1, 1.5, 1.7, 2 → proceed to Phase 4 with Phase 1 of the template
+6. If template not found: warn user and fall through to normal workflow
 
 **Step 0.5 — Cross-Project Recall**: Call `neural-memory` (Recall Mode) with 3-5 topics relevant to the current task. Always prefix queries with the project name (e.g., `"ProjectName auth pattern"` not `"auth pattern"`).
 
@@ -427,7 +466,15 @@ Before entering ANY Phase N+1, assert: Phase N `completed` in TodoWrite | gate c
 2. Save to `.rune/decisions.md` (approach + trade-offs), `.rune/progress.md` (task complete), `.rune/conventions.md` (new patterns)
 3. **Skill metrics** → `.rune/metrics/skills.json`: increment phase run/skip counts, quality gate results, debug loop counts under `cook` key
 4. **Routing overrides** (H3): if Phase 4 hit max loops for an error pattern → write rule to `.rune/metrics/routing-overrides.json`. Max 10 active rules.
-5. **Step 8.5 — Capture Learnings**: `neural-memory` (Capture Mode) — 2-5 memories: architecture decisions, patterns, error root-causes, trade-offs. Cognitive language (causal/decisional/comparative). Tags: `[project, tech, topic]`. Priority 5 routine / 7-8 decisions / 9-10 critical errors.
+5. **Step 8.5 — Cross-Cutting Sweep**: After commit, check if this phase changed stats (skill count, test count, signal count, pack count, layer counts). If ANY stat changed:
+   - [ ] `README.md` — stats, badges, feature list
+   - [ ] `docs/index.html` (landing page) — meta tags, hero badge, install section, mesh stats, footer
+   - [ ] `dashboard.html` (if local) — KPI cards, test count, skill tabs, layer counts
+   - [ ] `CLAUDE.md` — commands, test count, skill list
+   - [ ] `MEMORY.md` — milestones, version info
+
+   **Skip if**: No stats changed (pure refactor, docs-only, style change). **MANDATORY** if any numeric stat in README differs from actual.
+6. **Step 8.6 — Capture Learnings**: `neural-memory` (Capture Mode) — 2-5 memories: architecture decisions, patterns, error root-causes, trade-offs. Cognitive language (causal/decisional/comparative). Tags: `[project, tech, topic]`. Priority 5 routine / 7-8 decisions / 9-10 critical errors.
 6. Mark Phase 8 as `completed`
 
 ## Autonomous Loop Patterns
@@ -487,6 +534,56 @@ If ambiguous between Cancel and Steer → ask user: "Did you mean stop, or chang
 Hard caps: MAX_DEBUG_LOOPS=3, MAX_QUALITY_LOOPS=2, MAX_REPLAN=1, MAX_PIVOT=1, MAX_FIXES=30, WTF_THRESHOLD=20%.
 Escalation chain: debug-fix (3x) → re-plan (1x) → brainstorm rescue (1x) → THEN escalate to user.
 
+### Structured Escalation Report
+
+> From agency-agents (msitarzewski/agency-agents, 50.8k★): "After 3 retry failures, structured escalation prevents cargo-cult retrying."
+
+When escalation chain exhausts (all retries hit) or cook returns `BLOCKED`, produce a Structured Escalation Report instead of a vague "I can't do this":
+
+```markdown
+## Escalation Report
+- **Task**: [original task description]
+- **Status**: BLOCKED
+- **Attempts**: [count] across [N] phases
+
+### Failure History
+| # | Approach | Phase | Outcome | Root Cause |
+|---|---------|-------|---------|------------|
+| 1 | Direct fix | Phase 4 | Tests fail — null ref in auth.ts:42 | Missing user context |
+| 2 | Re-plan with guard clause | Phase 4 | Build fails — circular import | Guard approach introduces cycle |
+| 3 | Brainstorm rescue → adapter pattern | Phase 4 | Tests pass but perf regression 3x | Adapter adds indirection overhead |
+
+### Root Cause Analysis
+[1-2 sentences: why ALL approaches failed — is it architectural, environmental, or requirements-level?]
+
+### Recommended Resolutions (pick one)
+1. **Reassign** — different skill/agent with fresh context
+2. **Decompose** — break into smaller sub-tasks that CAN succeed independently
+3. **Revise requirements** — relax constraint X to unblock (specify which)
+4. **Accept partial** — ship what works, defer blocked portion
+5. **Defer** — park this task, work on something else first
+
+### Impact Assessment
+- **Blocked by this**: [downstream tasks/phases that depend on this]
+- **Not blocked**: [independent work that can continue]
+```
+
+<HARD-GATE>
+"Bad work is worse than no work." Cook MUST produce this report rather than attempting a 4th variant of a failing approach. Escalating is not failure — shipping broken code is.
+</HARD-GATE>
+
+### Subagent Question Gate
+
+> From superpowers (obra/superpowers, 84k★): "Subagents that start work without asking questions produce the wrong thing 40% of the time."
+
+Before dispatching a sub-skill (fix, test, review) for a non-trivial task (3+ files OR ambiguous scope):
+
+1. **Invite questions**: Include in the handoff: "Before starting, ask up to 3 clarifying questions if anything is unclear."
+2. **Answer before work**: If the sub-skill returns questions → answer them, THEN re-dispatch with answers included.
+3. **Skip if**: Fast/Nano rigor, single-file fix, or sub-skill is haiku-tier (too cheap to gate).
+
+This prevents the #1 parallel work failure: sub-skill assumes wrong interpretation, builds 500 LOC, then gets rejected in review.
+
 ### Subagent Status Protocol
 
 <MUST-READ path="references/subagent-status.md" trigger="when cook or any sub-skill needs to return a status"/>
@@ -615,6 +712,42 @@ Mentally track tool call fingerprints. 3 identical calls → WARN. 5 identical c
 | Quality Gate | preflight + sentinel + review before Phase 7 | Fix findings, re-run |
 | Verification Gate | lint + types + tests + build green before commit | Fix, re-run |
 
+## Structured Output Contract (Prompt-as-API Pattern)
+
+When cook invokes sub-skills that produce structured output (e.g., `ba` for requirements, `plan` for implementation plans, `test` for test specs), use the **Prompt-as-API-Contract** pattern: specify the exact output schema in the invocation prompt so the sub-skill returns machine-parseable results, not free-form prose.
+
+### Pattern
+
+```
+INVOCATION: "Analyze [X] and return results as JSON matching this schema:
+{
+  "insights": [{ "id": string, "category": string, "description": string, "actionable": string }],
+  "confidence": number,
+  "next_steps": string[]
+}
+Do NOT include explanatory text outside the JSON block."
+```
+
+### When to Apply
+
+| Phase | Sub-skill | Output Contract |
+|-------|-----------|----------------|
+| Phase 1 | `ba` | `{ requirements: [{id, priority, description, acceptance_criteria}], ambiguities: string[] }` |
+| Phase 2 | `plan` | `{ phases: [{name, tasks: [{description, files, effort}], dependencies}] }` |
+| Phase 3 | `test` | `{ test_cases: [{name, type, file, assertion}], coverage_targets: string[] }` |
+| Phase 5 | `review` | `{ findings: [{severity, file, line, description, fix}], verdict: "PASS"|"WARN"|"BLOCK" }` |
+
+### Rules
+
+- Include 1-2 concrete examples in the prompt — examples are worth more than schema descriptions
+- Always specify "Do NOT include explanatory text outside the JSON/markdown block" — LLMs default to wrapping structured output in prose
+- When the output will be consumed by another skill (not displayed to user), ALWAYS use this pattern
+- When the output will be displayed to the user, use markdown format instead — humans don't read JSON
+
+### Why
+
+Free-form sub-skill output forces the calling skill to parse natural language — fragile and lossy. Structured contracts make skill-to-skill communication reliable, enable automated validation, and reduce the tokens wasted on parsing instructions.
+
 ## Output Format
 
 <MUST-READ path="references/output-format.md" trigger="before emitting the Cook Report at end of any session"/>

package/skills/debug/SKILL.md

@@ -3,7 +3,7 @@ name: debug
 description: Root cause analysis for bugs and unexpected behavior. Traces errors through code, uses structured reasoning, and hands off to fix when cause is found. Core of the debug↔fix mesh.
 metadata:
   author: runedev
-  version: "0.8.0"
+  version: "0.9.0"
   layer: L2
   model: sonnet
   group: development
@@ -232,6 +232,21 @@ Track fix attempts in the Debug Report. If this is attempt N>1 for the same symp
 - Explain why the previous fix didn't hold
 - If N=3: trigger the escalation gate above — classify and route accordingly
 
+### 3+ Fixes as Architectural Signal
+
+> From superpowers (obra/superpowers, 84k★): "Each fix revealing new problems elsewhere = structural issue, not a bug hunt."
+
+When 3+ **distinct** fixes fail (not retries of the same fix), STOP treating it as a bug:
+
+| Signal | Interpretation | Next Step |
+|--------|---------------|-----------|
+| Same blocker each time (API limit, platform gap) | Wrong approach | `brainstorm(mode="rescue")` — need fundamentally different path |
+| Different bugs each fix (null → race → type) | Wrong architecture | `plan` redesign — module has structural problems |
+| Each fix creates a new bug elsewhere | Tight coupling | The module boundary is wrong — need to redraw boundaries before fixing |
+| Fix works locally but fails in integration | Missing contract | Cross-module interface is undefined — add explicit contracts first |
+
+**Key insight**: After 3 failures, question the DESIGN, not the CODE. "Try harder" is never the right answer at this point.
+
 ### Step 7: Report
 
 Produce structured output and hand off to rune:fix.

package/skills/docs/SKILL.md

@@ -3,7 +3,7 @@ name: docs
 description: Auto-generate and maintain project documentation. Creates README, API docs, architecture docs, changelogs, and keeps them in sync with code changes. The "docs are never outdated" skill.
 metadata:
   author: runedev
-  version: "0.2.0"
+  version: "0.3.0"
   layer: L2
   model: sonnet
   group: delivery
@@ -174,9 +174,32 @@ Never silently remove doc content. If code was deleted, mark the doc section as
 
 Delegate to `rune:git changelog` to produce a changelog entry from commits since last docs update.
 
-#### Step 4 — Report
+#### Step 4 — Cross-Doc Consistency Pass
 
-Show user: what was updated, what was added, what was flagged for review.
+> From gstack (garrytan/gstack, 50.9k★): "Cross-document consistency prevents the #2 docs problem: docs that exist but contradict each other."
+
+After updating any doc, verify consistency across all project documentation:
+
+| Check | Files | What to Compare |
+|-------|-------|----------------|
+| **Version numbers** | README, CLAUDE.md, package.json, CHANGELOG | Must all match current version |
+| **Feature lists** | README, landing page, CLAUDE.md | Same features listed (may differ in detail level) |
+| **Stats** | README, CLAUDE.md, landing page, dashboard | Skill count, test count, signal count must match |
+| **Commands** | README, CLAUDE.md, docs/ | Same commands with same flags |
+| **Tech stack** | README, ARCHITECTURE.md, CLAUDE.md | Consistent framework/library references |
+
+```
+Cross-Doc Consistency:
+- [x] README.md ↔ CLAUDE.md: versions match, commands match
+- [x] README.md ↔ docs/index.html: stats match, features match
+- [ ] README.md says "61 skills" but CLAUDE.md says "59" → FIX CLAUDE.md
+```
+
+**Fix inconsistencies immediately** — don't just report them. Update the stale doc to match the source of truth (usually the code or the most recently updated doc).
+
+#### Step 5 — Report
+
+Show user: what was updated, what was added, what was flagged for review. Include Cross-Doc Consistency results.
 
 ### API Mode
 
@@ -316,6 +339,8 @@ Docs Update Report:
 | API docs with wrong request/response shapes | HIGH | Extract from Zod/Pydantic/TypeScript types, not from memory |
 | Missing Quick Start section | MEDIUM | Constraint 4: every README has Quick Start |
 | Changelog with orphan PR links | LOW | Validate PR numbers exist before linking |
+| Cross-document inconsistency (README says X, CLAUDE.md says Y) | HIGH | Step 7: Cross-Doc Consistency Pass — verify stats, versions, and feature lists match across all docs |
+| Updating one doc but not others (stats drift) | HIGH | After any doc update, sweep all related docs for stale stats — especially README ↔ CLAUDE.md ↔ landing page |
 
 ## Done When
 

package/skills/fix/SKILL.md

@@ -3,7 +3,7 @@ name: fix
 description: Apply code changes and fixes. Writes implementation code, applies bug fixes, and verifies changes with tests. Core action hub in the development mesh.
 metadata:
   author: runedev
-  version: "0.6.0"
+  version: "0.7.0"
   layer: L2
   model: sonnet
   group: development
@@ -263,6 +263,7 @@ Known failure modes for this skill. Check these before declaring done.
 | Single-point validation (fix one spot, hope it holds) | MEDIUM | Step 5: add entry + business logic + environment + debug layers for data-flow bugs |
 | Removing debug instrumentation before fix is verified | MEDIUM | Step 5b: preserve `#region agent-debug` markers until all tests pass — premature cleanup erases failure history |
 | Runaway fix loop — 20+ fixes without checking quality decay | HIGH | Step 4.5: WTF-likelihood self-regulation. >20% risk = STOP. Hard cap 30 fixes/session. Each fix adds risk — diminishing returns after ~15 |
+| Each fix creates a new bug elsewhere — whack-a-mole | CRITICAL | Tight coupling signal. STOP fixing → escalate to debug with note "each fix creates new failure — suspect structural issue". Debug will route to plan for redesign |
 
 ## Done When
 

package/skills/mcp-builder/SKILL.md

@@ -3,7 +3,7 @@ name: mcp-builder
 description: Build Model Context Protocol servers from specifications. Generates tool definitions, resource handlers, and test suites for MCP servers in TypeScript or Python (FastMCP).
 metadata:
   author: runedev
-  version: "0.3.0"
+  version: "0.4.0"
   layer: L2
   model: sonnet
   group: creation
@@ -321,6 +321,58 @@ mcp-server-<name>/
 - Installation: Claude Code, Cursor, Windsurf config snippets
 - Configuration reference (env vars with descriptions)
 
+## Reference Pattern: Multi-Provider Adapter
+
+When the MCP server needs to call multiple AI providers (e.g., both Anthropic and OpenAI), use the **Provider Adapter** pattern to normalize different APIs behind a unified interface.
+
+### Interface
+
+```typescript
+interface ProviderAdapter {
+  formatRequest(params: RequestParams): { url: string; init: RequestInit };
+  parseResponse(data: unknown): { content: string; usage: TokenUsage | null };
+  formatStreamRequest(params: RequestParams): { url: string; init: RequestInit };
+  parseSSEEvent(eventType: string, data: string): StreamChunk | null;
+}
+```
+
+### Discriminated Union for Stream Chunks
+
+```typescript
+type StreamChunk =
+  | { type: "thinking"; content: string }
+  | { type: "text"; content: string }
+  | { type: "done" }
+  | { type: "done_with_usage"; usage: TokenUsage }
+  | { type: "usage_delta"; inputTokens?: number; outputTokens?: number }
+  | { type: "error"; message: string };
+```
+
+### When to Apply
+
+- MCP server wraps multiple AI providers (e.g., a router server that dispatches to Claude, GPT, or local models)
+- MCP server aggregates responses from multiple APIs with different response formats
+- MCP server needs to support streaming from providers with different SSE event schemas
+
+### Key Implementation Notes
+
+- Each provider adapter handles its own SSE event types (Anthropic: `content_block_delta`, `message_start`; OpenAI: `response.output_text.delta`, `[DONE]`)
+- Buffer management for SSE: handle incomplete lines, track event types, manage abort signals
+- Provider-specific prompt tuning: some models benefit from additional constraints (e.g., "Maximum 2-3 paragraphs" for verbose models)
+- Per-provider token tracking: normalize different usage reporting formats into a single `TokenUsage` type
+
+### Cost-Aware Model Selection
+
+When building MCP servers that call AI providers, support **dual-model configuration** — allow users to specify a primary model for critical operations and a cheaper model for background tasks (summarization, classification, metadata extraction). This avoids burning expensive API credits on tasks that don't need maximum quality.
+
+```typescript
+// config.ts
+const config = {
+  primaryModel: process.env.PRIMARY_MODEL || 'claude-sonnet-4-20250514',
+  backgroundModel: process.env.BACKGROUND_MODEL || 'claude-haiku-4-5-20251001',
+};
+```
+
 ## Constraints
 
 1. MUST validate all tool inputs with Zod (TS) or Pydantic (Python) — never trust AI-provided inputs

package/skills/onboard/SKILL.md

@@ -3,7 +3,7 @@ name: onboard
 description: Auto-generate project context for AI sessions. Scans codebase, creates CLAUDE.md and .rune/ setup so every future session starts with full context.
 metadata:
   author: runedev
-  version: "0.3.0"
+  version: "0.4.0"
   layer: L2
   model: sonnet
   group: quality
@@ -227,6 +227,56 @@ Audit the project's baseline context cost from MCP servers and agent configurati
 
 **Skip if**: Total MCP tools ≤80 AND CLAUDE.md ≤150 lines (healthy baseline).
 
+### Step 6e — AI-Driven Interview (Optional, User-Initiated)
+
+When invoked as `/rune onboard --interview` or when the project is too ambiguous for automated detection (e.g., no package.json, no clear entry point, mixed languages), switch to **conversational onboarding** — the AI asks targeted questions instead of relying solely on file scanning.
+
+#### Interview Flow
+
+Ask 5-8 questions in sequence, adapting based on answers. Start broad, narrow based on responses:
+
+```
+Q1: "What does this project do in one sentence?"
+    → Captures purpose (README may be missing or outdated)
+
+Q2: "Who uses this — internal team, external users, or both?"
+    → Determines audience, affects DEVELOPER-GUIDE.md tone
+
+Q3: "What's the main entry point — where does execution start?"
+    → Bypasses file scanning for complex monorepos
+
+Q4: "What commands do you use daily? (dev server, tests, build)"
+    → Gets verified commands instead of guessing from config files
+
+Q5: "Any areas of the codebase you'd warn a new developer about?"
+    → Captures tribal knowledge that no scan can detect
+
+Q6: "Are there external services this depends on? (databases, APIs, queues)"
+    → Maps integration points for Architecture Map
+
+Q7: "What's the deployment story — how does code get to production?"
+    → Captures CI/CD context
+
+Q8 (conditional): "Anything else a new session should know that's not in the code?"
+    → Catches edge cases, workarounds, known issues
+```
+
+#### Interview Rules
+
+- **Adapt**: Skip questions that were already answered by earlier responses. If Q1 reveals "it's a Next.js app", don't ask about the framework.
+- **Validate**: Cross-reference answers with actual file scan results. If user says "we use Jest" but `vitest.config.ts` exists, ask to clarify.
+- **Merge**: Interview answers supplement (not replace) automated scan. Scan provides facts, interview provides context and intent.
+- **Store**: Save interview responses as high-confidence entries in `.rune/conventions.md` and `.rune/cumulative-notes.md` (tagged `[from-interview]`)
+
+#### When to Auto-Suggest Interview
+
+Suggest switching to interview mode (but don't force it) when:
+- Step 2 produces 3+ "unknown" fields in tech stack detection
+- Project has no README.md and no package.json/pyproject.toml/Cargo.toml
+- Project appears to be a monorepo with 3+ distinct sub-projects
+
+Output: `"ℹ️ This project is hard to auto-detect. Run /rune onboard --interview for guided setup."`
+
 ### Step 7 — Commit
 Use `Bash` to stage and commit the generated files:
 ```bash