mirror of
https://github.com/catlog22/Claude-Code-Workflow.git
synced 2026-02-06 01:54:11 +08:00
Compare commits
4 Commits
| Author | SHA1 | Date | |
|---|---|---|---|
|
915eb396e7 | ||
|
|
1cb83c07e0 | ||
|
|
0404a7eb7c | ||
|
|
b98d28df3d |
@@ -151,9 +151,17 @@ Generate individual `.task/IMPL-*.json` files with:
|
||||
"agent": "@code-developer"
|
||||
},
|
||||
"context": {
|
||||
"requirements": ["from analysis_results"],
|
||||
"focus_paths": ["src/paths"],
|
||||
"acceptance": ["measurable criteria"],
|
||||
"requirements": [
|
||||
"Implement 3 features: [authentication, authorization, session management]",
|
||||
"Create 5 files: [auth.service.ts, auth.controller.ts, auth.middleware.ts, auth.types.ts, auth.test.ts]",
|
||||
"Modify 2 existing functions: [validateUser() in users.service.ts lines 45-60, hashPassword() in utils.ts lines 120-135]"
|
||||
],
|
||||
"focus_paths": ["src/auth", "tests/auth"],
|
||||
"acceptance": [
|
||||
"3 features implemented: verify by npm test -- auth (exit code 0)",
|
||||
"5 files created: verify by ls src/auth/*.ts | wc -l = 5",
|
||||
"Test coverage >=80%: verify by npm test -- --coverage | grep auth"
|
||||
],
|
||||
"depends_on": ["IMPL-N"],
|
||||
"artifacts": [
|
||||
{
|
||||
@@ -181,23 +189,50 @@ Generate individual `.task/IMPL-*.json` files with:
|
||||
{
|
||||
"step": 1,
|
||||
"title": "Load and analyze role analyses",
|
||||
"description": "Load role analyses from artifacts and extract requirements",
|
||||
"modification_points": ["Load role analyses", "Extract requirements and design patterns"],
|
||||
"logic_flow": ["Read role analyses from artifacts", "Parse architecture decisions", "Extract implementation requirements"],
|
||||
"description": "Load 3 role analysis files and extract quantified requirements",
|
||||
"modification_points": [
|
||||
"Load 3 role analysis files: [system-architect/analysis.md, product-manager/analysis.md, ui-designer/analysis.md]",
|
||||
"Extract 15 requirements from role analyses",
|
||||
"Parse 8 architecture decisions from system-architect analysis"
|
||||
],
|
||||
"logic_flow": [
|
||||
"Read 3 role analyses from artifacts inventory",
|
||||
"Parse architecture decisions (8 total)",
|
||||
"Extract implementation requirements (15 total)",
|
||||
"Build consolidated requirements list"
|
||||
],
|
||||
"depends_on": [],
|
||||
"output": "synthesis_requirements"
|
||||
},
|
||||
{
|
||||
"step": 2,
|
||||
"title": "Implement following specification",
|
||||
"description": "Implement task requirements following consolidated role analyses",
|
||||
"modification_points": ["Apply requirements from [synthesis_requirements]", "Modify target files", "Integrate with existing code"],
|
||||
"logic_flow": ["Apply changes based on [synthesis_requirements]", "Implement core logic", "Validate against acceptance criteria"],
|
||||
"description": "Implement 3 features across 5 files following consolidated role analyses",
|
||||
"modification_points": [
|
||||
"Create 5 new files in src/auth/: [auth.service.ts (180 lines), auth.controller.ts (120 lines), auth.middleware.ts (60 lines), auth.types.ts (40 lines), auth.test.ts (200 lines)]",
|
||||
"Modify 2 functions: [validateUser() in users.service.ts lines 45-60, hashPassword() in utils.ts lines 120-135]",
|
||||
"Implement 3 core features: [JWT authentication, role-based authorization, session management]"
|
||||
],
|
||||
"logic_flow": [
|
||||
"Apply 15 requirements from [synthesis_requirements]",
|
||||
"Implement 3 features across 5 new files (600 total lines)",
|
||||
"Modify 2 existing functions (30 lines total)",
|
||||
"Write 25 test cases covering all features",
|
||||
"Validate against 3 acceptance criteria"
|
||||
],
|
||||
"depends_on": [1],
|
||||
"output": "implementation"
|
||||
}
|
||||
],
|
||||
"target_files": ["file:function:lines", "path/to/NewFile.ts"]
|
||||
"target_files": [
|
||||
"src/auth/auth.service.ts",
|
||||
"src/auth/auth.controller.ts",
|
||||
"src/auth/auth.middleware.ts",
|
||||
"src/auth/auth.types.ts",
|
||||
"tests/auth/auth.test.ts",
|
||||
"src/users/users.service.ts:validateUser:45-60",
|
||||
"src/utils/utils.ts:hashPassword:120-135"
|
||||
]
|
||||
}
|
||||
}
|
||||
```
|
||||
@@ -285,6 +320,35 @@ Use `analysis_results.complexity` or task count to determine structure:
|
||||
- **Re-scope required**: Maximum 10 tasks hard limit
|
||||
- If analysis_results contains >10 tasks, consolidate or request re-scoping
|
||||
|
||||
## Quantification Requirements (MANDATORY)
|
||||
|
||||
**Purpose**: Eliminate ambiguity by enforcing explicit counts and enumerations in all task specifications.
|
||||
|
||||
**Core Rules**:
|
||||
1. **Extract Counts from Analysis**: Search for HOW MANY items and list them explicitly
|
||||
2. **Enforce Explicit Lists**: Every deliverable uses format `{count} {type}: [{explicit_list}]`
|
||||
3. **Make Acceptance Measurable**: Include verification commands (e.g., `ls ... | wc -l = N`)
|
||||
4. **Quantify Modification Points**: Specify exact targets (files, functions with line numbers)
|
||||
5. **Avoid Vague Language**: Replace "complete", "comprehensive", "reorganize" with quantified statements
|
||||
|
||||
**Standard Formats**:
|
||||
- **Requirements**: `"Implement N items: [item1, item2, ...]"` or `"Modify N files: [file1:func:lines, ...]"`
|
||||
- **Acceptance**: `"N items exist: verify by [command]"` or `"Coverage >= X%: verify by [test command]"`
|
||||
- **Modification Points**: `"Create N files: [list]"` or `"Modify N functions: [func() in file lines X-Y]"`
|
||||
|
||||
**Validation Checklist** (Apply to every generated task JSON):
|
||||
- [ ] Every requirement contains explicit count or enumerated list
|
||||
- [ ] Every acceptance criterion is measurable with verification command
|
||||
- [ ] Every modification_point specifies exact targets (files/functions/lines)
|
||||
- [ ] No vague language ("complete", "comprehensive", "reorganize" without counts)
|
||||
- [ ] Each implementation step has its own acceptance criteria
|
||||
|
||||
**Examples**:
|
||||
- ✅ GOOD: `"Implement 5 commands: [cmd1, cmd2, cmd3, cmd4, cmd5]"`
|
||||
- ❌ BAD: `"Implement new commands"`
|
||||
- ✅ GOOD: `"5 files created: verify by ls .claude/commands/*.md | wc -l = 5"`
|
||||
- ❌ BAD: `"All commands implemented successfully"`
|
||||
|
||||
## Quality Standards
|
||||
|
||||
**Planning Principles:**
|
||||
@@ -305,6 +369,7 @@ Use `analysis_results.complexity` or task count to determine structure:
|
||||
## Key Reminders
|
||||
|
||||
**ALWAYS:**
|
||||
- **Apply Quantification Requirements**: All requirements, acceptance criteria, and modification points MUST include explicit counts and enumerations
|
||||
- **Use provided context package**: Extract all information from structured context
|
||||
- **Respect memory-first rule**: Use provided content (already loaded from memory/file)
|
||||
- **Follow 5-field schema**: All task JSONs must have id, title, status, meta, context, flow_control
|
||||
@@ -313,6 +378,7 @@ Use `analysis_results.complexity` or task count to determine structure:
|
||||
- **Validate task count**: Maximum 10 tasks hard limit, request re-scope if exceeded
|
||||
- **Use session paths**: Construct all paths using provided session_id
|
||||
- **Link documents properly**: Use correct linking format (📋 for JSON, ✅ for summaries)
|
||||
- **Run validation checklist**: Verify all quantification requirements before finalizing task JSONs
|
||||
|
||||
**NEVER:**
|
||||
- Load files directly (use provided context package instead)
|
||||
|
||||
@@ -24,6 +24,7 @@ Analyzes conflicts between implementation plans and existing codebase, generatin
|
||||
| **Generate Strategies** | Provide 2-4 resolution options per conflict |
|
||||
| **CLI Analysis** | Use Gemini/Qwen (Claude fallback) |
|
||||
| **User Decision** | Present options, never auto-apply |
|
||||
| **Direct Text Output** | Output questions via text directly, NEVER use bash echo/printf |
|
||||
| **Single Output** | `CONFLICT_RESOLUTION.md` with findings |
|
||||
|
||||
## Conflict Categories
|
||||
|
||||
@@ -177,23 +177,49 @@ If conflict_risk was medium/high, modifications have been applied to:
|
||||
- **Function-based**: Complete units (logic + UI + tests + config)
|
||||
- **Hierarchy**: Flat (≤5) | Two-level (6-10) | Re-scope (>10)
|
||||
|
||||
### Quantification Requirements (MANDATORY)
|
||||
|
||||
**Purpose**: Eliminate ambiguity by enforcing explicit counts and enumerations in all task specifications.
|
||||
|
||||
**Core Rules**:
|
||||
1. **Extract Counts from Analysis**: Search for HOW MANY items and list them explicitly
|
||||
2. **Enforce Explicit Lists**: Every deliverable uses format `{count} {type}: [{explicit_list}]`
|
||||
3. **Make Acceptance Measurable**: Include verification commands (e.g., `ls ... | wc -l = N`)
|
||||
4. **Quantify Modification Points**: Specify exact targets (files, functions with line numbers)
|
||||
5. **Avoid Vague Language**: Replace "complete", "comprehensive", "reorganize" with quantified statements
|
||||
|
||||
**Standard Formats**:
|
||||
- **Requirements**: `"Implement N items: [item1, item2, ...]"` or `"Modify N files: [file1:func:lines, ...]"`
|
||||
- **Acceptance**: `"N items exist: verify by [command]"` or `"Coverage >= X%: verify by [test command]"`
|
||||
- **Modification Points**: `"Create N files: [list]"` or `"Modify N functions: [func() in file lines X-Y]"`
|
||||
|
||||
**Validation Checklist**:
|
||||
- [ ] Every requirement contains explicit count or enumerated list
|
||||
- [ ] Every acceptance criterion is measurable with verification command
|
||||
- [ ] Every modification_point specifies exact targets (files/functions/lines)
|
||||
- [ ] No vague language ("complete", "comprehensive", "reorganize" without counts)
|
||||
- [ ] Each implementation step has its own acceptance criteria
|
||||
|
||||
### Required Outputs
|
||||
|
||||
#### 1. Task JSON Files (.task/IMPL-*.json)
|
||||
**Location**: .workflow/{session-id}/.task/
|
||||
**Template**: Read from the template path provided above
|
||||
|
||||
**Task JSON Template Loading**:
|
||||
\`\`\`
|
||||
Read({template_path})
|
||||
\`\`\`
|
||||
**Location**: `.workflow/{session-id}/.task/`
|
||||
**Template Path**: Provided by command (agent-mode or cli-mode template)
|
||||
|
||||
**Important**:
|
||||
- Read the template from the path provided in context
|
||||
- Use the template structure exactly as written
|
||||
- Replace placeholder variables ({synthesis_spec_path}, {role_analysis_path}, etc.) with actual session-specific paths
|
||||
- Include MCP tool integration in pre_analysis steps
|
||||
**Key Responsibilities**:
|
||||
- Read template from provided path: `Read({template_path})`
|
||||
- Replace placeholder variables with session-specific paths
|
||||
- Include MCP tool integration in `pre_analysis` steps
|
||||
- Map artifacts based on task domain (UI → ui-designer, Backend → system-architect)
|
||||
- Apply quantification requirements to all task fields
|
||||
- Ensure all tasks follow template structure exactly
|
||||
|
||||
**Template Selection** (Pre-selected by command):
|
||||
- **Agent Mode**: `~/.claude/workflows/cli-templates/prompts/workflow/task-json-agent-mode.txt`
|
||||
- **CLI Mode**: `~/.claude/workflows/cli-templates/prompts/workflow/task-json-cli-mode.txt`
|
||||
|
||||
**Note**: Agent does NOT choose template - it's pre-selected based on `--cli-execute` flag and provided in context
|
||||
|
||||
#### 2. IMPL_PLAN.md
|
||||
**Location**: .workflow/{session-id}/IMPL_PLAN.md
|
||||
@@ -240,20 +266,31 @@ $(cat ~/.claude/workflows/cli-templates/prompts/workflow/impl-plan-template.txt)
|
||||
- Read template from the provided path: `Read({template_path})`
|
||||
- This template is already the correct one based on execution mode
|
||||
|
||||
**Step 2: Extract and Decompose Tasks**
|
||||
**Step 2: Extract and Decompose Tasks (WITH QUANTIFICATION)**
|
||||
- Parse role analysis.md files for requirements, design specs, and task recommendations
|
||||
- **CRITICAL: Apply Quantification Extraction Process**:
|
||||
- Scan for counts: numbers + nouns (e.g., "5 files", "17 commands", "3 features")
|
||||
- Build explicit lists for each deliverable (no "..." unless list >20 items)
|
||||
- Flag vague language ("complete", "comprehensive", "reorganize") for replacement
|
||||
- Extract verification methods for each deliverable
|
||||
- Review synthesis enhancements and clarifications in role analyses
|
||||
- Apply conflict resolution strategies (if CONFLICT_RESOLUTION.md exists)
|
||||
- Apply task merging rules (merge when possible, decompose only when necessary)
|
||||
- Map artifacts to tasks based on domain (UI → ui-designer, Backend → system-architect, Data → data-architect)
|
||||
- Ensure task count ≤10
|
||||
|
||||
**Step 3: Generate Task JSON Files**
|
||||
**Step 3: Generate Task JSON Files (ENFORCE QUANTIFICATION)**
|
||||
- Use the template structure from Step 1
|
||||
- Create .task/IMPL-*.json files with proper structure
|
||||
- **MANDATORY: Apply Quantification Formats**:
|
||||
- Every requirement: \`{count} {type}: [{explicit_list}]\`
|
||||
- Every acceptance: Measurable with verification command
|
||||
- Every modification_point: Exact targets (files/functions/lines)
|
||||
- NO vague language in any field
|
||||
- Replace all {placeholder} variables with actual session paths
|
||||
- Embed artifacts array with brainstorming outputs
|
||||
- Include MCP tool integration in pre_analysis steps
|
||||
- **Validation**: Run checklist from Quantification Requirements section before writing files
|
||||
|
||||
**Step 4: Create IMPL_PLAN.md**
|
||||
- Use IMPL_PLAN template
|
||||
@@ -270,34 +307,10 @@ $(cat ~/.claude/workflows/cli-templates/prompts/workflow/impl-plan-template.txt)
|
||||
- Update workflow-session.json with task count and artifact inventory
|
||||
- Mark session ready for execution
|
||||
|
||||
### MCP Enhancement Examples
|
||||
### MCP Enhancement (Optional)
|
||||
|
||||
**Code Index Usage**:
|
||||
\`\`\`javascript
|
||||
// Discover authentication-related files
|
||||
bash(find . -name "*auth*" -type f)
|
||||
|
||||
// Search for OAuth patterns
|
||||
bash(rg "oauth|jwt|authentication" -g "*.{ts,js}")
|
||||
|
||||
// Get file summary for key components
|
||||
bash(rg "^(class|function|export|interface)" src/auth/index.ts)
|
||||
\`\`\`
|
||||
|
||||
**Exa Research Usage**:
|
||||
\`\`\`javascript
|
||||
// Get best practices for task implementation
|
||||
mcp__exa__get_code_context_exa(
|
||||
query="TypeScript OAuth2 implementation patterns",
|
||||
tokensNum="dynamic"
|
||||
)
|
||||
|
||||
// Research specific API usage
|
||||
mcp__exa__get_code_context_exa(
|
||||
query="Express.js JWT middleware examples",
|
||||
tokensNum=5000
|
||||
)
|
||||
\`\`\`
|
||||
**Code Analysis**: Use `find`, `rg` for file discovery and pattern search
|
||||
**External Research**: Use `mcp__exa__get_code_context_exa` for best practices and API examples
|
||||
|
||||
### Quality Validation
|
||||
|
||||
|
||||
@@ -55,6 +55,33 @@ Generate TDD-specific tasks from analysis results with complete Red-Green-Refact
|
||||
- **Context-Aware**: Analyzes existing codebase and test patterns
|
||||
- **Iterative Green Phase**: Auto-diagnose and fix test failures with Gemini + optional Codex
|
||||
- **Safety-First**: Auto-revert on max iterations to prevent broken state
|
||||
- **Quantification-Enforced**: All test cases, coverage requirements, and implementation scope MUST include explicit counts and enumerations (e.g., "15 test cases: [test1, test2, ...]" not "comprehensive tests")
|
||||
|
||||
## Quantification Requirements for TDD (MANDATORY)
|
||||
|
||||
**Purpose**: Eliminate ambiguity by enforcing explicit test case counts, coverage metrics, and implementation scope.
|
||||
|
||||
**Core Rules**:
|
||||
1. **Explicit Test Case Counts**: Red phase specifies exact number with enumerated list
|
||||
2. **Quantified Coverage**: Acceptance includes measurable percentage (e.g., ">=85%")
|
||||
3. **Detailed Implementation Scope**: Green phase enumerates files, functions, line counts
|
||||
4. **Enumerated Refactoring Targets**: Refactor phase lists specific improvements with counts
|
||||
|
||||
**TDD Phase Formats**:
|
||||
- **Red Phase**: `"Write N test cases: [test1, test2, ...]"`
|
||||
- **Green Phase**: `"Implement N functions in file lines X-Y: [func1() X1-Y1, func2() X2-Y2, ...]"`
|
||||
- **Refactor Phase**: `"Apply N refactorings: [improvement1 (details), improvement2 (details), ...]"`
|
||||
- **Acceptance**: `"All N tests pass with >=X% coverage: verify by [test command]"`
|
||||
|
||||
**TDD Cycles Array**: Each cycle must include `test_count`, `test_cases` array, `implementation_scope`, and `expected_coverage`
|
||||
|
||||
**Validation Checklist**:
|
||||
- [ ] Every Red phase specifies exact test case count with enumerated list
|
||||
- [ ] Every Green phase enumerates files, functions, and estimated line counts
|
||||
- [ ] Every Refactor phase lists specific improvements with counts
|
||||
- [ ] Every acceptance criterion includes measurable coverage percentage
|
||||
- [ ] tdd_cycles array contains test_count and test_cases for each cycle
|
||||
- [ ] No vague language ("comprehensive", "complete", "thorough")
|
||||
|
||||
## Core Responsibilities
|
||||
- Parse analysis results and identify testable features
|
||||
@@ -129,250 +156,87 @@ For each feature, generate task(s) with ID format:
|
||||
|
||||
#### Task JSON Structure Reference
|
||||
|
||||
**Simple Feature Task (IMPL-N.json)** - Recommended for most features:
|
||||
```json
|
||||
{
|
||||
"id": "IMPL-N", // Task identifier
|
||||
"title": "Feature description with TDD", // Human-readable title
|
||||
"status": "pending", // pending | in_progress | completed | container
|
||||
"context_package_path": ".workflow/{session-id}/.process/context-package.json", // Path to smart context package
|
||||
"meta": {
|
||||
"type": "feature", // Task type
|
||||
"agent": "@code-developer", // Assigned agent
|
||||
"tdd_workflow": true, // REQUIRED: Enables TDD flow
|
||||
"max_iterations": 3, // Green phase test-fix cycle limit
|
||||
"use_codex": false // false=manual fixes, true=Codex automated fixes
|
||||
},
|
||||
"context": {
|
||||
"requirements": [ // Feature requirements with TDD phases
|
||||
"Feature description",
|
||||
"Red: Test scenarios to write",
|
||||
"Green: Implementation approach with test-fix cycle",
|
||||
"Refactor: Code quality improvements"
|
||||
],
|
||||
"tdd_cycles": [ // OPTIONAL: Detailed test cycles
|
||||
{
|
||||
"cycle": 1,
|
||||
"feature": "Specific functionality",
|
||||
"test_focus": "What to test",
|
||||
"expected_failure": "Why test should fail initially"
|
||||
}
|
||||
],
|
||||
"focus_paths": ["D:\\project\\src\\path", "./tests/path"], // Absolute or clear relative paths from project root
|
||||
"acceptance": [ // Success criteria
|
||||
"All tests pass (Red → Green)",
|
||||
"Code refactored (Refactor complete)",
|
||||
"Test coverage ≥80%"
|
||||
],
|
||||
"depends_on": [] // Task dependencies
|
||||
},
|
||||
"flow_control": {
|
||||
"pre_analysis": [ // OPTIONAL: Pre-execution checks
|
||||
{
|
||||
"step": "check_test_framework",
|
||||
"action": "Verify test framework",
|
||||
"command": "bash(npm list jest)",
|
||||
"output_to": "test_framework_info",
|
||||
"on_error": "warn"
|
||||
}
|
||||
],
|
||||
"implementation_approach": [ // REQUIRED: 3 TDD phases
|
||||
{
|
||||
"step": 1,
|
||||
"title": "RED Phase: Write failing tests",
|
||||
"tdd_phase": "red", // REQUIRED: Phase identifier
|
||||
"description": "Write comprehensive failing tests",
|
||||
"modification_points": ["Files/changes to make"],
|
||||
"logic_flow": ["Step-by-step process"],
|
||||
"acceptance": ["Phase success criteria"],
|
||||
"depends_on": [],
|
||||
"output": "failing_tests"
|
||||
},
|
||||
{
|
||||
"step": 2,
|
||||
"title": "GREEN Phase: Implement to pass tests",
|
||||
"tdd_phase": "green", // REQUIRED: Phase identifier
|
||||
"description": "Minimal implementation with test-fix cycle",
|
||||
"modification_points": ["Implementation files"],
|
||||
"logic_flow": [
|
||||
"Implement minimal code",
|
||||
"Run tests",
|
||||
"If fail → Enter iteration loop (max 3):",
|
||||
" 1. Extract failure messages",
|
||||
" 2. Gemini bug-fix diagnosis",
|
||||
" 3. Apply fixes",
|
||||
" 4. Rerun tests",
|
||||
"If max_iterations → Auto-revert"
|
||||
],
|
||||
"acceptance": ["All tests pass"],
|
||||
"command": "bash(npm test -- tests/path/)",
|
||||
"depends_on": [1],
|
||||
"output": "passing_implementation"
|
||||
},
|
||||
{
|
||||
"step": 3,
|
||||
"title": "REFACTOR Phase: Improve code quality",
|
||||
"tdd_phase": "refactor", // REQUIRED: Phase identifier
|
||||
"description": "Refactor while keeping tests green",
|
||||
"modification_points": ["Quality improvements"],
|
||||
"logic_flow": ["Incremental refactoring with test verification"],
|
||||
"acceptance": ["Tests still pass", "Code quality improved"],
|
||||
"command": "bash(npm run lint && npm test)",
|
||||
"depends_on": [2],
|
||||
"output": "refactored_implementation"
|
||||
}
|
||||
],
|
||||
"post_completion": [ // OPTIONAL: Final verification
|
||||
{
|
||||
"step": "verify_full_tdd_cycle",
|
||||
"action": "Confirm complete TDD cycle",
|
||||
"command": "bash(npm test && echo 'TDD complete')",
|
||||
"output_to": "final_validation",
|
||||
"on_error": "fail"
|
||||
}
|
||||
],
|
||||
"error_handling": { // OPTIONAL: Error recovery
|
||||
"green_phase_max_iterations": {
|
||||
"action": "revert_all_changes",
|
||||
"commands": ["bash(git reset --hard HEAD)"],
|
||||
"report": "Generate failure report"
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
Each TDD task JSON contains complete Red-Green-Refactor cycle with these key fields:
|
||||
|
||||
**Key JSON Fields Summary**:
|
||||
- `meta.tdd_workflow`: Must be `true`
|
||||
- `meta.max_iterations`: Green phase fix cycle limit (default: 3)
|
||||
- `meta.use_codex`: Automated fixes (false=manual, true=Codex)
|
||||
- `flow_control.implementation_approach`: Exactly 3 steps with `tdd_phase`: "red", "green", "refactor"
|
||||
- `context.tdd_cycles`: Optional detailed test cycle specifications
|
||||
- `context.parent`: Required for subtasks (IMPL-N.M)
|
||||
**Top-Level Fields**:
|
||||
- `id`: Task identifier (`IMPL-N` or `IMPL-N.M` for subtasks)
|
||||
- `title`: Feature description with TDD
|
||||
- `status`: `pending | in_progress | completed | container`
|
||||
- `context_package_path`: Path to context package
|
||||
- `meta`: TDD-specific metadata
|
||||
- `context`: Requirements, cycles, paths, acceptance
|
||||
- `flow_control`: Pre-analysis, 3 TDD phases, post-completion, error handling
|
||||
|
||||
**Meta Object (TDD-Specific)**:
|
||||
- `type`: "feature"
|
||||
- `agent`: "@code-developer"
|
||||
- `tdd_workflow`: `true` (REQUIRED - enables TDD flow)
|
||||
- `max_iterations`: Green phase test-fix cycle limit (default: 3)
|
||||
- `use_codex`: `false` (manual fixes) or `true` (Codex automated fixes)
|
||||
|
||||
**Context Object**:
|
||||
- `requirements`: Quantified feature requirements with TDD phase details
|
||||
- `tdd_cycles`: Array of test cycles (each with `test_count`, `test_cases`, `implementation_scope`, `expected_coverage`)
|
||||
- `focus_paths`: Target directories (absolute or relative from project root)
|
||||
- `acceptance`: Measurable success criteria with verification commands
|
||||
- `depends_on`: Task dependencies
|
||||
- `parent`: Parent task ID (for subtasks only)
|
||||
|
||||
**Flow Control Object**:
|
||||
- `pre_analysis`: Optional pre-execution checks
|
||||
- `implementation_approach`: Exactly 3 steps with `tdd_phase` field:
|
||||
1. **Red Phase** (`tdd_phase: "red"`): Write failing tests
|
||||
2. **Green Phase** (`tdd_phase: "green"`): Implement to pass tests (includes test-fix cycle)
|
||||
3. **Refactor Phase** (`tdd_phase: "refactor"`): Improve code quality
|
||||
- `post_completion`: Optional final verification
|
||||
- `error_handling`: Error recovery strategies (e.g., auto-revert on max iterations)
|
||||
|
||||
**Implementation Approach Step Structure**:
|
||||
Each step includes:
|
||||
- `step`: Step number
|
||||
- `title`: Phase description
|
||||
- `tdd_phase`: Phase identifier ("red" | "green" | "refactor")
|
||||
- `description`: Detailed phase description
|
||||
- `modification_points`: Quantified changes to make
|
||||
- `logic_flow`: Step-by-step execution logic
|
||||
- `acceptance`: Phase-specific acceptance criteria
|
||||
- `command`: Test/verification command (optional)
|
||||
- `depends_on`: Previous step dependencies
|
||||
- `output`: Step output identifier
|
||||
|
||||
#### IMPL_PLAN.md Structure
|
||||
|
||||
Generate IMPL_PLAN.md with 8-section structure:
|
||||
**Frontmatter** (TDD-specific fields):
|
||||
- `workflow_type`: "tdd"
|
||||
- `tdd_workflow`: true
|
||||
- `feature_count`, `task_count` (≤10 total)
|
||||
- `task_breakdown`: simple_features, complex_features, total_subtasks
|
||||
- `test_context`: Path to test-context-package.json (if exists)
|
||||
- `conflict_resolution`: Path to CONFLICT_RESOLUTION.md (if exists)
|
||||
- `verification_history`, `phase_progression`
|
||||
|
||||
**Frontmatter** (required fields):
|
||||
```yaml
|
||||
---
|
||||
identifier: WFS-{session-id}
|
||||
source: "User requirements" | "File: path"
|
||||
conflict_resolution: .workflow/{session-id}/.process/CONFLICT_RESOLUTION.md # if exists
|
||||
context_package: .workflow/{session-id}/.process/context-package.json
|
||||
context_package_path: .workflow/{session-id}/.process/context-package.json
|
||||
test_context: .workflow/{session-id}/.process/test-context-package.json # if exists
|
||||
workflow_type: "tdd"
|
||||
verification_history:
|
||||
conflict_resolution: "executed | skipped" # based on conflict_risk
|
||||
action_plan_verify: "pending"
|
||||
phase_progression: "brainstorm → context → test_context → conflict_resolution → tdd_planning"
|
||||
feature_count: N
|
||||
task_count: N # ≤10 total
|
||||
task_breakdown:
|
||||
simple_features: K
|
||||
complex_features: L
|
||||
total_subtasks: M
|
||||
tdd_workflow: true
|
||||
---
|
||||
```
|
||||
|
||||
**8 Sections Structure**:
|
||||
|
||||
```markdown
|
||||
# Implementation Plan: {Project Title}
|
||||
|
||||
## 1. Summary
|
||||
- Core requirements and objectives (2-3 paragraphs)
|
||||
- TDD-specific technical approach
|
||||
|
||||
## 2. Context Analysis
|
||||
- CCW Workflow Context (Phase progression, Quality gates)
|
||||
- Context Package Summary (Focus paths, Test context)
|
||||
- Project Profile (Type, Scale, Tech Stack, Timeline)
|
||||
- Module Structure (Directory tree)
|
||||
- Dependencies (Primary, Testing, Development)
|
||||
- Patterns & Conventions
|
||||
|
||||
## 3. Brainstorming Artifacts Reference
|
||||
- Artifact Usage Strategy
|
||||
- CONFLICT_RESOLUTION.md (if exists - selected resolution strategies)
|
||||
- role analysis documents (primary reference)
|
||||
- test-context-package.json (test patterns)
|
||||
- context-package.json (smart context)
|
||||
- Artifact Priority in Development
|
||||
|
||||
## 4. Implementation Strategy
|
||||
- Execution Strategy (TDD Cycles: Red-Green-Refactor)
|
||||
- Architectural Approach
|
||||
- Key Dependencies (Task dependency graph)
|
||||
- Testing Strategy (Coverage targets, Quality gates)
|
||||
|
||||
## 5. TDD Implementation Tasks
|
||||
- Feature-by-Feature TDD Tasks
|
||||
- Each task: IMPL-N with internal Red → Green → Refactor
|
||||
- Dependencies and complexity metrics
|
||||
- Complex Feature Examples (when subtasks needed)
|
||||
- TDD Task Breakdown Summary
|
||||
|
||||
## 6. Implementation Plan (Detailed Phased Breakdown)
|
||||
- Execution Strategy (feature-by-feature sequential)
|
||||
- Phase breakdown (Phase 1, Phase 2, etc.)
|
||||
- Resource Requirements (Team, Dependencies, Infrastructure)
|
||||
|
||||
## 7. Risk Assessment & Mitigation
|
||||
- Risk table (Risk, Impact, Probability, Mitigation, Owner)
|
||||
- Critical Risks (TDD-specific)
|
||||
- Monitoring Strategy
|
||||
|
||||
## 8. Success Criteria
|
||||
- Functional Completeness
|
||||
- Technical Quality (Test coverage ≥80%)
|
||||
- Operational Readiness
|
||||
- TDD Compliance
|
||||
```
|
||||
**8 Sections**:
|
||||
1. **Summary**: Core requirements, TDD-specific approach
|
||||
2. **Context Analysis**: CCW workflow context, project profile, module structure, dependencies
|
||||
3. **Brainstorming Artifacts Reference**: Artifact usage strategy, priority order
|
||||
4. **Implementation Strategy**: TDD cycles (Red-Green-Refactor), architectural approach, testing strategy
|
||||
5. **TDD Implementation Tasks**: Feature-by-feature tasks with internal TDD cycles, dependencies
|
||||
6. **Implementation Plan**: Phased breakdown, resource requirements
|
||||
7. **Risk Assessment & Mitigation**: Risk table, TDD-specific risks, monitoring
|
||||
8. **Success Criteria**: Functional completeness, technical quality (≥80% coverage), TDD compliance
|
||||
|
||||
### Phase 4: TODO_LIST.md Generation
|
||||
|
||||
Generate task list with internal TDD phase indicators:
|
||||
|
||||
**For Simple Features (1 task per feature)**:
|
||||
```markdown
|
||||
## TDD Implementation Tasks
|
||||
|
||||
### Feature 1: {Feature Name}
|
||||
- [ ] **IMPL-1**: Implement {feature} with TDD → [Task](./.task/IMPL-1.json)
|
||||
- Internal phases: Red → Green → Refactor
|
||||
- Dependencies: None
|
||||
|
||||
### Feature 2: {Feature Name}
|
||||
- [ ] **IMPL-2**: Implement {feature} with TDD → [Task](./.task/IMPL-2.json)
|
||||
- Internal phases: Red → Green → Refactor
|
||||
- Dependencies: IMPL-1
|
||||
```
|
||||
|
||||
**For Complex Features (with subtasks)**:
|
||||
```markdown
|
||||
### Feature 3: {Complex Feature Name}
|
||||
▸ **IMPL-3**: Implement {complex feature} with TDD → [Task](./.task/IMPL-3.json)
|
||||
- [ ] **IMPL-3.1**: {Sub-feature A} with TDD → [Task](./.task/IMPL-3.1.json)
|
||||
- Internal phases: Red → Green → Refactor
|
||||
- [ ] **IMPL-3.2**: {Sub-feature B} with TDD → [Task](./.task/IMPL-3.2.json)
|
||||
- Internal phases: Red → Green → Refactor
|
||||
- Dependencies: IMPL-3.1
|
||||
```
|
||||
**Structure**:
|
||||
- Simple features: `- [ ] **IMPL-N**: Feature with TDD` (Internal phases: Red → Green → Refactor)
|
||||
- Complex features: `▸ **IMPL-N**: Container` with subtasks `- [ ] **IMPL-N.M**: Sub-feature`
|
||||
|
||||
**Status Legend**:
|
||||
```markdown
|
||||
## Status Legend
|
||||
- ▸ = Container task (has subtasks)
|
||||
- [ ] = Pending task
|
||||
- [x] = Completed task
|
||||
- Red = Write failing tests
|
||||
- Green = Implement to pass tests (with test-fix cycle)
|
||||
- Refactor = Improve code quality
|
||||
```
|
||||
- `▸` = Container task (has subtasks)
|
||||
- `[ ]` = Pending | `[x]` = Completed
|
||||
- Red → Green → Refactor = TDD phases
|
||||
|
||||
### Phase 5: Session State Update
|
||||
|
||||
@@ -465,12 +329,12 @@ Update workflow-session.json with TDD metadata:
|
||||
|
||||
## Integration & Usage
|
||||
|
||||
### Command Chain
|
||||
- **Called By**: `/workflow:tdd-plan` (Phase 4)
|
||||
- **Calls**: Gemini CLI for TDD breakdown
|
||||
- **Followed By**: `/workflow:execute`, `/workflow:tdd-verify`
|
||||
**Command Chain**:
|
||||
- Called by: `/workflow:tdd-plan` (Phase 4)
|
||||
- Calls: Gemini CLI for TDD breakdown
|
||||
- Followed by: `/workflow:execute`, `/workflow:tdd-verify`
|
||||
|
||||
### Basic Usage
|
||||
**Basic Usage**:
|
||||
```bash
|
||||
# Manual mode (default)
|
||||
/workflow:tools:task-generate-tdd --session WFS-auth
|
||||
@@ -479,38 +343,11 @@ Update workflow-session.json with TDD metadata:
|
||||
/workflow:tools:task-generate-tdd --session WFS-auth --agent
|
||||
```
|
||||
|
||||
### Expected Output
|
||||
```
|
||||
TDD task generation complete for session: WFS-auth
|
||||
|
||||
Features analyzed: 5
|
||||
Total tasks: 5 (1 task per feature with internal TDD cycles)
|
||||
|
||||
Task breakdown:
|
||||
- Simple features: 4 tasks (IMPL-1 to IMPL-4)
|
||||
- Complex features: 1 task with 2 subtasks (IMPL-5, IMPL-5.1, IMPL-5.2)
|
||||
- Total task count: 6 (within 10-task limit)
|
||||
|
||||
Structure:
|
||||
- IMPL-1: User Authentication (Internal: Red → Green → Refactor)
|
||||
- IMPL-2: Password Reset (Internal: Red → Green → Refactor)
|
||||
- IMPL-3: Email Verification (Internal: Red → Green → Refactor)
|
||||
- IMPL-4: Role Management (Internal: Red → Green → Refactor)
|
||||
- IMPL-5: Payment System (Container)
|
||||
- IMPL-5.1: Gateway Integration (Internal: Red → Green → Refactor)
|
||||
- IMPL-5.2: Transaction Management (Internal: Red → Green → Refactor)
|
||||
|
||||
Plans generated:
|
||||
- Unified Plan: .workflow/WFS-auth/IMPL_PLAN.md (includes TDD Implementation Tasks section)
|
||||
- Task List: .workflow/WFS-auth/TODO_LIST.md (with internal TDD phase indicators)
|
||||
|
||||
TDD Configuration:
|
||||
- Each task contains complete Red-Green-Refactor cycle
|
||||
- Green phase includes test-fix cycle (max 3 iterations)
|
||||
- Auto-revert on max iterations reached
|
||||
|
||||
Next: /workflow:action-plan-verify --session WFS-auth (recommended) or /workflow:execute --session WFS-auth
|
||||
```
|
||||
**Output**:
|
||||
- Task JSON files in `.task/` directory (IMPL-N.json format)
|
||||
- IMPL_PLAN.md with TDD Implementation Tasks section
|
||||
- TODO_LIST.md with internal TDD phase indicators
|
||||
- Session state updated with task count and TDD metadata
|
||||
|
||||
## Test Coverage Analysis Integration
|
||||
|
||||
|
||||
@@ -45,8 +45,33 @@ This command is built on a set of core principles to ensure efficient and reliab
|
||||
- **Memory-First**: Prioritizes using documents already loaded in conversation memory to avoid redundant file operations
|
||||
- **Mode-Flexible**: Supports both agent-driven execution (default) and CLI tool execution (with `--cli-execute` flag)
|
||||
- **Multi-Step Support**: Complex tasks can use multiple sequential steps in `implementation_approach` with codex resume mechanism
|
||||
- **Quantification-Enforced**: **NEW** - All requirements, acceptance criteria, and modification points MUST include explicit counts and enumerations to prevent ambiguity (e.g., "17 commands: [list]" not "implement commands")
|
||||
- **Responsibility**: Parses analysis, detects artifacts, generates enhanced task JSONs, creates `IMPL_PLAN.md` and `TODO_LIST.md`, updates session state
|
||||
|
||||
## 3.5. Quantification Requirements (MANDATORY)
|
||||
|
||||
**Purpose**: Eliminate ambiguity by enforcing explicit counts and enumerations in all task specifications.
|
||||
|
||||
**Core Rules**:
|
||||
1. **Extract Counts from Analysis**: Search for HOW MANY items and list them explicitly
|
||||
2. **Enforce Explicit Lists**: Every deliverable uses format `{count} {type}: [{explicit_list}]`
|
||||
3. **Make Acceptance Measurable**: Include verification commands (e.g., `ls ... | wc -l = N`)
|
||||
4. **Quantify Modification Points**: Specify exact targets (files, functions with line numbers)
|
||||
5. **Avoid Vague Language**: Replace "complete", "comprehensive", "reorganize" with quantified statements
|
||||
|
||||
**Standard Formats**:
|
||||
|
||||
- **Requirements**: `"Implement N items: [item1, item2, ...]"` or `"Modify N files: [file1:func:lines, ...]"`
|
||||
- **Acceptance**: `"N items exist: verify by [command]"` or `"Coverage >= X%: verify by [test command]"`
|
||||
- **Modification Points**: `"Create N files: [list]"` or `"Modify N functions: [func() in file lines X-Y]"`
|
||||
|
||||
**Validation Checklist**:
|
||||
- [ ] Every requirement contains explicit count or enumerated list
|
||||
- [ ] Every acceptance criterion is measurable with verification command
|
||||
- [ ] Every modification_point specifies exact targets (files/functions/lines)
|
||||
- [ ] No vague language ("complete", "comprehensive", "reorganize" without counts)
|
||||
- [ ] Each implementation step has its own acceptance criteria
|
||||
|
||||
## 4. Execution Flow
|
||||
The command follows a streamlined, three-step process to convert analysis into executable tasks.
|
||||
|
||||
@@ -59,13 +84,39 @@ The process begins by gathering all necessary inputs. It follows a **Memory-Firs
|
||||
|
||||
### Step 2: Task Decomposition & Grouping
|
||||
Once all inputs are loaded, the command analyzes the tasks defined in the analysis results and groups them based on shared context.
|
||||
1. **Task Definition Parsing**: Extracts task definitions, requirements, and dependencies.
|
||||
2. **Context Signature Analysis**: Computes a unique hash (`context_signature`) for each task based on its `focus_paths` and referenced `artifacts`.
|
||||
|
||||
**Phase 2.1: Quantification Extraction (NEW - CRITICAL)**
|
||||
1. **Count Extraction**: Scan analysis documents for quantifiable information:
|
||||
- Search for numbers + nouns (e.g., "5 files", "17 commands", "3 features")
|
||||
- Identify enumerated lists (bullet points, numbered lists, comma-separated items)
|
||||
- Extract explicit counts from tables, diagrams, or structured data
|
||||
- Store extracted counts with their context (what is being counted)
|
||||
|
||||
2. **List Enumeration**: Build explicit lists for each deliverable:
|
||||
- If analysis says "implement session commands", enumerate ALL commands: [start, resume, list, complete, archive]
|
||||
- If analysis mentions "create categories", list ALL categories: [literature, experiment, data-analysis, visualization, context]
|
||||
- If analysis describes "modify functions", list ALL functions with line numbers
|
||||
- Maintain full enumerations (no "..." unless list exceeds 20 items)
|
||||
|
||||
3. **Verification Method Assignment**: For each deliverable, determine verification approach:
|
||||
- File count: `ls {path}/*.{ext} | wc -l = {count}`
|
||||
- Directory existence: `ls {parent}/ | grep -E '(name1|name2|...)' | wc -l = {count}`
|
||||
- Test coverage: `pytest --cov={module} --cov-report=term | grep TOTAL | awk '{print $4}' >= {percentage}`
|
||||
- Function existence: `grep -E '(func1|func2|...)' {file} | wc -l = {count}`
|
||||
|
||||
4. **Ambiguity Detection**: Flag vague language for replacement:
|
||||
- Detect words: "complete", "comprehensive", "reorganize", "refactor", "implement", "create" without counts
|
||||
- Require quantification: "implement" → "implement {N} {items}: [{list}]"
|
||||
- Reject unquantified deliverables
|
||||
|
||||
**Phase 2.2: Task Definition & Grouping**
|
||||
1. **Task Definition Parsing**: Extracts task definitions, requirements, and dependencies from quantified analysis
|
||||
2. **Context Signature Analysis**: Computes a unique hash (`context_signature`) for each task based on its `focus_paths` and referenced `artifacts`
|
||||
3. **Task Grouping**:
|
||||
* Tasks with the **same signature** are candidates for merging, as they operate on the same context.
|
||||
* Tasks with **different signatures** and no dependencies are grouped for parallel execution.
|
||||
* Tasks with `depends_on` relationships are marked for sequential execution.
|
||||
4. **Modification Target Determination**: Extracts specific code locations (`file:function:lines`) from the analysis to populate the `target_files` field.
|
||||
* Tasks with the **same signature** are candidates for merging, as they operate on the same context
|
||||
* Tasks with **different signatures** and no dependencies are grouped for parallel execution
|
||||
* Tasks with `depends_on` relationships are marked for sequential execution
|
||||
4. **Modification Target Determination**: Extracts specific code locations (`file:function:lines`) from the analysis to populate the `target_files` field
|
||||
|
||||
### Step 3: Output Generation
|
||||
Finally, the command generates all the necessary output files.
|
||||
@@ -167,38 +218,82 @@ function assignExecutionGroups(tasks) {
|
||||
The command produces three key documents and a directory of task files.
|
||||
|
||||
### 6.1. Task JSON Schema (`.task/IMPL-*.json`)
|
||||
This enhanced 5-field schema embeds all necessary context, artifacts, and execution steps.
|
||||
Each task JSON embeds all necessary context, artifacts, and execution steps using this schema:
|
||||
|
||||
**Top-Level Fields**:
|
||||
- `id`: Task identifier (format: `IMPL-N` or `IMPL-N.M` for subtasks)
|
||||
- `title`: Descriptive task name
|
||||
- `status`: Task state (`pending|active|completed|blocked|container`)
|
||||
- `context_package_path`: Path to context package (`.workflow/WFS-[session]/.process/context-package.json`)
|
||||
- `meta`: Task metadata
|
||||
- `context`: Task-specific context and requirements
|
||||
- `flow_control`: Execution steps and workflow
|
||||
|
||||
**Meta Object**:
|
||||
- `type`: Task category (`feature|bugfix|refactor|test-gen|test-fix|docs`)
|
||||
- `agent`: Assigned agent (`@code-developer|@test-fix-agent|@universal-executor`)
|
||||
- `execution_group`: Parallelization group ID or null
|
||||
- `context_signature`: Hash for context-based grouping
|
||||
|
||||
**Context Object**:
|
||||
- `requirements`: Quantified implementation requirements (with counts and explicit lists)
|
||||
- `focus_paths`: Target directories/files (absolute or relative paths)
|
||||
- `acceptance`: Measurable acceptance criteria (with verification commands)
|
||||
- `parent`: Parent task ID for subtasks
|
||||
- `depends_on`: Prerequisite task IDs
|
||||
- `inherited`: Shared patterns and dependencies from parent
|
||||
- `shared_context`: Tech stack and conventions
|
||||
- `artifacts`: Referenced brainstorm artifacts with paths, priority, and usage
|
||||
|
||||
**Flow Control Object**:
|
||||
- `pre_analysis`: Context loading and preparation steps
|
||||
- `load_context_package`: Load smart context and artifact catalog
|
||||
- `load_role_analysis_artifacts`: Load role analyses dynamically from context package
|
||||
- `load_planning_context`: Load finalized decisions with resolved conflicts
|
||||
- `codebase_exploration`: Discover existing patterns
|
||||
- `analyze_task_patterns`: Identify modification targets
|
||||
- `implementation_approach`: Execution steps
|
||||
- **Agent Mode**: Steps contain `modification_points` and `logic_flow` (agent executes autonomously)
|
||||
- **CLI Mode**: Steps include `command` field with CLI tool invocation
|
||||
- `target_files`: Specific files/functions/lines to modify
|
||||
|
||||
**Key Characteristics**:
|
||||
- **Quantification**: All requirements/acceptance use explicit counts and enumerations
|
||||
- **Mode Flexibility**: Supports both agent execution (default) and CLI tool execution (`--cli-execute`)
|
||||
- **Context Intelligence**: References context-package.json for smart context and artifact paths
|
||||
- **Artifact Integration**: Dynamically loads role analyses and brainstorm artifacts
|
||||
|
||||
**Example Task JSON**:
|
||||
```json
|
||||
{
|
||||
"id": "IMPL-N[.M]",
|
||||
"title": "Descriptive task name",
|
||||
"status": "pending|active|completed|blocked|container",
|
||||
"context_package_path": ".workflow/WFS-[session]/.process/context-package.json",
|
||||
"id": "IMPL-1",
|
||||
"title": "Implement feature X with Y components",
|
||||
"status": "pending",
|
||||
"context_package_path": ".workflow/WFS-session/.process/context-package.json",
|
||||
"meta": {
|
||||
"type": "feature|bugfix|refactor|test-gen|test-fix|docs",
|
||||
"agent": "@code-developer|@test-fix-agent|@universal-executor",
|
||||
"execution_group": "group-id|null",
|
||||
"context_signature": "hash-of-focus_paths-and-artifacts"
|
||||
"type": "feature",
|
||||
"agent": "@code-developer",
|
||||
"execution_group": "parallel-abc123",
|
||||
"context_signature": "hash-value"
|
||||
},
|
||||
"context": {
|
||||
"requirements": ["Clear requirement from analysis"],
|
||||
"focus_paths": ["D:\\project\\src\\module\\path", "./tests/module/path"],
|
||||
"acceptance": ["Measurable acceptance criterion"],
|
||||
"parent": "IMPL-N",
|
||||
"depends_on": ["IMPL-N.M"],
|
||||
"inherited": {"shared_patterns": [], "common_dependencies": []},
|
||||
"shared_context": {"tech_stack": [], "conventions": []},
|
||||
"requirements": [
|
||||
"Implement 5 commands: [cmd1, cmd2, cmd3, cmd4, cmd5]",
|
||||
"Create 3 directories: [dir1/, dir2/, dir3/]",
|
||||
"Modify 2 functions: [funcA() in file1.ts lines 10-25, funcB() in file2.ts lines 40-60]"
|
||||
],
|
||||
"focus_paths": ["D:\\project\\src\\module", "./tests/module"],
|
||||
"acceptance": [
|
||||
"5 command files created: verify by ls .claude/commands/*/*.md | wc -l = 5",
|
||||
"3 directories exist: verify by ls -d dir*/ | wc -l = 3",
|
||||
"All tests pass: pytest tests/ --cov=src/module (>=80% coverage)"
|
||||
],
|
||||
"depends_on": [],
|
||||
"artifacts": [
|
||||
{
|
||||
"path": "{{from context-package.json → brainstorm_artifacts.role_analyses[].files[].path}}",
|
||||
"path": ".workflow/WFS-session/.brainstorming/system-architect/analysis.md",
|
||||
"priority": "highest",
|
||||
"usage": "Role-specific requirements, design specs, enhanced by synthesis. Paths loaded dynamically from context-package.json (supports multiple files per role: analysis.md, analysis-01.md, analysis-api.md, etc.). Common roles: product-manager, system-architect, ui-designer, data-architect, ux-expert."
|
||||
},
|
||||
{
|
||||
"path": ".workflow/WFS-[session]/.brainstorming/guidance-specification.md",
|
||||
"priority": "high",
|
||||
"usage": "Finalized design decisions (potentially modified by conflict resolution if conflict_risk was medium/high). Use for: understanding resolved requirements, design choices, conflict resolutions applied in-place"
|
||||
"usage": "Architecture decisions and API specifications"
|
||||
}
|
||||
]
|
||||
},
|
||||
@@ -206,18 +301,14 @@ This enhanced 5-field schema embeds all necessary context, artifacts, and execut
|
||||
"pre_analysis": [
|
||||
{
|
||||
"step": "load_context_package",
|
||||
"action": "Load context package for artifact paths",
|
||||
"note": "Context package path is now at top-level field: context_package_path",
|
||||
"commands": [
|
||||
"Read({{context_package_path}})"
|
||||
],
|
||||
"action": "Load context package for artifact paths and smart context",
|
||||
"commands": ["Read({{context_package_path}})"],
|
||||
"output_to": "context_package",
|
||||
"on_error": "fail"
|
||||
},
|
||||
{
|
||||
"step": "load_role_analysis_artifacts",
|
||||
"action": "Load role analyses from context-package.json (supports multiple files per role)",
|
||||
"note": "Paths loaded from context-package.json → brainstorm_artifacts.role_analyses[]. Supports analysis*.md automatically.",
|
||||
"action": "Load role analyses from context-package.json",
|
||||
"commands": [
|
||||
"Read({{context_package_path}})",
|
||||
"Extract(brainstorm_artifacts.role_analyses[].files[].path)",
|
||||
@@ -225,73 +316,36 @@ This enhanced 5-field schema embeds all necessary context, artifacts, and execut
|
||||
],
|
||||
"output_to": "role_analysis_artifacts",
|
||||
"on_error": "skip_optional"
|
||||
},
|
||||
{
|
||||
"step": "load_planning_context",
|
||||
"action": "Load plan-generated context intelligence with resolved conflicts",
|
||||
"note": "CRITICAL: context-package.json (from context_package_path) provides smart context (focus paths, dependencies, patterns) and conflict resolution status. If conflict_risk was medium/high, conflicts have been resolved in guidance-specification.md and role analyses.",
|
||||
"commands": [
|
||||
"Read({{context_package_path}})",
|
||||
"Read(.workflow/WFS-[session]/.brainstorming/guidance-specification.md)"
|
||||
],
|
||||
"output_to": "planning_context",
|
||||
"on_error": "fail",
|
||||
"usage_guidance": {
|
||||
"context-package.json": "Use for focus_paths validation, dependency resolution, existing pattern discovery, module structure understanding, conflict_risk status (resolved/none/low)",
|
||||
"guidance-specification.md": "Use for finalized design decisions (includes applied conflict resolutions if any)"
|
||||
}
|
||||
},
|
||||
{
|
||||
"step": "codebase_exploration",
|
||||
"action": "Explore codebase using native tools",
|
||||
"command": "bash(find . -name \"[patterns]\" -type f && rg \"[patterns]\")",
|
||||
"output_to": "codebase_structure"
|
||||
},
|
||||
{
|
||||
"step": "analyze_task_patterns",
|
||||
"action": "Analyze existing code patterns and identify modification targets",
|
||||
"commands": [
|
||||
"bash(cd \"[focus_paths]\")",
|
||||
"bash(gemini \"PURPOSE: Identify modification targets TASK: Analyze '[title]' and locate specific files/functions/lines to modify CONTEXT: [role_analyses] [individual_artifacts] EXPECTED: Code locations in format 'file:function:lines' RULES: Consult role analyses for requirements, identify exact modification points\")"
|
||||
],
|
||||
"output_to": "task_context_with_targets",
|
||||
"on_error": "fail"
|
||||
}
|
||||
],
|
||||
"implementation_approach": [
|
||||
{
|
||||
"step": 1,
|
||||
"title": "Implement task following role analyses and context",
|
||||
"description": "Implement '[title]' following this priority: 1) role analysis.md files (requirements, design specs, enhancements from synthesis), 2) guidance-specification.md (finalized decisions with resolved conflicts), 3) context-package.json (smart context, focus paths, patterns). Role analyses are enhanced by synthesis phase with concept improvements and clarifications. If conflict_risk was medium/high, conflict resolutions are already applied in-place.",
|
||||
"title": "Implement feature following role analyses",
|
||||
"description": "Implement feature X using requirements from role analyses and context package",
|
||||
"modification_points": [
|
||||
"Apply requirements and design specs from role analysis documents",
|
||||
"Use enhancements and clarifications from synthesis phase",
|
||||
"Use finalized decisions from guidance-specification.md (includes resolved conflicts)",
|
||||
"Use context-package.json for focus paths and dependency resolution",
|
||||
"Consult specific role artifacts for implementation details when needed",
|
||||
"Integrate with existing patterns"
|
||||
"Create 5 command files: [cmd1.md, cmd2.md, cmd3.md, cmd4.md, cmd5.md]",
|
||||
"Modify funcA() in file1.ts lines 10-25: add validation logic",
|
||||
"Modify funcB() in file2.ts lines 40-60: integrate with new API"
|
||||
],
|
||||
"logic_flow": [
|
||||
"Load role analyses (requirements, design, enhancements from synthesis)",
|
||||
"Load guidance-specification.md (finalized decisions with resolved conflicts if any)",
|
||||
"Load context-package.json (smart context: focus paths, dependencies, patterns, conflict_risk status)",
|
||||
"Extract requirements and design decisions from role documents",
|
||||
"Review synthesis enhancements and clarifications",
|
||||
"Use finalized decisions (conflicts already resolved if applicable)",
|
||||
"Identify modification targets using context package",
|
||||
"Implement following role requirements and design specs",
|
||||
"Consult role artifacts for detailed specifications when needed",
|
||||
"Load role analyses and context package",
|
||||
"Extract requirements and design decisions",
|
||||
"Implement commands following existing patterns",
|
||||
"Update functions with new logic",
|
||||
"Validate against acceptance criteria"
|
||||
],
|
||||
"depends_on": [],
|
||||
"output": "implementation"
|
||||
}
|
||||
],
|
||||
"target_files": ["file:function:lines"]
|
||||
"target_files": ["file1.ts:funcA:10-25", "file2.ts:funcB:40-60"]
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
**Note**: In CLI Execute Mode (`--cli-execute`), `implementation_approach` steps include a `command` field with the CLI tool invocation (e.g., `bash(codex ...)`).
|
||||
|
||||
### 6.2. IMPL_PLAN.md Structure
|
||||
This document provides a high-level overview of the entire implementation plan.
|
||||
|
||||
@@ -585,194 +639,7 @@ Artifacts are mapped to tasks based on their relevance to the task's domain.
|
||||
|
||||
This ensures that each task has access to the most relevant and detailed specifications from role-specific analyses.
|
||||
|
||||
## 8. CLI Execute Mode Details
|
||||
When using `--cli-execute`, each step in `implementation_approach` includes a `command` field with the execution command.
|
||||
|
||||
**Key Points**:
|
||||
- **Sequential Steps**: Steps execute in order defined in `implementation_approach` array
|
||||
- **Context Delivery**: Each codex command receives context via CONTEXT field: `@{context_package_path}` (role analyses loaded dynamically from context package)- **Multi-Step Tasks**: First step provides full context, subsequent steps use `resume --last` to maintain session continuity
|
||||
- **Step Dependencies**: Later steps reference outputs from earlier steps via `depends_on` field
|
||||
|
||||
### Example 1: Agent Mode - Simple Task (Default, No Command)
|
||||
```json
|
||||
{
|
||||
"id": "IMPL-001",
|
||||
"title": "Implement user authentication module",
|
||||
"context_package_path": ".workflow/WFS-session/.process/context-package.json",
|
||||
"context": {
|
||||
"depends_on": [],
|
||||
"focus_paths": ["src/auth"],
|
||||
"requirements": ["JWT-based authentication", "Login and registration endpoints"],
|
||||
"acceptance": [
|
||||
"JWT token generation working",
|
||||
"Login and registration endpoints implemented",
|
||||
"Tests passing with >70% coverage"
|
||||
]
|
||||
},
|
||||
"flow_control": {
|
||||
"pre_analysis": [
|
||||
{
|
||||
"step": "load_role_analyses",
|
||||
"action": "Load role analyses from context-package.json",
|
||||
"commands": [
|
||||
"Read({{context_package_path}})",
|
||||
"Extract(brainstorm_artifacts.role_analyses[].files[].path)",
|
||||
"Read(each extracted path)"
|
||||
],
|
||||
"output_to": "role_analyses",
|
||||
"on_error": "fail"
|
||||
},
|
||||
{
|
||||
"step": "load_context",
|
||||
"action": "Load context package for project structure",
|
||||
"commands": ["Read({{context_package_path}})"],
|
||||
"output_to": "context_pkg",
|
||||
"on_error": "fail"
|
||||
}
|
||||
],
|
||||
"implementation_approach": [
|
||||
{
|
||||
"step": 1,
|
||||
"title": "Implement JWT-based authentication",
|
||||
"description": "Create authentication module using JWT following [role_analyses] requirements and [context_pkg] patterns",
|
||||
"modification_points": [
|
||||
"Create auth service with JWT generation",
|
||||
"Implement login endpoint with credential validation",
|
||||
"Implement registration endpoint with user creation",
|
||||
"Add JWT middleware for route protection"
|
||||
],
|
||||
"logic_flow": [
|
||||
"User registers → validate input → hash password → create user",
|
||||
"User logs in → validate credentials → generate JWT → return token",
|
||||
"Protected routes → validate JWT → extract user → allow access"
|
||||
],
|
||||
"depends_on": [],
|
||||
"output": "auth_implementation"
|
||||
}
|
||||
],
|
||||
"target_files": ["src/auth/service.ts", "src/auth/middleware.ts", "src/routes/auth.ts"]
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### Example 2: CLI Execute Mode - Single Codex Step
|
||||
```json
|
||||
{
|
||||
"id": "IMPL-002",
|
||||
"title": "Implement user authentication module",
|
||||
"context_package_path": ".workflow/WFS-session/.process/context-package.json",
|
||||
"context": {
|
||||
"depends_on": [],
|
||||
"focus_paths": ["src/auth"],
|
||||
"requirements": ["JWT-based authentication", "Login and registration endpoints"],
|
||||
"acceptance": ["JWT generation working", "Endpoints implemented", "Tests passing"]
|
||||
},
|
||||
"flow_control": {
|
||||
"pre_analysis": [
|
||||
{
|
||||
"step": "load_role_analyses",
|
||||
"action": "Load role analyses from context-package.json",
|
||||
"commands": [
|
||||
"Read({{context_package_path}})",
|
||||
"Extract(brainstorm_artifacts.role_analyses[].files[].path)",
|
||||
"Read(each extracted path)"
|
||||
],
|
||||
"output_to": "role_analyses",
|
||||
"on_error": "fail"
|
||||
}
|
||||
],
|
||||
"implementation_approach": [
|
||||
{
|
||||
"step": 1,
|
||||
"title": "Implement authentication with Codex",
|
||||
"description": "Create JWT-based authentication module",
|
||||
"command": "bash(codex -C src/auth --full-auto exec \"PURPOSE: Implement user authentication TASK: JWT-based auth with login/registration MODE: auto CONTEXT: @{{context_package_path}} EXPECTED: Complete auth module with tests RULES: Load role analyses from context-package.json → brainstorm_artifacts\" --skip-git-repo-check -s danger-full-access)",
|
||||
"modification_points": ["Create auth service", "Implement endpoints", "Add JWT middleware"],
|
||||
"logic_flow": ["Validate credentials", "Generate JWT", "Return token"],
|
||||
"depends_on": [],
|
||||
"output": "auth_implementation"
|
||||
}
|
||||
],
|
||||
"target_files": ["src/auth/service.ts", "src/auth/middleware.ts"]
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### Example 3: CLI Execute Mode - Multi-Step with Resume
|
||||
```json
|
||||
{
|
||||
"id": "IMPL-003",
|
||||
"title": "Implement role-based access control",
|
||||
"context_package_path": ".workflow/WFS-session/.process/context-package.json",
|
||||
"context": {
|
||||
"depends_on": ["IMPL-002"],
|
||||
"focus_paths": ["src/auth", "src/middleware"],
|
||||
"requirements": ["User roles and permissions", "Route protection middleware"],
|
||||
"acceptance": ["RBAC models created", "Middleware working", "Management API complete"]
|
||||
},
|
||||
"flow_control": {
|
||||
"pre_analysis": [
|
||||
{
|
||||
"step": "load_context",
|
||||
"action": "Load context and role analyses from context-package.json",
|
||||
"commands": [
|
||||
"Read({{context_package_path}})",
|
||||
"Extract(brainstorm_artifacts.role_analyses[].files[].path)",
|
||||
"Read(each extracted path)"
|
||||
],
|
||||
"output_to": "full_context",
|
||||
"on_error": "fail"
|
||||
}
|
||||
],
|
||||
"implementation_approach": [
|
||||
{
|
||||
"step": 1,
|
||||
"title": "Create RBAC models",
|
||||
"description": "Define role and permission data models",
|
||||
"command": "bash(codex -C src/auth --full-auto exec \"PURPOSE: Create RBAC models TASK: Role and permission models MODE: auto CONTEXT: @{{context_package_path}} EXPECTED: Models with migrations RULES: Load role analyses from context-package.json → brainstorm_artifacts\" --skip-git-repo-check -s danger-full-access)",
|
||||
"modification_points": ["Define role model", "Define permission model", "Create migrations"],
|
||||
"logic_flow": ["Design schema", "Implement models", "Generate migrations"],
|
||||
"depends_on": [],
|
||||
"output": "rbac_models"
|
||||
},
|
||||
{
|
||||
"step": 2,
|
||||
"title": "Implement RBAC middleware",
|
||||
"description": "Create route protection middleware using models from step 1",
|
||||
"command": "bash(codex --full-auto exec \"PURPOSE: Create RBAC middleware TASK: Route protection middleware MODE: auto CONTEXT: RBAC models from step 1 EXPECTED: Middleware for route protection RULES: Use session patterns\" resume --last --skip-git-repo-check -s danger-full-access)",
|
||||
"modification_points": ["Create permission checker", "Add route decorators", "Integrate with auth"],
|
||||
"logic_flow": ["Check user role", "Validate permissions", "Allow/deny access"],
|
||||
"depends_on": [1],
|
||||
"output": "rbac_middleware"
|
||||
},
|
||||
{
|
||||
"step": 3,
|
||||
"title": "Add role management API",
|
||||
"description": "Create CRUD endpoints for roles and permissions",
|
||||
"command": "bash(codex --full-auto exec \"PURPOSE: Role management API TASK: CRUD endpoints for roles/permissions MODE: auto CONTEXT: Models and middleware from previous steps EXPECTED: Complete API with validation RULES: Maintain consistency\" resume --last --skip-git-repo-check -s danger-full-access)",
|
||||
"modification_points": ["Create role endpoints", "Create permission endpoints", "Add validation"],
|
||||
"logic_flow": ["Define routes", "Implement controllers", "Add authorization"],
|
||||
"depends_on": [2],
|
||||
"output": "role_management_api"
|
||||
}
|
||||
],
|
||||
"target_files": [
|
||||
"src/models/Role.ts",
|
||||
"src/models/Permission.ts",
|
||||
"src/middleware/rbac.ts",
|
||||
"src/routes/roles.ts"
|
||||
]
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
**Pattern Summary**:
|
||||
- **Agent Mode (Example 1)**: No `command` field - agent executes via `modification_points` and `logic_flow`
|
||||
- **CLI Mode Single-Step (Example 2)**: One `command` field with full context package
|
||||
- **CLI Mode Multi-Step (Example 3)**: First step uses full context, subsequent steps use `resume --last`
|
||||
- **Context Delivery**: Context package provided via `@{...}` references in CONTEXT field
|
||||
|
||||
## 9. Error Handling
|
||||
## 8. Error Handling
|
||||
|
||||
### Input Validation Errors
|
||||
| Error | Cause | Resolution |
|
||||
@@ -795,21 +662,19 @@ When using `--cli-execute`, each step in `implementation_approach` includes a `c
|
||||
| Invalid format | Corrupted file | Skip artifact loading |
|
||||
| Path invalid | Moved/deleted | Update references |
|
||||
|
||||
## 10. Integration & Usage
|
||||
## 10. Usage & Related Commands
|
||||
|
||||
### Command Chain
|
||||
- **Called By**: `/workflow:plan` (Phase 4)
|
||||
- **Calls**: None (terminal command)
|
||||
- **Followed By**: `/workflow:execute`, `/workflow:status`
|
||||
|
||||
### Basic Usage
|
||||
**Basic Usage**:
|
||||
```bash
|
||||
/workflow:tools:task-generate --session WFS-auth
|
||||
/workflow:tools:task-generate --session WFS-auth [--cli-execute]
|
||||
```
|
||||
|
||||
## 11. Related Commands
|
||||
- `/workflow:plan` - Orchestrates entire planning
|
||||
- `/workflow:plan --cli-execute` - Planning with CLI execution mode
|
||||
- `/workflow:tools:context-gather` - Provides context package
|
||||
- `/workflow:tools:conflict-resolution` - Provides conflict resolution strategies (optional)
|
||||
**Workflow Integration**:
|
||||
- Called by: `/workflow:plan` (task generation phase)
|
||||
- Followed by: `/workflow:execute`, `/workflow:status`
|
||||
|
||||
**Related Commands**:
|
||||
- `/workflow:plan` - Orchestrates entire planning workflow
|
||||
- `/workflow:tools:context-gather` - Provides context package input
|
||||
- `/workflow:tools:conflict-resolution` - Provides conflict resolution (if needed)
|
||||
- `/workflow:execute` - Executes generated tasks
|
||||
|
||||
@@ -91,16 +91,23 @@ Comprehensive command guide for Claude DMS3 workflow system covering 69 commands
|
||||
|
||||
**When**: New user needs guidance
|
||||
|
||||
**Triggers**: "新手", "getting started", "如何开始", "常用命令"
|
||||
**Triggers**: "新手", "getting started", "如何开始", "常用命令", **"从0到1"**, **"全新项目"**
|
||||
|
||||
**Process**:
|
||||
1. **Assess user background** - Ask clarifying questions if needed (coding experience? project type?)
|
||||
2. **Design personalized learning path** based on their goals
|
||||
3. **Curate essential commands** from `index/essential-commands.json` - Select 3-5 most relevant for their use case
|
||||
4. **Provide guided first example** - Walk through ONE complete workflow with explanation
|
||||
5. **Set clear next steps** - What to try next, where to get help
|
||||
2. **⚠️ Identify project stage** - FROM-ZERO-TO-ONE vs FEATURE-ADDITION:
|
||||
- **从0到1场景** (全新项目/产品/架构决策) → **MUST START with brainstorming workflow**
|
||||
- **功能新增场景** (已有项目中添加功能) → Start with planning workflow
|
||||
3. **Design personalized learning path** based on their goals and stage
|
||||
4. **Curate essential commands** from `index/essential-commands.json` - Select 3-5 most relevant for their use case
|
||||
5. **Provide guided first example** - Walk through ONE complete workflow with explanation, **emphasizing brainstorming for 0-to-1 scenarios**
|
||||
6. **Set clear next steps** - What to try next, where to get help
|
||||
|
||||
**Example**: "我是新手，如何开始？" → Detect if they have a specific task OR just exploring → For specific task: provide laser-focused 3-step guide; For exploring: progressive learning path starting with simplest workflow, NOT overwhelming 14-command list
|
||||
**Example 1 (从0到1)**: "我是新手，如何开始全新项目？" → Identify as FROM-ZERO-TO-ONE → Emphasize brainstorming workflow (`/workflow:brainstorm:artifacts`) as mandatory first step → Explain brainstorm → plan → execute flow
|
||||
|
||||
**Example 2 (功能新增)**: "我是新手，如何在已有项目中添加功能？" → Identify as FEATURE-ADDITION → Guide to planning workflow (`/workflow:plan`) → Explain plan → execute → test flow
|
||||
|
||||
**Example 3 (探索)**: "我是新手，如何开始？" → Ask clarifying question: "是全新项目启动（从0到1）还是在已有项目中添加功能？" → Based on answer, route to appropriate workflow
|
||||
|
||||
---
|
||||
|
||||
|
||||
@@ -14,6 +14,173 @@
|
||||
|
||||
---
|
||||
|
||||
## 💡 Pattern 0: 头脑风暴（从0到1的第一步）
|
||||
|
||||
**⚠️ 重要**：这是**从0到1开发的起点**！在开始编码之前，通过多角色头脑风暴明确需求、技术选型和架构决策。
|
||||
|
||||
**适用场景**：
|
||||
- 全新项目启动，需求和技术方案不明确
|
||||
- 重大功能开发，涉及多个技术领域和权衡
|
||||
- 架构决策，需要多角色视角分析
|
||||
|
||||
**流程**：话题分析 → 角色选择 → 角色问答 → 冲突解决 → 生成指导文档
|
||||
|
||||
### 模式 A：交互式头脑风暴（推荐）
|
||||
|
||||
**特点**：通过问答交互，逐步明确需求和决策
|
||||
|
||||
```bash
|
||||
# 步骤 1：启动头脑风暴
|
||||
/workflow:brainstorm:artifacts "
|
||||
GOAL: 实现实时协作编辑平台
|
||||
SCOPE: 支持100+用户同时在线，低延迟(<100ms)，冲突自动解决
|
||||
CONTEXT: MVP阶段，3个月上线，团队5人（2前端+2后端+1全栈）
|
||||
" --count 3
|
||||
|
||||
# 系统输出 Phase 0：自动收集项目上下文
|
||||
# ✅ 分析现有代码库结构
|
||||
# ✅ 加载相关文档
|
||||
# ✅ 识别技术栈和依赖
|
||||
|
||||
# 系统输出 Phase 1：意图分析（2-4个问题）
|
||||
# 【问题1 - 核心挑战】实时协作的主要技术挑战？
|
||||
# a) 实时数据同步
|
||||
# b) 可扩展性架构
|
||||
# c) 冲突解决机制
|
||||
# 【问题2 - 优先级】MVP阶段最关注？
|
||||
# a) 功能完整性
|
||||
# b) 用户体验
|
||||
# c) 系统稳定性
|
||||
# 请回答 (格式: 1a 2c)：
|
||||
|
||||
# 用户输入：1c 2b
|
||||
|
||||
# 系统输出 Phase 2：角色选择（推荐 count+2 个角色）
|
||||
# 【角色选择】请选择 3 个角色参与头脑风暴
|
||||
# a) system-architect (系统架构师) - 实时同步架构设计
|
||||
# b) ui-designer (UI设计师) - 协作界面用户体验
|
||||
# c) product-manager (产品经理) - 功能优先级决策
|
||||
# d) data-architect (数据架构师) - 数据同步模型设计
|
||||
# e) ux-expert (UX专家) - 多用户协作交互流程
|
||||
# 请输入选择 (格式: 2acd 或 2a 2c 2d)：
|
||||
|
||||
# 用户输入：2acd
|
||||
|
||||
# 系统输出 Phase 3：角色问题（每个角色 3-4 个问题）
|
||||
# ===== system-architect 问题 =====
|
||||
# 【问题1】100+ 用户实时状态同步方案？
|
||||
# a) Event Sourcing - 完整事件历史，易于回溯
|
||||
# b) 集中式状态管理 - 简单直接，适合MVP
|
||||
# c) CRDT - 自动冲突解决，分布式友好
|
||||
# 【问题2】低延迟通信协议选择？
|
||||
# ...
|
||||
# 请回答：
|
||||
|
||||
# 用户输入：1c 2a 3b 4c
|
||||
|
||||
# 系统输出 Phase 4：冲突检测和解决
|
||||
# 【冲突1】CRDT 与 UI 回滚期望冲突
|
||||
# Background: system-architect 选择 CRDT，但 ui-designer 期望回滚UI
|
||||
# a) 采用 CRDT，显示合并状态
|
||||
# b) 切换到 OT 算法支持回滚
|
||||
# c) 混合方案：CRDT + 本地撤销栈
|
||||
# ...
|
||||
|
||||
# 系统输出 Phase 5：生成指导文档
|
||||
# ✅ 生成 guidance-specification.md
|
||||
# ✅ 记录所有决策和理由
|
||||
# ✅ 标注冲突解决方案
|
||||
# 📁 文件位置：.workflow/WFS-realtime-collab/.brainstorming/guidance-specification.md
|
||||
|
||||
# 步骤 2：查看生成的指导文档
|
||||
cat .workflow/WFS-*//.brainstorming/guidance-specification.md
|
||||
```
|
||||
|
||||
### 模式 B：自动并行头脑风暴（快速）
|
||||
|
||||
**特点**：自动选择角色，并行执行，快速生成多角色分析
|
||||
|
||||
```bash
|
||||
# 步骤 1：一键启动并行头脑风暴
|
||||
/workflow:brainstorm:auto-parallel "
|
||||
GOAL: 实现支付处理模块
|
||||
SCOPE: 支持微信/支付宝/银行卡，日交易10万笔，99.99%可用性
|
||||
CONTEXT: 金融合规要求，PCI DSS认证，风控系统集成
|
||||
" --count 4
|
||||
|
||||
# 系统输出：
|
||||
# ✅ Phase 0: 收集项目上下文
|
||||
# ✅ Phase 1-2: artifacts 交互式框架生成
|
||||
# ⏳ Phase 3: 4个角色并行分析
|
||||
# - system-architect → 分析中...
|
||||
# - data-architect → 分析中...
|
||||
# - product-manager → 分析中...
|
||||
# - subject-matter-expert → 分析中...
|
||||
# ✅ Phase 4: synthesis 综合分析
|
||||
# 📁 输出文件：
|
||||
# - .brainstorming/guidance-specification.md (框架)
|
||||
# - system-architect/analysis.md
|
||||
# - data-architect/analysis.md
|
||||
# - product-manager/analysis.md
|
||||
# - subject-matter-expert/analysis.md
|
||||
# - synthesis/final-recommendations.md
|
||||
|
||||
# 步骤 2：查看综合建议
|
||||
cat .workflow/WFS-*//.brainstorming/synthesis/final-recommendations.md
|
||||
```
|
||||
|
||||
### 模式 C：单角色深度分析（特定领域）
|
||||
|
||||
**特点**：针对特定领域问题，调用单个角色深度分析
|
||||
|
||||
```bash
|
||||
# 系统架构分析
|
||||
/workflow:brainstorm:system-architect "API 网关架构设计，支持10万QPS，微服务集成"
|
||||
|
||||
# UI 设计分析
|
||||
/workflow:brainstorm:ui-designer "管理后台界面设计，复杂数据展示，操作效率优先"
|
||||
|
||||
# 数据架构分析
|
||||
/workflow:brainstorm:data-architect "分布式数据存储方案，MySQL+Redis+ES 组合"
|
||||
```
|
||||
|
||||
### 关键点
|
||||
|
||||
1. **Phase 0 自动上下文收集**：
|
||||
- 自动分析现有代码库、文档、技术栈
|
||||
- 识别潜在冲突和集成点
|
||||
- 为后续问题生成提供上下文
|
||||
|
||||
2. **动态问题生成**：
|
||||
- 基于话题关键词和项目上下文生成问题
|
||||
- 不使用预定义模板
|
||||
- 问题直接针对你的具体场景
|
||||
|
||||
3. **智能角色推荐**：
|
||||
- 基于话题分析推荐最相关的角色
|
||||
- 推荐 count+2 个角色供选择
|
||||
- 每个角色都有基于话题的推荐理由
|
||||
|
||||
4. **输出物**：
|
||||
- `guidance-specification.md` - 确认的指导规范（决策、理由、集成点）
|
||||
- `{role}/analysis.md` - 各角色详细分析（仅 auto-parallel 模式）
|
||||
- `synthesis/final-recommendations.md` - 综合建议（仅 auto-parallel 模式）
|
||||
|
||||
5. **下一步**：
|
||||
- 头脑风暴完成后，使用 `/workflow:plan` 基于指导文档生成实施计划
|
||||
- 指导文档作为规划和实现的权威参考
|
||||
|
||||
### 使用场景对比
|
||||
|
||||
| 场景 | 推荐模式 | 原因 |
|
||||
|------|---------|------|
|
||||
| 全新项目启动 | 交互式 (artifacts) | 需要充分澄清需求和约束 |
|
||||
| 重大架构决策 | 交互式 (artifacts) | 需要深入讨论权衡 |
|
||||
| 快速原型验证 | 自动并行 (auto-parallel) | 快速获得多角色建议 |
|
||||
| 特定技术问题 | 单角色 (specific role) | 专注某个领域深度分析 |
|
||||
|
||||
---
|
||||
|
||||
## 📋 Pattern 1: 规划→执行（最常用）
|
||||
|
||||
**适用场景**：实现新功能、新模块
|
||||
@@ -389,29 +556,44 @@
|
||||
|
||||
## 📊 工作流选择指南
|
||||
|
||||
**核心区分**：从0到1 vs 功能新增
|
||||
- **从0到1**：全新项目、新产品、重大架构决策 → **必须头脑风暴**
|
||||
- **功能新增**：已有项目中添加功能 → **可直接规划**
|
||||
|
||||
```mermaid
|
||||
graph TD
|
||||
A[我要做什么?] --> B{任务类型?}
|
||||
A[我要做什么?] --> B{项目阶段?}
|
||||
|
||||
B -->|新功能| C[规划→执行]
|
||||
B -->|需要测试| D{代码是否存在?}
|
||||
B -->|UI开发| E[UI设计工作流]
|
||||
B -->|代码优化| F[分析→重构]
|
||||
B -->|生成文档| G[文档生成]
|
||||
B -->|快速实现| H[Codex YOLO]
|
||||
B -->|从0到1<br/>全新项目/产品| Z[💡头脑风暴<br/>必经阶段]
|
||||
B -->|功能新增<br/>已有项目| C{任务类型?}
|
||||
|
||||
D -->|不存在| I[TDD工作流]
|
||||
D -->|已存在| J[测试生成]
|
||||
Z --> Z1[/workflow:brainstorm:artifacts<br/>或<br/>/workflow:brainstorm:auto-parallel]
|
||||
Z1 --> Z2[⬇️ 生成指导文档]
|
||||
Z2 --> C
|
||||
|
||||
C --> K[/workflow:plan<br/>↓<br/>/workflow:execute]
|
||||
I --> L[/workflow:tdd-plan<br/>↓<br/>/workflow:execute]
|
||||
J --> M[/workflow:test-gen<br/>↓<br/>/workflow:test-cycle-execute]
|
||||
E --> N[/workflow:ui-design:*]
|
||||
F --> O[/cli:analyze<br/>↓<br/>/cli:mode:plan<br/>↓<br/>/cli:execute]
|
||||
G --> P[/memory:docs]
|
||||
H --> Q[/cli:codex-execute]
|
||||
C -->|新功能| D[规划→执行]
|
||||
C -->|需要测试| E{代码是否存在?}
|
||||
C -->|UI开发| F[UI设计工作流]
|
||||
C -->|代码优化| G[分析→重构]
|
||||
C -->|生成文档| H[文档生成]
|
||||
C -->|快速实现| I[Codex YOLO]
|
||||
|
||||
E -->|不存在| J[TDD工作流]
|
||||
E -->|已存在| K[测试生成]
|
||||
|
||||
D --> L[/workflow:plan<br/>↓<br/>/workflow:execute]
|
||||
J --> M[/workflow:tdd-plan<br/>↓<br/>/workflow:execute]
|
||||
K --> N[/workflow:test-gen<br/>↓<br/>/workflow:test-cycle-execute]
|
||||
F --> O[/workflow:ui-design:*]
|
||||
G --> P[/cli:analyze<br/>↓<br/>/cli:mode:plan<br/>↓<br/>/cli:execute]
|
||||
H --> Q[/memory:docs]
|
||||
I --> R[/cli:codex-execute]
|
||||
```
|
||||
|
||||
**说明**：
|
||||
- **从0到1场景**：创业项目、新产品线、系统重构 → 头脑风暴明确方向后再规划
|
||||
- **功能新增场景**：现有系统添加模块、优化现有功能 → 直接进入规划或分析
|
||||
|
||||
---
|
||||
|
||||
## 💡 最佳实践
|
||||
@@ -447,79 +629,24 @@ graph TD
|
||||
|
||||
### ❌ 避免做法
|
||||
|
||||
1. **不要跳过规划直接执行复杂任务**
|
||||
1. **⚠️ 不要在从0到1场景跳过头脑风暴**
|
||||
- ❌ 全新项目直接 `/workflow:plan`
|
||||
- ✅ 先 `/workflow:brainstorm:artifacts` 明确方向再规划
|
||||
|
||||
2. **不要跳过规划直接执行复杂任务**
|
||||
- ❌ 直接 `/cli:execute` 实现复杂功能
|
||||
- ✅ 先 `/workflow:plan` 再 `/workflow:execute`
|
||||
|
||||
2. **不要忽略测试**
|
||||
3. **不要忽略测试**
|
||||
- ❌ 实现完成后不生成测试
|
||||
- ✅ 使用 `/workflow:test-gen` 生成测试
|
||||
|
||||
3. **不要遗忘文档**
|
||||
4. **不要遗忘文档**
|
||||
- ❌ 代码实现后忘记更新文档
|
||||
- ✅ 使用 `/memory:update-related` 自动更新
|
||||
|
||||
---
|
||||
|
||||
## 🎨 Pattern 7: UI设计工作流
|
||||
|
||||
**适用场景**：前端UI设计和原型开发
|
||||
|
||||
**流程**：探索设计 / 模仿设计 / 代码导入 → 生成原型 → 集成
|
||||
|
||||
### 三种子模式
|
||||
|
||||
#### 7.1 探索式设计（新概念）
|
||||
|
||||
```bash
|
||||
# 从提示词创建多个设计方案
|
||||
/workflow:ui-design:explore-auto \
|
||||
--prompt "现代化SaaS着陆页，包含英雄区、特性、定价" \
|
||||
--style-variants 3 \
|
||||
--layout-variants 2
|
||||
|
||||
# 输出：
|
||||
# - 3个风格变体 × 2个布局变体 = 6个原型
|
||||
# - design-tokens-v1/v2/v3.json
|
||||
# - layout-templates-v1/v2.json
|
||||
# - compare.html（对比页面）
|
||||
```
|
||||
|
||||
#### 7.2 模仿式设计（复制现有网站）
|
||||
|
||||
```bash
|
||||
# 高保真克隆目标网站
|
||||
/workflow:ui-design:imitate-auto \
|
||||
--url-map "首页:https://example.com, 定价:https://example.com/pricing"
|
||||
|
||||
# 输出：
|
||||
# - 统一的设计系统（design-tokens.json）
|
||||
# - 页面结构（layout-templates.json）
|
||||
# - 重建的HTML原型
|
||||
```
|
||||
|
||||
#### 7.3 代码优先导入
|
||||
|
||||
```bash
|
||||
# 从现有代码库提取设计系统
|
||||
/workflow:ui-design:import-from-code \
|
||||
--base-path ./src/components
|
||||
|
||||
# 输出：
|
||||
# - 提取的设计令牌
|
||||
# - 完整性报告
|
||||
# - 改进建议
|
||||
```
|
||||
|
||||
**关键概念**：
|
||||
- **关注点分离**：样式（design-tokens）、结构（layout-templates）、动画（animation-tokens）独立
|
||||
- **令牌优先**：使用CSS变量而非硬编码
|
||||
- **可重用性**：设计系统可跨项目复用
|
||||
|
||||
**详细指南**：参见 [UI Design Workflow Guide](ui-design-workflow-guide.md)
|
||||
|
||||
---
|
||||
|
||||
## 🔗 相关资源
|
||||
|
||||
- **快速入门**：[Getting Started](getting-started.md) - 5分钟上手
|
||||
|
||||
Reference in New Issue
Block a user