@open-code-review/agents 1.0.0

package/README.md

@@ -0,0 +1,83 @@
+# @open-code-review/agents
+
+AI-native skills, commands, and reviewer personas for Open Code Review.
+
+## Overview
+
+This package contains static assets for AI-powered code review:
+
+- **Skills** (`skills/ocr/`) - Core skill definitions and workflow references
+- **Commands** (`commands/`) - Slash command definitions for AI tools
+
+## Installation
+
+### Option 1: CLI (Multi-Tool Support)
+
+Works with Claude Code, Cursor, Windsurf, and 10+ other AI tools:
+
+```bash
+npx @open-code-review/cli init
+```
+
+### Option 2: Claude Code Plugin
+
+Native Claude Code integration with automatic updates:
+
+```bash
+# Add the marketplace
+/plugin marketplace add open-code-review/open-code-review
+
+# Install the plugin
+/plugin install open-code-review
+```
+
+Or test locally:
+
+```bash
+claude --plugin-dir ./packages/agents
+```
+
+## Package Structure
+
+```
+packages/agents/
+├── .claude-plugin/
+│   └── plugin.json       # Claude Code plugin manifest
+├── commands/             # Slash commands (→ /open-code-review:review)
+│   ├── review.md
+│   ├── doctor.md
+│   └── ...
+└── skills/
+    └── ocr/              # Main OCR skill
+        ├── SKILL.md      # Core Tech Lead skill
+        ├── AGENTS.md     # AI assistant instructions
+        ├── references/   # Workflow, reviewers, etc.
+        └── assets/       # Templates, config
+```
+
+## Skills (`skills/ocr/`)
+
+| File | Description |
+|------|-------------|
+| `SKILL.md` | Core Tech Lead skill definition |
+| `AGENTS.md` | Instructions for AI assistants |
+| `references/workflow.md` | 8-phase review workflow |
+| `references/synthesis.md` | Finding synthesis guide |
+| `references/discourse.md` | Multi-agent discourse rules |
+| `references/reviewers/*.md` | Reviewer persona definitions |
+| `assets/config.yaml` | Configuration template (installed to `.ocr/config.yaml`) |
+
+## Commands (`commands/`)
+
+| Command | CLI Format | Plugin Format |
+|---------|------------|---------------|
+| `review.md` | `/ocr:review` | `/open-code-review:review` |
+| `doctor.md` | `/ocr:doctor` | `/open-code-review:doctor` |
+| `reviewers.md` | `/ocr:reviewers` | `/open-code-review:reviewers` |
+| `history.md` | `/ocr:history` | `/open-code-review:history` |
+| `show.md` | `/ocr:show` | `/open-code-review:show` |
+| `post.md` | `/ocr:post` | `/open-code-review:post` |
+
+## License
+
+MIT

package/commands/doctor.md

@@ -0,0 +1,37 @@
+---
+description: Check OCR installation and verify all dependencies are available.
+name: "OCR: Doctor"
+category: Code Review
+tags: [ocr, setup, diagnostics]
+---
+
+**Usage**
+```
+/ocr-doctor
+```
+
+**Steps**
+
+1. **Check OCR Installation**
+   - Verify `.ocr/skills/SKILL.md` exists and is readable
+   - Verify `references/` directory contains required workflow files
+
+2. **Check Git**
+   - Verify `git` is available in PATH
+   - Verify current directory is a git repository
+
+3. **Check GitHub CLI** (optional)
+   - Check if `gh` is available
+   - If available, verify authentication with `gh auth status`
+
+4. **Report Status**
+   ```
+   ✓ OCR skill installed
+   ✓ Git available (version X.X.X)
+   ✓ GitHub CLI available and authenticated
+   
+   Ready for code review!
+   ```
+
+**Reference**
+- Run `/ocr-review` to start a code review

package/commands/history.md

@@ -0,0 +1,32 @@
+---
+description: List past OCR review sessions.
+name: "OCR: History"
+category: Code Review
+tags: [ocr, history, sessions]
+---
+
+**Usage**
+```
+/ocr-history
+```
+
+**Steps**
+
+1. Read `.ocr/sessions/` directory
+2. List sessions in reverse chronological order
+3. For each session, show:
+   - Session ID (date-branch)
+   - Branch/target reviewed
+   - Number of reviewers
+   - Final verdict (if complete)
+
+**Output Format**
+```
+| Session                    | Target        | Reviewers | Verdict |
+|----------------------------|---------------|-----------|---------|
+| 2025-01-26-feature-auth    | feature/auth  | 4         | Approve |
+| 2025-01-25-fix-bug         | fix/bug-123   | 2         | Block   |
+```
+
+**Reference**
+- Use `/ocr-show <session>` to view a past review

package/commands/post.md

@@ -0,0 +1,28 @@
+---
+description: Post the current OCR review to a GitHub PR.
+name: "OCR: Post"
+category: Code Review
+tags: [ocr, github, pr]
+---
+
+**Usage**
+```
+/ocr-post [session]
+```
+
+**Arguments**
+- `session` (optional): Session ID to post. Defaults to most recent.
+
+**Prerequisites**
+- GitHub CLI (`gh`) must be installed and authenticated
+- Must be on a branch with an open PR
+
+**Steps**
+
+1. Verify `gh` is available and authenticated
+2. Find the PR for current branch
+3. Read the session's `final.md`
+4. Post as PR comment via `gh pr comment`
+
+**Reference**
+- Run `/ocr-doctor` to check GitHub CLI status

package/commands/review.md

@@ -0,0 +1,100 @@
+---
+description: Run an AI-powered multi-agent code review on your changes.
+name: "OCR: Review"
+category: Code Review
+tags: [ocr, review, code-review]
+---
+
+**Usage**
+```
+/ocr-review [target] [--fresh]
+```
+
+**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.
+
+**Examples**
+```
+/ocr-review                    # Review staged changes
+/ocr-review --fresh            # Clear today's session and start fresh
+/ocr-review HEAD~3             # Review last 3 commits
+/ocr-review feature/auth       # Review branch vs main
+/ocr-review src/api/           # Review specific directory
+```
+
+**Steps**
+
+1. **Session State Check** (CRITICAL - do this first!)
+2. Load the OCR skill from `.ocr/skills/SKILL.md`
+3. Execute the 8-phase review workflow defined in `.ocr/skills/references/workflow.md`
+4. Store results in `.ocr/sessions/{date}-{branch}/`
+
+---
+
+## 🔍 Session State Check (Phase 0)
+
+Before starting any review work, you MUST 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: If session exists, verify state
+
+Read `state.json` AND verify actual files match:
+
+| Phase | state.json says | Verify file exists |
+|-------|-----------------|-------------------|
+| context | `completed_phases` includes "context" | `.ocr/sessions/{id}/context.md` |
+| requirements | `completed_phases` includes "requirements" | `.ocr/sessions/{id}/discovered-standards.md` |
+| reviews | `completed_phases` includes "reviews" | At least 2 files in `.ocr/sessions/{id}/reviews/` |
+| discourse | `completed_phases` includes "discourse" | `.ocr/sessions/{id}/discourse.md` |
+| synthesis | `completed_phases` includes "synthesis" | `.ocr/sessions/{id}/final.md` |
+
+### Step 3: Determine action
+
+- **If `--fresh` flag**: Delete the session directory and start from Phase 1
+- **If state.json missing but files exist**: Recreate state.json from file existence
+- **If state.json exists and files match**: Resume from `current_phase`
+- **If state.json and files mismatch**: Report discrepancy and ask user which to trust
+- **If no session exists**: Start fresh from Phase 1
+
+---
+
+## ⚠️ CRITICAL: Required Artifacts (Must Create In Order)
+
+You MUST create these files sequentially. **Do NOT skip to `final.md`.**
+
+```
+.ocr/sessions/{id}/
+├── context.md              # Phase 2: WRITE FIRST - change summary
+├── discovered-standards.md # Phase 1: merged project standards  
+├── reviews/
+│   ├── principal-1.md      # Phase 4: individual reviewer output
+│   ├── principal-2.md      # Phase 4: individual reviewer output
+│   ├── quality-1.md        # Phase 4: individual reviewer output
+│   └── {reviewer}-{n}.md    # Phase 4: individual reviewer output
+├── discourse.md            # Phase 6: reviewer cross-discussion
+└── final.md                # Phase 7: ONLY after all above exist
+```
+
+### Checkpoint Rules
+
+1. **Before Phase 4** (Spawn Reviewers): `context.md` MUST exist
+2. **Before Phase 6** (Discourse): At least 2 files in `reviews/` MUST exist
+3. **Before Phase 7** (Synthesis): `discourse.md` MUST exist
+4. **NEVER** write `final.md` without completing Phases 1-6
+
+### Why This Matters
+
+The `ocr progress` CLI watches these files to show real-time progress. If you skip files, the progress display breaks and users see incorrect state.
+
+---
+
+**Reference**
+- See `.ocr/skills/SKILL.md` for full Tech Lead instructions
+- See `.ocr/skills/references/workflow.md` for detailed workflow phases

package/commands/reviewers.md

@@ -0,0 +1,30 @@
+---
+description: List all available reviewer personas for code review.
+name: "OCR: Reviewers"
+category: Code Review
+tags: [ocr, reviewers, config]
+---
+
+**Usage**
+```
+/ocr-reviewers
+```
+
+**Steps**
+
+1. Read `.ocr/skills/references/reviewers/` directory
+2. For each reviewer file, extract name and focus area
+3. Display in table format:
+
+```
+| Reviewer   | Focus                                    |
+|------------|------------------------------------------|
+| Principal  | Architecture, patterns, maintainability  |
+| Quality    | Code style, readability, best practices  |
+| Security   | Auth, vulnerabilities, data handling     |
+| Testing    | Test coverage, edge cases, assertions    |
+```
+
+**Reference**
+- Reviewer definitions are in `.ocr/skills/references/reviewers/`
+- See `.ocr/skills/assets/reviewer-template.md` to create custom reviewers

package/commands/show.md

@@ -0,0 +1,24 @@
+---
+description: Display a past OCR review session.
+name: "OCR: Show"
+category: Code Review
+tags: [ocr, history, sessions]
+---
+
+**Usage**
+```
+/ocr-show [session]
+```
+
+**Arguments**
+- `session` (optional): Session ID to display. Defaults to most recent.
+
+**Steps**
+
+1. If no session specified, find most recent in `.ocr/sessions/`
+2. Read and display `final.md` (synthesized review)
+3. Optionally show individual reviewer files if requested
+
+**Reference**
+- Use `/ocr-history` to list all sessions
+- Use `/ocr-post` to post a review to GitHub

package/package.json

@@ -0,0 +1,29 @@
+{
+  "name": "@open-code-review/agents",
+  "version": "1.0.0",
+  "description": "AI-native skills, commands, and reviewer personas for Open Code Review",
+  "type": "module",
+  "files": [
+    "ocr",
+    "commands"
+  ],
+  "keywords": [
+    "code-review",
+    "ai",
+    "agents",
+    "skills",
+    "claude",
+    "cursor",
+    "windsurf"
+  ],
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/spencermarx/open-code-review",
+    "directory": "packages/agents"
+  },
+  "license": "MIT",
+  "author": "Spencer Marx",
+  "publishConfig": {
+    "access": "public"
+  }
+}