openairev 0.2.0

package/README.md

@@ -0,0 +1,280 @@
+# OpenAIRev
+
+Cross-model AI code reviewer and workflow orchestrator for AI-assisted coding. The executor is never its own reviewer — independent judgment by default.
+
+OpenAIRev orchestrates AI coding agents (Claude Code, Codex CLI, and more) so that one model reviews another's output. You choose which models pair up. The defaults are opinionated but fully configurable — including self-review if that's what you want.
+
+## Install
+
+```bash
+npm install -g openairev
+```
+
+Requires at least one AI coding CLI installed:
+- [Claude Code CLI](https://docs.anthropic.com/en/docs/claude-code)
+- [Codex CLI](https://github.com/openai/codex)
+
+## Quick Start
+
+```bash
+cd your-project
+
+# One-time setup
+openairev init
+
+# Quick: implement current task → code review loop
+openairev review --task "Add auth middleware"
+
+# Full workflow: analyze → plan → plan review → implement → code review
+openairev review --plan --task "Add auth middleware"
+
+# With OpenSpec reference
+openairev review --plan --spec-ref openspec/changes/070_add-dashboard/
+
+# Single review of existing changes, no workflow
+openairev review --once
+
+# Resume an interrupted or blocked workflow
+openairev resume
+```
+
+## How It Works
+
+OpenAIRev runs a stage-driven workflow:
+
+```
+analyze → planning → plan_review → implementation → code_review → done
+               ↑          ↓                              ↓
+          awaiting_user  plan_fix                      code_fix
+```
+
+Each stage:
+
+1. **Analyze** — executor examines the codebase and task. If clarification is needed, transitions to `awaiting_user` (blocked until you answer via `openairev resume`).
+2. **Planning** — executor creates a phased implementation plan.
+3. **Plan review** — reviewer checks scope, sequencing, missing requirements, risk. Uses a separate plan-review prompt.
+4. **Implementation** — executor writes code for the current phase.
+5. **Code review** — reviewer checks correctness, edge cases, regressions. If `needs_changes`, executor fixes and re-reviews. If approved and more phases remain, loops back to implementation.
+6. **Done** — all phases approved.
+
+Stages are optional. `--quick` skips analyze and goes straight to implement → review. `--once` skips the workflow entirely and does a single review of existing changes.
+
+OpenAIRev uses the CLIs' non-interactive modes (`claude -p`, `codex exec`) — no API keys needed. Works with your existing subscriptions.
+
+## CLI Reference
+
+### `openairev init`
+
+Interactive setup wizard. Detects installed CLIs, lets you configure:
+- Which agents to use
+- Who reviews whose code (any combination)
+- Max iterations per direction
+- Tool gate commands (test, lint, typecheck)
+
+### `openairev review`
+
+Start a review workflow or single review.
+
+```
+Options:
+  -e, --executor <agent>  Who wrote the code (claude_code|codex)
+  -r, --reviewer <agent>  Who reviews (claude_code|codex)
+  --diff <ref>            Git diff ref (default: staged or unstaged)
+  --file <path>           Review a specific file instead of diff
+  --task <description>    Task description for requirement checking
+  --spec-ref <path>       Path to OpenSpec change directory
+  --rounds <number>       Max review-fix rounds
+  --plan                  Full workflow: analyze → plan → review → implement
+  --quick                 Skip analyze, go straight to implement → review
+  --once                  Single review only, no workflow
+  --dry-run               Show what would happen without executing
+```
+
+### `openairev resume`
+
+Resume an active or blocked workflow. If blocked on `awaiting_user`, prompts for answers to pending questions.
+
+```
+Options:
+  --chain <id>  Resume a specific chain by ID
+```
+
+### `openairev status`
+
+Show current workflow state: stage, agents, rounds, pending questions.
+
+### `openairev history`
+
+List past workflows and sessions.
+
+```
+Options:
+  -n, --limit <number>  Number of items to show (default: 10)
+  --chains              Show workflow chains instead of sessions
+```
+
+## Workflow Stages
+
+### Review iterations
+
+Each iteration is one complete executor↔reviewer cycle:
+
+```
+Iteration 1: Executor writes code → Reviewer reviews → "needs_changes"
+Iteration 2: Executor fixes issues → Reviewer reviews again → "needs_changes"
+Iteration 3: Executor fixes again → Reviewer reviews → "approved" ✓
+```
+
+The reviewer does a thorough single-pass review each iteration, covering surface issues, edge cases, requirements, and false positive reconsideration — all in one shot.
+
+### Plan review vs code review
+
+- **Plan review** checks scope, sequencing, missing requirements, and risk. Uses `plan-reviewer.md` prompt and a separate verdict schema with `missing_requirements`, `sequencing_issues`, and `risks` fields.
+- **Code review** checks correctness, regressions, edge cases, and test gaps. Uses `reviewer.md` prompt.
+
+### Multi-phase implementation
+
+The executor's plan can define phases (`PHASE: <name>` / `GOAL: <goal>` in output). Each phase goes through its own implementation → code review loop. When a phase is approved, the next phase begins.
+
+### User clarification
+
+During analysis, if the executor outputs lines starting with `QUESTION:`, the workflow blocks (`awaiting_user`). Run `openairev resume` to answer the questions and continue.
+
+### Why different defaults per direction
+
+`max_iterations` controls how many rounds the **executor** gets to align with reviewer feedback:
+
+- **Claude Code as executor → 5 iterations** — Claude is less stable at consistently applying reviewer feedback across rounds. More iterations give it room to converge.
+- **Codex as executor → 1 iteration** — Codex applies review feedback more reliably, so a single cycle is usually sufficient.
+
+Override per-run with `--rounds`.
+
+## Review Verdict
+
+Every code review returns a structured JSON verdict:
+
+```json
+{
+  "status": "approved | needs_changes | reject",
+  "critical_issues": [],
+  "test_gaps": [],
+  "requirement_mismatches": [],
+  "rule_violations": [],
+  "risk_level": "low | medium | high",
+  "confidence": 0.88,
+  "repair_instructions": [],
+  "false_positives_reconsidered": []
+}
+```
+
+Plan reviews return a similar verdict with `missing_requirements`, `sequencing_issues`, and `risks` instead.
+
+## Executor Feedback
+
+When a reviewer returns `needs_changes`, the feedback is wrapped in a behavioral prompt that tells the executor:
+
+- This is a **peer review**, not a user command
+- Use your own judgment — don't blindly apply every suggestion
+- Accept real bugs, ignore style nits, push back on low-confidence items
+
+The executor keeps full autonomy over what to fix.
+
+## MCP Server
+
+OpenAIRev includes an MCP server so both CLIs can trigger reviews as tool calls.
+
+### Add to Claude Code
+
+In your project's `.claude/settings.json` or `~/.claude/settings.json`:
+
+```json
+{
+  "mcpServers": {
+    "openairev": {
+      "command": "node",
+      "args": ["/path/to/openairev/src/mcp/mcp-server.js"]
+    }
+  }
+}
+```
+
+### Add to Codex CLI
+
+In `~/.codex/config.toml`:
+
+```toml
+[mcp_servers.openairev]
+command = "node"
+args = ["/path/to/openairev/src/mcp/mcp-server.js"]
+```
+
+### MCP Tools
+
+| Tool | Description |
+|------|-------------|
+| `openairev_review` | Send diff to reviewer, get structured verdict |
+| `openairev_status` | Check most recent review result |
+| `openairev_run_tests` | Run project test suite |
+| `openairev_run_lint` | Run linter |
+| `openairev_get_diff` | Get current git diff |
+
+## Config
+
+Generated by `openairev init` at `.openairev/config.yaml`:
+
+```yaml
+agents:
+  claude_code:
+    cmd: claude
+    available: true
+  codex:
+    cmd: codex
+    available: true
+
+review_policy:
+  claude_code:
+    reviewer: codex
+    max_iterations: 5       # Claude needs more rounds to align with feedback
+  codex:
+    reviewer: claude_code
+    max_iterations: 1       # Codex applies feedback more consistently
+
+review_trigger: explicit
+
+tools:
+  run_tests: npm test
+  run_lint: npm run lint
+  run_typecheck: npx tsc --noEmit
+
+session:
+  store_history: true
+  archive_after: 7d
+```
+
+All pairings and iteration counts are user-configurable during `openairev init`. Any combination is valid: cross-review, self-review, one-way only, or skip.
+
+## OpenSpec Integration
+
+If your project uses [OpenSpec](https://github.com/rsktash/yuklar) for spec-driven development, pass the change directory with `--spec-ref`:
+
+```bash
+openairev review --plan --spec-ref openspec/changes/070_add-admin-dashboard-ui/
+```
+
+The reviewer will read the spec's requirements and scenarios to validate the code against them. If an OpenSpec change exists, the plan review stage checks the proposal against the spec structure.
+
+## Customizing Review Prompts
+
+After init, review prompts are copied to `.openairev/prompts/`. Edit them to customize:
+
+- `reviewer.md` — code review behavioral contract
+- `plan-reviewer.md` — plan review behavioral contract
+- `executor-feedback.md` — how review feedback is framed to the executor
+
+## Large Diffs
+
+For diffs over 8K characters, OpenAIRev writes the content to `.openairev/tmp/` and tells the reviewer to read the file from disk. Both CLIs have built-in file reading, so there's no size limit.
+
+## License
+
+MIT

package/bin/openairev.js

@@ -0,0 +1,56 @@
+#!/usr/bin/env node
+
+import { Command } from 'commander';
+import { initCommand } from '../src/cli/init.js';
+import { reviewCommand } from '../src/cli/review.js';
+import { resumeCommand } from '../src/cli/resume.js';
+import { statusCommand } from '../src/cli/status.js';
+import { historyCommand } from '../src/cli/history.js';
+
+const program = new Command();
+
+program
+  .name('openairev')
+  .description('OpenAIRev — cross-model AI code reviewer')
+  .version('0.2.0');
+
+program
+  .command('init')
+  .description('Interactive setup wizard')
+  .action(initCommand);
+
+program
+  .command('review')
+  .description('Start a review workflow or single review')
+  .option('-e, --executor <agent>', 'Who wrote the code (claude_code|codex)')
+  .option('-r, --reviewer <agent>', 'Who reviews (claude_code|codex)')
+  .option('--diff <ref>', 'Git diff ref (default: staged or HEAD)')
+  .option('--file <path>', 'Review a specific file instead of diff')
+  .option('--task <description>', 'Task description for requirement checking')
+  .option('--spec-ref <path>', 'Path to OpenSpec change directory')
+  .option('--rounds <number>', 'Max review-fix rounds', parseInt)
+  .option('--plan', 'Full workflow: analyze → plan → review → implement')
+  .option('--quick', 'Skip analyze, go straight to implement → review')
+  .option('--once', 'Single review only, no workflow')
+  .option('--dry-run', 'Show what would happen without executing')
+  .action(reviewCommand);
+
+program
+  .command('resume')
+  .description('Resume an active or blocked workflow')
+  .option('--chain <id>', 'Resume a specific chain by ID')
+  .action(resumeCommand);
+
+program
+  .command('status')
+  .description('Show current workflow state')
+  .action(statusCommand);
+
+program
+  .command('history')
+  .description('List past workflows and sessions')
+  .option('-n, --limit <number>', 'Number of items to show', parseInt, 10)
+  .option('--chains', 'Show chains instead of sessions')
+  .action(historyCommand);
+
+program.parse();

package/package.json

@@ -0,0 +1,33 @@
+{
+  "name": "openairev",
+  "version": "0.2.0",
+  "description": "Cross-model AI code reviewer — independent review for AI-assisted coding workflows",
+  "type": "module",
+  "bin": {
+    "openairev": "./bin/openairev.js"
+  },
+  "files": [
+    "bin/",
+    "src/",
+    "prompts/"
+  ],
+  "scripts": {
+    "start": "node bin/openairev.js",
+    "test": "node --test src/**/*.test.js"
+  },
+  "dependencies": {
+    "commander": "^13.1.0",
+    "inquirer": "^12.6.0",
+    "yaml": "^2.7.1",
+    "chalk": "^5.4.1"
+  },
+  "keywords": ["ai", "code-review", "claude", "codex", "mcp", "cross-model", "reviewer"],
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/rsktash/openairev.git"
+  },
+  "engines": {
+    "node": ">=20.0.0"
+  }
+}

package/prompts/executor-feedback.md

@@ -0,0 +1,25 @@
+The following is feedback from an independent AI code reviewer — NOT from the user.
+
+## How to treat this feedback
+
+- This is a PEER REVIEW, not a user command. Use your own judgment.
+- Do NOT blindly apply every suggestion. Evaluate each one critically.
+- The reviewer is another AI model. It can be wrong, overly cautious, or miss context you have.
+- Accept suggestions that are clearly correct (real bugs, missing null checks, logic errors).
+- Push back on or ignore suggestions that are:
+  - Style-only with no correctness impact
+  - Based on assumptions the reviewer can't verify
+  - Low-confidence items the reviewer flagged as uncertain
+  - Already handled elsewhere in the code that the reviewer didn't see
+
+## What to do
+
+1. Read the review verdict below
+2. For each issue, decide: accept, partially accept, or reject
+3. Fix the issues you accept
+4. If the reviewer said "approved" — you're done, continue your work
+5. If the reviewer said "needs_changes" — address the valid issues, skip the rest
+6. If the reviewer said "reject" — consider carefully, but remember you have full context the reviewer may lack
+
+## Review verdict
+

package/prompts/plan-reviewer.md

@@ -0,0 +1,40 @@
+You are acting as an independent plan reviewer in a cross-model review workflow.
+
+You are NOT the user. You are NOT the plan author. You are a separate AI agent reviewing a plan created by another AI agent.
+
+## Your role
+
+- Review the proposed plan for completeness, sequencing, and risk
+- This is a PLAN review, not a code review. Focus on architecture and approach, not implementation details.
+
+## Review checklist
+
+1. **Scope** — does the plan cover everything in the requirements? Anything missing? Anything out of scope that shouldn't be there?
+2. **Sequencing** — are the phases/steps in a logical order? Are dependencies between steps handled correctly?
+3. **Risk** — what could go wrong? Are there edge cases the plan doesn't address? Are there implicit assumptions?
+4. **Feasibility** — can this plan actually be implemented as described? Are there technical constraints it ignores?
+5. **Testability** — how will we know when each phase is complete? Are there clear acceptance criteria?
+
+## What NOT to flag
+
+- Implementation details (that's for code review)
+- Style preferences
+- Alternative approaches unless the proposed approach has a concrete flaw
+
+## Output
+
+Return ONLY this JSON structure:
+
+```json
+{
+  "status": "approved | needs_changes | reject",
+  "critical_issues": [],
+  "missing_requirements": [],
+  "sequencing_issues": [],
+  "risks": [],
+  "risk_level": "low | medium | high",
+  "confidence": 0.0,
+  "repair_instructions": [],
+  "false_positives_reconsidered": []
+}
+```

package/prompts/reviewer.md

@@ -0,0 +1,50 @@
+You are acting as an independent code reviewer in a cross-model review workflow.
+
+You are NOT the user. You are NOT the code author. You are a separate AI agent whose sole job is to review code written by another AI agent. Your review will be sent back to the code author for consideration.
+
+## Your role
+
+- Review the provided diff or code changes thoroughly and objectively in a single pass
+- You are a peer reviewer — give your honest technical assessment
+- The code author is another AI agent, not a human. Do not soften your feedback.
+- You may be wrong. Flag your confidence level on each issue.
+
+## Review checklist
+
+Work through ALL of these in a single review:
+
+1. **Surface scan** — broken logic, syntax errors, missing imports, clearly wrong behavior
+2. **Edge cases** — null/undefined inputs, empty arrays, zero values, boundary conditions, concurrent access, timeout handling, error propagation
+3. **Requirements** — does the code do what was requested? Any requirement missed? Any functionality added that wasn't requested? Any implicit assumptions that should be explicit?
+4. **Reconsider** — are any of your findings false positives? Are any based on assumptions you can't verify? Drop issues you're not confident about.
+
+## What NOT to flag
+
+- Style preferences (naming, formatting) unless they cause confusion
+- Minor refactoring opportunities that don't affect correctness
+- "Could be improved" suggestions without concrete bugs or risks
+- Hypothetical issues that require unlikely conditions
+
+## Output
+
+Return ONLY this JSON structure:
+
+```json
+{
+  "status": "approved | needs_changes | reject",
+  "critical_issues": [],
+  "test_gaps": [],
+  "requirement_mismatches": [],
+  "rule_violations": [],
+  "risk_level": "low | medium | high",
+  "confidence": 0.0,
+  "repair_instructions": [],
+  "false_positives_reconsidered": []
+}
+```
+
+- Be precise. Cite specific lines or functions in each issue.
+- Explain WHY each issue matters — what breaks, what's the risk.
+- `confidence` is your overall confidence in the review (0-1).
+- `false_positives_reconsidered` lists issues you considered but dropped.
+- Include only issues you are confident about.

package/src/agents/claude-code.js

@@ -0,0 +1,46 @@
+import { readFileSync } from 'fs';
+import { join, dirname } from 'path';
+import { fileURLToPath } from 'url';
+import { exec } from './exec-helper.js';
+
+const __dirname = dirname(fileURLToPath(import.meta.url));
+
+export class ClaudeCodeAdapter {
+  constructor(options = {}) {
+    this.cmd = options.cmd || 'claude';
+    this.cwd = options.cwd || process.cwd();
+    this.sessionName = null;
+  }
+
+  restoreSession(id) {
+    this.sessionName = id;
+  }
+
+  async run(prompt, { useSchema = false, schemaFile = 'verdict-schema.json', continueSession = false, sessionName = null } = {}) {
+    const args = ['-p', prompt, '--output-format', 'json'];
+
+    if (useSchema) {
+      const schemaPath = join(__dirname, '../config', schemaFile);
+      const schema = readFileSync(schemaPath, 'utf-8');
+      args.push('--json-schema', schema);
+    }
+
+    if (continueSession && this.sessionName) {
+      args.push('--resume', this.sessionName);
+    } else if (sessionName) {
+      args.push('--name', sessionName);
+      this.sessionName = sessionName;
+    }
+
+    const result = await exec(this.cmd, args);
+    try {
+      const parsed = JSON.parse(result.stdout);
+      if (!this.sessionName && parsed.session_id) {
+        this.sessionName = parsed.session_id;
+      }
+      return parsed;
+    } catch {
+      return { raw: result.stdout, error: 'Failed to parse JSON output' };
+    }
+  }
+}

package/src/agents/codex.js

@@ -0,0 +1,71 @@
+import { join, dirname } from 'path';
+import { fileURLToPath } from 'url';
+import { exec } from './exec-helper.js';
+
+const __dirname = dirname(fileURLToPath(import.meta.url));
+
+export class CodexAdapter {
+  constructor(options = {}) {
+    this.cmd = options.cmd || 'codex';
+    this.cwd = options.cwd || process.cwd();
+    this.sessionId = null;
+  }
+
+  restoreSession(id) {
+    this.sessionId = id;
+  }
+
+  async run(prompt, { useSchema = false, schemaFile = 'verdict-schema.json', continueSession = false, sessionName = null } = {}) {
+    const args = ['exec'];
+
+    if (continueSession && this.sessionId) {
+      args.push('resume', this.sessionId);
+    }
+
+    args.push(prompt);
+    args.push('--json');
+
+    if (useSchema) {
+      const schemaPath = join(__dirname, '../config', schemaFile);
+      args.push('--output-schema', schemaPath);
+    }
+
+    const result = await exec(this.cmd, args);
+
+    try {
+      const lines = result.stdout.trim().split('\n');
+      let agentMessage = null;
+      let sessionId = null;
+
+      for (const line of lines) {
+        try {
+          const event = JSON.parse(line);
+          if (event.type === 'thread.started' && event.thread_id) {
+            sessionId = event.thread_id;
+          }
+          if (event.type === 'item.completed' && event.item?.type === 'agent_message') {
+            agentMessage = event.item.text;
+          }
+        } catch {
+          // skip non-JSON lines
+        }
+      }
+
+      if (sessionId && !this.sessionId) {
+        this.sessionId = sessionId;
+      }
+
+      if (agentMessage) {
+        try {
+          return { result: JSON.parse(agentMessage), session_id: this.sessionId };
+        } catch {
+          return { result: agentMessage, session_id: this.sessionId };
+        }
+      }
+
+      return { raw: result.stdout, session_id: this.sessionId };
+    } catch {
+      return { raw: result.stdout, error: 'Failed to parse output' };
+    }
+  }
+}

package/src/agents/detect.js

@@ -0,0 +1,9 @@
+import { execFile } from 'child_process';
+
+export function detectAgent(cmd) {
+  return new Promise((resolve) => {
+    execFile('which', [cmd], (error) => {
+      resolve(!error);
+    });
+  });
+}

package/src/agents/exec-helper.js

@@ -0,0 +1,16 @@
+import { execFile } from 'child_process';
+
+export function exec(cmd, args) {
+  return new Promise((resolve, reject) => {
+    execFile(cmd, args, {
+      maxBuffer: 10 * 1024 * 1024,
+      timeout: 300_000,
+    }, (error, stdout, stderr) => {
+      if (error && !stdout) {
+        reject(new Error(`${cmd} failed: ${stderr || error.message}`));
+      } else {
+        resolve({ stdout, stderr });
+      }
+    });
+  });
+}

package/src/agents/registry.js

@@ -0,0 +1,20 @@
+import { ClaudeCodeAdapter } from './claude-code.js';
+import { CodexAdapter } from './codex.js';
+
+const ADAPTERS = {
+  claude_code: ClaudeCodeAdapter,
+  codex: CodexAdapter,
+};
+
+export function createAdapter(agentName, config, { cwd } = {}) {
+  const AdapterClass = ADAPTERS[agentName];
+  if (!AdapterClass) {
+    throw new Error(`Unknown agent: ${agentName}. Available: ${Object.keys(ADAPTERS).join(', ')}`);
+  }
+  const agentConfig = config.agents?.[agentName] || {};
+  return new AdapterClass({ cmd: agentConfig.cmd, cwd });
+}
+
+export function listAgents() {
+  return Object.keys(ADAPTERS);
+}