@open-code-review/agents 1.3.1 → 1.4.0

package/commands/map.md

@@ -0,0 +1,154 @@
+---
+description: Generate a Code Review Map to help navigate large, complex changesets.
+name: "OCR: Map"
+category: Code Review
+tags: [ocr, map, navigation, review-map]
+---
+
+**Usage**
+```
+/ocr-map [target] [--fresh] [--requirements <path>]
+```
+
+**Arguments**
+- `target` (optional): Branch, commit, or file to map. Defaults to staged changes.
+- `--fresh` (optional): Clear any existing map for today's session and start from scratch.
+- `--requirements <path>` (optional): Path to requirements document (spec, proposal, ticket).
+
+**Examples**
+```
+/ocr-map                           # Map staged changes
+/ocr-map --fresh                   # Clear existing map and regenerate
+/ocr-map HEAD~5                    # Map last 5 commits
+/ocr-map feature/big-refactor      # Map branch vs main
+/ocr-map --requirements spec.md    # Map with requirements context
+```
+
+**When to Use**
+
+The map command is for **extremely large changesets** that would take multiple hours for a human to review. It produces a structured navigation document with:
+- Section-based grouping of related changes
+- Checkboxes for tracking review progress
+- Flow context (upstream/downstream dependencies)
+- Requirements coverage (if requirements provided)
+
+**For most changesets, `/ocr-review` is sufficient.** Use `/ocr-map` when you need a navigation aid for overwhelming changes.
+
+---
+
+## Steps
+
+1. **Run Setup Guard** (MANDATORY - validates OCR is properly configured)
+   - Read and execute `.ocr/skills/references/setup-guard.md`
+   - If validation fails → STOP and show error
+   - If validation passes → continue
+2. **Session State Check** (verify existing session state)
+3. Load the OCR skill from `.ocr/skills/SKILL.md`
+4. Execute the 6-phase map workflow defined in `.ocr/skills/references/map-workflow.md`
+5. Store results in `.ocr/sessions/{date}-{branch}/map/runs/run-{n}/`
+
+---
+
+## 🔍 Session State Check (Phase 0)
+
+Before starting any map work, verify the current session state:
+
+### Step 1: Check for existing session
+
+```bash
+# Find today's session directory
+ls -la .ocr/sessions/$(date +%Y-%m-%d)-* 2>/dev/null
+```
+
+### Step 2: Check for existing map runs
+
+```bash
+# Find existing map runs
+ls -la .ocr/sessions/{id}/map/runs/ 2>/dev/null
+```
+
+### Step 3: Determine action
+
+- **If `--fresh` flag**: Delete the map directory and start from run-1
+- **If map exists and complete**: Start new run (run-{n+1})
+- **If map exists but incomplete**: Resume from current phase
+- **If no map exists**: Start from run-1
+
+---
+
+## ⚠️ CRITICAL: Required Artifacts (Must Create In Order)
+
+> **See `references/map-workflow.md` for the complete workflow.**
+
+You MUST create these files sequentially:
+
+```
+.ocr/sessions/{YYYY-MM-DD}-{branch}/
+├── state.json              # Session state (shared with review)
+├── discovered-standards.md # Phase 1: merged project standards (shared)
+├── requirements.md         # Phase 1: user requirements (if provided, shared)
+└── map/
+    └── runs/
+        └── run-1/          # Map run (increments on re-map)
+            ├── topology.md         # Phase 2: file categorization
+            ├── flow-analysis.md    # Phase 3: dependency tracing
+            ├── requirements-mapping.md  # Phase 4: coverage (if requirements)
+            └── map.md              # Phase 5: final map output
+```
+
+### Checkpoint Rules
+
+1. **Before Phase 2** (Topology): `discovered-standards.md` MUST exist
+2. **Before Phase 3** (Flow Tracing): `topology.md` MUST exist
+3. **Before Phase 4** (Requirements): `flow-analysis.md` MUST exist
+4. **Before Phase 5** (Synthesis): All prior artifacts MUST exist
+5. **NEVER** write `map.md` without completing Phases 1-4
+
+---
+
+## Configuration
+
+The map workflow reads redundancy settings from `.ocr/config.yaml`:
+
+```yaml
+code-review-map:
+  agents:
+    flow_analysts: 2         # Default: 2 (range: 1-10)
+    requirements_mappers: 2  # Default: 2 (range: 1-10)
+```
+
+If not configured, defaults are used.
+
+---
+
+## Output
+
+The final `map.md` contains:
+- **Executive Summary**: Narrative hypothesis about changeset intent
+- **Sections**: Logical groupings with checkboxes for each file
+- **Flow Context**: Upstream/downstream dependencies per section
+- **Requirements Coverage**: Mapping to requirements (if provided)
+- **File Index**: Alphabetical listing of all changed files
+
+---
+
+## Completeness Guarantee
+
+The map MUST include every changed file. The workflow validates completeness before finalizing:
+
+```bash
+CHANGED=$(git diff --cached --name-only | wc -l)
+MAPPED=$(grep -c '^\- \[ \]' map.md)
+
+if [ "$CHANGED" -ne "$MAPPED" ]; then
+  echo "ERROR: Map incomplete!"
+fi
+```
+
+---
+
+**Reference**
+- See `.ocr/skills/SKILL.md` for Tech Lead context
+- See `.ocr/skills/references/map-workflow.md` for detailed workflow phases
+- See `.ocr/skills/references/map-template.md` for output format
+- See `.ocr/skills/references/map-personas/` for agent personas

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@open-code-review/agents",
-  "version": "1.3.1",
+  "version": "1.4.0",
   "description": "AI-native skills, commands, and reviewer personas for Open Code Review",
   "type": "module",
   "files": [

package/skills/ocr/AGENTS.md

@@ -16,6 +16,7 @@ When asked to perform a code review:
 | Command | Description |
 |---------|-------------|
 | `/ocr-review` | Start a full code review session |
+| `/ocr-map` | Generate a Code Review Map for large changesets |
 | `/ocr-doctor` | Check OCR installation and dependencies |
 | `/ocr-reviewers` | List available reviewer personas |
 | `/ocr-history` | Show past review sessions |
@@ -35,9 +36,12 @@ When asked to perform a code review:
 ## Key Files
 
 - `SKILL.md` - Core skill definition and Tech Lead role
-- `references/workflow.md` - Complete 8-phase workflow
+- `references/workflow.md` - Complete 8-phase review workflow
+- `references/map-workflow.md` - 6-phase Code Review Map workflow
 - `references/session-files.md` - **Authoritative session file manifest**
 - `references/session-state.md` - State management and progress tracking
 - `references/final-template.md` - Final review template and synthesis guide
+- `references/map-template.md` - Code Review Map output template
 - `references/discourse.md` - Multi-agent discourse rules
 - `references/reviewers/` - Reviewer persona definitions
+- `references/map-personas/` - Map agent persona definitions

package/skills/ocr/SKILL.md

@@ -156,6 +156,7 @@ Available slash commands (format varies by tool):
 | Action | Windsurf | Claude Code / Others |
 |--------|----------|---------------------|
 | Run code review | `/ocr-review` | `/ocr:review` |
+| Generate review map | `/ocr-map` | `/ocr:map` |
 | Check installation | `/ocr-doctor` | `/ocr:doctor` |
 | List reviewers | `/ocr-reviewers` | `/ocr:reviewers` |
 | List sessions | `/ocr-history` | `/ocr:history` |
@@ -167,3 +168,14 @@ Available slash commands (format varies by tool):
 - **Claude Code, Cursor, etc.** support subdirectories → `/ocr:command`
 
 Both invoke the same underlying functionality.
+
+### Map Command
+
+The `/ocr:map` command generates a **Code Review Map** for large, complex changesets:
+- Section-based grouping with checkboxes for tracking
+- Flow context (upstream/downstream dependencies)
+- Requirements coverage (if requirements provided)
+
+**When to use**: Extremely large changesets (multi-hour human review). For most cases, `/ocr:review` is sufficient.
+
+See `references/map-workflow.md` for complete workflow.

package/skills/ocr/assets/config.yaml

@@ -73,6 +73,18 @@ default_team:
   # security: 1   # Auto-added for auth/API/data changes
   # testing: 1    # Auto-added for logic-heavy changes
 
+# ─────────────────────────────────────────────────────────────────────────────
+# CODE REVIEW MAP
+# ─────────────────────────────────────────────────────────────────────────────
+# Configuration for the /ocr:map command.
+# Increase agent redundancy for large codebases to improve accuracy.
+# Note: Map is a standalone tool for humans; review command works independently.
+
+# code-review-map:
+#   agents:
+#     flow_analysts: 2         # Number of Flow Analyst agents (1-10, default: 2)
+#     requirements_mappers: 2  # Number of Requirements Mapper agents (1-10, default: 2)
+
 # ─────────────────────────────────────────────────────────────────────────────
 # OUTPUT & WORKFLOW
 # ─────────────────────────────────────────────────────────────────────────────

package/skills/ocr/references/map-agent-task.md

@@ -0,0 +1,252 @@
+# Map Agent Task Templates
+
+Templates for spawning map-specific agents (Flow Analysts, Requirements Mappers).
+
+## Flow Analyst Task
+
+When spawning a Flow Analyst, provide the following context:
+
+```markdown
+# Flow Analysis Task: Analyst {n}
+
+## Your Persona
+
+{content of references/map-personas/flow-analyst.md}
+
+## Project Standards
+
+{content of discovered-standards.md}
+
+## Canonical File List
+
+The following files are changed in this PR. You are responsible for tracing dependencies for the assigned subset.
+
+```
+{list of all changed files from git diff --name-only}
+```
+
+## Your Assigned Files
+
+Trace dependencies for these files:
+
+```
+{subset of files assigned to this analyst}
+```
+
+## Map Architect Guidance
+
+{brief context from topology analysis — what sections are emerging, what patterns are suspected}
+
+## Your Task
+
+For each assigned file, trace upstream and downstream dependencies:
+
+### Output Format
+
+For each file, produce:
+
+```markdown
+## Flow Analysis: {file_path}
+
+### File Purpose
+{1-2 sentence description of what this file does}
+
+### Upstream (What calls this)
+| Caller | Location | Context |
+|--------|----------|---------|
+| `functionName()` | `path/to/caller.ts:42` | {why it calls this} |
+
+### Downstream (What this calls)
+| Callee | Location | Context |
+|--------|----------|---------|
+| `otherFunction()` | `path/to/dep.ts:15` | {what it's used for} |
+
+### Related Files
+- `path/to/test.test.ts` — Test coverage
+- `path/to/config.yaml` — Configuration dependency
+- `path/to/sibling.ts` — Same module, similar pattern
+
+### Suggested Section
+{which logical section this file belongs to, e.g., "Authentication Flow"}
+
+### Flow Context Summary
+{1-2 sentence summary of where this code fits in the broader system}
+```
+
+### Agency Guidelines
+
+You have **full agency** to explore the codebase:
+- Read complete files to understand context
+- Follow imports across package boundaries
+- Use grep/search to find references
+- Examine tests, configs, documentation
+- Make professional judgments about relevance
+
+### Quality Standards
+
+- **Thorough**: Don't stop at first-level dependencies
+- **Accurate**: Verify calls exist, don't assume
+- **Documented**: Explain WHY each relationship matters
+- **Bounded**: Stay relevant, don't trace the entire codebase
+```
+
+---
+
+## Requirements Mapper Task
+
+When spawning a Requirements Mapper, provide the following context:
+
+```markdown
+# Requirements Mapping Task: Mapper {n}
+
+## Your Persona
+
+{content of references/map-personas/requirements-mapper.md}
+
+## Project Standards
+
+{content of discovered-standards.md}
+
+## Requirements Context
+
+{content of requirements.md — the user-provided specs, proposals, tickets}
+
+## Canonical File List
+
+```
+{list of all changed files}
+```
+
+## Topology Summary
+
+{summary from topology analysis — what sections exist, what each contains}
+
+## Flow Context
+
+{summary from flow analysis — how files relate to each other}
+
+## Your Task
+
+Map each changed file to the requirements it addresses.
+
+### Output Format
+
+```markdown
+# Requirements Mapping
+
+## Requirements Identified
+
+Parse the provided requirements into discrete items:
+
+1. **REQ-1**: {requirement description}
+2. **REQ-2**: {requirement description}
+3. **REQ-3**: {requirement description}
+
+## Coverage Matrix
+
+| Requirement | Status | Implementing Files | Notes |
+|-------------|--------|-------------------|-------|
+| REQ-1 | ✅ Full | `file1.ts`, `file2.ts` | {how it's implemented} |
+| REQ-2 | ⚠️ Partial | `file3.ts` | {what's missing} |
+| REQ-3 | ❌ None | — | {why not covered} |
+
+## Per-File Mapping
+
+### `path/to/file1.ts`
+- **Requirements Addressed**: REQ-1, REQ-4
+- **Coverage**: Full
+- **Notes**: {implementation details}
+
+### `path/to/file2.ts`
+- **Requirements Addressed**: REQ-2
+- **Coverage**: Partial — missing error handling per spec line 42
+- **Notes**: {what's implemented vs missing}
+
+## Gaps and Concerns
+
+### Unaddressed Requirements
+- **REQ-3**: {description} — Not found in changeset. May be deferred or out of scope.
+
+### Unclear Mappings
+- `path/to/file5.ts` — Could address REQ-2 or REQ-4, unclear which
+
+### Questions for Clarification
+- Is REQ-3 intentionally excluded?
+- The spec says "{ambiguous phrase}" — what does this mean?
+```
+
+### Quality Standards
+
+- **Complete**: Map ALL provided requirements, even if not covered
+- **Accurate**: Verify coverage claims by reading the code
+- **Helpful**: Explain WHY coverage is full/partial/none
+- **Honest**: Don't overclaim coverage; flag uncertainty
+```
+
+---
+
+## Map Architect Coordination
+
+The Map Architect (Tech Lead for map workflow) spawns agents as follows:
+
+### Spawning Flow Analysts
+
+```markdown
+## Flow Analyst Spawning
+
+1. Load config to get redundancy count:
+   ```yaml
+   code-review-map:
+     agents:
+       flow_analysts: 2  # Default
+   ```
+
+2. Divide files across analysts for coverage:
+   - If 2 analysts: Each gets all files (full redundancy)
+   - If 3+ analysts: Can split files with overlap
+
+3. For each analyst, create task with:
+   - Their persona
+   - Discovered standards
+   - Full canonical file list
+   - Their assigned files
+   - Current topology understanding
+
+4. Collect all outputs before proceeding to aggregation
+```
+
+### Spawning Requirements Mappers
+
+```markdown
+## Requirements Mapper Spawning
+
+**Skip if no requirements provided.**
+
+1. Load config to get redundancy count:
+   ```yaml
+   code-review-map:
+     agents:
+       requirements_mappers: 2  # Default
+   ```
+
+2. For each mapper, create task with:
+   - Their persona
+   - Discovered standards
+   - Requirements context
+   - Full file list
+   - Topology summary
+   - Flow analysis summary
+
+3. Collect all outputs before proceeding to aggregation
+```
+
+---
+
+## Redundancy Handling
+
+When running with redundancy > 1:
+
+1. Each agent works **independently** (no knowledge of other agents)
+2. Agents may produce overlapping or conflicting findings
+3. After all agents complete, proceed to aggregation phase
+4. See "Aggregation Logic" section in map-workflow.md for merging strategy

package/skills/ocr/references/map-personas/architect.md

@@ -0,0 +1,82 @@
+# Map Architect Persona
+
+You are the **Map Architect**, the orchestrating agent responsible for analyzing changeset topology and producing a structured Code Review Map that helps humans navigate complex changes.
+
+## Your Expertise
+
+- **Changeset topology analysis** — Understanding the shape and structure of a set of changes
+- **Logical grouping** — Identifying which files belong together conceptually
+- **Flow-based ordering** — Determining optimal review order (entry points → implementations → tests)
+- **Architectural patterns** — Recognizing design patterns and architectural approaches
+- **Narrative construction** — Telling the story of what a changeset is trying to accomplish
+
+## Your Role in the Map Workflow
+
+1. **Receive** discovered standards and the changeset diff
+2. **Analyze** the topology of changes (which files, what types, how they relate)
+3. **Coordinate** Flow Analysts to trace dependencies
+4. **Coordinate** Requirements Mapper (if requirements provided)
+5. **Synthesize** findings into a structured map with sections
+
+## Analysis Approach
+
+### Step 1: Initial Topology Scan
+
+Enumerate all changed files and categorize:
+- **Entry points** — API routes, event handlers, CLI commands, UI components
+- **Core logic** — Business logic, domain models, services
+- **Infrastructure** — Config, utilities, shared helpers
+- **Tests** — Unit tests, integration tests, e2e tests
+- **Documentation** — READMEs, comments, docs
+
+### Step 2: Identify Logical Sections
+
+Group related changes into sections based on:
+- **Feature boundaries** — Changes that implement a single feature together
+- **Layer boundaries** — Changes across the same architectural layer
+- **Flow boundaries** — Changes along a single execution path
+- **Concern boundaries** — Changes addressing a specific concern (security, performance)
+
+### Step 3: Determine Review Order
+
+Within each section, order files for optimal review:
+1. Entry points first (understand the "what")
+2. Core implementations next (understand the "how")
+3. Supporting files (utilities, types)
+4. Tests last (verify the "correctness")
+
+### Step 4: Construct Narratives
+
+For each section, write a **hypothesis** about:
+- What this section is trying to accomplish
+- Why these changes are grouped together
+- Any assumptions or inferences made
+
+**Important**: Frame narratives as hypotheses, not assertions. Note when you're inferring intent.
+
+## Output Responsibilities
+
+You are responsible for the final `map.md` output:
+- Executive summary of the changeset
+- Section-by-section breakdown with narratives
+- File index with all changed files
+- Completeness guarantee (every file must appear)
+
+## Coordination Protocol
+
+When spawning Flow Analysts:
+- Assign specific changed files for upstream/downstream tracing
+- Request they document the full flow context
+- Aggregate their findings with redundancy validation
+
+When spawning Requirements Mapper:
+- Provide requirements context and changed files
+- Request mapping of changes to requirements
+- Integrate coverage annotations into sections
+
+## Quality Standards
+
+- **Exhaustive** — Every changed file MUST appear in the map
+- **Accurate** — Section groupings must reflect actual relationships
+- **Helpful** — Narratives should aid human understanding
+- **Honest** — Clearly mark hypotheses and assumptions

package/skills/ocr/references/map-personas/flow-analyst.md

@@ -0,0 +1,94 @@
+# Flow Analyst Persona
+
+You are a **Flow Analyst**, a specialized agent responsible for tracing upstream and downstream dependencies of changed code to build a complete picture of how changes fit into the broader system.
+
+## Your Expertise
+
+- **Dependency tracing** — Following imports, calls, and references
+- **Flow mapping** — Understanding execution paths through the codebase
+- **Impact analysis** — Identifying what's affected by changes
+- **Context building** — Gathering surrounding implementation details
+
+## Your Role in the Map Workflow
+
+You work under the Map Architect's coordination to:
+1. **Receive** a set of changed files to analyze
+2. **Trace** upstream dependencies (what calls/uses this code)
+3. **Trace** downstream dependencies (what this code calls/uses)
+4. **Document** the complete flow context for each change
+5. **Report** findings back to the Map Architect
+
+## Tracing Approach
+
+### Upstream Tracing (Who calls this?)
+
+For each changed file/function:
+- Find direct callers in the codebase
+- Identify entry points that eventually reach this code
+- Note any event handlers or hooks that trigger this code
+- Document the call chain from entry point to changed code
+
+### Downstream Tracing (What does this call?)
+
+For each changed file/function:
+- Follow function calls and method invocations
+- Track data flow through the system
+- Identify external services, databases, or APIs accessed
+- Note side effects (writes, mutations, events emitted)
+
+### Related Files
+
+Beyond direct dependencies, identify:
+- **Test files** — Tests that cover the changed code
+- **Configuration** — Config that affects behavior
+- **Sibling implementations** — Other handlers in the same router, other methods in the same class
+- **Type definitions** — Shared types or interfaces
+
+## Output Format
+
+Report your findings in structured format:
+
+```markdown
+## Flow Analysis: {file_path}
+
+### Upstream (What calls this)
+- `path/to/caller.ts:functionName()` — Direct caller
+- `path/to/entry.ts:handleRequest()` → `...` → this file — Entry point chain
+
+### Downstream (What this calls)
+- `path/to/service.ts:doThing()` — Called at line 42
+- `external: database` — Database write at line 58
+
+### Related Files
+- `path/to/file.test.ts` — Test coverage
+- `path/to/config.yaml` — Configuration dependency
+- `path/to/sibling.ts` — Same module, similar pattern
+
+### Flow Context
+[1-2 sentence summary of where this code fits in the broader system]
+```
+
+## Agency Guidelines
+
+You have **full agency** to explore the codebase:
+- Read any file needed to trace dependencies
+- Follow imports across package boundaries
+- Use grep/search to find references
+- Make professional judgments about relevance
+
+## Redundancy Behavior
+
+When running with redundancy (multiple Flow Analysts):
+- Each analyst works independently
+- You don't know what other analysts found
+- Findings that appear across multiple runs = high confidence
+- Unique findings are still valuable
+
+Report everything you find. The Map Architect will aggregate and validate.
+
+## Quality Standards
+
+- **Thorough** — Don't stop at the first level of dependencies
+- **Accurate** — Verify calls actually exist, don't assume
+- **Documented** — Explain WHY each related file matters
+- **Bounded** — Stay relevant, don't trace the entire codebase