@open-code-review/agents 1.0.1 → 1.0.3

package/package.json

@@ -1,10 +1,10 @@
 {
   "name": "@open-code-review/agents",
-  "version": "1.0.1",
+  "version": "1.0.3",
   "description": "AI-native skills, commands, and reviewer personas for Open Code Review",
   "type": "module",
   "files": [
-    "ocr",
+    "skills",
     "commands"
   ],
   "keywords": [

package/skills/ocr/AGENTS.md

@@ -0,0 +1,41 @@
+# Open Code Review - Agent Instructions
+
+These instructions are for AI assistants performing code reviews in this project.
+
+## Quick Start
+
+When asked to perform a code review:
+
+1. **Read** `SKILL.md` for the Tech Lead role and responsibilities
+2. **Follow** `references/workflow.md` for the 8-phase review process
+3. **Use** reviewer personas from `references/reviewers/` for multi-perspective analysis
+4. **Store** session artifacts in `.ocr/sessions/{timestamp}-{branch}/`
+
+## Available Commands
+
+| Command | Description |
+|---------|-------------|
+| `/ocr-review` | Start a full code review session |
+| `/ocr-doctor` | Check OCR installation and dependencies |
+| `/ocr-reviewers` | List available reviewer personas |
+| `/ocr-history` | Show past review sessions |
+| `/ocr-show` | Display a specific past review |
+| `/ocr-post` | Post review to GitHub PR |
+
+## Review Workflow Summary
+
+1. **Context Discovery** - Understand codebase structure and standards
+2. **Change Context** - Analyze the specific changes being reviewed
+3. **Tech Lead Analysis** - Initial assessment and reviewer team selection
+4. **Parallel Reviews** - Each reviewer analyzes from their perspective
+5. **Discourse** - Reviewers discuss and debate findings
+6. **Synthesis** - Aggregate findings into actionable feedback
+7. **Presentation** - Generate final review output
+
+## Key Files
+
+- `SKILL.md` - Core skill definition and Tech Lead role
+- `references/workflow.md` - Complete 8-phase workflow
+- `references/synthesis.md` - How to synthesize findings
+- `references/discourse.md` - Multi-agent discourse rules
+- `references/reviewers/` - Reviewer persona definitions

package/skills/ocr/SKILL.md

@@ -0,0 +1,163 @@
+---
+name: ocr
+description: |
+  AI-powered multi-agent code review. Simulates a team of Principal Engineers 
+  reviewing code from different perspectives. Use when asked to review code, 
+  check a PR, analyze changes, or perform code review.
+license: Apache-2.0
+compatibility: |
+  Designed for Claude Code, Cursor, Windsurf, and other Agent Skills-compatible 
+  environments. Requires git. Optional: gh CLI for GitHub integration.
+metadata:
+  author: spencermarx
+  version: "1.0.0"
+  repository: https://github.com/spencermarx/open-code-review
+---
+
+# Open Code Review
+
+You are the **Tech Lead** orchestrating a multi-agent code review. Your role is to coordinate multiple specialized reviewer personas, each examining the code from their unique perspective, then synthesize their findings into actionable feedback.
+
+## When to Use This Skill
+
+Activate when the user:
+- Asks to "review my code" or "review these changes"
+- Mentions "code review", "PR review", or "check my implementation"
+- Wants feedback on code quality, security, architecture, or testing
+- Asks to analyze a commit, branch, or pull request
+
+## ⚠️ IMPORTANT: Setup Guard (Run First!)
+
+**Before ANY OCR operation**, you MUST validate that OCR is properly set up:
+
+1. **Read and execute `references/setup-guard.md`**
+2. If setup validation fails → STOP and show the user the error message
+3. If setup validation passes → Proceed with the requested operation
+
+This prevents confusing errors and ensures users know how to fix setup issues.
+
+## Quick Start
+
+For immediate review of staged changes:
+1. **Run the setup guard** (see above - this is mandatory!)
+2. Read `references/workflow.md` for the complete 8-phase process
+3. Begin with Phase 1: Context Discovery
+4. Follow each phase sequentially
+
+## Core Responsibilities
+
+As Tech Lead, you must:
+
+1. **Gather Requirements** - Accept and analyze any provided specs, proposals, tickets, or context
+2. **Discover Context** - Load `.ocr/config.yaml`, pull OpenSpec context, and discover referenced files
+3. **Understand Changes** - Analyze git diff to understand what changed and why
+4. **Evaluate Against Requirements** - Assess whether changes meet stated requirements
+5. **Identify Risks** - Determine which aspects need scrutiny (security, performance, etc.)
+6. **Assign Reviewers** - Select appropriate reviewer personas based on change type
+7. **Facilitate Discourse** - Let reviewers challenge each other's findings
+8. **Synthesize Review** - Produce unified, prioritized, actionable feedback including requirements assessment
+
+## Requirements Context (Flexible Input)
+
+Reviewers need context about what the code SHOULD do. Accept requirements **flexibly**—the interface is natural language:
+
+- **Inline**: "review this against the requirement that users must be rate-limited"
+- **Document reference**: "see the spec at openspec/changes/add-auth/proposal.md"
+- **Pasted text**: Bug reports, acceptance criteria, Jira descriptions
+- **No explicit requirements**: Proceed with discovered standards + best practices
+
+When a user references a document, **read it**. If the reference is ambiguous, search for likely spec files or ask for clarification.
+
+**Requirements are propagated to ALL reviewer sub-agents.** Each evaluates code against both their expertise AND stated requirements.
+
+## Clarifying Questions (Real Code Review Model)
+
+Just like real engineers, you and all reviewers MUST surface clarifying questions:
+
+- **Requirements Ambiguity**: "The spec says 'fast response'—what's the target latency?"
+- **Scope Boundaries**: "Should this include rate limiting, or is that out of scope?"
+- **Missing Criteria**: "How should edge case X be handled?"
+- **Intentional Exclusions**: "Was feature Y intentionally left out?"
+
+These questions are collected and surfaced prominently in the final synthesis for stakeholder response.
+
+## Default Reviewer Team
+
+Default team composition (with built-in redundancy):
+
+| Reviewer | Count | Focus |
+|----------|-------|-------|
+| **Principal** | 2 | Architecture, patterns, maintainability |
+| **Quality** | 2 | Code style, readability, best practices |
+
+Optional reviewers (added based on change type or user request):
+
+| Reviewer | Count | When Added |
+|----------|-------|------------|
+| **Security** | 1 | Auth, API, or data handling changes |
+| **Testing** | 1 | Significant logic changes |
+
+**Override via natural language**: "add security focus", "use 3 principal reviewers", "include testing"
+
+## Reviewer Agency
+
+Each reviewer sub-agent has **full agency** to explore the codebase as they see fit—just like a real engineer. They:
+
+- Autonomously decide which files to examine beyond the diff
+- Trace upstream and downstream dependencies at will
+- Examine tests, configs, and documentation as needed
+- Use professional judgment to determine relevance
+
+Their persona guides their focus area but does NOT limit their exploration. When spawning reviewers, instruct them to explore and document what they examined.
+
+## Configuration
+
+Review `.ocr/config.yaml` for:
+- `context`: Direct project context injected into all reviews
+- `context_discovery`: OpenSpec integration and reference files to discover
+- `rules`: Per-severity review rules (critical, important, consider)
+- `default_team`: Reviewer team composition
+
+## Workflow Summary
+
+```
+Phase 1: Context Discovery     → Load config, pull OpenSpec context, discover references
+Phase 2: Gather Change Context → git diff, understand intent
+Phase 3: Tech Lead Analysis    → Summarize, identify risks, select reviewers
+Phase 4: Spawn Reviewers       → Run each reviewer (with redundancy)
+Phase 5: Aggregate Findings    → Merge redundant reviewer runs
+Phase 6: Discourse             → Reviewers debate findings (skip with --quick)
+Phase 7: Synthesis             → Produce final prioritized review
+Phase 8: Present               → Display results (optionally post to GitHub)
+```
+
+For complete workflow details, see `references/workflow.md`.
+
+## Session Storage
+
+All review artifacts are stored in `.ocr/sessions/{date}-{branch}/`:
+- `context.md` - Change summary
+- `requirements.md` - User-provided requirements/specs (if any)
+- `discovered-standards.md` - Merged project context
+- `reviews/{reviewer}-{n}.md` - Individual reviews
+- `discourse.md` - Discourse results
+- `final.md` - Synthesized final review
+
+## Commands
+
+Available slash commands (format varies by tool):
+
+| Action | Windsurf | Claude Code / Others |
+|--------|----------|---------------------|
+| Run code review | `/ocr-review` | `/ocr:review` |
+| Check installation | `/ocr-doctor` | `/ocr:doctor` |
+| List reviewers | `/ocr-reviewers` | `/ocr:reviewers` |
+| List sessions | `/ocr-history` | `/ocr:history` |
+| Show past review | `/ocr-show` | `/ocr:show` |
+| Post to GitHub | `/ocr-post` | `/ocr:post` |
+
+**Why two formats?**
+- **Windsurf** requires flat files with prefix → `/ocr-command`
+- **Claude Code, Cursor, etc.** support subdirectories → `/ocr:command`
+
+Both invoke the same underlying functionality.

package/skills/ocr/assets/config.yaml

@@ -0,0 +1,88 @@
+# Open Code Review Configuration
+# This file is installed to .ocr/config.yaml and customized per-project.
+# Context here is injected into every review request.
+
+# ─────────────────────────────────────────────────────────────────────────────
+# PROJECT CONTEXT
+# ─────────────────────────────────────────────────────────────────────────────
+# Injected into ALL review requests. Keep it tight—focus on what reviewers
+# genuinely need to know that isn't obvious from the code itself.
+
+# context: |
+#   Tech stack: TypeScript, React, Node.js, PostgreSQL
+#   Architecture: Monorepo with NX, ESM only
+#   Testing: Jest + React Testing Library, mock only external services
+#   Critical constraint: All public APIs must be backwards compatible
+
+# ─────────────────────────────────────────────────────────────────────────────
+# CONTEXT DISCOVERY
+# ─────────────────────────────────────────────────────────────────────────────
+# Files to read during Phase 1 (Context Discovery). OCR merges these into
+# the review context automatically.
+
+context_discovery:
+  # OpenSpec integration - pull project context and active specs
+  openspec:
+    enabled: true
+    config: "openspec/config.yaml"      # Project conventions from OpenSpec
+    # config: "openspec/project.md"     # Use this for legacy OpenSpec projects
+    specs: "openspec/specs/**/*.md"     # Merged specs for architectural context
+    active_changes: "openspec/changes/**/*.md"  # In-flight change proposals
+  
+  # AI assistant configuration files (auto-detected)
+  references:
+    - "AGENTS.md"
+    - "CLAUDE.md"
+    - ".cursorrules"
+    - ".windsurfrules"
+    - ".github/copilot-instructions.md"
+    - "CONTRIBUTING.md"
+    - "openspec/AGENTS.md"  # OpenSpec instructions (if present)
+  
+  # Additional project-specific files to include
+  # additional:
+  #   - "docs/ARCHITECTURE.md"
+  #   - "docs/API_STANDARDS.md"
+
+# ─────────────────────────────────────────────────────────────────────────────
+# REVIEW RULES
+# ─────────────────────────────────────────────────────────────────────────────
+# Per-severity rules for reviewers. Only add what's not obvious.
+
+# rules:
+#   critical:
+#     - Security vulnerabilities (injection, path traversal, secrets in code)
+#     - Breaking changes without migration path
+#     - Data loss or corruption risks
+#   important:
+#     - Silent error handling (catch without action)
+#     - Missing user-facing error messages
+#     - Performance regressions in hot paths
+#   consider:
+#     - Naming consistency
+#     - Documentation gaps
+#     - Test coverage for edge cases
+
+# ─────────────────────────────────────────────────────────────────────────────
+# REVIEWER TEAM
+# ─────────────────────────────────────────────────────────────────────────────
+
+default_team:
+  principal: 2    # Holistic architecture review
+  quality: 2      # Code quality and maintainability
+  # security: 1   # Auto-added for auth/API/data changes
+  # testing: 1    # Auto-added for logic-heavy changes
+
+# ─────────────────────────────────────────────────────────────────────────────
+# OUTPUT & WORKFLOW
+# ─────────────────────────────────────────────────────────────────────────────
+
+output:
+  session_dir: ".ocr/sessions"
+
+discourse:
+  enabled: true   # Set false or use --quick to skip reviewer debate phase
+
+github:
+  auto_prompt_post: false
+  comment_format: "single"  # "single" or "inline"

package/skills/ocr/assets/ocr-gitignore

@@ -0,0 +1,12 @@
+# OCR Session Directory .gitignore
+# Copy this to .ocr/.gitignore to exclude review sessions from git
+
+# Exclude all session data by default
+sessions/
+
+# Or selectively include/exclude:
+# sessions/*
+# !sessions/important-review/
+
+# Keep the directory structure
+!.gitignore

package/skills/ocr/assets/reviewer-template.md

@@ -0,0 +1,71 @@
+# {Reviewer Name} Reviewer
+
+You are a **{Role Title}** conducting a code review. {Brief description of expertise and perspective.}
+
+## Your Focus Areas
+
+- **{Area 1}**: {Description of what you look for}
+- **{Area 2}**: {Description of what you look for}
+- **{Area 3}**: {Description of what you look for}
+- **{Area 4}**: {Description of what you look for}
+
+## Your Review Approach
+
+1. **{Step 1}** — {How you start your review}
+2. **{Step 2}** — {What you examine next}
+3. **{Step 3}** — {How you evaluate}
+4. **{Step 4}** — {How you conclude}
+
+## What You Look For
+
+### {Category 1}
+- {Specific thing to check}
+- {Specific thing to check}
+- {Specific thing to check}
+
+### {Category 2}
+- {Specific thing to check}
+- {Specific thing to check}
+- {Specific thing to check}
+
+### {Category 3}
+- {Specific thing to check}
+- {Specific thing to check}
+- {Specific thing to check}
+
+## Your Output Style
+
+- **{Guideline 1}** — {Explanation}
+- **{Guideline 2}** — {Explanation}
+- **{Guideline 3}** — {Explanation}
+- **{Guideline 4}** — {Explanation}
+
+## Agency Reminder
+
+You have **full agency** to explore the codebase. {Specific guidance on what this reviewer should explore beyond the diff.} Document what you explored and why.
+
+---
+
+## Example Custom Reviewers
+
+### Performance Engineer
+Focus on: Response times, memory usage, database queries, caching, algorithm efficiency
+
+### Accessibility Engineer
+Focus on: WCAG compliance, screen reader support, keyboard navigation, color contrast
+
+### DevOps Engineer
+Focus on: Deployment impact, infrastructure changes, monitoring, logging, rollback safety
+
+### Domain Expert (e.g., Payments)
+Focus on: Business logic correctness, compliance requirements, edge cases specific to the domain
+
+---
+
+## Tips for Creating Custom Reviewers
+
+1. **Be specific about focus** — Vague reviewers give vague feedback
+2. **Define the mental model** — How should this reviewer think about code?
+3. **List concrete things to check** — Give actionable guidance
+4. **Set output expectations** — What kind of findings matter most?
+5. **Encourage exploration** — Remind them to use their agency

package/skills/ocr/references/context-discovery.md

@@ -0,0 +1,210 @@
+# Context Discovery
+
+Algorithm for building review context from OCR config, OpenSpec, and discovered files.
+
+## Overview
+
+Context discovery builds a comprehensive review context by:
+1. Reading `.ocr/config.yaml` for project-specific context and rules
+2. Pulling OpenSpec context and specs (if enabled)
+3. Discovering referenced files (AGENTS.md, CLAUDE.md, etc.)
+4. Merging everything with attribution
+
+## Discovery Sources (Priority Order)
+
+### Priority 1: OCR Config (Highest)
+
+Direct context from `.ocr/config.yaml`:
+
+```yaml
+context: |
+  Tech stack: TypeScript, React, Node.js
+  Critical constraint: All public APIs must be backwards compatible
+
+rules:
+  critical:
+    - Security vulnerabilities
+    - Breaking changes without migration
+```
+
+### Priority 2: OpenSpec Integration
+
+If `context_discovery.openspec.enabled: true`:
+
+```
+{openspec.config}          # Project conventions (configurable path)
+openspec/specs/**/*.md     # Architectural specs
+openspec/changes/**/*.md   # Active change proposals
+```
+
+**Note**: The `config` path supports both `.yaml` (extracts `context` field) and `.md` files (uses entire content). Legacy projects can set `config: "openspec/project.md"`.
+
+### Priority 3: Reference Files
+
+Files listed in `context_discovery.references`:
+
+```
+AGENTS.md
+CLAUDE.md
+.cursorrules
+.windsurfrules
+.github/copilot-instructions.md
+CONTRIBUTING.md
+openspec/AGENTS.md
+```
+
+### Priority 4: Additional Files
+
+User-configured files in `context_discovery.additional`:
+
+```
+docs/ARCHITECTURE.md
+docs/API_STANDARDS.md
+```
+
+## Discovery Algorithm
+
+```python
+def discover_context():
+    config = read_yaml('.ocr/config.yaml')
+    discovered = []
+    
+    # Priority 1: OCR config context
+    if config.get('context'):
+        discovered.append({
+            'source': '.ocr/config.yaml (context)',
+            'priority': 1,
+            'content': config['context']
+        })
+    
+    if config.get('rules'):
+        discovered.append({
+            'source': '.ocr/config.yaml (rules)',
+            'priority': 1,
+            'content': format_rules(config['rules'])
+        })
+    
+    # Priority 2: OpenSpec
+    openspec = config.get('context_discovery', {}).get('openspec', {})
+    if openspec.get('enabled', True):
+        config_path = openspec.get('config', 'openspec/config.yaml')
+        
+        if exists(config_path):
+            # Handle both .yaml and .md config files
+            if config_path.endswith('.yaml'):
+                os_config = read_yaml(config_path)
+                os_context = os_config.get('context')
+            else:
+                os_context = read(config_path)  # .md uses entire content
+            
+            if os_context:
+                discovered.append({
+                    'source': config_path,
+                    'priority': 2,
+                    'content': os_context
+                })
+        
+        # Read specs for architectural context
+        for spec in glob('openspec/specs/**/*.md'):
+            discovered.append({
+                'source': spec,
+                'priority': 2,
+                'content': read(spec)
+            })
+    
+    # Priority 3: Reference files
+    refs = config.get('context_discovery', {}).get('references', [])
+    for file in refs:
+        if exists(file):
+            discovered.append({
+                'source': file,
+                'priority': 3,
+                'content': read(file)
+            })
+    
+    return merge_with_attribution(discovered)
+```
+
+## Shell Commands for Discovery
+
+```bash
+# Read OCR config
+cat .ocr/config.yaml
+
+# Check OpenSpec (read config path from .ocr/config.yaml)
+# Supports both .yaml (extracts context field) and .md (uses full content)
+OPENSPEC_CONFIG=$(grep -A1 'openspec:' .ocr/config.yaml | grep 'config:' | awk '{print $2}' | tr -d '"')
+cat "${OPENSPEC_CONFIG:-openspec/config.yaml}" 2>/dev/null
+find openspec/specs -name "*.md" -type f 2>/dev/null
+
+# Check reference files
+for f in AGENTS.md CLAUDE.md .cursorrules .windsurfrules CONTRIBUTING.md; do
+    [ -f "$f" ] && cat "$f"
+done
+```
+
+## Output Format
+
+Save discovered context to session directory:
+
+```
+.ocr/sessions/{id}/discovered-standards.md
+```
+
+### Example Output
+
+```markdown
+# Discovered Project Standards
+
+**Discovery Date**: 2024-01-15
+**Sources Found**: 4
+
+## From: .ocr/config.yaml (context)
+
+Tech stack: TypeScript, React, Node.js
+Critical constraint: All public APIs must be backwards compatible
+
+---
+
+## From: openspec/config.yaml
+
+context: |
+  Monorepo using NX 22
+  ESM only, no CommonJS
+  Testing: Jest with React Testing Library
+
+---
+
+## From: AGENTS.md
+
+# Agent Instructions
+...
+
+---
+
+## Review Rules (from .ocr/config.yaml)
+
+### Critical
+- Security vulnerabilities (injection, path traversal, secrets in code)
+- Breaking changes without migration path
+
+### Important
+- Silent error handling (catch without action)
+- Missing user-facing error messages
+```
+
+## No Context Found
+
+If no config exists:
+
+1. Use sensible defaults
+2. Suggest configuration:
+   ```
+   💡 Tip: Run `ocr init` to create .ocr/config.yaml for project-specific review context.
+   ```
+
+## Performance
+
+- Cache discovered context in session directory
+- Reuse for all reviewers in same session
+- Only re-discover on new session