diff --git a/.claude/agents/cli-lite-planning-agent.md b/.claude/agents/cli-lite-planning-agent.md index 20b8e870..b843cc19 100644 --- a/.claude/agents/cli-lite-planning-agent.md +++ b/.claude/agents/cli-lite-planning-agent.md @@ -1,13 +1,14 @@ --- name: cli-lite-planning-agent description: | - Generic planning agent for lite-plan and lite-fix workflows. Generates structured plan JSON based on provided schema reference. + Generic planning agent for lite-plan, collaborative-plan, and lite-fix workflows. Generates structured plan JSON based on provided schema reference. Core capabilities: - Schema-driven output (plan-json-schema or fix-plan-json-schema) - Task decomposition with dependency analysis - CLI execution ID assignment for fork/merge strategies - Multi-angle context integration (explorations or diagnoses) + - Process documentation (planning-context.md) for collaborative workflows color: cyan --- @@ -15,6 +16,40 @@ You are a generic planning agent that generates structured plan JSON for lite wo **CRITICAL**: After generating plan.json, you MUST execute internal **Plan Quality Check** (Phase 5) using CLI analysis to validate and auto-fix plan quality before returning to orchestrator. Quality dimensions: completeness, granularity, dependencies, acceptance criteria, implementation steps, constraint compliance. +## Output Artifacts + +The agent produces different artifacts based on workflow context: + +### Standard Output (lite-plan, lite-fix) + +| Artifact | Description | +|----------|-------------| +| `plan.json` | Structured plan following plan-json-schema.json | + +### Extended Output (collaborative-plan sub-agents) + +When invoked with `process_docs: true` in input context: + +| Artifact | Description | +|----------|-------------| +| `planning-context.md` | Evidence paths + synthesized understanding (insights, decisions, approach) | +| `sub-plan.json` | Sub-plan following plan-json-schema.json with source_agent metadata | + +**planning-context.md format**: +```markdown +# Planning Context: {focus_area} + +## Source Evidence +- `exploration-{angle}.json` - {key finding} +- `{file}:{line}` - {what this proves} + +## Understanding +- Current state: {analysis} +- Proposed approach: {strategy} + +## Key Decisions +- Decision: {what} | Rationale: {why} | Evidence: {file ref} +``` ## Input Context @@ -34,10 +69,39 @@ You are a generic planning agent that generates structured plan JSON for lite wo clarificationContext: { [question]: answer } | null, complexity: "Low" | "Medium" | "High", // For lite-plan severity: "Low" | "Medium" | "High" | "Critical", // For lite-fix - cli_config: { tool, template, timeout, fallback } + cli_config: { tool, template, timeout, fallback }, + + // Process documentation (collaborative-plan) + process_docs: boolean, // If true, generate planning-context.md + focus_area: string, // Sub-requirement focus area (collaborative-plan) + output_folder: string // Where to write process docs (collaborative-plan) } ``` +## Process Documentation (collaborative-plan) + +When `process_docs: true`, generate planning-context.md before sub-plan.json: + +```markdown +# Planning Context: {focus_area} + +## Source Evidence +- `exploration-{angle}.json` - {key finding from exploration} +- `{file}:{line}` - {code evidence for decision} + +## Understanding +- **Current State**: {what exists now} +- **Problem**: {what needs to change} +- **Approach**: {proposed solution strategy} + +## Key Decisions +- Decision: {what} | Rationale: {why} | Evidence: {file:line or exploration ref} + +## Dependencies +- Depends on: {other sub-requirements or none} +- Provides for: {what this enables} +``` + ## Schema-Driven Output **CRITICAL**: Read the schema reference first to determine output structure: diff --git a/.claude/commands/workflow/collaborative-plan.md b/.claude/commands/workflow/collaborative-plan.md index 0035c288..eb37b560 100644 --- a/.claude/commands/workflow/collaborative-plan.md +++ b/.claude/commands/workflow/collaborative-plan.md @@ -29,13 +29,33 @@ When `--yes` or `-y`: Auto-approve splits, use default merge rule, skip confirma **CLI Tools**: cli-lite-planning-agent (internally calls ccw cli with gemini/codex/qwen) **Schema**: plan-json-schema.json (sub-plans & final plan share same base schema) +## Output Artifacts + +### Per Sub-Agent (Phase 2) + +| Artifact | Description | +|----------|-------------| +| `planning-context.md` | Evidence paths + synthesized understanding | +| `sub-plan.json` | Sub-plan following plan-json-schema.json | + +### Final Output (Phase 4) + +| Artifact | Description | +|----------|-------------| +| `requirement-analysis.json` | Requirement breakdown and sub-agent assignments | +| `conflicts.json` | Detected conflicts between sub-plans | +| `plan.json` | Merged plan (plan-json-schema + merge_metadata) | +| `plan.md` | Human-readable plan summary | + +**Agent**: `cli-lite-planning-agent` with `process_docs: true` for sub-agents + ## Overview Unified collaborative planning workflow that: 1. **Analyzes** complex requirements and splits into sub-requirements 2. **Spawns** parallel sub-agents, each responsible for one sub-requirement -3. **Each agent** maintains process files: exploration.md → understanding.md → sub-plan.json +3. **Each agent** maintains process files: planning-refs.md + sub-plan.json 4. **Merges** all sub-plans into unified plan.json with conflict resolution ``` @@ -51,10 +71,9 @@ Unified collaborative planning workflow that: │ Phase 2: Parallel Sub-Agent Execution │ │ ┌──────────────┬──────────────┬──────────────┐ │ │ │ Agent 1 │ Agent 2 │ Agent N │ │ -│ ├──────────────┼──────────────┼──────────────┤ │ -│ │ exploration │ exploration │ exploration │ → exploration.md │ -│ │ understanding│ understanding│ understanding│ → understanding.md │ -│ │ planning │ planning │ planning │ → sub-plan.json │ +├──────────────┼──────────────┼──────────────┤ │ +│ │ planning │ planning │ planning │ → planning-context.md│ +│ │ + sub-plan │ + sub-plan │ + sub-plan │ → sub-plan.json │ │ └──────────────┴──────────────┴──────────────┘ │ │ │ │ Phase 3: Cross-Verification & Conflict Detection │ @@ -77,9 +96,8 @@ Unified collaborative planning workflow that: ├── requirement-analysis.json # Phase 1: Requirement breakdown ├── agents/ # Phase 2: Per-agent process files │ ├── {focus-area-1}/ -│ │ ├── exploration.md # What was discovered -│ │ ├── understanding.md # Synthesized insights -│ │ └── sub-plan.json # Agent's plan for this focus area +│ │ ├── planning-context.md # Evidence + understanding +│ │ └── sub-plan.json # Agent's plan for this focus area │ ├── {focus-area-2}/ │ │ └── ... │ └── {focus-area-N}/ @@ -243,129 +261,38 @@ const agentPromises = subRequirements.map((sub, index) => { run_in_background: false, description: `Plan: ${sub.focus_area}`, prompt: ` -## Sub-Agent Mission +## Sub-Agent Context -You are responsible for planning ONE sub-requirement of a larger task. -Maintain 3 process files documenting your exploration, understanding, and plan. +You are planning ONE sub-requirement. Generate process docs + sub-plan. -## Your Focus Area - -**Index**: ${index + 1} **Focus Area**: ${sub.focus_area} **Description**: ${sub.description} **Key Concerns**: ${sub.key_concerns.join(', ')} -**Suggested Tool**: ${sub.suggested_cli_tool} +**CLI Tool**: ${sub.suggested_cli_tool} **Depth**: ${depth} -## Parent Context +## Input Context -**Original Requirement**: ${taskDescription} -**Session**: ${sessionId} -**Your Folder**: ${sessionFolder}/agents/${sub.focus_area}/ - -## Schema Reference - -Execute: cat ~/.claude/workflows/cli-templates/schemas/plan-json-schema.json - -## Execution Process (3 Stages) - -### Stage 1: Exploration (→ exploration.md) - -Use ccw cli to explore the codebase for your focus area: - -\`\`\`bash -ccw cli -p " -PURPOSE: Explore codebase for ${sub.focus_area} -Success: Identify all relevant files, patterns, and constraints - -TASK: -• Find existing code related to ${sub.focus_area} -• Identify current architecture and patterns -• Discover integration points and dependencies -• Note any constraints or limitations - -CONTEXT: @**/* -MODE: analysis -" --tool ${sub.suggested_cli_tool} --mode analysis +\`\`\`json +{ + "task_description": "${sub.description}", + "schema_path": "~/.claude/workflows/cli-templates/schemas/plan-json-schema.json", + "session": { "id": "${sessionId}", "folder": "${sessionFolder}" }, + "process_docs": true, + "focus_area": "${sub.focus_area}", + "output_folder": "${sessionFolder}/agents/${sub.focus_area}", + "cli_config": { "tool": "${sub.suggested_cli_tool}" }, + "parent_requirement": "${taskDescription}" +} \`\`\` -After CLI completes, write exploration.md: - -\`\`\`markdown -# Exploration: ${sub.focus_area} - -## Discovered Files -- [list relevant files with brief descriptions] - -## Current Architecture -- [describe existing structure] - -## Integration Points -- [list dependencies and interfaces] - -## Constraints & Limitations -- [note any blockers or constraints] - -## Key Findings -- [most important discoveries] -\`\`\` - -### Stage 2: Understanding (→ understanding.md) - -Synthesize exploration findings into actionable understanding: - -\`\`\`markdown -# Understanding: ${sub.focus_area} - -## Problem Statement -[Restate what needs to be done for this focus area] - -## Current State Analysis -[What exists now, what's missing] - -## Proposed Approach -[High-level strategy for implementation] - -## Technical Decisions -- Decision 1: [choice] because [rationale] -- Decision 2: [choice] because [rationale] - -## Risks & Mitigations -- Risk 1: [description] → Mitigation: [approach] - -## Dependencies on Other Sub-Requirements -- Depends on: [list any dependencies on other focus areas] -- Provides for: [what this provides to other focus areas] - -## Key Insights -[Most important understanding gained] -\`\`\` - -### Stage 3: Planning (→ sub-plan.json) - -Generate sub-plan.json following plan-json-schema.json: -- 2-5 tasks for this focus area -- Clear modification_points with file, target, change -- Verification criteria (unit_tests, integration_tests, manual_checks) -- Risk assessment per task -- Dependencies (internal to this sub-plan) -- Add source_agent: "${sub.focus_area}" to _metadata - ## Output Requirements -Write exactly 3 files: -1. \`${sessionFolder}/agents/${sub.focus_area}/exploration.md\` -2. \`${sessionFolder}/agents/${sub.focus_area}/understanding.md\` -3. \`${sessionFolder}/agents/${sub.focus_area}/sub-plan.json\` +Write 2 files to \`${sessionFolder}/agents/${sub.focus_area}/\`: +1. **planning-context.md** - Evidence paths + synthesized understanding +2. **sub-plan.json** - Plan with \`_metadata.source_agent: "${sub.focus_area}"\` -## Success Criteria - -- [ ] Exploration covers all relevant code areas -- [ ] Understanding synthesizes findings into clear approach -- [ ] sub-plan.json follows plan-json-schema.json with 2-5 tasks -- [ ] Each task has modification_points, acceptance, verification -- [ ] Dependencies clearly stated -- [ ] All 3 files written to correct location +See cli-lite-planning-agent documentation for file formats. ` }) }) @@ -515,9 +442,9 @@ TodoWrite({ todos: [ { content: "Phase 4: Merge & Synthesis", status: "in_progress", activeForm: "Merging plans" } ]}) -// Collect all understanding documents for context -const understandingDocs = subRequirements.map(sub => { - const path = `${sessionFolder}/agents/${sub.focus_area}/understanding.md` +// Collect all planning context documents for context +const contextDocs = subRequirements.map(sub => { + const path = `${sessionFolder}/agents/${sub.focus_area}/planning-context.md` return { focus_area: sub.focus_area, content: Read(path) @@ -559,11 +486,11 @@ ${JSON.stringify(sp.plan, null, 2)} \`\`\` `).join('\n')} -## Understanding Documents +## Planning Context Documents -${understandingDocs.map(ud => ` -### Understanding: ${ud.focus_area} -${ud.content} +${contextDocs.map(cd => ` +### Context: ${cd.focus_area} +${cd.content} `).join('\n')} ## Detected Conflicts @@ -740,8 +667,7 @@ ${task.acceptance?.map(ac => `- ${ac}`).join('\n') || 'N/A'} ${subRequirements.map(sub => ` ### ${sub.focus_area} -- Exploration: \`${sessionFolder}/agents/${sub.focus_area}/exploration.md\` -- Understanding: \`${sessionFolder}/agents/${sub.focus_area}/understanding.md\` +- Context: \`${sessionFolder}/agents/${sub.focus_area}/planning-context.md\` - Sub-Plan: \`${sessionFolder}/agents/${sub.focus_area}/sub-plan.json\` `).join('\n')} @@ -776,8 +702,7 @@ console.log(` ├── requirement-analysis.json # Requirement breakdown ├── agents/ # Per-agent process files ${subRequirements.map(sub => `│ ├── ${sub.focus_area}/ -│ │ ├── exploration.md -│ │ ├── understanding.md +│ │ ├── planning-context.md │ │ └── sub-plan.json`).join('\n')} ├── conflicts.json # Detected conflicts ├── plan.json # Unified plan (execution-ready) @@ -792,7 +717,7 @@ Execute the plan: Review a specific agent's work: \`\`\`bash -cat ${sessionFolder}/agents/{focus-area}/understanding.md +cat ${sessionFolder}/agents/{focus-area}/planning-context.md \`\`\` `) ``` @@ -827,7 +752,7 @@ cat ${sessionFolder}/agents/{focus-area}/understanding.md ## Best Practices 1. **Be Specific**: Detailed requirements lead to better splits -2. **Review Process Files**: Check exploration.md and understanding.md for insights +2. **Review Process Files**: Check planning-context.md for insights 3. **Trust the Merge**: Conflict resolution follows defined rules 4. **Iterate if Needed**: Re-run with different --merge-rule if results unsatisfactory diff --git a/.claude/commands/workflow/lite-fix.md b/.claude/commands/workflow/lite-fix.md index c95ebf92..edbf68e0 100644 --- a/.claude/commands/workflow/lite-fix.md +++ b/.claude/commands/workflow/lite-fix.md @@ -37,6 +37,23 @@ Intelligent lightweight bug fixing command with dynamic workflow adaptation base /workflow:lite-fix -y --hotfix "生产环境数据库连接失败" # Auto + hotfix mode ``` +## Output Artifacts + +| Artifact | Description | +|----------|-------------| +| `diagnosis-{angle}.json` | Per-angle diagnosis results (1-4 files based on severity) | +| `diagnoses-manifest.json` | Index of all diagnosis files | +| `planning-context.md` | Evidence paths + synthesized understanding | +| `fix-plan.json` | Structured fix plan (fix-plan-json-schema.json) | + +**Output Directory**: `.workflow/.lite-fix/{bug-slug}-{YYYY-MM-DD}/` + +**Agent Usage**: +- Low/Medium severity → Direct Claude planning (no agent) +- High/Critical severity → `cli-lite-planning-agent` generates `fix-plan.json` + +**Schema Reference**: `~/.claude/workflows/cli-templates/schemas/fix-plan-json-schema.json` + ## Auto Mode Defaults When `--yes` or `-y` flag is used: @@ -192,11 +209,15 @@ const diagnosisTasks = selectedAngles.map((angle, index) => ## Task Objective Execute **${angle}** diagnosis for bug root cause analysis. Analyze codebase from this specific angle to discover root cause, affected paths, and fix hints. +## Output Location + +**Session Folder**: ${sessionFolder} +**Output File**: ${sessionFolder}/diagnosis-${angle}.json + ## Assigned Context - **Diagnosis Angle**: ${angle} - **Bug Description**: ${bug_description} - **Diagnosis Index**: ${index + 1} of ${selectedAngles.length} -- **Output File**: ${sessionFolder}/diagnosis-${angle}.json ## MANDATORY FIRST STEPS (Execute by Agent) **You (cli-explore-agent) MUST execute these steps in order:** @@ -225,8 +246,6 @@ Execute **${angle}** diagnosis for bug root cause analysis. Analyze codebase fro ## Expected Output -**File**: ${sessionFolder}/diagnosis-${angle}.json - **Schema Reference**: Schema obtained in MANDATORY FIRST STEPS step 3, follow schema exactly **Required Fields** (all ${angle} focused): @@ -255,9 +274,9 @@ Execute **${angle}** diagnosis for bug root cause analysis. Analyze codebase fro - [ ] JSON output follows schema exactly - [ ] clarification_needs includes options + recommended -## Output -Write: ${sessionFolder}/diagnosis-${angle}.json -Return: 2-3 sentence summary of ${angle} diagnosis findings +## Execution +**Write**: \`${sessionFolder}/diagnosis-${angle}.json\` +**Return**: 2-3 sentence summary of ${angle} diagnosis findings ` ) ) @@ -493,6 +512,13 @@ Task( prompt=` Generate fix plan and write fix-plan.json. +## Output Location + +**Session Folder**: ${sessionFolder} +**Output Files**: +- ${sessionFolder}/planning-context.md (evidence + understanding) +- ${sessionFolder}/fix-plan.json (fix plan) + ## Output Schema Reference Execute: cat ~/.claude/workflows/cli-templates/schemas/fix-plan-json-schema.json (get schema reference before generating plan) @@ -588,8 +614,9 @@ Generate fix-plan.json with: - For High/Critical: REQUIRED new fields (rationale, verification, risks, code_skeleton, data_flow, design_decisions) - Each task MUST have rationale (why this fix), verification (how to verify success), and risks (potential issues) 5. Parse output and structure fix-plan -6. Write JSON: Write('${sessionFolder}/fix-plan.json', jsonContent) -7. Return brief completion summary +6. **Write**: \`${sessionFolder}/planning-context.md\` (evidence paths + understanding) +7. **Write**: \`${sessionFolder}/fix-plan.json\` +8. Return brief completion summary ## Output Format for CLI Include these sections in your fix-plan output: @@ -747,22 +774,24 @@ SlashCommand(command="/workflow:lite-execute --in-memory --mode bugfix") ``` .workflow/.lite-fix/{bug-slug}-{YYYY-MM-DD}/ -|- diagnosis-{angle1}.json # Diagnosis angle 1 -|- diagnosis-{angle2}.json # Diagnosis angle 2 -|- diagnosis-{angle3}.json # Diagnosis angle 3 (if applicable) -|- diagnosis-{angle4}.json # Diagnosis angle 4 (if applicable) -|- diagnoses-manifest.json # Diagnosis index -+- fix-plan.json # Fix plan +├── diagnosis-{angle1}.json # Diagnosis angle 1 +├── diagnosis-{angle2}.json # Diagnosis angle 2 +├── diagnosis-{angle3}.json # Diagnosis angle 3 (if applicable) +├── diagnosis-{angle4}.json # Diagnosis angle 4 (if applicable) +├── diagnoses-manifest.json # Diagnosis index +├── planning-context.md # Evidence + understanding +└── fix-plan.json # Fix plan ``` **Example**: ``` -.workflow/.lite-fix/user-avatar-upload-fails-413-2025-11-25-14-30-25/ -|- diagnosis-error-handling.json -|- diagnosis-dataflow.json -|- diagnosis-validation.json -|- diagnoses-manifest.json -+- fix-plan.json +.workflow/.lite-fix/user-avatar-upload-fails-413-2025-11-25/ +├── diagnosis-error-handling.json +├── diagnosis-dataflow.json +├── diagnosis-validation.json +├── diagnoses-manifest.json +├── planning-context.md +└── fix-plan.json ``` ## Error Handling diff --git a/.claude/commands/workflow/lite-plan.md b/.claude/commands/workflow/lite-plan.md index 9088596f..183da066 100644 --- a/.claude/commands/workflow/lite-plan.md +++ b/.claude/commands/workflow/lite-plan.md @@ -37,6 +37,23 @@ Intelligent lightweight planning command with dynamic workflow adaptation based /workflow:lite-plan -y -e "优化数据库查询性能" # Auto mode + force exploration ``` +## Output Artifacts + +| Artifact | Description | +|----------|-------------| +| `exploration-{angle}.json` | Per-angle exploration results (1-4 files based on complexity) | +| `explorations-manifest.json` | Index of all exploration files | +| `planning-context.md` | Evidence paths + synthesized understanding | +| `plan.json` | Structured implementation plan (plan-json-schema.json) | + +**Output Directory**: `.workflow/.lite-plan/{task-slug}-{YYYY-MM-DD}/` + +**Agent Usage**: +- Low complexity → Direct Claude planning (no agent) +- Medium/High complexity → `cli-lite-planning-agent` generates `plan.json` + +**Schema Reference**: `~/.claude/workflows/cli-templates/schemas/plan-json-schema.json` + ## Auto Mode Defaults When `--yes` or `-y` flag is used: @@ -193,11 +210,15 @@ const explorationTasks = selectedAngles.map((angle, index) => ## Task Objective Execute **${angle}** exploration for task planning context. Analyze codebase from this specific angle to discover relevant structure, patterns, and constraints. +## Output Location + +**Session Folder**: ${sessionFolder} +**Output File**: ${sessionFolder}/exploration-${angle}.json + ## Assigned Context - **Exploration Angle**: ${angle} - **Task Description**: ${task_description} - **Exploration Index**: ${index + 1} of ${selectedAngles.length} -- **Output File**: ${sessionFolder}/exploration-${angle}.json ## MANDATORY FIRST STEPS (Execute by Agent) **You (cli-explore-agent) MUST execute these steps in order:** @@ -225,8 +246,6 @@ Execute **${angle}** exploration for task planning context. Analyze codebase fro ## Expected Output -**File**: ${sessionFolder}/exploration-${angle}.json - **Schema Reference**: Schema obtained in MANDATORY FIRST STEPS step 3, follow schema exactly **Required Fields** (all ${angle} focused): @@ -252,9 +271,9 @@ Execute **${angle}** exploration for task planning context. Analyze codebase fro - [ ] JSON output follows schema exactly - [ ] clarification_needs includes options + recommended -## Output -Write: ${sessionFolder}/exploration-${angle}.json -Return: 2-3 sentence summary of ${angle} findings +## Execution +**Write**: \`${sessionFolder}/exploration-${angle}.json\` +**Return**: 2-3 sentence summary of ${angle} findings ` ) ) @@ -443,6 +462,13 @@ Task( prompt=` Generate implementation plan and write plan.json. +## Output Location + +**Session Folder**: ${sessionFolder} +**Output Files**: +- ${sessionFolder}/planning-context.md (evidence + understanding) +- ${sessionFolder}/plan.json (implementation plan) + ## Output Schema Reference Execute: cat ~/.claude/workflows/cli-templates/schemas/plan-json-schema.json (get schema reference before generating plan) @@ -492,8 +518,9 @@ Generate plan.json following the schema obtained above. Key constraints: 2. Execute CLI planning using Gemini (Qwen fallback) 3. Read ALL exploration files for comprehensive context 4. Synthesize findings and generate plan following schema -5. Write JSON: Write('${sessionFolder}/plan.json', jsonContent) -6. Return brief completion summary +5. **Write**: \`${sessionFolder}/planning-context.md\` (evidence paths + understanding) +6. **Write**: \`${sessionFolder}/plan.json\` +7. Return brief completion summary ` ) ```