map

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.

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

<when_to_use> 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 (<5 files) </when_to_use>

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

<focus_hint>$ARGUMENTS</focus_hint>

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