@rune-kit/rune 2.1.1

package/skills/scope-guard/SKILL.md

@@ -0,0 +1,150 @@
+---
+name: scope-guard
+description: "Detects scope creep. Auto-triggered by L1 orchestrators when files exceed the original plan. Compares current git changes against plan, flags out-of-scope files, reports IN_SCOPE or CREEP_DETECTED."
+user-invocable: false
+metadata:
+  author: runedev
+  version: "0.3.0"
+  layer: L3
+  model: haiku
+  group: monitoring
+  tools: "Read, Glob, Grep"
+---
+
+# scope-guard
+
+## Purpose
+
+Passive scope monitor. Reads the original task plan, inspects current git diff to see what files have changed, and compares them against the planned scope. Flags any unplanned additions as scope creep with specific file-level detail.
+
+## Called By (inbound)
+
+- Auto-triggered by L1 orchestrators when files changed exceed plan expectations
+
+## Calls (outbound)
+
+None — pure L3 monitoring utility.
+
+## Executable Instructions
+
+### Step 1: Load Plan
+
+Read the original task/plan from one of these sources (check in order):
+
+1. TodoWrite task list — read active todos as the planned scope
+2. `.rune/progress.md` — use `Read` on `D:\Project\.rune\progress.md` (or equivalent path)
+3. If neither exists, ask the calling skill to provide the plan as a text description
+
+Extract from the plan:
+- List of files/directories expected to be changed
+- List of features/tasks planned
+- Any explicitly out-of-scope items mentioned
+
+### Step 2: Assess Current Work
+
+Run `Bash` with git diff to see what has actually changed:
+
+```bash
+git diff --stat HEAD
+```
+
+Also check staged changes:
+
+```bash
+git diff --stat --cached
+```
+
+Parse the output to extract the list of changed files.
+
+### Step 3: Compare
+
+For each changed file, determine if it is:
+- **IN_SCOPE**: file matches a planned file/directory or is a natural dependency of planned work
+- **OUT_OF_SCOPE**: file is not mentioned in the plan and is not a direct dependency
+
+Rules for "natural dependency" (counts as IN_SCOPE):
+- Test files for planned source files
+- Config files modified as a side-effect of adding a planned feature
+- Lock files (package-lock.json, yarn.lock, Cargo.lock) — always IN_SCOPE
+
+Rules for OUT_OF_SCOPE (counts as creep):
+- New features not mentioned in the plan
+- Refactoring of files unrelated to the task
+- New dependencies added without a planned feature requiring them
+- Documentation files for unplanned features
+
+### Step 4: Flag Creep
+
+If any OUT_OF_SCOPE files are detected:
+- List each out-of-scope file with the reason it is flagged
+- Classify as: `MINOR CREEP` (1-2 unplanned files) or `SIGNIFICANT CREEP` (3+ unplanned files)
+
+If zero OUT_OF_SCOPE files: status is `IN_SCOPE`.
+
+### Step 5: Report
+
+Output the following structure:
+
+```
+## Scope Report
+
+- **Planned files**: [count from plan]
+- **Actual files changed**: [count from git diff]
+- **Out-of-scope files**: [count]
+- **Status**: IN_SCOPE | MINOR CREEP | SIGNIFICANT CREEP
+
+### In-Scope Changes
+- [file] — [matches planned task]
+
+### Out-of-Scope Changes
+- [file] — [reason: unplanned feature | unrelated refactor | unplanned dep]
+
+### Recommendations
+- [If IN_SCOPE]: No action needed. Proceed.
+- [If MINOR CREEP]: Review [file] — consider reverting or acknowledging as intentional.
+- [If SIGNIFICANT CREEP]: STOP. Re-align with original plan before continuing. [list files to revert]
+```
+
+## Output Format
+
+```
+## Scope Report
+- Planned files: 3 | Actual: 5 | Out-of-scope: 2
+- Status: MINOR CREEP
+
+### Out-of-Scope Changes
+- src/components/NewWidget.tsx — unplanned feature
+- docs/new-feature.md — documentation for unplanned feature
+
+### Recommendations
+- Review src/components/NewWidget.tsx — revert or log as intentional scope change.
+```
+
+## Constraints
+
+1. MUST compare actual changes against stated scope — not just file count
+2. MUST flag files modified outside scope with specific paths
+3. MUST allow user override — advisory, not authoritarian
+
+## Sharp Edges
+
+Known failure modes for this skill. Check these before declaring done.
+
+| Failure Mode | Severity | Mitigation |
+|---|---|---|
+| Classifying test files for planned code as out-of-scope | MEDIUM | Test files for planned source files are always IN_SCOPE — natural dependency |
+| Classifying lock file changes as out-of-scope | LOW | package-lock.json, yarn.lock, Cargo.lock are always IN_SCOPE |
+| SIGNIFICANT CREEP threshold applied to 1-2 unplanned files | LOW | MINOR = 1-2 files, SIGNIFICANT = 3+ files — don't escalate prematurely |
+| Plan not loadable (no TodoWrite, no progress.md) | MEDIUM | Ask calling skill for plan as text description before proceeding |
+
+## Done When
+
+- Plan loaded from TodoWrite active tasks or .rune/progress.md
+- git diff --stat and --cached output parsed for all changed files
+- Each changed file classified IN_SCOPE or OUT_OF_SCOPE with reasoning
+- Creep severity classified (IN_SCOPE / MINOR CREEP / SIGNIFICANT CREEP)
+- Scope Report emitted with recommendations
+
+## Cost Profile
+
+~200-500 tokens input, ~100-300 tokens output. Haiku. Lightweight monitor.

package/skills/scout/SKILL.md

@@ -0,0 +1,232 @@
+---
+name: scout
+description: "Fast codebase scanner. Use when any skill needs codebase context. Finds files, patterns, dependencies, project structure. Pure read-only — never modifies files."
+metadata:
+  author: runedev
+  version: "0.2.0"
+  layer: L2
+  model: haiku
+  group: creation
+  tools: "Read, Glob, Grep"
+---
+
+# scout
+
+Fast, lightweight codebase scanning. Scout is the eyes of the Rune ecosystem.
+
+## Instructions
+
+When invoked, perform these steps:
+
+### Phase 1: Structure Scan
+
+Map the project layout:
+
+1. Use `Glob` with `**/*` to understand directory structure
+2. Use `Bash` to run `ls` on key directories (root, src, lib, app)
+3. Identify framework by detecting these files:
+   - `package.json` → Node.js/TypeScript
+   - `Cargo.toml` → Rust
+   - `pyproject.toml` / `setup.py` → Python
+   - `go.mod` → Go
+   - `pom.xml` / `build.gradle` → Java
+
+```
+TodoWrite: [
+  { content: "Scan project structure", status: "in_progress" },
+  { content: "Run targeted file search", status: "pending" },
+  { content: "Map dependencies", status: "pending" },
+  { content: "Detect conventions", status: "pending" },
+  { content: "Generate codebase map (if full scan)", status: "pending" },
+  { content: "Generate scout report", status: "pending" }
+]
+```
+
+### Phase 2: Targeted Search (Search-First)
+
+**Search-first principle**: Before building anything new, scout checks if a solution already exists — in the codebase, in package registries, or in available MCP servers.
+
+**Adopt / Extend / Compose / Build decision matrix**:
+
+When scout finds the caller's target domain, classify the situation:
+
+```
+ADOPT     — Exact match exists (in codebase, npm, PyPI, MCP). Use as-is.
+EXTEND    — Partial match exists. Extend/configure existing solution.
+COMPOSE   — Multiple pieces exist. Wire them together.
+BUILD     — Nothing suitable exists. Build from scratch.
+```
+
+Report the classification to the calling skill. This informs Phase 2 (PLAN) in cook — ADOPT and EXTEND are vastly cheaper than BUILD.
+
+**Quick checks before deep search**:
+1. `Grep` the codebase for existing implementations of the target functionality
+2. Check `package.json` / `pyproject.toml` / `Cargo.toml` for relevant installed packages
+3. If the task involves external data/APIs: note available MCP servers that might help
+
+Based on the scan request, run focused searches:
+
+1. Use `Glob` to find files matching the target domain:
+   - Auth domain: `**/*auth*`, `**/*login*`, `**/*session*`
+   - API domain: `**/*.controller.*`, `**/*.route.*`, `**/*.handler.*`
+   - Data domain: `**/*.model.*`, `**/*.schema.*`, `**/*.entity.*`
+2. Use `Grep` to search for specific patterns:
+   - Function names: `pattern: "function <name>"` or `"def <name>"`
+   - Class definitions: `pattern: "class <Name>"`
+   - Import statements: `pattern: "import.*<module>"` or `"from <module>"`
+3. Use `Read` to examine the most relevant files (max 10 files, prioritize by relevance)
+
+**Verification gate**: At least 1 relevant file found, OR confirm the target does not exist.
+
+### Phase 3: Dependency Mapping
+
+1. Use `Grep` to find import/require/use statements in identified files
+2. Map which modules depend on which (A → imports → B)
+3. Identify the blast radius of potential changes: which files import the target file
+
+### Phase 4: Convention Detection
+
+1. Check for config files using `Glob`:
+   - `.eslintrc*`, `eslint.config.*` → ESLint rules
+   - `tsconfig.json` → TypeScript config
+   - `.prettierrc*` → Prettier config
+   - `ruff.toml`, `.ruff.toml` → Python linter
+2. Check naming conventions by reading 2-3 representative source files
+3. Find existing tests with `Glob`: `**/*.test.*`, `**/*.spec.*`, `**/test_*`
+4. Determine test framework: `jest.config.*`, `vitest.config.*`, `pytest.ini`
+
+### Phase 5: Codebase Map (Optional)
+
+When called by `cook`, `team`, `onboard`, or `autopsy` (skills that need full project understanding), generate a structured codebase map:
+
+1. Create `.rune/codebase-map.md` with:
+
+```markdown
+## Codebase Map
+Generated: [timestamp]
+
+### Module Boundaries
+| Module | Directory | Public API | Dependencies | Domain |
+|--------|-----------|-----------|--------------|--------|
+| auth | src/auth/ | login(), logout(), verify() | database, config | Authentication |
+| api | src/api/ | routes, middleware | auth, database | HTTP Layer |
+
+### Dependency Graph (Mermaid)
+​```mermaid
+graph LR
+  api --> auth
+  api --> database
+  auth --> database
+  auth --> config
+​```
+
+### Domain Ownership
+| Domain | Modules | Key Files |
+|--------|---------|-----------|
+| Authentication | auth, session | src/auth/login.ts, src/auth/verify.ts |
+| Data Layer | database, models | src/db/schema.ts, src/models/ |
+```
+
+2. Derive modules from directory structure (top-level `src/` subdirectories, or detected framework conventions)
+3. Public API = exported functions/classes from each module's index/entry file
+4. Dependencies = import statements between modules (from Phase 3)
+5. Domain = inferred from module name + file contents (auth, payments, frontend, infra, data, config, etc.)
+
+**Skip this phase** when called by skills that only need targeted search (debug, fix, review, sentinel).
+
+### Phase 6: Generate Report
+
+Produce structured output for the calling skill. Update TodoWrite to completed.
+
+## Constraints
+
+- **Read-only**: NEVER use Edit, Write, or Bash with destructive commands. Exception: Phase 5 may write `.rune/codebase-map.md` when called by cook, team, onboard, or autopsy
+- **Fast**: Max 10 file reads per scan. Prioritize by relevance score
+- **Focused**: Only scan what is relevant to the request, not the entire codebase
+- **No side effects**: Do not cache, store, or modify anything
+
+## Error Recovery
+
+- If `Glob` returns 0 results: try broader pattern, then report "not found"
+- If a file fails to `Read`: skip it, note in report, continue with remaining files
+- If project type is ambiguous: check multiple config files, report all candidates
+
+## Calls (outbound)
+
+None — pure scanner using Glob, Grep, Read, and Bash tools directly. Does not invoke other skills.
+
+## Called By (inbound)
+
+- `plan` (L2): scan codebase before planning
+- `debug` (L2): find related code for root cause analysis
+- `review` (L2): find related code for context during review
+- `fix` (L2): understand dependencies before changing code
+- `cook` (L1): Phase 1 UNDERSTAND — scan codebase
+- `team` (L1): understand full project scope
+- `sentinel` (L2): scan changed files for security issues
+- `preflight` (L2): find affected code paths
+- `onboard` (L2): full project scan for CLAUDE.md generation
+- `autopsy` (L2): comprehensive health assessment
+- `surgeon` (L2): scan module before refactoring
+- `marketing` (L2): scan codebase for feature descriptions
+- `safeguard` (L2): scan module boundaries before adding safety net
+- `audit` (L2): Phase 0 project structure and stack discovery
+- `db` (L2): find schema and migration files
+- `design` (L2): scan UI component library and design tokens
+- `perf` (L2): find hotpath files and performance-critical code
+- `review-intake` (L2): scan codebase for review context
+- `skill-forge` (L2): scan existing skills for patterns when creating new skills
+
+## Output Format
+
+```
+## Scout Report
+- **Project**: [name] | **Framework**: [detected] | **Language**: [detected]
+- **Files**: [count] | **Test Framework**: [detected]
+
+### Relevant Files
+| File | Why Relevant | LOC |
+|------|-------------|-----|
+| `path/to/file` | [reason] | [lines] |
+
+### Dependencies
+- `module-a` → imports → `module-b`
+
+### Conventions
+- Naming: [pattern detected]
+- File structure: [pattern]
+- Test pattern: [pattern]
+
+### Search-First Assessment
+- **Classification**: ADOPT | EXTEND | COMPOSE | BUILD
+- **Existing solution**: [what was found, if any]
+- **Recommendation**: [brief rationale]
+
+### Observations
+- [pattern or potential issue noticed]
+```
+
+## Sharp Edges
+
+Known failure modes for this skill. Check these before declaring done.
+
+| Failure Mode | Severity | Mitigation |
+|---|---|---|
+| Reading all files instead of targeted search (50+ files scanned) | MEDIUM | Max 10 file reads enforced — prioritize by relevance to the caller's domain |
+| Reporting "nothing found" without trying a broader pattern | MEDIUM | Try broader glob first (e.g. `**/*auth*` → `**/auth*` → `**/*login*`), then report not found |
+| Wrong framework detection affects all downstream planning | HIGH | Check multiple config files; report all candidates if ambiguous, don't guess |
+| Missing dependency blast radius in Phase 3 | MEDIUM | Phase 3 is mandatory — callers need to know what else imports the target |
+
+## Done When
+
+- Project structure mapped (directory layout, entry points)
+- Framework detected from config files (or "ambiguous" with candidates listed)
+- Targeted file search completed for the caller's domain
+- Dependency blast radius identified for target files
+- Conventions detected (naming, test framework, linting config)
+- Codebase map written to `.rune/codebase-map.md` (when called by cook, team, onboard, autopsy)
+- Scout Report emitted in structured format with Relevant Files table
+
+## Cost Profile
+
+~500-2000 tokens input, ~200-500 tokens output. Always haiku. Cheapest skill in the mesh.