Map

---
description: Analyze codebase with wave-based mapper agents to produce .claude/context/ documents
argument-hint: [focus prompt] — optional, shapes mapping focus (e.g., "focus on the auth layer")
allowed-tools:
  - Task
  - Agent
  - Read
  - Write
  - Glob
  - Bash(ls:*)
  - Bash(mkdir:*)
  - Bash(wc:*)
  - Bash(rm:*)
  - AskUserQuestion
model: inherit
context: inherit
hooks: {}
user-invocable: true
---

<objective>
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`.
</objective>

<context>
$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
</context>

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

<process>

**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 `<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."
)
```

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

<focus_hint>$ARGUMENTS</focus_hint>

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

<focus_hint>$ARGUMENTS</focus_hint>

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.

<focus_hint>$ARGUMENTS</focus_hint>

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.

<focus_hint>$ARGUMENTS</focus_hint>

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.

<focus_hint>$ARGUMENTS</focus_hint>

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.

<focus_hint>$ARGUMENTS</focus_hint>

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

<focus_hint>$ARGUMENTS</focus_hint>

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.

<focus_hint>$ARGUMENTS</focus_hint>

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 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. Focus on 'how to write tests here' not 'what tests exist'.

<focus_hint>$ARGUMENTS</focus_hint>

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

**Agent 11: Codemap**

```
Task(
  subagent_type="orc:codemap-generator",
  run_in_background=true,
  description="Generate dependency and call chain map",
  prompt="Focus: module dependency graph

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

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

Include:
- Module dependency graph (which modules import which)
- Circular dependencies (if any)
- Fan-in rankings (most-imported modules)
- Fan-out rankings (modules with most imports)
- Export surface per package/module (what's publicly exposed)

DO NOT DOCUMENT:
- Execution flows or call chains (defer to FLOWS.md in Wave 4)
- Entry point file paths (see STRUCTURE.md)
- Architecture description (see ARCHITECTURE.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. Dependency tables and graphs only.
- Focus on the static module graph, not runtime behavior.

<focus_hint>$ARGUMENTS</focus_hint>

Analyze thoroughly. Write document directly. Return confirmation only."
)
```

**Agent 12: UX Patterns**

```
Task(
  subagent_type="orc:orc-codebase-mapper",
  run_in_background=true,
  description="Map UX patterns and components",
  prompt="Focus: frontend UX patterns

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

Your goal is to document UI patterns so a developer can RECREATE components from scratch.

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

Structure as:
## Layout Patterns — page templates, grid usage, nav/sidebar shells, z-index layers
## Component Catalog — per-component: file path, props interface, design system deps, key Tailwind classes/tokens
## Interaction Patterns — modals, toasts, dropdowns: trigger, animation, dismiss
## Form Patterns — field anatomy, validation display, submission states, error recovery
## Design System Usage — which shared UI library components are used and where
## Responsive & A11y — breakpoint strategy, aria patterns, keyboard nav

For each component document:
1. What design system primitives it composes
2. Key Tailwind classes / design tokens used
3. Prop interface and variant states

DO NOT DOCUMENT:
- Directory layout (see STRUCTURE.md)
- Code style rules (see CONVENTIONS.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 for component catalogs. Brief examples only for complex patterns.

<focus_hint>$ARGUMENTS</focus_hint>

Traverse ALL frontend component directories. Read source to extract actual token/class usage — do not guess. Write document directly. Return confirmation only."
)
```

**Wait for Wave 3 to complete before proceeding.**

Verify Wave 3 docs exist:
```bash
ls -la .claude/context/PATTERNS.md .claude/context/TYPES.md .claude/context/TESTING.md .claude/context/CODEMAP.md .claude/context/UX-PATTERNS.md
```

---

**Step 3d: Wave 4 — Cross-Cutting Analysis (4 parallel agents)**

These agents synthesize across all prior documents.

**Agent 13: Boundaries**

```
Task(
  subagent_type="orc:orc-codebase-mapper",
  run_in_background=true,
  description="Map package boundaries and contracts",
  prompt="Focus: code boundaries and contracts

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

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

Include:

## Interface Inventory
For key TypeScript interfaces/type aliases that define contracts between modules:
| Interface | File | Implementors | Consumers | Purpose |
Group by package/app. Include Zod schemas that serve as runtime interfaces.

## Package Boundary Seams
For each package/module boundary:
- Exports (public API surface)
- Imports (what it consumes)
- Data shapes flowing across the boundary
- Pre/postconditions (what callers must guarantee)

## Cross-Package Contracts
Implicit contracts not captured by TypeScript types:
- Ordering assumptions (must validate before persist)
- State preconditions (must be in X state before calling Y)
- Error propagation rules (throws vs returns Result)
- Shared constants that must stay in sync

## Seam Risk Matrix
| Seam | Packages | Data Shape | Validated? | Risk |
Rate: validated (Zod/runtime), typed-only (TS but no runtime), unvalidated (cast/any)

DO NOT DOCUMENT:
- Type quality ratings (see TYPES.md)
- Dependency graph (see CODEMAP.md)
- Architecture layers (see ARCHITECTURE.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 for inventories. Brief notes for contracts.

EXPLORATION STRATEGY:
1. Find all cross-package imports (grep for workspace package names in import statements)
2. Read each package's index.ts / exports to find the public API surface
3. Find Zod schemas that validate at boundaries
4. Look for composition roots (createApp, createDependencies) that reveal wiring
5. READ implementation code — document what actually happens, not what you assume

<focus_hint>$ARGUMENTS</focus_hint>

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

**Agent 14: Flows**

```
Task(
  subagent_type="orc:orc-codebase-mapper",
  run_in_background=true,
  description="Map execution flows and data lifecycles",
  prompt="Focus: execution flows and data lifecycles

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

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

Include:

## Execution Flows — Key User Stories
Discover the primary user stories by examining route handlers, event listeners, and CLI entry points. For each major flow, produce an ASCII tree diagram:

```
[Entry Point] description
├── [module] function()
│   ├── step 1
│   └── step 2
├── [module] function()
│   └── side effect
└── [storage] final destination
```

Aim for 3-5 flows covering the most important paths through the system.

## Data Entity Lifecycles
For each core data entity (discover from models/schemas), trace its lifecycle:
- Creation → transformations → storage → retrieval → output
- Which packages/modules touch it at each stage
- What transformations occur at each boundary

DO NOT DOCUMENT:
- Architecture overview (see ARCHITECTURE.md)
- Module dependency graph (see CODEMAP.md)
- Interface definitions (see BOUNDARIES.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. ASCII diagrams for flows. Brief lifecycle tables for entities.

EXPLORATION STRATEGY:
1. Find route handlers (grep for router, .get(, .post(, .put(, .delete()
2. Find event handlers and scheduled jobs
3. Find database models/schemas to identify core entities
4. Trace each flow from entry point to side effect by reading actual code
5. READ implementation code — document what actually happens, not what you assume

<focus_hint>$ARGUMENTS</focus_hint>

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

**Agent 15: Concerns**

```
Task(
  subagent_type="orc:orc-codebase-mapper",
  run_in_background=true,
  description="Map technical concerns and recommendations",
  prompt="Focus: technical debt, security, and concerns

Before exploring, read ALL documents from prior waves in .claude/context/:
- STACK.md, STRUCTURE.md, HISTORY.md
- ARCHITECTURE.md, CONVENTIONS.md, INTEGRATIONS.md, REPO.md
- PATTERNS.md, TYPES.md, TESTING.md, CODEMAP.md, UX-PATTERNS.md

This is the ONLY document that should contain improvement recommendations. All other docs identify issues but defer recommendations here.

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

Include:

## Security Concerns
- Authentication/authorization gaps
- Input validation gaps (unvalidated boundaries from TYPES.md)
- Secrets management issues
- CORS/CSP configuration

## Technical Debt
- Anti-patterns identified in PATTERNS.md that need fixing (reference, don't repeat)
- Type system weaknesses from TYPES.md (reference, don't repeat)
- Code duplication hotspots from PATTERNS.md (reference, don't repeat)

## Performance Risks
- N+1 queries, missing indexes
- Memory leaks, unbounded growth
- Inefficient algorithms or data structures

## Fragile Areas
- Components with zero test coverage
- Complex code with high cyclomatic complexity
- Areas with frequent git churn (from HISTORY.md)

## Prioritized Recommendations
| Priority | Area | Issue | Recommendation | Refs |
P0 = blocks shipping, P1 = should fix soon, P2 = nice to have

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. Reference prior docs by name instead of repeating their content.
- This is a synthesis document — add new observations from your own exploration but primarily cross-reference findings from other docs.

<focus_hint>$ARGUMENTS</focus_hint>

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

**Agent 16: Test Quality**

```
Task(
  subagent_type="orc:test-analyzer",
  run_in_background=true,
  description="Map test coverage gaps and brittleness",
  prompt="Focus: behavioral test coverage quality

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

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

Include:
- Critical untested paths (rated 1-10 by risk), grouped by module
- Brittle tests (tightly coupled to implementation, likely to break on refactor)
- Missing negative test cases (error paths, edge cases, invalid inputs)
- Over-tested areas (excessive mocking, testing implementation not behavior)
- Highest-risk gaps: what would you test first if you had one day?

DO NOT DOCUMENT:
- Test framework setup (see TESTING.md)
- Type system issues (see TYPES.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 for gap listings. Brief rationale per gap.
- Focus on behavioral coverage, not line coverage.

<focus_hint>$ARGUMENTS</focus_hint>

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

**Wait for Wave 4 to complete.**

Verify Wave 4 docs exist:
```bash
ls -la .claude/context/BOUNDARIES.md .claude/context/FLOWS.md .claude/context/CONCERNS.md .claude/context/TEST-QUALITY.md
```

---

**Step 4: Verify output**

```bash
ls -la .claude/context/
wc -l .claude/context/*.md
```

**Verification checklist:**
- All 16 documents exist
- No empty documents (each should have >20 lines)
- Warn if any document exceeds 200 lines (not a hard failure, but note it)

If any documents missing or empty, note which agents may have failed.

---

**Step 5: Present results**

Get line counts:
```bash
wc -l .claude/context/*.md
```

Display grouped by wave:

```
Codebase mapping complete (4 waves, 16 agents).

Wave 1 — Foundation:
- STACK.md ([N] lines) - Technologies and dependencies
- STRUCTURE.md ([N] lines) - Directory layout and key locations
- HISTORY.md ([N] lines) - Git evolution and inflection points

Wave 2 — Architecture & Conventions:
- ARCHITECTURE.md ([N] lines) - System design and patterns
- CONVENTIONS.md ([N] lines) - Code style and patterns
- INTEGRATIONS.md ([N] lines) - External services and APIs
- REPO.md ([N] lines) - Repository conventions and CI/CD

Wave 3 — Deep Analysis:
- PATTERNS.md ([N] lines) - Design patterns and anti-patterns
- TYPES.md ([N] lines) - Type invariant analysis
- TESTING.md ([N] lines) - Test infrastructure and patterns
- CODEMAP.md ([N] lines) - Module dependency graph
- UX-PATTERNS.md ([N] lines) - UI component catalog and patterns

Wave 4 — Cross-Cutting:
- BOUNDARIES.md ([N] lines) - Package boundaries, interfaces, contracts
- FLOWS.md ([N] lines) - Execution flows and data lifecycles
- CONCERNS.md ([N] lines) - Tech debt, security, recommendations
- TEST-QUALITY.md ([N] lines) - Coverage gaps and brittleness

[N] lines over 200-line target: [list files if any]
```

</process>

<success_criteria>
- [ ] .claude/context/ directory created
- [ ] Wave 1 (3 docs) completed before Wave 2 launched
- [ ] Wave 2 (4 docs) completed before Wave 3 launched
- [ ] Wave 3 (5 docs) completed before Wave 4 launched
- [ ] Wave 4 (4 docs) completed
- [ ] All 16 documents written and non-empty
- [ ] Documents reference prior-wave docs instead of duplicating content
- [ ] Results reported with line counts grouped by wave
</success_criteria>