@rune-kit/rune 2.14.0 → 2.16.0

package/skills/context-pack/references/agent-brief.md

@@ -0,0 +1,194 @@
+# Agent Brief (Durable Handoff Variant)
+
+A context-pack variant designed for **async handoff to AFK agents** — one-shot agents that pick up work hours or days later, without the live conversation context. The standard context-pack is for immediate sub-agent dispatch; the agent brief is for the handoff that may sit in a queue (issue tracker, task board, scheduled run).
+
+> The standard packet is a system prompt. The agent brief is a contract. Both must survive without the originating conversation; the brief must also survive code drift.
+
+## When to use agent-brief vs standard packet
+
+| Variant | Use when |
+|---------|----------|
+| **Standard packet** (`Output Format` in SKILL.md) | Immediate dispatch — sub-agent runs in the same session, < 1 hour delay, codebase will not drift |
+| **Agent brief** (this file) | Async dispatch — task posted to issue tracker, scheduled run, or external worker. May sit for days. Codebase may rename/move files in the meantime. |
+
+Both share the same compression discipline. Agent brief adds **durability rules** to survive drift.
+
+## The two extra principles
+
+### 1. Durability over precision
+
+The brief may execute days later. Files renamed, moved, refactored. Write so the brief stays useful.
+
+| Do | Don't |
+|----|-------|
+| Describe interfaces, types, behavioral contracts | Reference file paths in narrative ("change `src/auth/login.ts`") |
+| Name specific types, function signatures, config shapes the agent should look for | Reference line numbers ("on line 42") |
+| Describe what to find ("the function that validates JWT tokens") | Assume current implementation structure stays the same |
+
+File paths can appear in `### Files Touched` (locator-only, may rename). They cannot appear in narrative.
+
+### 2. Behavioral, not procedural
+
+Describe **what** the system should do, not **how** to implement it. The agent will explore the codebase fresh and make implementation decisions.
+
+| Behavioral (good) | Procedural (bad) |
+|-------------------|------------------|
+| `SkillConfig` should accept an optional `schedule: CronExpression` field | Open `src/types/skill.ts` and add a `schedule` field on line 42 |
+| When user runs `/triage` with no args, show a summary of issues needing attention | Add a switch statement in the main handler |
+| Truncated descriptions end at last word boundary before 1024 chars and append `...` | Modify the `truncate()` function to check word boundaries |
+
+## Template
+
+```markdown
+## Agent Brief
+
+**Category:** bug | enhancement | refactor
+**Summary:** one-line description of what needs to happen
+
+**Current behavior:**
+What happens now. For bugs: the broken behavior. For enhancements: the status quo.
+
+**Desired behavior:**
+What should happen after the work is complete. Be specific about edge cases and error conditions.
+
+**Key interfaces:**
+- `TypeName` — what needs to change and why
+- `functionName(input: T): Result<O, E>` — current contract vs desired contract
+- Config shape — any new options needed
+
+**Acceptance criteria:**
+- [ ] Specific, independently testable criterion 1
+- [ ] Specific, independently testable criterion 2
+- [ ] Specific, independently testable criterion 3
+
+**Out of scope:**
+- Thing that should NOT be changed
+- Adjacent feature that might seem related but is separate
+- (or "(none)" if explicitly empty)
+
+**Files Touched (locator hints, may rename):**
+- `path/to/file.ts` (`TypeName`, `functionName`) — behavioral hint
+```
+
+## Worked example — bug
+
+```markdown
+## Agent Brief
+
+**Category:** bug
+**Summary:** Skill description truncation drops mid-word, producing broken output
+
+**Current behavior:**
+When a skill description exceeds 1024 characters, it is truncated at exactly 1024
+characters regardless of word boundaries. Output ends mid-word
+(e.g. "Use when the user wants to confi").
+
+**Desired behavior:**
+Truncation should break at the last word boundary before 1024 characters and
+append "..." to indicate truncation. Total length including "..." must not
+exceed 1024 chars.
+
+**Key interfaces:**
+- The `SkillMetadata` type's `description` field — no type change, but the
+  validation/processing logic that populates it needs to respect word boundaries
+- Any function that reads SKILL.md frontmatter and extracts the description
+
+**Acceptance criteria:**
+- [ ] Descriptions under 1024 chars are unchanged
+- [ ] Descriptions over 1024 chars are truncated at the last word boundary before 1024 chars
+- [ ] Truncated descriptions end with "..."
+- [ ] Total length including "..." does not exceed 1024 chars
+
+**Out of scope:**
+- Changing the 1024 char limit itself
+- Multi-line description support
+
+**Files Touched:**
+- `compiler/parser.js` (`extractDescription`) — likely truncation site
+- `compiler/__tests__/skill-description-quality.test.js` — add coverage
+```
+
+## Worked example — enhancement
+
+```markdown
+## Agent Brief
+
+**Category:** enhancement
+**Summary:** Add `.out-of-scope/` directory support for tracking rejected feature requests
+
+**Current behavior:**
+Rejected feature requests are closed with a `wontfix` label and a comment.
+No persistent record of decision or reasoning. Future similar requests require
+the maintainer to recall or search prior discussion.
+
+**Desired behavior:**
+Rejected feature requests are documented in `.out-of-scope/<concept>.md` files
+capturing decision, reasoning, and links to all issues that requested the
+feature. New issues are matched against these files during triage.
+
+**Key interfaces:**
+- Markdown file format in `.out-of-scope/` — each file has a `# Concept Name`
+  heading, `**Decision:**` line, `**Reason:**` line, `**Prior requests:**` list
+- The triage workflow reads all `.out-of-scope/*.md` files early and matches
+  incoming issues by concept similarity
+
+**Acceptance criteria:**
+- [ ] Closing a feature as wontfix creates/updates a file in `.out-of-scope/`
+- [ ] File includes the decision, reasoning, link to the closed issue
+- [ ] If a matching `.out-of-scope/` file already exists, the new issue is appended
+      to its "Prior requests" list rather than creating a duplicate
+- [ ] During triage, existing `.out-of-scope/` files are checked and surfaced
+      when a new issue matches a prior rejection
+
+**Out of scope:**
+- Automated matching (human confirms the match)
+- Reopening previously rejected features
+- Bug reports (only enhancement rejections go to `.out-of-scope/`)
+```
+
+## Anti-pattern (what makes a brief rot)
+
+```markdown
+## Agent Brief
+
+**Summary:** Fix the triage bug
+
+**What to do:**
+The triage thing is broken. Look at the main file and fix it.
+The function around line 150 has the issue.
+
+**Files to change:**
+- src/triage/handler.ts (line 150)
+- src/types.ts (line 42)
+```
+
+Rots because:
+- No category
+- Vague summary ("the triage thing")
+- Line numbers in narrative — go stale on first edit
+- File paths in narrative without behavioral hint
+- No acceptance criteria
+- No scope boundaries
+- No current vs desired behavior split
+
+## Smell test additions for agent-brief
+
+In addition to the BLOCK-tier smell tests in `context-pack/SKILL.md`, agent briefs MUST also pass:
+
+| Check | Tier | Reason |
+|-------|------|--------|
+| Has `**Category:**` line with `bug`, `enhancement`, or `refactor` | BLOCK | Agent uses category for routing decisions |
+| Has `**Current behavior:**` AND `**Desired behavior:**` sections | BLOCK | Without both, agent can't verify the delta |
+| Acceptance criteria are independently testable (each can pass/fail alone) | BLOCK | Bundled criteria hide partial completion |
+| `**Key interfaces:**` names actual types/functions, not file paths | BLOCK | The whole point of the brief — drift survival |
+| `**Out of scope:**` present (even `(none)`) | BLOCK | Prevents gold-plating |
+
+## Integration
+
+Use agent-brief when delegating to:
+- An issue tracker (GitHub issue, Linear, Jira) for an AFK agent to pick up
+- `rune:autopilot` (Pro) for autonomous multi-session work
+- A scheduled cron agent (`/schedule` for one-time follow-up)
+- Any handoff where the receiver may not see the originating conversation
+
+Use the standard packet for in-session subagent dispatch (cook → fix, team → workstream).

package/skills/cook/SKILL.md

@@ -217,7 +217,7 @@ Auto-trigger: no `.rune/` dir (first run) OR build just failed with env-looking
 
 1. Create TodoWrite with all applicable phases for this task
 2. Mark Phase 1 as `in_progress`
-3. **BA gate**: Feature Request / Integration / Greenfield → invoke `rune:ba`. Task > 50 words or business terms (users, revenue, workflow) → invoke `rune:ba`. Bug Fix / simple Refactor → skip. BA produces `.rune/features/<name>/requirements.md` for Phase 2.
+3. **BA gate**: Feature Request / Integration / Greenfield → invoke `rune:ba`. Task > 50 words or business terms (users, revenue, workflow) → invoke `rune:ba`. Bug Fix / simple Refactor → skip. BA produces `.rune/features/<name>/requirements.md` for Phase 2. **Synthesis-mode auto-trigger**: if user pasted a spec > 200 words, conversation has > 1000 words on this feature, `.rune/features/<name>/requirements.md` already exists (continuation), or user said "synthesize"/"just write the spec" → BA Step 1.4 activates Synthesis Mode (extract + cite sources + confirm), skipping the 5-question elicitation. Cook does NOT need to choose mode — BA detects automatically.
 4. **Decision enforcement**: `Glob` for `.rune/decisions.md`; if exists, `Read` + extract constraints for Phase 2. Plan MUST NOT contradict active decisions without explicit user override.
 4b. **Contract enforcement**: If `.rune/contract.md` was loaded in Phase 0.6, list applicable contract sections for this task (e.g., `contract.security` for auth work, `contract.data` for database changes). These rules constrain Phase 2 planning and Phase 4 implementation.
 
@@ -384,6 +384,7 @@ If the coder model needs info from other phases, it's in the Cross-Phase Context
 4. Run tests after each significant change — if fail → debug and fix
    - **Python async** (if async-first flagged): no blocking calls in async functions — `time.sleep` → `asyncio.sleep`, `requests` → `httpx.AsyncClient`, use `asyncio.gather()` for parallel I/O
 5. If stuck → invoke `rune:debug` (max 3 debug↔fix loops). Fixes outside plan scope require user approval (R4).
+   - **Oracle reattach check** — between tasks, glob `.rune/oracle-pending/*.json`. For any record with `status=pending`, invoke `session-bridge --reattach <sessionId>`. If `complete` → consume the response (route to debug/fix per `sourceSkill`). If `pending` → continue with next independent task. If `failed` → continue without second opinion.
 6. **Re-plan check** — evaluate before Phase 5: max debug loops hit? out-of-scope files changed? new dep changes approach? user scope change? If any fire → invoke `rune:plan` with delta context, get user approval before resuming.
 7. **Approach Pivot Gate** — if re-plan ALSO fails:
 
@@ -765,7 +766,7 @@ Mentally track tool call fingerprints. 3 identical calls → WARN. 5 identical c
 | 5 | `scope-guard` | L3 | Verify changed files match approved plan scope (flag out-of-scope files before commit) |
 | 5 | `perf` | L2 | Performance regression check (optional) |
 | 5 | `audit` | L2 | Project health audit when scope warrants |
-| 5 | `review-intake` | L2 | Structured review intake for complex PRs |
+| 5 | `review-intake` | L2 | Structured review intake for complex PRs OR Issue Triage Mode for issue tracker items (state machine: needs-triage / needs-info / ready-for-agent / ready-for-human / wontfix). When external feedback source is an issue (not PR comment), review-intake auto-detects and runs Issue Triage Mode — emits `triage.classified` + `agent.brief.ready` (for AFK pickup) |
 | 5 | `sast` | L3 | Static analysis security testing |
 | 5d | `completion-gate` | L3 | Validate agent claims against evidence trail |
 | 5 | `constraint-check` | L3 | Audit HARD-GATE compliance across workflow |

package/skills/db/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: db
-description: Database workflow specialist. Generates migration files with rollback scripts, detects breaking schema changes, and validates query parameterization.
+description: "Database workflow specialist. Generates migration files with rollback scripts, detects breaking schema changes, and validates query parameterization."
 metadata:
   author: runedev
   version: "0.2.0"

package/skills/debug/SKILL.md

@@ -1,15 +1,15 @@
 ---
 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.
+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: "1.1.0"
+  version: "1.2.0"
   layer: L2
   model: sonnet
   group: development
   tools: "Read, Bash, Glob, Grep"
   emit: bug.diagnosed, agent.stuck
-  listen: tests.failed
+  listen: tests.failed, oracle.response
 ---
 
 # debug
@@ -21,8 +21,9 @@ Root cause analysis ONLY. Debug investigates — it does NOT fix. It traces erro
 <HARD-GATE>
 Do NOT fix the code. Debug investigates only. Any code change is out of scope.
 If root cause cannot be identified after 3 hypothesis cycles:
-- Emit `agent.stuck` signal — `scout` zoom-out mode may surface the broader module map that's hiding the root cause
-- Escalate to `rune:problem-solver` for structured 5-Whys or Fishbone analysis
+- Emit `agent.stuck` signal — `scout` zoom-out mode surfaces broader module map (structural pivot); `adversary` oracle-mode dispatches a stateless second-model pass (semantic pivot); both fire in parallel
+- If `oracle.response` arrives with confidence=high and cites file:line, treat as new hypothesis H_oracle and test directly (skip 3-cycle gate — it's externally validated)
+- Otherwise, escalate to `rune:problem-solver` for structured 5-Whys or Fishbone analysis
 - Or escalate to `rune:sequential-thinking` for multi-variable analysis
 - Report escalation in the Debug Report with all evidence gathered so far
 </HARD-GATE>
@@ -46,6 +47,7 @@ If root cause cannot be identified after 3 hypothesis cycles:
 - `browser-pilot` (L3): capture browser console errors, network failures, visual bugs
 - `sequential-thinking` (L3): multi-variable root cause analysis
 - `neural-memory` (L3): after root cause found — capture error pattern for future recognition
+- `adversary` (L2): on `agent.stuck` — oracle-mode dispatches stateless second-model pass to break confirmation-bias loop (parallel with scout zoom-out)
 
 ## Called By (inbound)
 
@@ -61,6 +63,17 @@ If root cause cannot be identified after 3 hypothesis cycles:
 
 ## Execution
 
+### Step 0: Build a Feedback Loop (the actual skill)
+<MUST-READ path="references/feedback-loop-ladder.md" trigger="when current repro is not a single command returning pass/fail in <5s, or when bug is intermittent/multi-component"/>
+
+**The loop is the speed limit.** A fast, deterministic, agent-runnable pass/fail signal turns debugging into mechanical bisection. Without one, hypotheses just consume noise.
+
+Skip Step 0 only if the existing repro is already one command, deterministic, and runs in < 5s.
+
+Otherwise, before Step 1: pick the highest viable rung from `references/feedback-loop-ladder.md` (10-rank ladder: failing test → curl → CLI snapshot → headless browser → trace replay → throwaway harness → fuzz → bisection → differential → HITL script). Construct it. Verify it currently FAILS (proves it measures the bug, not noise). Only then proceed.
+
+If loop construction takes > 10 minutes, that itself is the diagnosis: the bug surface is too large or the system too coupled. Trigger the 3-Fix Escalation Rule (Step 6) — architecture is the problem, not the bug.
+
 ### Step 1: Reproduce
 
 Understand and confirm the error described in the request.
@@ -347,6 +360,7 @@ ALL of these mean: STOP. Return to Step 2 (Gather Evidence).
 7. MUST NOT say "I know what's wrong" without citing file:line evidence
 8. For deep stack errors: MUST use backward tracing (Step 2) — never fix at the crash site
 9. For multi-component systems: MUST instrument boundaries before hypothesizing
+10. MUST run Step 0 (Build Feedback Loop) before forming hypotheses on non-trivial bugs — skipping the loop = guessing
 
 ## Output Format
 
@@ -413,7 +427,7 @@ Append to Debug Report when invoked standalone. Suppress when called as sub-skil
 ```yaml
 chain_metadata:
   skill: "rune:debug"
-  version: "1.1.0"
+  version: "1.2.0"
   status: "[DONE | DONE_WITH_CONCERNS | NEEDS_CONTEXT | BLOCKED]"
   domain: "[area debugged]"
   files_changed: []  # debug never changes files
@@ -447,6 +461,8 @@ chain_metadata:
 | Debug report recommends touching 5+ unrelated files | HIGH | Symptom of fixing at crash sites instead of source. Backward trace (Step 2) to find origin. If truly 5+ files → likely architectural issue → escalate via 3-Fix Rule |
 | Re-investigating known error patterns from scratch | MEDIUM | Step 2d: match error against Known Error Pattern Catalog first — skip hypothesis cycling for recognized patterns |
 | Same error fingerprint across cycles treated as different errors | MEDIUM | Step 2d: normalize line numbers, paths, variable names before comparison — same fingerprint = same error |
+| Forming hypotheses with a slow / non-deterministic / manual repro | CRITICAL | Step 0: build a fast deterministic pass/fail signal first — see `references/feedback-loop-ladder.md` 10-rank ladder. Hypothesis testing on a slow loop wastes 10x the cycles |
+| Skipping loop construction "to save time" on non-trivial bugs | HIGH | The loop IS the time-saver. 10 min on the loop saves hours of cycling. If construction takes > 10 min, escalate via 3-Fix Rule — bug is architectural |
 
 ## Done When
 

package/skills/debug/references/feedback-loop-ladder.md

@@ -0,0 +1,62 @@
+# Feedback Loop Ladder
+
+**The loop is the skill.** A fast, deterministic, agent-runnable pass/fail signal converts debugging into a mechanical bisection problem. Without one, no amount of file-reading will save you.
+
+> "The rate of feedback is your speed limit." Spend disproportionate effort on the loop itself — bisection, hypothesis testing, and instrumentation all just consume that signal.
+
+## When to invest in a better loop
+
+Run the ladder before Step 3 (Form Hypotheses) when ANY of these are true:
+
+| Signal | Threshold |
+|--------|-----------|
+| Repro is "click around in browser, then check" | Always — slowest possible loop |
+| Cycle 1 hypotheses ruled out, no faster signal exists | Required before cycle 2 |
+| Reproduction is intermittent (flaky) | Required — non-deterministic loop wastes cycles |
+| Bug spans 3+ components and you can't isolate where it fails | Build component-boundary instrumentation FIRST |
+| Manual repro takes > 30 seconds | Auto-script it before forming hypotheses |
+
+**Skip if:** repro is already a single command returning exit code 0/1 in < 5s. The loop is already optimal.
+
+## The ladder (try in order — stop at first viable rung)
+
+| # | Loop | Speed | Determinism | When |
+|---|------|-------|-------------|------|
+| 1 | **Failing test at the bug's seam** (unit, integration, e2e) | Fast | Hard pass/fail | Default — bug already has a test infrastructure |
+| 2 | **curl / HTTP script** against running dev server | Fast | Snapshot-diffable | API or backend bugs |
+| 3 | **CLI invocation with fixture input**, diff stdout vs known-good snapshot | Fast | Snapshot-diffable | CLI tools, parsers, formatters |
+| 4 | **Headless browser script** (Playwright / `rune:browser-pilot`) — drives UI, asserts on DOM/console/network | Medium | Reliable | UI bugs, JS errors, network failures |
+| 5 | **Replay a captured trace** — save real network request / payload / event log to disk; replay through code path in isolation | Fast | Deterministic | Bugs reproducible only with specific data |
+| 6 | **Throwaway harness** — minimal subset of system (one service, mocked deps), exercise bug code path with single function call | Fast | Isolated | Bug deep inside framework or service stack |
+| 7 | **Property / fuzz loop** — 1000 random inputs, look for failure mode | Slow | Probabilistic | "Sometimes wrong output", race conditions, edge cases |
+| 8 | **Bisection harness** — automate "boot at state X, check, repeat" so `git bisect run` works | Medium | Hard pass/fail | Bug appeared between two known commits / dataset versions |
+| 9 | **Differential loop** — same input through old vs new (or two configs), diff outputs | Medium | Diff-based | Regression vs reference implementation |
+| 10 | **HITL bash script** — last resort. Drive the human with a structured script | Slow | Human-error-prone | All else fails — at least the loop has structure |
+
+## What "good loop" looks like
+
+- One command, one second to run, one bit of output (pass / fail)
+- Deterministic — same input → same output, every time
+- Captures the bug, not a proxy ("test passes when bug present" is a broken loop)
+- Cleanup-safe — re-runnable without manual reset
+
+## Anti-patterns
+
+| Anti-pattern | Why it fails |
+|--------------|--------------|
+| "I'll just print and check the console" | Stateless, manual, slow — degrades to staring at logs |
+| "Let me read the code one more time" | Reading is not a loop. Loop = pass/fail signal. |
+| "It works on my machine, not in CI" | Build a loop in the CI environment FIRST |
+| Skipping loop construction because "it's complicated" | The loop is the skill. Skipping it = guessing for the next 5 cycles |
+
+## Integration with Step 0
+
+Add Step 0 (before Reproduce) when invoked on a non-trivial bug:
+
+```
+0. Build feedback loop — pick the highest rung from the ladder that you can construct
+   in < 10 minutes. Make it deterministic. Verify it currently FAILS (proves it's
+   measuring the bug, not noise). Only then proceed to Step 1.
+```
+
+If loop construction takes > 10 minutes, that itself is the diagnosis: the bug surface is too large or the system is too coupled. Escalate via 3-Fix Rule (architecture is the problem, not the bug).

package/skills/dependency-doctor/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: dependency-doctor
-description: Dependency health management. Detects package manager, checks outdated packages and vulnerabilities, and produces a prioritized update plan.
+description: "Dependency health management. Detects package manager, checks outdated packages and vulnerabilities, and produces a prioritized update plan."
 metadata:
   author: runedev
   version: "0.2.0"

package/skills/design/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: design
-description: Design system reasoning. Maps product domain to style, palette, typography, and platform-specific patterns. Generates .rune/design-system.md as the shared design contract for all UI-generating skills.
+description: "Design system reasoning. Maps product domain to style, palette, typography, and platform-specific patterns. Generates .rune/design-system.md as the shared design contract for all UI-generating skills."
 metadata:
   author: runedev
   version: "0.5.0"

package/skills/doc-processor/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: doc-processor
-description: Generate and parse office documents — PDF, DOCX, XLSX, PPTX, CSV. Pure format utility for creating reports, exporting data, and processing uploaded documents.
+description: "Generate and parse office documents — PDF, DOCX, XLSX, PPTX, CSV. Use when creating reports, exporting tabular data, or processing uploaded office files. NOT for project documentation (use docs)."
 metadata:
   author: runedev
   version: "0.2.0"

package/skills/docs/SKILL.md

@@ -1,6 +1,6 @@
 ---
 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.
+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.3.0"

package/skills/docs-seeker/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: docs-seeker
-description: Find documentation for APIs, libraries, and error messages. Looks up official docs, changelog entries, and migration guides.
+description: "Find documentation for APIs, libraries, and error messages. Looks up official docs, changelog entries, and migration guides."
 metadata:
   author: runedev
   version: "0.2.0"

package/skills/fix/SKILL.md

@@ -1,6 +1,6 @@
 ---
 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.
+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: "1.0.0"
@@ -9,7 +9,7 @@ metadata:
   group: development
   tools: "Read, Write, Edit, Bash, Glob, Grep"
   emit: code.changed, agent.stuck
-  listen: bug.diagnosed, review.issues, preflight.blocked, security.blocked
+  listen: bug.diagnosed, review.issues, preflight.blocked, security.blocked, oracle.response
 ---
 
 # fix
@@ -41,6 +41,7 @@ If unsure whether the test is wrong or the implementation is wrong → call `run
 - `hallucination-guard` (L3): verify imports after code changes
 - `scout` (L2): find related code before applying changes
 - `neural-memory` (L3): after fix verified — capture fix pattern (cause → solution)
+- `adversary` (L2): on `agent.stuck` after 2+ failed attempts — oracle-mode dispatches stateless second-model pass to break confirmation-bias loop
 
 ## Called By (inbound)
 
@@ -142,7 +143,7 @@ When fix is called repeatedly (e.g., by cook Phase 4, or iterative fix loops), t
 **Thresholds:**
 - **>20% WTF-likelihood**: STOP fixing. Report current state to cook/user with: "Quality decay detected — continued fixes risk introducing more bugs than they resolve. {N} fixes applied, {score}% risk. Recommend: commit current progress, re-assess remaining issues."
 - **Hard cap: 30 fixes per session** — regardless of score. After 30, STOP and report.
-- **2+ consecutive fixes on the same file all failed**: emit `agent.stuck` signal (listened by `scout` zoom-out mode). Receiving agents may zoom out to the surrounding module map to recover bigger-picture context.
+- **2+ consecutive fixes on the same file all failed**: emit `agent.stuck` signal. `scout` zoom-out mode (structural pivot) and `adversary` oracle-mode (semantic pivot via stateless second-model dispatch) both listen and fire in parallel. If `oracle.response` arrives with confidence=high, apply its recommended edit (still routes through normal validation gates).
 
 **Reset conditions:** WTF-likelihood resets to 0% when:
 - User explicitly says "continue fixing"

package/skills/git/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: git
-description: Specialized git operations — semantic commits, PR descriptions, branch management, conflict resolution guidance. Replaces ad-hoc git commands with a dedicated, convention-aware utility.
+description: "Specialized git operations — semantic commits, PR descriptions, branch management, conflict resolution guidance. Replaces ad-hoc git commands with a dedicated, convention-aware utility."
 metadata:
   author: runedev
   version: "0.3.0"

package/skills/hallucination-guard/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: hallucination-guard
-description: Verify AI-generated imports, API calls, and packages actually exist. Catches phantom functions, non-existent packages, and slopsquatting attacks.
+description: "Verify AI-generated imports, API calls, and packages actually exist. Use when finishing AI-generated code that introduces new imports or external API calls — auto-fires after fix/cook to catch phantom functions, non-existent packages, and slopsquatting attacks."
 metadata:
   author: runedev
   version: "0.3.0"

package/skills/integrity-check/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: integrity-check
-description: "Verify integrity of persisted state, skill outputs, and context bus data. Detects prompt injection, memory poisoning, identity spoofing, and adversarial payloads in .rune/ files and agent outputs. Called by sentinel, team, and session-bridge."
+description: "Verify integrity of persisted state, skill outputs, and context bus data. Use when validating .rune/ files or sub-agent outputs against prompt injection, memory poisoning, identity spoofing, or adversarial payloads. Called by sentinel, team, session-bridge."
 user-invocable: false
 metadata:
   author: runedev

package/skills/journal/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: journal
-description: Persistent state tracking and Architecture Decision Records across sessions. Use when recording a decision, ADR, or progress that must survive session boundaries. Manages progress state, module health, dependency graphs, and ADRs for any workflow.
+description: "Persistent state tracking and Architecture Decision Records across sessions. Use when recording a decision, ADR, or progress that must survive session boundaries. Manages progress state, module health, dependency graphs, and ADRs for any workflow."
 metadata:
   author: runedev
   version: "0.4.0"

package/skills/logic-guardian/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: logic-guardian
-description: Protects complex business logic from accidental deletion or overwrite. Maintains a logic manifest, enforces pre-edit gates, and validates post-edit diffs.
+description: "Protects complex business logic from accidental deletion or overwrite. Use when editing payment, trading, state-machine, or other load-bearing business logic where a single deleted line can cause silent data corruption. Maintains a logic manifest, enforces pre-edit gates, validates post-edit diffs."
 metadata:
   author: runedev
   version: "0.3.0"

package/skills/marketing/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: marketing
-description: Create marketing assets and execute launch strategy. Generates landing copy, social banners, SEO meta, blog posts, and video scripts.
+description: "Create marketing assets and execute launch strategy. Generates landing copy, social banners, SEO meta, blog posts, and video scripts."
 metadata:
   author: runedev
   version: "0.6.0"

package/skills/mcp-builder/SKILL.md

@@ -1,6 +1,6 @@
 ---
 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).
+description: "Build Model Context Protocol servers from specifications. Use when creating an MCP server for a tool, resource, or service that AI agents should access. Generates tool definitions, resource handlers, and test suites in TypeScript or Python (FastMCP)."
 metadata:
   author: runedev
   version: "0.5.0"

package/skills/onboard/SKILL.md

@@ -1,6 +1,6 @@
 ---
 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.
+description: "Auto-generate project context for AI sessions. Use when starting on a new repo for the first time, or when CLAUDE.md / .rune/ context is missing or stale. Scans codebase and creates the setup so every future session starts with full context."
 metadata:
   author: runedev
   version: "0.4.0"

package/skills/perf/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: perf
-description: Performance regression gate. Detects N+1 queries, sync-in-async, missing indexes, memory leaks, and bundle bloat before they reach production.
+description: "Performance regression gate. Detects N+1 queries, sync-in-async, missing indexes, memory leaks, and bundle bloat before they reach production."
 metadata:
   author: runedev
   version: "0.3.0"

package/skills/plan/SKILL.md

@@ -1,9 +1,9 @@
 ---
 name: plan
-description: Create structured implementation plans from requirements. Produces master plan + phase files for enterprise-scale project management. Master plan = overview (<80 lines). Phase files = execution detail (<150 lines each). Each session handles 1 phase. Uses opus for deep reasoning.
+description: "Create structured implementation plans from requirements. Produces master plan + phase files for enterprise-scale project management. Master plan = overview (<80 lines). Phase files = execution detail (<150 lines each). Each session handles 1 phase. Uses opus for deep reasoning."
 metadata:
   author: runedev
-  version: "1.5.0"
+  version: "1.6.0"
   layer: L2
   model: opus
   group: creation
@@ -149,9 +149,12 @@ If ANY "Master + Phase Files" criterion is true → produce master plan + phase
 
 ### Step 3 — Decompose into Phases
 <MUST-READ path="references/wave-planning.md" trigger="when writing wave-structured task lists inside any phase"/>
+<MUST-READ path="references/vertical-slice.md" trigger="when decomposing a feature into tasks/issues — ALWAYS prefer vertical (end-to-end) slices over horizontal (single-layer) ones"/>
 
 Group work into phases. Each phase: completable in one session, clear "done when", produces testable output, independent enough to run without other phases loaded.
 
+**Vertical slices over horizontal layers**: each task within a phase MUST be a tracer-bullet slice (schema + API + UI + test, end-to-end), NOT a single-layer chunk. Horizontal slicing ("all models → all APIs → all UI") looks organized but blocks on the slowest layer. See `references/vertical-slice.md` for slice rules, AFK vs HITL classification, and the per-task slice template.
+
 <HARD-GATE>
 Each phase MUST be completable by ANY coder model (including Haiku) with ONLY the phase file loaded.
 If the coder would need to read the master plan or other phase files to execute → the phase file is missing detail.
@@ -163,7 +166,7 @@ Phase decomposition rules:
 - **Dependencies before consumers**: create what's imported before the importer
 - **Test alongside**: each phase includes its own test tasks
 - **Max 5-7 tasks per phase**: if more, split the phase
-- **Vertical slices over horizontal layers**: prefer "auth end-to-end" over "all models → all APIs → all UI"
+- **Vertical slices over horizontal layers**: prefer "auth end-to-end" over "all models → all APIs → all UI" (see `references/vertical-slice.md` for tracer-bullet template, AFK/HITL labels, granularity rules)
 
 Tasks within each phase MUST be organized into waves (parallel-safe groupings). See `references/wave-planning.md`.
 
@@ -346,7 +349,7 @@ Append to plan output when invoked standalone. Suppress when called as sub-skill
 ```yaml
 chain_metadata:
   skill: "rune:plan"
-  version: "1.5.0"
+  version: "1.6.0"
   status: "[DONE | DONE_WITH_CONCERNS | NEEDS_CONTEXT | BLOCKED]"
   domain: "[area planned]"
   files_changed:
@@ -385,7 +388,9 @@ chain_metadata:
 | Phase with zero test tasks | CRITICAL | HARD-GATE rejects it |
 | 10+ phases overwhelming the master plan | MEDIUM | Max 8 phases — split into sub-projects if more |
 | Task without File path or Verify command | HIGH | Every task MUST have File + Test + Verify + Commit fields — no vague "implement the feature" tasks |
-| Horizontal layer planning (all models → all APIs → all UI) | HIGH | Vertical slices parallelize better. Use wave-based grouping: independent tasks in same wave, dependent tasks in later waves |
+| Horizontal layer planning (all models → all APIs → all UI) | HIGH | Vertical slices parallelize better. Use wave-based grouping AND vertical-slice template (`references/vertical-slice.md`): each task = end-to-end path through schema/API/UI/test, demoable on its own |
+| Slice not demoable on its own ("just the migration", "just the UI shell") | HIGH | Per `references/vertical-slice.md` — every slice produces a verifiable outcome. Layer-only fragments block downstream slices and hide partial completion |
+| HITL slices marked liberally to enable "review" friction | MEDIUM | HITL is for hard blockers (OAuth setup, design decision, paid third-party access), not soft preferences. Default to AFK; use post-merge review for soft signals |
 | Tasks without `depends_on` in Wave 2+ | MEDIUM | Implicit dependencies break parallel dispatch. Every Wave 2+ task MUST declare `depends_on` |
 | Plan ignores locked Decisions from BA | CRITICAL | Decision Compliance section cross-checks requirements.md — locked decisions are non-negotiable |
 | Complex feature missing Workflow Registry — components planned but never wired | HIGH | Step 4.5: 4-view registry catches orphaned components, unphased workflows, and missing state transitions before phase files are written |