A scout goes ahead into unknown territory, reports back with reliable information, and
leaves a map for whoever follows. scout does that for software: point Claude at a
multi-repo system and it builds trustworthy, evidence-backed understanding, produces
shareable artifacts, and persists a knowledge base so the next engineer (or the next
session) starts warm instead of cold.
Built for the moment you land in a codebase you don't know and have to answer, quickly and correctly: how does this thing actually work?
| Mode | Ask it… | You get |
|---|---|---|
| 🗺️ Map | "onboard me to this system" | Architecture overview: service roles, stacks, data stores, cross-service links, vendor glossary |
| 🚶 Walkthrough | "walk me through this repo — where's the entry point?" | Guided reading path at your chosen depth (core / standard / detailed / deep): entry point, ordered call chain function→function, load-bearing functions, call-graph diagram (ASCII + SVG) |
| 🔎 Trace | "how is X fetched? give me the curl" | Data lineage, request payload, response schema, faithful curls, flow diagram (ASCII + SVG) |
| ✅ Verify | "fact-check this analysis" | Claim-by-claim verdicts (CONFIRMED / PARTLY-TRUE / FALSE) with file:line |
| 🔐 Audit | "find secrets / what's risky" | Secret inventory + risky-pattern findings, severity-ranked, with masked output |
| 📖 Guide | "put it all in one doc — one file to learn the whole repo" | One self-contained, diagram-rich learning document (inline Mermaid) at your chosen audience (newcomer / engineer / expert): what-it-is + why, primer, architecture, a tour of each subsystem, deep dives, why-it's-shaped-this-way, glossary |
Modes chain: map a system, walk through the code, trace a vendor through it, audit what you found, then package it all into a guide. Map is breadth (what exists); Walkthrough is depth in one codebase (how the code runs); Guide is the standalone artifact that packages both plus teaching into one file — "one representative per category + a diff table" covers a huge repo in a readable doc.
Baked into every mode:
- Parallel fan-out — one sub-agent per repo, run concurrently, then synthesized.
- Adversarial verify pass — findings are re-checked (and refuted where possible) before you see them.
- Evidence or it didn't happen — every claim carries
file:line, and everything is labelled: config vs execution, in-repo vs external, confirmed vs reconstructed. Never fabricated. - Secret-safe by default — secrets are masked in shareable output, and committed secrets are surfaced as findings.
you: "/scout:trace how is Edited data fetched?"
│
▼
┌───────────────┐ reads .scout/ notes first (start warm)
│ scout skill │
└───────┬───────┘
│ fan out — one worker per repo, concurrently
┌──────────┼──────────┬──────────┐
▼ ▼ ▼ ▼
repo-explorer repo-explorer … (agents/repo-explorer.md)
│ │ │ │
└──────────┴────┬─────┴──────────┘
│ synthesize into the mode's artifact
▼
┌───────────────┐
│ verifier │ adversarial pass — refute each claim
└───────┬───────┘ (agents/verifier.md)
│ mask secrets · label externals · keep file:line
▼
answer + updated .scout/ knowledge base
scout ships two ways from this one repo — pick whichever fits your setup.
Installs the skill plus the /scout:* slash commands and the fan-out agents.
Run these one at a time — enter the first, press Enter and let it finish, then run the second (copying both at once feeds the second line into the marketplace prompt):
/plugin marketplace add pur4v/scout
/plugin install scout
Then use the commands directly:
/scout:map onboard me to this workspace
/scout:walkthrough [core|standard|detailed|deep] walk me through the code
/scout:trace how is <X> fetched?
/scout:verify fact-check <paste analysis>
/scout:audit find committed secrets
/scout:guide [newcomer|engineer|expert] one file to learn the whole repo
Just the skill (no slash commands) — drop it where your Claude tooling looks for skills:
# Personal skill for Claude Code
git clone https://github.com/pur4v/scout /tmp/scout
cp -r /tmp/scout/skills/scout ~/.claude/skills/scoutOr copy skills/scout into a project's .claude/skills/. Once present, Claude invokes it
automatically when a request matches the triggers in SKILL.md, or you can ask for it by name.
scout/
├── .claude-plugin/
│ ├── plugin.json # plugin manifest (commands + agents + skills)
│ └── marketplace.json # so `/plugin marketplace add pur4v/scout` works
├── commands/ # slash commands → /scout:map :walkthrough :trace :verify :audit :guide
├── agents/
│ ├── repo-explorer.md # per-repo fan-out worker
│ └── verifier.md # adversarial refuter for the verify pass
├── skills/scout/ # the skill itself (canonical, installable on its own)
│ ├── SKILL.md # when-to-use, 6 modes, disciplines, workflow
│ ├── reference/ # progressive-disclosure docs, loaded on demand
│ │ ├── mode-map.md mode-walkthrough.md mode-trace.md mode-verify.md mode-audit.md mode-guide.md
│ │ ├── fan-out.md # parallel sub-agent orchestration recipe
│ │ ├── diagrams.md # ASCII + SVG diagram conventions (shared model)
│ │ └── knowledge-base.md
│ ├── scripts/scan_secrets.sh # deterministic first-pass secret scan
│ └── assets/kb-template.md # per-topic knowledge-base note template
└── examples/acmetrends/ # a fully fictional worked example of all four modes
Findings accumulate in the target workspace (a .scout/ folder, or docs/architecture/),
version-controlled next to the code they describe — so re-analysis is incremental and the
map travels with the repo. The skill stays generic; the notes live where the code lives.
See examples/acmetrends/ for a worked run of every mode against a
small, entirely fictional platform (no real systems or secrets).
Issues and PRs welcome — see CONTRIBUTING.md and the Code of Conduct. Security reports: SECURITY.md.
MIT — see LICENSE.