cc-reviewer 1.5.1 → 1.7.0

package/commands/ask-codex.md

@@ -0,0 +1,35 @@
+# Ask Codex
+
+Ask OpenAI Codex CLI for help as a peer engineer.
+
+## Arguments
+- `$ARGUMENTS` - Your question or request
+
+## Codex Strengths
+- **Correctness**: Logic errors, edge cases, bugs
+- **Performance**: Efficiency, complexity analysis
+- **Security**: Vulnerability detection
+
+## Tool Invocation
+
+Call `ask_codex` with:
+
+```json
+{
+  "workingDir": "<current directory>",
+  "prompt": "<your question or request from $ARGUMENTS>",
+  "taskType": "<infer from request: plan|debug|explain|question|fix|explore|general>",
+  "relevantFiles": ["<files related to the question>"],
+  "context": "<any error messages or prior analysis>"
+}
+```
+
+## After Receiving Response
+
+1. **Read the answer** and key points
+2. **Check file references** — verify they exist
+3. **Evaluate suggested actions** — do they make sense?
+4. **Apply your judgment** — you may disagree
+5. **Act on the suggestions** or ask follow-up questions
+
+$ARGUMENTS

package/commands/ask-gemini.md

@@ -0,0 +1,35 @@
+# Ask Gemini
+
+Ask Google Gemini CLI for help as a peer engineer.
+
+## Arguments
+- `$ARGUMENTS` - Your question or request
+
+## Gemini Strengths
+- **Architecture**: Design patterns, structure
+- **Scalability**: Load handling, bottlenecks
+- **Maintainability**: Code clarity, tech debt
+
+## Tool Invocation
+
+Call `ask_gemini` with:
+
+```json
+{
+  "workingDir": "<current directory>",
+  "prompt": "<your question or request from $ARGUMENTS>",
+  "taskType": "<infer from request: plan|debug|explain|question|fix|explore|general>",
+  "relevantFiles": ["<files related to the question>"],
+  "context": "<any error messages or prior analysis>"
+}
+```
+
+## After Receiving Response
+
+1. **Read the answer** and key points
+2. **Check file references** — verify they exist
+3. **Evaluate suggested actions** — do they make sense?
+4. **Apply your judgment** — you may disagree
+5. **Act on the suggestions** or ask follow-up questions
+
+$ARGUMENTS

package/commands/ask-multi.md

@@ -0,0 +1,38 @@
+# Ask Multi
+
+Ask both Codex and Gemini for help in parallel — get multiple perspectives.
+
+## Arguments
+- `$ARGUMENTS` - Your question or request
+
+## When to Use
+
+Use `/ask-multi` when you want perspectives from both models on the same question.
+
+## Tool Invocation
+
+Call `ask_multi` with:
+
+```json
+{
+  "workingDir": "<current directory>",
+  "prompt": "<your question or request from $ARGUMENTS>",
+  "taskType": "<infer from request: plan|debug|explain|question|fix|explore|general>",
+  "relevantFiles": ["<files related to the question>"],
+  "context": "<any error messages or prior analysis>"
+}
+```
+
+## After Receiving Responses
+
+You will receive separate responses from each model.
+
+### Synthesize
+
+1. **Find agreements** — both models say the same thing (higher confidence)
+2. **Identify conflicts** — they disagree (YOU decide who's right)
+3. **Note unique insights** — findings only one model provided
+4. **Verify file references** — check they exist
+5. **Make YOUR recommendation** — don't just relay, apply judgment
+
+$ARGUMENTS

package/dist/adapters/base.d.ts

@@ -5,8 +5,8 @@
  * Makes it easy to add new models (Ollama, Azure, etc.) without
  * changing the core orchestration logic.
  */
-import { ReviewOutput } from '../schema.js';
-import { FocusArea, OutputType, ReasoningEffort } from '../types.js';
+import { ReviewOutput, PeerOutput } from '../schema.js';
+import { FocusArea, OutputType, ReasoningEffort, TaskType } from '../types.js';
 export interface ReviewerCapabilities {
     /** Display name for this reviewer */
     name: string;
@@ -43,6 +43,24 @@ export interface ReviewRequest {
     /** Expert role configuration (optional override) */
     expertRole?: ExpertRole;
 }
+export interface PeerRequest {
+    /** Working directory containing the code */
+    workingDir: string;
+    /** The question or request from CC */
+    prompt: string;
+    /** Hint about the type of task */
+    taskType?: TaskType;
+    /** Files the peer should focus on */
+    relevantFiles?: string[];
+    /** Additional context (error messages, prior analysis) */
+    context?: string;
+    /** Areas to focus on */
+    focusAreas?: FocusArea[];
+    /** Custom instructions from the user */
+    customPrompt?: string;
+    /** Reasoning effort level (for models that support it) */
+    reasoningEffort?: ReasoningEffort;
+}
 export interface ExpertRole {
     name: string;
     description: string;
@@ -74,6 +92,20 @@ export interface ReviewError {
     message: string;
     details?: Record<string, unknown>;
 }
+export interface PeerSuccess {
+    success: true;
+    output: PeerOutput;
+    rawOutput?: string;
+    executionTimeMs: number;
+}
+export interface PeerFailure {
+    success: false;
+    error: ReviewError;
+    suggestion?: string;
+    rawOutput?: string;
+    executionTimeMs: number;
+}
+export type PeerResult = PeerSuccess | PeerFailure;
 /**
  * Base interface that all reviewer adapters must implement.
  * This allows easy addition of new AI CLIs without changing orchestration logic.
@@ -87,6 +119,8 @@ export interface ReviewerAdapter {
     isAvailable(): Promise<boolean>;
     /** Run a review and return structured output */
     runReview(request: ReviewRequest): Promise<ReviewResult>;
+    /** Run a general-purpose peer request and return structured output */
+    runPeerRequest(request: PeerRequest): Promise<PeerResult>;
     /**
      * Optional: Run peer review of another model's output
      * Future capability - not currently implemented by any adapter

package/dist/adapters/codex.d.ts

@@ -4,13 +4,15 @@
  * Implements the ReviewerAdapter interface for OpenAI's Codex CLI.
  * Specializes in correctness, edge cases, and performance analysis.
  */
-import { ReviewerAdapter, ReviewerCapabilities, ReviewRequest, ReviewResult } from './base.js';
+import { ReviewerAdapter, ReviewerCapabilities, ReviewRequest, ReviewResult, PeerRequest, PeerResult } from './base.js';
 export declare class CodexAdapter implements ReviewerAdapter {
     readonly id = "codex";
     getCapabilities(): ReviewerCapabilities;
     isAvailable(): Promise<boolean>;
     runReview(request: ReviewRequest): Promise<ReviewResult>;
     private runWithRetry;
+    runPeerRequest(request: PeerRequest): Promise<PeerResult>;
+    private runPeerWithRetry;
     private runCli;
     private categorizeError;
     private getSuggestion;

package/dist/adapters/codex.js

@@ -9,8 +9,8 @@ import { existsSync, writeFileSync, unlinkSync, mkdtempSync } from 'fs';
 import { tmpdir } from 'os';
 import { join } from 'path';
 import { registerAdapter, } from './base.js';
-import { parseReviewOutput, parseLegacyMarkdownOutput, getReviewOutputJsonSchema } from '../schema.js';
-import { buildSimpleHandoff, buildHandoffPrompt, selectRole, } from '../handoff.js';
+import { parseReviewOutput, parseLegacyMarkdownOutput, getReviewOutputJsonSchema, getPeerOutputJsonSchema, parsePeerOutput } from '../schema.js';
+import { buildSimpleHandoff, buildHandoffPrompt, buildPeerPrompt, selectRole, } from '../handoff.js';
 // =============================================================================
 // CONFIGURATION
 // =============================================================================
@@ -89,7 +89,7 @@ export class CodexAdapter {
                     (previousOutput ? `\nPrevious output (for reference):\n${previousOutput.slice(0, 500)}...` : '');
             }
             // Run the CLI
-            const result = await this.runCli(prompt, request.workingDir, request.reasoningEffort || 'high');
+            const result = await this.runCli(prompt, request.workingDir, request.reasoningEffort || 'high', getReviewOutputJsonSchema);
             // Handle CLI errors
             if (result.exitCode !== 0) {
                 const error = this.categorizeError(result.stderr);
@@ -138,16 +138,29 @@ export class CodexAdapter {
                     executionTimeMs: Date.now() - startTime,
                 };
             }
-            // If we used fallback and got minimal data, retry
-            if (usedFallback && attempt < MAX_RETRIES) {
-                const hasMinimalData = output.findings.length === 0 &&
-                    output.agreements.length === 0 &&
-                    output.disagreements.length === 0 &&
-                    output.risk_assessment.summary === 'Unable to parse structured risk assessment';
-                if (hasMinimalData) {
-                    console.error(`[codex] Received incomplete output (fallback parse with no data), retrying...`);
-                    return this.runWithRetry(request, attempt + 1, startTime, 'Received markdown output instead of JSON. Please provide valid JSON output.', result.stdout);
+            // Check for empty/minimal data on any parse path
+            const hasMinimalData = output.findings.length === 0 &&
+                output.agreements.length === 0 &&
+                output.disagreements.length === 0;
+            if (hasMinimalData) {
+                if (attempt < MAX_RETRIES) {
+                    console.error(`[codex] Received empty output, retrying...`);
+                    return this.runWithRetry(request, attempt + 1, startTime, usedFallback
+                        ? 'Received markdown output instead of JSON. Please provide valid JSON output.'
+                        : 'Output contained no findings, agreements, or disagreements. Please provide substantive review.', result.stdout);
                 }
+                // Final attempt with no data — report failure
+                return {
+                    success: false,
+                    error: {
+                        type: 'parse_error',
+                        message: 'Reviewer returned empty output after retries',
+                        details: { rawOutput: result.stdout.slice(0, 1000) },
+                    },
+                    suggestion: 'The model returned no substantive review. Try a different focus area.',
+                    rawOutput: result.stdout,
+                    executionTimeMs: Date.now() - startTime,
+                };
             }
             return {
                 success: true,
@@ -201,14 +214,105 @@ export class CodexAdapter {
             };
         }
     }
-    runCli(prompt, workingDir, reasoningEffort) {
+    async runPeerRequest(request) {
+        const startTime = Date.now();
+        if (!existsSync(request.workingDir)) {
+            return {
+                success: false,
+                error: {
+                    type: 'cli_error',
+                    message: `Working directory does not exist: ${request.workingDir}`,
+                },
+                suggestion: 'Check that the working directory path is correct',
+                executionTimeMs: Date.now() - startTime,
+            };
+        }
+        return this.runPeerWithRetry(request, 0, startTime);
+    }
+    async runPeerWithRetry(request, attempt, startTime, previousError, previousOutput) {
+        try {
+            let prompt = buildPeerPrompt({
+                workingDir: request.workingDir,
+                prompt: request.prompt,
+                taskType: request.taskType,
+                relevantFiles: request.relevantFiles,
+                context: request.context,
+                focusAreas: request.focusAreas,
+                customInstructions: request.customPrompt,
+                outputFormat: 'json',
+            });
+            if (attempt > 0) {
+                prompt += `\n\n---\n\n# RETRY ATTEMPT ${attempt + 1}\n\n` +
+                    `Previous output had issues: ${previousError}\n` +
+                    `Please fix these issues and provide valid JSON output.\n` +
+                    (previousOutput ? `\nPrevious output (for reference):\n${previousOutput.slice(0, 500)}...` : '');
+            }
+            const result = await this.runCli(prompt, request.workingDir, request.reasoningEffort || 'high', getPeerOutputJsonSchema);
+            if (result.exitCode !== 0) {
+                const error = this.categorizeError(result.stderr);
+                return {
+                    success: false,
+                    error,
+                    suggestion: this.getSuggestion(error),
+                    rawOutput: result.stderr,
+                    executionTimeMs: Date.now() - startTime,
+                };
+            }
+            if (result.truncated) {
+                return {
+                    success: false,
+                    error: { type: 'cli_error', message: 'Output exceeded maximum buffer size (1MB)' },
+                    suggestion: 'Try a more focused request',
+                    executionTimeMs: Date.now() - startTime,
+                };
+            }
+            const output = parsePeerOutput(result.stdout);
+            if (!output) {
+                if (attempt < MAX_RETRIES) {
+                    return this.runPeerWithRetry(request, attempt + 1, startTime, 'Output did not match expected JSON schema', result.stdout);
+                }
+                return {
+                    success: false,
+                    error: { type: 'parse_error', message: 'Failed to parse peer output after retries',
+                        details: { rawOutput: result.stdout.slice(0, 1000) } },
+                    suggestion: 'The model may not be following the output format.',
+                    rawOutput: result.stdout,
+                    executionTimeMs: Date.now() - startTime,
+                };
+            }
+            return {
+                success: true,
+                output,
+                rawOutput: result.stdout,
+                executionTimeMs: Date.now() - startTime,
+            };
+        }
+        catch (error) {
+            const err = error;
+            if (err.code === 'ENOENT') {
+                return { success: false, error: { type: 'cli_not_found', message: 'Codex CLI not found' },
+                    suggestion: 'Install with: npm install -g @openai/codex', executionTimeMs: Date.now() - startTime };
+            }
+            if (err.message === 'TIMEOUT') {
+                return { success: false, error: { type: 'timeout', message: 'No output for 2 minutes' },
+                    suggestion: 'Try a simpler request', executionTimeMs: Date.now() - startTime };
+            }
+            if (err.message === 'MAX_TIMEOUT') {
+                return { success: false, error: { type: 'timeout', message: 'Task exceeded 60 minute maximum' },
+                    suggestion: 'Try a smaller scope', executionTimeMs: Date.now() - startTime };
+            }
+            return { success: false, error: { type: 'cli_error', message: err.message },
+                executionTimeMs: Date.now() - startTime };
+        }
+    }
+    runCli(prompt, workingDir, reasoningEffort, schemaGetter) {
         return new Promise((resolve, reject) => {
             // Create temp schema file for structured output
             let schemaFile = null;
             try {
                 const tempDir = mkdtempSync(join(tmpdir(), 'codex-schema-'));
                 schemaFile = join(tempDir, 'schema.json');
-                const schema = getReviewOutputJsonSchema();
+                const schema = schemaGetter();
                 writeFileSync(schemaFile, JSON.stringify(schema, null, 2), 'utf-8');
             }
             catch (err) {
@@ -236,6 +340,11 @@ export class CodexAdapter {
                 stdio: ['pipe', 'pipe', 'pipe'], // stdin is pipe for prompt delivery
                 env: { ...process.env }
             });
+            // Guard against EPIPE if the child exits before consuming stdin.
+            // Log but don't reject — let the `close` handler capture the real exit code.
+            proc.stdin.on('error', (err) => {
+                console.error(`[codex] stdin error (likely EPIPE): ${err.message}`);
+            });
             // Deliver prompt via stdin
             proc.stdin.write(prompt);
             proc.stdin.end();

package/dist/adapters/gemini.d.ts

@@ -4,13 +4,15 @@
  * Implements the ReviewerAdapter interface for Google's Gemini CLI.
  * Specializes in architecture, design patterns, and large-context analysis.
  */
-import { ReviewerAdapter, ReviewerCapabilities, ReviewRequest, ReviewResult } from './base.js';
+import { ReviewerAdapter, ReviewerCapabilities, ReviewRequest, ReviewResult, PeerRequest, PeerResult } from './base.js';
 export declare class GeminiAdapter implements ReviewerAdapter {
     readonly id = "gemini";
     getCapabilities(): ReviewerCapabilities;
     isAvailable(): Promise<boolean>;
     runReview(request: ReviewRequest): Promise<ReviewResult>;
     private runWithRetry;
+    runPeerRequest(request: PeerRequest): Promise<PeerResult>;
+    private runPeerWithRetry;
     private runCli;
     private categorizeError;
     private getSuggestion;

package/dist/adapters/gemini.js

@@ -7,8 +7,8 @@
 import { spawn } from 'child_process';
 import { existsSync } from 'fs';
 import { registerAdapter, } from './base.js';
-import { parseReviewOutput, parseLegacyMarkdownOutput } from '../schema.js';
-import { buildSimpleHandoff, buildHandoffPrompt, selectRole, } from '../handoff.js';
+import { parseReviewOutput, parseLegacyMarkdownOutput, parsePeerOutput } from '../schema.js';
+import { buildSimpleHandoff, buildHandoffPrompt, buildPeerPrompt, selectRole, } from '../handoff.js';
 // =============================================================================
 // CONFIGURATION
 // =============================================================================
@@ -136,17 +136,29 @@ export class GeminiAdapter {
                     executionTimeMs: Date.now() - startTime,
                 };
             }
-            // If output has no substantive data, retry regardless of parse path
-            if (attempt < MAX_RETRIES) {
-                const hasMinimalData = output.findings.length === 0 &&
-                    output.agreements.length === 0 &&
-                    output.disagreements.length === 0;
-                if (hasMinimalData) {
+            // If output has no substantive data, retry or fail
+            const hasMinimalData = output.findings.length === 0 &&
+                output.agreements.length === 0 &&
+                output.disagreements.length === 0;
+            if (hasMinimalData) {
+                if (attempt < MAX_RETRIES) {
                     console.error(`[gemini] Received empty output, retrying...`);
                     return this.runWithRetry(request, attempt + 1, startTime, usedFallback
                         ? 'Received markdown output instead of JSON. Please provide valid JSON output.'
                         : 'Output contained no findings, agreements, or disagreements. Please provide substantive review.', result.stdout);
                 }
+                // Final attempt with no data — report failure
+                return {
+                    success: false,
+                    error: {
+                        type: 'parse_error',
+                        message: 'Reviewer returned empty output after retries',
+                        details: { rawOutput: result.stdout.slice(0, 1000) },
+                    },
+                    suggestion: 'The model returned no substantive review. Try a different focus area.',
+                    rawOutput: result.stdout,
+                    executionTimeMs: Date.now() - startTime,
+                };
             }
             return {
                 success: true,
@@ -200,6 +212,92 @@ export class GeminiAdapter {
             };
         }
     }
+    async runPeerRequest(request) {
+        const startTime = Date.now();
+        if (!existsSync(request.workingDir)) {
+            return {
+                success: false,
+                error: { type: 'cli_error', message: `Working directory does not exist: ${request.workingDir}` },
+                suggestion: 'Check that the working directory path is correct',
+                executionTimeMs: Date.now() - startTime,
+            };
+        }
+        return this.runPeerWithRetry(request, 0, startTime);
+    }
+    async runPeerWithRetry(request, attempt, startTime, previousError, previousOutput) {
+        try {
+            let prompt = buildPeerPrompt({
+                workingDir: request.workingDir,
+                prompt: request.prompt,
+                taskType: request.taskType,
+                relevantFiles: request.relevantFiles,
+                context: request.context,
+                focusAreas: request.focusAreas,
+                customInstructions: request.customPrompt,
+                outputFormat: 'json',
+            });
+            if (attempt > 0) {
+                prompt += `\n\n---\n\n# RETRY ATTEMPT ${attempt + 1}\n\n` +
+                    `Previous output had issues: ${previousError}\n` +
+                    `Please fix these issues and provide valid JSON output.\n` +
+                    (previousOutput ? `\nPrevious output (for reference):\n${previousOutput.slice(0, 500)}...` : '');
+            }
+            const result = await this.runCli(prompt, request.workingDir);
+            if (result.exitCode !== 0) {
+                const error = this.categorizeError(result.stderr);
+                return {
+                    success: false, error,
+                    suggestion: this.getSuggestion(error),
+                    rawOutput: result.stderr,
+                    executionTimeMs: Date.now() - startTime,
+                };
+            }
+            if (result.truncated) {
+                return {
+                    success: false,
+                    error: { type: 'cli_error', message: 'Output exceeded maximum buffer size (1MB)' },
+                    suggestion: 'Try a more focused request',
+                    executionTimeMs: Date.now() - startTime,
+                };
+            }
+            const output = parsePeerOutput(result.stdout);
+            if (!output) {
+                if (attempt < MAX_RETRIES) {
+                    return this.runPeerWithRetry(request, attempt + 1, startTime, 'Output did not match expected JSON schema', result.stdout);
+                }
+                return {
+                    success: false,
+                    error: { type: 'parse_error', message: 'Failed to parse peer output after retries',
+                        details: { rawOutput: result.stdout.slice(0, 1000) } },
+                    suggestion: 'The model may not be following the output format.',
+                    rawOutput: result.stdout,
+                    executionTimeMs: Date.now() - startTime,
+                };
+            }
+            return {
+                success: true, output,
+                rawOutput: result.stdout,
+                executionTimeMs: Date.now() - startTime,
+            };
+        }
+        catch (error) {
+            const err = error;
+            if (err.code === 'ENOENT') {
+                return { success: false, error: { type: 'cli_not_found', message: 'Gemini CLI not found' },
+                    suggestion: 'Install with: npm install -g @google/gemini-cli', executionTimeMs: Date.now() - startTime };
+            }
+            if (err.message === 'TIMEOUT') {
+                return { success: false, error: { type: 'timeout', message: 'No output for 10 minutes' },
+                    suggestion: 'Try a simpler request', executionTimeMs: Date.now() - startTime };
+            }
+            if (err.message === 'MAX_TIMEOUT') {
+                return { success: false, error: { type: 'timeout', message: 'Task exceeded 60 minute maximum' },
+                    suggestion: 'Try a smaller scope', executionTimeMs: Date.now() - startTime };
+            }
+            return { success: false, error: { type: 'cli_error', message: err.message },
+                executionTimeMs: Date.now() - startTime };
+        }
+    }
     runCli(prompt, workingDir) {
         return new Promise((resolve, reject) => {
             // Gemini CLI uses --yolo for auto-approval, prompt passed via stdin
@@ -209,12 +307,18 @@ export class GeminiAdapter {
                 '--yolo',
                 '--output-format', 'json', // Force JSON output
                 '--include-directories', workingDir,
+                '-p', '', // Force headless mode; actual prompt delivered via stdin
             ];
             const proc = spawn('gemini', args, {
                 cwd: workingDir,
                 stdio: ['pipe', 'pipe', 'pipe'], // stdin is pipe for prompt delivery
                 env: { ...process.env }
             });
+            // Guard against EPIPE if the child exits before consuming stdin.
+            // Log but don't reject — let the `close` handler capture the real exit code.
+            proc.stdin.on('error', (err) => {
+                console.error(`[gemini] stdin error (likely EPIPE): ${err.message}`);
+            });
             // Deliver prompt via stdin — more stable than args for complex content
             proc.stdin.write(prompt);
             proc.stdin.end();

package/dist/handoff.d.ts

@@ -230,3 +230,18 @@ export declare function buildSimpleHandoff(workingDir: string, ccOutput: string,
  * CC should call this to add its specific concerns
  */
 export declare function enhanceHandoff(handoff: Handoff, uncertainties?: Uncertainty[], questions?: Question[], decisions?: Decision[]): Handoff;
+export interface PeerPromptOptions {
+    workingDir: string;
+    prompt: string;
+    taskType?: string;
+    relevantFiles?: string[];
+    context?: string;
+    focusAreas?: FocusArea[];
+    customInstructions?: string;
+    outputFormat: 'json';
+}
+/**
+ * Build a prompt for general-purpose peer assistance (not review).
+ * The peer acts as a collaborative coworker, not a critic.
+ */
+export declare function buildPeerPrompt(options: PeerPromptOptions): string;