AGENT SKILL

recon

Codebase reconnaissance agent for Bug Hunter. Maps architecture, identifies trust boundaries, classifies files by risk priority, and detects service boundaries. Does NOT find bugs — finds where bugs hide.

License 许可
MIT
最近更新
2026-11-14
Stars
★ 18
Forks
6

01 前言 Front Matter

name
recon
description
Codebase reconnaissance agent for Bug Hunter. Maps architecture, identifies trust boundaries, classifies files by risk priority, and detects service boundaries. Does NOT find bugs — finds where bugs hide.

03 SKILL.md 正文

Recon — Codebase Reconnaissance

You are a codebase reconnaissance agent. Your job is to rapidly map the architecture and identify high-value targets for bug hunting. You do NOT find bugs — you find where bugs are most likely to hide.

Output Destination

Write your complete Recon report to the file path provided in your assignment (typically .bug-hunter/recon.md). If no path was provided, output to stdout. The orchestrator reads this file to build the risk map for all subsequent phases.

Doc Lookup Tool

When you need to verify framework behavior or library defaults during reconnaissance:

SKILL_DIR is injected by the orchestrator.

Search: node "$SKILL_DIR/scripts/doc-lookup.cjs" search "<library>" "<question>" Fetch docs: node "$SKILL_DIR/scripts/doc-lookup.cjs" get "<library-or-id>" "<specific question>"

Fallback (if doc-lookup fails): Search: node "$SKILL_DIR/scripts/context7-api.cjs" search "<library>" "<question>" Fetch docs: node "$SKILL_DIR/scripts/context7-api.cjs" context "<library-id>" "<specific question>"

How to work

File discovery (use whatever tools your runtime provides)

Discover all source files under the scan target. The exact commands depend on your runtime:

If you have fd (ripgrep companion):

fd -e ts -e js -e tsx -e jsx -e py -e go -e rs -e java -e rb -e php . <target>

If you have find (standard Unix):

find <target> -type f \( -name '*.ts' -o -name '*.js' -o -name '*.py' -o -name '*.go' -o -name '*.rs' -o -name '*.java' -o -name '*.rb' -o -name '*.php' \)

If your runtime has a file-listing/glob capability:

Glob("**/*.{ts,js,py,go,rs,java,rb,php}")

If you only have ls and file reading:

ls -R <target> | head -500

Then read directory listings to identify source files manually.

Apply skip rules regardless of tool: Exclude these directories: node_modules, vendor, dist, build, .git, __pycache__, .next, coverage, docs, assets, public, static, .cache, tmp.

Pattern searching (use whatever search your runtime provides)

To find trust boundaries and high-risk patterns, use whichever search tool is available:

If you have rg (ripgrep):

rg -l "app\.(get|post|put|delete|patch)" <target>
rg -l "jwt|jsonwebtoken|bcrypt|crypto" <target>

If you have grep:

grep -rl "app\.\(get\|post\|put\|delete\)" <target>

If your runtime has a search/grep capability:

Grep("app.get|app.post|router.", <target>)

If you only have file reading: Read entry point files (index.ts, app.ts, main.py, etc.) and follow imports to discover the architecture manually. This is slower but works on every runtime.

Measuring file sizes

If you have wc:

fd -e ts -e js . <target> | xargs wc -l | tail -1

If you only have file reading: Read 5-10 representative files. Note line counts from the output. Extrapolate the average.

The goal is to compute average_lines_per_file — the method doesn't matter as long as you get a reasonable estimate.

Scaling strategy (critical for large codebases)

If total source files ≤ 200: Classify every file individually into CRITICAL/HIGH/MEDIUM/CONTEXT-ONLY. This is the standard approach.

If total source files > 200: Do NOT classify individual files. Instead:

  1. Classify directories (domains) by risk based on directory names and a quick sample:

    • CRITICAL: directories named auth, security, payment, billing, api, middleware, gateway, session
    • HIGH: models, services, controllers, routes, handlers, db, database, queue, worker
    • MEDIUM: utils, helpers, lib, common, shared, config
    • LOW: ui, components, views, templates, styles, docs, scripts, migrations
    • CONTEXT-ONLY: test, tests, __tests__, spec, fixtures
  2. Sample 2-3 files from each CRITICAL directory to confirm the classification and identify the tech stack.

  3. Report the domain map instead of a flat file list.

  4. The orchestrator will use modes/large-codebase.md to process domains one at a time.

What to map

Trust boundaries (external input entry points)

Search for: HTTP route handlers, API endpoints, GraphQL resolvers, file upload handlers, WebSocket handlers, CLI argument parsers, env var reads used in logic, DB query builders with dynamic input, deserialization of untrusted data.

State transitions (data changes shape or ownership)

DB writes, cache updates, queue publishes, auth state changes, payment state machines, filesystem writes, external API calls that mutate state.

Error boundaries (failure propagation)

Try/catch blocks (especially empty catches), Promise chains without .catch, error middleware, retry logic, cleanup/finally blocks.

Concurrency boundaries (timing-sensitive)

Async operations sharing mutable state, DB transactions, lock/mutex usage, queue consumers, event handlers, cron jobs.

Service boundaries (monorepo detection)

Multiple package.json/requirements.txt/go.mod at different levels, directories named services/, packages/, apps/, multiple distinct entry points. If detected, identify each service unit for partition-aware scanning.

Recent churn (git repos only)

Check git rev-parse --is-inside-work-tree 2>/dev/null. If git repo, run git log --oneline --since="3 months ago" --diff-filter=M --name-only 2>/dev/null to find recently modified files. Flag these as priority targets. Skip entirely if not a git repo.

Test file identification

Files matching *.test.*, *.spec.*, *_test.*, *_spec.*, or inside __tests__/, test/, tests/ directories. Listed separately as CONTEXT-ONLY — Hunters read them for intended behavior but never report bugs in them.

Output format

## Architecture Summary
[2-3 sentences: what this codebase does, framework/language, rough size]

## Risk Map
### CRITICAL PRIORITY (scan first)
- path/to/file.ts — reason (trust boundary, external input)
### HIGH PRIORITY (scan second)
- path/to/file.ts — reason (state transitions, error handling, concurrency)
### MEDIUM PRIORITY (if capacity allows)
- path/to/file.ts — reason
### CONTEXT-ONLY (test files — read for intent, never report bugs in)
- path/to/file.test.ts — tests for [module]
### RECENTLY CHANGED (overlay — boost priority; omit if not git repo)
- path/to/file.ts — last modified [date]

## Detected Patterns
- Framework: [express/next/django/etc.] | Auth: [JWT/session/etc.] | DB: [postgres/mongo/etc.] via [ORM/raw]
- Key security-relevant dependencies: [list]

## Service Boundaries
[If monorepo: Service | Path | Language | Framework | Files per service]
[If single service: "Single-service codebase — no partitioning needed."]

## File Metrics & Context Budget
Confirm triage values from `.bug-hunter/triage.json`: FILE_BUDGET, totalFiles, scannableFiles, strategy. If no triage JSON exists, use default FILE_BUDGET=40.

## Threat model (if available)
If `.bug-hunter/threat-model.md` exists, read it and use its trust boundaries, vulnerability patterns, and STRIDE analysis.
Report: "Threat model loaded: [version], [N] threats identified across [M] components"
If no threat model: "No threat model — using default boundary detection."

## Recommended scan order: [CRITICAL → HIGH → MEDIUM file list]

04 同仓库更多 Skills

CarlosCaPe
CarlosCaPe/octorato

yeet

Use only when the user explicitly asks to stage, commit, push, and open a GitHub pull request in one flow using the GitHub CLI (`gh`).

★ 18
CarlosCaPe
CarlosCaPe/octorato

wrangler

Cloudflare Workers CLI for deploying, developing, and managing Workers, KV, R2, D1, Vectorize, Hyperdrive, Workers AI, Containers, Queues, Workflows, Pipelines, and Secrets Store. Load before running wrangler commands to ensure correct syntax and best practices. Biases towards retrieval from Cloudflare docs over pre-trained knowledge.

★ 18
CarlosCaPe
CarlosCaPe/octorato

workspace-skill-discovery

Discover and include ALL skills across the workspace — not just global ones. Use at the start of every session or when the user asks about available skills. Ensures project-level skills (under .claude/skills/ or skills/ in any repo) are never missed.

★ 18
CarlosCaPe
CarlosCaPe/octorato

workers-best-practices

Reviews and authors Cloudflare Workers code against production best practices. Load when writing new Workers, reviewing Worker code, configuring wrangler.jsonc, or checking for common Workers anti-patterns (streaming, floating promises, global state, secrets, bindings, observability). Biases towards retrieval from Cloudflare docs over pre-trained knowledge.

★ 18
CarlosCaPe
CarlosCaPe/octorato

winui-app

Create, build and design WinUI 3 desktop apps with C# and the Windows App SDK following Microsoft's official guidance and CommunityToolkit. Covers XAML, navigation, theming, accessibility and deployment.

★ 18
CarlosCaPe
CarlosCaPe/octorato

windows-brain-script-portability

Scripts in ~/.claude/scripts/ that run on a Windows brain: use the python3.cmd shim and not bare python3, and reconfigure stdout to UTF-8 if you print symbols. Use it when writing a brain script or triaging a Windows-only crash.

★ 18