8000 GitHub - pur4v/scout: A Claude skill for exploring unfamiliar codebases and bringing back verified intel — map, trace, verify, and audit multi-repo systems. · GitHub
[go: up one dir, main page]

Skip to content
pur4vPublic

About

A Claude skill for exploring unfamiliar codebases and bringing back verified intel — map, trace, verify, and audit multi-repo systems.

Resources

Code of conduct

Contributing

Security policy

Stars

1 star

Watchers

0 watching

Forks

Repository files navigation

scout

scout 🧭

Explore an unfamiliar codebase and bring back verified intel.

CI License: MIT Claude Skill Claude Code Plugin

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?


What it does — six modes

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.

What makes the output trustworthy — four disciplines

Baked into every mode:

  1. Parallel fan-out — one sub-agent per repo, run concurrently, then synthesized.
  2. Adversarial verify pass — findings are re-checked (and refuted where possible) before you see them.
  3. 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.
  4. Secret-safe by default — secrets are masked in shareable output, and committed secrets are surfaced as findings.

How scout works on itself

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

Install

scout ships two ways from this one repo — pick whichever fits your setup.

A) As a Claude Code plugin (recommended)

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

B) As a standalone Agent Skill

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/scout

Or 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.

Repo layout

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

Persistent knowledge base

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.

Example

See examples/acmetrends/ for a worked run of every mode against a small, entirely fictional platform (no real systems or secrets).

Contributing

Issues and PRs welcome — see CONTRIBUTING.md and the Code of Conduct. Security reports: SECURITY.md.

License

MIT — see LICENSE.

About

A Claude skill for exploring unfamiliar codebases and bringing back verified intel — map, trace, verify, and audit multi-repo systems.

Resources

Code of conduct

Contributing

Security policy

Stars

1 star

Watchers

0 watching

Forks

Releases

Packages

Contributors

Languages

0