# Orc Scout

> Phase-scoped codebase discovery and cross-phase context bridge.

- **Type:** Skill
- **Install:** `agentstack add skill-qgolem-orc-orc-scout`
- **Verified:** Yes — security-reviewed for prompt injection and unsafe behavior
- **Seller:** [qGolem](https://agentstack.voostack.com/s/qgolem)
- **Installs:** 0
- **Category:** [Agent Skills](https://agentstack.voostack.com/c/agent-skills)
- **Latest version:** 0.1.0
- **License:** MIT
- **Upstream author:** [qGolem](https://github.com/qGolem)
- **Source:** https://github.com/qGolem/orc/tree/main/skills/orc-scout

## Install

```sh
agentstack add skill-qgolem-orc-orc-scout
```

Requires the [AgentStack CLI](https://agentstack.voostack.com/docs/cli). Works with Claude Code, Cursor, and any MCP-compatible agent.

## About

# 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](https://github.com/qGolem)
- **Source:** [qGolem/orc](https://github.com/qGolem/orc)
- **License:** MIT

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

## Pricing

- **Free** — Free

## Security capabilities

Automated source analysis of v0.1.0 — what this tool can access:

- **Network access:** no
- **Filesystem access:** no
- **Shell / process execution:** no
- **Environment & secrets:** no
- **Dynamic code execution:** no

*"Yes" means the capability is present in the source — more access means more to trust, not that it is unsafe.*


## Versions

- **0.1.0** — security scan: passed — Imported from the upstream source.

## Links

- Listing page: https://agentstack.voostack.com/l/skill-qgolem-orc-orc-scout
- Seller: https://agentstack.voostack.com/s/qgolem
- Browse the marketplace: https://agentstack.voostack.com/browse

---
Listed on AgentStack — the marketplace for AI agent skills and MCP servers. Every listing is security-reviewed. Creators keep 70%.