Compare commits

..

1 Commits

Author SHA1 Message Date
catlog22
f063fb0cde feat: enhance workflow planning with concept clarification and agent delegation
🎯 Major Enhancements:

1. Concept Clarification Quality Gate (concept-clarify.md)
   - Added dual-mode support: brainstorm & plan modes
   - Auto-detects mode based on artifact presence (ANALYSIS_RESULTS.md vs synthesis-specification.md)
   - Backward compatible with existing brainstorm workflow
   - Updates appropriate artifacts based on detected mode

2. Planning Workflow Enhancement (plan.md)
   - Added Phase 3.5: Concept Clarification as quality gate
   - Integrated Phase 3.5 between analysis and task generation
   - Enhanced with interactive Q&A to resolve ambiguities
   - Updated from 4-phase to 5-phase workflow model
   - Delegated Phase 3 (Intelligent Analysis) to cli-execution-agent
   - Autonomous context discovery and enhanced prompt generation

3. Documentation Updates (README.md, README_CN.md)
   - Added /workflow:test-cycle-execute command documentation
   - Explained dynamic task generation and iterative fix cycles
   - Included usage examples and key features
   - Updated both English and Chinese versions

🔧 Technical Details:
- concept-clarify now supports both ANALYSIS_RESULTS.md (plan) and synthesis-specification.md (brainstorm)
- plan.md Phase 3 now uses cli-execution-agent for MCP-powered context discovery
- Maintains auto-continue mechanism with one interactive quality gate (Phase 3.5)
- All changes preserve backward compatibility

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude <noreply@anthropic.com>
2025-10-18 12:22:18 +08:00
5 changed files with 189 additions and 64 deletions

View File

@@ -15,9 +15,13 @@ You **MUST** consider the user input before proceeding (if not empty).
## Outline
**Goal**: Detect and reduce ambiguity or missing decision points in brainstorming artifacts (synthesis-specification.md, topic-framework.md, role analyses) before moving to action planning phase.
**Goal**: Detect and reduce ambiguity or missing decision points in planning artifacts before moving to task generation. Supports both brainstorm and plan workflows.
**Timing**: This command runs AFTER `/workflow:brainstorm:synthesis` and BEFORE `/workflow:plan`. It serves as a quality gate to ensure conceptual clarity before detailed task planning.
**Timing**:
- **Brainstorm mode**: Runs AFTER `/workflow:brainstorm:synthesis` and BEFORE `/workflow:plan`
- **Plan mode**: Runs AFTER Phase 3 (concept-enhanced) and BEFORE Phase 4 (task-generate) within `/workflow:plan`
This serves as a quality gate to ensure conceptual clarity before detailed task planning or generation.
**Execution steps**:
@@ -34,28 +38,40 @@ You **MUST** consider the user input before proceeding (if not empty).
ERROR: "No active workflow session found. Use --session <session-id> or start a session."
EXIT
# Validate brainstorming completion
# Mode detection: plan vs brainstorm
brainstorm_dir = .workflow/WFS-{session}/.brainstorming/
process_dir = .workflow/WFS-{session}/.process/
CHECK: brainstorm_dir/synthesis-specification.md
IF NOT EXISTS:
ERROR: "synthesis-specification.md not found. Run /workflow:brainstorm:synthesis first"
IF EXISTS(process_dir/ANALYSIS_RESULTS.md):
clarify_mode = "plan"
primary_artifact = process_dir/ANALYSIS_RESULTS.md
INFO: "Plan mode: Analyzing ANALYSIS_RESULTS.md"
ELSE IF EXISTS(brainstorm_dir/synthesis-specification.md):
clarify_mode = "brainstorm"
primary_artifact = brainstorm_dir/synthesis-specification.md
INFO: "Brainstorm mode: Analyzing synthesis-specification.md"
ELSE:
ERROR: "No valid artifact found. Run /workflow:brainstorm:synthesis or /workflow:plan first"
EXIT
CHECK: brainstorm_dir/topic-framework.md
IF NOT EXISTS:
WARN: "topic-framework.md not found. Verification will be limited."
# Mode-specific validation
IF clarify_mode == "brainstorm":
CHECK: brainstorm_dir/topic-framework.md
IF NOT EXISTS:
WARN: "topic-framework.md not found. Verification will be limited."
```
2. **Load Brainstorming Artifacts**
2. **Load Artifacts (Mode-Aware)**
```bash
# Load primary artifacts
synthesis_spec = Read(brainstorm_dir + "/synthesis-specification.md")
topic_framework = Read(brainstorm_dir + "/topic-framework.md") # if exists
# Load primary artifact (determined in step 1)
primary_content = Read(primary_artifact)
# Discover role analyses
role_analyses = Glob(brainstorm_dir + "/*/analysis.md")
participating_roles = extract_role_names(role_analyses)
# Load mode-specific supplementary artifacts
IF clarify_mode == "brainstorm":
topic_framework = Read(brainstorm_dir + "/topic-framework.md") # if exists
role_analyses = Glob(brainstorm_dir + "/*/analysis.md")
participating_roles = extract_role_names(role_analyses)
# Plan mode: primary_content (ANALYSIS_RESULTS.md) is self-contained
```
3. **Ambiguity & Coverage Scan**
@@ -182,8 +198,8 @@ You **MUST** consider the user input before proceeding (if not empty).
```bash
# Ensure Clarifications section exists
IF synthesis_spec NOT contains "## Clarifications":
Insert "## Clarifications" section after "# [Topic]" heading
IF primary_content NOT contains "## Clarifications":
Insert "## Clarifications" section after first heading
# Create session subsection
IF NOT contains "### Session YYYY-MM-DD":
@@ -194,20 +210,20 @@ You **MUST** consider the user input before proceeding (if not empty).
# Apply clarification to appropriate section
CASE category:
Functional Requirements → Update "## Requirements & Acceptance Criteria"
Architecture → Update "## Key Designs & Decisions" or "## Design Specifications"
User Experience → Update "## Design Specifications > UI/UX Guidelines"
Risk → Update "## Risk Assessment & Mitigation"
Process → Update "## Process & Collaboration Concerns"
Data Model → Update "## Key Designs & Decisions > Data Model Overview"
Non-Functional → Update "## Requirements & Acceptance Criteria > Non-Functional Requirements"
Functional Requirements → Update "## Requirements" or equivalent section
Architecture → Update "## Architecture" or "## Design" sections
User Experience → Update "## UI/UX" or "## User Experience" sections
Risk → Update "## Risks" or "## Risk Assessment" sections
Process → Update "## Process" or "## Implementation" sections
Data Model → Update "## Data Model" or "## Database" sections
Non-Functional → Update "## Non-Functional Requirements" or equivalent
# Remove obsolete/contradictory statements
IF clarification invalidates existing statement:
Replace statement instead of duplicating
# Save immediately
Write(synthesis_specification.md)
# Save immediately to primary_artifact
Write(primary_artifact)
```
7. **Validation After Each Write**
@@ -227,8 +243,9 @@ You **MUST** consider the user input before proceeding (if not empty).
## ✅ Concept Verification Complete
**Session**: WFS-{session-id}
**Mode**: {clarify_mode}
**Questions Asked**: {count}/5
**Artifacts Updated**: synthesis-specification.md
**Artifacts Updated**: {primary_artifact filename}
**Sections Touched**: {list section names}
### Coverage Summary
@@ -261,18 +278,26 @@ You **MUST** consider the user input before proceeding (if not empty).
9. **Update Session Metadata**
```json
```bash
# Update metadata based on mode
IF clarify_mode == "brainstorm":
phase_key = "BRAINSTORM"
ELSE: # plan mode
phase_key = "PLAN"
# Update session metadata
{
"phases": {
"BRAINSTORM": {
"status": "completed",
"{phase_key}": {
"status": "concept_verified",
"concept_verification": {
"completed": true,
"completed_at": "timestamp",
"questions_asked": 3,
"categories_clarified": ["Requirements", "Risk", "Architecture"],
"mode": "{clarify_mode}",
"questions_asked": {count},
"categories_clarified": [{list}],
"outstanding_items": [],
"recommendation": "PROCEED_TO_PLANNING"
"recommendation": "PROCEED" # or "ADDRESS_OUTSTANDING"
}
}
}

View File

@@ -1,6 +1,6 @@
---
name: plan
description: Orchestrate 4-phase planning workflow by executing commands and passing context between phases
description: Orchestrate 5-phase planning workflow with quality gate, executing commands and passing context between phases
argument-hint: "[--agent] [--cli-execute] \"text description\"|file.md"
allowed-tools: SlashCommand(*), TodoWrite(*), Read(*), Bash(*)
---
@@ -9,22 +9,24 @@ allowed-tools: SlashCommand(*), TodoWrite(*), Read(*), Bash(*)
## Coordinator Role
**This command is a pure orchestrator**: Execute 4 slash commands in sequence, parse their outputs, pass context between them, and ensure complete execution through **automatic continuation**.
**This command is a pure orchestrator**: Execute 5 slash commands in sequence (including a quality gate), parse their outputs, pass context between them, and ensure complete execution through **automatic continuation**.
**Execution Model - Auto-Continue Workflow**:
**Execution Model - Auto-Continue Workflow with Quality Gate**:
This workflow runs **fully autonomously** once triggered. Each phase completes, reports its output to you, then **immediately and automatically** proceeds to the next phase without requiring any user intervention.
This workflow runs **mostly autonomously** once triggered, with one interactive quality gate (Phase 3.5). Phases 3 and 4 are delegated to specialized agents for complex analysis and task generation.
1. **User triggers**: `/workflow:plan "task"`
2. **Phase 1 executes**Reports output to user → Auto-continues
3. **Phase 2 executes**Reports output to user → Auto-continues
4. **Phase 3 executes** → Reports output to user → Auto-continues
5. **Phase 4 executes**Reports final summary
2. **Phase 1 executes**Session discovery → Auto-continues
3. **Phase 2 executes**Context gathering → Auto-continues
4. **Phase 3 executes** (cli-execution-agent) → Intelligent analysis → Auto-continues
5. **Phase 3.5 executes****Pauses for user Q&A** → User answers clarification questions → Auto-continues
6. **Phase 4 executes** (task-generate-agent if --agent) → Task generation → Reports final summary
**Auto-Continue Mechanism**:
- TodoList tracks current phase status
- After each phase completion, automatically executes next pending phase
- **No user action required** - workflow runs end-to-end autonomously
- **Phase 3.5 requires user interaction** - answers clarification questions (up to 5)
- If no ambiguities found, Phase 3.5 auto-skips and continues to Phase 4
- Progress updates shown at each phase for visibility
**Execution Modes**:
@@ -36,11 +38,12 @@ This workflow runs **fully autonomously** once triggered. Each phase completes,
1. **Start Immediately**: First action is TodoWrite initialization, second action is Phase 1 command execution
2. **No Preliminary Analysis**: Do not read files, analyze structure, or gather context before Phase 1
3. **Parse Every Output**: Extract required data from each command's output for next phase
3. **Parse Every Output**: Extract required data from each command/agent output for next phase
4. **Auto-Continue via TodoList**: Check TodoList status to execute next pending phase automatically
5. **Track Progress**: Update TodoWrite after every phase completion
6. **Agent Delegation**: Phase 3 uses cli-execution-agent for autonomous intelligent analysis
## 4-Phase Execution
## 5-Phase Execution
### Phase 1: Session Discovery
**Command**: `SlashCommand(command="/workflow:session:start --auto \"[structured-task-description]\"")`
@@ -93,32 +96,92 @@ CONTEXT: Existing user database schema, REST API endpoints
---
### Phase 3: Intelligent Analysis
**Command**: `SlashCommand(command="/workflow:tools:concept-enhanced --session [sessionId] --context [contextPath]")`
### Phase 3: Intelligent Analysis (Agent-Delegated)
**Command**: `Task(subagent_type="cli-execution-agent", description="Intelligent Analysis", prompt="...")`
**Agent Task Prompt**:
```
Analyze project requirements and generate comprehensive solution blueprint for session [sessionId].
Context: Load context package from [contextPath]
Output: Generate ANALYSIS_RESULTS.md in .workflow/[sessionId]/.process/
Requirements:
- Review context-package.json and discover additional relevant files
- Analyze architecture patterns, data models, and dependencies
- Identify technical constraints and risks
- Generate comprehensive solution blueprint
- Include task breakdown recommendations
Session: [sessionId]
Mode: analysis (read-only during discovery, write for ANALYSIS_RESULTS.md)
```
**Input**: `sessionId` from Phase 1, `contextPath` from Phase 2
**Agent Execution**:
- Phase 1: Understands analysis intent, extracts keywords
- Phase 2: Discovers additional context via MCP code-index
- Phase 3: Enhances prompt with discovered patterns
- Phase 4: Executes with Gemini (analysis mode), generates ANALYSIS_RESULTS.md
- Phase 5: Routes output to session directory
**Parse Output**:
- Verify ANALYSIS_RESULTS.md created
- Agent returns execution log path
- Verify ANALYSIS_RESULTS.md created by agent
**Validation**:
- File `.workflow/[sessionId]/ANALYSIS_RESULTS.md` exists
- File `.workflow/[sessionId]/.process/ANALYSIS_RESULTS.md` exists
- Contains task recommendations section
- Agent execution log saved to `.workflow/[sessionId]/.chat/`
**TodoWrite**: Mark phase 3 completed, phase 4 in_progress
**TodoWrite**: Mark phase 3 completed, phase 3.5 in_progress
**After Phase 3**: Return to user showing Phase 3 results, then auto-continue to Phase 4
**After Phase 3**: Return to user showing Phase 3 results, then auto-continue to Phase 3.5
**Memory State Check**:
- Evaluate current context window usage and memory state
- If memory usage is high (>110K tokens or approaching context limits):
- **Command**: `SlashCommand(command="/compact")`
- This optimizes memory before proceeding to Phase 4
- This optimizes memory before proceeding to Phase 3.5
- Memory compaction is particularly important after analysis phase which may generate extensive documentation
- Ensures optimal performance and prevents context overflow
---
### Phase 3.5: Concept Clarification (Quality Gate)
**Command**: `SlashCommand(command="/workflow:concept-clarify --session [sessionId]")`
**Purpose**: Quality gate to verify and clarify analysis results before task generation
**Input**: `sessionId` from Phase 1
**Behavior**:
- Auto-detects plan mode (ANALYSIS_RESULTS.md exists)
- Interactively asks up to 5 targeted questions to resolve ambiguities
- Updates ANALYSIS_RESULTS.md with clarifications
- Pauses workflow for user input (breaks auto-continue temporarily)
**Parse Output**:
- Verify clarifications added to ANALYSIS_RESULTS.md
- Check recommendation: "PROCEED" or "ADDRESS_OUTSTANDING"
**Validation**:
- ANALYSIS_RESULTS.md updated with `## Clarifications` section
- All critical ambiguities resolved or documented as outstanding
**TodoWrite**: Mark phase 3.5 completed, phase 4 in_progress
**After Phase 3.5**: Return to user showing clarification summary, then auto-continue to Phase 4
**Skip Conditions**:
- If `/workflow:concept-clarify` reports "No critical ambiguities detected", automatically proceed to Phase 4
- User can skip by responding "skip" or "proceed" immediately
---
### Phase 4: Task Generation
**Relationship with Brainstorm Phase**:
@@ -176,6 +239,7 @@ TodoWrite({todos: [
{"content": "Execute session discovery", "status": "in_progress", "activeForm": "Executing session discovery"},
{"content": "Execute context gathering", "status": "pending", "activeForm": "Executing context gathering"},
{"content": "Execute intelligent analysis", "status": "pending", "activeForm": "Executing intelligent analysis"},
{"content": "Execute concept clarification", "status": "pending", "activeForm": "Executing concept clarification"},
{"content": "Execute task generation", "status": "pending", "activeForm": "Executing task generation"}
]})
@@ -184,10 +248,11 @@ TodoWrite({todos: [
{"content": "Execute session discovery", "status": "completed", "activeForm": "Executing session discovery"},
{"content": "Execute context gathering", "status": "in_progress", "activeForm": "Executing context gathering"},
{"content": "Execute intelligent analysis", "status": "pending", "activeForm": "Executing intelligent analysis"},
{"content": "Execute concept clarification", "status": "pending", "activeForm": "Executing concept clarification"},
{"content": "Execute task generation", "status": "pending", "activeForm": "Executing task generation"}
]})
// Continue pattern for Phase 2, 3, 4...
// Continue pattern for Phase 2, 3, 3.5, 4...
```
## Input Processing
@@ -238,12 +303,18 @@ Phase 2: context-gather --session sessionId "structured-description"
↓ Input: sessionId + session memory + structured description
↓ Output: contextPath (context-package.json)
Phase 3: concept-enhanced --session sessionId --context contextPath
↓ Input: sessionId + contextPath + session memory
Output: ANALYSIS_RESULTS.md
Phase 3: cli-execution-agent (Intelligent Analysis)
↓ Input: sessionId + contextPath + task description
Agent discovers context, enhances prompt, executes with Gemini
↓ Output: ANALYSIS_RESULTS.md + execution log
Phase 3.5: concept-clarify --session sessionId (Quality Gate)
↓ Input: sessionId + ANALYSIS_RESULTS.md (auto-detected)
↓ Interactive: User answers clarification questions
↓ Output: Updated ANALYSIS_RESULTS.md with clarifications
Phase 4: task-generate[--agent] --session sessionId
↓ Input: sessionId + ANALYSIS_RESULTS.md + session memory
↓ Input: sessionId + clarified ANALYSIS_RESULTS.md + session memory
↓ Output: IMPL_PLAN.md, task JSONs, TODO_LIST.md
Return summary to user
@@ -270,13 +341,18 @@ Return summary to user
## Coordinator Checklist
✅ **Pre-Phase**: Convert user input to structured format (GOAL/SCOPE/CONTEXT)
✅ Initialize TodoWrite before any command
✅ Initialize TodoWrite before any command (include Phase 3.5)
✅ Execute Phase 1 immediately with structured description
✅ Parse session ID from Phase 1 output, store in memory
✅ Pass session ID and structured description to Phase 2 command
✅ Parse context path from Phase 2 output, store in memory
Pass session ID and context path to Phase 3 command
Verify ANALYSIS_RESULTS.md after Phase 3
**Launch Phase 3 agent**: Build Task prompt with sessionId and contextPath
Wait for agent completion, parse execution log path
✅ Verify ANALYSIS_RESULTS.md created by agent
✅ **Execute Phase 3.5**: Pass session ID to `/workflow:concept-clarify`
✅ Wait for user interaction (clarification Q&A)
✅ Verify ANALYSIS_RESULTS.md updated with clarifications
✅ Check recommendation: proceed if "PROCEED", otherwise alert user
✅ **Build Phase 4 command** based on flags:
- Base command: `/workflow:tools:task-generate` (or `-agent` if `--agent` flag)
- Add `--session [sessionId]`

View File

@@ -137,6 +137,8 @@ Advanced solution design and feasibility analysis engine with parallel CLI execu
3. **Parallel Execution**: Launch tools simultaneously, monitor progress, handle completion/errors, maintain logs
**⚠️ IMPORTANT**: CLI commands MUST execute in foreground (NOT background). Do NOT use `run_in_background` parameter for Gemini/Codex execution.
### Phase 4: Results Collection & Synthesis
1. **Output Validation**: Validate gemini-solution-design.md (all), codex-feasibility-validation.md (complex), use logs if incomplete, classify status
2. **Quality Assessment**: Verify design rationale, insight depth, feasibility rigor, optimization value

View File

@@ -400,13 +400,23 @@ cd .workflow/WFS-auth/.design/prototypes && python -m http.server 8080
**Phase 5: Testing & Quality Assurance**
```bash
# Generate independent test-fix workflow (v3.2.2+)
/workflow:test-gen WFS-auth # Creates WFS-test-auth session
/workflow:test-cycle-execute # Execute test-fix cycle with iterative validation
/workflow:test-gen WFS-auth # Creates WFS-test-auth session
/workflow:test-cycle-execute # Execute test-fix cycle with dynamic iteration
# Resume interrupted test session
/workflow:test-cycle-execute --resume-session="WFS-test-auth"
# OR verify TDD compliance (TDD workflow)
/workflow:tdd-verify
```
**What is `/workflow:test-cycle-execute`?**
- **Dynamic Task Generation**: Creates intermediate fix tasks based on test failures during execution
- **Iterative Testing**: Automatically runs test-fix cycles until all tests pass or max iterations reached
- **CLI-Driven Analysis**: Uses Gemini/Qwen to analyze failures and generate fix strategies
- **Agent Coordination**: Delegates test execution and fixes to `@test-fix-agent`
- **Autonomous Completion**: Continues until success without user interruption
### Quick Start for Simple Tasks
**Feature Development:**
@@ -484,6 +494,7 @@ cd .workflow/WFS-auth/.design/prototypes && python -m http.server 8080
| `/workflow:execute` | Execute the current workflow plan autonomously. |
| `/workflow:status` | Display the current status of the workflow. |
| `/workflow:test-gen [--use-codex] <session>` | Create test generation workflow with auto-diagnosis and fix cycle for completed implementations. |
| `/workflow:test-cycle-execute` | **v4.5.0** Execute test-fix workflow with dynamic task generation and iterative fix cycles. Runs tests → analyzes failures with CLI → generates fix tasks → retests until success. |
| `/workflow:tdd-verify` | Verify TDD compliance and generate quality report. |
| `/workflow:review` | **Optional** manual review (only use when explicitly needed - passing tests = approved code). |
| `/workflow:tools:test-context-gather` | Analyze test coverage and identify missing test files. |

View File

@@ -400,13 +400,23 @@ cd .workflow/WFS-auth/.design/prototypes && python -m http.server 8080
**阶段 5测试与质量保证**
```bash
# 生成独立测试修复工作流v3.2.2+
/workflow:test-gen WFS-auth # 创建 WFS-test-auth 会话
/workflow:execute # 行测试验证
/workflow:test-gen WFS-auth # 创建 WFS-test-auth 会话
/workflow:test-cycle-execute # 行测试修复循环,包含动态迭代
# 恢复中断的测试会话
/workflow:test-cycle-execute --resume-session="WFS-test-auth"
# 或验证 TDD 合规性TDD 工作流)
/workflow:tdd-verify
```
**什么是 `/workflow:test-cycle-execute`**
- **动态任务生成**:基于测试失败在执行过程中创建中间修复任务
- **迭代测试**:自动运行测试修复循环,直到所有测试通过或达到最大迭代次数
- **CLI 驱动分析**:使用 Gemini/Qwen 分析失败并生成修复策略
- **智能体协调**:将测试执行和修复委托给 `@test-fix-agent`
- **自主完成**:持续直到成功,无需用户干预
### 简单任务快速入门
**功能开发:**
@@ -484,6 +494,7 @@ cd .workflow/WFS-auth/.design/prototypes && python -m http.server 8080
| `/workflow:execute` | 自主执行当前的工作流计划。 |
| `/workflow:status` | 显示工作流的当前状态。 |
| `/workflow:test-gen [--use-codex] <session>` | 为已完成实现创建独立测试生成工作流,支持自动诊断和修复。 |
| `/workflow:test-cycle-execute` | **v4.5.0** 执行测试修复工作流,包含动态任务生成和迭代修复循环。运行测试 → 使用 CLI 分析失败 → 生成修复任务 → 重新测试直至成功。 |
| `/workflow:tdd-verify` | 验证 TDD 合规性并生成质量报告。 |
| `/workflow:review` | **可选** 手动审查(仅在明确需要时使用,测试通过即代表代码已批准)。 |
| `/workflow:tools:test-context-gather` | 分析测试覆盖率,识别缺失的测试文件。 |