From cd206f275edf6235f4e8b03edca985a95b04d8e2 Mon Sep 17 00:00:00 2001 From: catlog22 Date: Tue, 25 Nov 2025 16:16:11 +0800 Subject: [PATCH] Add JSON schemas for deep-dive results and dimension analysis - Introduced `review-deep-dive-results-schema.json` to define the structure for deep-dive iteration analysis results, including root cause analysis, remediation plans, and impact assessments. - Added `review-dimension-results-schema.json` to outline the schema for dimension analysis results, capturing findings across various dimensions such as security and architecture, along with cross-references to related findings. --- .claude/commands/cli/analyze.md | 87 -- .claude/commands/cli/chat.md | 82 -- .claude/commands/cli/codex-execute.md | 519 -------- .claude/commands/cli/discuss-plan.md | 320 ----- .claude/commands/cli/execute.md | 202 --- .claude/commands/cli/mode/bug-diagnosis.md | 96 -- .claude/commands/cli/mode/code-analysis.md | 98 -- .../commands/cli/mode/document-analysis.md | 126 -- .claude/commands/cli/mode/plan.md | 93 -- .claude/commands/workflow/review-cycle.md | 816 ++++++++++++ .claude/templates/review-cycle-dashboard.html | 1142 +++++++++++++++++ .../review-deep-dive-results-schema.json | 291 +++++ .../review-dimension-results-schema.json | 281 ++++ 13 files changed, 2530 insertions(+), 1623 deletions(-) delete mode 100644 .claude/commands/cli/analyze.md delete mode 100644 .claude/commands/cli/chat.md delete mode 100644 .claude/commands/cli/codex-execute.md delete mode 100644 .claude/commands/cli/discuss-plan.md delete mode 100644 .claude/commands/cli/execute.md delete mode 100644 .claude/commands/cli/mode/bug-diagnosis.md delete mode 100644 .claude/commands/cli/mode/code-analysis.md delete mode 100644 .claude/commands/cli/mode/document-analysis.md delete mode 100644 .claude/commands/cli/mode/plan.md create mode 100644 .claude/commands/workflow/review-cycle.md create mode 100644 .claude/templates/review-cycle-dashboard.html create mode 100644 .claude/workflows/cli-templates/schemas/review-deep-dive-results-schema.json create mode 100644 .claude/workflows/cli-templates/schemas/review-dimension-results-schema.json diff --git a/.claude/commands/cli/analyze.md b/.claude/commands/cli/analyze.md deleted file mode 100644 index 2c792540..00000000 --- a/.claude/commands/cli/analyze.md +++ /dev/null @@ -1,87 +0,0 @@ ---- -name: analyze -description: Read-only codebase analysis using Gemini (default), Qwen, or Codex with auto-pattern detection and template selection -argument-hint: "[--tool codex|gemini|qwen] [--enhance] analysis target" -allowed-tools: SlashCommand(*), Bash(*), TodoWrite(*), Read(*), Glob(*), Task(*) ---- - -# CLI Analyze Command (/cli:analyze) - -## Purpose - -Quick codebase analysis using CLI tools. **Read-only - does NOT modify code**. - -**Tool Selection**: -- **gemini** (default) - Best for code analysis -- **qwen** - Fallback when Gemini unavailable -- **codex** - Alternative for deep analysis - -## Parameters - -- `--tool ` - Tool selection (default: gemini) -- `--enhance` - Use `/enhance-prompt` for context-aware enhancement -- `` - Description of what to analyze - -## Tool Usage - -**Gemini** (Primary): -```bash ---tool gemini # or omit (default) -``` - -**Qwen** (Fallback): -```bash ---tool qwen -``` - -**Codex** (Alternative): -```bash ---tool codex -``` - -## Execution Flow - -Uses **cli-execution-agent** (default) for automated analysis: - -```javascript -Task( - subagent_type="cli-execution-agent", - description="Codebase analysis with pattern detection", - prompt=` - Task: ${analysis_target} - Mode: analyze - Tool: ${tool_flag || 'gemini'} - Enhance: ${enhance_flag} - - Execute codebase analysis with auto-pattern detection: - - 1. Context Discovery: - - Extract keywords from analysis target - - Auto-detect file patterns (auth→auth files, component→components, etc.) - - Discover additional relevant files using MCP - - Build comprehensive file context - - 2. Template Selection: - - Auto-select analysis template based on keywords - - Apply appropriate analysis methodology - - Include @CLAUDE.md for project context - - 3. CLI Command Construction: - - Tool: ${tool_flag || 'gemini'} (qwen fallback, codex for deep analysis) - - Context: @CLAUDE.md + auto-detected patterns + discovered files - - Mode: analysis (read-only) - - Expected: Insights, recommendations, pattern analysis - - 4. Execution & Output: - - Execute CLI tool with assembled context - - Generate comprehensive analysis report - - Save to .workflow/active/WFS-[id]/.chat/analyze-[timestamp].md (or .scratchpad/) - ` -) -``` - -## Core Rules - -- **Read-only**: Analyzes code, does NOT modify files -- **Auto-pattern**: Detects file patterns from keywords (auth→auth files, component→components, API→api/routes, test→test files) -- **Output**: `.workflow/active/WFS-[id]/.chat/analyze-[timestamp].md` (or `.scratchpad/` if no session) diff --git a/.claude/commands/cli/chat.md b/.claude/commands/cli/chat.md deleted file mode 100644 index cc212bae..00000000 --- a/.claude/commands/cli/chat.md +++ /dev/null @@ -1,82 +0,0 @@ ---- -name: chat -description: Read-only Q&A interaction with Gemini/Qwen/Codex for codebase questions with automatic context inference -argument-hint: "[--tool codex|gemini|qwen] [--enhance] inquiry" -allowed-tools: SlashCommand(*), Bash(*), Task(*) ---- - -# CLI Chat Command (/cli:chat) - -## Purpose - -Direct Q&A interaction with CLI tools for codebase analysis. **Read-only - does NOT modify code**. - -**Tool Selection**: -- **gemini** (default) - Best for Q&A and explanations -- **qwen** - Fallback when Gemini unavailable -- **codex** - Alternative for technical deep-dives - -## Parameters - -- `--tool ` - Tool selection (default: gemini) -- `--enhance` - Enhance inquiry with `/enhance-prompt` -- `` (Required) - Question or analysis request - -## Tool Usage - -**Gemini** (Primary): -```bash ---tool gemini # or omit (default) -``` - -**Qwen** (Fallback): -```bash ---tool qwen -``` - -**Codex** (Alternative): -```bash ---tool codex -``` - -## Execution Flow - -Uses **cli-execution-agent** (default) for automated Q&A: - -```javascript -Task( - subagent_type="cli-execution-agent", - description="Codebase Q&A with intelligent context discovery", - prompt=` - Task: ${inquiry} - Mode: chat - Tool: ${tool_flag || 'gemini'} - Enhance: ${enhance_flag} - - Execute codebase Q&A with intelligent context discovery: - - 1. Context Discovery: - - Parse inquiry to identify relevant topics/keywords - - Discover related files using MCP/ripgrep (prioritize precision) - - Include @CLAUDE.md + discovered files - - Validate context relevance to question - - 2. CLI Command Construction: - - Tool: ${tool_flag || 'gemini'} (qwen fallback, codex for deep dives) - - Context: @CLAUDE.md + discovered file patterns - - Mode: analysis (read-only) - - Expected: Clear, accurate answer with code references - - 3. Execution & Output: - - Execute CLI tool with assembled context - - Validate answer completeness - - Save to .workflow/active/WFS-[id]/.chat/chat-[timestamp].md (or .scratchpad/) - ` -) -``` - -## Core Rules - -- **Read-only**: Provides answers, does NOT modify code -- **Context**: `@CLAUDE.md` + inferred or all files (`@**/*`) -- **Output**: `.workflow/active/WFS-[id]/.chat/chat-[timestamp].md` (or `.scratchpad/` if no session) diff --git a/.claude/commands/cli/codex-execute.md b/.claude/commands/cli/codex-execute.md deleted file mode 100644 index 652a69d1..00000000 --- a/.claude/commands/cli/codex-execute.md +++ /dev/null @@ -1,519 +0,0 @@ ---- -name: codex-execute -description: Multi-stage Codex execution with automatic task decomposition into grouped subtasks using resume mechanism for context continuity -argument-hint: "[--verify-git] task description or task-id" -allowed-tools: SlashCommand(*), Bash(*), TodoWrite(*), Read(*), Glob(*) ---- - -# CLI Codex Execute Command (/cli:codex-execute) - -## Purpose - -Automated task decomposition and sequential execution with Codex, using `codex exec "..." resume --last` mechanism for continuity between subtasks. - -**Input**: User description or task ID (automatically loads from `.task/[ID].json` if applicable) - -## Core Workflow - -``` -Task Input → Analyze Dependencies → Create Task Flow Diagram → -Decompose into Subtask Groups → TodoWrite Tracking → -For Each Subtask Group: - For First Subtask in Group: - 0. Stage existing changes (git add -A) if valid git repo - 1. Execute with Codex (new session) - 2. [Optional] Git verification - 3. Mark complete in TodoWrite - For Related Subtasks in Same Group: - 0. Stage changes from previous subtask - 1. Execute with `codex exec "..." resume --last` (continue session) - 2. [Optional] Git verification - 3. Mark complete in TodoWrite -→ Final Summary -``` - -## Parameters - -- `` (Required): Task description or task ID (e.g., "implement auth" or "IMPL-001") - - If input matches task ID format, loads from `.task/[ID].json` - - Otherwise, uses input as task description -- `--verify-git` (Optional): Verify git status after each subtask completion - -## Execution Flow - -### Phase 1: Input Processing & Task Flow Analysis - -1. **Parse Input**: - - Check if input matches task ID pattern (e.g., `IMPL-001`, `TASK-123`) - - If yes: Load from `.task/[ID].json` and extract requirements - - If no: Use input as task description directly - -2. **Analyze Dependencies & Create Task Flow Diagram**: - - Analyze task complexity and scope - - Identify dependencies and relationships between subtasks - - Create visual task flow diagram showing: - - Independent task groups (parallel execution possible) - - Sequential dependencies (must use resume) - - Branching logic (conditional paths) - - Display flow diagram for user review - -**Task Flow Diagram Format**: -``` -[Group A: Auth Core] - A1: Create user model ──┐ - A2: Add validation ─┤─► [resume] ─► A3: Database schema - │ -[Group B: API Layer] │ - B1: Auth endpoints ─────┘─► [new session] - B2: Middleware ────────────► [resume] ─► B3: Error handling - -[Group C: Testing] - C1: Unit tests ─────────────► [new session] - C2: Integration tests ──────► [resume] -``` - -**Diagram Symbols**: -- `──►` Sequential dependency (must resume previous session) -- `─┐` Branch point (multiple paths) -- `─┘` Merge point (wait for completion) -- `[resume]` Use `codex exec "..." resume --last` -- `[new session]` Start fresh Codex session - -3. **Decompose into Subtask Groups**: - - Group related subtasks that share context - - Break down into 3-8 subtasks total - - Assign each subtask to a group - - Create TodoWrite tracker with groups - - Display decomposition for user review - -**Decomposition Criteria**: -- Each subtask: 5-15 minutes completable -- Clear, testable outcomes -- Explicit dependencies -- Focused file scope (1-5 files per subtask) -- **Group coherence**: Subtasks in same group share context/files - -### File Discovery for Task Decomposition - -Use `rg` or MCP tools to discover relevant files, then group by domain: - -**Workflow**: Discover → Analyze scope → Group by files → Create task flow - -**Example**: -```bash -# Discover files -rg "authentication" --files-with-matches --type ts - -# Group by domain -# Group A: src/auth/model.ts, src/auth/schema.ts -# Group B: src/api/auth.ts, src/middleware/auth.ts -# Group C: tests/auth/*.test.ts - -# Each group becomes a session with related subtasks -``` - -File patterns: see intelligent-tools-strategy.md (loaded in memory) - -### Phase 2: Group-Based Execution - -**Pre-Execution Git Staging** (if valid git repository): -```bash -# Stage all current changes before codex execution -# This makes codex changes clearly visible in git diff -git add -A -git status --short -``` - -**For First Subtask in Each Group** (New Session): -```bash -# Start new Codex session for independent task group -codex -C [dir] --full-auto exec " -PURPOSE: [group goal] -TASK: [subtask description - first in group] -CONTEXT: @{relevant_files} @CLAUDE.md -EXPECTED: [specific deliverables] -RULES: [constraints] -Group [X]: [group name] - Subtask 1 of N in this group -" --skip-git-repo-check -s danger-full-access -``` - -**For Related Subtasks in Same Group** (Resume Session): -```bash -# Stage changes from previous subtask (if valid git repository) -git add -A - -# Resume session ONLY for subtasks in same group -codex exec " -CONTINUE IN SAME GROUP: -Group [X]: [group name] - Subtask N of M - -PURPOSE: [continuation goal within group] -TASK: [subtask N description] -CONTEXT: Previous work in this group completed, now focus on @{new_relevant_files} -EXPECTED: [specific deliverables] -RULES: Build on previous subtask in group, maintain consistency -" resume --last --skip-git-repo-check -s danger-full-access -``` - -**For First Subtask in Different Group** (New Session): -```bash -# Stage changes from previous group -git add -A - -# Start NEW session for different group (no resume) -codex -C [dir] --full-auto exec " -PURPOSE: [new group goal] -TASK: [subtask description - first in new group] -CONTEXT: @{different_files} @CLAUDE.md -EXPECTED: [specific deliverables] -RULES: [constraints] -Group [Y]: [new group name] - Subtask 1 of N in this group -" --skip-git-repo-check -s danger-full-access -``` - -**Resume Decision Logic**: -``` -if (subtask.group == previous_subtask.group): - use `codex exec "..." resume --last` # Continue session -else: - use `codex -C [dir] exec "..."` # New session -``` - -### Phase 3: Verification (if --verify-git enabled) - -After each subtask completion: -```bash -# Check git status -git status --short - -# Verify expected changes -git diff --stat - -# Optional: Check for untracked files that should be committed -git ls-files --others --exclude-standard -``` - -**Verification Checks**: -- Files modified match subtask scope -- No unexpected changes in unrelated files -- No merge conflicts or errors -- Code compiles/runs (if applicable) - -### Phase 4: TodoWrite Tracking with Groups - -**Initial Setup with Task Flow**: -```javascript -TodoWrite({ - todos: [ - // Display task flow diagram first - { content: "Task Flow Analysis Complete - See diagram above", status: "completed", activeForm: "Analyzing task flow" }, - - // Group A subtasks (will use resume within group) - { content: "[Group A] Subtask 1: [description]", status: "in_progress", activeForm: "Executing Group A subtask 1" }, - { content: "[Group A] Subtask 2: [description] [resume]", status: "pending", activeForm: "Executing Group A subtask 2" }, - - // Group B subtasks (new session, then resume within group) - { content: "[Group B] Subtask 1: [description] [new session]", status: "pending", activeForm: "Executing Group B subtask 1" }, - { content: "[Group B] Subtask 2: [description] [resume]", status: "pending", activeForm: "Executing Group B subtask 2" }, - - // Group C subtasks (new session) - { content: "[Group C] Subtask 1: [description] [new session]", status: "pending", activeForm: "Executing Group C subtask 1" }, - - { content: "Final verification and summary", status: "pending", activeForm: "Verifying and summarizing" } - ] -}) -``` - -**After Each Subtask**: -```javascript -TodoWrite({ - todos: [ - { content: "Task Flow Analysis Complete - See diagram above", status: "completed", activeForm: "Analyzing task flow" }, - { content: "[Group A] Subtask 1: [description]", status: "completed", activeForm: "Executing Group A subtask 1" }, - { content: "[Group A] Subtask 2: [description] [resume]", status: "in_progress", activeForm: "Executing Group A subtask 2" }, - // ... update status - ] -}) -``` - -## Codex Resume Mechanism - -**Why Group-Based Resume?** -- **Within Group**: Maintains conversation context for related subtasks - - Codex remembers previous decisions and patterns - - Reduces context repetition - - Ensures consistency in implementation style -- **Between Groups**: Fresh session for independent tasks - - Avoids context pollution from unrelated work - - Prevents confusion when switching domains - - Maintains focused attention on current group - -**How It Works**: -1. **First subtask in Group A**: Creates new Codex session -2. **Subsequent subtasks in Group A**: Use `codex resume --last` to continue session -3. **First subtask in Group B**: Creates NEW Codex session (no resume) -4. **Subsequent subtasks in Group B**: Use `codex resume --last` within Group B -5. Each group builds on its own context, isolated from other groups - -**When to Resume vs New Session**: -``` -RESUME (same group): - - Subtasks share files/modules - - Logical continuation of previous work - - Same architectural domain - -NEW SESSION (different group): - - Independent task area - - Different files/modules - - Switching architectural domains - - Testing after implementation -``` - -**Image Support**: -```bash -# First subtask with design reference -codex -C [dir] -i design.png --full-auto exec "..." --skip-git-repo-check -s danger-full-access - -# Resume for next subtask (image context preserved) -codex exec "CONTINUE TO NEXT SUBTASK: ..." resume --last --skip-git-repo-check -s danger-full-access -``` - -## Error Handling - -**Subtask Failure**: -1. Mark subtask as blocked in TodoWrite -2. Report error details to user -3. Pause execution for manual intervention -4. Use AskUserQuestion for recovery decision: - -```typescript -AskUserQuestion({ - questions: [{ - question: "Codex execution failed for the subtask. How should the workflow proceed?", - header: "Recovery", - options: [ - { label: "Retry Subtask", description: "Attempt to execute the same subtask again." }, - { label: "Skip Subtask", description: "Continue to the next subtask in the plan." }, - { label: "Abort Workflow", description: "Stop the entire execution." } - ], - multiSelect: false - }] -}) -``` - -**Git Verification Failure** (if --verify-git): -1. Show unexpected changes -2. Pause execution -3. Request user decision: - - Continue anyway - - Rollback and retry - - Manual fix - -**Codex Session Lost**: -1. Detect if `codex exec "..." resume --last` fails -2. Attempt retry with fresh session -3. Report to user if manual intervention needed - -## Output Format - -**During Execution**: -``` -Task Flow Diagram: -[Group A: Auth Core] - A1: Create user model ──┐ - A2: Add validation ─┤─► [resume] ─► A3: Database schema - │ -[Group B: API Layer] │ - B1: Auth endpoints ─────┘─► [new session] - B2: Middleware ────────────► [resume] ─► B3: Error handling - -[Group C: Testing] - C1: Unit tests ─────────────► [new session] - C2: Integration tests ──────► [resume] - -Task Decomposition: - [Group A] 1. Create user model - [Group A] 2. Add validation logic [resume] - [Group A] 3. Implement database schema [resume] - [Group B] 4. Create auth endpoints [new session] - [Group B] 5. Add middleware [resume] - [Group B] 6. Error handling [resume] - [Group C] 7. Unit tests [new session] - [Group C] 8. Integration tests [resume] - -[Group A] Executing Subtask 1/8: Create user model - Starting new Codex session for Group A... - [Codex output] - Subtask 1 completed - -Git Verification: - M src/models/user.ts - Changes verified - -[Group A] Executing Subtask 2/8: Add validation logic - Resuming Codex session (same group)... - [Codex output] - Subtask 2 completed - -[Group B] Executing Subtask 4/8: Create auth endpoints - Starting NEW Codex session for Group B... - [Codex output] - Subtask 4 completed -... - -All Subtasks Completed -Summary: [file references, changes, next steps] -``` - -**Final Summary**: -```markdown -# Task Execution Summary: [Task Description] - -## Subtasks Completed -1. [Subtask 1]: [files modified] -2. [Subtask 2]: [files modified] -... - -## Files Modified -- src/file1.ts:10-50 - [changes] -- src/file2.ts - [changes] - -## Git Status -- N files modified -- M files added -- No conflicts - -## Next Steps -- [Suggested follow-up actions] -``` - -## Examples - -**Example 1: Simple Task with Groups** -```bash -/cli:codex-execute "implement user authentication system" - -# Task Flow Diagram: -# [Group A: Data Layer] -# A1: Create user model ──► [resume] ──► A2: Database schema -# -# [Group B: Auth Logic] -# B1: JWT token generation ──► [new session] -# B2: Authentication middleware ──► [resume] -# -# [Group C: API Endpoints] -# C1: Login/logout endpoints ──► [new session] -# -# [Group D: Testing] -# D1: Unit tests ──► [new session] -# D2: Integration tests ──► [resume] - -# Execution: -# Group A: A1 (new) → A2 (resume) -# Group B: B1 (new) → B2 (resume) -# Group C: C1 (new) -# Group D: D1 (new) → D2 (resume) -``` - -**Example 2: With Git Verification** -```bash -/cli:codex-execute --verify-git "refactor API layer to use dependency injection" - -# After each subtask, verifies: -# - Only expected files modified -# - No breaking changes in unrelated code -# - Tests still pass -``` - -**Example 3: With Task ID** -```bash -/cli:codex-execute IMPL-001 - -# Loads task from .task/IMPL-001.json -# Decomposes based on task requirements -``` - -## Best Practices - -1. **Task Flow First**: Always create visual flow diagram before execution -2. **Group Related Work**: Cluster subtasks by domain/files for efficient resume -3. **Subtask Granularity**: Keep subtasks small and focused (5-15 min each) -4. **Clear Boundaries**: Each subtask should have well-defined input/output -5. **Git Hygiene**: Use `--verify-git` for critical refactoring -6. **Pre-Execution Staging**: Stage changes before each subtask to clearly see codex modifications -7. **Smart Resume**: Use `resume --last` ONLY within same group -8. **Fresh Sessions**: Start new session when switching to different group/domain -9. **Recovery Points**: TodoWrite with group labels provides clear progress tracking -10. **Image References**: Attach design files for UI tasks (first subtask in group) - -## Input Processing - -**Automatic Detection**: -- Input matches task ID pattern → Load from `.task/[ID].json` -- Otherwise → Use as task description - -**Task JSON Structure** (when loading from file): -```json -{ - "task_id": "IMPL-001", - "title": "Implement user authentication", - "description": "Create JWT-based auth system", - "acceptance_criteria": [...], - "scope": {...}, - "brainstorming_refs": [...] -} -``` - -## Output Routing - -**Execution Log Destination**: -- **IF** active workflow session exists: - - Execution log: `.workflow/active/WFS-[id]/.chat/codex-execute-[timestamp].md` - - Task summaries: `.workflow/active/WFS-[id]/.summaries/[TASK-ID]-summary.md` (if task ID) - - Task updates: `.workflow/active/WFS-[id]/.task/[TASK-ID].json` status updates - - TodoWrite tracking: Embedded in execution log -- **ELSE** (no active session): - - **Recommended**: Create workflow session first (`/workflow:session:start`) - - **Alternative**: Save to `.workflow/.scratchpad/codex-execute-[description]-[timestamp].md` - -**Output Files** (during execution): -``` -.workflow/active/WFS-[session-id]/ -├── .chat/ -│ └── codex-execute-20250105-143022.md # Full execution log with task flow -├── .summaries/ -│ ├── IMPL-001.1-summary.md # Subtask summaries -│ ├── IMPL-001.2-summary.md -│ └── IMPL-001-summary.md # Final task summary -└── .task/ - ├── IMPL-001.json # Updated task status - └── [subtask JSONs if decomposed] -``` - -**Examples**: -- During session `WFS-auth-system`, executing multi-stage auth implementation: - - Log: `.workflow/active/WFS-auth-system/.chat/codex-execute-20250105-143022.md` - - Summaries: `.workflow/active/WFS-auth-system/.summaries/IMPL-001.{1,2,3}-summary.md` - - Task status: `.workflow/active/WFS-auth-system/.task/IMPL-001.json` (status: completed) -- No session, ad-hoc multi-stage task: - - Log: `.workflow/.scratchpad/codex-execute-auth-refactor-20250105-143045.md` - -**Save Results**: -- Execution log with task flow diagram and TodoWrite tracking -- Individual summaries for each completed subtask -- Final consolidated summary when all subtasks complete -- Modified code files throughout project - -## Notes - -**vs. `/cli:execute`**: -- `/cli:execute`: Single-shot execution with Gemini/Qwen/Codex -- `/cli:codex-execute`: Multi-stage Codex execution with automatic task decomposition and resume mechanism - -**Input Flexibility**: Accepts both freeform descriptions and task IDs (auto-detects and loads JSON) - -**Context Window**: `codex exec "..." resume --last` maintains conversation history, ensuring consistency across subtasks without redundant context injection. - -**Output Details**: -- Session management: see intelligent-tools-strategy.md -- **⚠️ Code Modification**: This command performs multi-stage code modifications - execution log tracks all changes diff --git a/.claude/commands/cli/discuss-plan.md b/.claude/commands/cli/discuss-plan.md deleted file mode 100644 index 78019533..00000000 --- a/.claude/commands/cli/discuss-plan.md +++ /dev/null @@ -1,320 +0,0 @@ ---- -name: discuss-plan -description: Multi-round collaborative planning using Gemini, Codex, and Claude synthesis with iterative discussion cycles (read-only, no code changes) -argument-hint: "[--topic '...'] [--task-id '...'] [--rounds N]" -allowed-tools: SlashCommand(*), Bash(*), TodoWrite(*), Read(*), Glob(*) ---- - -# CLI Discuss-Plan Command (/cli:discuss-plan) - -## Purpose - -Orchestrates a multi-model collaborative discussion for in-depth planning and problem analysis. This command facilitates an iterative dialogue between Gemini, Codex, and Claude (the orchestrating AI) to explore a topic from multiple perspectives, refine ideas, and build a robust plan. - -**This command is for discussion and planning ONLY. It does NOT modify any code.** - -## Core Workflow: The Discussion Loop - -The command operates in iterative rounds, allowing the plan to evolve with each cycle. The user can choose to continue for more rounds or conclude when consensus is reached. - -``` -Topic Input → [Round 1: Gemini → Codex → Claude] → [User Review] → -[Round 2: Gemini → Codex → Claude] → ... → Final Plan -``` - -### Model Roles & Priority - -**Priority Order**: Gemini > Codex > Claude - -1. **Gemini (The Analyst)** - Priority 1 - - Kicks off each round with deep analysis - - Provides foundational ideas and draft plans - - Analyzes current context or previous synthesis - -2. **Codex (The Architect/Critic)** - Priority 2 - - Reviews Gemini's output critically - - Uses deep reasoning for technical trade-offs - - Proposes alternative strategies - - **Participates purely in conversational/reasoning capacity** - - Uses resume mechanism to maintain discussion context - -3. **Claude (The Synthesizer/Moderator)** - Priority 3 - - Synthesizes discussion from Gemini and Codex - - Highlights agreements and contentions - - Structures refined plan - - Poses key questions for next round - -## Parameters - -- `` (Required): Topic description or task ID (e.g., "Design a new caching layer" or `PLAN-002`) -- `--rounds ` (Optional): Maximum number of discussion rounds (default: prompts after each round) -- `--task-id ` (Optional): Associates discussion with workflow task ID -- `--topic ` (Optional): High-level topic for discussion - -## Execution Flow - -### Phase 1: Initial Setup - -1. **Input Processing**: Parse topic or task ID -2. **Context Gathering**: Identify relevant files based on topic - -### Phase 2: Discussion Round - -Each round consists of three sequential steps, tracked via `TodoWrite`. - -**Step 1: Gemini's Analysis (Priority 1)** - -Gemini analyzes the topic and proposes preliminary plan. - -```bash -# Round 1: CONTEXT_INPUT is the initial topic -# Subsequent rounds: CONTEXT_INPUT is the synthesis from previous round -gemini -p " -PURPOSE: Analyze and propose a plan for '[topic]' -TASK: Provide initial analysis, identify key modules, and draft implementation plan -MODE: analysis -CONTEXT: @CLAUDE.md [auto-detected files] -INPUT: [CONTEXT_INPUT] -EXPECTED: Structured analysis and draft plan for discussion -RULES: Focus on technical depth and practical considerations -" -``` - -**Step 2: Codex's Critique (Priority 2)** - -Codex reviews Gemini's output using conversational reasoning. Uses `resume --last` to maintain context across rounds. - -```bash -# First round (new session) -codex --full-auto exec " -PURPOSE: Critically review technical plan -TASK: Review the provided plan, identify weaknesses, suggest alternatives, reason about trade-offs -MODE: analysis -CONTEXT: @CLAUDE.md [relevant files] -INPUT_PLAN: [Output from Gemini's analysis] -EXPECTED: Critical review with alternative ideas and risk analysis -RULES: Focus on architectural soundness and implementation feasibility -" --skip-git-repo-check - -# Subsequent rounds (resume discussion) -codex --full-auto exec " -PURPOSE: Re-evaluate plan based on latest synthesis -TASK: Review updated plan and discussion points, provide further critique or refined ideas -MODE: analysis -CONTEXT: Previous discussion context (maintained via resume) -INPUT_PLAN: [Output from Gemini's analysis for current round] -EXPECTED: Updated critique building on previous discussion -RULES: Build on previous insights, avoid repeating points -" resume --last --skip-git-repo-check -``` - -**Step 3: Claude's Synthesis (Priority 3)** - -Claude (orchestrating AI) synthesizes both outputs: - -- Summarizes Gemini's proposal and Codex's critique -- Highlights agreements and disagreements -- Structures consolidated plan -- Presents open questions for next round -- This synthesis becomes input for next round - -### Phase 3: User Review and Iteration - -1. **Present Synthesis**: Show synthesized plan and key discussion points -2. **Continue or Conclude**: Use AskUserQuestion to prompt user: - -```typescript -AskUserQuestion({ - questions: [{ - question: "Round of discussion complete. What is the next step?", - header: "Next Round", - options: [ - { label: "Start another round", description: "Continue the discussion to refine the plan further." }, - { label: "Conclude and finalize", description: "End the discussion and save the final plan." } - ], - multiSelect: false - }] -}) -``` - -3. **Loop or Finalize**: - - Continue → New round with Gemini analyzing latest synthesis - - Conclude → Save final synthesized document - -## TodoWrite Tracking - -Progress tracked for each round and model. - -```javascript -// Example for 2-round discussion -TodoWrite({ - todos: [ - // Round 1 - { content: "[Round 1] Gemini: Analyzing topic", status: "completed", activeForm: "Analyzing with Gemini" }, - { content: "[Round 1] Codex: Critiquing plan", status: "completed", activeForm: "Critiquing with Codex" }, - { content: "[Round 1] Claude: Synthesizing discussion", status: "completed", activeForm: "Synthesizing discussion" }, - { content: "[User Action] Review Round 1 and decide next step", status: "in_progress", activeForm: "Awaiting user decision" }, - - // Round 2 - { content: "[Round 2] Gemini: Analyzing refined plan", status: "pending", activeForm: "Analyzing refined plan" }, - { content: "[Round 2] Codex: Re-evaluating plan [resume]", status: "pending", activeForm: "Re-evaluating with Codex" }, - { content: "[Round 2] Claude: Finalizing plan", status: "pending", activeForm: "Finalizing plan" }, - { content: "Discussion complete - Final plan generated", status: "pending", activeForm: "Generating final document" } - ] -}) -``` - -## Output Routing - -- **Primary Log**: Entire multi-round discussion logged to single file: - - `.workflow/active/WFS-[id]/.chat/discuss-plan-[topic]-[timestamp].md` -- **Final Plan**: Clean final version saved upon conclusion: - - `.workflow/active/WFS-[id]/.summaries/plan-[topic].md` -- **Scratchpad**: If no session active: - - `.workflow/.scratchpad/discuss-plan-[topic]-[timestamp].md` - -## Discussion Structure - -Each round's output is structured as: - -```markdown -## Round N: [Topic] - -### Gemini's Analysis (Priority 1) -[Gemini's full analysis and proposal] - -### Codex's Critique (Priority 2) -[Codex's critical review and alternatives] - -### Claude's Synthesis (Priority 3) -**Points of Agreement:** -- [Agreement 1] -- [Agreement 2] - -**Points of Contention:** -- [Issue 1]: Gemini suggests X, Codex suggests Y -- [Issue 2]: Trade-off between A and B - -**Consolidated Plan:** -[Structured plan incorporating both perspectives] - -**Open Questions for Next Round:** -1. [Question 1] -2. [Question 2] -``` - -## Examples - -### Example 1: Multi-Round Architecture Discussion - -**Command**: `/cli:discuss-plan --topic "Design a real-time notification system"` - -**Round 1**: -1. **Gemini**: Proposes WebSocket-based architecture with RabbitMQ message queue -2. **Codex**: Critiques as overly complex for MVP. Suggests Server-Sent Events (SSE) for simplicity (one-way notifications). Questions RabbitMQ necessity, proposes simpler Redis Pub/Sub -3. **Claude**: Synthesizes views: - - **Plan A (Gemini)**: WebSockets + RabbitMQ (highly scalable, complex) - - **Plan B (Codex)**: SSE + Redis (simpler, less overhead) - - **Open Question**: Is bi-directional communication critical, or is simplicity priority? -4. **User Action**: Opts for another round to explore trade-offs - -**Round 2**: -1. **Gemini**: Analyzes synthesized document. Notes that if features like "user is typing" indicators are roadmapped, WebSockets better long-term. Drafts plan starting with SSE/Redis but designing for easy migration -2. **Codex**: Reviews migration plan. Reasons that migration itself could be complex. If feature set likely to expand, starting with WebSockets using managed service might be best cost/benefit -3. **Claude**: Synthesizes new discussion: - - **Consensus**: Simple SSE/Redis too short-sighted - - **Refined Options**: - 1. Phased approach (SSE → WebSocket) with clear migration plan - 2. Direct WebSocket with managed service (Pusher, Ably) to reduce ops overhead - - **Recommendation**: Option 2 most robust and future-proof -4. **User Action**: Agrees with recommendation, concludes discussion - -**Final Output**: Planning document saved with: -- Chosen architecture (Managed WebSocket service) -- Multi-round reasoning -- High-level implementation steps - -### Example 2: Feature Design Discussion - -**Command**: `/cli:discuss-plan --topic "Design user permission system" --rounds 2` - -**Round 1**: -1. **Gemini**: Proposes RBAC (Role-Based Access Control) with predefined roles -2. **Codex**: Suggests ABAC (Attribute-Based Access Control) for more flexibility -3. **Claude**: Synthesizes trade-offs between simplicity (RBAC) vs flexibility (ABAC) - -**Round 2**: -1. **Gemini**: Analyzes hybrid approach - RBAC for core permissions, attributes for fine-grained control -2. **Codex**: Reviews hybrid model, identifies implementation challenges -3. **Claude**: Final plan with phased rollout strategy - -**Automatic Conclusion**: Command concludes after 2 rounds as specified - -### Example 3: Problem-Solving Discussion - -**Command**: `/cli:discuss-plan --topic "Debug memory leak in data pipeline" --task-id ISSUE-042` - -**Round 1**: -1. **Gemini**: Identifies potential leak sources (unclosed handles, growing cache, event listeners) -2. **Codex**: Adds profiling tool recommendations, suggests memory monitoring -3. **Claude**: Structures debugging plan with phased approach - -**User Decision**: Single round sufficient, concludes with debugging strategy - -## Consensus Mechanisms - -**When to Continue:** -- Significant disagreement between models -- Open questions requiring deeper analysis -- Trade-offs need more exploration -- User wants additional perspectives - -**When to Conclude:** -- Models converge on solution -- All key questions addressed -- User satisfied with plan depth -- Maximum rounds reached (if specified) - -## Comparison with Other Commands - -| Command | Models | Rounds | Discussion | Implementation | Use Case | -|---------|--------|--------|------------|----------------|----------| -| `/cli:mode:plan` | Gemini | 1 | NO | NO | Single-model planning | -| `/cli:analyze` | Gemini/Qwen | 1 | NO | NO | Code analysis | -| `/cli:execute` | Any | 1 | NO | YES | Direct implementation | -| `/cli:codex-execute` | Codex | 1 | NO | YES | Multi-stage implementation | -| `/cli:discuss-plan` | **Gemini+Codex+Claude** | **Multiple** | **YES** | **NO** | **Multi-perspective planning** | - -## Best Practices - -1. **Use for Complex Decisions**: Ideal for architectural decisions, design trade-offs, problem-solving -2. **Start with Broad Topic**: Let first round establish scope, subsequent rounds refine -3. **Review Each Synthesis**: Claude's synthesis is key decision point - review carefully -4. **Know When to Stop**: Don't over-iterate - 2-3 rounds usually sufficient -5. **Task Association**: Use `--task-id` for traceability in workflow -6. **Save Intermediate Results**: Each round's synthesis saved automatically -7. **Let Models Disagree**: Divergent views often reveal important trade-offs -8. **Focus Questions**: Use Claude's open questions to guide next round - -## Breaking Discussion Loops - -**Detecting Loops:** -- Models repeating same arguments -- No new insights emerging -- Trade-offs well understood - -**Breaking Strategies:** -1. **User Decision**: Make executive decision when enough info gathered -2. **Timeboxing**: Set max rounds upfront with `--rounds` -3. **Criteria-Based**: Define decision criteria before starting -4. **Hybrid Approach**: Accept multiple valid solutions in final plan - -## Notes - -- **Pure Discussion**: This command NEVER modifies code - only produces planning documents -- **Codex Role**: Codex participates as reasoning/critique tool, not executor -- **Resume Context**: Codex maintains discussion context via `resume --last` -- **Priority System**: Ensures Gemini leads analysis, Codex provides critique, Claude synthesizes -- **Output Quality**: Multi-perspective discussion produces more robust plans than single-model analysis -- Command patterns and session management: see intelligent-tools-strategy.md (loaded in memory) -- For implementation after discussion, use `/cli:execute` or `/cli:codex-execute` separately diff --git a/.claude/commands/cli/execute.md b/.claude/commands/cli/execute.md deleted file mode 100644 index 0314702d..00000000 --- a/.claude/commands/cli/execute.md +++ /dev/null @@ -1,202 +0,0 @@ ---- -name: execute -description: Autonomous code implementation with YOLO auto-approval using Gemini/Qwen/Codex, supports task ID or description input with automatic file pattern detection -argument-hint: "[--tool codex|gemini|qwen] [--enhance] description or task-id" -allowed-tools: SlashCommand(*), Bash(*), Task(*) ---- - -# CLI Execute Command (/cli:execute) - -## Purpose - -Execute implementation tasks with **YOLO permissions** (auto-approves all confirmations). **MODIFIES CODE**. - -**Intent**: Autonomous code implementation, modification, and generation -**Supported Tools**: codex, gemini (default), qwen -**Key Feature**: Automatic context inference and file pattern detection - -## Core Behavior - -1. **Code Modification**: This command MODIFIES, CREATES, and DELETES code files -2. **Auto-Approval**: YOLO mode bypasses confirmation prompts for all operations -3. **Implementation Focus**: Executes actual code changes, not just recommendations -4. **Requires Explicit Intent**: Use only when implementation is intended - -## Core Concepts - -### YOLO Permissions -Auto-approves: file pattern inference, execution, **file modifications**, summary generation - -**WARNING**: This command will make actual code changes without manual confirmation - -### Execution Modes - -**1. Description Mode** (supports `--enhance`): -- Input: Natural language description -- Process: [Optional: Enhance] → Keyword analysis → Pattern inference → Execute - -**2. Task ID Mode** (no `--enhance`): -- Input: Workflow task identifier (e.g., `IMPL-001`) -- Process: Task JSON parsing → Scope analysis → Execute - -**3. Agent Mode** (default): -- Input: Description or task-id -- Process: 5-Phase Workflow → Context Discovery → Optimal Tool Selection → Execute - -### Context Inference - -Auto-selects files based on keywords and technology (each @ references one pattern): -- "auth" → `@**/*auth* @**/*user*` -- "React" → `@src/**/*.jsx @src/**/*.tsx` -- "api" → `@**/api/**/* @**/routes/**/*` -- Always includes: `@CLAUDE.md @**/*CLAUDE.md` - -For precise file targeting, use `rg` or MCP tools to discover files first. - -### Codex Session Continuity - -**Resume Pattern** for related tasks: -```bash -# First task - establish session -codex -C [dir] --full-auto exec "[task]" --skip-git-repo-check -s danger-full-access - -# Related task - continue session -codex --full-auto exec "[related-task]" resume --last --skip-git-repo-check -s danger-full-access -``` - -Use `resume --last` when current task extends/relates to previous execution. See intelligent-tools-strategy.md for auto-resume rules. - -## Parameters - -- `--tool ` - Select CLI tool (default: auto-select by agent based on complexity) -- `--enhance` - Enhance input with `/enhance-prompt` first (Description Mode only) -- `` - Natural language description or task identifier -- `--debug` - Verbose logging -- `--save-session` - Save execution to workflow session - -## Workflow Integration - -**Session Management**: Auto-detects active session from `.workflow/active/` directory -- Active session: Save to `.workflow/active/WFS-[id]/.chat/execute-[timestamp].md` -- No session: Create new session or save to scratchpad - -**Task Integration**: Load from `.task/[TASK-ID].json`, update status, generate summary - -## Execution Flow - -Uses **cli-execution-agent** (default) for automated implementation: - -```javascript -Task( - subagent_type="cli-execution-agent", - description="Autonomous code implementation with YOLO auto-approval", - prompt=` - Task: ${description_or_task_id} - Mode: execute - Tool: ${tool_flag || 'auto-select'} - Enhance: ${enhance_flag} - Task-ID: ${task_id} - - Execute autonomous code implementation with full modification permissions: - - 1. Task Analysis: - ${task_id ? '- Load task spec from .task/' + task_id + '.json' : ''} - - Parse requirements and implementation scope - - Classify complexity (simple/medium/complex) - - Extract keywords for context discovery - - 2. Context Discovery: - - Discover implementation files using MCP/ripgrep - - Identify existing patterns and conventions (CLAUDE.md) - - Map dependencies and integration points - - Gather related tests and documentation - - Auto-detect file patterns from keywords - - 3. Tool Selection & Execution: - - Complexity assessment: - * Simple/Medium → Gemini/Qwen (MODE=write, --approval-mode yolo) - * Complex → Codex (MODE=auto, --skip-git-repo-check -s danger-full-access) - - Tool preference: ${tool_flag || 'auto-select based on complexity'} - - Apply appropriate implementation template - - Execute with YOLO auto-approval (bypasses all confirmations) - - 4. Implementation: - - Modify/create/delete code files per requirements - - Follow existing code patterns and conventions - - Include comprehensive context in CLI command - - Ensure working implementation with proper error handling - - 5. Output & Documentation: - - Save execution log: .workflow/active/WFS-[id]/.chat/execute-[timestamp].md - ${task_id ? '- Generate task summary: .workflow/active/WFS-[id]/.summaries/' + task_id + '-summary.md' : ''} - ${task_id ? '- Update task status in .task/' + task_id + '.json' : ''} - - Document all code changes made - - ⚠️ YOLO Mode: All file operations auto-approved without confirmation - ` -) -``` - -**Output**: `.workflow/active/WFS-[id]/.chat/execute-[timestamp].md` + `.workflow/active/WFS-[id]/.summaries/[TASK-ID]-summary.md` (or `.scratchpad/` if no session) - -## Examples - -**Basic Implementation** (modifies code): -```bash -/cli:execute "implement JWT authentication with middleware" -# Agent Phase 1: Classifies intent=execute, complexity=medium, keywords=['jwt', 'auth', 'middleware'] -# Agent Phase 2: Discovers auth patterns, existing middleware structure -# Agent Phase 3: Selects Gemini (medium complexity) -# Agent Phase 4: Executes with auto-approval -# Result: NEW/MODIFIED code files with JWT implementation -``` - -**Complex Implementation** (modifies code): -```bash -/cli:execute "implement OAuth2 authentication with token refresh" -# Agent Phase 1: Classifies intent=execute, complexity=complex, keywords=['oauth2', 'auth', 'token', 'refresh'] -# Agent Phase 2: MCP discovers auth patterns, existing middleware, JWT dependencies -# Agent Phase 3: Enhances prompt with discovered patterns and best practices -# Agent Phase 4: Selects Codex (complex task), executes with comprehensive context -# Agent Phase 5: Saves execution log + generates implementation summary -# Result: Complete OAuth2 implementation + detailed execution log -``` - -**Enhanced Implementation** (modifies code): -```bash -/cli:execute --enhance "implement JWT authentication" -# Step 1: Enhance to expand requirements -# Step 2: Execute implementation with auto-approval -# Result: Complete auth system with MODIFIED code files -``` - -**Task Execution** (modifies code): -```bash -/cli:execute IMPL-001 -# Reads: .task/IMPL-001.json for requirements -# Executes: Implementation based on task spec -# Result: Code changes per task definition -``` - -**Codex Implementation** (modifies code): -```bash -/cli:execute --tool codex "optimize database queries" -# Executes: Codex with full file access -# Result: MODIFIED query code, new indexes, updated tests -``` - -**Qwen Code Generation** (modifies code): -```bash -/cli:execute --tool qwen --enhance "refactor auth module" -# Step 1: Enhanced refactoring plan -# Step 2: Execute with MODE=write -# Result: REFACTORED auth code with structural changes -``` - -## Comparison with Analysis Commands - -| Command | Intent | Code Changes | Auto-Approve | -|---------|--------|--------------|--------------| -| `/cli:analyze` | Understand code | NO | N/A | -| `/cli:chat` | Ask questions | NO | N/A | -| `/cli:execute` | **Implement** | **YES** | **YES** | diff --git a/.claude/commands/cli/mode/bug-diagnosis.md b/.claude/commands/cli/mode/bug-diagnosis.md deleted file mode 100644 index 656d73c3..00000000 --- a/.claude/commands/cli/mode/bug-diagnosis.md +++ /dev/null @@ -1,96 +0,0 @@ ---- -name: bug-diagnosis -description: Read-only bug root cause analysis using Gemini/Qwen/Codex with systematic diagnosis template for fix suggestions -argument-hint: "[--tool codex|gemini|qwen] [--enhance] [--cd path] bug description" -allowed-tools: SlashCommand(*), Bash(*), Task(*) ---- - -# CLI Mode: Bug Diagnosis (/cli:mode:bug-diagnosis) - -## Purpose - -Systematic bug diagnosis with root cause analysis template (`~/.claude/workflows/cli-templates/prompts/analysis/01-diagnose-bug-root-cause.txt`). - -**Tool Selection**: -- **gemini** (default) - Best for bug diagnosis -- **qwen** - Fallback when Gemini unavailable -- **codex** - Alternative for complex bug analysis - -## Parameters - -- `--tool ` - Tool selection (default: gemini) -- `--enhance` - Enhance bug description with `/enhance-prompt` -- `--cd "path"` - Target directory for focused diagnosis -- `` (Required) - Bug description or error details - -## Tool Usage - -**Gemini** (Primary): -```bash -# Uses gemini by default, or specify explicitly ---tool gemini -``` - -**Qwen** (Fallback): -```bash ---tool qwen -``` - -**Codex** (Alternative): -```bash ---tool codex -``` - -## Execution Flow - -Uses **cli-execution-agent** (default) for automated bug diagnosis: - -```javascript -Task( - subagent_type="cli-execution-agent", - description="Bug root cause diagnosis with fix suggestions", - prompt=` - Task: ${bug_description} - Mode: bug-diagnosis - Tool: ${tool_flag || 'gemini'} - Directory: ${cd_path || '.'} - Enhance: ${enhance_flag} - Template: ~/.claude/workflows/cli-templates/prompts/analysis/01-diagnose-bug-root-cause.txt - - Execute systematic bug diagnosis and root cause analysis: - - 1. Context Discovery: - - Locate error traces, stack traces, and log messages - - Find related code sections and affected modules - - Identify data flow paths leading to the bug - - Discover test cases related to bug area - - Use MCP/ripgrep for comprehensive context gathering - - 2. Root Cause Analysis: - - Apply diagnostic template methodology - - Trace execution to identify failure point - - Analyze state, data, and logic causing issue - - Document potential root causes with evidence - - Assess bug severity and impact scope - - 3. CLI Command Construction: - - Tool: ${tool_flag || 'gemini'} (qwen fallback, codex for complex bugs) - - Directory: cd ${cd_path || '.'} && - - Context: @**/* + error traces + affected code - - Mode: analysis (read-only) - - Template: analysis/01-diagnose-bug-root-cause.txt - - 4. Output Generation: - - Root cause diagnosis with evidence - - Fix suggestions and recommendations - - Prevention strategies - - Save to .workflow/active/WFS-[id]/.chat/bug-diagnosis-[timestamp].md (or .scratchpad/) - ` -) -``` - -## Core Rules - -- **Read-only**: Diagnoses bugs, does NOT modify code -- **Template**: `~/.claude/workflows/cli-templates/prompts/analysis/01-diagnose-bug-root-cause.txt` -- **Output**: `.workflow/active/WFS-[id]/.chat/bug-diagnosis-[timestamp].md` (or `.scratchpad/` if no session) diff --git a/.claude/commands/cli/mode/code-analysis.md b/.claude/commands/cli/mode/code-analysis.md deleted file mode 100644 index 31baf30e..00000000 --- a/.claude/commands/cli/mode/code-analysis.md +++ /dev/null @@ -1,98 +0,0 @@ ---- -name: code-analysis -description: Read-only execution path tracing using Gemini/Qwen/Codex with specialized analysis template for call flow and optimization -argument-hint: "[--tool codex|gemini|qwen] [--enhance] [--cd path] analysis target" -allowed-tools: SlashCommand(*), Bash(*), Task(*) ---- - -# CLI Mode: Code Analysis (/cli:mode:code-analysis) - -## Purpose - -Systematic code analysis with execution path tracing template (`~/.claude/workflows/cli-templates/prompts/analysis/01-trace-code-execution.txt`). - -**Tool Selection**: -- **gemini** (default) - Best for code analysis and tracing -- **qwen** - Fallback when Gemini unavailable -- **codex** - Alternative for complex analysis tasks - -**Key Feature**: `--cd` flag for directory-scoped analysis - -## Parameters - -- `--tool ` - Tool selection (default: gemini) -- `--enhance` - Enhance analysis target with `/enhance-prompt` first -- `--cd "path"` - Target directory for focused analysis -- `` (Required) - Code analysis target or question - -## Tool Usage - -**Gemini** (Primary): -```bash -/cli:mode:code-analysis --tool gemini "trace auth flow" -# OR (default) -/cli:mode:code-analysis "trace auth flow" -``` - -**Qwen** (Fallback): -```bash -/cli:mode:code-analysis --tool qwen "trace auth flow" -``` - -**Codex** (Alternative): -```bash -/cli:mode:code-analysis --tool codex "trace auth flow" -``` - -## Execution Flow - -Uses **cli-execution-agent** (default) for automated code analysis: - -```javascript -Task( - subagent_type="cli-execution-agent", - description="Execution path tracing and call flow analysis", - prompt=` - Task: ${analysis_target} - Mode: code-analysis - Tool: ${tool_flag || 'gemini'} - Directory: ${cd_path || '.'} - Enhance: ${enhance_flag} - Template: ~/.claude/workflows/cli-templates/prompts/analysis/01-trace-code-execution.txt - - Execute systematic code analysis with execution path tracing: - - 1. Context Discovery: - - Identify entry points and function signatures - - Trace call chains and execution flows - - Discover related files (implementations, dependencies, tests) - - Map data flow and state transformations - - Use MCP/ripgrep for comprehensive file discovery - - 2. Analysis Execution: - - Apply execution tracing template - - Generate call flow diagrams (textual) - - Document execution paths and branching logic - - Identify optimization opportunities - - 3. CLI Command Construction: - - Tool: ${tool_flag || 'gemini'} (qwen fallback, codex for complex analysis) - - Directory: cd ${cd_path || '.'} && - - Context: @**/* + discovered execution context - - Mode: analysis (read-only) - - Template: analysis/01-trace-code-execution.txt - - 4. Output Generation: - - Execution trace documentation - - Call flow analysis with diagrams - - Performance and optimization insights - - Save to .workflow/active/WFS-[id]/.chat/code-analysis-[timestamp].md (or .scratchpad/) - ` -) -``` - -## Core Rules - -- **Read-only**: Analyzes code, does NOT modify files -- **Template**: `~/.claude/workflows/cli-templates/prompts/analysis/01-trace-code-execution.txt` -- **Output**: `.workflow/active/WFS-[id]/.chat/code-analysis-[timestamp].md` (or `.scratchpad/` if no session) diff --git a/.claude/commands/cli/mode/document-analysis.md b/.claude/commands/cli/mode/document-analysis.md deleted file mode 100644 index 3cd92132..00000000 --- a/.claude/commands/cli/mode/document-analysis.md +++ /dev/null @@ -1,126 +0,0 @@ ---- -name: document-analysis -description: Read-only technical document/paper analysis using Gemini/Qwen/Codex with systematic comprehension template for insights extraction -argument-hint: "[--tool codex|gemini|qwen] [--enhance] [--cd path] document path or topic" -allowed-tools: SlashCommand(*), Bash(*), Task(*), Read(*) ---- - -# CLI Mode: Document Analysis (/cli:mode:document-analysis) - -## Purpose - -Systematic analysis of technical documents, research papers, API documentation, and technical specifications. - -**Tool Selection**: -- **gemini** (default) - Best for document comprehension and structure analysis -- **qwen** - Fallback when Gemini unavailable -- **codex** - Alternative for complex technical documents - -**Key Feature**: `--cd` flag for directory-scoped document discovery - -## Parameters - -- `--tool ` - Tool selection (default: gemini) -- `--enhance` - Enhance analysis target with `/enhance-prompt` -- `--cd "path"` - Target directory for document search -- `` (Required) - File path or topic description - -## Tool Usage - -**Gemini** (Primary): -```bash -/cli:mode:document-analysis "README.md" -/cli:mode:document-analysis --tool gemini "analyze API documentation" -``` - -**Qwen** (Fallback): -```bash -/cli:mode:document-analysis --tool qwen "docs/architecture.md" -``` - -**Codex** (Alternative): -```bash -/cli:mode:document-analysis --tool codex "research paper in docs/" -``` - -## Execution Flow - -Uses **cli-execution-agent** for automated document analysis: - -```javascript -Task( - subagent_type="cli-execution-agent", - description="Systematic document comprehension and insights extraction", - prompt=` - Task: ${document_path_or_topic} - Mode: document-analysis - Tool: ${tool_flag || 'gemini'} - Directory: ${cd_path || '.'} - Enhance: ${enhance_flag} - Template: ~/.claude/workflows/cli-templates/prompts/analysis/02-analyze-technical-document.txt - - Execute systematic document analysis: - - 1. Document Discovery: - - Locate target document(s) via path or topic keywords - - Identify document type (README, API docs, research paper, spec, tutorial) - - Detect document format (Markdown, PDF, plain text, reStructuredText) - - Discover related documents (references, appendices, examples) - - Use MCP/ripgrep for comprehensive file discovery - - 2. Pre-Analysis Planning (Required): - - Determine document structure (sections, hierarchy, flow) - - Identify key components (abstract, methodology, implementation details) - - Map dependencies and cross-references - - Assess document scope and complexity - - Plan analysis approach based on document type - - 3. CLI Command Construction: - - Tool: ${tool_flag || 'gemini'} (qwen fallback, codex for complex docs) - - Directory: cd ${cd_path || '.'} && - - Context: @{document_paths} + @CLAUDE.md + related files - - Mode: analysis (read-only) - - Template: analysis/02-analyze-technical-document.txt - - 4. Analysis Execution: - - Apply 6-field template structure (PURPOSE, TASK, MODE, CONTEXT, EXPECTED, RULES) - - Execute multi-phase analysis protocol with pre-planning - - Perform self-critique before final output - - Generate structured report with evidence-based insights - - 5. Output Generation: - - Comprehensive document analysis report - - Structured insights with section references - - Critical assessment with evidence - - Actionable recommendations - - Save to .workflow/active/WFS-[id]/.chat/doc-analysis-[timestamp].md (or .scratchpad/) - ` -) -``` - -## Core Rules - -- **Read-only**: Analyzes documents, does NOT modify files -- **Evidence-based**: All claims must reference specific sections/pages -- **Pre-planning**: Requires analysis approach planning before execution -- **Precise language**: Direct, accurate wording - no persuasive embellishment -- **Output**: `.workflow/active/WFS-[id]/.chat/doc-analysis-[timestamp].md` (or `.scratchpad/` if no session) - -## Document Types Supported - -| Type | Focus Areas | Key Outputs | -|------|-------------|-------------| -| README | Purpose, setup, usage | Integration steps, quick-start guide | -| API Documentation | Endpoints, parameters, responses | API usage patterns, integration points | -| Research Paper | Methodology, findings, validity | Applicable techniques, implementation feasibility | -| Specification | Requirements, standards, constraints | Compliance checklist, implementation requirements | -| Tutorial | Learning path, examples, exercises | Key concepts, practical applications | -| Architecture Docs | System design, components, patterns | Design decisions, integration points, trade-offs | - -## Best Practices - -1. **Scope Definition**: Clearly define what aspects to analyze before starting -2. **Layered Reading**: Structure/Overview → Details → Critical Analysis → Synthesis -3. **Evidence Trail**: Track section references for all extracted information -4. **Gap Identification**: Note missing information or unclear sections explicitly -5. **Actionable Output**: Focus on insights that inform decisions or actions diff --git a/.claude/commands/cli/mode/plan.md b/.claude/commands/cli/mode/plan.md deleted file mode 100644 index 98d14c23..00000000 --- a/.claude/commands/cli/mode/plan.md +++ /dev/null @@ -1,93 +0,0 @@ ---- -name: plan -description: Read-only architecture planning using Gemini/Qwen/Codex with strategic planning template for modification plans and impact analysis -argument-hint: "[--tool codex|gemini|qwen] [--enhance] [--cd path] topic" -allowed-tools: SlashCommand(*), Bash(*), Task(*) ---- - -# CLI Mode: Plan (/cli:mode:plan) - -## Purpose - -Strategic software architecture planning template (`~/.claude/workflows/cli-templates/prompts/planning/01-plan-architecture-design.txt`). - -**Tool Selection**: -- **gemini** (default) - Best for architecture planning -- **qwen** - Fallback when Gemini unavailable -- **codex** - Alternative for implementation planning - -## Parameters - -- `--tool ` - Tool selection (default: gemini) -- `--enhance` - Enhance task with `/enhance-prompt` -- `--cd "path"` - Target directory for focused planning -- `` (Required) - Architecture planning task or modification requirements - -## Tool Usage - -**Gemini** (Primary): -```bash ---tool gemini # or omit (default) -``` - -**Qwen** (Fallback): -```bash ---tool qwen -``` - -**Codex** (Alternative): -```bash ---tool codex -``` - -## Execution Flow - -Uses **cli-execution-agent** (default) for automated planning: - -```javascript -Task( - subagent_type="cli-execution-agent", - description="Architecture planning with impact analysis", - prompt=` - Task: ${planning_task} - Mode: plan - Tool: ${tool_flag || 'gemini'} - Directory: ${cd_path || '.'} - Enhance: ${enhance_flag} - Template: ~/.claude/workflows/cli-templates/prompts/planning/01-plan-architecture-design.txt - - Execute strategic architecture planning: - - 1. Context Discovery: - - Analyze current architecture structure - - Identify affected components and modules - - Map dependencies and integration points - - Assess modification impacts (scope, complexity, risks) - - 2. Planning Analysis: - - Apply strategic planning template - - Generate modification plan with phases - - Document architectural decisions and rationale - - Identify potential conflicts and mitigation strategies - - 3. CLI Command Construction: - - Tool: ${tool_flag || 'gemini'} (qwen fallback, codex for implementation guidance) - - Directory: cd ${cd_path || '.'} && - - Context: @**/* (full architecture context) - - Mode: analysis (read-only, no code generation) - - Template: planning/01-plan-architecture-design.txt - - 4. Output Generation: - - Strategic modification plan - - Impact analysis and risk assessment - - Implementation roadmap - - Save to .workflow/active/WFS-[id]/.chat/plan-[timestamp].md (or .scratchpad/) - ` -) -``` - -## Core Rules - -- **Read-only**: Creates modification plans, does NOT generate code -- **Template**: `~/.claude/workflows/cli-templates/prompts/planning/01-plan-architecture-design.txt` -- **Output**: `.workflow/active/WFS-[id]/.chat/plan-[timestamp].md` (or `.scratchpad/` if no session) diff --git a/.claude/commands/workflow/review-cycle.md b/.claude/commands/workflow/review-cycle.md new file mode 100644 index 00000000..c0269ec5 --- /dev/null +++ b/.claude/commands/workflow/review-cycle.md @@ -0,0 +1,816 @@ +--- +name: review-cycle +description: Comprehensive multi-dimensional code review with hybrid parallel-iterative execution. Analyzes code across 7 dimensions, aggregates findings, and performs focused deep-dives on critical issues until quality gates met. +argument-hint: "[session-id] [--dimensions=security,architecture,...] [--max-iterations=N] [--output-dir=path] [--resume]" +allowed-tools: SlashCommand(*), TodoWrite(*), Read(*), Bash(*), Task(*) +--- + +# Workflow Review-Cycle Command + +## Quick Start + +```bash +# Execute comprehensive review (all 7 dimensions) +/workflow:review-cycle + +# Custom dimensions selection +/workflow:review-cycle --dimensions=security,architecture,quality + +# Resume interrupted review +/workflow:review-cycle --resume + +# Specify session and iteration limit +/workflow:review-cycle WFS-payment-integration --max-iterations=5 + +# Custom output directory +/workflow:review-cycle --output-dir=.workflow/active/WFS-session/.review-cycle +``` + +**Default Dimensions**: Security, Architecture, Quality, Action-Items, Performance, Maintainability, Best-Practices +**Max Iterations**: 3 (default, adjustable) +**CLI Tools**: Gemini → Qwen → Codex (fallback chain) + +## What & Why + +### Core Concept +Multi-dimensional code review orchestrator with **hybrid parallel-iterative execution** for comprehensive quality assessment. + +**vs Standard Review**: +- **Standard**: Sequential manual reviews → Inconsistent coverage → Missed cross-cutting concerns +- **Review-Cycle**: **Parallel automated analysis → Aggregate findings → Deep-dive critical issues** → Comprehensive coverage + +### Value Proposition +1. **Comprehensive Coverage**: 7 specialized dimensions analyze all quality aspects simultaneously +2. **Intelligent Prioritization**: Automatic identification of critical issues and cross-cutting concerns +3. **Actionable Insights**: Deep-dive iterations provide step-by-step remediation plans +4. **Real-time Visibility**: JSON-based progress tracking with interactive HTML dashboard + +### Orchestrator Boundary (CRITICAL) +- **ONLY command** for comprehensive multi-dimensional review +- Manages: dimension coordination, aggregation, iteration control, progress tracking +- Delegates: Code exploration and analysis to @cli-explore-agent, dimension-specific reviews via Deep Scan mode + +## How It Works + +### Execution Flow (Simplified) + +``` +1. Discovery & Initialization + └─ Validate session, initialize state, create output structure + +2. Phase 2: Parallel Reviews (for each dimension): + ├─ Launch 7 review agents simultaneously + ├─ Each executes CLI analysis via Gemini/Qwen + ├─ Generate dimension JSON + markdown reports + └─ Update review-progress.json + +3. Phase 3: Aggregation: + ├─ Load all dimension JSON files + ├─ Calculate severity distribution (critical/high/medium/low) + ├─ Identify cross-cutting concerns (files in 3+ dimensions) + └─ Decision: + ├─ Critical findings OR high > 5 OR critical files → Phase 4 (Iterate) + └─ Else → Phase 5 (Complete) + +4. Phase 4: Iterative Deep-Dive (optional): + ├─ Select critical findings (max 5 per iteration) + ├─ Launch deep-dive agents for root cause analysis + ├─ Generate remediation plans with impact assessment + ├─ Re-assess severity based on analysis + └─ Loop until no critical findings OR max iterations + +5. Phase 5: Completion + └─ Generate REVIEW-SUMMARY.md → dashboard.html → Output path +``` + +### Agent Roles + +| Agent | Responsibility | +|-------|---------------| +| **Orchestrator** | Phase control, session discovery, state management, aggregation logic, iteration control | +| **@cli-explore-agent** (Review) | Execute dimension-specific code analysis via Deep Scan mode, generate findings JSON with dual-source strategy (Bash + Gemini), create structured analysis reports | +| **@cli-explore-agent** (Deep-dive) | Focused root cause analysis using dependency mapping, remediation planning with architectural insights, impact assessment, severity re-assessment | + +## Enhanced Features + +### 1. Review Dimensions Configuration + +**7 Specialized Dimensions** with priority-based allocation: + +| Dimension | Template | Priority | Timeout | +|-----------|----------|----------|---------| +| **Security** | 03-assess-security-risks.txt | 1 (Critical) | 60min | +| **Architecture** | 02-review-architecture.txt | 2 (High) | 60min | +| **Quality** | 02-review-code-quality.txt | 3 (Medium) | 40min | +| **Action-Items** | 02-analyze-code-patterns.txt | 2 (High) | 40min | +| **Performance** | 03-analyze-performance.txt | 3 (Medium) | 60min | +| **Maintainability** | 02-review-code-quality.txt* | 3 (Medium) | 40min | +| **Best-Practices** | 03-review-quality-standards.txt | 3 (Medium) | 40min | + +*Custom focus: "Assess technical debt and maintainability" + +**Category Definitions by Dimension**: + +```javascript +const CATEGORIES = { + security: ['injection', 'authentication', 'authorization', 'encryption', 'input-validation', 'access-control', 'data-exposure'], + architecture: ['coupling', 'cohesion', 'layering', 'dependency', 'pattern-violation', 'scalability', 'separation-of-concerns'], + quality: ['code-smell', 'duplication', 'complexity', 'naming', 'error-handling', 'testability', 'readability'], + 'action-items': ['requirement-coverage', 'acceptance-criteria', 'documentation', 'deployment-readiness', 'missing-functionality'], + performance: ['n-plus-one', 'inefficient-query', 'memory-leak', 'blocking-operation', 'caching', 'resource-usage'], + maintainability: ['technical-debt', 'magic-number', 'long-method', 'large-class', 'dead-code', 'commented-code'], + 'best-practices': ['convention-violation', 'anti-pattern', 'deprecated-api', 'missing-validation', 'inconsistent-style'] +}; +``` + +### 2. Aggregation Logic + +**Cross-Cutting Concern Detection**: +1. Files appearing in 3+ dimensions = **Critical Files** +2. Same issue pattern across dimensions = **Systemic Issue** +3. Severity clustering in specific files = **Hotspots** + +**Deep-Dive Selection Criteria**: +- All critical severity findings (priority 1) +- Top 3 high-severity findings in critical files (priority 2) +- Max 5 findings per iteration (prevent overwhelm) + +### 3. Severity Assessment + +**Severity Levels**: +- **Critical**: Security vulnerabilities, data corruption risks, system-wide failures, authentication/authorization bypass +- **High**: Feature degradation, performance bottlenecks, architecture violations, significant technical debt +- **Medium**: Code smells, minor performance issues, style inconsistencies, maintainability concerns +- **Low**: Documentation gaps, minor refactoring opportunities, cosmetic issues + +**Iteration Trigger**: +- Critical findings > 0 OR +- High findings > 5 OR +- Critical files count > 0 + +## Core Responsibilities + +### Orchestrator + +**Phase 1: Discovery & Initialization** +- Session discovery: Auto-detect active session if not specified +- Validation: Ensure session has completed implementation (check .summaries/) +- State initialization: Create review-state.json with dimensions, max_iterations +- Directory structure: Create .review-cycle/{dimensions,iterations,reports}/ +- TodoWrite initialization: Set up progress tracking + +**Phase 2: Parallel Review Coordination** +- Launch 7 @cli-explore-agent instances simultaneously (Deep Scan mode) +- Pass dimension-specific context (template, timeout, custom focus) +- Monitor completion via review-progress.json updates +- TodoWrite updates: Mark dimensions as completed +- CLI tool fallback: Gemini → Qwen → Codex (on error/timeout) + +**Phase 3: Aggregation** +- Load all dimension JSON files from dimensions/ +- Calculate severity distribution: Count by critical/high/medium/low +- Identify cross-cutting concerns: Files in 3+ dimensions +- Select deep-dive findings: Critical + high in critical files (max 5) +- Decision logic: Iterate if critical > 0 OR high > 5 OR critical files exist +- Update review-state.json with aggregation results + +**Phase 4: Iteration Control** +- Check iteration count < max_iterations (default 3) +- Launch deep-dive agents for selected findings +- Collect remediation plans and re-assessed severities +- Update severity distribution based on re-assessments +- Record iteration in review-state.json +- Loop back to aggregation if still have critical/high findings + +**Phase 5: Completion** +- Generate REVIEW-SUMMARY.md with all findings and statistics +- Generate dashboard.html from template (see Dashboard Generation below) +- Update review-state.json with completion_time and phase=complete +- TodoWrite completion: Mark all tasks done +- Output: Dashboard path to user with opening instructions + +### Review Agent (@cli-explore-agent) + +**Analysis Mode**: Deep Scan (Phase 1: Bash structural + Phase 2: Gemini semantic + Phase 3: Synthesis) + +**Context Provided by Orchestrator**: +```javascript +{ + dimension: "security|architecture|quality|...", + session_id: "WFS-xxx", + session_metadata_path: ".workflow/active/WFS-xxx/workflow-session.json", + summaries_dir: ".workflow/active/WFS-xxx/.summaries/", + output_paths: { + json: ".review-cycle/dimensions/{dimension}.json", + report: ".review-cycle/reports/{dimension}-analysis.md", + cli_output: ".review-cycle/reports/{dimension}-cli-output.txt" + }, + cli_config: { + tool: "gemini", + template: "~/.claude/workflows/cli-templates/prompts/analysis/xxx.txt", + timeout: 3600000, + mode: "analysis" + } +} +``` + +**Deliverables**: +1. Dimension JSON with findings array (see JSON Schema below) +2. Analysis markdown report with summary and recommendations +3. CLI output log for debugging + +### Deep-Dive Agent (@cli-explore-agent) + +**Analysis Mode**: Dependency Map + Deep Scan (for root cause analysis with architectural context) + +**Context Provided**: +```javascript +{ + finding_id: "uuid", + original_finding: {...}, + iteration: 1, + output_paths: { + json: ".review-cycle/iterations/iteration-1-finding-{uuid}.json", + report: ".review-cycle/reports/deep-dive-1-{uuid}.md" + }, + cli_config: { + tool: "gemini", + template: "01-diagnose-bug-root-cause.txt", + timeout: 2400000 + } +} +``` + +**Deliverables**: +1. Deep-dive JSON with root cause, remediation plan, impact assessment +2. Analysis report with detailed recommendations + +## Dashboard Generation + +### Mechanism + +Dashboard uses **static HTML + JSON polling**: reads template from `~/.claude/templates/review-cycle-dashboard.html`, replaces placeholders, writes to output directory. Dashboard polls `review-progress.json` every 5 seconds for real-time updates, then loads all dimension JSON files when `phase=complete`. + +### Phase 5 Steps + +1. **Read & Process Template** + ```javascript + const template = Read('~/.claude/templates/review-cycle-dashboard.html'); + const dashboard = template.replace('{{SESSION_ID}}', sessionId); + Write(`${outputDir}/dashboard.html`, dashboard); + ``` + +2. **Auto-open in Browser** (optional) + ```javascript + Bash(`start ${dashboardPath}`); // Windows + Bash(`open ${dashboardPath}`); // macOS + Bash(`xdg-open ${dashboardPath}`); // Linux + ``` + +3. **Output Path to User** + ``` + ✅ Review Complete! + 📊 Dashboard: file://${absolutePath}/dashboard.html + ``` + +### Features Summary + +- **Real-time Progress**: Phase indicator, progress bar, agent status (auto-refresh 5s) +- **Interactive Findings**: Severity/dimension filtering, search, sort, detail drawer +- **Export**: Generate markdown report +- **Dark Mode**: Toggle with localStorage persistence + +**Usage Details**: See `~/.claude/workflows/DASHBOARD-QUICKSTART.md` + +## Reference + +### CLI Tool Configuration + +**Fallback Chain**: Gemini → Qwen → Codex (same as test-cycle-execute) + +**Tool Details**: +1. **Gemini** (primary): `gemini-2.5-pro` - 60min timeout +2. **Qwen** (fallback): `coder-model` - 60min timeout +3. **Codex** (fallback): `gpt-5.1-codex` - 60min timeout + +**When to Fallback**: HTTP 429, timeout, invalid JSON output, confidence < 0.4 + +### Session File Structure + +``` +.workflow/active/WFS-{session}/.review-cycle/ +├── review-state.json # Orchestrator state machine +├── review-progress.json # Real-time progress for dashboard +├── dimensions/ # Per-dimension results +│ ├── security.json +│ ├── architecture.json +│ ├── quality.json +│ ├── action-items.json +│ ├── performance.json +│ ├── maintainability.json +│ └── best-practices.json +├── iterations/ # Deep-dive results +│ ├── iteration-1-finding-{uuid}.json +│ └── iteration-2-finding-{uuid}.json +├── reports/ # Human-readable reports +│ ├── security-analysis.md +│ ├── security-cli-output.txt +│ ├── deep-dive-1-{uuid}.md +│ └── ... +├── REVIEW-SUMMARY.md # Final summary +└── dashboard.html # Interactive dashboard +``` + +### Review State JSON + +**Purpose**: Persisted state machine for phase transitions and iteration control - enables Resume + +```json +{ + "session_id": "WFS-payment-integration", + "review_id": "review-20250125-143022", + "phase": "parallel|aggregate|iterate|complete", + "current_iteration": 1, + "max_iterations": 3, + "dimensions_reviewed": ["security", "architecture", "quality", "action-items", "performance", "maintainability", "best-practices"], + "selected_strategy": "comprehensive", + "next_action": "execute_parallel_reviews|aggregate_findings|execute_deep_dive|generate_final_report|complete", + "severity_distribution": { + "critical": 2, + "high": 5, + "medium": 12, + "low": 8 + }, + "critical_files": [ + { + "file": "src/payment/processor.ts", + "finding_count": 5, + "dimensions": ["security", "architecture", "quality"] + } + ], + "iterations": [ + { + "iteration": 1, + "findings_analyzed": ["uuid-1", "uuid-2"], + "findings_resolved": 1, + "findings_escalated": 1, + "severity_change": { + "before": {"critical": 2, "high": 5, "medium": 12, "low": 8}, + "after": {"critical": 1, "high": 6, "medium": 12, "low": 8} + }, + "timestamp": "2025-01-25T14:30:00Z" + } + ], + "completion_criteria": { + "target": "no_critical_findings_and_high_under_5", + "current_status": "in_progress", + "estimated_completion": "2 iterations remaining" + } +} +``` + +**Field Descriptions**: +- `phase`: Current execution phase (state machine pointer) +- `current_iteration`: Iteration counter (used for max check) +- `next_action`: Next step orchestrator should execute +- `severity_distribution`: Aggregated counts across all dimensions +- `critical_files`: Files appearing in 3+ dimensions with metadata +- `iterations[]`: Historical log for trend analysis + +### Review Progress JSON + +**Purpose**: Real-time dashboard updates via polling + +```json +{ + "review_id": "review-20250125-143022", + "last_update": "2025-01-25T14:35:10Z", + "phase": "parallel|aggregate|iterate|complete", + "current_iteration": 1, + "progress": { + "parallel_review": { + "total_dimensions": 7, + "completed": 5, + "in_progress": 2, + "percent_complete": 71 + }, + "deep_dive": { + "total_findings": 6, + "analyzed": 2, + "in_progress": 1, + "percent_complete": 33 + } + }, + "agent_status": [ + { + "agent_type": "review-agent", + "dimension": "security", + "status": "completed", + "started_at": "2025-01-25T14:30:00Z", + "completed_at": "2025-01-25T15:15:00Z", + "duration_ms": 2700000 + }, + { + "agent_type": "deep-dive-agent", + "finding_id": "sec-001-uuid", + "status": "in_progress", + "started_at": "2025-01-25T14:32:00Z" + } + ], + "estimated_completion": "2025-01-25T16:00:00Z" +} +``` + +### Agent Output Schemas + +**Agent-produced JSON files follow standardized schemas**: + +1. **Dimension Results** (cli-explore-agent output from parallel reviews) + - Schema: `~/.claude/workflows/cli-templates/schemas/review-dimension-results-schema.json` + - Output: `.review-cycle/dimensions/{dimension}.json` + - Contains: findings array, summary statistics, cross_references + +2. **Deep-Dive Results** (cli-explore-agent output from iterations) + - Schema: `~/.claude/workflows/cli-templates/schemas/review-deep-dive-results-schema.json` + - Output: `.review-cycle/iterations/iteration-{N}-finding-{uuid}.json` + - Contains: root_cause, remediation_plan, impact_assessment, reassessed_severity + +### Agent Invocation Template + +**Review Agent** (parallel execution, 7 instances): + +```javascript +Task( + subagent_type="cli-explore-agent", + description=`Execute ${dimension} review analysis via Deep Scan`, + prompt=` + ## Task Objective + Conduct comprehensive ${dimension} code exploration and analysis using Deep Scan mode (Bash + Gemini dual-source strategy) for completed implementation in session ${sessionId} + + ## Analysis Mode Selection + Use **Deep Scan mode** for this review: + - Phase 1: Bash structural scan for standard patterns (classes, functions, imports) + - Phase 2: Gemini semantic analysis for design intent, non-standard patterns, ${dimension}-specific concerns + - Phase 3: Synthesis with attribution (bash-discovered vs gemini-discovered findings) + + ## MANDATORY FIRST STEPS + 1. Read session metadata: ${sessionMetadataPath} + 2. Read completed task summaries: bash(find ${summariesDir} -name "IMPL-*.md" -type f) + 3. Get changed files: bash(cd ${workflowDir} && git log --since="${sessionCreatedAt}" --name-only --pretty=format: | sort -u) + 4. Read review state: ${reviewStateJsonPath} + + ## Session Context + - Session ID: ${sessionId} + - Review Dimension: ${dimension} + - Review ID: ${reviewId} + - Implementation Phase: Complete (all tests passing) + - Output Directory: ${outputDir} + + ## CLI Configuration + - Tool Priority: gemini → qwen → codex (fallback chain) + - Template: ~/.claude/workflows/cli-templates/prompts/analysis/${dimensionTemplate} + - Custom Focus: ${customFocus || 'Standard dimension analysis'} + - Timeout: ${timeout}ms + - Mode: analysis (READ-ONLY) + + ## Expected Deliverables + 1. Dimension Results JSON: ${outputDir}/dimensions/${dimension}.json + - MUST follow schema: ~/.claude/workflows/cli-templates/schemas/review-dimension-results-schema.json + - MUST include: findings array with severity, file, line, description, recommendation + - MUST include: summary statistics (total findings, severity distribution) + - MUST include: cross_references to related findings + 2. Analysis Report: ${outputDir}/reports/${dimension}-analysis.md + - Human-readable summary with recommendations + - Grouped by severity: critical → high → medium → low + - Include file:line references for all findings + 3. CLI Output Log: ${outputDir}/reports/${dimension}-cli-output.txt + - Raw CLI tool output for debugging + - Include full analysis text + + ## Dimension-Specific Guidance + ${getDimensionGuidance(dimension)} + + ## Success Criteria + - All changed files analyzed for ${dimension} concerns + - All findings include file:line references with code snippets + - Severity assessment follows established criteria (see reference) + - Recommendations are actionable with code examples + - JSON output is valid and follows schema exactly + - Report is comprehensive and well-organized + ` +) +``` + +**Deep-Dive Agent** (iteration execution): + +```javascript +Task( + subagent_type="cli-explore-agent", + description=`Deep-dive analysis for critical finding: ${findingTitle} via Dependency Map + Deep Scan`, + prompt=` + ## Task Objective + Perform focused root cause analysis using Dependency Map mode (for impact analysis) + Deep Scan mode (for semantic understanding) to generate comprehensive remediation plan for critical ${dimension} issue + + ## Analysis Mode Selection + Use **Dependency Map mode** first to understand dependencies: + - Build dependency graph around ${file} to identify affected components + - Detect circular dependencies or tight coupling related to this finding + - Calculate change risk scores for remediation impact + + Then apply **Deep Scan mode** for semantic analysis: + - Understand design intent and architectural context + - Identify non-standard patterns or implicit dependencies + - Extract remediation insights from code structure + + ## Finding Context + - Finding ID: ${findingId} + - Original Dimension: ${dimension} + - Title: ${findingTitle} + - File: ${file}:${line} + - Severity: ${severity} + - Category: ${category} + - Original Description: ${description} + - Iteration: ${iteration} + + ## MANDATORY FIRST STEPS + 1. Read original finding: ${dimensionJsonPath} + 2. Read affected file: ${file} + 3. Identify related code: bash(grep -r "import.*${basename(file)}" ${workflowDir}/src --include="*.ts") + 4. Read test files: bash(find ${workflowDir}/tests -name "*${basename(file, '.ts')}*" -type f) + + ## CLI Configuration + - Tool Priority: gemini → qwen → codex + - Template: ~/.claude/workflows/cli-templates/prompts/analysis/01-diagnose-bug-root-cause.txt + - Timeout: 2400000ms (40 minutes) + - Mode: analysis (READ-ONLY) + + ## Expected Deliverables + 1. Deep-Dive Results JSON: ${outputDir}/iterations/iteration-${iteration}-finding-${findingId}.json + - MUST follow schema: ~/.claude/workflows/cli-templates/schemas/review-deep-dive-results-schema.json + - MUST include: root_cause with summary, details, affected_scope, similar_patterns + - MUST include: remediation_plan with approach, steps[], estimated_effort, risk_level + - MUST include: impact_assessment with files_affected, tests_required, breaking_changes + - MUST include: reassessed_severity with severity_change_reason + - MUST include: confidence_score (0.0-1.0) + 2. Analysis Report: ${outputDir}/reports/deep-dive-${iteration}-${findingId}.md + - Detailed root cause analysis + - Step-by-step remediation plan + - Impact assessment and rollback strategy + + ## Success Criteria + - Root cause clearly identified with supporting evidence + - Remediation plan is step-by-step actionable with exact file:line references + - Each step includes specific commands and validation tests + - Impact fully assessed (files, tests, breaking changes, dependencies) + - Severity re-evaluation justified with evidence + - Confidence score accurately reflects certainty of analysis + - References include project-specific and external documentation + ` +) +``` + +### Dimension Guidance Reference + +```javascript +function getDimensionGuidance(dimension) { + const guidance = { + security: ` + Focus Areas: + - Input validation and sanitization + - Authentication and authorization mechanisms + - Data encryption (at-rest and in-transit) + - SQL/NoSQL injection vulnerabilities + - XSS, CSRF, and other web vulnerabilities + - Sensitive data exposure + - Access control and privilege escalation + + Severity Criteria: + - Critical: Authentication bypass, SQL injection, RCE, sensitive data exposure + - High: Missing authorization checks, weak encryption, exposed secrets + - Medium: Missing input validation, insecure defaults, weak password policies + - Low: Security headers missing, verbose error messages, outdated dependencies + `, + architecture: ` + Focus Areas: + - Layering and separation of concerns + - Coupling and cohesion + - Design pattern adherence + - Dependency management + - Scalability and extensibility + - Module boundaries + - API design consistency + + Severity Criteria: + - Critical: Circular dependencies, god objects, tight coupling across layers + - High: Violated architectural principles, scalability bottlenecks + - Medium: Missing abstractions, inconsistent patterns, suboptimal design + - Low: Minor coupling issues, documentation gaps, naming inconsistencies + `, + quality: ` + Focus Areas: + - Code duplication + - Complexity (cyclomatic, cognitive) + - Naming conventions + - Error handling patterns + - Code readability + - Comment quality + - Dead code + + Severity Criteria: + - Critical: Severe complexity (CC > 20), massive duplication (>50 lines) + - High: High complexity (CC > 10), significant duplication, poor error handling + - Medium: Moderate complexity (CC > 5), naming issues, code smells + - Low: Minor duplication, documentation gaps, cosmetic issues + `, + 'action-items': ` + Focus Areas: + - Requirements coverage verification + - Acceptance criteria met + - Documentation completeness + - Deployment readiness + - Missing functionality + - Test coverage gaps + - Configuration management + + Severity Criteria: + - Critical: Core requirements not met, deployment blockers + - High: Significant functionality missing, acceptance criteria not met + - Medium: Minor requirements gaps, documentation incomplete + - Low: Nice-to-have features missing, minor documentation gaps + `, + performance: ` + Focus Areas: + - N+1 query problems + - Inefficient algorithms (O(n²) where O(n log n) possible) + - Memory leaks + - Blocking operations on main thread + - Missing caching opportunities + - Resource usage (CPU, memory, network) + - Database query optimization + + Severity Criteria: + - Critical: Memory leaks, O(n²) in hot path, blocking main thread + - High: N+1 queries, missing indexes, inefficient algorithms + - Medium: Suboptimal caching, unnecessary computations, lazy loading issues + - Low: Minor optimization opportunities, redundant operations + `, + maintainability: ` + Focus Areas: + - Technical debt indicators + - Magic numbers and hardcoded values + - Long methods (>50 lines) + - Large classes (>500 lines) + - Dead code and commented code + - Code documentation + - Test coverage + + Severity Criteria: + - Critical: Massive methods (>200 lines), severe technical debt blocking changes + - High: Large methods (>100 lines), significant dead code, undocumented complex logic + - Medium: Magic numbers, moderate technical debt, missing tests + - Low: Minor refactoring opportunities, cosmetic improvements + `, + 'best-practices': ` + Focus Areas: + - Framework conventions adherence + - Language idioms + - Anti-patterns + - Deprecated API usage + - Coding standards compliance + - Error handling patterns + - Logging and monitoring + + Severity Criteria: + - Critical: Severe anti-patterns, deprecated APIs with security risks + - High: Major convention violations, poor error handling, missing logging + - Medium: Minor anti-patterns, style inconsistencies, suboptimal patterns + - Low: Cosmetic style issues, minor convention deviations + ` + }; + + return guidance[dimension] || 'Standard code review analysis'; +} +``` + +### Completion Conditions + +**Full Success**: +- All dimensions reviewed +- Critical findings = 0 +- High findings ≤ 5 +- Action: Generate final report, mark phase=complete + +**Partial Success**: +- All dimensions reviewed +- Max iterations reached +- Still have critical/high findings +- Action: Generate report with warnings, recommend follow-up + +**Resume Capability**: +- Read review-state.json on startup +- Check phase and next_action +- Resume from current phase (parallel/aggregate/iterate) +- Preserve iteration history + +### Error Handling + +| Scenario | Action | +|----------|--------| +| Session not found | Error: Provide session ID or ensure active session exists | +| No completed tasks | Error: Complete implementation before review | +| CLI analysis failure | Fallback: Gemini → Qwen → Codex → degraded mode | +| Invalid JSON output | Retry with clarified prompt, fallback to next tool | +| Max iterations reached | Generate report with remaining issues, mark partial success | +| Agent timeout | Log timeout, continue with available results | +| Missing dimension file | Skip in aggregation, log warning | + +**CLI Fallback Triggers** (same as test-cycle-execute): +1. Invalid JSON output (parse error, missing required fields) +2. Low confidence score < 0.4 +3. HTTP 429, 5xx errors, timeouts +4. Analysis too brief (< 100 words in report) + +### TodoWrite Structure + +```javascript +TodoWrite({ + todos: [ + { + content: "Phase 1: Discovery & Initialization", + status: "completed", + activeForm: "Completed discovery & initialization" + }, + { + content: "Phase 2: Parallel Reviews (7 dimensions)", + status: "in_progress", + activeForm: "Executing parallel reviews" + }, + { + content: " → Security review", + status: "completed", + activeForm: "Analyzing security" + }, + { + content: " → Architecture review", + status: "completed", + activeForm: "Analyzing architecture" + }, + { + content: " → Quality review", + status: "in_progress", + activeForm: "Analyzing quality" + }, + { + content: " → Action-Items review", + status: "pending", + activeForm: "Analyzing action items" + }, + { + content: " → Performance review", + status: "pending", + activeForm: "Analyzing performance" + }, + { + content: " → Maintainability review", + status: "pending", + activeForm: "Analyzing maintainability" + }, + { + content: " → Best-Practices review", + status: "pending", + activeForm: "Analyzing best practices" + }, + { + content: "Phase 3: Aggregation", + status: "pending", + activeForm: "Aggregating findings" + }, + { + content: "Phase 4: Iteration 1 - Deep-dive (5 findings)", + status: "pending", + activeForm: "Executing deep-dive iteration 1" + }, + { + content: "Phase 5: Completion", + status: "pending", + activeForm: "Generating final report" + } + ] +}); +``` + +**Update Rules**: +- Add dimension items during parallel phase +- Add iteration items dynamically based on findings +- Mark completed immediately after each phase/agent +- Update parent task when phase complete + +## Best Practices + +1. **Default Settings Work**: 7 dimensions + 3 iterations sufficient for most cases +2. **Parallel Execution**: ~60 minutes for full initial review (7 dimensions) +3. **Trust Aggregation Logic**: Auto-selection based on proven heuristics +4. **Monitor Logs**: Check reports/ directory for CLI analysis insights +5. **Dashboard Polling**: Refresh every 5 seconds for real-time updates +6. **Resume Support**: Interrupted reviews can resume from last checkpoint +7. **Export Results**: Use dashboard export for external tracking tools diff --git a/.claude/templates/review-cycle-dashboard.html b/.claude/templates/review-cycle-dashboard.html new file mode 100644 index 00000000..46b8fbd3 --- /dev/null +++ b/.claude/templates/review-cycle-dashboard.html @@ -0,0 +1,1142 @@ + + + + + + Code Review Dashboard - {{SESSION_ID}} + + + +
+
+

🔍 Code Review Dashboard

+
+ 📋 Session: Loading... + 🆔 Review ID: Loading... + 🕒 Last Updated: Loading... +
+ +
+
+ +
+ + +
+
+ + +
+
+

Review Progress

+ LOADING +
+
+
+
+
+ Initializing... +
+
+ + +
+
+
🔴
+
0
+
Critical
+
+
+
🟠
+
0
+
High
+
+
+
🟡
+
0
+
Medium
+
+
+
🟢
+
0
+
Low
+
+
+ + +
+ + + + + + + + +
+ + +
+
+

Findings (0)

+
+ +
+
+
+
+
⏳
+

Loading findings...

+
+
+
+
+ + +
+
+
+
Finding Details
+ +
+
+ +
+
+ + + + + + diff --git a/.claude/workflows/cli-templates/schemas/review-deep-dive-results-schema.json b/.claude/workflows/cli-templates/schemas/review-deep-dive-results-schema.json new file mode 100644 index 00000000..8ddd69cb --- /dev/null +++ b/.claude/workflows/cli-templates/schemas/review-deep-dive-results-schema.json @@ -0,0 +1,291 @@ +{ + "$schema": "http://json-schema.org/draft-07/schema#", + "title": "Review Deep-Dive Results Schema", + "description": "Output schema for cli-explore-agent deep-dive iteration analysis. Contains root cause analysis, remediation plan, and impact assessment for critical findings.", + "type": "object", + "required": [ + "finding_id", + "original_dimension", + "iteration", + "analysis_timestamp", + "cli_tool_used", + "root_cause", + "remediation_plan", + "impact_assessment", + "reassessed_severity", + "confidence_score", + "status" + ], + "properties": { + "finding_id": { + "type": "string", + "description": "Original finding ID from dimension analysis", + "example": "sec-001-a1b2c3d4" + }, + "original_dimension": { + "type": "string", + "enum": ["security", "architecture", "quality", "action-items", "performance", "maintainability", "best-practices"], + "description": "Dimension where finding was originally discovered" + }, + "iteration": { + "type": "integer", + "minimum": 1, + "description": "Deep-dive iteration number" + }, + "analysis_timestamp": { + "type": "string", + "format": "date-time", + "description": "ISO8601 timestamp when deep-dive completed" + }, + "cli_tool_used": { + "type": "string", + "enum": ["gemini", "qwen", "codex"], + "description": "CLI tool used for deep-dive analysis" + }, + "root_cause": { + "type": "object", + "required": ["summary", "details", "affected_scope"], + "properties": { + "summary": { + "type": "string", + "description": "One-sentence root cause summary" + }, + "details": { + "type": "string", + "description": "Detailed explanation with history and context" + }, + "affected_scope": { + "type": "string", + "description": "Full scope of affected code" + }, + "similar_patterns": { + "type": "array", + "items": { + "type": "string" + }, + "description": "List of file:function where similar issue exists" + } + } + }, + "remediation_plan": { + "type": "object", + "required": ["approach", "priority", "estimated_effort", "risk_level", "steps"], + "properties": { + "approach": { + "type": "string", + "description": "High-level fix strategy" + }, + "priority": { + "type": "string", + "pattern": "^P[0-2] - ", + "description": "Priority level with severity label", + "examples": ["P0 - Critical (security vulnerability)", "P1 - High (performance bottleneck)"] + }, + "estimated_effort": { + "type": "string", + "description": "Estimated time for development and testing", + "example": "4 hours development + 2 hours testing" + }, + "risk_level": { + "type": "string", + "enum": ["low", "medium", "high"], + "description": "Risk level of implementing the fix" + }, + "steps": { + "type": "array", + "minItems": 1, + "items": { + "type": "object", + "required": ["step", "action", "files", "commands", "rationale", "validation"], + "properties": { + "step": { + "type": "integer", + "minimum": 1, + "description": "Step sequence number" + }, + "action": { + "type": "string", + "description": "What to do in this step" + }, + "files": { + "type": "array", + "items": { + "type": "string" + }, + "description": "Files to modify with function:lines format", + "examples": ["src/database/query-builder.ts:buildUserQuery:140-150"] + }, + "commands": { + "type": "array", + "items": { + "type": "string" + }, + "description": "Specific code changes or commands to execute" + }, + "rationale": { + "type": "string", + "description": "Why this step is needed" + }, + "validation": { + "type": "string", + "description": "How to verify step completion (test command)", + "example": "Run: npm test -- src/database/query-builder.test.ts" + } + } + } + }, + "rollback_strategy": { + "type": "string", + "description": "How to safely revert changes if needed" + } + } + }, + "impact_assessment": { + "type": "object", + "required": ["files_affected", "tests_required", "breaking_changes"], + "properties": { + "files_affected": { + "type": "array", + "items": { + "type": "string" + }, + "description": "Files affected with action type", + "examples": ["src/database/query-builder.ts (modify)", "src/database/validators.ts (new)"] + }, + "tests_required": { + "type": "array", + "items": { + "type": "string" + }, + "description": "Test files required with action type", + "examples": ["src/database/query-builder.test.ts (update existing)", "src/database/validators.test.ts (new)"] + }, + "breaking_changes": { + "type": "boolean", + "description": "Whether this fix introduces breaking changes" + }, + "dependencies_updated": { + "type": "array", + "items": { + "type": "string" + }, + "description": "Dependencies that need updating", + "examples": ["knex@2.5.1 (ORM library)"] + }, + "deployment_notes": { + "type": "string", + "description": "Special deployment considerations" + } + } + }, + "reassessed_severity": { + "type": "string", + "enum": ["critical", "high", "medium", "low"], + "description": "Updated severity after deep analysis" + }, + "severity_change_reason": { + "type": "string", + "description": "Justification for severity change (or 'No change')" + }, + "confidence_score": { + "type": "number", + "minimum": 0.0, + "maximum": 1.0, + "description": "Confidence level of analysis (0.0-1.0)" + }, + "references": { + "type": "array", + "items": { + "type": "string" + }, + "description": "Project-specific and external documentation references" + }, + "status": { + "type": "string", + "enum": ["remediation_plan_ready", "resolved"], + "description": "Status after deep-dive analysis" + } + }, + "examples": [ + { + "finding_id": "sec-001-a1b2c3d4", + "original_dimension": "security", + "iteration": 1, + "analysis_timestamp": "2025-01-25T14:40:15Z", + "cli_tool_used": "gemini", + "root_cause": { + "summary": "Legacy code from v1 migration, pre-ORM implementation", + "details": "Query builder was ported from old codebase without security review. Team unaware of injection risks in string concatenation pattern. Code review at migration time focused on functionality, not security.", + "affected_scope": "All query-builder.ts methods using string template literals (15 methods total)", + "similar_patterns": [ + "src/database/user-queries.ts:buildEmailQuery", + "src/database/order-queries.ts:buildOrderSearch" + ] + }, + "remediation_plan": { + "approach": "Migrate to ORM prepared statements with input validation layer", + "priority": "P0 - Critical (security vulnerability)", + "estimated_effort": "4 hours development + 2 hours testing", + "risk_level": "low", + "steps": [ + { + "step": 1, + "action": "Replace direct string concatenation with ORM query builder", + "files": ["src/database/query-builder.ts:buildUserQuery:140-150"], + "commands": [ + "Replace: const query = `SELECT * FROM users WHERE id = ${userId}`;", + "With: return db('users').where('id', userId).first();" + ], + "rationale": "ORM automatically parameterizes queries, eliminating injection risk", + "validation": "Run: npm test -- src/database/query-builder.test.ts" + }, + { + "step": 2, + "action": "Add input validation layer before ORM", + "files": ["src/database/validators.ts:validateUserId:NEW"], + "commands": [ + "Create validator: export function validateUserId(id: unknown): number { ... }", + "Add schema: z.number().positive().int()" + ], + "rationale": "Defense in depth - validate types and ranges before database layer", + "validation": "Run: npm test -- src/database/validators.test.ts" + }, + { + "step": 3, + "action": "Apply pattern to all 15 similar methods", + "files": ["src/database/query-builder.ts:ALL_METHODS"], + "commands": ["Bulk replace string templates with ORM syntax"], + "rationale": "Prevent similar vulnerabilities in other query methods", + "validation": "Run: npm test -- src/database/" + } + ], + "rollback_strategy": "Git commit before each step, revert if tests fail. Staged rollout: dev → staging → production with monitoring." + }, + "impact_assessment": { + "files_affected": [ + "src/database/query-builder.ts (modify)", + "src/database/validators.ts (new)", + "src/database/user-queries.ts (modify)", + "src/database/order-queries.ts (modify)" + ], + "tests_required": [ + "src/database/query-builder.test.ts (update existing)", + "src/database/validators.test.ts (new)", + "integration/security/sql-injection.test.ts (new)" + ], + "breaking_changes": false, + "dependencies_updated": ["knex@2.5.1 (ORM library)"], + "deployment_notes": "No downtime required. Database migrations not needed." + }, + "reassessed_severity": "high", + "severity_change_reason": "Found existing WAF rules partially mitigate risk in production. Input validation at API gateway layer provides additional defense. Downgrade from critical to high, but still requires immediate fix.", + "confidence_score": 0.95, + "references": [ + "Project ORM migration guide: docs/architecture/orm-guide.md", + "Knex.js parameterization: https://knexjs.org/guide/query-builder.html#where", + "Similar incident: TICKET-1234 (previous SQL injection fix)" + ], + "status": "remediation_plan_ready" + } + ] +} diff --git a/.claude/workflows/cli-templates/schemas/review-dimension-results-schema.json b/.claude/workflows/cli-templates/schemas/review-dimension-results-schema.json new file mode 100644 index 00000000..caa5e7c0 --- /dev/null +++ b/.claude/workflows/cli-templates/schemas/review-dimension-results-schema.json @@ -0,0 +1,281 @@ +{ + "$schema": "http://json-schema.org/draft-07/schema#", + "title": "Review Dimension Results Schema", + "description": "Output schema for cli-explore-agent dimension analysis results. Contains structured findings from security, architecture, quality, action-items, performance, maintainability, and best-practices reviews.", + "type": "object", + "required": ["dimension", "review_id", "analysis_timestamp", "cli_tool_used", "summary", "findings"], + "properties": { + "dimension": { + "type": "string", + "enum": ["security", "architecture", "quality", "action-items", "performance", "maintainability", "best-practices"], + "description": "Review dimension being analyzed" + }, + "review_id": { + "type": "string", + "pattern": "^review-\\d{8}-\\d{6}$", + "description": "Unique review cycle identifier", + "example": "review-20250125-143022" + }, + "analysis_timestamp": { + "type": "string", + "format": "date-time", + "description": "ISO8601 timestamp when analysis completed" + }, + "cli_tool_used": { + "type": "string", + "enum": ["gemini", "qwen", "codex"], + "description": "CLI tool used for analysis (fallback chain: gemini → qwen → codex)" + }, + "model": { + "type": "string", + "description": "Model name/version used by CLI tool", + "examples": ["gemini-2.5-pro", "coder-model", "gpt-5.1-codex"] + }, + "analysis_duration_ms": { + "type": "integer", + "minimum": 0, + "description": "Analysis duration in milliseconds" + }, + "summary": { + "type": "object", + "required": ["total_findings", "critical", "high", "medium", "low", "files_analyzed", "lines_reviewed"], + "properties": { + "total_findings": { + "type": "integer", + "minimum": 0, + "description": "Total number of findings across all severities" + }, + "critical": { + "type": "integer", + "minimum": 0, + "description": "Count of critical severity findings" + }, + "high": { + "type": "integer", + "minimum": 0, + "description": "Count of high severity findings" + }, + "medium": { + "type": "integer", + "minimum": 0, + "description": "Count of medium severity findings" + }, + "low": { + "type": "integer", + "minimum": 0, + "description": "Count of low severity findings" + }, + "files_analyzed": { + "type": "integer", + "minimum": 0, + "description": "Total number of files analyzed" + }, + "lines_reviewed": { + "type": "integer", + "minimum": 0, + "description": "Total lines of code reviewed" + } + } + }, + "findings": { + "type": "array", + "description": "Array of findings discovered during analysis", + "items": { + "$ref": "#/definitions/unifiedFinding" + } + }, + "cross_references": { + "type": "array", + "description": "Cross-references to findings in other dimensions", + "items": { + "type": "object", + "required": ["finding_id", "related_dimensions", "reason"], + "properties": { + "finding_id": { + "type": "string", + "description": "Finding ID that appears in multiple dimensions" + }, + "related_dimensions": { + "type": "array", + "items": { + "type": "string" + }, + "description": "List of dimensions where this finding appears" + }, + "reason": { + "type": "string", + "description": "Explanation of cross-reference relationship" + } + } + } + } + }, + "definitions": { + "unifiedFinding": { + "type": "object", + "title": "Unified Finding Schema", + "description": "Standardized finding structure applicable to all review dimensions", + "required": ["id", "title", "severity", "category", "description", "file", "line", "snippet", "recommendation", "impact", "iteration", "status"], + "properties": { + "id": { + "type": "string", + "format": "uuid", + "description": "Unique finding identifier (UUID v4)", + "example": "sec-001-a1b2c3d4" + }, + "title": { + "type": "string", + "minLength": 10, + "maxLength": 100, + "description": "Short descriptive title (50-100 chars)" + }, + "severity": { + "type": "string", + "enum": ["critical", "high", "medium", "low"], + "description": "Severity level based on impact and risk" + }, + "category": { + "type": "string", + "description": "Dimension-specific category (see CATEGORIES in review-cycle.md)", + "examples": ["injection", "coupling", "code-smell", "n-plus-one"] + }, + "description": { + "type": "string", + "minLength": 50, + "description": "Detailed description with context (200-500 words)" + }, + "file": { + "type": "string", + "description": "Relative path to affected file", + "example": "src/database/query-builder.ts" + }, + "line": { + "type": "integer", + "minimum": 1, + "description": "Line number where issue occurs" + }, + "snippet": { + "type": "string", + "description": "Code context (5-10 lines around the issue)" + }, + "recommendation": { + "type": "string", + "description": "Actionable fix recommendation with code examples" + }, + "impact": { + "type": "string", + "description": "Potential impact description (business + technical)" + }, + "references": { + "type": "array", + "items": { + "type": "string" + }, + "description": "Documentation URLs and standard references", + "examples": [ + "OWASP Top 10 - A03:2021 Injection", + "https://owasp.org/www-community/attacks/SQL_Injection" + ] + }, + "metadata": { + "type": "object", + "description": "Dimension-specific metadata", + "properties": { + "cwe_id": { + "type": "string", + "description": "CWE identifier (for security findings)", + "example": "CWE-89" + }, + "owasp_category": { + "type": "string", + "description": "OWASP category (for security findings)", + "example": "A03:2021-Injection" + }, + "pattern_type": { + "type": "string", + "description": "Pattern type (for quality findings)", + "examples": ["anti-pattern", "code-smell"] + }, + "complexity_score": { + "type": "number", + "description": "Cyclomatic complexity score (for quality findings)" + } + } + }, + "iteration": { + "type": "integer", + "minimum": 0, + "description": "Iteration number when finding was discovered (0 = initial parallel phase)" + }, + "status": { + "type": "string", + "enum": ["pending_remediation", "remediation_plan_ready", "resolved"], + "description": "Current status of finding" + }, + "cross_references": { + "type": "array", + "items": { + "type": "string" + }, + "description": "List of dimensions where this finding also appears" + }, + "reassessed_severity": { + "type": "string", + "enum": ["critical", "high", "medium", "low"], + "description": "Updated severity if changed in deep-dive iteration" + } + } + } + }, + "examples": [ + { + "dimension": "security", + "review_id": "review-20250125-143022", + "analysis_timestamp": "2025-01-25T14:30:22Z", + "cli_tool_used": "gemini", + "model": "gemini-2.5-pro", + "analysis_duration_ms": 2145000, + "summary": { + "total_findings": 15, + "critical": 2, + "high": 4, + "medium": 6, + "low": 3, + "files_analyzed": 47, + "lines_reviewed": 8932 + }, + "findings": [ + { + "id": "sec-001-a1b2c3d4", + "title": "SQL Injection vulnerability in user query", + "severity": "critical", + "category": "injection", + "description": "Direct string concatenation in SQL query allows injection attacks. User input is not sanitized before query execution.", + "file": "src/database/query-builder.ts", + "line": 145, + "snippet": "const query = `SELECT * FROM users WHERE id = ${userId}`;", + "recommendation": "Use parameterized queries: db.query('SELECT * FROM users WHERE id = ?', [userId])", + "references": [ + "OWASP Top 10 - A03:2021 Injection", + "https://owasp.org/www-community/attacks/SQL_Injection" + ], + "impact": "Potential data breach, unauthorized access to user records, data manipulation", + "metadata": { + "cwe_id": "CWE-89", + "owasp_category": "A03:2021-Injection" + }, + "iteration": 0, + "status": "pending_remediation", + "cross_references": [] + } + ], + "cross_references": [ + { + "finding_id": "sec-001-a1b2c3d4", + "related_dimensions": ["quality", "architecture"], + "reason": "Same file flagged in multiple dimensions" + } + ] + } + ] +}