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](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
• `` 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)

For each prior phase:

• Extract deliverables and key files modified
• Identify files that overlap with current phase targets
• Note patterns established by prior phases

Step 7: Write SCOUT.md

Write .claude/plans/{slug}/phases/0{N}-{name}/SCOUT.md using the template.

Fill all sections. For phase 1, omit the "Prior Phases" section.

Constraint

Cannot use AskUserQuestion — forked context is non-interactive.

Completion Criteria

• [ ] All target files from PLAN.md analyzed (existence, size, imports, importers, tests)
• [ ] madge --depends run on key files
• [ ] tree run on target directories
• [ ] Conventions documented with file:line references
• [ ] Cross-phase context included (if phase > 1)
• [ ] SCOUT.md written to phase directory

Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: qGolem
• Source: qGolem/orc
• License: MIT

Install and usage instructions live in the source repository linked above.