Map

Analyze existing codebase using mapper agents deployed in 4 waves to produce structured codebase documents.

Each wave builds on prior waves — later agents read earlier documents instead of re-exploring the same ground. This eliminates duplication and produces focused, non-overlapping output.

Output: .claude/context/ folder with 16 structured documents, each ≤200 lines.

Why waves: Parallel-only deployment causes agents to independently discover the same structure, stack, and patterns — producing 3-4 files that overlap on architecture, naming, validation, etc. Waves let foundation docs (STACK, STRUCTURE) be written first, then referenced by all subsequent agents.

Why ≤200 lines: Documents are reference material loaded into context. Bloated files waste tokens. Prefer tables over prose, examples over explanations. If a topic is covered in another doc, write "See [DOC].md" instead of repeating.

Upstream enrichment: Wave 2+ agents may update prior-wave documents if they discover information that would improve output for later waves. For example, a Wave 2 architecture agent might add entry points it discovered to STRUCTURE.md, or a Wave 3 patterns agent might add a convention it found to CONVENTIONS.md. Append to the relevant section — never delete or rewrite existing content.

Why dedicated mapper agents:

• Fresh context per domain (no token contamination)
• Agents write documents directly (no context transfer back to orchestrator)
• Orchestrator only summarizes what was created (minimal context usage)

Always include file paths: Documents are reference material for Claude when planning/executing. Always include actual file paths formatted with backticks: src/services/user.ts.

$ARGUMENTS: optional prompt to shape the mapping focus (e.g., "focus on the auth layer" or "pay special attention to the API surface")

Target directory: .claude/context/

This command can run:

• Before /orc (brownfield codebases) -- creates codebase map first
• After /orc (greenfield codebases) -- updates codebase map as code evolves
• Anytime to refresh codebase understanding

Use orc-map for:

• Brownfield projects before planning (understand existing code first)
• Refreshing codebase map after significant changes
• Onboarding to an unfamiliar codebase
• Before major refactoring (understand current state)

Skip orc-map for:

• Greenfield projects with no code yet (nothing to map)
• Trivial codebases (

Step 1: Check existing maps

ls -la .claude/context/ 2>/dev/null && echo "has_maps=true" || echo "has_maps=false"

If context/ already exists:

Present options:

AskUserQuestion:
  header: "Existing"
  question: ".claude/context/ already exists. What should we do?"
  options:
    - label: "Refresh"
      description: "Delete existing and remap codebase"
    - label: "Skip"
      description: "Use existing codebase map as-is"

If "Refresh": Delete context/, continue to step 2 If "Skip": Exit workflow

If doesn't exist: Continue to step 2.

---

Step 2: Create directory structure

mkdir -p .claude/context

Expected output files (16 documents across 4 waves):

Wave 1 — Foundation:

• STACK.md, STRUCTURE.md, HISTORY.md

Wave 2 — Architecture & Conventions:

• ARCHITECTURE.md, CONVENTIONS.md, INTEGRATIONS.md, REPO.md

Wave 3 — Deep Analysis:

• PATTERNS.md, TYPES.md, TESTING.md, CODEMAP.md, UX-PATTERNS.md

Wave 4 — Cross-Cutting:

• BOUNDARIES.md, FLOWS.md, CONCERNS.md, TEST-QUALITY.md

---

Step 3a: Wave 1 — Foundation (3 parallel agents)

These are discovery agents with no prior context. They establish the facts that all later waves reference.

If $ARGUMENTS contains a prompt, append it to each agent's prompt as a `` block.

Agent 1: Stack

Task(
  subagent_type="orc:orc-codebase-mapper",
  run_in_background=true,
  description="Map codebase tech stack",
  prompt="Focus: tech stack

Analyze this codebase for its technology stack and configuration.

Write to .claude/context/:
- STACK.md (max 150 lines)

Include:
- Languages, runtime versions, package manager
- Frameworks and key dependencies (with versions)
- Build tools, bundlers, task runners
- Environment configuration model (env files, config patterns)
- Dev vs production differences

Use tables for dependency listings. Be concise.

$ARGUMENTS

Explore thoroughly. Write document directly. Return confirmation only."
)

Agent 2: Structure

Task(
  subagent_type="orc:orc-codebase-mapper",
  run_in_background=true,
  description="Map codebase structure",
  prompt="Focus: directory structure

Analyze this codebase's directory layout, key file locations, and naming conventions.

Write to .claude/context/:
- STRUCTURE.md (max 200 lines)

Include:
- Top-level directory layout (tree -L 2 style)
- Purpose of each major directory
- Key file locations: entry points, configs, schemas, routes, models
- File and directory naming conventions (casing, suffixes)
- Path aliases if configured (tsconfig paths, webpack aliases)
- Monorepo structure if applicable (workspaces, packages)

This document is the canonical reference for 'where things are'. All later documents should reference it instead of re-describing directory layout.

$ARGUMENTS

Explore thoroughly. Write document directly. Return confirmation only."
)

Agent 3: History

Task(
  subagent_type="orc:git-history-analyzer",
  run_in_background=true,
  description="Map codebase evolution",
  prompt="Focus: history

Analyze git history to understand code evolution and why current patterns exist.

Write to .claude/context/:
- HISTORY.md (max 120 lines)

Include:
- Major changes timeline (architectural inflection points)
- Contributor domains (who owns what areas)
- Recurring themes in commits
- Hotspot files (most frequently changed)
- Dead code or abandoned features still in the codebase

$ARGUMENTS

Explore thoroughly. Write document directly. Return confirmation only."
)

Wait for Wave 1 to complete before proceeding.

Verify Wave 1 docs exist:

ls -la .claude/context/STACK.md .claude/context/STRUCTURE.md .claude/context/HISTORY.md

---

Step 3b: Wave 2 — Architecture & Conventions (4 parallel agents)

Each agent reads Wave 1 docs to avoid re-describing structure/stack.

Agent 4: Architecture

Task(
  subagent_type="orc:orc-codebase-mapper",
  run_in_background=true,
  description="Map codebase architecture",
  prompt="Focus: architecture

Before exploring, read these documents from prior waves:
- .claude/context/STRUCTURE.md
- .claude/context/STACK.md

These are authoritative. Do NOT re-document their content. Reference them with 'see STRUCTURE.md' or 'see STACK.md' instead.

Write to .claude/context/:
- ARCHITECTURE.md (max 200 lines)

Include:
- Architectural pattern (layered, hexagonal, microservices, etc.)
- Layer definitions and responsibilities
- Data flow between layers (with direction)
- Key abstractions and interfaces
- Dependency injection / wiring strategy
- Error handling strategy (where errors are caught, how they propagate)

DO NOT DOCUMENT:
- Directory layout (see STRUCTURE.md)
- Technology listing (see STACK.md)
- Entry point file paths (see STRUCTURE.md)

UPSTREAM ENRICHMENT: If you discover information that belongs in a prior-wave document (e.g., a missing entry point for STRUCTURE.md, a convention for CONVENTIONS.md), APPEND it to that file under an '## Addendum from [your focus]' heading. Never delete or rewrite existing content.

DEDUPLICATION RULES:
- Maximum 200 lines. Tables over prose, examples over explanations.
- If STRUCTURE.md or STACK.md already covers a topic, write 'See [DOC].md' instead.

$ARGUMENTS

Explore thoroughly. Write document directly. Return confirmation only."
)

Agent 5: Conventions

Task(
  subagent_type="orc:orc-codebase-mapper",
  run_in_background=true,
  description="Map codebase conventions",
  prompt="Focus: coding conventions

Before exploring, read these documents from prior waves:
- .claude/context/STRUCTURE.md
- .claude/context/STACK.md

These are authoritative. Do NOT re-document their content.

Write to .claude/context/:
- CONVENTIONS.md (max 200 lines)

Include:
- Code style (formatting, linting tools, config)
- Naming conventions (variables, functions, classes, files) — only if not in STRUCTURE.md
- Common code patterns (error handling, validation, logging, DI)
- Import ordering and module organization
- Type usage patterns (generics, utility types, branded types)
- Functional vs OOP preferences

DO NOT DOCUMENT:
- File naming conventions (see STRUCTURE.md)
- Framework/tool listing (see STACK.md)

UPSTREAM ENRICHMENT: If you discover information that belongs in a prior-wave document (e.g., a missing entry point for STRUCTURE.md, a convention for CONVENTIONS.md), APPEND it to that file under an '## Addendum from [your focus]' heading. Never delete or rewrite existing content.

DEDUPLICATION RULES:
- Maximum 200 lines. Tables over prose, examples over explanations.
- If STRUCTURE.md or STACK.md already covers a topic, write 'See [DOC].md' instead.

$ARGUMENTS

Explore thoroughly. Write document directly. Return confirmation only."
)

Agent 6: Integrations

Task(
  subagent_type="orc:orc-codebase-mapper",
  run_in_background=true,
  description="Map external integrations",
  prompt="Focus: external integrations

Before exploring, read this document from prior waves:
- .claude/context/STACK.md

This is authoritative. Do NOT re-list frameworks or dependencies already covered there.

Write to .claude/context/:
- INTEGRATIONS.md (max 180 lines)

Include:
- External APIs consumed (endpoints, auth methods, SDKs used)
- Databases (type, ORM/driver, connection config, schema location)
- Auth providers (OAuth, SIWE, JWT, session storage)
- Message queues, caches, blob storage
- Webhooks (inbound and outbound)
- Environment variables required for each integration
- Smart contract interactions (if applicable)

DO NOT DOCUMENT:
- Framework versions or dependency lists (see STACK.md)

UPSTREAM ENRICHMENT: If you discover information that belongs in a prior-wave document (e.g., a missing entry point for STRUCTURE.md, a convention for CONVENTIONS.md), APPEND it to that file under an '## Addendum from [your focus]' heading. Never delete or rewrite existing content.

DEDUPLICATION RULES:
- Maximum 180 lines. Tables over prose.
- If STACK.md already covers a topic, write 'See STACK.md' instead.

$ARGUMENTS

Explore thoroughly. Write document directly. Return confirmation only."
)

Agent 7: Repo

Task(
  subagent_type="orc:repo-research-analyst",
  run_in_background=true,
  description="Map repository conventions",
  prompt="Focus: repository conventions

Before exploring, read this document from prior waves:
- .claude/context/STRUCTURE.md

This is authoritative. Do NOT re-describe directory layout.

Write to .claude/context/:
- REPO.md (max 170 lines)

Include:
- CI/CD setup (.github/, GitLab CI, etc.)
- Contribution guidelines (PR templates, issue templates, CODEOWNERS)
- Branch strategy (main/develop, release branches)
- Commit conventions (conventional commits, signed commits)
- Release process (changelogs, versioning, release tools)
- Documentation conventions (ADR index if applicable, README structure)
- Dev environment setup gotchas

DO NOT DOCUMENT:
- Directory layout (see STRUCTURE.md)
- Test framework details (covered in later wave)
- Package manager or build tools (see STACK.md)

UPSTREAM ENRICHMENT: If you discover information that belongs in a prior-wave document (e.g., a missing entry point for STRUCTURE.md, a convention for CONVENTIONS.md), APPEND it to that file under an '## Addendum from [your focus]' heading. Never delete or rewrite existing content.

DEDUPLICATION RULES:
- Maximum 170 lines. Tables over prose.
- If STRUCTURE.md already covers a topic, write 'See STRUCTURE.md' instead.

$ARGUMENTS

Explore thoroughly. Write document directly. Return confirmation only."
)

Wait for Wave 2 to complete before proceeding.

Verify Wave 2 docs exist:

ls -la .claude/context/ARCHITECTURE.md .claude/context/CONVENTIONS.md .claude/context/INTEGRATIONS.md .claude/context/REPO.md

---

Step 3c: Wave 3 — Deep Analysis (5 parallel agents)

Each agent reads relevant Wave 1+2 docs.

Agent 8: Patterns

Task(
  subagent_type="orc:pattern-recognition-specialist",
  run_in_background=true,
  description="Map design patterns and anti-patterns",
  prompt="Focus: design patterns

Before exploring, read these documents from prior waves:
- .claude/context/ARCHITECTURE.md
- .claude/context/CONVENTIONS.md

These are authoritative for architecture and coding conventions.

Write to .claude/context/:
- PATTERNS.md (max 200 lines)

Include:
- Design patterns found (Factory, Repository, Strategy, Observer, etc.) with file paths
- Anti-patterns and code smells (God objects, circular deps, feature envy)
- Code duplication hotspots (files with similar logic)
- Naming consistency analysis (inconsistent naming across modules)

DO NOT DOCUMENT:
- Validation/DI/logging patterns (see CONVENTIONS.md)
- Layer architecture (see ARCHITECTURE.md)
- Improvement recommendations (defer to CONCERNS.md in Wave 4)

UPSTREAM ENRICHMENT: If you discover information that belongs in a prior-wave document (e.g., a missing entry point for STRUCTURE.md, a convention for CONVENTIONS.md), APPEND it to that file under an '## Addendum from [your focus]' heading. Never delete or rewrite existing content.

DEDUPLICATION RULES:
- Maximum 200 lines. Tables over prose.
- Identify patterns only — do not prescribe fixes (that's CONCERNS.md's job).

$ARGUMENTS

Explore thoroughly. Write document directly. Return confirmation only."
)

Agent 9: Types

Task(
  subagent_type="orc:type-design-analyzer",
  run_in_background=true,
  description="Map type invariant strength",
  prompt="Focus: type system quality

Before exploring, read these documents from prior waves:
- .claude/context/CONVENTIONS.md
- .claude/context/STRUCTURE.md

Write to .claude/context/:
- TYPES.md (max 200 lines)

Include:
- Core domain types with 4-dimension ratings (encapsulation, invariant expression, usefulness, enforcement) each rated 1-10
- Illegal-state risks (types that allow invalid combinations)
- Type anti-patterns (stringly-typed fields, any casts, missing discriminated unions)
- Top improvement targets (prioritized P0/P1/P2)

Keep type listings in tables. One row per type with ratings. Expand only the most critical types with detailed analysis.

UPSTREAM ENRICHMENT: If you discover information that belongs in a prior-wave document (e.g., a missing entry point for STRUCTURE.md, a convention for CONVENTIONS.md), APPEND it to that file under an '## Addendum from [your focus]' heading. Never delete or rewrite existing content.

DEDUPLICATION RULES:
- Maximum 200 lines. Tables over prose.

$ARGUMENTS

Explore thoroughly. Write document directly. Return confirmation only."
)

Agent 10: Testing

Task(
  subagent_type="orc:orc-codebase-mapper",
  run_in_background=true,
  description="Map testing patterns",
  prompt="Focus: testing infrastructure

Before exploring, read these documents from prior waves:
- .claude/context/CONVENTIONS.md
- .claude/context/STRUCTURE.md

Write to .claude/context/:
- TESTING.md (max 200 lines)

Include:
- Test framework and runner (Jest, Vitest, etc.) with config file locations
- Test file organization (co-located vs separate, naming patterns)
- Test categories (unit, integration, e2e) and how to run each
- Mocking patterns (what's mocked, how, common test utilities)
- Test database/fixture setup patterns
- Property-based testing if used

DO NOT DOCUMENT:
- Coverage gap analysis (defer to TEST-QUALITY.md in Wave 4)
- File naming conventions already in STRUCTURE.md

UPSTREAM ENRICHMENT: If you discover information that belongs in a prior-wave document (e.g., a missing entry point for STRUC

…

## 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.