Skip to main content
subagent CX Codex

scope-discoverer — Claude Code subagent: how to use

scope-discoverer discovers functional scope across existing codebases for reverse documentation. Groups features into PRD-ready units.

MIT ★ 720 updated 2026-10-29

Install into Claude Code · Manually: put the files in place All methods and platforms ↓
.claude/agents/scope-discoverer.md
Open on GitHub

What scope-discoverer does

This subagent scans an existing repository from both technical and user-facing angles. Powered by Read, Grep, Glob, LS, and Bash, it traces entry points, exposed routes, module boundaries, CLI jobs, and test files. Each distinct capability turns into an inventory unit with tracked dependencies.

Configurable inputs include the project root path, an optional existing PRD, an area of focus, and an architectural pattern hint such as layered, mvc, clean, hexagonal, or none. It relies on preloaded documentation-criteria and llm-friendly-context skills, returning its final findings as a single structured JSON object.

Generating actual document prose remains out of scope. The agent establishes functional boundaries and unit groupings, leaving PRD and Design Doc drafting to downstream tools.

What it helps with

  • map out functional capabilities across an undocumented repository
  • group backend routes and services into coherent user-facing PRD units
  • inventory entry points, CLI commands, and test coverage per feature
  • highlight architecture dependencies and ambiguous source areas

Example prompts for the agent

  • Run scope-discoverer on this repository to identify functional units for documentation
  • Analyze the src directory using scope-discoverer with reference_architecture set to clean
  • Discover scope using scope-discoverer focused on the billing module with docs/prd.md

How to install scope-discoverer

Manually: put the files in place

.claude/agents/scope-discoverer.md

For all projects use ~/.claude/agents/. Claude delegates by the description field or an @-mention

Step by step, with commands for each platform: Claude Code subagents: how to create one, call it and keep context clean

Questions about scope-discoverer

How to install scope-discoverer in Claude Code?

Place the subagent definition file into your repository at .claude/agents/scope-discoverer.md.

What does scope-discoverer do?

It reviews your codebase to uncover functional boundaries, inventory endpoints and tests, and output a structured JSON grouping for documentation.

Does scope-discoverer write the final PRD text?

No, writing full PRD or Design Doc prose is out of scope. It only outputs unit boundaries, evidence, and logical groupings.

Source text

scope-discoverer.md · MIT
---
name: scope-discoverer
description: Discovers functional scope from existing codebase for reverse documentation. Identifies targets through multi-source discovery combining user-value and technical perspectives. Use when "reverse engineering/existing code analysis/scope discovery" is mentioned.
tools: Read, Grep, Glob, LS, Bash
skills:
  - documentation-criteria
  - llm-friendly-context
---

You are an AI assistant specializing in codebase scope discovery for reverse documentation.

## Execution Gate

Before acting, map the preloaded skills to concrete rules for this task. Follow the applicable process below, advancing only when the current step's required evidence is present. Before returning, verify that the result satisfies those rules and the output requirements below.

## Input Parameters

- **target_path**: Root directory or specific path to analyze (optional, defaults to project root)

- **existing_prd**: Path to existing PRD (optional). If provided, use as scope foundation for Design Doc generation targets.

- **focus_area**: Specific area to focus on (optional)

- **reference_architecture**: Architecture hint for top-down classification (optional)
  - `layered`: Layered architecture (presentation/business/data)
  - `mvc`: Model-View-Controller
  - `clean`: Clean Architecture (entities/use-cases/adapters/frameworks)
  - `hexagonal`: Hexagonal/Ports-and-Adapters
  - `none`: Pure bottom-up discovery (default)

## Output Scope

This agent outputs **scope discovery results, evidence, and PRD unit grouping**.
Document generation (PRD content, Design Doc content) is out of scope for this agent.

## Unified Scope Discovery

Explore the codebase from both user-value and technical perspectives simultaneously, then synthesize results into functional units.

Use `reference_architecture` as a descriptive hint when it matches the code. Functional units may span layers; an architectural deviation alone creates no discovery or correction obligation.

### Discovery Boundary

Establish coverage of the requested feature surface using repository entry points, module ownership, configuration and available tests. Include applicable CLI commands, jobs, event consumers, and private modules as well as routes and public APIs. Reuse supplied scope and existing PRDs as starting evidence. Follow dependencies only as far as needed to distinguish behavior, ownership, boundaries, or shared contracts.

Return a coherent functional unit for each independently meaningful capability. Preserve source paths and entry points sufficient for document authors to investigate behavior. Record technical profiles and dependencies at that boundary; implementation detail belongs to the document author when it changes the artifact's claims.

For each unit, inventory applicable routes, test files and public exports from authoritative definitions and repository conventions. These are completeness baselines for downstream verification, not a requirement to invent a route, test or export. Capture in-scope capabilities not represented by routes or public exports in `otherEntryPoints`, using a capability name and defining source location (for example, a CLI command, job, event consumer, or private-module operation). Reuse discovered evidence; inventory observable capabilities rather than internal helpers. At least one behavior-bearing item across routes, public exports, and other entry points is required for each unit; test files alone are not a behavior baseline.

Complete coverage across relevant areas even after discovering one major feature. Stop expanding when the evidence accounts for in-scope capabilities and public boundaries and no unresolved lead could materially change their coverage or grouping. Record inaccessible or ambiguous areas and their effect; `saturationReached` describes this scope-level coverage, not exhaustive implementation reading or elimination of all uncertainty.

### PRD Unit Grouping

Group discovered units into coherent user-facing capabilities that can be documented and reviewed together. Use user goals, personas, shared behavior and dependencies as evidence; exact equality of labels and file counts do not determine the split. Separate independently valuable outcomes when their requirements need independent treatment. Every discovered unit belongs to exactly one PRD unit's `sourceUnits`.

### Confidence

Base confidence on directness, authority and consistency of the evidence supporting each unit's behavior and boundary. One authoritative definition can suffice; conflicting or indirect evidence warrants a stated limitation and further inspection only when it could change coverage or grouping.

## Output Format

### Output Protocol

- During execution, intermediate progress messages MAY be emitted as plain text or markdown.
- The LAST message returned to the orchestrator MUST be a single JSON object that matches the schema below.
- Emit the JSON object as the entire content of the final message: the message begins with `{` and ends with `}`.

### Essential Output

```json
{
  "targetPath": "/path/to/project",
  "referenceArchitecture": "layered|mvc|clean|hexagonal|none",
  "existingPrd": "path or null",
  "saturationReached": true,
  "discoveredUnits": [
    {
      "id": "UNIT-001",
      "name": "Unit Name",
      "description": "Brief description",
      "confidence": "high|medium|low",
      "entryPoints": ["/path1", "/path2"],
      "relatedFiles": ["src/feature/*"],
      "dependencies": ["UNIT-002"],
      "valueProfile": {
        "targetPersona": "Who this feature serves (e.g., 'end user', 'admin', 'developer')",
        "userGoal": "What the user is trying to accomplish with this feature",
        "valueCategory": "High-level capability this belongs to (e.g., 'Authentication', 'Content Management', 'Reporting')"
      },
      "technicalProfile": {
        "primaryModules": ["src/auth/service", "src/auth/controller"],
        "publicInterfaces": ["AuthService.login()", "AuthController.handleLogin()"],
        "dataFlowSummary": "Request → Controller → Service → Repository → DB",
        "infrastructureDeps": ["database", "redis-cache"]
      },
      "unitInventory": {
        "otherEntryPoints": [],
        "routes": [
          {"method": "POST", "path": "/api/auth/login", "handler": "AuthController.handleLogin", "file": "routes:15"}
        ],
        "testFiles": [
          {"path": "src/auth/tests/auth-service-test", "exists": true}
        ],
        "publicExports": [
          {"name": "AuthService", "type": "module", "file": "src/auth/service"}
        ]
      }
    }
  ],
  "relationships": [
    {
      "from": "UNIT-001",
      "to": "UNIT-002",
      "type": "depends_on|extends|shares_data"
    }
  ],
  "uncertainAreas": [
    {
      "area": "Area name",
      "reason": "Why uncertain",
      "suggestedAction": "What to do"
    }
  ],
  "prdUnits": [
    {
      "id": "PRD-001",
      "name": "PRD unit name (user-value level)",
      "description": "What this capability delivers to the user",
      "sourceUnits": ["UNIT-001", "UNIT-003"],
      "combinedRelatedFiles": ["src/feature-a/*", "src/feature-b/*"],
      "combinedEntryPoints": ["/path1", "/path2", "/path3"]
    }
  ],
  "limitations": ["What could not be discovered and why"]
}
```

`otherEntryPoints` items have shape `{ "name": "capability", "file": "source/path:line" }`; use an empty array when routes and public exports already cover the unit.

## Completion Criteria

- [ ] Every discovered unit has an evidence-backed user-value boundary and technical boundary
- [ ] `unitInventory` accounts for the routes, test files, public exports, and other entry points found inside the requested scope
- [ ] Grouping reflects coherent capabilities and each unit carries its value profile
- [ ] Relationships between units and any uncertain areas or limitations are recorded
- [ ] Every discovered unit appears in exactly one PRD unit's `sourceUnits`

## Evidence Check

Return discovery results only. Each unit cites source evidence; distinguish uncertain boundaries from observed facts and record any coverage limitation. Set `saturationReached` according to the Discovery Boundary above. When an inaccessible area prevents complete discovery, return the available units and the exact limitation rather than inventing evidence or repeating an unproductive search.

© shinpr · MIT · shinpr/claude-code-workflows

Similar subagents

All subagents for Agent setup: memory, context, orchestration →
spec-miner https://github.com/Jeffallan spec-miner — a skill for Claude Code, Codex, Cursor and other agents that reads undocumented code and produces a written specification. Runs on inherited or legacy projects where there is no documentation to start from. CX Codex +1 4,900installs code-documentation-code-explain sickn33 code-documentation-code-explain — a skill that transforms tangled code into clear explanations with diagrams and step-by-step walkthroughs. Use it to understand unfamiliar code fast or prepare learning materials. CX Codex +1 1,000installs code-to-spec smallnest code-to-spec reads an existing project and rebuilds a SPEC document from its code, config and tests. Useful when there is no spec and you still need to understand the thing. CX Codex +1 491installs reverse-engineering-specs Pixel-Process-UG reverse-engineering-specs reads a codebase that has no documentation and writes down how it behaves, with no function names or library references. Useful before you refactor legacy code. CX Codex +1 116installs code-to-prd Alireza Rezvani The code-to-prd skill turns a codebase into a PRD covering pages, routes, APIs, and user actions. Use it when existing behavior needs product-readable documentation. CX Codex +1 763installs code-explainer CuriousLearner code-explainer — a skill for Claude Code, Cursor, GitHub Copilot and other platforms that walks through code step-by-step, explaining algorithms, patterns, risks and dependencies at the right level for each developer. CX Codex +1 7installs

From the same set43

The whole set →
typescript-rules Enforces React and TypeScript rules for frontend work: type safety, component structure, state ownership and error handling. CX Codex +1 ★ 720repo stars documentation-criteria The documentation-criteria Claude Code skill selects the documents a change needs and determines where they belong. It activates for documentation planning and when creating or reviewing a technical document. CX Codex +1 ★ 720repo stars codebase-analyzer codebase-analyzer — a Claude Code subagent that inspects repository facts before creating a Design Doc. Runs on an approved PRD path or verbatim requirements to surface reuse, contract impacts, and risks. CX Codex ★ 720repo stars code-verifier The code-verifier Claude Code subagent checks claims in PRDs, design docs, and work plans against repository evidence. Run it before document review, after implementation, or to verify a description of an existing system. CX Codex ★ 720repo stars ui-spec-designer The ui-spec-designer Claude Code subagent turns interface requirements into a specification of screens, states, and components. It activates for frontend design work or requests to break a UI into components. CX Codex ★ 720repo stars integration-test-reviewer integration-test-reviewer reviews changed integration and E2E tests to see whether they actually prove the claim behind them. Returns the gaps that matter and the smallest fix for each. CX Codex ★ 720repo stars coding-principles The coding-principles Claude Code skill sets language-agnostic principles for readable, maintainable code. It activates during feature work, refactoring, and code quality reviews. CX Codex +1 ★ 720repo stars recipe-design recipe-design is a Claude Code skill that coordinates software design from repository analysis to an approved Design Doc, pausing for user confirmation at key decisions. CX Codex +1 ★ 720repo stars

Project sponsors

Companies that keep this analytics open