@rune-kit/rune 2.2.4 → 2.3.0

package/skills/deploy/SKILL.md

@@ -4,7 +4,7 @@ description: "Deploy application to target platform. Use when user explicitly sa
 disable-model-invocation: true
 metadata:
   author: runedev
-  version: "0.3.0"
+  version: "0.4.0"
   layer: L2
   model: sonnet
   group: delivery
@@ -64,6 +64,49 @@ If sentinel returns CRITICAL issues → STOP. Do NOT proceed. Report issues.
 
 Both gates MUST pass. No exceptions.
 
+### Step 1.5 — Release Checklist (Production Deploys Only)
+
+**Skip for**: staging, preview, development deploys.
+
+Before production deploy, verify ALL items:
+
+| # | Check | How | Gate |
+|---|-------|-----|------|
+| 1 | Version bumped | `package.json`/`pyproject.toml` version matches release | BLOCK if unchanged |
+| 2 | Changelog updated | `CHANGELOG.md` has entry for this version | WARN if missing |
+| 3 | Breaking changes documented | RFC artifact exists for each breaking change | BLOCK if RFC missing |
+| 4 | Migration scripts ready | DB migrations tested on staging first | BLOCK if untested migration |
+| 5 | Rollback plan documented | `.rune/deploy/rollback-<version>.md` exists | WARN if missing |
+| 6 | Release notes drafted | Customer-facing notes for release-comms | WARN if missing |
+| 7 | Dependencies locked | Lock file committed, no floating versions | BLOCK if unlocked |
+
+**Rollback Plan Template** (`.rune/deploy/rollback-<version>.md`):
+
+```markdown
+# Rollback Plan: v<version>
+
+## Trigger Conditions
+- [When to rollback — e.g., error rate >5%, P0 incident, data corruption]
+
+## Steps
+1. [Revert command — e.g., `vercel rollback`, `fly releases rollback`]
+2. [DB rollback — e.g., `npm run migrate:rollback` or "N/A — no migration"]
+3. [Cache invalidation if needed]
+4. [Notify stakeholders]
+
+## Verification
+- [ ] Previous version serving traffic
+- [ ] Health check passing
+- [ ] No data loss confirmed
+
+## Post-Rollback
+- [ ] Incident created for root cause analysis
+- [ ] Fix branch created from rolled-back commit
+```
+
+If any BLOCK item fails → STOP deploy. Fix before retrying.
+If WARN items missing → proceed but flag in deploy report.
+
 ### Step 2 — Detect platform
 
 Use `Bash` to inspect the project root for platform config files:
@@ -147,6 +190,18 @@ Deploy Report with platform, status (success/failed/rollback), deployed URL, bui
 3. MUST verify deploy is live and responding before declaring success
 4. MUST NOT deploy with known CRITICAL security findings
 5. MUST log deploy metadata (version, timestamp, commit hash)
+6. MUST complete release checklist for production deploys — version bump, changelog, rollback plan
+7. MUST create rollback plan artifact before first production deploy of a version
+
+## Returns
+
+| Artifact | Format | Location |
+|----------|--------|----------|
+| Deploy report | Markdown | inline (chat output) |
+| Deploy status (success/failed/rollback) | Text | inline |
+| Health check results (HTTP status, visual) | Markdown | inline |
+| Rollback plan document | Markdown | `.rune/deploy/rollback-<version>.md` |
+| Monitoring confirmation | Text | inline |
 
 ## Sharp Edges
 

package/skills/design/SKILL.md

@@ -443,6 +443,15 @@ Trading/Fintech — Data-Dense Dark — Web
 | Persistence Gate | .rune/design-system.md written before reporting done | Write file first |
 | Platform Gate | Platform detected before generating tokens | Default to web, note assumption |
 
+## Returns
+
+| Artifact | Format | Location |
+|----------|--------|----------|
+| Design system file | Markdown | `.rune/design-system.md` |
+| Design report | Markdown | inline (chat output) |
+| Accessibility audit findings | Markdown list | inline + appended to design-system.md |
+| UX writing guidelines | Markdown section | `.rune/design-system.md` § UX Writing |
+
 ## Sharp Edges
 
 Known failure modes for this skill. Check these before declaring done.

package/skills/docs/SKILL.md

@@ -294,6 +294,18 @@ Docs Update Report:
 5. MUST NOT generate docs for code that doesn't exist yet (unless explicitly creating spec docs)
 6. API docs MUST match actual route signatures — wrong API docs are worse than no docs
 
+## Returns
+
+| Artifact | Format | Location |
+|----------|--------|----------|
+| README.md | Markdown | project root |
+| ARCHITECTURE.md | Markdown | project root (if 10+ files) |
+| API reference | Markdown | `docs/API.md` |
+| Changelog entry | Markdown (Keep a Changelog) | `CHANGELOG.md` |
+| Docs update report | Markdown | inline (chat output) |
+
+**Scope guardrail:** Documents only what exists in the codebase — never invents features, endpoints, or APIs.
+
 ## Sharp Edges
 
 | Failure Mode | Severity | Mitigation |

package/skills/docs-seeker/SKILL.md

@@ -161,6 +161,17 @@ Known failure modes for this skill. Check these before declaring done.
 - Source URL provided
 - Documentation emitted in output format
 
+## Returns
+
+| Artifact | Format | Location |
+|----------|--------|----------|
+| API reference (signature + params) | Markdown | inline |
+| Minimal working code example | Code block | inline |
+| Deprecation / version notes | Markdown | inline |
+| Source URL | Plain text | inline |
+
 ## Cost Profile
 
 ~300-600 tokens input, ~200-400 tokens output. Haiku. Fast lookup.
+
+**Scope guardrail:** docs-seeker looks up documentation only — it does not apply changes, write code, or interpret whether the API fits the caller's use case.

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.4.0"
+  version: "0.6.0"
   layer: L2
   model: sonnet
   group: development
@@ -97,6 +97,32 @@ Confirm the change works and nothing is broken.
 - If project has a type-check command, run it via `Bash`
 - If project has a lint command, run it via `Bash`
 
+### Step 4.5: Quality Decay Check (Self-Regulation)
+
+When fix is called repeatedly (e.g., by cook Phase 4, or iterative fix loops), track a **WTF-likelihood score** — the probability that continued fixing is making things worse.
+
+**Compute every 3 fix attempts** (or when called 5+ times in a single cook session):
+
+| Signal | Score Adjustment |
+|--------|-----------------|
+| A fix was reverted (any test that passed now fails) | +15% |
+| Fix touched >3 files (blast radius expanding) | +5% per extra file beyond 3 |
+| 15+ fixes already applied in this session | +1% per fix beyond 15 |
+| All remaining issues are LOW severity | +10% |
+| Fix touched files outside the original diagnosis scope | +20% |
+| Consecutive fixes without running tests between them | +10% |
+
+**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.
+
+**Reset conditions:** WTF-likelihood resets to 0% when:
+- User explicitly says "continue fixing"
+- A full test suite run shows zero regressions
+- Scope is narrowed to a single file
+
+> Source: garrytan/gstack v0.9.0 (qa skill) — prevents runaway fix loops where each fix introduces new risk.
+
 ### Step 5: Post-Fix Hardening (Defense-in-Depth)
 
 After the fix works, make the bug **structurally impossible** — not just "fixed this time."
@@ -178,7 +204,7 @@ If fix requires touching >3 files not in the diagnosis → re-diagnose. You're p
 ```
 ## Fix Report
 - **Task**: [what was fixed/implemented]
-- **Status**: complete | partial | blocked
+- **Status**: DONE | DONE_WITH_CONCERNS | NEEDS_CONTEXT | BLOCKED
 
 ### Changes
 - `path/to/file.ts` — [description of change]
@@ -189,10 +215,38 @@ If fix requires touching >3 files not in the diagnosis → re-diagnose. You're p
 - Types: PASS | FAIL
 - Tests: PASS | FAIL ([n] passed, [m] failed)
 
+### Concerns (if DONE_WITH_CONCERNS)
+- [concern]: [impact assessment] — [suggested remediation]
+
+### Context Needed (if NEEDS_CONTEXT)
+- [what is unknown]: [why it blocks] — [two most likely answers]
+
+### Blocker (if BLOCKED)
+- [specific blocker]: [what was attempted]
+
 ### Notes
 - [any caveats or follow-up needed]
 ```
 
+### Status Protocol (Subagent Contract)
+
+Fix returns one of four statuses to its caller (cook, debug, review, surgeon). The caller uses this to route next actions.
+
+| Status | When | Example |
+|--------|------|---------|
+| `DONE` | Fix applied, tests pass, no issues | Clean bug fix, all green |
+| `DONE_WITH_CONCERNS` | Fix works but has side effects or caveats worth noting | "Tests pass but performance regressed 15% — consider optimizing in follow-up" |
+| `NEEDS_CONTEXT` | Cannot apply fix without clarification — ambiguous spec or missing info | "Two valid interpretations of the expected behavior — need user input" |
+| `BLOCKED` | Hard blocker — exhausted fix attempts, broken dependency, fundamental incompatibility | "3 fix attempts failed — triggering debug escalation" |
+
+## Returns
+
+| Artifact | Format | Location |
+|----------|--------|----------|
+| Code changes | Source files | Per debug report / plan file paths |
+| Fix Report | Markdown (inline) | Emitted to calling skill (cook, debug, review, surgeon) |
+| Verification output | Inline (Fix Report) | Lint + types + test results |
+
 ## Sharp Edges
 
 Known failure modes for this skill. Check these before declaring done.
@@ -207,6 +261,7 @@ Known failure modes for this skill. Check these before declaring done.
 | Fixing at crash site without tracing data origin | HIGH | Defense-in-depth: trace where bad data ORIGINATES, add validation at every layer it passes through |
 | 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 |
 
 ## Done When
 
@@ -215,8 +270,13 @@ Known failure modes for this skill. Check these before declaring done.
 - Tests pass for the fixed functionality (actual output shown)
 - Lint and type check pass
 - hallucination-guard verified any new imports
-- Fix Report emitted with changed files and verification results
+- Fix Report emitted with 4-state status, changed files, and verification results
+- If `DONE_WITH_CONCERNS`: concerns listed with impact + remediation
+- If `NEEDS_CONTEXT`: specific questions stated with two likely answers
+- If `BLOCKED`: blocker + all attempted approaches documented
 
 ## Cost Profile
 
 ~2000-5000 tokens input, ~1000-3000 tokens output. Sonnet for code writing quality. Most active skill during implementation.
+
+**Scope guardrail**: Do not refactor unrelated code or create new features beyond the diagnosed fix target unless explicitly delegated by the parent agent.

package/skills/git/SKILL.md

@@ -3,7 +3,7 @@ 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.
 metadata:
   author: runedev
-  version: "0.2.0"
+  version: "0.3.0"
   layer: L3
   model: haiku
   group: utility
@@ -27,6 +27,7 @@ Specialized git operations utility. Handles semantic commits, PR descriptions, b
 - `/rune git pr` — manual PR generation
 - `/rune git branch <description>` — generate branch name
 - `/rune git changelog` — generate changelog from commits
+- `/rune git release <version>` — create tagged release with changelog
 
 ## Calls (outbound)
 
@@ -187,6 +188,49 @@ Group commits by conventional commit type. Format as [Keep a Changelog](https://
 
 Link to PRs/issues when references found in commit messages.
 
+### Release Mode
+
+Create a version tag with release artifacts.
+
+**Triggers:**
+- `/rune git release <version>` — create release for specified version
+- Called by `launch` (L1) during release pipeline
+- Called by `deploy` (L2) after successful production deploy
+
+#### Step 1 — Validate Version
+
+Parse version string. Must follow semver (`major.minor.patch`):
+- Breaking changes → major bump
+- New features → minor bump
+- Bug fixes → patch bump
+
+Check `git tag -l` to ensure version doesn't already exist.
+
+#### Step 2 — Generate Release Artifacts
+
+1. **Changelog**: Run Changelog Mode to generate entries since last tag
+2. **Version bump**: Update version in `package.json`, `pyproject.toml`, `Cargo.toml`, or equivalent
+3. **Release notes**: Summarize changes for GitHub Release body
+
+#### Step 3 — Tag and Push
+
+```bash
+git add <version-files>
+git commit -m "chore: bump version to v<version>"
+git tag -a v<version> -m "Release v<version>"
+git push origin master --tags
+```
+
+#### Step 4 — Create GitHub Release
+
+```bash
+gh release create v<version> --title "v<version>" --notes "<release-notes>"
+```
+
+#### Step 5 — Notify
+
+If deploy reports customer email list available (via rune-pay `/admin/emails`), flag for notification.
+
 ## Output Format
 
 ### Commit Mode
@@ -235,6 +279,16 @@ Examples: `feat/jwt-refresh`, `fix/123-login-crash`, `refactor/auth-module`
 - Change description (#PR)
 ```
 
+### Release Mode
+```
+## Release: v<version>
+- **Tag**: v<version>
+- **Commits**: [count] since last release
+- **Changelog**: [path to CHANGELOG.md]
+- **GitHub Release**: [URL]
+- **Artifacts**: version bump, changelog, tag, release
+```
+
 ## Constraints
 
 1. MUST use conventional commit format — no freeform messages

package/skills/incident/SKILL.md

@@ -214,6 +214,16 @@ File: src/middleware/auth.ts:47
 | Security Gate | sentinel ran before closing incident | Run sentinel — do not skip |
 | Postmortem Gate | All sections populated (Timeline, RCA, Prevention Actions) before status = Resolved | Complete or note as DRAFT |
 
+## Returns
+
+| Artifact | Format | Location |
+|----------|--------|----------|
+| Incident response report | Markdown | inline (chat output) |
+| Incident timeline | Text (HH:MM format) | inline + postmortem |
+| Postmortem document | Markdown | `.rune/incidents/INCIDENT-<date>-<slug>.md` |
+| Prevention actions table | Markdown table | postmortem |
+| Journal entry (incident ADR) | Text | `.rune/adr/` (via `rune:journal`) |
+
 ## Sharp Edges
 
 Known failure modes for this skill. Check these before declaring done.

package/skills/journal/SKILL.md

@@ -3,7 +3,7 @@ name: journal
 description: Persistent state tracking and Architecture Decision Records across sessions. Manages progress state, module health, dependency graphs, and ADRs for any workflow.
 metadata:
   author: runedev
-  version: "0.2.0"
+  version: "0.3.0"
   layer: L3
   model: haiku
   group: state
@@ -43,6 +43,7 @@ None — pure L3 state management utility.
 .rune/module-status.json   — Machine-readable module states
 .rune/dependency-graph.mmd — Mermaid diagram, color-coded by health
 .rune/adr/                 — Architecture Decision Records (one per decision)
+.rune/risks/               — Risk Register entries (one per identified risk)
 ```
 
 ## Execution
@@ -111,6 +112,50 @@ For each architectural decision or trade-off made during this session (applies t
 - **[Alternative B]**: Rejected because [specific reason]. May reconsider if [condition changes].
 ```
 
+### Step 3.5 — Record risks
+
+For each risk identified during the session (technical, schedule, dependency, security):
+
+1. Generate a risk filename: `.rune/risks/RISK-[NNN]-[slug].md` where NNN is next sequential number
+2. Use `Write` to create the risk file:
+
+```markdown
+# RISK-[NNN]: [Risk Title]
+
+**Date Identified**: [YYYY-MM-DD]
+**Identified By**: [workflow — cook | plan | deploy | audit | adversary]
+**Severity**: Critical | High | Medium | Low
+**Likelihood**: High | Medium | Low
+**Status**: Open | Mitigated | Accepted | Closed
+
+## Description
+[What could go wrong — specific scenario, not vague "things might break"]
+
+## Impact
+[What happens if this risk materializes — quantify if possible]
+
+## Mitigation
+[Actions to reduce likelihood or impact]
+- [ ] [Action 1 — owner, deadline]
+- [ ] [Action 2]
+
+## Trigger Conditions
+[How to detect this risk is materializing — monitoring, alerts, symptoms]
+
+## Contingency
+[What to do if risk materializes despite mitigation — the Plan B]
+```
+
+3. **Risk classification matrix**:
+
+| Likelihood \ Severity | Critical | High | Medium | Low |
+|----------------------|----------|------|--------|-----|
+| **High** | 🔴 Immediate action | 🔴 This sprint | 🟡 This quarter | ⚪ Backlog |
+| **Medium** | 🔴 This sprint | 🟡 This quarter | ⚪ Backlog | ⚪ Accept |
+| **Low** | 🟡 This quarter | ⚪ Backlog | ⚪ Accept | ⚪ Accept |
+
+4. Risks marked 🔴 MUST have mitigation actions with deadlines. ⚪ Accept = documented acknowledgment, no action required.
+
 ### Step 4 — Update dependency graph
 
 If any module dependencies changed during this session (new imports, removed dependencies, refactored interfaces):
@@ -145,6 +190,7 @@ Emit the journal update summary to the calling skill.
 - **Module**: [current module]
 - **Health**: [before] → [after]
 - **ADRs Written**: [count]
+- **Risks Logged**: [count] ([severity breakdown])
 - **Files Updated**: [list of .rune/ files modified]
 - **Next Module**: [next in queue, or "rescue complete"]
 ```
@@ -154,8 +200,9 @@ Emit the journal update summary to the calling skill.
 ```
 1. Read .rune/RESCUE-STATE.md   → full rescue history
 2. Read .rune/module-status.json → module states and health scores
-3. Read git log                  → latest changes since last session
-4. Read CLAUDE.md               → project conventions
+3. Read .rune/risks/             → open risks and their status
+4. Read git log                  → latest changes since last session
+5. Read CLAUDE.md               → project conventions
 → Result: Zero context loss across rescue sessions
 ```
 
@@ -180,6 +227,7 @@ Known failure modes for this skill. Check these before declaring done.
 ## Done When
 
 - All decisions from the session recorded as ADR files with rationale
+- All identified risks recorded as RISK files with severity, mitigation, and trigger conditions
 - Progress state updated (module status, phase, or deploy event as appropriate)
 - Dependency graph updated if module relationships changed
 - Journal Update summary emitted to calling skill

package/skills/launch/SKILL.md

@@ -303,6 +303,16 @@ Mark todo[4] `completed`.
 - Launch video: [ready | skipped]
 ```
 
+## Returns
+
+| Artifact | Format | Location |
+|----------|--------|----------|
+| Deploy status + live URL | Inline (Launch Report) | Emitted at session end |
+| Marketing assets (copy, social, SEO) | Markdown (inline) | Generated by `rune:marketing`, presented in Phase 5 |
+| Release checklist | Markdown (inline) | Shown in Announce phase |
+| Monitoring confirmation | Inline | Watchdog setup output |
+| Launch Report | Markdown (inline) | Emitted at end of session |
+
 ## Sharp Edges
 
 Known failure modes for this skill. Check these before declaring done.
@@ -328,3 +338,5 @@ Known failure modes for this skill. Check these before declaring done.
 ## Cost Profile
 
 ~$0.08-0.15 per launch. Sonnet for coordination, delegates to haiku for scanning.
+
+**Scope guardrail**: Do not publish marketing assets or trigger external announcements unless explicitly delegated by the parent agent.

package/skills/logic-guardian/SKILL.md

@@ -235,6 +235,17 @@ Ensure the next session can pick up where this one left off:
 - Manifest summary saved to journal + neural memory for cross-session handoff
 - Tests pass after any logic edit
 
+## Returns
+
+| Artifact | Format | Location |
+|----------|--------|----------|
+| Logic manifest | JSON | `.rune/logic-manifest.json` |
+| Validation report (SYNCED / DRIFT) | Markdown | inline |
+| Pre-edit gate summary | Structured text | inline |
+| ADR entries for logic changes | Markdown | via `journal` L3 |
+
 ## Cost Profile
 
 ~1,000-2,000 tokens for manifest load + pre-edit gate. ~3,000-5,000 tokens for full project scan (Phase 3). Sonnet for code analysis; haiku for file scanning via scout.
+
+**Scope guardrail:** logic-guardian protects existing logic — it does not implement new features or refactor code.

package/skills/marketing/SKILL.md

@@ -224,6 +224,19 @@ Known failure modes for this skill. Check these before declaring done.
 - Files saved to marketing/ directory
 - Marketing Assets report emitted with file list
 
+## Returns
+
+| Artifact | Format | Location |
+|----------|--------|----------|
+| Brand voice contract | Markdown | `marketing/brand-voice.md` |
+| Landing page copy | Markdown | `marketing/landing-copy.md` |
+| Social media posts | Markdown | `marketing/social-posts.md` |
+| SEO metadata | JSON | `marketing/seo-meta.json` |
+| SEO audit report | Markdown | `marketing/seo-audit.md` |
+| Video demo script | Markdown | `marketing/video-script.md` |
+
 ## Cost Profile
 
 ~2000-5000 tokens input, ~1000-3000 tokens output. Sonnet for copywriting quality.
+
+**Scope guardrail:** marketing generates assets based on actual product capabilities only — no aspirational copy, no fabricated stats.

package/skills/mcp-builder/SKILL.md

@@ -353,6 +353,19 @@ mcp-server-<name>/
 - Verification passed (types + tests)
 - Ready to install in Claude Code / Cursor / other IDEs
 
+## Returns
+
+| Artifact | Format | Location |
+|----------|--------|----------|
+| MCP server source code | TypeScript or Python | `mcp-server-<name>/src/` |
+| Tool definitions (one per tool) | TS/Python files | `src/tools/<name>.ts` or `.py` |
+| Resource handlers | TS/Python files | `src/resources/<name>.ts` or `.py` |
+| Test suite | TS/Python test files | `tests/` |
+| README with tool catalog | Markdown | `mcp-server-<name>/README.md` |
+| Environment config template | `.env.example` | project root |
+
 ## Cost Profile
 
 ~3000-6000 tokens input, ~2000-5000 tokens output. Sonnet — MCP server generation is a structured code task, not architectural reasoning.
+
+**Scope guardrail:** mcp-builder generates the server and tests — it does not deploy, register with MCP registries, or configure the host IDE beyond providing the installation snippet.

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.2.0"
+  version: "0.3.0"
   layer: L2
   model: sonnet
   group: quality
@@ -43,6 +43,7 @@ project/
     ├── decisions.md       # Empty, ready for session-bridge
     ├── progress.md        # Empty, ready for session-bridge
     ├── session-log.md     # Empty, ready for session-bridge
+    ├── instincts.md       # Empty, ready for session-bridge instinct learning
     └── DEVELOPER-GUIDE.md # Human-readable onboarding for new developers
 ```
 
@@ -103,6 +104,21 @@ Use `Write` to create each file:
 - `.rune/decisions.md` — create with header `# Architecture Decisions` and one placeholder row in a markdown table (Date | Decision | Rationale | Status)
 - `.rune/progress.md` — create with header `# Progress Log` and one placeholder entry
 - `.rune/session-log.md` — create with header `# Session Log` and current date as first entry
+- `.rune/instincts.md` — create with header `# Project Instincts` and a description: "Learned trigger→action patterns. Managed by session-bridge. See session-bridge SKILL.md Step 5.7 for format."
+
+### Step 5.5 — Load Existing Instincts
+
+If `.rune/instincts.md` already exists and contains instinct entries, read it and include a summary in the Onboard Report under `### Learned Instincts`. This tells the agent what project-specific behaviors have been learned from previous sessions.
+
+For each instinct with confidence ≥0.6, include in the report:
+- Trigger and action (one line)
+- Confidence level
+
+Instincts with confidence <0.6 are still learning — mention count but don't list individually.
+
+**Why**: Onboard is the first skill that runs in a new session. Surfacing instincts here ensures the agent starts with project-specific learned behaviors, not just static conventions.
+
+> Source: affaan-m/everything-claude-code (91.9k★) — instinct-based learning with project isolation.
 
 ### Step 6b — Generate DEVELOPER-GUIDE.md
 
@@ -188,6 +204,26 @@ Based on your detected stack ([detected frameworks]), these extension packs may
   Install: [link or command when available]
 ```
 
+### Step 6d — Context Budget Check
+
+Audit the project's baseline context cost from MCP servers and agent configurations. This helps developers understand why their context window fills up faster than expected.
+
+1. Count MCP tools available (from session start messages or `settings.json`)
+2. Check CLAUDE.md line count
+3. If total MCP tools >80 or CLAUDE.md >150 lines, include a **Context Budget Advisory** in the Onboard Report:
+
+```
+### Context Budget Advisory
+- **MCP tools loaded**: [count] across [N] servers
+- **CLAUDE.md size**: [N] lines
+- **Estimated baseline**: ~[N]k tokens before any work begins
+- **Recommendation**: [specific advice — disable unused MCP servers, move CLAUDE.md details to .rune/]
+```
+
+**Skip if**: Total MCP tools ≤80 AND CLAUDE.md ≤150 lines (healthy baseline).
+
+> Source: affaan-m/everything-claude-code (91.9k★) — MCP token cost awareness.
+
 ### Step 7 — Commit
 Use `Bash` to stage and commit the generated files:
 ```bash
@@ -256,6 +292,10 @@ If any of the `.rune/` files already exist, do not overwrite them (they may cont
 ### Skipped (already exist)
 - [list of files not overwritten]
 
+### Learned Instincts (if any)
+- [trigger] → [action] (confidence: [0.6-0.9]) — for each high-confidence instinct
+- [N] low-confidence instincts still learning
+
 ### Observations
 - [notable patterns or anomalies found]
 - [potential issues detected]
@@ -288,11 +328,23 @@ Known failure modes for this skill. Check these before declaring done.
 ## Done When
 
 - CLAUDE.md written (or merged) with all detected tech stack fields populated
-- .rune/ directory initialized with conventions, decisions, progress, session-log
+- .rune/ directory initialized with conventions, decisions, progress, session-log, instincts
 - .rune/DEVELOPER-GUIDE.md written with setup commands from actual scan
 - All generated commands verified to exist in package.json/Makefile/etc.
 - Onboard Report emitted with Generated + Skipped + Observations sections
 
+## Returns
+
+| Artifact | Format | Location |
+|----------|--------|----------|
+| Project AI config | Markdown | `CLAUDE.md` (project root) |
+| Detected conventions | Markdown | `.rune/conventions.md` |
+| Decision log (initialized) | Markdown | `.rune/decisions.md` |
+| Developer onboarding guide | Markdown | `.rune/DEVELOPER-GUIDE.md` |
+| Session/progress files | Markdown | `.rune/progress.md`, `.rune/session-log.md` |
+
 ## Cost Profile
 
 ~2000-5000 tokens input, ~1000-2000 tokens output. Sonnet for analysis quality.
+
+**Scope guardrail:** onboard generates project context files — it does not modify source code, install dependencies, or change project configuration.

package/skills/perf/SKILL.md

@@ -292,6 +292,17 @@ Known failure modes for this skill. Check these before declaring done.
 - Benchmark scripts ran (if configured) or INFO: skipped
 - Perf Report emitted with PASS/WARN/BLOCK verdict
 
+## Returns
+
+| Artifact | Format | Location |
+|----------|--------|----------|
+| Perf Report with verdict | Markdown (PASS/WARN/BLOCK) | inline |
+| Per-finding details | Structured list (file:line + impact) | inline |
+| Lighthouse scores (if ran) | Score table | inline |
+| Framework-specific findings | Categorized list | inline |
+
 ## Cost Profile
 
 ~3000-8000 tokens input, ~500-1500 tokens output. Sonnet for pattern recognition.
+
+**Scope guardrail:** perf investigates and reports only — it does not fix code. All fixes are delegated to `fix` (L2) after the report is reviewed.