catlog22/Claude-Code-Workflow
1
0
Fork 0
mirror of https://github.com/catlog22/Claude-Code-Workflow.git synced 2026-02-09 02:24:11 +08:00
Code Issues Packages Projects Releases Wiki Activity

Add JSON schemas for deep-dive results and dimension analysis

Browse Source 
- 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.
This commit is contained in:
catlog22
2025-11-25 16:16:11 +08:00
parent d99448ffd5
commit cd206f275e
13 changed files with 2530 additions and 1623 deletions
Download Patch File Download Diff File Expand all files Collapse all files

87
.claude/commands/cli/analyze.md
View File

@@ -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 <gemini|qwen|codex>` - Tool selection (default: gemini)
- `--enhance` - Use `/enhance-prompt` for context-aware enhancement
- `<analysis-target>` - 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)

82
.claude/commands/cli/chat.md
View File

@@ -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 <gemini|qwen|codex>` - Tool selection (default: gemini)
- `--enhance` - Enhance inquiry with `/enhance-prompt`
- `<inquiry>` (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)

519
.claude/commands/cli/codex-execute.md
View File

@@ -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
- `<input>` (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

320
.claude/commands/cli/discuss-plan.md
View File

@@ -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
- `<input>` (Required): Topic description or task ID (e.g., "Design a new caching layer" or `PLAN-002`)
- `--rounds <N>` (Optional): Maximum number of discussion rounds (default: prompts after each round)
- `--task-id <id>` (Optional): Associates discussion with workflow task ID
- `--topic <description>` (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

202
.claude/commands/cli/execute.md
View File

@@ -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 <codex|gemini|qwen>` - Select CLI tool (default: auto-select by agent based on complexity)
- `--enhance` - Enhance input with `/enhance-prompt` first (Description Mode only)
- `<description|task-id>` - 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** |

96
.claude/commands/cli/mode/bug-diagnosis.md
View File

@@ -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 <gemini|qwen|codex>` - Tool selection (default: gemini)
- `--enhance` - Enhance bug description with `/enhance-prompt`
- `--cd "path"` - Target directory for focused diagnosis
- `<bug-description>` (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)

98
.claude/commands/cli/mode/code-analysis.md
View File

@@ -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 <gemini|qwen|codex>` - Tool selection (default: gemini)
- `--enhance` - Enhance analysis target with `/enhance-prompt` first
- `--cd "path"` - Target directory for focused analysis
- `<analysis-target>` (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)

126
.claude/commands/cli/mode/document-analysis.md
View File

@@ -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 <gemini|qwen|codex>` - Tool selection (default: gemini)
- `--enhance` - Enhance analysis target with `/enhance-prompt`
- `--cd "path"` - Target directory for document search
- `<document-path-or-topic>` (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

93
.claude/commands/cli/mode/plan.md
View File

@@ -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 <gemini|qwen|codex>` - Tool selection (default: gemini)
- `--enhance` - Enhance task with `/enhance-prompt`
- `--cd "path"` - Target directory for focused planning
- `<planning-task>` (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)

816
.claude/commands/workflow/review-cycle.md Normal file
View File

@@ -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

1142
.claude/templates/review-cycle-dashboard.html Normal file
View File

File diff suppressed because it is too large Load Diff

291
.claude/workflows/cli-templates/schemas/review-deep-dive-results-schema.json Normal file
View File

@@ -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"
}
]
}

281
.claude/workflows/cli-templates/schemas/review-dimension-results-schema.json Normal file
View File

@@ -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"
}
]
}
]
}