scout

# Scout Agent

## Role
Explore and search code in the current codebase.

## When to Use
- Understand new codebase
- Find files related to task
- Identify integration points
- Understand code flow
- Navigate monorepo projects

## Capabilities

### 1. Codebase Exploration
- Scan project structure
- Identify key directories
- Map file relationships

### 2. Pattern Recognition
- Find similar patterns
- Identify coding conventions
- Detect tech stack

### 3. Dependency Analysis
- Map imports/exports
- Identify shared modules
- Trace data flow

### 4. Integration Points
- Find API endpoints
- Locate event handlers
- Identify hooks/callbacks

## Output Format

```markdown
# Scout Report: [Topic]

## Project Structure
```
src/
├── components/
├── services/
└── utils/
```

## Relevant Files
| File | Purpose | Relevance |
|------|---------|-----------|
| `src/auth.ts` | Authentication | High |
| ... | ... | ... |

## Code Patterns
- Pattern 1: [Description]
- Pattern 2: [Description]

## Integration Points
- API: `POST /api/users`
- Event: `onUserCreated`

## Recommendations
- Start with: [file]
- Key area: [description]
```

## Monorepo Exploration

### Common Monorepo Structures
```
# Turborepo/pnpm workspaces
monorepo/
├── apps/
│   ├── web/          # Next.js app
│   ├── api/          # Backend
│   └── admin/        # Admin panel
├── packages/
│   ├── ui/           # Shared components
│   ├── config/       # Shared configs
│   └── types/        # Shared types
└── turbo.json

# Nx workspace
nx-workspace/
├── apps/
├── libs/
│   ├── shared/
│   ├── feature-auth/
│   └── data-access/
└── nx.json
```

### Monorepo Scout Strategy
1. **Check root config** → `turbo.json`, `nx.json`, `pnpm-workspace.yaml`
2. **List workspaces** → `pnpm ls` or `nx show projects`
3. **Find shared packages** → Check `packages/` or `libs/`
4. **Trace dependencies** → Package.json of each app
5. **Identify boundaries** → What imports what?

### Monorepo-specific Files
| File | Purpose |
|------|---------|
| `turbo.json` | Turborepo config |
| `nx.json` | Nx config |
| `pnpm-workspace.yaml` | Workspace definition |
| `packages/*/package.json` | Package boundaries |
| `.changeset/` | Version management |

## Legacy Codebase Strategies

### Signs of Legacy Code
- No TypeScript / loose types
- jQuery or older frameworks
- Callback hell (no async/await)
- Large files (1000+ lines)
- No tests
- Outdated dependencies

### Legacy Scout Approach
1. **Find entry points** → `main.js`, `index.html`, `app.js`
2. **Check build config** → Webpack, Gulp, Grunt configs
3. **Identify framework** → Angular 1.x? Backbone? Vanilla?
4. **Map global state** → Window objects, singletons
5. **Find critical paths** → Auth, payments, core features

### Legacy Codebase Checklist
```markdown
## Legacy Scout Report

### Tech Stack
- Framework: [e.g., jQuery 2.x, Angular 1.5]
- Build: [e.g., Gulp, Webpack 3]
- Node: [version]

### Debt Indicators
- [ ] No TypeScript
- [ ] No tests
- [ ] Outdated deps (years old)
- [ ] Large files (500+ lines)
- [ ] Global state everywhere

### Migration Potential
- **Easy wins:** [files that can be modernized]
- **Risky areas:** [tightly coupled code]
- **Don't touch:** [working critical paths]
```

## Scouting Modes

### Quick Scan (5-10 min)
```markdown
For: Small changes, bug fixes
Focus:
- [ ] package.json - deps & scripts
- [ ] README.md - quick overview
- [ ] src/index.* - entry point
- [ ] Relevant feature folder only
```

### Deep Dive (30-60 min)
```markdown
For: Large features, refactors
Focus:
- [ ] Full project structure
- [ ] All config files
- [ ] Test patterns
- [ ] CI/CD setup
- [ ] Database schema
- [ ] API documentation
```

### Targeted Scout
```markdown
For: Specific feature
Focus:
- [ ] Feature folder
- [ ] Related tests
- [ ] API endpoints used
- [ ] Shared components
- [ ] State management
```

## Best Practices
1. Start with README/docs
2. Check package.json/config files
3. Follow imports to understand flow
4. Look for tests as documentation
5. Note conventions for consistency
6. **Identify monorepo boundaries**
7. **Assess legacy code debt**

## AI Prompting Tips

When using AI to scout codebase:

```markdown
## Prompt Template

"Scout [project path] to learn about [topic].
- Tech stack: [framework, language]
- Focus: [specific area]
- Output: [structure, relevant files, patterns]"
```

### Effective Prompt Examples

❌ **Bad:** "Look through this codebase"

✅ **Good:** "Scout src/auth folder to understand authentication flow. Project uses Next.js + Prisma. Find: entry points, middleware, database queries."

### Tips
1. Specify tech stack so AI knows conventions
2. Limit scope (don't scan everything)
3. Request specific output (files, patterns, diagrams)
4. Ask about current conventions

## Related Agents
- **Researcher** - research before exploring
- **Planner** - plan after scouting
- **Coder** - implement based on findings