From rune
Scans codebase structure, detects frameworks via key files (package.json, Cargo.toml, pyproject.toml), finds files/patterns/dependencies with Glob/Grep/Bash. Use for context before building.
npx claudepluginhub rune-kit/rune --plugin @rune/analyticsThis skill uses the workspace's default tool permissions.
Fast, lightweight codebase scanning. Scout is the eyes of the Rune ecosystem.
Maps unfamiliar codebases in phases: structure, entry points, data flow, patterns, landmines. Use before coding in new, inherited, or revisited projects.
Maps codebase structure, patterns, symbols, and dependencies using ast-grep and bash scripts. Outputs factual maps with paths/line numbers to .artifacts/research/.
Share bugs, ideas, or general feedback.
Fast, lightweight codebase scanning. Scout is the eyes of the Rune ecosystem.
When invoked, perform these steps:
Map the project layout:
Glob with **/* to understand directory structureBash to run ls on key directories (root, src, lib, app)package.json → Node.js/TypeScriptCargo.toml → Rustpyproject.toml / setup.py → Pythongo.mod → Gopom.xml / build.gradle → JavaTodoWrite: [
{ 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" }
]
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:
Grep the codebase for existing implementations of the target functionalitypackage.json / pyproject.toml / Cargo.toml for relevant installed packagesBased on the scan request, run focused searches:
Glob to find files matching the target domain:
**/*auth*, **/*login*, **/*session***/*.controller.*, **/*.route.*, **/*.handler.***/*.model.*, **/*.schema.*, **/*.entity.*Grep to search for specific patterns:
pattern: "function <name>" or "def <name>"pattern: "class <Name>"pattern: "import.*<module>" or "from <module>"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.
Scout's default is "max 10 file reads" — but the real question is whether additional reads are productive. Track saturation across Phase 2 searches:
Entity tracking: As you scan files, extract key entities (function names, class names, imports, API endpoints, config keys). Maintain a running set of discovered entities.
| Signal | Threshold | Meaning | Action |
|---|---|---|---|
| New entity ratio | Last 2 file reads added <2 new entities | Search is exhausted for this domain | STOP scanning, move to Phase 3 |
| Content similarity | Last 2 files share >70% of the same imports/patterns | Files are in the same module, redundant reads | Skip remaining files in this directory |
| Query variation | 3+ Glob/Grep queries with different patterns all return the same files | All search angles converge | Domain is fully mapped, proceed |
When saturation detected: Emit in Scout Report:
### Saturation
- Reached after [N] file reads — last 2 reads added [M] new entities
- Recommendation: synthesize_and_report (further scanning unlikely to yield new insights)
Why: Without saturation detection, scout reads its full budget of 10 files even when 3 files already contain everything needed. This wastes context tokens and delays the calling skill. Early saturation detection returns control faster.
Grep to find import/require/use statements in identified filesGlob:
.eslintrc*, eslint.config.* → ESLint rulestsconfig.json → TypeScript config.prettierrc* → Prettier configruff.toml, .ruff.toml → Python linterGlob: **/*.test.*, **/*.spec.*, **/test_*jest.config.*, vitest.config.*, pytest.iniTriggered by mode="zoom-out" from the caller, OR auto-triggered by listening on agent.stuck signal (emitted by fix after 2+ failed attempts on the same file, or by debug after 3+ disproved hypothesis cycles).
When activated, scout produces a 3-layer ascent map:
| Layer | What it includes | Cap |
|---|---|---|
| L0 (target) | The stuck file's symbols + immediate imports | unlimited |
| L1 (siblings) | Files in the same directory + their public exports | 8 files |
| L2 (callers/neighbors) | Modules that import L0's exports + neighboring modules in the same domain | 8 modules |
Output is a Mermaid diagram, NOT just a file list — visual is the value-add when an agent is stuck.
graph LR
target[src/auth/login.ts]:::stuck
target --> dep1[crypto.compare]
target --> dep2[db.users.get]
caller1[src/routes/auth.ts] --> target
caller2[src/middleware/protect.ts] --> target
sibling1[src/auth/refresh.ts] -.same-dir.- target
sibling2[src/auth/logout.ts] -.same-dir.- target
classDef stuck fill:#ff6b6b
Bounded — L2 ascent caps at 8 modules. If exceeded, collapse to "showing top 8 by import-frequency". Never blow past the cap silently.
After emitting the map, scout returns to its normal Phase 6 (Generate Report) with the zoom-out section as the primary output.
When called by cook, team, onboard, or autopsy (skills that need full project understanding), generate a structured codebase map:
.rune/codebase-map.md with:## 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/ |
src/ subdirectories, or detected framework conventions)Skip this phase when called by skills that only need targeted search (debug, fix, review, sentinel).
Produce structured output for the calling skill. Update TodoWrite to completed.
.rune/codebase-map.md when called by cook, team, onboard, or autopsyGlob returns 0 results: try broader pattern, then report "not found"Read: skip it, note in report, continue with remaining filesNone — pure scanner using Glob, Grep, Read, and Bash tools directly. Does not invoke other skills.
plan (L2): scan codebase before planningdebug (L2): find related code for root cause analysisreview (L2): find related code for context during reviewfix (L2): understand dependencies before changing codecook (L1): Phase 1 UNDERSTAND — scan codebaseteam (L1): understand full project scopesentinel (L2): scan changed files for security issuespreflight (L2): find affected code pathsonboard (L2): full project scan for CLAUDE.md generationautopsy (L2): comprehensive health assessmentsurgeon (L2): scan module before refactoringmarketing (L2): scan codebase for feature descriptionssafeguard (L2): scan module boundaries before adding safety netaudit (L2): Phase 0 project structure and stack discoverydb (L2): find schema and migration filesdesign (L2): scan UI component library and design tokensperf (L2): find hotpath files and performance-critical codereview-intake (L2): scan codebase for review contextskill-forge (L2): scan existing skills for patterns when creating new skillsba (L2): scan existing codebase for context before requirements elicitationretro (L2): scan commit history and codebase for retrospective analysisgraft (L2): scan target codebase before grafting code from external repodocs (L2): scan codebase structure for documentation generationlogic-guardian (L2): scan business logic modules for protection mappingadversary (L2): scan codebase before red-team analysisimprove-architecture (L2): re-scan target module + callers when input context is stale## 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]
| Artifact | Format | Location |
|---|---|---|
| Scout Report | Markdown (inline) | Emitted to calling skill |
| Codebase map | Markdown | .rune/codebase-map.md (when called by cook, team, onboard, autopsy) |
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 |
.rune/codebase-map.md (when called by cook, team, onboard, autopsy)~500-2000 tokens input, ~200-500 tokens output. Always haiku. Cheapest skill in the mesh.
Scope guardrail: Do not expand the scan to unrelated modules or write files beyond .rune/codebase-map.md unless explicitly delegated by the parent agent.