orc-scout

Orc Scout

Phase-scoped codebase discovery that runs forked (non-interactive). Explores files referenced in PLAN.md and their surrounding code. For phases > 1, reads prior phase artifacts for cross-phase awareness.

Input

• $ARGUMENTS — {slug} {phase-num} (e.g., my-feature 2)

Template

See templates/SCOUT.md for output format.

Process

Step 1: Parse Arguments and Locate Phase

slug = first word of $ARGUMENTS
phase_num = second word of $ARGUMENTS

Find phase directory:

Glob .claude/plans/{slug}/phases/0{phase_num}-*/PLAN.md

Read the matched PLAN.md.

Step 2: Extract Target Files

From PLAN.md, collect all target files:

• files_modified from frontmatter
• must_haves.artifacts paths
• <files> sections from each task

Deduplicate into a single list.

Step 3: Analyze Each Target File

For each target file:

Existence & size:

Glob for the file path
Bash: wc -l {file}

Imports (what it depends on):

Grep: import.*from in the file

Imported by (what depends on it):

Grep: import.*{filename} across src/

Related tests:

Glob: **/{basename}.test.* and **/{basename}.spec.*

Dependency graph:

Bash: madge --depends {file}

Step 4: Analyze Target Directories

For each unique directory containing target files:

Bash: tree -L 2 -P '*.ts' {target-dir}

Step 5: Discover Conventions

From the target files and their neighbors, document:

• Naming conventions (files, exports, variables)
• Error handling patterns
• Testing patterns (framework, mocking, location)
• Import organization

Include file:line references for each convention.

Step 6: Cross-Phase Context (phase > 1 only)

If phase_num > 1, read prior phase artifacts:

Glob .claude/plans/{slug}/phases/0{prior}-*/PROGRESS-*.md  → Read each match
Glob .claude/plans/{slug}/phases/0{prior}-*/SUMMARY-*.md   → Read each match
Glob .claude/plans/{slug}/phases/0{prior}-*/IMPL-VERIFICATION.md  → Read if exists

Fallback: If PROGRESS-*.md not found, try reading PROGRESS.md (single-executor phases)
Fallback: If SUMMARY-*.md not found, try reading SUMMARY.md (single-executor phases)