scout

name	scout
description	Codebase reconnaissance and exploration -- map structure, find patterns, understand architecture
layer	hub
category	workflow
triggers	["/scout","explore the codebase","what does this codebase look like","map the architecture","find where X is","how is this structured"]
inputs	[{"target":"What to explore -- a directory, feature, pattern, or question about the codebase"},{"depth":"How deep to go -- surface (structure only), standard (structure + key files), deep (full analysis)"}]
outputs	[{"architectureMap":"High-level structure and relationships between components"},{"fileIndex":"Relevant files categorized by purpose"},{"patterns":"Detected coding patterns, conventions, and architectural decisions"},{"entryPoints":"Key files to read for understanding a feature or subsystem"},{"techStack":"Detected technologies, frameworks, and tools"}]
linksTo	["research","debug","code-review"]
linkedFrom	["plan","cook","team","ship","refactor","optimize","debug"]
preferredNextSkills	["plan","code-review","debug"]
fallbackSkills	["research"]
riskLevel	low
memoryReadPolicy	selective
memoryWritePolicy	selective
sideEffects	["Reads many files (may be slow on very large codebases)","Produces architecture map in working memory"]

Scout Skill

Purpose

Perform systematic codebase reconnaissance to answer questions about structure, conventions, patterns, and architecture. Scout is the eyes and ears of the agent system -- it goes in first and reports back what it finds so that other skills (plan, debug, refactor, etc.) can make informed decisions.

Scout does not change code. It reads, maps, and reports.

Workflow

Mode 1: Full Reconnaissance (default for new codebases)

1. Project structure scan

   • List top-level directories and files
   • Identify project type (monorepo, single app, library, etc.)
   • Read configuration files: package.json, tsconfig.json, Cargo.toml, pyproject.toml, .env.example, etc.
   • Identify build tools, test frameworks, and CI/CD configuration

2. Tech stack identification

   • Framework(s) and version(s)
   • Language(s) and version(s)
   • Database(s) and ORM(s)
   • Key dependencies (UI libraries, state management, API clients)
   • Dev tooling (linters, formatters, type checkers)

3. Architecture mapping

   • Identify architectural pattern (MVC, hexagonal, feature-sliced, etc.)
   • Map directory structure to responsibilities
   • Identify shared/common code locations
   • Find the entry points (main files, route definitions, API handlers)
   • Map data flow: where does data come from, how does it transform, where does it go?

4. Convention detection

   • Naming conventions (files, functions, components, variables)
   • File organization patterns (co-location, separation by type, feature folders)
   • Import patterns (barrel files, direct imports, path aliases)
   • Error handling patterns
   • Testing conventions (test file location, naming, framework)

5. Produce the reconnaissance report using the template below.

Mode 2: Targeted Exploration (for specific questions)

1. Parse the question -- What specifically is the user looking for?

   • A feature: "Where is authentication handled?"
   • A pattern: "How does this project handle errors?"
   • A file/function: "Where is the user model defined?"