mirror of
https://github.com/catlog22/Claude-Code-Workflow.git
synced 2026-02-11 02:33:51 +08:00
refactor: Simplify and streamline agent documentation and output schemas for clarity and consistency
This commit is contained in:
catlog22
@@ -224,55 +224,7 @@ if (result.passRate < 100%) {
|
||||
- TodoWrite completion: Mark all phases done
|
||||
- Output summary to user with dashboard link
|
||||
|
||||
### Planning Agent (@cli-planning-agent)
|
||||
|
||||
**Role**: Analyze findings, create execution strategy, initialize progress tracking
|
||||
|
||||
**Orchestrator Provides**:
|
||||
- Review findings data (id, title, severity, file, description, recommendations)
|
||||
- Project context (structure, test framework, git status)
|
||||
- Output directory and template paths
|
||||
|
||||
**Agent Outputs**:
|
||||
- fix-plan.json (groups, timeline, execution strategy)
|
||||
- fix-progress-{N}.json (one per group, initial state)
|
||||
|
||||
### Execution Agent (@cli-execute-agent)
|
||||
|
||||
**Role**: Execute fixes for assigned group, update progress in real-time
|
||||
|
||||
**Orchestrator Provides**:
|
||||
- Group assignment (from fix-plan.json)
|
||||
- Fix strategy and risk assessment (from fix-plan.json)
|
||||
- Progress file path (fix-progress-{N}.json)
|
||||
|
||||
**Agent Responsibilities**:
|
||||
- Read/update assigned progress file
|
||||
- Apply fixes with flow control tracking
|
||||
- Run tests and verify
|
||||
- Commit successful fixes to git
|
||||
|
||||
## Reference
|
||||
|
||||
### CLI Tool Configuration
|
||||
|
||||
**Planning Agent**:
|
||||
```javascript
|
||||
{
|
||||
subagent_type: "cli-planning-agent",
|
||||
timeout: 300000, // 5 minutes for planning
|
||||
description: "Generate fix plan for N code review findings"
|
||||
}
|
||||
```
|
||||
|
||||
**Execution Agent**:
|
||||
```javascript
|
||||
{
|
||||
subagent_type: "cli-execute-agent",
|
||||
timeout: 3600000, // 60 minutes per group (adjustable)
|
||||
description: "Fix M issues: {group_name}"
|
||||
}
|
||||
```
|
||||
|
||||
### Output File Structure
|
||||
|
||||
|
||||
@@ -263,73 +263,7 @@ echo "📊 Dashboard: file://${absolutePath}/.review/dashboard.html"
|
||||
- TodoWrite completion: Mark all tasks done
|
||||
- Output: Dashboard path and REVIEW-SUMMARY.md path to user
|
||||
|
||||
### 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|...",
|
||||
review_type: "module",
|
||||
target_files: ["src/auth/service.ts", "src/auth/validator.ts", ...],
|
||||
output_paths: {
|
||||
json: "{output-dir}/dimensions/{dimension}.json",
|
||||
report: "{output-dir}/reports/{dimension}-analysis.md",
|
||||
cli_output: "{output-dir}/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: "{output-dir}/iterations/iteration-1-finding-{uuid}.json",
|
||||
report: "{output-dir}/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
|
||||
|
||||
## 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
|
||||
|
||||
### Output File Structure
|
||||
|
||||
@@ -494,15 +428,17 @@ Task(
|
||||
|
||||
## 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)
|
||||
- Context Pattern: ${targetFiles.map(f => `@${f}`).join(' ')}
|
||||
|
||||
## Expected Deliverables
|
||||
**MANDATORY**: Before generating any JSON output, read the template example first:
|
||||
- Read: ~/.claude/workflows/cli-templates/schemas/review-dimension-results-schema.json
|
||||
- Follow the exact structure and field naming from the example
|
||||
|
||||
1. Dimension Results JSON: ${outputDir}/dimensions/${dimension}.json
|
||||
- MUST follow schema: ~/.claude/workflows/cli-templates/schemas/review-dimension-results-schema.json
|
||||
- MUST follow example template: ~/.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
|
||||
@@ -568,12 +504,15 @@ Task(
|
||||
## 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
|
||||
**MANDATORY**: Before generating any JSON output, read the template example first:
|
||||
- Read: ~/.claude/workflows/cli-templates/schemas/review-deep-dive-results-schema.json
|
||||
- Follow the exact structure and field naming from the example
|
||||
|
||||
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 follow example template: ~/.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
|
||||
|
||||
@@ -249,84 +249,7 @@ echo "📊 Dashboard: file://${absolutePath}/.review/dashboard.html"
|
||||
- TodoWrite completion: Mark all tasks done
|
||||
- Output: Dashboard path and REVIEW-SUMMARY.md path to user
|
||||
|
||||
### 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
|
||||
|
||||
|
||||
### 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
|
||||
|
||||
@@ -520,8 +443,12 @@ Task(
|
||||
- Mode: analysis (READ-ONLY)
|
||||
|
||||
## Expected Deliverables
|
||||
**MANDATORY**: Before generating any JSON output, read the template example first:
|
||||
- Read: ~/.claude/workflows/cli-templates/schemas/review-dimension-results-schema.json
|
||||
- Follow the exact structure and field naming from the example
|
||||
|
||||
1. Dimension Results JSON: ${outputDir}/dimensions/${dimension}.json
|
||||
- MUST follow schema: ~/.claude/workflows/cli-templates/schemas/review-dimension-results-schema.json
|
||||
- MUST follow example template: ~/.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
|
||||
@@ -591,8 +518,12 @@ Task(
|
||||
- Mode: analysis (READ-ONLY)
|
||||
|
||||
## Expected Deliverables
|
||||
**MANDATORY**: Before generating any JSON output, read the template example first:
|
||||
- Read: ~/.claude/workflows/cli-templates/schemas/review-deep-dive-results-schema.json
|
||||
- Follow the exact structure and field naming from the example
|
||||
|
||||
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 follow example template: ~/.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
|
||||
|
||||
Reference in New Issue
Block a user