@open-code-review/agents 1.5.1 → 1.7.0

package/README.md

@@ -1,8 +1,34 @@
 # @open-code-review/agents
 
-The skill definitions, reviewer personas, and workflow references that power Open Code Review.
+Skill definitions, reviewer personas, and workflow references that power [Open Code Review](https://github.com/spencermarx/open-code-review).
 
-> Browse review output and map artifacts in the [Dashboard](../dashboard/README.md) or through your AI assistant's slash commands.
+## Getting Started
+
+All OCR workflows require the CLI for session state management. Install it first:
+
+```bash
+# 1. Install the CLI
+npm install -g @open-code-review/cli
+
+# 2. Initialize in your project (copies these assets to .ocr/)
+cd your-project
+ocr init
+```
+
+To update after a package upgrade:
+
+```bash
+ocr update
+```
+
+This updates skills and workflow references while **preserving your `.ocr/config.yaml`** and **all reviewer personas** (both default and custom).
+
+### Via Claude Code Plugin
+
+```bash
+/plugin marketplace add spencermarx/open-code-review
+/plugin install ocr@aclarify
+```
 
 ## What This Package Contains
 
@@ -17,64 +43,50 @@ agents/
 │   │   ├── discourse.md       # Multi-agent debate rules
 │   │   ├── final-template.md  # Final review template
 │   │   └── reviewers/         # Persona definitions (customizable)
-│   │       ├── principal.md # Architecture, design patterns
-│   │       ├── quality.md   # Code style, best practices
-│   │       ├── security.md  # Auth, data handling, vulnerabilities
-│   │       └── testing.md   # Coverage, edge cases
+│   │       ├── principal.md     # Architecture, design patterns
+│   │       ├── quality.md       # Code style, best practices
+│   │       ├── security.md      # Auth, data handling, vulnerabilities
+│   │       ├── testing.md       # Coverage, edge cases
+│   │       ├── martin-fowler.md # Famous engineer persona
+│   │       └── ...              # 28 personas total
 │   └── assets/
-│       ├── config.yaml      # Default configuration
+│       ├── config.yaml        # Default configuration
 │       └── reviewer-template.md
-├── commands/                # Slash command definitions
+├── commands/                  # Slash command definitions
 │   ├── review.md
 │   ├── map.md
 │   ├── doctor.md
 │   ├── history.md
 │   ├── show.md
 │   ├── reviewers.md
-│   └── post.md
-└── .claude-plugin/          # Claude Code plugin manifest
+│   ├── post.md
+│   ├── address.md
+│   └── translate-review-to-single-human.md
+└── .claude-plugin/            # Claude Code plugin manifest
     └── plugin.json
 ```
 
-## Prerequisites
-
-All OCR workflows require the CLI for session state management. Before running any review or map command, ensure the CLI is installed:
-
-```bash
-npm install -g @open-code-review/cli
-ocr init
-```
-
-The CLI provides the `ocr state` commands that track workflow progress through each phase. Without it, reviews will fail at phase transitions.
-
-## Installation
-
-### Via CLI (Recommended)
-
-The CLI copies these assets to your project's `.ocr/` directory:
-
-```bash
-npx @open-code-review/cli init
-```
-
-To update after a package upgrade:
-
-```bash
-ocr update
-```
-
-This updates skills and workflow references while **preserving your `.ocr/config.yaml`** and **all reviewer personas** (both default and custom).
+## Commands
 
-### Via Claude Code Plugin
+| File | Windsurf | Claude Code / Cursor |
+|------|----------|----------------------|
+| `review.md` | `/ocr-review` | `/ocr:review` |
+| `map.md` | `/ocr-map` | `/ocr:map` |
+| `post.md` | `/ocr-post` | `/ocr:post` |
+| `doctor.md` | `/ocr-doctor` | `/ocr:doctor` |
+| `reviewers.md` | `/ocr-reviewers` | `/ocr:reviewers` |
+| `history.md` | `/ocr-history` | `/ocr:history` |
+| `show.md` | `/ocr-show` | `/ocr:show` |
+| `address.md` | `/ocr-address` | `/ocr:address` |
+| `create-reviewer.md` | `/ocr-create-reviewer` | `/ocr:create-reviewer` |
+| `sync-reviewers.md` | `/ocr-sync-reviewers` | `/ocr:sync-reviewers` |
+| `translate-review-to-single-human.md` | `/ocr-translate-review-to-single-human` | `/ocr:translate-review-to-single-human` |
 
-```bash
-/plugin marketplace add spencermarx/open-code-review
-/plugin install ocr@aclarify
-```
+**Why two formats?** Windsurf requires flat command files with a prefix (`/ocr-command`), while Claude Code and Cursor support subdirectories (`/ocr:command`). Both invoke the same underlying functionality.
 
 ## Skill Architecture
 
-The `SKILL.md` file defines the **Tech Lead** role—the orchestrator that:
+The `SKILL.md` file defines the **Tech Lead** role — the orchestrator that:
 
 1. Discovers project context (config, OpenSpec, reference files)
 2. Analyzes changes and identifies risk areas
@@ -82,62 +94,58 @@ The `SKILL.md` file defines the **Tech Lead** role—the orchestrator that:
 4. Facilitates discourse between reviewers
 5. Synthesizes findings into a unified review
 
-Each reviewer in `references/reviewers/` is a specialized persona. You can customize the built-in reviewers or add your own.
+### Reviewer Personas
+
+28 personas across four tiers:
+
+| Tier | Personas |
+|------|----------|
+| **Generalists** | Principal, Quality, Fullstack, Staff Engineer, Architect |
+| **Specialists** | Security, Testing, Frontend, Backend, Performance, DevOps, Infrastructure, Reliability, Mobile, Data, DX, Docs Writer, Accessibility, AI |
+| **Famous Engineers** | Martin Fowler, Kent Beck, Sandi Metz, Rich Hickey, Kent Dodds, Anders Hejlsberg, John Ousterhout, Kamil Mysliwiec, Tanner Linsley, Vladimir Khorikov |
+| **Custom** | Your own domain-specific reviewers |
+
+Famous Engineer personas review through the lens of each engineer's published work and philosophy — e.g., Martin Fowler focuses on refactoring and domain modeling, Kent Beck on test-driven development, Sandi Metz on object-oriented design.
+
+**Create custom reviewers** via the `/ocr:create-reviewer` command or by adding `.md` files to `.ocr/skills/references/reviewers/`. See the [reviewer template](skills/ocr/assets/reviewer-template.md).
+
+**Ephemeral reviewers** can be added per-review with `--reviewer` — no persistence required. See the `review.md` command spec for details.
 
 ### Map Agent Personas
 
-The `/ocr:map` command uses a separate set of specialized agents defined in `references/map-personas/`:
+The `/ocr:map` command uses specialized agents:
 
 | Persona | Role |
 |---------|------|
-| **Map Architect** | Analyzes change topology, determines optimal section groupings and review ordering |
+| **Map Architect** | Analyzes change topology, determines section groupings and review ordering |
 | **Flow Analyst** | Traces upstream/downstream dependencies, groups related changes by data and control flow |
-| **Requirements Mapper** | Maps changes to requirements/specs when provided, identifies coverage gaps |
+| **Requirements Mapper** | Maps changes to requirements/specs, identifies coverage gaps |
 
-These agents run with configurable redundancy (default: 2) to increase confidence in groupings. See `.ocr/config.yaml` → `code-review-map.agents` for tuning.
+These run with configurable redundancy (default: 2). See `.ocr/config.yaml` → `code-review-map.agents`.
 
 ## Session Structure
 
-OCR uses a **round-first architecture** for session storage:
-
 ```
 .ocr/sessions/{YYYY-MM-DD}-{branch}/
-├── discovered-standards.md # Project context (shared across rounds)
-├── context.md              # Change analysis (shared)
+├── discovered-standards.md  # Project context (shared across rounds)
+├── context.md               # Change analysis (shared)
 └── rounds/
     ├── round-1/
-    │   ├── reviews/        # Individual reviewer outputs
-    │   ├── discourse.md    # Cross-reviewer discussion
-    │   └── final.md        # Synthesized review
-    └── round-2/            # Created on re-review
-        └── ...
-├── maps/
-│   ├── run-1/
-│   │   ├── map.md             # Code Review Map output
-│   │   └── flow-analysis.md   # Dependency graph (Mermaid)
-│   └── run-2/                 # Created on re-map
-│       └── ...
+    │   ├── reviews/         # Individual reviewer outputs
+    │   │   ├── principal-1.md
+    │   │   ├── quality-1.md
+    │   │   └── ephemeral-1.md  # From --reviewer (if used)
+    │   ├── discourse.md     # Cross-reviewer discussion
+    │   └── final.md         # Synthesized review
+    └── round-2/             # Created on re-review
+├── map/
+│   └── runs/
+│       └── run-1/
+│           ├── map.md           # Code Review Map
+│           └── flow-analysis.md # Dependency graph (Mermaid)
 ```
 
-**Multi-round reviews**: Running `/ocr-review` again on an existing session creates a new round (`round-2/`, `round-3/`, etc.) if the previous round is complete. This enables iterative "review → fix → re-review" workflows while preserving history.
-
-**Map runs**: Running `/ocr-map` creates map artifacts in `maps/run-{n}/`. Like review rounds, subsequent runs create new directories without modifying previous ones.
-
-See `references/session-files.md` for the complete file manifest.
-
-## Commands
-
-| File | Windsurf | Claude Code / Cursor |
-|------|----------|----------------------|
-| `review.md` | `/ocr-review` | `/ocr:review` |
-| `map.md` | `/ocr-map` | `/ocr:map` |
-| `doctor.md` | `/ocr-doctor` | `/ocr:doctor` |
-| `reviewers.md` | `/ocr-reviewers` | `/ocr:reviewers` |
-| `history.md` | `/ocr-history` | `/ocr:history` |
-| `show.md` | `/ocr-show` | `/ocr:show` |
-| `post.md` | `/ocr-post` | `/ocr:post` |
-
-**Why two formats?** Windsurf requires flat command files with a prefix (`/ocr-command`), while Claude Code and Cursor support subdirectories (`/ocr:command`). Both invoke the same underlying functionality.
+Running `/ocr-review` again on an existing session creates a new round if the previous round is complete. See `references/session-files.md` for the complete file manifest.
 
 ## License
 

package/commands/create-reviewer.md

@@ -0,0 +1,66 @@
+---
+description: Create a new custom reviewer from a natural language description.
+name: "OCR: Create Reviewer"
+category: Code Review
+tags: [ocr, reviewers, create]
+---
+
+**Usage**
+```
+/ocr-create-reviewer {name} --focus "{description}"
+```
+
+**Examples**
+```
+create-reviewer rust-safety --focus "Memory safety, ownership patterns, lifetime management, unsafe block auditing"
+create-reviewer api-design --focus "REST API design, backwards compatibility, versioning, error response consistency"
+create-reviewer graphql --focus "Schema design, resolver efficiency, N+1 queries, type safety"
+```
+
+**What it does**
+
+Creates a new reviewer markdown file in `.ocr/skills/references/reviewers/`, following the standard reviewer template structure, and automatically syncs the metadata so the dashboard can see the new reviewer.
+
+**Steps**
+
+1. **Parse arguments**: Extract the reviewer name and `--focus` description from the arguments.
+   - Normalize the name to a slug: lowercase, hyphens for spaces, alphanumeric + hyphens only
+   - Example: "API Design" → `api-design`
+
+2. **Check for duplicates**: Verify `.ocr/skills/references/reviewers/{slug}.md` does NOT already exist.
+   - If it exists, report: "Reviewer `{slug}` already exists. Edit the file directly at `.ocr/skills/references/reviewers/{slug}.md`."
+   - Stop — do not overwrite.
+
+3. **Read the template** (REQUIRED — this is the source of truth for reviewer structure):
+   Read `.ocr/skills/assets/reviewer-template.md`. This file defines the exact sections, ordering, and format every reviewer MUST follow. Do not invent sections or skip sections — adhere to the template.
+
+4. **Read exemplars**: Read 2-3 existing reviewer files from `.ocr/skills/references/reviewers/` as style reference. Good choices:
+   - One holistic reviewer (e.g., `architect.md` or `fullstack.md`)
+   - One specialist reviewer close to the requested domain (if applicable)
+   - Study the tone, section depth, and specificity level
+
+5. **Generate the reviewer file**: Write a complete reviewer markdown file that follows the template structure from step 3:
+   - Starts with `# {Display Name} Reviewer` (title case, no "Principal" prefix — all reviewers are senior by default)
+   - Contains every section from the template (`## Your Focus Areas`, `## Your Review Approach`, `## What You Look For`, `## Your Output Style`, `## Agency Reminder`)
+   - Uses specific, actionable language (not generic advice)
+   - Reflects the user's `--focus` description as the primary lens
+   - Matches the depth and tone of the exemplars from step 4
+
+6. **Write the file**: Save to `.ocr/skills/references/reviewers/{slug}.md`
+
+7. **Sync metadata**: After writing the file, run the sync-reviewers workflow to update `reviewers-meta.json`.
+   Follow the instructions in `.ocr/commands/sync-reviewers.md` — this reads ALL reviewer files (including the one you just created), extracts metadata with semantic understanding, and pipes through the CLI for validated persistence.
+
+8. **Report**: Confirm the new reviewer was created with:
+   - Name and slug
+   - Focus areas extracted
+   - Tier classification (`custom` for user-created reviewers)
+   - Total reviewer count after sync
+
+**Important**
+
+- Do NOT use the `Principal` prefix in the title — all reviewers are assumed to be senior/principal level by default.
+- Follow the exact template structure from the exemplars — consistency matters for the dashboard parser.
+- The `--focus` description is guidance, not a literal copy. Transform it into well-structured focus areas and review checklists.
+- Always run the sync step — the dashboard depends on `reviewers-meta.json` being up to date.
+- The `ocr` CLI path may be provided in the CLI Resolution section above. If so, use that path instead of bare `ocr`.

package/commands/review.md

@@ -7,12 +7,14 @@ tags: [ocr, review, code-review]
 
 **Usage**
 ```
-/ocr-review [target] [--fresh]
+/ocr-review [target] [--fresh] [--team <ids>] [--reviewer "<description>"]
 ```
 
 **Arguments**
 - `target` (optional): Branch, commit, or file to review. Defaults to staged changes.
 - `--fresh` (optional): Clear any existing session for today's date and start from scratch.
+- `--team` (optional): Override the default reviewer team. Format: `reviewer-id:count,reviewer-id:count`. Example: `--team principal:2,martin-fowler:1`.
+- `--reviewer` (optional, repeatable): Add an ephemeral reviewer described in natural language. The Tech Lead will synthesize a focused reviewer persona from the description. Does not persist. Example: `--reviewer "Focus on error handling in the auth flow"`.
 
 **Examples**
 ```
@@ -21,6 +23,9 @@ tags: [ocr, review, code-review]
 /ocr-review HEAD~3             # Review last 3 commits
 /ocr-review feature/auth       # Review branch vs main
 /ocr-review src/api/           # Review specific directory
+/ocr-review --team principal:2,security:1   # Custom team composition
+/ocr-review --reviewer "Review as a junior developer would"
+/ocr-review --team principal:1 --reviewer "Focus on error handling" --reviewer "Check accessibility"
 ```
 
 **Steps**

package/commands/sync-reviewers.md

@@ -0,0 +1,93 @@
+---
+description: Sync reviewer metadata from markdown files to reviewers-meta.json for the dashboard.
+name: "OCR: Sync Reviewers"
+category: Code Review
+tags: [ocr, reviewers, sync]
+---
+
+**Usage**
+```
+/ocr:sync-reviewers
+```
+
+**What it does**
+
+Reads all reviewer markdown files in `.ocr/skills/references/reviewers/`, extracts structured metadata from each, and pipes the result to the CLI for validated, atomic persistence to `reviewers-meta.json`.
+
+**When to run**
+
+- After adding or editing a reviewer in `.ocr/skills/references/reviewers/`
+- After changing `default_team` in `.ocr/config.yaml`
+
+**Steps**
+
+1. **Read config**: Parse `.ocr/config.yaml` and extract the `default_team` keys (reviewer IDs mapped to weights).
+
+2. **Read all reviewer files**: List every `.md` file in `.ocr/skills/references/reviewers/`. For each file, read its contents and extract:
+   - **id**: Filename without `.md` (e.g., `architect`, `martin-fowler`)
+   - **name**: From the `# Title` heading — strip trailing "Reviewer", "— Reviewer", etc.
+   - **tier**: Classify using the lists below, or `custom` if not recognized
+   - **icon**: Assign from the icon table below, defaulting to `brain` for personas and `user` for custom
+   - **description**: The opening paragraph that describes what this reviewer does (first substantive non-heading, non-blockquote line)
+   - **focus_areas**: Bold items from the `## Your Focus Areas` section (the text before the colon/dash)
+   - **is_default**: `true` if the id is a key in `config.yaml`'s `default_team`
+   - **is_builtin**: `true` if the id appears in any of the built-in lists below
+   - **known_for** (persona only): From `> **Known for**: ...` blockquote
+   - **philosophy** (persona only): From `> **Philosophy**: ...` blockquote
+
+   Use your understanding of the markdown — reviewer files may have minor structural variations. Extract the semantically correct value even if formatting differs slightly from the template.
+
+3. **Build the JSON payload**:
+   ```json
+   {
+     "schema_version": 1,
+     "generated_at": "<ISO 8601 timestamp>",
+     "reviewers": [<array of reviewer objects>]
+   }
+   ```
+
+4. **Pipe to CLI for validation and persistence**:
+   ```bash
+   echo '<json>' | ocr reviewers sync --stdin
+   ```
+   The CLI validates the schema, checks for duplicate IDs and invalid tiers, and writes `reviewers-meta.json` atomically. If validation fails, fix the JSON and retry.
+
+5. **Report**: Confirm the count and tier breakdown from the CLI output.
+
+**Built-in reviewer IDs**
+
+Holistic: `architect`, `fullstack`, `reliability`, `staff-engineer`, `principal`
+
+Specialist: `frontend`, `backend`, `infrastructure`, `performance`, `accessibility`, `data`, `devops`, `dx`, `mobile`, `security`, `quality`, `testing`, `ai`
+
+Persona: `martin-fowler`, `kent-beck`, `john-ousterhout`, `anders-hejlsberg`, `vladimir-khorikov`, `kent-dodds`, `tanner-linsley`, `kamil-mysliwiec`, `sandi-metz`, `rich-hickey`
+
+**Icon assignments**
+
+| ID | Icon |
+|---|---|
+| architect | blocks |
+| fullstack | layers |
+| reliability | activity |
+| staff-engineer | compass |
+| principal | crown |
+| frontend | layout |
+| backend | server |
+| infrastructure | cloud |
+| performance | gauge |
+| accessibility | accessibility |
+| data | database |
+| devops | rocket |
+| dx | terminal |
+| mobile | smartphone |
+| security | shield-alert |
+| quality | sparkles |
+| testing | test-tubes |
+| ai | bot |
+| *(persona)* | brain |
+| *(custom)* | user |
+
+**Notes**
+
+- The `ocr` CLI path may be provided in the CLI Resolution section above. If so, use that path instead of bare `ocr`.
+- The CLI's `--stdin` mode is the mechanism that ensures the final `reviewers-meta.json` is valid. Always pipe through it rather than writing the file directly.

package/package.json

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

package/skills/ocr/references/final-template.md

@@ -23,7 +23,8 @@ This synthesis process is designed to mirror how high-performing engineering tea
 
 - **Preserve all feedback** — Every finding from every reviewer appears, attributed
 - **Identify blockers** — Surface anything that should prevent merge
-- **Present suggestions** — Non-blocking improvements for author consideration
+- **Categorize should-fix items** — Issues that aren't blocking but should be addressed
+- **Present suggestions** — Lower-priority improvements for author consideration
 - **Assess requirements** — Evaluate against provided requirements (if any)
 - **Recommend action** — Clear verdict with rationale
 
@@ -53,11 +54,49 @@ A finding is a **blocker** if ANY of the following are true:
 
 **Any single reviewer can flag a blocker.** This is not subject to consensus—one engineer seeing a security hole is sufficient to block.
 
-### Step 3: Collect Suggestions
+### Step 3: Categorize Non-Blocking Findings
 
-All non-blocking feedback is preserved and attributed:
+All non-blocking feedback is categorized into **Should Fix** or **Suggestions**, then preserved and attributed.
+
+**Should Fix** — Issues that aren't blocking but should be addressed before or shortly after merge:
+
+| Should Fix Criteria | Examples |
+|---------------------|----------|
+| **Code quality issues** | Missing error handling, dead code, untested critical paths |
+| **Potential bugs** | Silent fallthrough, unvalidated input at boundaries, race conditions (non-data-loss) |
+| **Important refactors** | DRY violations with real maintenance cost, tight coupling between modules |
+| **Missing validation** | Input boundaries not enforced, missing null checks on external data |
+| **Functional gaps** | Feature partially implemented, edge case not handled |
+
+**Suggestions** — Low-priority improvements for author consideration:
+
+| Suggestion Criteria | Examples |
+|---------------------|----------|
+| **Style preferences** | Naming, formatting, early returns vs nested ifs |
+| **Minor refactors** | Extract small helper, reorder parameters, simplify expression |
+| **Documentation** | Add JSDoc, clarify comment, update README |
+| **Testing ideas** | Additional edge cases, snapshot tests, performance benchmarks |
+| **Informational** | Alternative approaches, FYI notes, future considerations |
 
 ```markdown
+## Should Fix
+
+### 1. {Title}
+
+**Flagged by**: @principal-1, @quality-1
+**Location**: `path/to/file.ts:42-50`
+
+{Description of the issue and why it should be fixed.}
+
+### 2. {Title}
+
+**Flagged by**: @quality-2
+**Location**: `path/to/other-file.ts:15`
+
+{Description.}
+
+---
+
 ## Suggestions
 
 ### Code Quality
@@ -74,7 +113,7 @@ All non-blocking feedback is preserved and attributed:
 - "Edge case for empty input not covered" — @testing-1
 ```
 
-**No suggestion is lost.** Even if only one reviewer mentions something, it surfaces.
+**No feedback is lost.** Even if only one reviewer mentions something, it surfaces.
 
 ### Step 4: Note Consensus and Dissent
 
@@ -200,15 +239,35 @@ The Tech Lead determines the verdict based on simple rules:
 
 ---
 
+## Should Fix
+
+{Issues that aren't blocking but should be addressed. Use numbered sub-headings.}
+
+### 1. {Title}
+
+**Flagged by**: @principal-1, @quality-1
+**Location**: `path/to/file.ts:42-50`
+
+{Description and why it should be fixed.}
+
+### 2. {Title}
+
+**Flagged by**: @quality-2
+**Location**: `path/to/other-file.ts:15`
+
+{Description.}
+
+---
+
 ## Suggestions
 
-{All non-blocking feedback, preserved and attributed}
+{Lower-priority improvements and informational feedback, preserved and attributed.}
 
 ### Code Quality
 - "Consider extracting the validation logic into a separate function" — @principal-1
 - "The error messages could be more user-friendly" — @quality-1
 
-### Performance  
+### Performance
 - "This query could benefit from an index on `user_id`" — @principal-2
 
 ### Testing
@@ -271,12 +330,12 @@ The Tech Lead determines the verdict based on simple rules:
 
 Full reviews available in session directory:
 
-| Reviewer | Blockers | Suggestions | File |
-|----------|----------|-------------|------|
-| @principal-1 | 0 | 3 | `rounds/round-{n}/reviews/principal-1.md` |
-| @principal-2 | 0 | 2 | `rounds/round-{n}/reviews/principal-2.md` |
-| @quality-1 | 0 | 4 | `rounds/round-{n}/reviews/quality-1.md` |
-| @security-1 | 1 | 2 | `rounds/round-{n}/reviews/security-1.md` |
+| Reviewer | Blockers | Should Fix | Suggestions | File |
+|----------|----------|------------|-------------|------|
+| @principal-1 | 0 | 1 | 3 | `rounds/round-{n}/reviews/principal-1.md` |
+| @principal-2 | 0 | 0 | 2 | `rounds/round-{n}/reviews/principal-2.md` |
+| @quality-1 | 0 | 1 | 4 | `rounds/round-{n}/reviews/quality-1.md` |
+| @security-1 | 1 | 0 | 2 | `rounds/round-{n}/reviews/security-1.md` |
 
 **Session**: `.ocr/sessions/{session-id}/`
 **Discourse**: `rounds/round-{n}/discourse.md`

package/skills/ocr/references/map-workflow.md

@@ -405,10 +405,49 @@ See `references/map-personas/flow-analyst.md` for persona details.
    [ "$EXPECTED" -ne "$MAPPED" ] && echo "ERROR: Missing files!"
    ```
 
-11. **Save final map**:
+11. **Pipe structured map data to CLI**:
+
+    Construct a JSON object with the map's structured data and pipe it to the CLI. The CLI validates, writes `map-meta.json`, and records a `map_completed` orchestration event — all in one command.
+
+    ```bash
+    cat <<'JSON' | ocr state map-complete --stdin
+    {
+      "schema_version": 1,
+      "sections": [
+        {
+          "section_number": 1,
+          "title": "Section Title",
+          "description": "Section description",
+          "files": [
+            {
+              "file_path": "src/example.ts",
+              "role": "Entry point",
+              "lines_added": 10,
+              "lines_deleted": 2
+            }
+          ]
+        }
+      ],
+      "dependencies": [
+        {
+          "from_section": 2,
+          "from_title": "Tests",
+          "to_section": 1,
+          "to_title": "Core Logic",
+          "relationship": "tests"
+        }
+      ]
+    }
+    JSON
+    ```
+
+    > The CLI validates the JSON schema, writes `map-meta.json` to the correct run directory, and records the event in SQLite. The orchestrator MUST NOT write `map-meta.json` directly.
+
+12. **Save final map** (presentation artifact):
     ```
     .ocr/sessions/{id}/map/runs/run-{n}/map.md
     ```
+    > `map.md` is the human-readable presentation artifact. The dashboard uses `map-meta.json` for structured data; `map.md` is stored as raw markdown for display and chat context.
 
 ### Map Output Format
 
@@ -426,6 +465,7 @@ See `references/map-template.md` for the complete template.
 - [ ] Section Dependencies table generated
 - [ ] File Index complete
 - [ ] Completeness validated (all files appear in tables)
+- [ ] `map-meta.json` piped to CLI via `ocr state map-complete --stdin`
 - [ ] `map.md` written
 - [ ] `ocr state transition` called with `--phase "synthesis"`
 

package/skills/ocr/references/reviewer-task.md

@@ -157,6 +157,44 @@ This PR adds a new user profile API endpoint that returns user data.
 Review this code from a security perspective...
 ```
 
+## Ephemeral Reviewer Variant
+
+When spawning an ephemeral reviewer (from `--reviewer`), use the same task structure but replace the persona section with a synthesized prompt based on the user's description.
+
+**Key differences from library reviewers:**
+- No `.md` file lookup — the persona is synthesized by the Tech Lead from the `--reviewer` value
+- Output file naming: `ephemeral-{n}.md` instead of `{type}-{n}.md`
+- Redundancy is always 1 (ephemeral reviewers are inherently unique)
+- The ephemeral reviewer file MUST include the original description at the top
+
+```markdown
+# Code Review Task: Ephemeral Reviewer
+
+## Your Persona
+
+> **User description**: "{the --reviewer value}"
+
+{Tech Lead's synthesized persona based on the description. This should expand the user's
+description into a focused reviewer identity with clear guidance on what to look for,
+while maintaining the same structure as library reviewer personas.}
+
+## Project Standards
+{same as library reviewers}
+
+## Tech Lead Guidance
+{same as library reviewers}
+
+## Code to Review
+{same as library reviewers}
+
+## Your Task
+{same as library reviewers — full agency, same output format}
+```
+
+**Output format**: Ephemeral reviewers use the exact same output format as library reviewers (`## Summary`, `## Findings`, `## What's Working Well`, etc.). The only addition is the original description quoted at the top of the review file.
+
+---
+
 ## Reviewer Guidelines
 
 ### Be Thorough But Focused