mirror of
https://github.com/catlog22/Claude-Code-Workflow.git
synced 2026-02-05 01:50:27 +08:00
feat: enhance workflow with CCW-aware IMPL_PLAN.md templates
- Add concept-verify and action-plan-verify quality gate commands - Enhance IMPL_PLAN.md with CCW Workflow Context section - Add Artifact Usage Strategy for clear CCW artifact hierarchy - Update frontmatter with context_package, verification_history, phase_progression - Synchronize enhancements across task-generate, task-generate-agent, task-generate-tdd - Update synthesis, plan, and tdd-plan commands with verification guidance Makes CCW's multi-phase workflow and intelligent context gathering visible in generated documentation. 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude <noreply@anthropic.com>
This commit is contained in:
catlog22
421
.claude/commands/workflow/action-plan-verify.md
Normal file
421
.claude/commands/workflow/action-plan-verify.md
Normal file
@@ -0,0 +1,421 @@
|
||||
---
|
||||
name: action-plan-verify
|
||||
description: Perform non-destructive cross-artifact consistency and quality analysis of IMPL_PLAN.md and task.json before execution
|
||||
usage: /workflow:action-plan-verify [--session <session-id>]
|
||||
argument-hint: "optional: --session <session-id>"
|
||||
examples:
|
||||
- /workflow:action-plan-verify
|
||||
- /workflow:action-plan-verify --session WFS-auth
|
||||
allowed-tools: Read(*), TodoWrite(*), Glob(*), Bash(*)
|
||||
---
|
||||
|
||||
## User Input
|
||||
|
||||
```text
|
||||
$ARGUMENTS
|
||||
```
|
||||
|
||||
You **MUST** consider the user input before proceeding (if not empty).
|
||||
|
||||
## Goal
|
||||
|
||||
Identify inconsistencies, duplications, ambiguities, and underspecified items between action planning artifacts (`IMPL_PLAN.md`, `task.json`) and brainstorming artifacts (`synthesis-specification.md`) before implementation. This command MUST run only after `/workflow:plan` has successfully produced complete `IMPL_PLAN.md` and task JSON files.
|
||||
|
||||
## Operating Constraints
|
||||
|
||||
**STRICTLY READ-ONLY**: Do **not** modify any files. Output a structured analysis report. Offer an optional remediation plan (user must explicitly approve before any follow-up editing commands).
|
||||
|
||||
**Synthesis Authority**: The `synthesis-specification.md` is **authoritative** for requirements and design decisions. Any conflicts between IMPL_PLAN/tasks and synthesis are automatically CRITICAL and require adjustment of the plan/tasks—not reinterpretation of requirements.
|
||||
|
||||
## Execution Steps
|
||||
|
||||
### 1. Initialize Analysis Context
|
||||
|
||||
```bash
|
||||
# Detect active workflow session
|
||||
IF --session parameter provided:
|
||||
session_id = provided session
|
||||
ELSE:
|
||||
CHECK: .workflow/.active-* marker files
|
||||
IF active_session EXISTS:
|
||||
session_id = get_active_session()
|
||||
ELSE:
|
||||
ERROR: "No active workflow session found. Use --session <session-id>"
|
||||
EXIT
|
||||
|
||||
# Derive absolute paths
|
||||
session_dir = .workflow/WFS-{session}
|
||||
brainstorm_dir = session_dir/.brainstorming
|
||||
task_dir = session_dir/.task
|
||||
|
||||
# Validate required artifacts
|
||||
SYNTHESIS = brainstorm_dir/synthesis-specification.md
|
||||
IMPL_PLAN = session_dir/IMPL_PLAN.md
|
||||
TASK_FILES = Glob(task_dir/*.json)
|
||||
|
||||
# Abort if missing
|
||||
IF NOT EXISTS(SYNTHESIS):
|
||||
ERROR: "synthesis-specification.md not found. Run /workflow:brainstorm:synthesis first"
|
||||
EXIT
|
||||
|
||||
IF NOT EXISTS(IMPL_PLAN):
|
||||
ERROR: "IMPL_PLAN.md not found. Run /workflow:plan first"
|
||||
EXIT
|
||||
|
||||
IF TASK_FILES.count == 0:
|
||||
ERROR: "No task JSON files found. Run /workflow:plan first"
|
||||
EXIT
|
||||
```
|
||||
|
||||
### 2. Load Artifacts (Progressive Disclosure)
|
||||
|
||||
Load only minimal necessary context from each artifact:
|
||||
|
||||
**From synthesis-specification.md**:
|
||||
- Functional Requirements (IDs, descriptions, acceptance criteria)
|
||||
- Non-Functional Requirements (IDs, targets)
|
||||
- Business Requirements (IDs, success metrics)
|
||||
- Key Architecture Decisions
|
||||
- Risk factors and mitigation strategies
|
||||
- Implementation Roadmap (high-level phases)
|
||||
|
||||
**From IMPL_PLAN.md**:
|
||||
- Summary and objectives
|
||||
- Context Analysis
|
||||
- Implementation Strategy
|
||||
- Task Breakdown Summary
|
||||
- Success Criteria
|
||||
- Brainstorming Artifacts References (if present)
|
||||
|
||||
**From task.json files**:
|
||||
- Task IDs
|
||||
- Titles and descriptions
|
||||
- Status
|
||||
- Dependencies (depends_on, blocks)
|
||||
- Context (requirements, focus_paths, acceptance, artifacts)
|
||||
- Flow control (pre_analysis, implementation_approach)
|
||||
- Meta (complexity, priority, use_codex)
|
||||
|
||||
### 3. Build Semantic Models
|
||||
|
||||
Create internal representations (do not include raw artifacts in output):
|
||||
|
||||
**Requirements inventory**:
|
||||
- Each functional/non-functional/business requirement with stable ID
|
||||
- Requirement text, acceptance criteria, priority
|
||||
|
||||
**Architecture decisions inventory**:
|
||||
- ADRs from synthesis
|
||||
- Technology choices
|
||||
- Data model references
|
||||
|
||||
**Task coverage mapping**:
|
||||
- Map each task to one or more requirements (by ID reference or keyword inference)
|
||||
- Map each requirement to covering tasks
|
||||
|
||||
**Dependency graph**:
|
||||
- Task-to-task dependencies (depends_on, blocks)
|
||||
- Requirement-level dependencies (from synthesis)
|
||||
|
||||
### 4. Detection Passes (Token-Efficient Analysis)
|
||||
|
||||
Focus on high-signal findings. Limit to 50 findings total; aggregate remainder in overflow summary.
|
||||
|
||||
#### A. Requirements Coverage Analysis
|
||||
|
||||
- **Orphaned Requirements**: Requirements in synthesis with zero associated tasks
|
||||
- **Unmapped Tasks**: Tasks with no clear requirement linkage
|
||||
- **NFR Coverage Gaps**: Non-functional requirements (performance, security, scalability) not reflected in tasks
|
||||
|
||||
#### B. Consistency Validation
|
||||
|
||||
- **Requirement Conflicts**: Tasks contradicting synthesis requirements
|
||||
- **Architecture Drift**: IMPL_PLAN architecture not matching synthesis ADRs
|
||||
- **Terminology Drift**: Same concept named differently across IMPL_PLAN and tasks
|
||||
- **Data Model Inconsistency**: Tasks referencing entities/fields not in synthesis data model
|
||||
|
||||
#### C. Dependency Integrity
|
||||
|
||||
- **Circular Dependencies**: Task A depends on B, B depends on C, C depends on A
|
||||
- **Missing Dependencies**: Task requires outputs from another task but no explicit dependency
|
||||
- **Broken Dependencies**: Task depends on non-existent task ID
|
||||
- **Logical Ordering Issues**: Implementation tasks before foundational setup without dependency note
|
||||
|
||||
#### D. Synthesis Alignment
|
||||
|
||||
- **Priority Conflicts**: High-priority synthesis requirements mapped to low-priority tasks
|
||||
- **Success Criteria Mismatch**: IMPL_PLAN success criteria not covering synthesis acceptance criteria
|
||||
- **Risk Mitigation Gaps**: Critical risks in synthesis without corresponding mitigation tasks
|
||||
|
||||
#### E. Task Specification Quality
|
||||
|
||||
- **Ambiguous Focus Paths**: Tasks with vague or missing focus_paths
|
||||
- **Underspecified Acceptance**: Tasks without clear acceptance criteria
|
||||
- **Missing Artifacts References**: Tasks not referencing relevant brainstorming artifacts in context.artifacts
|
||||
- **Weak Flow Control**: Tasks without clear implementation_approach or pre_analysis steps
|
||||
- **Missing Target Files**: Tasks without flow_control.target_files specification
|
||||
|
||||
#### F. Duplication Detection
|
||||
|
||||
- **Overlapping Task Scope**: Multiple tasks with nearly identical descriptions
|
||||
- **Redundant Requirements Coverage**: Same requirement covered by multiple tasks without clear partitioning
|
||||
|
||||
#### G. Feasibility Assessment
|
||||
|
||||
- **Complexity Misalignment**: Task marked "simple" but requires multiple file modifications
|
||||
- **Resource Conflicts**: Parallel tasks requiring same resources/files
|
||||
- **Skill Gap Risks**: Tasks requiring skills not in team capability assessment (from synthesis)
|
||||
|
||||
### 5. Severity Assignment
|
||||
|
||||
Use this heuristic to prioritize findings:
|
||||
|
||||
- **CRITICAL**:
|
||||
- Violates synthesis authority (requirement conflict)
|
||||
- Core requirement with zero coverage
|
||||
- Circular dependencies
|
||||
- Broken dependencies
|
||||
|
||||
- **HIGH**:
|
||||
- NFR coverage gaps
|
||||
- Priority conflicts
|
||||
- Missing risk mitigation tasks
|
||||
- Ambiguous acceptance criteria
|
||||
|
||||
- **MEDIUM**:
|
||||
- Terminology drift
|
||||
- Missing artifacts references
|
||||
- Weak flow control
|
||||
- Logical ordering issues
|
||||
|
||||
- **LOW**:
|
||||
- Style/wording improvements
|
||||
- Minor redundancy not affecting execution
|
||||
|
||||
### 6. Produce Compact Analysis Report
|
||||
|
||||
Output a Markdown report (no file writes) with the following structure:
|
||||
|
||||
```markdown
|
||||
## Action Plan Verification Report
|
||||
|
||||
**Session**: WFS-{session-id}
|
||||
**Generated**: {timestamp}
|
||||
**Artifacts Analyzed**: synthesis-specification.md, IMPL_PLAN.md, {N} task files
|
||||
|
||||
---
|
||||
|
||||
### Executive Summary
|
||||
|
||||
- **Overall Risk Level**: CRITICAL | HIGH | MEDIUM | LOW
|
||||
- **Recommendation**: BLOCK_EXECUTION | PROCEED_WITH_FIXES | PROCEED_WITH_CAUTION | PROCEED
|
||||
- **Critical Issues**: {count}
|
||||
- **High Issues**: {count}
|
||||
- **Medium Issues**: {count}
|
||||
- **Low Issues**: {count}
|
||||
|
||||
---
|
||||
|
||||
### Findings Summary
|
||||
|
||||
| ID | Category | Severity | Location(s) | Summary | Recommendation |
|
||||
|----|----------|----------|-------------|---------|----------------|
|
||||
| C1 | Coverage | CRITICAL | synthesis:FR-03 | Requirement "User auth" has zero task coverage | Add authentication implementation task |
|
||||
| H1 | Consistency | HIGH | IMPL-1.2 vs synthesis:ADR-02 | Task uses REST while synthesis specifies GraphQL | Align task with ADR-02 decision |
|
||||
| M1 | Specification | MEDIUM | IMPL-2.1 | Missing context.artifacts reference | Add @synthesis reference |
|
||||
| L1 | Duplication | LOW | IMPL-3.1, IMPL-3.2 | Similar scope | Consider merging |
|
||||
|
||||
(Add one row per finding; generate stable IDs prefixed by severity initial.)
|
||||
|
||||
---
|
||||
|
||||
### Requirements Coverage Analysis
|
||||
|
||||
| Requirement ID | Requirement Summary | Has Task? | Task IDs | Priority Match | Notes |
|
||||
|----------------|---------------------|-----------|----------|----------------|-------|
|
||||
| FR-01 | User authentication | ✅ Yes | IMPL-1.1, IMPL-1.2 | ✅ Match | Complete |
|
||||
| FR-02 | Data export | ✅ Yes | IMPL-2.3 | ⚠️ Mismatch | High req → Med priority task |
|
||||
| FR-03 | Profile management | ❌ No | - | - | **CRITICAL: Zero coverage** |
|
||||
| NFR-01 | Response time <200ms | ❌ No | - | - | **HIGH: No performance tasks** |
|
||||
|
||||
**Coverage Metrics**:
|
||||
- Functional Requirements: 85% (17/20 covered)
|
||||
- Non-Functional Requirements: 40% (2/5 covered)
|
||||
- Business Requirements: 100% (5/5 covered)
|
||||
|
||||
---
|
||||
|
||||
### Unmapped Tasks
|
||||
|
||||
| Task ID | Title | Issue | Recommendation |
|
||||
|---------|-------|-------|----------------|
|
||||
| IMPL-4.5 | Refactor utils | No requirement linkage | Link to technical debt or remove |
|
||||
|
||||
---
|
||||
|
||||
### Dependency Graph Issues
|
||||
|
||||
**Circular Dependencies**: None detected ✅
|
||||
|
||||
**Broken Dependencies**:
|
||||
- IMPL-2.3 depends on "IMPL-2.4" (non-existent)
|
||||
|
||||
**Logical Ordering Issues**:
|
||||
- IMPL-5.1 (integration test) has no dependency on IMPL-1.* (implementation tasks)
|
||||
|
||||
---
|
||||
|
||||
### Synthesis Alignment Issues
|
||||
|
||||
| Issue Type | Synthesis Reference | IMPL_PLAN/Task | Impact | Recommendation |
|
||||
|------------|---------------------|----------------|--------|----------------|
|
||||
| Architecture Conflict | synthesis:ADR-01 (JWT auth) | IMPL_PLAN uses session cookies | HIGH | Update IMPL_PLAN to use JWT |
|
||||
| Priority Mismatch | synthesis:FR-02 (High) | IMPL-2.3 (Medium) | MEDIUM | Elevate task priority |
|
||||
| Missing Risk Mitigation | synthesis:Risk-03 (API rate limits) | No mitigation tasks | HIGH | Add rate limiting implementation task |
|
||||
|
||||
---
|
||||
|
||||
### Task Specification Quality Issues
|
||||
|
||||
**Missing Artifacts References**: 12 tasks lack context.artifacts
|
||||
**Weak Flow Control**: 5 tasks lack implementation_approach
|
||||
**Missing Target Files**: 8 tasks lack flow_control.target_files
|
||||
|
||||
**Sample Issues**:
|
||||
- IMPL-1.2: No context.artifacts reference to synthesis
|
||||
- IMPL-3.1: Missing flow_control.target_files specification
|
||||
- IMPL-4.2: Vague focus_paths ["src/"] - needs refinement
|
||||
|
||||
---
|
||||
|
||||
### Feasibility Concerns
|
||||
|
||||
| Concern | Tasks Affected | Issue | Recommendation |
|
||||
|---------|----------------|-------|----------------|
|
||||
| Skill Gap | IMPL-6.1, IMPL-6.2 | Requires Kubernetes expertise not in team | Add training task or external consultant |
|
||||
| Resource Conflict | IMPL-3.1, IMPL-3.2 | Both modify src/auth/service.ts in parallel | Add dependency or serialize |
|
||||
|
||||
---
|
||||
|
||||
### Metrics
|
||||
|
||||
- **Total Requirements**: 30 (20 functional, 5 non-functional, 5 business)
|
||||
- **Total Tasks**: 25
|
||||
- **Overall Coverage**: 77% (23/30 requirements with ≥1 task)
|
||||
- **Critical Issues**: 2
|
||||
- **High Issues**: 5
|
||||
- **Medium Issues**: 8
|
||||
- **Low Issues**: 3
|
||||
|
||||
---
|
||||
|
||||
### Next Actions
|
||||
|
||||
#### If CRITICAL Issues Exist (Current Status: 2 CRITICAL)
|
||||
**Recommendation**: ❌ **BLOCK EXECUTION** - Resolve CRITICAL issues before proceeding
|
||||
|
||||
**Required Actions**:
|
||||
1. **CRITICAL**: Add authentication implementation tasks to cover FR-03
|
||||
2. **CRITICAL**: Add performance optimization tasks to cover NFR-01
|
||||
|
||||
#### If Only HIGH/MEDIUM/LOW Issues
|
||||
**Recommendation**: ⚠️ **PROCEED WITH CAUTION** - Issues are non-blocking but should be addressed
|
||||
|
||||
**Suggested Improvements**:
|
||||
1. Add context.artifacts references to all tasks (use /task:replan)
|
||||
2. Fix broken dependency IMPL-2.3 → IMPL-2.4
|
||||
3. Add flow_control.target_files to underspecified tasks
|
||||
|
||||
#### Command Suggestions
|
||||
```bash
|
||||
# Fix critical coverage gaps
|
||||
/task:create "Implement user authentication (FR-03)"
|
||||
/task:create "Add performance optimization (NFR-01)"
|
||||
|
||||
# Refine existing tasks
|
||||
/task:replan IMPL-1.2 "Add context.artifacts and target_files"
|
||||
|
||||
# Update IMPL_PLAN if architecture drift detected
|
||||
# (Manual edit required)
|
||||
```
|
||||
```
|
||||
|
||||
### 7. Provide Remediation Options
|
||||
|
||||
At end of report, ask the user:
|
||||
|
||||
```markdown
|
||||
### 🔧 Remediation Options
|
||||
|
||||
Would you like me to:
|
||||
1. **Generate task suggestions** for unmapped requirements (no auto-creation)
|
||||
2. **Provide specific edit commands** for top N issues (you execute manually)
|
||||
3. **Create remediation checklist** for systematic fixing
|
||||
|
||||
(Do NOT apply fixes automatically - this is read-only analysis)
|
||||
```
|
||||
|
||||
### 8. Update Session Metadata
|
||||
|
||||
```json
|
||||
{
|
||||
"phases": {
|
||||
"PLAN": {
|
||||
"status": "completed",
|
||||
"action_plan_verification": {
|
||||
"completed": true,
|
||||
"completed_at": "timestamp",
|
||||
"overall_risk_level": "HIGH",
|
||||
"recommendation": "PROCEED_WITH_FIXES",
|
||||
"issues": {
|
||||
"critical": 2,
|
||||
"high": 5,
|
||||
"medium": 8,
|
||||
"low": 3
|
||||
},
|
||||
"coverage": {
|
||||
"functional_requirements": 0.85,
|
||||
"non_functional_requirements": 0.40,
|
||||
"business_requirements": 1.00
|
||||
},
|
||||
"report_path": ".workflow/WFS-{session}/.process/ACTION_PLAN_VERIFICATION.md"
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
## Operating Principles
|
||||
|
||||
### Context Efficiency
|
||||
- **Minimal high-signal tokens**: Focus on actionable findings
|
||||
- **Progressive disclosure**: Load artifacts incrementally
|
||||
- **Token-efficient output**: Limit findings table to 50 rows; summarize overflow
|
||||
- **Deterministic results**: Rerunning without changes produces consistent IDs and counts
|
||||
|
||||
### Analysis Guidelines
|
||||
- **NEVER modify files** (this is read-only analysis)
|
||||
- **NEVER hallucinate missing sections** (if absent, report them accurately)
|
||||
- **Prioritize synthesis violations** (these are always CRITICAL)
|
||||
- **Use examples over exhaustive rules** (cite specific instances)
|
||||
- **Report zero issues gracefully** (emit success report with coverage statistics)
|
||||
|
||||
### Verification Taxonomy
|
||||
- **Coverage**: Requirements → Tasks mapping
|
||||
- **Consistency**: Cross-artifact alignment
|
||||
- **Dependencies**: Task ordering and relationships
|
||||
- **Synthesis Alignment**: Adherence to authoritative requirements
|
||||
- **Task Quality**: Specification completeness
|
||||
- **Feasibility**: Implementation risks
|
||||
|
||||
## Behavior Rules
|
||||
|
||||
- **If no issues found**: Report "✅ Action plan verification passed. No issues detected." and suggest proceeding to `/workflow:execute`.
|
||||
- **If CRITICAL issues exist**: Recommend blocking execution until resolved.
|
||||
- **If only HIGH/MEDIUM issues**: User may proceed with caution, but provide improvement suggestions.
|
||||
- **If IMPL_PLAN.md or task files missing**: Instruct user to run `/workflow:plan` first.
|
||||
- **Always provide actionable remediation suggestions**: Don't just identify problems—suggest solutions.
|
||||
|
||||
## Context
|
||||
|
||||
{ARGS}
|
||||
@@ -436,4 +436,65 @@ Upon completion, update `workflow-session.json`:
|
||||
- [ ] **Implementation Readiness**: Plans detailed enough for immediate execution, with clear handoff to IMPL_PLAN.md
|
||||
- [ ] **Stakeholder Alignment**: Addresses needs and concerns of all key stakeholders
|
||||
- [ ] **Decision Traceability**: Every major decision traceable to source role analysis via @ references
|
||||
- [ ] **Continuous Improvement**: Establishes framework for ongoing optimization and learning
|
||||
- [ ] **Continuous Improvement**: Establishes framework for ongoing optimization and learning
|
||||
|
||||
## 🚀 **Recommended Next Steps**
|
||||
|
||||
After synthesis completion, follow this recommended workflow:
|
||||
|
||||
### Option 1: Standard Planning Workflow (Recommended)
|
||||
```bash
|
||||
# Step 1: Verify conceptual clarity (Quality Gate)
|
||||
/workflow:concept-verify --session WFS-{session-id}
|
||||
# → Interactive Q&A (up to 5 questions) to clarify ambiguities in synthesis
|
||||
|
||||
# Step 2: Proceed to action planning (after concept verification)
|
||||
/workflow:plan --session WFS-{session-id}
|
||||
# → Generates IMPL_PLAN.md and task.json files
|
||||
|
||||
# Step 3: Verify action plan quality (Quality Gate)
|
||||
/workflow:action-plan-verify --session WFS-{session-id}
|
||||
# → Read-only analysis to catch issues before execution
|
||||
|
||||
# Step 4: Start implementation
|
||||
/workflow:execute --session WFS-{session-id}
|
||||
```
|
||||
|
||||
### Option 2: TDD Workflow
|
||||
```bash
|
||||
# Step 1: Verify conceptual clarity
|
||||
/workflow:concept-verify --session WFS-{session-id}
|
||||
|
||||
# Step 2: Generate TDD task chains (RED-GREEN-REFACTOR)
|
||||
/workflow:tdd-plan --session WFS-{session-id} "Feature description"
|
||||
|
||||
# Step 3: Verify TDD plan quality
|
||||
/workflow:action-plan-verify --session WFS-{session-id}
|
||||
|
||||
# Step 4: Execute TDD workflow
|
||||
/workflow:execute --session WFS-{session-id}
|
||||
```
|
||||
|
||||
### Quality Gates Explained
|
||||
|
||||
**`/workflow:concept-verify`** (Phase 2 - After Brainstorming):
|
||||
- **Purpose**: Detect and resolve conceptual ambiguities before detailed planning
|
||||
- **Time**: 10-20 minutes (interactive)
|
||||
- **Value**: Reduces downstream rework by 40-60%
|
||||
- **Output**: Updated synthesis-specification.md with clarifications
|
||||
|
||||
**`/workflow:action-plan-verify`** (Phase 4 - After Planning):
|
||||
- **Purpose**: Validate IMPL_PLAN.md and task.json consistency and completeness
|
||||
- **Time**: 5-10 minutes (read-only analysis)
|
||||
- **Value**: Prevents execution of flawed plans, saves 2-5 days
|
||||
- **Output**: Verification report with actionable recommendations
|
||||
|
||||
### Skip Verification? (Not Recommended)
|
||||
|
||||
If you want to skip verification and proceed directly:
|
||||
```bash
|
||||
/workflow:plan --session WFS-{session-id}
|
||||
/workflow:execute --session WFS-{session-id}
|
||||
```
|
||||
|
||||
⚠️ **Warning**: Skipping verification increases risk of late-stage issues and rework.
|
||||
311
.claude/commands/workflow/concept-verify.md
Normal file
311
.claude/commands/workflow/concept-verify.md
Normal file
@@ -0,0 +1,311 @@
|
||||
---
|
||||
name: concept-verify
|
||||
description: Identify underspecified areas in brainstorming artifacts through targeted clarification questions before action planning
|
||||
usage: /workflow:concept-verify [--session <session-id>]
|
||||
argument-hint: "optional: --session <session-id>"
|
||||
examples:
|
||||
- /workflow:concept-verify
|
||||
- /workflow:concept-verify --session WFS-auth
|
||||
allowed-tools: Read(*), Write(*), Edit(*), TodoWrite(*), Glob(*), Bash(*)
|
||||
---
|
||||
|
||||
## User Input
|
||||
|
||||
```text
|
||||
$ARGUMENTS
|
||||
```
|
||||
|
||||
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.
|
||||
|
||||
**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.
|
||||
|
||||
**Execution steps**:
|
||||
|
||||
1. **Session Detection & Validation**
|
||||
```bash
|
||||
# Detect active workflow session
|
||||
IF --session parameter provided:
|
||||
session_id = provided session
|
||||
ELSE:
|
||||
CHECK: .workflow/.active-* marker files
|
||||
IF active_session EXISTS:
|
||||
session_id = get_active_session()
|
||||
ELSE:
|
||||
ERROR: "No active workflow session found. Use --session <session-id> or start a session."
|
||||
EXIT
|
||||
|
||||
# Validate brainstorming completion
|
||||
brainstorm_dir = .workflow/WFS-{session}/.brainstorming/
|
||||
|
||||
CHECK: brainstorm_dir/synthesis-specification.md
|
||||
IF NOT EXISTS:
|
||||
ERROR: "synthesis-specification.md not found. Run /workflow:brainstorm:synthesis first"
|
||||
EXIT
|
||||
|
||||
CHECK: brainstorm_dir/topic-framework.md
|
||||
IF NOT EXISTS:
|
||||
WARN: "topic-framework.md not found. Verification will be limited."
|
||||
```
|
||||
|
||||
2. **Load Brainstorming Artifacts**
|
||||
```bash
|
||||
# Load primary artifacts
|
||||
synthesis_spec = Read(brainstorm_dir + "/synthesis-specification.md")
|
||||
topic_framework = Read(brainstorm_dir + "/topic-framework.md") # if exists
|
||||
|
||||
# Discover role analyses
|
||||
role_analyses = Glob(brainstorm_dir + "/*/analysis.md")
|
||||
participating_roles = extract_role_names(role_analyses)
|
||||
```
|
||||
|
||||
3. **Ambiguity & Coverage Scan**
|
||||
|
||||
Perform structured scan using this taxonomy. For each category, mark status: **Clear** / **Partial** / **Missing**.
|
||||
|
||||
**Requirements Clarity**:
|
||||
- Functional requirements specificity and measurability
|
||||
- Non-functional requirements with quantified targets
|
||||
- Business requirements with success metrics
|
||||
- Acceptance criteria completeness
|
||||
|
||||
**Architecture & Design Clarity**:
|
||||
- Architecture decisions with rationale
|
||||
- Data model completeness (entities, relationships, constraints)
|
||||
- Technology stack justification
|
||||
- Integration points and API contracts
|
||||
|
||||
**User Experience & Interface**:
|
||||
- User journey completeness
|
||||
- Critical interaction flows
|
||||
- Error/edge case handling
|
||||
- Accessibility and localization considerations
|
||||
|
||||
**Implementation Feasibility**:
|
||||
- Team capability vs. required skills
|
||||
- External dependencies and failure modes
|
||||
- Resource constraints (timeline, personnel)
|
||||
- Technical constraints and tradeoffs
|
||||
|
||||
**Risk & Mitigation**:
|
||||
- Critical risks identified
|
||||
- Mitigation strategies defined
|
||||
- Success factors clarity
|
||||
- Monitoring and quality gates
|
||||
|
||||
**Process & Collaboration**:
|
||||
- Role responsibilities and handoffs
|
||||
- Collaboration patterns defined
|
||||
- Timeline and milestone clarity
|
||||
- Dependency management strategy
|
||||
|
||||
**Decision Traceability**:
|
||||
- Controversial points documented
|
||||
- Alternatives considered and rejected
|
||||
- Decision rationale clarity
|
||||
- Consensus vs. dissent tracking
|
||||
|
||||
**Terminology & Consistency**:
|
||||
- Canonical terms defined
|
||||
- Consistent naming across artifacts
|
||||
- No unresolved placeholders (TODO, TBD, ???)
|
||||
|
||||
For each category with **Partial** or **Missing** status, add to candidate question queue unless:
|
||||
- Clarification would not materially change implementation strategy
|
||||
- Information is better deferred to planning phase
|
||||
|
||||
4. **Generate Prioritized Question Queue**
|
||||
|
||||
Internally generate prioritized queue of candidate questions (maximum 5):
|
||||
|
||||
**Constraints**:
|
||||
- Maximum 5 questions per session
|
||||
- Each question must be answerable with:
|
||||
* Multiple-choice (2-5 mutually exclusive options), OR
|
||||
* Short answer (≤5 words)
|
||||
- Only include questions whose answers materially impact:
|
||||
* Architecture decisions
|
||||
* Data modeling
|
||||
* Task decomposition
|
||||
* Risk mitigation
|
||||
* Success criteria
|
||||
- Ensure category coverage balance
|
||||
- Favor clarifications that reduce downstream rework risk
|
||||
|
||||
**Prioritization Heuristic**:
|
||||
```
|
||||
priority_score = (impact_on_planning * 0.4) +
|
||||
(uncertainty_level * 0.3) +
|
||||
(risk_if_unresolved * 0.3)
|
||||
```
|
||||
|
||||
If zero high-impact ambiguities found, proceed to **Step 8** (report success).
|
||||
|
||||
5. **Sequential Question Loop** (Interactive)
|
||||
|
||||
Present **EXACTLY ONE** question at a time:
|
||||
|
||||
**Multiple-choice format**:
|
||||
```markdown
|
||||
**Question {N}/5**: {Question text}
|
||||
|
||||
| Option | Description |
|
||||
|--------|-------------|
|
||||
| A | {Option A description} |
|
||||
| B | {Option B description} |
|
||||
| C | {Option C description} |
|
||||
| D | {Option D description} |
|
||||
| Short | Provide different answer (≤5 words) |
|
||||
```
|
||||
|
||||
**Short-answer format**:
|
||||
```markdown
|
||||
**Question {N}/5**: {Question text}
|
||||
|
||||
Format: Short answer (≤5 words)
|
||||
```
|
||||
|
||||
**Answer Validation**:
|
||||
- Validate answer maps to option or fits ≤5 word constraint
|
||||
- If ambiguous, ask quick disambiguation (doesn't count as new question)
|
||||
- Once satisfactory, record in working memory and proceed to next question
|
||||
|
||||
**Stop Conditions**:
|
||||
- All critical ambiguities resolved
|
||||
- User signals completion ("done", "no more", "proceed")
|
||||
- Reached 5 questions
|
||||
|
||||
**Never reveal future queued questions in advance**.
|
||||
|
||||
6. **Integration After Each Answer** (Incremental Update)
|
||||
|
||||
After each accepted answer:
|
||||
|
||||
```bash
|
||||
# Ensure Clarifications section exists
|
||||
IF synthesis_spec NOT contains "## Clarifications":
|
||||
Insert "## Clarifications" section after "# [Topic]" heading
|
||||
|
||||
# Create session subsection
|
||||
IF NOT contains "### Session YYYY-MM-DD":
|
||||
Create "### Session {today's date}" under "## Clarifications"
|
||||
|
||||
# Append clarification entry
|
||||
APPEND: "- Q: {question} → A: {answer}"
|
||||
|
||||
# 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"
|
||||
|
||||
# Remove obsolete/contradictory statements
|
||||
IF clarification invalidates existing statement:
|
||||
Replace statement instead of duplicating
|
||||
|
||||
# Save immediately
|
||||
Write(synthesis_specification.md)
|
||||
```
|
||||
|
||||
7. **Validation After Each Write**
|
||||
|
||||
- [ ] Clarifications section contains exactly one bullet per accepted answer
|
||||
- [ ] Total asked questions ≤ 5
|
||||
- [ ] Updated sections contain no lingering placeholders
|
||||
- [ ] No contradictory earlier statements remain
|
||||
- [ ] Markdown structure valid
|
||||
- [ ] Terminology consistent across all updated sections
|
||||
|
||||
8. **Completion Report**
|
||||
|
||||
After questioning loop ends or early termination:
|
||||
|
||||
```markdown
|
||||
## ✅ Concept Verification Complete
|
||||
|
||||
**Session**: WFS-{session-id}
|
||||
**Questions Asked**: {count}/5
|
||||
**Artifacts Updated**: synthesis-specification.md
|
||||
**Sections Touched**: {list section names}
|
||||
|
||||
### Coverage Summary
|
||||
|
||||
| Category | Status | Notes |
|
||||
|----------|--------|-------|
|
||||
| Requirements Clarity | ✅ Resolved | Acceptance criteria quantified |
|
||||
| Architecture & Design | ✅ Clear | No ambiguities found |
|
||||
| Implementation Feasibility | ⚠️ Deferred | Team training plan to be defined in IMPL_PLAN |
|
||||
| Risk & Mitigation | ✅ Resolved | Critical risks now have mitigation strategies |
|
||||
| ... | ... | ... |
|
||||
|
||||
**Legend**:
|
||||
- ✅ Resolved: Was Partial/Missing, now addressed
|
||||
- ✅ Clear: Already sufficient
|
||||
- ⚠️ Deferred: Low impact, better suited for planning phase
|
||||
- ❌ Outstanding: Still Partial/Missing but question quota reached
|
||||
|
||||
### Recommendations
|
||||
|
||||
- ✅ **PROCEED to /workflow:plan**: Conceptual foundation is clear
|
||||
- OR ⚠️ **Address Outstanding Items First**: {list critical outstanding items}
|
||||
- OR 🔄 **Run /workflow:concept-verify Again**: If new information available
|
||||
|
||||
### Next Steps
|
||||
```bash
|
||||
/workflow:plan # Generate IMPL_PLAN.md and task.json
|
||||
```
|
||||
```
|
||||
|
||||
9. **Update Session Metadata**
|
||||
|
||||
```json
|
||||
{
|
||||
"phases": {
|
||||
"BRAINSTORM": {
|
||||
"status": "completed",
|
||||
"concept_verification": {
|
||||
"completed": true,
|
||||
"completed_at": "timestamp",
|
||||
"questions_asked": 3,
|
||||
"categories_clarified": ["Requirements", "Risk", "Architecture"],
|
||||
"outstanding_items": [],
|
||||
"recommendation": "PROCEED_TO_PLANNING"
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
## Behavior Rules
|
||||
|
||||
- **If no meaningful ambiguities found**: Report "No critical ambiguities detected. Conceptual foundation is clear." and suggest proceeding to `/workflow:plan`.
|
||||
- **If synthesis-specification.md missing**: Instruct user to run `/workflow:brainstorm:synthesis` first.
|
||||
- **Never exceed 5 questions** (disambiguation retries don't count as new questions).
|
||||
- **Respect user early termination**: Signals like "stop", "done", "proceed" should stop questioning.
|
||||
- **If quota reached with high-impact items unresolved**: Explicitly flag them under "Outstanding" with recommendation to address before planning.
|
||||
- **Avoid speculative tech stack questions** unless absence blocks conceptual clarity.
|
||||
|
||||
## Operating Principles
|
||||
|
||||
### Context Efficiency
|
||||
- **Minimal high-signal tokens**: Focus on actionable clarifications
|
||||
- **Progressive disclosure**: Load artifacts incrementally
|
||||
- **Deterministic results**: Rerunning without changes produces consistent analysis
|
||||
|
||||
### Verification Guidelines
|
||||
- **NEVER hallucinate missing sections**: Report them accurately
|
||||
- **Prioritize high-impact ambiguities**: Focus on what affects planning
|
||||
- **Use examples over exhaustive rules**: Cite specific instances
|
||||
- **Report zero issues gracefully**: Emit success report with coverage statistics
|
||||
- **Update incrementally**: Save after each answer to minimize context loss
|
||||
|
||||
## Context
|
||||
|
||||
{ARGS}
|
||||
@@ -143,7 +143,12 @@ Planning complete for session: [sessionId]
|
||||
Tasks generated: [count]
|
||||
Plan: .workflow/[sessionId]/IMPL_PLAN.md
|
||||
|
||||
Next: /workflow:execute or /workflow:status
|
||||
✅ Recommended Next Steps:
|
||||
1. /workflow:action-plan-verify --session [sessionId] # Verify plan quality before execution
|
||||
2. /workflow:status # Review task breakdown
|
||||
3. /workflow:execute # Start implementation (after verification)
|
||||
|
||||
⚠️ Quality Gate: Consider running /workflow:action-plan-verify to catch issues early
|
||||
```
|
||||
|
||||
## TodoWrite Pattern
|
||||
|
||||
@@ -26,10 +26,11 @@ allowed-tools: SlashCommand(*), TodoWrite(*), Read(*), Bash(*)
|
||||
2. **No Preliminary Analysis**: Do not read files before Phase 1
|
||||
3. **Parse Every Output**: Extract required data for next phase
|
||||
4. **Sequential Execution**: Each phase depends on previous output
|
||||
5. **Complete All Phases**: Do not return until Phase 5 completes
|
||||
5. **Complete All Phases**: Do not return until Phase 7 completes (with concept verification)
|
||||
6. **TDD Context**: All descriptions include "TDD:" prefix
|
||||
7. **Quality Gate**: Phase 5 concept verification ensures clarity before task generation
|
||||
|
||||
## 6-Phase Execution
|
||||
## 7-Phase Execution (with Concept Verification)
|
||||
|
||||
### Phase 1: Session Discovery
|
||||
**Command**: `/workflow:session:start --auto "TDD: [structured-description]"`
|
||||
@@ -79,7 +80,22 @@ TEST_FOCUS: [Test scenarios]
|
||||
|
||||
**Parse**: Verify ANALYSIS_RESULTS.md contains TDD breakdown sections
|
||||
|
||||
### Phase 5: TDD Task Generation
|
||||
### Phase 5: Concept Verification (NEW QUALITY GATE)
|
||||
**Command**: `/workflow:concept-verify --session [sessionId]`
|
||||
|
||||
**Purpose**: Verify conceptual clarity before TDD task generation
|
||||
- Clarify test requirements and acceptance criteria
|
||||
- Resolve ambiguities in expected behavior
|
||||
- Validate TDD approach is appropriate
|
||||
|
||||
**Behavior**:
|
||||
- If no ambiguities found → Auto-proceed to Phase 6
|
||||
- If ambiguities exist → Interactive clarification (up to 5 questions)
|
||||
- After clarifications → Auto-proceed to Phase 6
|
||||
|
||||
**Parse**: Verify concept verification completed (check for clarifications section in ANALYSIS_RESULTS.md or synthesis file if exists)
|
||||
|
||||
### Phase 6: TDD Task Generation
|
||||
**Command**:
|
||||
- Manual: `/workflow:tools:task-generate-tdd --session [sessionId]`
|
||||
- Agent: `/workflow:tools:task-generate-tdd --session [sessionId] --agent`
|
||||
@@ -93,10 +109,10 @@ TEST_FOCUS: [Test scenarios]
|
||||
- IMPL tasks include test-fix-cycle configuration
|
||||
- IMPL_PLAN.md contains workflow_type: "tdd" in frontmatter
|
||||
|
||||
### Phase 6: TDD Structure Validation
|
||||
**Internal validation (no command)**
|
||||
### Phase 7: TDD Structure Validation & Action Plan Verification (RECOMMENDED)
|
||||
**Internal validation first, then recommend external verification**
|
||||
|
||||
**Validate**:
|
||||
**Internal Validation**:
|
||||
1. Each feature has TEST → IMPL → REFACTOR chain
|
||||
2. Dependencies: IMPL depends_on TEST, REFACTOR depends_on IMPL
|
||||
3. Meta fields: tdd_phase correct ("red"/"green"/"refactor")
|
||||
@@ -117,20 +133,26 @@ Structure:
|
||||
|
||||
Plan:
|
||||
- Unified Implementation Plan: .workflow/[sessionId]/IMPL_PLAN.md
|
||||
(includes TDD Task Chains section)
|
||||
(includes TDD Task Chains section with workflow_type: "tdd")
|
||||
|
||||
Next: /workflow:execute or /workflow:tdd-verify
|
||||
✅ Recommended Next Steps:
|
||||
1. /workflow:action-plan-verify --session [sessionId] # Verify TDD plan quality
|
||||
2. /workflow:execute --session [sessionId] # Start TDD execution
|
||||
3. /workflow:tdd-verify [sessionId] # Post-execution TDD compliance check
|
||||
|
||||
⚠️ Quality Gate: Consider running /workflow:action-plan-verify to validate TDD task dependencies
|
||||
```
|
||||
|
||||
## TodoWrite Pattern
|
||||
|
||||
```javascript
|
||||
// Initialize (6 phases now)
|
||||
// Initialize (7 phases now with concept verification)
|
||||
[
|
||||
{content: "Execute session discovery", status: "in_progress", activeForm: "Executing session discovery"},
|
||||
{content: "Execute context gathering", status: "pending", activeForm: "Executing context gathering"},
|
||||
{content: "Execute test coverage analysis", status: "pending", activeForm: "Executing test coverage analysis"},
|
||||
{content: "Execute TDD analysis", status: "pending", activeForm: "Executing TDD analysis"},
|
||||
{content: "Execute context gathering", status: "pending", activeForm": "Executing context gathering"},
|
||||
{content: "Execute test coverage analysis", status: "pending", activeForm": "Executing test coverage analysis"},
|
||||
{content: "Execute TDD analysis", status: "pending", activeForm": "Executing TDD analysis"},
|
||||
{content: "Execute concept verification", status: "pending", activeForm": "Executing concept verification"},
|
||||
{content: "Execute TDD task generation", status: "pending", activeForm: "Executing TDD task generation"},
|
||||
{content: "Validate TDD structure", status: "pending", activeForm: "Validating TDD structure"}
|
||||
]
|
||||
|
||||
@@ -238,35 +238,231 @@ Task(
|
||||
\`\`\`markdown
|
||||
---
|
||||
identifier: WFS-{session-id}
|
||||
source: "User requirements"
|
||||
source: "User requirements" | "File: path" | "Issue: ISS-001"
|
||||
analysis: .workflow/{session-id}/.process/ANALYSIS_RESULTS.md
|
||||
artifacts: .workflow/{session-id}/.brainstorming/
|
||||
context_package: .workflow/{session-id}/.process/context-package.json # CCW smart context
|
||||
workflow_type: "standard | tdd | design" # Indicates execution model
|
||||
verification_history: # CCW quality gates
|
||||
concept_verify: "passed | skipped | pending"
|
||||
action_plan_verify: "pending"
|
||||
phase_progression: "brainstorm → context → analysis → concept_verify → planning" # CCW workflow phases
|
||||
---
|
||||
|
||||
# Implementation Plan: {Project Title}
|
||||
|
||||
## Summary
|
||||
Core requirements, objectives, and technical approach.
|
||||
## 1. Summary
|
||||
Core requirements, objectives, technical approach summary (2-3 paragraphs max).
|
||||
|
||||
## Context Analysis
|
||||
- **Project**: Type, patterns, tech stack
|
||||
- **Modules**: Components and integration points
|
||||
- **Dependencies**: External libraries and constraints
|
||||
- **Patterns**: Code conventions and guidelines
|
||||
**Core Objectives**:
|
||||
- [Key objective 1]
|
||||
- [Key objective 2]
|
||||
|
||||
## Brainstorming Artifacts
|
||||
- synthesis-specification.md (Highest priority)
|
||||
- topic-framework.md (Medium priority)
|
||||
- Role analyses: ui-designer, system-architect, etc.
|
||||
**Technical Approach**:
|
||||
- [High-level approach]
|
||||
|
||||
## Task Breakdown
|
||||
- **Task Count**: N tasks, complexity level
|
||||
- **Hierarchy**: Flat/Two-level structure
|
||||
- **Dependencies**: Task dependency graph
|
||||
## 2. Context Analysis
|
||||
|
||||
## Implementation Plan
|
||||
- **Execution Strategy**: Sequential/Parallel approach
|
||||
- **Resource Requirements**: Tools, dependencies, artifacts
|
||||
- **Success Criteria**: Metrics and acceptance conditions
|
||||
### CCW Workflow Context
|
||||
**Phase Progression**:
|
||||
- ✅ Phase 1: Brainstorming (synthesis-specification.md generated)
|
||||
- ✅ Phase 2: Context Gathering (context-package.json: {N} files, {M} modules analyzed)
|
||||
- ✅ Phase 3: Enhanced Analysis (ANALYSIS_RESULTS.md: Gemini/Qwen/Codex parallel insights)
|
||||
- ✅ Phase 4: Concept Verification ({X} clarifications answered, synthesis updated | skipped)
|
||||
- ⏳ Phase 5: Action Planning (current phase - generating IMPL_PLAN.md)
|
||||
|
||||
**Quality Gates**:
|
||||
- concept-verify: ✅ Passed (0 ambiguities remaining) | ⏭️ Skipped (user decision) | ⏳ Pending
|
||||
- action-plan-verify: ⏳ Pending (recommended before /workflow:execute)
|
||||
|
||||
**Context Package Summary**:
|
||||
- **Focus Paths**: {list key directories from context-package.json}
|
||||
- **Key Files**: {list primary files for modification}
|
||||
- **Module Depth Analysis**: {from get_modules_by_depth.sh output}
|
||||
- **Smart Context**: {total file count} files, {module count} modules, {dependency count} dependencies identified
|
||||
|
||||
### Project Profile
|
||||
- **Type**: Greenfield/Enhancement/Refactor
|
||||
- **Scale**: User count, data volume, complexity
|
||||
- **Tech Stack**: Primary technologies
|
||||
- **Timeline**: Duration and milestones
|
||||
|
||||
### Module Structure
|
||||
\`\`\`
|
||||
[Directory tree showing key modules]
|
||||
\`\`\`
|
||||
|
||||
### Dependencies
|
||||
**Primary**: [Core libraries and frameworks]
|
||||
**APIs**: [External services]
|
||||
**Development**: [Testing, linting, CI/CD tools]
|
||||
|
||||
### Patterns & Conventions
|
||||
- **Architecture**: [Key patterns like DI, Event-Driven]
|
||||
- **Component Design**: [Design patterns]
|
||||
- **State Management**: [State strategy]
|
||||
- **Code Style**: [Naming, TypeScript coverage]
|
||||
|
||||
## 3. Brainstorming Artifacts Reference
|
||||
|
||||
### Artifact Usage Strategy
|
||||
**Primary Reference (synthesis-specification.md)**:
|
||||
- **What**: Comprehensive implementation blueprint from multi-role synthesis
|
||||
- **When**: Every task references this first for requirements and design decisions
|
||||
- **How**: Extract architecture decisions, UI/UX patterns, functional requirements, non-functional requirements
|
||||
- **Priority**: Authoritative - overrides role-specific analyses when conflicts arise
|
||||
- **CCW Value**: Consolidates insights from all brainstorming roles into single source of truth
|
||||
|
||||
**Context Intelligence (context-package.json)**:
|
||||
- **What**: Smart context gathered by CCW's context-gather phase
|
||||
- **Content**: Focus paths, dependency graph, existing patterns, module structure
|
||||
- **Usage**: Tasks load this via \`flow_control.preparatory_steps\` for environment setup
|
||||
- **CCW Value**: Automated intelligent context discovery replacing manual file exploration
|
||||
|
||||
**Technical Analysis (ANALYSIS_RESULTS.md)**:
|
||||
- **What**: Gemini/Qwen/Codex parallel analysis results
|
||||
- **Content**: Optimization strategies, risk assessment, architecture review, implementation patterns
|
||||
- **Usage**: Referenced in task planning for technical guidance and risk mitigation
|
||||
- **CCW Value**: Multi-model parallel analysis providing comprehensive technical intelligence
|
||||
|
||||
### Integrated Specifications (Highest Priority)
|
||||
- **synthesis-specification.md**: Comprehensive implementation blueprint
|
||||
- Contains: Architecture design, UI/UX guidelines, functional/non-functional requirements, implementation roadmap, risk assessment
|
||||
|
||||
### Supporting Artifacts (Reference)
|
||||
- **topic-framework.md**: Role-specific discussion points and analysis framework
|
||||
- **system-architect/analysis.md**: Detailed architecture specifications
|
||||
- **ui-designer/analysis.md**: Layout and component specifications
|
||||
- **product-manager/analysis.md**: Product vision and user stories
|
||||
|
||||
**Artifact Priority in Development**:
|
||||
1. synthesis-specification.md (primary reference for all tasks)
|
||||
2. context-package.json (smart context for execution environment)
|
||||
3. ANALYSIS_RESULTS.md (technical analysis and optimization strategies)
|
||||
4. Role-specific analyses (fallback for detailed specifications)
|
||||
|
||||
## 4. Implementation Strategy
|
||||
|
||||
### Execution Strategy
|
||||
**Execution Model**: [Sequential | Parallel | Phased | TDD Cycles]
|
||||
|
||||
**Rationale**: [Why this execution model fits the project]
|
||||
|
||||
**Parallelization Opportunities**:
|
||||
- [List independent workstreams]
|
||||
|
||||
**Serialization Requirements**:
|
||||
- [List critical dependencies]
|
||||
|
||||
### Architectural Approach
|
||||
**Key Architecture Decisions**:
|
||||
- [ADR references from synthesis]
|
||||
- [Justification for architecture patterns]
|
||||
|
||||
**Integration Strategy**:
|
||||
- [How modules communicate]
|
||||
- [State management approach]
|
||||
|
||||
### Key Dependencies
|
||||
**Task Dependency Graph**:
|
||||
\`\`\`
|
||||
[High-level dependency visualization]
|
||||
\`\`\`
|
||||
|
||||
**Critical Path**: [Identify bottleneck tasks]
|
||||
|
||||
### Testing Strategy
|
||||
**Testing Approach**:
|
||||
- Unit testing: [Tools, scope]
|
||||
- Integration testing: [Key integration points]
|
||||
- E2E testing: [Critical user flows]
|
||||
|
||||
**Coverage Targets**:
|
||||
- Lines: ≥70%
|
||||
- Functions: ≥70%
|
||||
- Branches: ≥65%
|
||||
|
||||
**Quality Gates**:
|
||||
- [CI/CD gates]
|
||||
- [Performance budgets]
|
||||
|
||||
## 5. Task Breakdown Summary
|
||||
|
||||
### Task Count
|
||||
**{N} tasks** (flat hierarchy | two-level hierarchy, sequential | parallel execution)
|
||||
|
||||
### Task Structure
|
||||
- **IMPL-1**: [Main task title]
|
||||
- **IMPL-2**: [Main task title]
|
||||
...
|
||||
|
||||
### Complexity Assessment
|
||||
- **High**: [List with rationale]
|
||||
- **Medium**: [List]
|
||||
- **Low**: [List]
|
||||
|
||||
### Dependencies
|
||||
[Reference Section 4.3 for dependency graph]
|
||||
|
||||
**Parallelization Opportunities**:
|
||||
- [Specific task groups that can run in parallel]
|
||||
|
||||
## 6. Implementation Plan (Detailed Phased Breakdown)
|
||||
|
||||
### Execution Strategy
|
||||
|
||||
**Phase 1 (Weeks 1-2): [Phase Name]**
|
||||
- **Tasks**: IMPL-1, IMPL-2
|
||||
- **Deliverables**:
|
||||
- [Specific deliverable 1]
|
||||
- [Specific deliverable 2]
|
||||
- **Success Criteria**:
|
||||
- [Measurable criterion]
|
||||
|
||||
**Phase 2 (Weeks 3-N): [Phase Name]**
|
||||
...
|
||||
|
||||
### Resource Requirements
|
||||
|
||||
**Development Team**:
|
||||
- [Team composition and skills]
|
||||
|
||||
**External Dependencies**:
|
||||
- [Third-party services, APIs]
|
||||
|
||||
**Infrastructure**:
|
||||
- [Development, staging, production environments]
|
||||
|
||||
## 7. Risk Assessment & Mitigation
|
||||
|
||||
| Risk | Impact | Probability | Mitigation Strategy | Owner |
|
||||
|------|--------|-------------|---------------------|-------|
|
||||
| [Risk description] | High/Med/Low | High/Med/Low | [Strategy] | [Role] |
|
||||
|
||||
**Critical Risks** (High impact + High probability):
|
||||
- [Risk 1]: [Detailed mitigation plan]
|
||||
|
||||
**Monitoring Strategy**:
|
||||
- [How risks will be monitored]
|
||||
|
||||
## 8. Success Criteria
|
||||
|
||||
**Functional Completeness**:
|
||||
- [ ] All requirements from synthesis-specification.md implemented
|
||||
- [ ] All acceptance criteria from task.json files met
|
||||
|
||||
**Technical Quality**:
|
||||
- [ ] Test coverage ≥70%
|
||||
- [ ] Bundle size within budget
|
||||
- [ ] Performance targets met
|
||||
|
||||
**Operational Readiness**:
|
||||
- [ ] CI/CD pipeline operational
|
||||
- [ ] Monitoring and logging configured
|
||||
- [ ] Documentation complete
|
||||
|
||||
**Business Metrics**:
|
||||
- [ ] [Key business metrics from synthesis]
|
||||
\`\`\`
|
||||
|
||||
#### 3. TODO_LIST.md
|
||||
|
||||
@@ -305,27 +305,279 @@ For each feature, generate 3 tasks with ID format:
|
||||
|
||||
### Phase 4: Unified IMPL_PLAN.md Generation
|
||||
|
||||
Generate single comprehensive IMPL_PLAN.md with:
|
||||
Generate single comprehensive IMPL_PLAN.md with enhanced 8-section structure:
|
||||
|
||||
**Frontmatter**:
|
||||
```yaml
|
||||
---
|
||||
identifier: WFS-{session-id}
|
||||
workflow_type: "tdd"
|
||||
source: "User requirements" | "File: path" | "Issue: ISS-001"
|
||||
analysis: .workflow/{session-id}/.process/ANALYSIS_RESULTS.md
|
||||
artifacts: .workflow/{session-id}/.brainstorming/
|
||||
context_package: .workflow/{session-id}/.process/context-package.json # CCW smart context
|
||||
workflow_type: "tdd" # TDD-specific workflow
|
||||
verification_history: # CCW quality gates
|
||||
concept_verify: "passed | skipped | pending"
|
||||
action_plan_verify: "pending"
|
||||
phase_progression: "brainstorm → context → test_context → analysis → concept_verify → tdd_planning" # TDD workflow phases
|
||||
feature_count: N
|
||||
task_count: 3N
|
||||
tdd_chains: N
|
||||
---
|
||||
```
|
||||
|
||||
**Structure**:
|
||||
1. **Summary**: Project overview
|
||||
2. **TDD Task Chains** (TDD-specific section):
|
||||
- Visual representation of TEST → IMPL → REFACTOR chains
|
||||
- Feature-by-feature breakdown with phase indicators
|
||||
3. **Task Breakdown**: Standard task listing
|
||||
4. **Implementation Strategy**: Execution approach
|
||||
5. **Success Criteria**: Acceptance conditions
|
||||
**Complete Structure** (8 Sections):
|
||||
|
||||
```markdown
|
||||
# Implementation Plan: {Project Title}
|
||||
|
||||
## 1. Summary
|
||||
Core requirements, objectives, and TDD-specific technical approach (2-3 paragraphs max).
|
||||
|
||||
**Core Objectives**:
|
||||
- [Key objective 1]
|
||||
- [Key objective 2]
|
||||
|
||||
**Technical Approach**:
|
||||
- TDD-driven development with Red-Green-Refactor cycles
|
||||
- [Other high-level approaches]
|
||||
|
||||
## 2. Context Analysis
|
||||
|
||||
### CCW Workflow Context
|
||||
**Phase Progression** (TDD-specific):
|
||||
- ✅ Phase 1: Brainstorming (synthesis-specification.md generated)
|
||||
- ✅ Phase 2: Context Gathering (context-package.json: {N} files, {M} modules analyzed)
|
||||
- ✅ Phase 3: Test Coverage Analysis (test-context-package.json: existing test patterns identified)
|
||||
- ✅ Phase 4: TDD Analysis (ANALYSIS_RESULTS.md: test-first requirements with Gemini/Qwen insights)
|
||||
- ✅ Phase 5: Concept Verification ({X} clarifications answered, test requirements clarified | skipped)
|
||||
- ⏳ Phase 6: TDD Task Generation (current phase - generating IMPL_PLAN.md with TDD chains)
|
||||
|
||||
**Quality Gates**:
|
||||
- concept-verify: ✅ Passed (test requirements clarified, 0 ambiguities) | ⏭️ Skipped (user decision) | ⏳ Pending
|
||||
- action-plan-verify: ⏳ Pending (recommended before /workflow:execute for TDD dependency validation)
|
||||
|
||||
**Context Package Summary**:
|
||||
- **Focus Paths**: {list key directories from context-package.json}
|
||||
- **Key Files**: {list primary files for modification}
|
||||
- **Test Context**: {existing test patterns, coverage baseline, test framework detected}
|
||||
- **Module Depth Analysis**: {from get_modules_by_depth.sh output}
|
||||
- **Smart Context**: {total file count} files, {module count} modules, {test file count} tests identified
|
||||
|
||||
### Project Profile
|
||||
- **Type**: Greenfield/Enhancement/Refactor
|
||||
- **Scale**: User count, data volume, complexity
|
||||
- **Tech Stack**: Primary technologies
|
||||
- **Timeline**: Duration and milestones
|
||||
- **TDD Framework**: Testing framework and tools
|
||||
|
||||
### Module Structure
|
||||
```
|
||||
[Directory tree showing key modules and test directories]
|
||||
```
|
||||
|
||||
### Dependencies
|
||||
**Primary**: [Core libraries and frameworks]
|
||||
**Testing**: [Test framework, mocking libraries]
|
||||
**Development**: [Linting, CI/CD tools]
|
||||
|
||||
### Patterns & Conventions
|
||||
- **Architecture**: [Key patterns]
|
||||
- **Testing Patterns**: [Unit, integration, E2E patterns]
|
||||
- **Code Style**: [Naming, TypeScript coverage]
|
||||
|
||||
## 3. Brainstorming Artifacts Reference
|
||||
|
||||
### Artifact Usage Strategy
|
||||
**Primary Reference (synthesis-specification.md)**:
|
||||
- **What**: Comprehensive implementation blueprint from multi-role synthesis
|
||||
- **When**: Every TDD task (TEST/IMPL/REFACTOR) references this for requirements and acceptance criteria
|
||||
- **How**: Extract testable requirements, architecture decisions, expected behaviors
|
||||
- **Priority**: Authoritative - defines what to test and how to implement
|
||||
- **CCW Value**: Consolidates insights from all brainstorming roles into single source of truth for TDD
|
||||
|
||||
**Context Intelligence (context-package.json & test-context-package.json)**:
|
||||
- **What**: Smart context from CCW's context-gather and test-context-gather phases
|
||||
- **Content**: Focus paths, dependency graph, existing test patterns, test framework configuration
|
||||
- **Usage**: RED phase loads test patterns, GREEN phase loads implementation context
|
||||
- **CCW Value**: Automated discovery of existing tests and patterns for TDD consistency
|
||||
|
||||
**Technical Analysis (ANALYSIS_RESULTS.md)**:
|
||||
- **What**: Gemini/Qwen parallel analysis with TDD-specific breakdown
|
||||
- **Content**: Testable requirements, test scenarios, implementation strategies, risk assessment
|
||||
- **Usage**: RED phase references test cases, GREEN phase references implementation approach
|
||||
- **CCW Value**: Multi-model analysis providing comprehensive TDD guidance
|
||||
|
||||
### Integrated Specifications (Highest Priority)
|
||||
- **synthesis-specification.md**: Comprehensive implementation blueprint
|
||||
- Contains: Architecture design, functional/non-functional requirements
|
||||
|
||||
### Supporting Artifacts (Reference)
|
||||
- **topic-framework.md**: Discussion framework
|
||||
- **system-architect/analysis.md**: Architecture specifications
|
||||
- **Role-specific analyses**: [Other relevant analyses]
|
||||
|
||||
**Artifact Priority in Development**:
|
||||
1. synthesis-specification.md (primary reference for test cases and implementation)
|
||||
2. test-context-package.json (existing test patterns for TDD consistency)
|
||||
3. context-package.json (smart context for execution environment)
|
||||
4. ANALYSIS_RESULTS.md (technical analysis with TDD breakdown)
|
||||
5. Role-specific analyses (supplementary)
|
||||
|
||||
## 4. Implementation Strategy
|
||||
|
||||
### Execution Strategy
|
||||
**Execution Model**: TDD Cycles (Red-Green-Refactor)
|
||||
|
||||
**Rationale**: Test-first approach ensures correctness and reduces bugs
|
||||
|
||||
**TDD Cycle Pattern**:
|
||||
- RED: Write failing test
|
||||
- GREEN: Implement minimal code to pass (with test-fix cycle if needed)
|
||||
- REFACTOR: Improve code quality while keeping tests green
|
||||
|
||||
**Parallelization Opportunities**:
|
||||
- [Independent features that can be developed in parallel]
|
||||
|
||||
### Architectural Approach
|
||||
**Key Architecture Decisions**:
|
||||
- [ADR references from synthesis]
|
||||
- [TDD-compatible architecture patterns]
|
||||
|
||||
**Integration Strategy**:
|
||||
- [How modules communicate]
|
||||
- [Test isolation strategy]
|
||||
|
||||
### Key Dependencies
|
||||
**Task Dependency Graph**:
|
||||
```
|
||||
Feature 1:
|
||||
TEST-1.1 (RED)
|
||||
↓
|
||||
IMPL-1.1 (GREEN) [with test-fix cycle]
|
||||
↓
|
||||
REFACTOR-1.1 (REFACTOR)
|
||||
|
||||
Feature 2:
|
||||
TEST-2.1 (RED) [depends on REFACTOR-1.1 if related]
|
||||
↓
|
||||
IMPL-2.1 (GREEN)
|
||||
↓
|
||||
REFACTOR-2.1 (REFACTOR)
|
||||
```
|
||||
|
||||
**Critical Path**: [Identify bottleneck features]
|
||||
|
||||
### Testing Strategy
|
||||
**TDD Testing Approach**:
|
||||
- Unit testing: Each feature has comprehensive unit tests
|
||||
- Integration testing: Cross-feature integration
|
||||
- E2E testing: Critical user flows after all TDD cycles
|
||||
|
||||
**Coverage Targets**:
|
||||
- Lines: ≥80% (TDD ensures high coverage)
|
||||
- Functions: ≥80%
|
||||
- Branches: ≥75%
|
||||
|
||||
**Quality Gates**:
|
||||
- All tests must pass before moving to next phase
|
||||
- Refactor phase must maintain test success
|
||||
|
||||
## 5. TDD Task Chains (TDD-Specific Section)
|
||||
|
||||
### Feature-by-Feature TDD Chains
|
||||
|
||||
**Feature 1: {Feature Name}**
|
||||
```
|
||||
🔴 TEST-1.1: Write failing test for {feature}
|
||||
↓
|
||||
🟢 IMPL-1.1: Implement to pass tests (includes test-fix cycle: max 3 iterations)
|
||||
↓
|
||||
🔵 REFACTOR-1.1: Refactor implementation while keeping tests green
|
||||
```
|
||||
|
||||
**Feature 2: {Feature Name}**
|
||||
```
|
||||
🔴 TEST-2.1: Write failing test for {feature}
|
||||
↓
|
||||
🟢 IMPL-2.1: Implement to pass tests (includes test-fix cycle)
|
||||
↓
|
||||
🔵 REFACTOR-2.1: Refactor implementation
|
||||
```
|
||||
|
||||
[Continue for all N features]
|
||||
|
||||
### TDD Task Breakdown Summary
|
||||
- **Total Features**: {N}
|
||||
- **Total Tasks**: {3N} (N TEST + N IMPL + N REFACTOR)
|
||||
- **TDD Chains**: {N}
|
||||
|
||||
## 6. Implementation Plan (Detailed Phased Breakdown)
|
||||
|
||||
### Execution Strategy
|
||||
|
||||
**TDD Cycle Execution**: Feature-by-feature sequential TDD cycles
|
||||
|
||||
**Phase 1 (Weeks 1-2): Foundation Features**
|
||||
- **Features**: Feature 1, Feature 2
|
||||
- **Tasks**: TEST-1.1, IMPL-1.1, REFACTOR-1.1, TEST-2.1, IMPL-2.1, REFACTOR-2.1
|
||||
- **Deliverables**:
|
||||
- Complete TDD cycles for foundation features
|
||||
- All tests passing
|
||||
- **Success Criteria**:
|
||||
- ≥80% test coverage
|
||||
- All RED-GREEN-REFACTOR cycles completed
|
||||
|
||||
**Phase 2 (Weeks 3-N): Advanced Features**
|
||||
[Continue with remaining features]
|
||||
|
||||
### Resource Requirements
|
||||
|
||||
**Development Team**:
|
||||
- [Team composition with TDD experience]
|
||||
|
||||
**External Dependencies**:
|
||||
- [Testing frameworks, mocking services]
|
||||
|
||||
**Infrastructure**:
|
||||
- [CI/CD with test automation]
|
||||
|
||||
## 7. Risk Assessment & Mitigation
|
||||
|
||||
| Risk | Impact | Probability | Mitigation Strategy | Owner |
|
||||
|------|--------|-------------|---------------------|-------|
|
||||
| Tests fail repeatedly in GREEN phase | High | Medium | Test-fix cycle (max 3 iterations) with auto-revert | Dev Team |
|
||||
| Complex features hard to test | High | Medium | Break down into smaller testable units | Architect |
|
||||
| [Other risks] | Med/Low | Med/Low | [Strategies] | [Owner] |
|
||||
|
||||
**Critical Risks** (TDD-Specific):
|
||||
- **GREEN phase failures**: Mitigated by test-fix cycle with Gemini diagnosis
|
||||
- **Test coverage gaps**: Mitigated by TDD-first approach ensuring tests before code
|
||||
|
||||
**Monitoring Strategy**:
|
||||
- Track TDD cycle completion rate
|
||||
- Monitor test success rate per iteration
|
||||
|
||||
## 8. Success Criteria
|
||||
|
||||
**Functional Completeness**:
|
||||
- [ ] All features implemented through TDD cycles
|
||||
- [ ] All RED-GREEN-REFACTOR cycles completed successfully
|
||||
|
||||
**Technical Quality**:
|
||||
- [ ] Test coverage ≥80% (ensured by TDD)
|
||||
- [ ] All tests passing (GREEN state achieved)
|
||||
- [ ] Code refactored for quality (REFACTOR phase completed)
|
||||
|
||||
**Operational Readiness**:
|
||||
- [ ] CI/CD pipeline with automated test execution
|
||||
- [ ] Test failure alerting configured
|
||||
|
||||
**TDD Compliance**:
|
||||
- [ ] Every feature has TEST → IMPL → REFACTOR chain
|
||||
- [ ] No implementation without tests (RED-first principle)
|
||||
- [ ] Refactoring did not break tests
|
||||
```
|
||||
|
||||
### Phase 5: TODO_LIST.md Generation
|
||||
|
||||
|
||||
@@ -240,33 +240,229 @@ Generate task JSON files and IMPL_PLAN.md from analysis results with automatic a
|
||||
identifier: WFS-{session-id}
|
||||
source: "User requirements" | "File: path" | "Issue: ISS-001"
|
||||
analysis: .workflow/{session-id}/.process/ANALYSIS_RESULTS.md
|
||||
artifacts: .workflow/{session-id}/.brainstorming/
|
||||
context_package: .workflow/{session-id}/.process/context-package.json # CCW smart context
|
||||
workflow_type: "standard | tdd | design" # Indicates execution model
|
||||
verification_history: # CCW quality gates
|
||||
concept_verify: "passed | skipped | pending"
|
||||
action_plan_verify: "pending"
|
||||
phase_progression: "brainstorm → context → analysis → concept_verify → planning" # CCW workflow phases
|
||||
---
|
||||
|
||||
# Implementation Plan: {Project Title}
|
||||
|
||||
## Summary
|
||||
Core requirements, objectives, and technical approach.
|
||||
## 1. Summary
|
||||
Core requirements, objectives, technical approach summary (2-3 paragraphs max).
|
||||
|
||||
## Context Analysis
|
||||
- **Project**: Type, patterns, tech stack
|
||||
- **Modules**: Components and integration points
|
||||
- **Dependencies**: External libraries and constraints
|
||||
- **Patterns**: Code conventions and guidelines
|
||||
**Core Objectives**:
|
||||
- [Key objective 1]
|
||||
- [Key objective 2]
|
||||
|
||||
## Brainstorming Artifacts
|
||||
- synthesis-specification.md (Highest priority)
|
||||
- topic-framework.md (Medium priority)
|
||||
- Role analyses: ui-designer, system-architect, etc.
|
||||
**Technical Approach**:
|
||||
- [High-level approach]
|
||||
|
||||
## Task Breakdown
|
||||
- **Task Count**: N tasks, complexity level
|
||||
- **Hierarchy**: Flat/Two-level structure
|
||||
- **Dependencies**: Task dependency graph
|
||||
## 2. Context Analysis
|
||||
|
||||
## Implementation Plan
|
||||
- **Execution Strategy**: Sequential/Parallel approach
|
||||
- **Resource Requirements**: Tools, dependencies, artifacts
|
||||
- **Success Criteria**: Metrics and acceptance conditions
|
||||
### CCW Workflow Context
|
||||
**Phase Progression**:
|
||||
- ✅ Phase 1: Brainstorming (synthesis-specification.md generated)
|
||||
- ✅ Phase 2: Context Gathering (context-package.json: {N} files, {M} modules analyzed)
|
||||
- ✅ Phase 3: Enhanced Analysis (ANALYSIS_RESULTS.md: Gemini/Qwen/Codex parallel insights)
|
||||
- ✅ Phase 4: Concept Verification ({X} clarifications answered, synthesis updated | skipped)
|
||||
- ⏳ Phase 5: Action Planning (current phase - generating IMPL_PLAN.md)
|
||||
|
||||
**Quality Gates**:
|
||||
- concept-verify: ✅ Passed (0 ambiguities remaining) | ⏭️ Skipped (user decision) | ⏳ Pending
|
||||
- action-plan-verify: ⏳ Pending (recommended before /workflow:execute)
|
||||
|
||||
**Context Package Summary**:
|
||||
- **Focus Paths**: {list key directories from context-package.json}
|
||||
- **Key Files**: {list primary files for modification}
|
||||
- **Module Depth Analysis**: {from get_modules_by_depth.sh output}
|
||||
- **Smart Context**: {total file count} files, {module count} modules, {dependency count} dependencies identified
|
||||
|
||||
### Project Profile
|
||||
- **Type**: Greenfield/Enhancement/Refactor
|
||||
- **Scale**: User count, data volume, complexity
|
||||
- **Tech Stack**: Primary technologies
|
||||
- **Timeline**: Duration and milestones
|
||||
|
||||
### Module Structure
|
||||
```
|
||||
[Directory tree showing key modules]
|
||||
```
|
||||
|
||||
### Dependencies
|
||||
**Primary**: [Core libraries and frameworks]
|
||||
**APIs**: [External services]
|
||||
**Development**: [Testing, linting, CI/CD tools]
|
||||
|
||||
### Patterns & Conventions
|
||||
- **Architecture**: [Key patterns like DI, Event-Driven]
|
||||
- **Component Design**: [Design patterns]
|
||||
- **State Management**: [State strategy]
|
||||
- **Code Style**: [Naming, TypeScript coverage]
|
||||
|
||||
## 3. Brainstorming Artifacts Reference
|
||||
|
||||
### Artifact Usage Strategy
|
||||
**Primary Reference (synthesis-specification.md)**:
|
||||
- **What**: Comprehensive implementation blueprint from multi-role synthesis
|
||||
- **When**: Every task references this first for requirements and design decisions
|
||||
- **How**: Extract architecture decisions, UI/UX patterns, functional requirements, non-functional requirements
|
||||
- **Priority**: Authoritative - overrides role-specific analyses when conflicts arise
|
||||
- **CCW Value**: Consolidates insights from all brainstorming roles into single source of truth
|
||||
|
||||
**Context Intelligence (context-package.json)**:
|
||||
- **What**: Smart context gathered by CCW's context-gather phase
|
||||
- **Content**: Focus paths, dependency graph, existing patterns, module structure
|
||||
- **Usage**: Tasks load this via `flow_control.preparatory_steps` for environment setup
|
||||
- **CCW Value**: Automated intelligent context discovery replacing manual file exploration
|
||||
|
||||
**Technical Analysis (ANALYSIS_RESULTS.md)**:
|
||||
- **What**: Gemini/Qwen/Codex parallel analysis results
|
||||
- **Content**: Optimization strategies, risk assessment, architecture review, implementation patterns
|
||||
- **Usage**: Referenced in task planning for technical guidance and risk mitigation
|
||||
- **CCW Value**: Multi-model parallel analysis providing comprehensive technical intelligence
|
||||
|
||||
### Integrated Specifications (Highest Priority)
|
||||
- **synthesis-specification.md**: Comprehensive implementation blueprint
|
||||
- Contains: Architecture design, UI/UX guidelines, functional/non-functional requirements, implementation roadmap, risk assessment
|
||||
|
||||
### Supporting Artifacts (Reference)
|
||||
- **topic-framework.md**: Role-specific discussion points and analysis framework
|
||||
- **system-architect/analysis.md**: Detailed architecture specifications
|
||||
- **ui-designer/analysis.md**: Layout and component specifications
|
||||
- **product-manager/analysis.md**: Product vision and user stories
|
||||
|
||||
**Artifact Priority in Development**:
|
||||
1. synthesis-specification.md (primary reference for all tasks)
|
||||
2. context-package.json (smart context for execution environment)
|
||||
3. ANALYSIS_RESULTS.md (technical analysis and optimization strategies)
|
||||
4. Role-specific analyses (fallback for detailed specifications)
|
||||
|
||||
## 4. Implementation Strategy
|
||||
|
||||
### Execution Strategy
|
||||
**Execution Model**: [Sequential | Parallel | Phased | TDD Cycles]
|
||||
|
||||
**Rationale**: [Why this execution model fits the project]
|
||||
|
||||
**Parallelization Opportunities**:
|
||||
- [List independent workstreams]
|
||||
|
||||
**Serialization Requirements**:
|
||||
- [List critical dependencies]
|
||||
|
||||
### Architectural Approach
|
||||
**Key Architecture Decisions**:
|
||||
- [ADR references from synthesis]
|
||||
- [Justification for architecture patterns]
|
||||
|
||||
**Integration Strategy**:
|
||||
- [How modules communicate]
|
||||
- [State management approach]
|
||||
|
||||
### Key Dependencies
|
||||
**Task Dependency Graph**:
|
||||
```
|
||||
[High-level dependency visualization]
|
||||
```
|
||||
|
||||
**Critical Path**: [Identify bottleneck tasks]
|
||||
|
||||
### Testing Strategy
|
||||
**Testing Approach**:
|
||||
- Unit testing: [Tools, scope]
|
||||
- Integration testing: [Key integration points]
|
||||
- E2E testing: [Critical user flows]
|
||||
|
||||
**Coverage Targets**:
|
||||
- Lines: ≥70%
|
||||
- Functions: ≥70%
|
||||
- Branches: ≥65%
|
||||
|
||||
**Quality Gates**:
|
||||
- [CI/CD gates]
|
||||
- [Performance budgets]
|
||||
|
||||
## 5. Task Breakdown Summary
|
||||
|
||||
### Task Count
|
||||
**{N} tasks** (flat hierarchy | two-level hierarchy, sequential | parallel execution)
|
||||
|
||||
### Task Structure
|
||||
- **IMPL-1**: [Main task title]
|
||||
- **IMPL-2**: [Main task title]
|
||||
...
|
||||
|
||||
### Complexity Assessment
|
||||
- **High**: [List with rationale]
|
||||
- **Medium**: [List]
|
||||
- **Low**: [List]
|
||||
|
||||
### Dependencies
|
||||
[Reference Section 4.3 for dependency graph]
|
||||
|
||||
**Parallelization Opportunities**:
|
||||
- [Specific task groups that can run in parallel]
|
||||
|
||||
## 6. Implementation Plan (Detailed Phased Breakdown)
|
||||
|
||||
### Execution Strategy
|
||||
|
||||
**Phase 1 (Weeks 1-2): [Phase Name]**
|
||||
- **Tasks**: IMPL-1, IMPL-2
|
||||
- **Deliverables**:
|
||||
- [Specific deliverable 1]
|
||||
- [Specific deliverable 2]
|
||||
- **Success Criteria**:
|
||||
- [Measurable criterion]
|
||||
|
||||
**Phase 2 (Weeks 3-N): [Phase Name]**
|
||||
...
|
||||
|
||||
### Resource Requirements
|
||||
|
||||
**Development Team**:
|
||||
- [Team composition and skills]
|
||||
|
||||
**External Dependencies**:
|
||||
- [Third-party services, APIs]
|
||||
|
||||
**Infrastructure**:
|
||||
- [Development, staging, production environments]
|
||||
|
||||
## 7. Risk Assessment & Mitigation
|
||||
|
||||
| Risk | Impact | Probability | Mitigation Strategy | Owner |
|
||||
|------|--------|-------------|---------------------|-------|
|
||||
| [Risk description] | High/Med/Low | High/Med/Low | [Strategy] | [Role] |
|
||||
|
||||
**Critical Risks** (High impact + High probability):
|
||||
- [Risk 1]: [Detailed mitigation plan]
|
||||
|
||||
**Monitoring Strategy**:
|
||||
- [How risks will be monitored]
|
||||
|
||||
## 8. Success Criteria
|
||||
|
||||
**Functional Completeness**:
|
||||
- [ ] All requirements from synthesis-specification.md implemented
|
||||
- [ ] All acceptance criteria from task.json files met
|
||||
|
||||
**Technical Quality**:
|
||||
- [ ] Test coverage ≥70%
|
||||
- [ ] Bundle size within budget
|
||||
- [ ] Performance targets met
|
||||
|
||||
**Operational Readiness**:
|
||||
- [ ] CI/CD pipeline operational
|
||||
- [ ] Monitoring and logging configured
|
||||
- [ ] Documentation complete
|
||||
|
||||
**Business Metrics**:
|
||||
- [ ] [Key business metrics from synthesis]
|
||||
```
|
||||
|
||||
### Phase 5: TODO_LIST.md Generation
|
||||
|
||||
235
.github/release-notes-v3.5.0.md
vendored
Normal file
235
.github/release-notes-v3.5.0.md
vendored
Normal file
@@ -0,0 +1,235 @@
|
||||
# 🎨 UI Design Workflow with Triple Vision Analysis & Interactive Preview
|
||||
|
||||
This release introduces a comprehensive UI design workflow system with triple vision analysis capabilities, interactive user checkpoints, zero agent overhead, and enhanced preview tools for real-time prototype comparison.
|
||||
|
||||
## 🌟 Major Features
|
||||
|
||||
### UI Design Workflow System
|
||||
- **`/workflow:design:auto`**: Semi-autonomous workflow orchestrator with interactive checkpoints
|
||||
- **`/workflow:design:style-extract`**: Triple vision analysis (Claude Code + Gemini + Codex)
|
||||
- **`/workflow:design:style-consolidate`**: Token validation and style guide generation
|
||||
- **`/workflow:design:ui-generate`**: Token-driven HTML/CSS prototype generation with preview tools
|
||||
- **`/workflow:design:design-update`**: Design system integration into brainstorming artifacts
|
||||
|
||||
### 👁️ Triple Vision Analysis
|
||||
- **Claude Code**: Quick initial visual analysis using native Read tool
|
||||
- **Gemini Vision**: Deep semantic understanding of design intent
|
||||
- **Codex Vision**: Structured pattern recognition with -i parameter
|
||||
- **Consensus Synthesis**: Weighted combination strategy for robust results
|
||||
|
||||
### ⏸️ Interactive Checkpoints
|
||||
- **Checkpoint 1**: User selects preferred style variants after extraction
|
||||
- **Checkpoint 2**: User confirms selected prototypes before design update
|
||||
- Pause-and-continue pattern for critical design decisions
|
||||
|
||||
### 🌐 Preview Enhancement System (NEW!)
|
||||
- **`index.html`**: Master preview navigation with grid layout
|
||||
- **`compare.html`**: Side-by-side comparison with responsive viewport toggles
|
||||
- **`PREVIEW.md`**: Comprehensive preview instructions and server setup guide
|
||||
- Synchronized scrolling for layout comparison
|
||||
- Dynamic page switching and real-time responsive testing
|
||||
|
||||
### 🎯 Zero Agent Overhead
|
||||
- Removed Task(conceptual-planning-agent) wrappers from design commands
|
||||
- Direct bash execution for gemini-wrapper and codex commands
|
||||
- Improved performance while preserving all functionality
|
||||
|
||||
## 🚀 Quick Start
|
||||
|
||||
### Complete Design Workflow
|
||||
```bash
|
||||
# Semi-autonomous workflow with user checkpoints
|
||||
/workflow:design:auto --session WFS-auth --images "design-refs/*.png" --pages "login,register" --batch-plan
|
||||
```
|
||||
|
||||
### Individual Commands
|
||||
```bash
|
||||
# Extract design styles (triple vision analysis)
|
||||
/workflow:design:style-extract --session WFS-auth --images "refs/*.png"
|
||||
|
||||
# Consolidate selected variants
|
||||
/workflow:design:style-consolidate --session WFS-auth --variants "variant-1,variant-3"
|
||||
|
||||
# Generate prototypes with preview tools
|
||||
/workflow:design:ui-generate --session WFS-auth --pages "login,register" --variants 2
|
||||
|
||||
# Preview generated prototypes
|
||||
cd .workflow/WFS-auth/.design/prototypes
|
||||
python -m http.server 8080 # Visit http://localhost:8080
|
||||
|
||||
# Integrate design system
|
||||
/workflow:design:design-update --session WFS-auth --selected-prototypes "login-variant-1,register-variant-2"
|
||||
```
|
||||
|
||||
## 🎨 Design System Features
|
||||
- **OKLCH Color Format**: Perceptually uniform color space
|
||||
- **W3C Design Tokens**: Standard-compliant token format
|
||||
- **WCAG 2.1 AA Compliance**: Automated accessibility validation
|
||||
- **Style Override Support**: Runtime token customization with --style-overrides
|
||||
- **Batch Task Generation**: Automatic task creation with --batch-plan
|
||||
|
||||
## 📊 Preview Tools
|
||||
|
||||
### Master Navigation (index.html)
|
||||
- Grid layout of all generated prototypes
|
||||
- Quick links to individual variants
|
||||
- Metadata display (session ID, timestamps, page info)
|
||||
- Direct access to implementation notes
|
||||
|
||||
### Side-by-Side Comparison (compare.html)
|
||||
- Iframe-based comparison for multiple variants
|
||||
- Responsive viewport toggles:
|
||||
- Desktop (100%)
|
||||
- Tablet (768px)
|
||||
- Mobile (375px)
|
||||
- Synchronized scrolling option
|
||||
- Dynamic page switching dropdown
|
||||
- Real-time variant comparison
|
||||
|
||||
### Preview Options
|
||||
```bash
|
||||
# Option 1: Direct browser (simplest)
|
||||
cd .workflow/WFS-{session}/.design/prototypes
|
||||
open index.html # or double-click
|
||||
|
||||
# Option 2: Local server (recommended)
|
||||
python -m http.server 8080 # Python
|
||||
npx http-server -p 8080 # Node.js
|
||||
php -S localhost:8080 # PHP
|
||||
# Visit: http://localhost:8080
|
||||
```
|
||||
|
||||
## 📦 What's Included
|
||||
|
||||
### New Commands (5)
|
||||
- `/workflow:design:auto`
|
||||
- `/workflow:design:style-extract`
|
||||
- `/workflow:design:style-consolidate`
|
||||
- `/workflow:design:ui-generate`
|
||||
- `/workflow:design:design-update`
|
||||
|
||||
### Generated Files
|
||||
```
|
||||
.workflow/WFS-{session}/.design/
|
||||
├── style-extraction/
|
||||
│ ├── claude_vision_analysis.json
|
||||
│ ├── gemini_vision_analysis.json
|
||||
│ ├── codex_vision_analysis.json
|
||||
│ ├── semantic_style_analysis.json
|
||||
│ ├── design-tokens.json
|
||||
│ └── style-cards.json
|
||||
├── style-consolidation/
|
||||
│ ├── design-tokens.json (validated)
|
||||
│ ├── style-guide.md
|
||||
│ ├── tailwind.config.js
|
||||
│ └── validation-report.json
|
||||
└── prototypes/
|
||||
├── index.html (NEW - preview navigation)
|
||||
├── compare.html (NEW - side-by-side comparison)
|
||||
├── PREVIEW.md (NEW - setup instructions)
|
||||
├── {page}-variant-{n}.html
|
||||
├── {page}-variant-{n}.css
|
||||
└── design-tokens.css
|
||||
```
|
||||
|
||||
## 🔄 Workflow Integration
|
||||
|
||||
Design phase fits seamlessly between brainstorming and planning:
|
||||
|
||||
```
|
||||
Brainstorming → UI Design → Planning → Execution
|
||||
↓ ↓ ↓ ↓
|
||||
synthesis- design-tokens tasks with token-driven
|
||||
specification + style design implementation
|
||||
guide context
|
||||
```
|
||||
|
||||
**Optional but recommended** for UI-heavy projects:
|
||||
- User-facing applications
|
||||
- Design system creation
|
||||
- Brand-critical interfaces
|
||||
- Accessibility compliance projects
|
||||
|
||||
## 💡 Benefits
|
||||
|
||||
### User Experience
|
||||
- 🎨 Visual validation before implementation
|
||||
- ⏸️ Interactive control at critical decision points
|
||||
- 👁️ Comprehensive analysis from three AI vision sources
|
||||
- 🌐 Real-time preview with comparison tools
|
||||
- 🎯 Zero waiting with direct bash execution
|
||||
|
||||
### Code Quality
|
||||
- 🔒 100% CSS values use custom properties
|
||||
- ♿ WCAG AA validated at design phase
|
||||
- 🎨 Single source of truth for visual design
|
||||
- 🧪 Production-ready prototypes (semantic HTML5, responsive, accessible)
|
||||
|
||||
### Development Workflow
|
||||
- 🔄 Seamless integration with existing workflow
|
||||
- 🚀 Backward compatible (design phase optional)
|
||||
- 📊 Better planning with design system context
|
||||
- 🎯 Focused implementation from validated prototypes
|
||||
|
||||
## 📚 Documentation
|
||||
|
||||
- **README.md**: Updated with UI Design Workflow section
|
||||
- **README_CN.md**: Chinese documentation for design workflow
|
||||
- **CHANGELOG.md**: Comprehensive release notes with examples
|
||||
- **Command Files**: Detailed implementation guides for all 5 commands
|
||||
|
||||
## 🔧 Technical Details
|
||||
|
||||
**Triple Vision Analysis Flow**:
|
||||
```
|
||||
Reference Images
|
||||
↓
|
||||
Claude Code (Read tool) → claude_vision_analysis.json
|
||||
Gemini Vision (wrapper) → gemini_vision_analysis.json
|
||||
Codex Vision (codex -i) → codex_vision_analysis.json
|
||||
↓
|
||||
Main Claude Synthesis → semantic_style_analysis.json
|
||||
↓
|
||||
Codex Token Generation → design-tokens.json, style-cards.json
|
||||
```
|
||||
|
||||
**Checkpoint Workflow Pattern**:
|
||||
```
|
||||
User: /workflow:design:auto --session WFS-xxx --images "refs/*.png" --pages "dashboard"
|
||||
↓
|
||||
Phase 1: style-extract (automatic)
|
||||
↓ [CHECKPOINT 1: User selects variants]
|
||||
User: /workflow:design:style-consolidate --session WFS-xxx --variants "variant-1"
|
||||
↓
|
||||
Phase 3: ui-generate (automatic)
|
||||
↓ [CHECKPOINT 2: User confirms prototypes]
|
||||
User: /workflow:design:design-update --session WFS-xxx --selected-prototypes "dashboard-variant-1"
|
||||
↓
|
||||
Phase 5: batch-plan (optional, if --batch-plan flag)
|
||||
```
|
||||
|
||||
## 🆙 Upgrade Instructions
|
||||
|
||||
```bash
|
||||
# Windows (PowerShell)
|
||||
Invoke-Expression (Invoke-WebRequest -Uri "https://raw.githubusercontent.com/catlog22/Claude-Code-Workflow/main/install-remote.ps1" -UseBasicParsing).Content
|
||||
|
||||
# Linux/macOS (Bash/Zsh)
|
||||
bash <(curl -fsSL https://raw.githubusercontent.com/catlog22/Claude-Code-Workflow/main/install-remote.sh)
|
||||
```
|
||||
|
||||
## 🐛 Bug Fixes & Improvements
|
||||
- Optimized agent architecture by removing unnecessary wrappers
|
||||
- Improved execution performance with direct bash commands
|
||||
- Enhanced documentation consistency across English and Chinese versions
|
||||
- Updated phase numbering to accommodate new design phase
|
||||
|
||||
## 📝 Full Changelog
|
||||
See [CHANGELOG.md](https://github.com/catlog22/Claude-Code-Workflow/blob/main/CHANGELOG.md) for complete details.
|
||||
|
||||
---
|
||||
|
||||
**Questions or Issues?**
|
||||
- 📖 [Documentation](https://github.com/catlog22/Claude-Code-Workflow)
|
||||
- 🐛 [Report Issues](https://github.com/catlog22/Claude-Code-Workflow/issues)
|
||||
- 💬 [Discussions](https://github.com/catlog22/Claude-Code-Workflow/discussions)
|
||||
3
.gitignore
vendored
3
.gitignore
vendored
@@ -19,4 +19,5 @@ Thumbs.db
|
||||
.env
|
||||
settings.local.json
|
||||
.workflow
|
||||
version.json
|
||||
version.json
|
||||
ref
|
||||
Reference in New Issue
Block a user