cc-reviewer 1.5.3 → 1.8.0

package/README.md

@@ -11,7 +11,7 @@ claude mcp add -s user cc-reviewer -- npx -y cc-reviewer
 
 **Step 2: Restart Claude Code**
 
-The MCP tools and slash commands (`/codex`, `/gemini`, `/multi`) are automatically installed.
+The MCP tools and slash commands (`/codex`, `/gemini`, `/multi`, `/ask-codex`, `/ask-gemini`, `/ask-multi`) are automatically installed.
 
 **Manual command install** (if needed):
 ```bash
@@ -51,11 +51,16 @@ gemini  # follow auth prompts
 
 These tools provide **external second-opinion reviews** from Codex and Gemini CLIs. They are designed to complement Claude Code's native review capabilities, not replace them.
 
-**When to use:**
+**Review tools** (external second-opinion on your work):
 - `/codex` or "review with codex" - Get external Codex review
 - `/gemini` or "review with gemini" - Get external Gemini review
 - `/multi` - Get parallel reviews from both CLIs
 
+**Ask tools** (get help from a peer engineer):
+- `/ask-codex` - Ask Codex for help (planning, debugging, explaining, fixing)
+- `/ask-gemini` - Ask Gemini for help (architecture, patterns, scalability)
+- `/ask-multi` - Ask both models in parallel
+
 **For regular reviews:** Just say "review" and Claude Code will use its native capabilities. These external tools are only invoked when explicitly requested.
 
 ## Slash Commands
@@ -63,14 +68,18 @@ These tools provide **external second-opinion reviews** from Codex and Gemini CL
 These commands are available after restart:
 
 ```bash
+# Review tools
 /codex                    # Review with Codex
 /codex security           # Focus on security
 /codex-xhigh              # Codex with xhigh reasoning effort
-
 /gemini                   # Review with Gemini
 /gemini architecture      # Focus on architecture
-
 /multi                    # Both models in parallel
+
+# Ask tools (peer engineer)
+/ask-codex                # Ask Codex for help
+/ask-gemini               # Ask Gemini for help
+/ask-multi                # Ask both in parallel
 ```
 
 ## How It Works
@@ -99,23 +108,33 @@ CC does work → User: /codex → External CLI reviews → CC synthesizes → Up
 
 ## MCP Tools
 
-The plugin exposes three MCP tools:
+The plugin exposes six MCP tools:
 
 | Tool | Description |
 |------|-------------|
 | `codex_review` | Get Codex review (correctness, edge cases, performance) |
 | `gemini_review` | Get Gemini review (design patterns, scalability, tech debt) |
 | `multi_review` | Parallel review from both models |
+| `ask_codex` | Ask Codex for help (planning, debugging, explaining, fixing) |
+| `ask_gemini` | Ask Gemini for help (architecture, patterns, scalability) |
+| `ask_multi` | Ask both models in parallel |
 
 ## Output Format
 
-External CLIs return structured JSON feedback with:
+**Review tools** return structured JSON feedback with:
 - **Findings**: Issues with severity, confidence, location, and suggestions
 - **Agreements**: Validations of CC's correct assessments
 - **Disagreements**: Challenges to CC's claims with corrections
 - **Alternatives**: Different approaches with tradeoffs
 - **Risk Assessment**: Overall risk level with top concerns
 
+**Ask tools** return structured JSON responses with:
+- **Answer**: Main response text (markdown)
+- **Key Points**: Bullet summary of main points
+- **Suggested Actions**: Recommended actions with priority and rationale
+- **File References**: Files examined with line ranges and relevance
+- **Alternatives**: Alternative approaches considered
+
 ## Development
 
 ```bash
@@ -130,9 +149,18 @@ npm start           # Run server
 
 ## Publishing
 
-Uses npm Trusted Publishing (OIDC, no tokens):
+Release-based publish via npm Trusted Publishing (OIDC, no tokens needed).
+CI triggers on GitHub Release, validates the tag matches `package.json`.
+
 ```bash
-gh workflow run publish.yml -f version=patch  # or minor/major
+# 1. Bump version in package.json
+# 2. Rebuild and test
+npm run build && npm test
+# 3. Commit, tag, push, release
+git add -A && git commit -m "v1.x.x"
+git tag v1.x.x
+git push && git push --tags
+gh release create v1.x.x --title "v1.x.x" --generate-notes
 ```
 
 ## License

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);
@@ -214,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) {

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
 // =============================================================================
@@ -212,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

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;