@rune-kit/rune 2.1.1

package/skills/docs-seeker/SKILL.md

@@ -0,0 +1,166 @@
+---
+name: docs-seeker
+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"
+  layer: L3
+  model: haiku
+  group: knowledge
+  tools: "Read, Glob, Grep, WebFetch, WebSearch"
+---
+
+# docs-seeker
+
+## Purpose
+
+Documentation lookup utility. Receives a library name, API reference, or error message, resolves the correct documentation, and returns API signatures, usage examples, and known issues. Stateless — no memory between calls.
+
+## Calls (outbound)
+
+None — pure L3 utility using `WebSearch`, `WebFetch`, and Context7 MCP tools directly.
+
+## Called By (inbound)
+
+- `debug` (L2): lookup API docs for unclear errors
+- `fix` (L2): check correct API usage before applying changes
+- `review` (L2): verify API usage is current and correct
+
+## Execution
+
+### Input
+
+```
+target: string         — library name, API endpoint, or error message
+version: string        — (optional) specific version to look up
+query: string          — specific question about the target (e.g., "how to configure retry")
+```
+
+### Step 1 — Identify Target
+
+Parse the input to extract:
+- Library or framework name (e.g., "react-query", "fastapi", "prisma")
+- Version if specified
+- The specific API, method, or error to look up
+
+### Step 2 — Try Context7 MCP (fastest)
+
+Attempt Context7 MCP lookup first (faster, higher quality):
+
+1. Call `mcp__plugin_context7_context7__resolve-library-id` with the library name and query
+2. Select the best matching library ID from results (prioritize: name match, source reputation, snippet count)
+3. Call `mcp__plugin_context7_context7__query-docs` with the resolved library ID and the specific query
+4. If Context7 returns a satisfactory answer with code examples, proceed to Step 5
+
+### Step 3 — Try llms.txt Discovery
+
+If Context7 MCP is unavailable or insufficient, try llms.txt (AI-optimized documentation):
+
+**For GitHub repos** — pattern: `https://context7.com/{org}/{repo}/llms.txt`
+```
+github.com/vercel/next.js    → context7.com/vercel/next.js/llms.txt
+github.com/shadcn-ui/ui      → context7.com/shadcn-ui/ui/llms.txt
+```
+
+**For doc sites** — pattern: `https://context7.com/websites/{normalized-domain}/llms.txt`
+```
+docs.imgix.com               → context7.com/websites/imgix/llms.txt
+ffmpeg.org/doxygen/8.0        → context7.com/websites/ffmpeg_doxygen_8_0/llms.txt
+```
+
+**Topic-specific** — append `?topic={query}` for focused results:
+```
+context7.com/shadcn-ui/ui/llms.txt?topic=date-picker
+context7.com/vercel/next.js/llms.txt?topic=cache
+```
+
+**Traditional llms.txt fallback**: `WebSearch "[library] llms.txt"` → common paths: `docs.[lib].com/llms.txt`, `[lib].dev/llms.txt`
+
+Use `WebFetch` on the resolved llms.txt URL. If it contains multiple section URLs (3+), launch parallel Explorer agents (one per section, max 5).
+
+### Step 4 — Fallback to Web Search
+
+If neither Context7 nor llms.txt available:
+
+1. Use `WebSearch` with queries:
+   - "[library] [api/method] official documentation"
+   - "[library] [version] [query]"
+   - "[error message] [library] fix"
+2. Identify official documentation URLs (docs.*, official GitHub, npm/pypi pages)
+3. Call `WebFetch` on the top 1-3 official sources
+
+**Repository analysis fallback** (when docs are sparse but code is available):
+```bash
+npx repomix --output /tmp/repomix-output.xml   # in the cloned repo
+```
+Read the repomix output to extract API patterns, usage examples, and internal documentation.
+
+### Step 5 — Extract Answer
+
+From Context7, llms.txt, or fetched pages, extract:
+- Exact API signature with parameter types and return type
+- Minimal working code example
+- Version-specific notes (deprecated in X, changed in Y)
+- Known issues or common pitfalls mentioned in docs
+
+### Step 6 — Report
+
+Return structured documentation in the output format below.
+
+## Constraints
+
+- Prefer Context7 MCP → llms.txt → WebSearch (in that priority order)
+- Only fall back to web if Context7 and llms.txt both lack coverage
+- Use `?topic=` parameter on llms.txt URLs for targeted results
+- Always include source URL so callers can verify
+- If the API is deprecated, say so explicitly and link to the replacement
+- For parallel fetching: 1-3 URLs = single agent, 4-10 = 3-5 Explorer agents, 11+ = 5-7 agents
+
+## Output Format
+
+```
+## Documentation: [Library/API]
+- **Version**: [detected or "latest"]
+- **Source**: [official docs URL or "Context7"]
+
+### API Reference
+- **Signature**: `functionName(param1: Type, param2: Type): ReturnType`
+- **Parameters**:
+  - `param1` — description
+  - `param2` — description
+- **Returns**: description
+
+### Usage Example
+```[lang]
+[minimal working code snippet from official docs]
+```
+
+### Known Issues / Deprecations
+- [relevant warning, deprecation notice, or common mistake]
+```
+
+## Sharp Edges
+
+Known failure modes for this skill. Check these before declaring done.
+
+| Failure Mode | Severity | Mitigation |
+|---|---|---|
+| Returning deprecated API without flagging it | HIGH | Must explicitly state "deprecated in X.Y, use Z instead" with replacement link |
+| Wrong version docs returned when version specified | HIGH | Verify version match — if version-specific docs unavailable, state that explicitly |
+| Skipping Context7 and going directly to web search | MEDIUM | Constraint: Context7 MCP → llms.txt → WebSearch — follow the priority chain |
+| Not using ?topic= on llms.txt for focused queries | LOW | Topic parameter dramatically reduces noise — always append when query is specific |
+| Returning docs without source URL | MEDIUM | Constraint: always include source URL so callers can verify |
+
+## Done When
+
+- Context7 attempted first (resolve-library-id + query-docs)
+- If Context7 insufficient: top 1-3 official doc URLs fetched via WebFetch
+- API signature extracted with parameter types and return type
+- Minimal working code example included
+- Deprecation/version notes included if applicable
+- Source URL provided
+- Documentation emitted in output format
+
+## Cost Profile
+
+~300-600 tokens input, ~200-400 tokens output. Haiku. Fast lookup.

package/skills/fix/SKILL.md

@@ -0,0 +1,192 @@
+---
+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.3.0"
+  layer: L2
+  model: sonnet
+  group: development
+  tools: "Read, Write, Edit, Bash, Glob, Grep"
+---
+
+# fix
+
+## Purpose
+
+Apply code changes. Fix receives a plan, debug finding, or review finding and writes the actual code. It does NOT investigate root causes — that is rune:debug's job. Fix is the action hub: locate, change, verify, report.
+
+<HARD-GATE>
+Never change test files to make tests pass unless the tests themselves are provably wrong (wrong expected value, wrong test setup, testing a removed API). The rule: fix the CODE, not the TESTS.
+If unsure whether the test is wrong or the implementation is wrong → call `rune:debug` to investigate.
+</HARD-GATE>
+
+## Triggers
+
+- Called by `cook` Phase 4 IMPLEMENT — write code to pass tests
+- Called by `debug` when root cause found and fix is ready
+- Called by `review` when bugs found during review
+- `/rune fix <issue>` — manual fix application
+- Auto-trigger: after successful debug diagnosis
+
+## Calls (outbound)
+
+- `debug` (L2): when root cause unclear before fixing — need diagnosis first
+- `test` (L2): verify fix with tests after applying changes
+- `review` (L2): self-review for complex or risky fixes
+- `verification` (L3): validate fix doesn't break existing functionality
+- `docs-seeker` (L3): check correct API usage before applying changes
+- `hallucination-guard` (L3): verify imports after code changes
+- `scout` (L2): find related code before applying changes
+
+## Called By (inbound)
+
+- `cook` (L1): Phase 4 IMPLEMENT — apply code changes
+- `debug` (L2): root cause found, ready to apply fix
+- `review` (L2): bug found during review, needs fixing
+- `surgeon` (L2): apply refactoring changes
+- `review-intake` (L2): apply fixes identified during structured review intake
+
+## Cross-Hub Connections
+
+- `fix` ↔ `debug` — bidirectional: debug diagnoses → fix applies, fix can't determine cause → debug investigates
+- `fix` → `test` — after applying fix, run tests to verify
+- `fix` ← `review` — review finds bug → fix applies correction
+- `fix` → `review` — complex fix requests self-review
+
+## Execution
+
+### Step 1: Understand
+
+Read and fully understand the fix request before touching any file.
+
+- Read the incoming request: debug report, plan spec, or review finding
+- Identify what is broken or missing and what the expected behavior should be
+- If the request is ambiguous or root cause is unclear → call `rune:debug` before proceeding
+- Note the scope: single function, single file, or multi-file change
+
+### Step 2: Locate
+
+Find the exact files and lines to change.
+
+- Use `rune:scout` to locate the relevant files, functions, and surrounding code
+- Use `Read` to examine the specific file:line identified in the debug report or plan
+- Use `Glob` to find related files: types, tests, config that may also need updating
+- Map all touch points before writing a single line of code
+
+### Step 3: Change
+
+Apply the minimal set of changes needed.
+
+- Use `Edit` for targeted modifications to existing files
+- Use `Write` only when creating a genuinely new file is required
+- Follow project conventions: naming, immutability patterns, error handling style
+- Keep changes minimal — fix the stated problem, do not refactor unrelated code (YAGNI)
+- Never use `any` in TypeScript; never use bare `except:` in Python
+- If a new import is needed → note it for Step 5 hallucination-guard check
+
+### Step 4: Verify
+
+Confirm the change works and nothing is broken.
+
+- Use `Bash` to run the relevant tests: the specific failing test first, then the full suite
+- If tests fail after the fix:
+  - Investigate with `rune:debug` (max 3 debug loops before escalating)
+  - Do NOT change test files to make tests pass — fix the implementation code
+- If project has a type-check command, run it via `Bash`
+- If project has a lint command, run it via `Bash`
+
+### Step 5: Post-Fix Hardening (Defense-in-Depth)
+
+After the fix works, make the bug **structurally impossible** — not just "fixed this time."
+
+Single validation at one point can be bypassed by different code paths, refactoring, or mocks. Add validation at EVERY layer data passes through:
+
+| Layer | Purpose | Example |
+|-------|---------|---------|
+| **Entry Point** | Reject invalid input at API boundary | Validate params not empty/exists/correct type |
+| **Business Logic** | Ensure data makes sense for this operation | Check preconditions specific to this function |
+| **Environment Guard** | Prevent dangerous ops in specific contexts | In tests: refuse writes outside tmpdir |
+| **Debug Instrumentation** | Capture context for forensics if bug recurs | Log stack trace + key values before risky ops |
+
+Apply this when: the bug was caused by invalid data flowing through multiple layers. Skip for trivial one-liner fixes.
+
+### Step 6: Self-Review
+
+Verify correctness of the changes just made.
+
+- Call `rune:hallucination-guard` to verify all imports introduced or modified are real and correctly named
+- Call `rune:docs-seeker` if any external API, library method, or SDK call was added or changed
+- For complex or risky fixes (auth, data mutation, async logic): call `rune:review` for a full quality check
+
+### Step 7: Report
+
+Produce a structured summary of all changes made.
+
+- List every file modified and a one-line description of what changed
+- Include verification results (tests, types, lint)
+- Note any follow-up work if the fix is partial or has known limitations
+
+## Constraints
+
+1. MUST NOT change test files to make tests pass — fix the CODE, not the TESTS
+2. MUST have a diagnosis (from debug or clear error) before applying fixes
+3. MUST run tests after each fix attempt — never batch multiple untested changes
+4. MUST NOT exceed 3 fix attempts — if 3 fixes fail, re-diagnose via rune:debug (which will classify: wrong approach → brainstorm rescue, wrong design → plan redesign)
+5. MUST follow project conventions found by scout — don't invent new patterns
+6. MUST NOT add unplanned features while fixing — fix only what was diagnosed
+7. MUST track fix attempt number — this feeds debug's 3-Fix Escalation classification
+
+## Mesh Gates
+
+| Gate | Requires | If Missing |
+|------|----------|------------|
+| Evidence Gate | Debug report OR clear error description before fixing | Run rune:debug first |
+| Test Gate | Tests run after each fix attempt | Run tests before claiming fix works |
+
+## Output Format
+
+```
+## Fix Report
+- **Task**: [what was fixed/implemented]
+- **Status**: complete | partial | blocked
+
+### Changes
+- `path/to/file.ts` — [description of change]
+- `path/to/other.ts` — [description of change]
+
+### Verification
+- Lint: PASS | FAIL
+- Types: PASS | FAIL
+- Tests: PASS | FAIL ([n] passed, [m] failed)
+
+### Notes
+- [any caveats or follow-up needed]
+```
+
+## Sharp Edges
+
+Known failure modes for this skill. Check these before declaring done.
+
+| Failure Mode | Severity | Mitigation |
+|---|---|---|
+| Modifying test files to make tests pass | CRITICAL | HARD-GATE blocks this — fix the code, never the tests (unless test setup is provably wrong) |
+| Applying fix without a diagnosis | HIGH | Evidence Gate: need debug report or clear error description before touching code |
+| Exceeding 3 fix attempts without re-diagnosing | HIGH | Constraint 4: after 3 failures, call debug again — the hypothesis was wrong |
+| Introducing unrelated refactoring while fixing | MEDIUM | YAGNI: fix only what was diagnosed — unrelated changes belong in a separate task |
+| Not running tests after each individual change | MEDIUM | Constraint 3: never batch untested changes — run tests after each edit |
+| 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 |
+
+## Done When
+
+- Root cause identified (debug report or clear error received)
+- Minimal changes applied targeting only the diagnosed problem
+- 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
+
+## Cost Profile
+
+~2000-5000 tokens input, ~1000-3000 tokens output. Sonnet for code writing quality. Most active skill during implementation.

package/skills/git/SKILL.md

@@ -0,0 +1,285 @@
+---
+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"
+  layer: L3
+  model: haiku
+  group: utility
+  tools: "Read, Bash, Glob, Grep"
+---
+
+# git
+
+## Purpose
+
+Specialized git operations utility. Handles semantic commits, PR descriptions, branch naming, and changelog generation with consistent conventions. Replaces scattered git logic across cook Phase 7 and other skills with a single, convention-aware utility.
+
+## Triggers
+
+- Called by `cook` Phase 7 for commit creation
+- Called by `scaffold` Phase 8 for initial commit
+- Called by `team` for parallel branch/PR management
+- Called by `docs` for changelog generation
+- Called by `launch` for release tagging
+- `/rune git commit` — manual semantic commit
+- `/rune git pr` — manual PR generation
+- `/rune git branch <description>` — generate branch name
+- `/rune git changelog` — generate changelog from commits
+
+## Calls (outbound)
+
+None — pure L3 utility. Reads git state, produces git commands/output.
+
+## Called By (inbound)
+
+- `cook` (L1): Phase 7 — create semantic commit after implementation
+- `scaffold` (L1): Phase 8 — initial commit with generated project
+- `team` (L1): parallel PR management across workstreams
+- `launch` (L1): release tagging and changelog
+- `docs` (L2): changelog generation sub-workflow
+- User: `/rune git` direct invocation
+
+## Modes
+
+### Commit Mode (default)
+
+Analyze staged changes and produce a semantic commit.
+
+### PR Mode
+
+Analyze full branch diff against base and produce a pull request.
+
+### Branch Mode
+
+Generate a branch name from a task description.
+
+### Changelog Mode
+
+Generate changelog entries from commit history.
+
+## Executable Steps
+
+### Commit Mode
+
+#### Step 1 — Analyze Staged Changes
+
+Read `git diff --staged` and `git status`. Classify the change:
+
+| Type | Signal | Prefix |
+|------|--------|--------|
+| New feature | New files, new exports, new routes | `feat` |
+| Bug fix | Changed logic in existing code, test fix | `fix` |
+| Refactor | Structural change, no behavior change | `refactor` |
+| Test | Only test files changed | `test` |
+| Documentation | Only .md, comments, JSDoc changed | `docs` |
+| Build/CI | Config files, CI pipelines, Dockerfile | `chore` |
+| Performance | Optimization, caching, query improvement | `perf` |
+
+#### Step 2 — Detect Scope
+
+Extract scope from file paths:
+- `src/auth/*` → scope: `auth`
+- `src/components/Button.tsx` → scope: `ui`
+- `api/routes/users.ts` → scope: `api`
+- Multiple directories → omit scope or use most relevant
+- Root config files → scope: `config`
+
+#### Step 3 — Generate Commit Message
+
+Format: `<type>(<scope>): <description>`
+
+Rules:
+- Description: imperative mood, lowercase first letter, no period
+- Max 72 characters for subject line
+- If > 5 files changed → add body with bullet summary
+- If breaking change detected (removed export, changed API signature, schema change) → add `!` suffix and `BREAKING CHANGE:` footer
+
+```
+feat(auth): add JWT refresh token rotation
+
+- Add refresh token endpoint with sliding window expiry
+- Store token family for reuse detection
+- Add middleware to validate refresh tokens
+
+BREAKING CHANGE: /api/auth/refresh now requires refresh_token in body instead of cookie
+```
+
+#### Step 4 — Execute
+
+Run `git commit` with the generated message. If pre-commit hooks fail → report the failure, do not `--no-verify`.
+
+### PR Mode
+
+#### Step 1 — Analyze Branch
+
+Read ALL commits on the current branch vs base branch using `git log <base>..HEAD` and `git diff <base>...HEAD`.
+
+Do NOT just look at the latest commit — PRs include ALL branch commits.
+
+#### Step 2 — Generate PR
+
+```markdown
+## Summary
+<1-3 bullet points covering ALL changes, not just the last commit>
+
+## Changes
+- [grouped by feature/area]
+
+## Test Plan
+- [ ] [specific test scenarios]
+
+## Breaking Changes
+- [if any — list explicitly]
+```
+
+Title: < 70 characters, descriptive of the full change set.
+
+#### Step 3 — Execute
+
+Run `gh pr create` with generated title and body. If no remote branch → push with `-u` first.
+
+### Branch Mode
+
+#### Step 1 — Parse Task
+
+Extract key intent from task description:
+- Feature → `feat/short-kebab-description`
+- Bug fix → `fix/issue-number-or-description`
+- Refactor → `refactor/module-name`
+- Chore → `chore/description`
+
+Rules:
+- Max 50 characters total
+- Kebab-case, no uppercase
+- Include issue number if referenced: `fix/123-login-crash`
+
+#### Step 2 — Execute
+
+Run `git checkout -b <branch-name>` from current branch.
+
+### Changelog Mode
+
+#### Step 1 — Read History
+
+Read commits since last tag (`git log $(git describe --tags --abbrev=0)..HEAD`) or since specified reference.
+
+#### Step 2 — Group and Format
+
+Group commits by conventional commit type. Format as [Keep a Changelog](https://keepachangelog.com/):
+
+```markdown
+## [Unreleased]
+
+### Added
+- New feature description (#PR)
+
+### Fixed
+- Bug fix description (#PR)
+
+### Changed
+- Change description (#PR)
+
+### Removed
+- Removed feature (#PR)
+```
+
+Link to PRs/issues when references found in commit messages.
+
+## Output Format
+
+### Commit Mode
+```
+<type>(<scope>): <description>
+
+[optional body — bullet summary if > 5 files changed]
+
+[BREAKING CHANGE: description — if breaking change detected]
+```
+
+### PR Mode
+```
+Title: <type>: <short description> (< 70 chars)
+
+## Summary
+- [bullet points covering ALL branch changes]
+
+## Changes
+- [grouped by feature/area]
+
+## Test Plan
+- [ ] [specific test scenarios]
+
+## Breaking Changes
+- [if any]
+```
+
+### Branch Mode
+```
+<type>/<short-kebab-description>
+```
+Examples: `feat/jwt-refresh`, `fix/123-login-crash`, `refactor/auth-module`
+
+### Changelog Mode
+```markdown
+## [Unreleased]
+
+### Added
+- Feature description (#PR)
+
+### Fixed
+- Bug fix description (#PR)
+
+### Changed
+- Change description (#PR)
+```
+
+## Constraints
+
+1. MUST use conventional commit format — no freeform messages
+2. MUST analyze full diff before generating message — don't guess from file names alone
+3. MUST detect breaking changes — missing BREAKING CHANGE footer causes downstream issues
+4. MUST NOT use `--no-verify` — if hooks fail, report and fix
+5. MUST NOT force push unless explicitly requested by user
+6. PR mode MUST analyze ALL commits on branch, not just the latest
+7. MUST respect project's existing commit conventions if detected (check recent git log)
+
+## Sharp Edges
+
+| Failure Mode | Severity | Mitigation |
+|---|---|---|
+| Commit message doesn't match actual changes | HIGH | Step 1 reads full diff, not just file names |
+| PR description covers only last commit | HIGH | Step 1 reads ALL commits on branch |
+| Missing breaking change detection | HIGH | Check: removed exports, changed function signatures, schema changes |
+| Branch name too long or has special characters | LOW | Max 50 chars, kebab-case only |
+| Force push without user consent | CRITICAL | Constraint 5: never force push unless explicitly requested |
+| Ignoring project's existing conventions | MEDIUM | Check recent `git log --oneline -10` for existing style |
+
+## Done When
+
+### Commit Mode
+- Staged diff analyzed and change type classified
+- Scope extracted from file paths
+- Semantic commit message generated (subject + body if needed)
+- Breaking changes detected and flagged
+- Commit executed (or failure reported)
+
+### PR Mode
+- All branch commits analyzed (not just latest)
+- Summary covers full change set
+- Test plan included
+- PR created with `gh pr create`
+
+### Branch Mode
+- Branch name follows convention
+- Branch created from current HEAD
+
+### Changelog Mode
+- All commits since last tag grouped by type
+- Formatted as Keep a Changelog
+- PR/issue references linked
+
+## Cost Profile
+
+~500-2000 tokens input, ~200-800 tokens output. Haiku — git operations are mechanical and convention-based, no deep reasoning needed.