# Map

> Analyze codebase with wave-based mapper agents to produce .claude/context/ documents

- **Type:** Skill
- **Install:** `agentstack add skill-qgolem-orc-map`
- **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/map

## Install

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

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

## About

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**

```bash
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**

```bash
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:
```bash
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:
```bash
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.

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