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

refactor: Update review commands to require active sessions and unify output directory structure for improved organization and clarity

Browse Source
This commit is contained in:
catlog22
2025-11-25 23:02:20 +08:00
parent c3e87db5be
commit 8f2126677f
5 changed files with 485 additions and 47 deletions
Download Patch File Download Diff File Expand all files Collapse all files

85
.claude/commands/workflow/review-module-cycle.md
View File

@@ -26,8 +26,9 @@ allowed-tools: SlashCommand(*), TodoWrite(*), Read(*), Bash(*), Task(*)
/workflow:review-module-cycle --resume
```
**Review Scope**: Specified modules/files only (independent of git history or sessions)
**Output Directory**: `.workflow/.reviews/module-{pattern-hash}/` (fixed location)
**Review Scope**: Specified modules/files only (independent of git history)
**Session Requirement**: Requires active workflow session (or creates review-only session)
**Output Directory**: `.workflow/active/WFS-{session-id}/.review/` (session-based)
**Default Dimensions**: Security, Architecture, Quality, Action-Items, Performance, Maintainability, Best-Practices
**Max Iterations**: 3 (default, adjustable)
**CLI Tools**: Gemini → Qwen → Codex (fallback chain)
@@ -39,19 +40,21 @@ Independent multi-dimensional code review orchestrator with **hybrid parallel-it
**Review Scope**:
- **Module-based**: Reviews specified file patterns (e.g., `src/auth/**`, `*.ts`)
- **No session dependency**: Works independently of workflow sessions
- **For session-based review**: Use `/workflow:review-session-cycle` command instead
- **Session-integrated**: Runs within workflow session context for unified tracking
- **Output location**: `.review/` subdirectory within active session
**vs Session Review**:
- **Session Review** (`review-session-cycle`): Reviews git changes within a workflow session
- **Module Review** (`review-module-cycle`): Reviews any specified code paths, regardless of git history
- **Common output**: Both use same `.review/` directory structure within session
### Value Proposition
1. **Ad-hoc Review**: Review any code without requiring a workflow session
2. **Module-focused**: Target specific areas of codebase for deep analysis
1. **Module-Focused Review**: Target specific code areas independent of git history
2. **Session-Integrated**: Review results tracked within workflow session for unified management
3. **Comprehensive Coverage**: Same 7 specialized dimensions as session review
4. **Intelligent Prioritization**: Automatic identification of critical issues and cross-cutting concerns
5. **Real-time Visibility**: JSON-based progress tracking with interactive HTML dashboard
6. **Unified Archive**: Review results archived with session for historical reference
### Orchestrator Boundary (CRITICAL)
- **ONLY command** for independent multi-dimensional module review
@@ -60,7 +63,7 @@ Independent multi-dimensional code review orchestrator with **hybrid parallel-it
## How It Works
### Execution Flow (Simplified)
### Execution Flow
```
1. Discovery & Initialization
@@ -175,13 +178,45 @@ const CATEGORIES = {
### Orchestrator
**Phase 1: Discovery & Initialization**
- Path resolution: Parse and expand file patterns (glob support)
**Step 1: Session Discovery**
```javascript
// Auto-discover or create session
SlashCommand(command="/workflow:session:start --auto \"Code review for [target_pattern]\"")
// Parse output
const sessionId = output.match(/SESSION_ID: (WFS-[^\s]+)/)[1];
// Validate session exists
Bash(`test -d .workflow/active/${sessionId} && echo "EXISTS"`);
```
**Step 2: Path Resolution & Validation**
- Parse and expand file patterns (glob support): `src/auth/**` → actual file list
- Validation: Ensure all specified files exist and are readable
- Output directory: Set to `.workflow/.reviews/module-{pattern-hash}/` (fixed location, hash based on target pattern)
- State initialization: Create review-state.json with dimensions, max_iterations, resolved_files
- Directory structure: Create {dimensions,iterations,reports}/ subdirectories
- Dashboard generation: Generate dashboard.html from template (see Dashboard Generation below)
- TodoWrite initialization: Set up progress tracking
- Store resolved files as absolute paths (e.g., `D:\\project\\src\\auth\\service.ts`)
**Step 3: Output Directory Setup**
- Output directory: `.workflow/active/${sessionId}/.review/`
- Create directory structure:
```bash
mkdir -p ${sessionDir}/.review/{dimensions,iterations,reports}
```
**Step 4: Initialize Review State**
- Metadata creation: Create `review-metadata.json` with scope, dimensions, and configuration
- State initialization: Create `review-state.json` with dimensions, max_iterations, resolved_files
- Progress tracking: Create `review-progress.json` for dashboard polling
**Step 5: Dashboard Generation**
- Read template: `~/.claude/templates/review-cycle-dashboard.html`
- Replace placeholders: `{{SESSION_ID}}`, `{{REVIEW_TYPE}}`, `{{REVIEW_DIR}}`
- Write to: `${sessionDir}/.review/dashboard.html`
- Output path to user: `file://${absolutePath}/dashboard.html`
**Step 6: TodoWrite Initialization**
- Set up progress tracking with hierarchical structure
- Mark Phase 1 completed, Phase 2 in_progress
**Phase 2: Parallel Review Coordination**
- Launch 7 @cli-explore-agent instances simultaneously (Deep Scan mode)
@@ -315,7 +350,8 @@ Dashboard uses **static HTML + JSON polling**: reads template from `~/.claude/te
### Output File Structure
```
.workflow/.reviews/module-{pattern-hash}/
.workflow/active/WFS-{session-id}/.review/
├── review-metadata.json # Review configuration and scope
├── review-state.json # Orchestrator state machine
├── review-progress.json # Real-time progress for dashboard
├── dimensions/ # Per-dimension results
@@ -338,6 +374,18 @@ Dashboard uses **static HTML + JSON polling**: reads template from `~/.claude/te
└── dashboard.html # Interactive dashboard
```
**Session Context**:
```
.workflow/active/WFS-{session-id}/
├── workflow-session.json
├── IMPL_PLAN.md
├── TODO_LIST.md
├── .task/
├── .summaries/
└── .review/ # Review results (this command)
└── (structure above)
```
### Review State JSON
**Purpose**: Persisted state machine for phase transitions and iteration control - enables Resume
@@ -346,11 +394,12 @@ Dashboard uses **static HTML + JSON polling**: reads template from `~/.claude/te
{
"review_id": "review-20250125-143022",
"review_type": "module",
"session_id": "WFS-auth-system",
"target_pattern": "src/auth/**",
"resolved_files": [
"src/auth/service.ts",
"src/auth/validator.ts",
"src/auth/middleware.ts"
"D:\\project\\src\\auth\\service.ts",
"D:\\project\\src\\auth\\validator.ts",
"D:\\project\\src\\auth\\middleware.ts"
],
"phase": "parallel|aggregate|iterate|complete",
"current_iteration": 1,
@@ -801,7 +850,7 @@ After completing a module review, use the dashboard to select findings and expor
# Dashboard generates: fix-export-{timestamp}.json
# Step 3: Run automated fixes
/workflow:review-fix .workflow/.reviews/module-{hash}/fix-export-{timestamp}.json
/workflow:review-fix .workflow/active/WFS-{session-id}/.review/fix-export-{timestamp}.json
```
See `/workflow:review-fix` for automated fixing with smart grouping, parallel execution, and test verification.

82
.claude/commands/workflow/review-session-cycle.md
View File

@@ -24,7 +24,8 @@ allowed-tools: SlashCommand(*), TodoWrite(*), Read(*), Bash(*), Task(*)
```
**Review Scope**: Git changes from session creation to present (via `git log --since`)
**Output Directory**: `.workflow/.reviews/session-{session-id}/` (fixed location)
**Session Requirement**: Requires active or completed workflow session
**Output Directory**: `.workflow/active/WFS-{session-id}/.review/` (session-based)
**Default Dimensions**: Security, Architecture, Quality, Action-Items, Performance, Maintainability, Best-Practices
**Max Iterations**: 3 (default, adjustable)
**CLI Tools**: Gemini → Qwen → Codex (fallback chain)
@@ -156,13 +157,61 @@ const CATEGORIES = {
### Orchestrator
**Phase 1: Discovery & Initialization**
- Session discovery: Auto-detect active session if not specified
- Validation: Ensure session has completed implementation (check .summaries/)
- Output directory: Set to `.workflow/.reviews/session-{session-id}/` (fixed location)
- State initialization: Create review-state.json with dimensions, max_iterations
- Directory structure: Create {dimensions,iterations,reports}/ subdirectories
- Dashboard generation: Generate dashboard.html from template (see Dashboard Generation below)
- TodoWrite initialization: Set up progress tracking
**Step 1: Session Discovery**
```javascript
// If session ID not provided, auto-detect
if (!providedSessionId) {
// Check for active sessions
const activeSessions = Glob('.workflow/active/WFS-*');
if (activeSessions.length === 1) {
sessionId = activeSessions[0].match(/WFS-[^/]+/)[0];
} else if (activeSessions.length > 1) {
// List sessions and prompt user
error("Multiple active sessions found. Please specify session ID.");
} else {
error("No active session found. Create session first with /workflow:session:start");
}
} else {
sessionId = providedSessionId;
}
// Validate session exists
Bash(`test -d .workflow/active/${sessionId} && echo "EXISTS"`);
```
**Step 2: Session Validation**
- Ensure session has implementation artifacts (check `.summaries/` or `.task/` directory)
- Extract session creation timestamp from `workflow-session.json`
- Use timestamp for git log filtering: `git log --since="${sessionCreatedAt}"`
**Step 3: Changed Files Detection**
```bash
# Get files changed since session creation
git log --since="${sessionCreatedAt}" --name-only --pretty=format: | sort -u
```
**Step 4: Output Directory Setup**
- Output directory: `.workflow/active/${sessionId}/.review/`
- Create directory structure:
```bash
mkdir -p ${sessionDir}/.review/{dimensions,iterations,reports}
```
**Step 5: Initialize Review State**
- Metadata creation: Create `review-metadata.json` with scope, dimensions, and configuration
- State initialization: Create `review-state.json` with dimensions, max_iterations
- Progress tracking: Create `review-progress.json` for dashboard polling
**Step 6: Dashboard Generation**
- Read template: `~/.claude/templates/review-cycle-dashboard.html`
- Replace placeholders: `{{SESSION_ID}}`, `{{REVIEW_TYPE}}`, `{{REVIEW_DIR}}`
- Write to: `${sessionDir}/.review/dashboard.html`
- Output path to user: `file://${absolutePath}/dashboard.html`
**Step 7: TodoWrite Initialization**
- Set up progress tracking with hierarchical structure
- Mark Phase 1 completed, Phase 2 in_progress
**Phase 2: Parallel Review Coordination**
- Launch 7 @cli-explore-agent instances simultaneously (Deep Scan mode)
@@ -304,7 +353,8 @@ Dashboard uses **static HTML + JSON polling**: reads template from `~/.claude/te
### Session File Structure
```
.workflow/.reviews/session-{session-id}/
.workflow/active/WFS-{session-id}/.review/
├── review-metadata.json # Review configuration and scope
├── review-state.json # Orchestrator state machine
├── review-progress.json # Real-time progress for dashboard
├── dimensions/ # Per-dimension results
@@ -327,6 +377,18 @@ Dashboard uses **static HTML + JSON polling**: reads template from `~/.claude/te
└── dashboard.html # Interactive dashboard
```
**Session Context**:
```
.workflow/active/WFS-{session-id}/
├── workflow-session.json
├── IMPL_PLAN.md
├── TODO_LIST.md
├── .task/
├── .summaries/
└── .review/ # Review results (this command)
└── (structure above)
```
### Review State JSON
**Purpose**: Persisted state machine for phase transitions and iteration control - enables Resume
@@ -834,7 +896,7 @@ After completing a review, use the dashboard to select findings and export them
# Dashboard generates: fix-export-{timestamp}.json
# Step 3: Run automated fixes
/workflow:review-fix .workflow/.reviews/session-{session-id}/fix-export-{timestamp}.json
/workflow:review-fix .workflow/active/WFS-{session-id}/.review/fix-export-{timestamp}.json
```
See `/workflow:review-fix` for automated fixing with smart grouping, parallel execution, and test verification.

19
.claude/commands/workflow/session/start.md
View File

@@ -168,25 +168,6 @@ DECISION: Reusing existing session
SESSION_ID: WFS-promptmaster-platform
```
## Command Integration
### For /workflow:plan (Use Auto Mode)
```bash
SlashCommand(command="/workflow:session:start --auto \"implement OAuth2 authentication\"")
# Parse session ID from output
grep "^SESSION_ID:" | awk '{print $2}'
```
### For Interactive Workflows (Use Discovery Mode)
```bash
SlashCommand(command="/workflow:session:start")
```
### For New Isolated Work (Use Force New Mode)
```bash
SlashCommand(command="/workflow:session:start --new \"experimental feature\"")
```
## Session ID Format
- Pattern: `WFS-[lowercase-slug]`

336
.claude/workflows/review-directory-specification.md Normal file
View File

@@ -0,0 +1,336 @@
# Review Directory Specification
## Overview
Unified directory structure for all review commands (session-based and module-based) within workflow sessions.
## Core Principles
1. **Session-Based**: All reviews run within a workflow session context
2. **Unified Structure**: Same directory layout for all review types
3. **Type Differentiation**: Review type indicated by metadata, not directory structure
4. **Progressive Creation**: Directories created on-demand during review execution
5. **Archive Support**: Reviews archived with their parent session
## Directory Structure
### Base Location
```
.workflow/active/WFS-{session-id}/.review/
```
### Complete Structure
```
.workflow/active/WFS-{session-id}/.review/
├── review-state.json # Review orchestrator state machine
├── review-progress.json # Real-time progress for dashboard polling
├── review-metadata.json # Review configuration and scope
├── dimensions/ # Per-dimension analysis results
│ ├── security.json
│ ├── architecture.json
│ ├── quality.json
│ ├── action-items.json
│ ├── performance.json
│ ├── maintainability.json
│ └── best-practices.json
├── iterations/ # Deep-dive iteration results
│ ├── iteration-1-finding-{uuid}.json
│ ├── iteration-2-finding-{uuid}.json
│ └── ...
├── reports/ # Human-readable reports
│ ├── security-analysis.md
│ ├── security-cli-output.txt
│ ├── architecture-analysis.md
│ ├── architecture-cli-output.txt
│ ├── ...
│ ├── deep-dive-1-{uuid}.md
│ └── deep-dive-2-{uuid}.md
├── REVIEW-SUMMARY.md # Final consolidated summary
└── dashboard.html # Interactive review dashboard
```
## Review Metadata Schema
**File**: `review-metadata.json`
```json
{
"review_id": "review-20250125-143022",
"review_type": "module|session",
"session_id": "WFS-auth-system",
"created_at": "2025-01-25T14:30:22Z",
"scope": {
"type": "module|session",
"module_scope": {
"target_pattern": "src/auth/**",
"resolved_files": [
"D:\\project\\src\\auth\\service.ts",
"D:\\project\\src\\auth\\validator.ts"
],
"file_count": 2
},
"session_scope": {
"commit_range": "abc123..def456",
"changed_files": [
"D:\\project\\src\\auth\\service.ts",
"D:\\project\\src\\payment\\processor.ts"
],
"file_count": 2
}
},
"dimensions": ["security", "architecture", "quality", "action-items", "performance", "maintainability", "best-practices"],
"max_iterations": 3,
"cli_tools": {
"primary": "gemini",
"fallback": ["qwen", "codex"]
}
}
```
## Review State Schema
**File**: `review-state.json`
```json
{
"review_id": "review-20250125-143022",
"phase": "init|parallel|aggregate|iterate|complete",
"current_iteration": 1,
"dimensions_status": {
"security": "pending|in_progress|completed|failed",
"architecture": "completed",
"quality": "in_progress",
"action-items": "pending",
"performance": "pending",
"maintainability": "pending",
"best-practices": "pending"
},
"severity_distribution": {
"critical": 2,
"high": 5,
"medium": 12,
"low": 8
},
"critical_files": [
"D:\\project\\src\\auth\\service.ts",
"D:\\project\\src\\payment\\processor.ts"
],
"iterations": [
{
"iteration": 1,
"findings_selected": ["uuid-1", "uuid-2", "uuid-3"],
"completed_at": "2025-01-25T15:30:00Z"
}
],
"completion_criteria": {
"critical_count": 0,
"high_count_threshold": 5,
"max_iterations": 3
},
"next_action": "execute_parallel_reviews|aggregate_findings|execute_deep_dive|generate_final_report|complete"
}
```
## Session Integration
### Session Discovery
**review-session-cycle** (auto-discover):
```bash
# Auto-detect active session
/workflow:review-session-cycle
# Or specify session explicitly
/workflow:review-session-cycle WFS-auth-system
```
**review-module-cycle** (require session):
```bash
# Must have active session or specify one
/workflow:review-module-cycle src/auth/** --session WFS-auth-system
# Or use active session
/workflow:review-module-cycle src/auth/**
```
### Session Creation Logic
**For review-module-cycle**:
1. **Check Active Session**: Search `.workflow/active/WFS-*`
2. **If Found**: Use active session's `.review/` directory
3. **If Not Found**:
- **Option A** (Recommended): Prompt user to create session first
- **Option B**: Auto-create review-only session: `WFS-review-{pattern-hash}`
**Recommended Flow**:
```bash
# Step 1: Start session
/workflow:session:start --new "Review auth module"
# Creates: .workflow/active/WFS-review-auth-module/
# Step 2: Run review
/workflow:review-module-cycle src/auth/**
# Creates: .workflow/active/WFS-review-auth-module/.review/
```
## Command Phase 1 Requirements
### Both Commands Must:
1. **Session Discovery**:
```javascript
// Check for active session
const sessions = Glob('.workflow/active/WFS-*');
if (sessions.length === 0) {
// Prompt user to create session first
error("No active session found. Please run /workflow:session:start first");
}
const sessionId = sessions[0].match(/WFS-[^/]+/)[0];
```
2. **Create .review/ Structure**:
```javascript
const reviewDir = `.workflow/active/${sessionId}/.review/`;
// Create directory structure
Bash(`mkdir -p ${reviewDir}/dimensions`);
Bash(`mkdir -p ${reviewDir}/iterations`);
Bash(`mkdir -p ${reviewDir}/reports`);
```
3. **Initialize Metadata**:
```javascript
// Write review-metadata.json
Write(`${reviewDir}/review-metadata.json`, JSON.stringify({
review_id: `review-${timestamp}`,
review_type: "module|session",
session_id: sessionId,
created_at: new Date().toISOString(),
scope: {...},
dimensions: [...],
max_iterations: 3,
cli_tools: {...}
}));
// Write review-state.json
Write(`${reviewDir}/review-state.json`, JSON.stringify({
review_id: `review-${timestamp}`,
phase: "init",
current_iteration: 0,
dimensions_status: {},
severity_distribution: {},
critical_files: [],
iterations: [],
completion_criteria: {},
next_action: "execute_parallel_reviews"
}));
```
4. **Generate Dashboard**:
```javascript
const template = Read('~/.claude/templates/review-cycle-dashboard.html');
const dashboard = template
.replace('{{SESSION_ID}}', sessionId)
.replace('{{REVIEW_TYPE}}', reviewType)
.replace('{{REVIEW_DIR}}', reviewDir);
Write(`${reviewDir}/dashboard.html`, dashboard);
// Output to user
console.log(`📊 Review Dashboard: file://${absolutePath(reviewDir)}/dashboard.html`);
console.log(`📂 Review Output: ${reviewDir}`);
```
## Archive Strategy
### On Session Completion
When `/workflow:session:complete` is called:
1. **Preserve Review Directory**:
```javascript
// Move entire session including .review/
Bash(`mv .workflow/active/${sessionId} .workflow/archives/${sessionId}`);
```
2. **Review Archive Structure**:
```
.workflow/archives/WFS-auth-system/
├── workflow-session.json
├── IMPL_PLAN.md
├── TODO_LIST.md
├── .task/
├── .summaries/
└── .review/ # Review results preserved
├── review-metadata.json
├── REVIEW-SUMMARY.md
└── dashboard.html
```
3. **Access Archived Reviews**:
```bash
# Open archived dashboard
start .workflow/archives/WFS-auth-system/.review/dashboard.html
```
## Benefits
### 1. Unified Structure
- Same directory layout for all review types
- Consistent file naming and schemas
- Easier maintenance and tooling
### 2. Session Integration
- Review history tracked with implementation
- Easy correlation between code changes and reviews
- Simplified archiving and retrieval
### 3. Progressive Creation
- Directories created only when needed
- No upfront overhead
- Clean session initialization
### 4. Type Flexibility
- Module-based and session-based reviews in same structure
- Type indicated by metadata, not directory layout
- Easy to add new review types
### 5. Dashboard Consistency
- Same dashboard template for both types
- Unified progress tracking
- Consistent user experience
## Migration Path
### For Existing Commands
**review-session-cycle**:
1. Change output from `.workflow/.reviews/session-{id}/` to `.workflow/active/{session-id}/.review/`
2. Update Phase 1 to use session discovery
3. Add review-metadata.json creation
**review-module-cycle**:
1. Add session requirement (or auto-create)
2. Change output from `.workflow/.reviews/module-{hash}/` to `.workflow/active/{session-id}/.review/`
3. Update Phase 1 to use session discovery
4. Add review-metadata.json creation
### Backward Compatibility
**For existing standalone reviews** in `.workflow/.reviews/`:
- Keep for reference
- Document migration in README
- Provide migration script if needed
## Implementation Checklist
- [ ] Update workflow-architecture.md with .review/ structure
- [ ] Update review-session-cycle.md command specification
- [ ] Update review-module-cycle.md command specification
- [ ] Update review-cycle-dashboard.html template
- [ ] Create review-metadata.json schema validation
- [ ] Update /workflow:session:complete to preserve .review/
- [ ] Update documentation examples
- [ ] Test both review types with new structure
- [ ] Validate dashboard compatibility
- [ ] Document migration path for existing reviews

10
.claude/workflows/workflow-architecture.md
View File

@@ -718,6 +718,15 @@ All workflows use the same file structure definition regardless of complexity. *
│ ├── [.summaries/] # Task completion summaries (created when tasks complete)
│ │ ├── IMPL-*-summary.md # Main task summaries
│ │ └── IMPL-*.*-summary.md # Subtask summaries
│ ├── [.review/] # Code review results (created by review commands)
│ │ ├── review-metadata.json # Review configuration and scope
│ │ ├── review-state.json # Review state machine
│ │ ├── review-progress.json # Real-time progress tracking
│ │ ├── dimensions/ # Per-dimension analysis results
│ │ ├── iterations/ # Deep-dive iteration results
│ │ ├── reports/ # Human-readable reports and CLI outputs
│ │ ├── REVIEW-SUMMARY.md # Final consolidated summary
│ │ └── dashboard.html # Interactive review dashboard
│ ├── [design-*/] # UI design outputs (created by ui-design workflows)
│ │ ├── .intermediates/ # Intermediate analysis files
│ │ │ ├── style-analysis/ # Style analysis data
@@ -750,6 +759,7 @@ All workflows use the same file structure definition regardless of complexity. *
- **Dynamic Files**: Subtask JSON files created during task decomposition
- **Scratchpad Usage**: `.scratchpad/` created when CLI commands run without active session
- **Design Usage**: `design-{timestamp}/` created by UI design workflows in `.workflow/` directly for standalone design runs
- **Review Usage**: `.review/` created by review commands (`/workflow:review-module-cycle`, `/workflow:review-session-cycle`) for comprehensive code quality analysis
- **Intermediate Files**: `.intermediates/` contains analysis data (style/layout) separate from final deliverables
- **Layout Templates**: `layout-extraction/layout-templates.json` contains structural templates for UI assembly