catlog22/Claude-Code-Workflow
1
0
Fork 0
mirror of https://github.com/catlog22/Claude-Code-Workflow.git synced 2026-02-11 02:33:51 +08:00
Code Issues Packages Projects Releases Wiki Activity

feat: enhance workflow with CCW-aware IMPL_PLAN.md templates

Browse Source 
- 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
2025-10-07 20:58:11 +08:00
parent 51bd51ea60
commit bd9278bb02
10 changed files with 1764 additions and 64 deletions
Download Patch File Download Diff File Expand all files Collapse all files

421
.claude/commands/workflow/action-plan-verify.md Normal file
View 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}

63
.claude/commands/workflow/brainstorm/synthesis.md
View File

@@ -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 - [ ] **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 - [ ] **Stakeholder Alignment**: Addresses needs and concerns of all key stakeholders
- [ ] **Decision Traceability**: Every major decision traceable to source role analysis via @ references - [ ] **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
View 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}

7
.claude/commands/workflow/plan.md
View File

@@ -143,7 +143,12 @@ Planning complete for session: [sessionId]
Tasks generated: [count] Tasks generated: [count]
Plan: .workflow/[sessionId]/IMPL_PLAN.md 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 ## TodoWrite Pattern

46
.claude/commands/workflow/tdd-plan.md
View File

@@ -26,10 +26,11 @@ allowed-tools: SlashCommand(*), TodoWrite(*), Read(*), Bash(*)
2. **No Preliminary Analysis**: Do not read files before Phase 1 2. **No Preliminary Analysis**: Do not read files before Phase 1
3. **Parse Every Output**: Extract required data for next phase 3. **Parse Every Output**: Extract required data for next phase
4. **Sequential Execution**: Each phase depends on previous output 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 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 ### Phase 1: Session Discovery
**Command**: `/workflow:session:start --auto "TDD: [structured-description]"` **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 **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**: **Command**:
- Manual: `/workflow:tools:task-generate-tdd --session [sessionId]` - Manual: `/workflow:tools:task-generate-tdd --session [sessionId]`
- Agent: `/workflow:tools:task-generate-tdd --session [sessionId] --agent` - 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 tasks include test-fix-cycle configuration
- IMPL_PLAN.md contains workflow_type: "tdd" in frontmatter - IMPL_PLAN.md contains workflow_type: "tdd" in frontmatter
### Phase 6: TDD Structure Validation ### Phase 7: TDD Structure Validation & Action Plan Verification (RECOMMENDED)
**Internal validation (no command)** **Internal validation first, then recommend external verification**
**Validate**: **Internal Validation**:
1. Each feature has TEST → IMPL → REFACTOR chain 1. Each feature has TEST → IMPL → REFACTOR chain
2. Dependencies: IMPL depends_on TEST, REFACTOR depends_on IMPL 2. Dependencies: IMPL depends_on TEST, REFACTOR depends_on IMPL
3. Meta fields: tdd_phase correct ("red"/"green"/"refactor") 3. Meta fields: tdd_phase correct ("red"/"green"/"refactor")
@@ -117,20 +133,26 @@ Structure:
Plan: Plan:
- Unified Implementation Plan: .workflow/[sessionId]/IMPL_PLAN.md - 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 ## TodoWrite Pattern
```javascript ```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 session discovery", status: "in_progress", activeForm: "Executing session discovery"},
{content: "Execute context gathering", status: "pending", activeForm: "Executing context gathering"}, {content: "Execute context gathering", status: "pending", activeForm": "Executing context gathering"},
{content: "Execute test coverage analysis", status: "pending", activeForm: "Executing test coverage analysis"}, {content: "Execute test coverage analysis", status: "pending", activeForm": "Executing test coverage analysis"},
{content: "Execute TDD analysis", status: "pending", activeForm: "Executing TDD 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: "Execute TDD task generation", status: "pending", activeForm: "Executing TDD task generation"},
{content: "Validate TDD structure", status: "pending", activeForm: "Validating TDD structure"} {content: "Validate TDD structure", status: "pending", activeForm: "Validating TDD structure"}
] ]

236
.claude/commands/workflow/tools/task-generate-agent.md
View File

@@ -238,35 +238,231 @@ Task(
\`\`\`markdown \`\`\`markdown
--- ---
identifier: WFS-{session-id} identifier: WFS-{session-id}
source: "User requirements" source: "User requirements" | "File: path" | "Issue: ISS-001"
analysis: .workflow/{session-id}/.process/ANALYSIS_RESULTS.md 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} # Implementation Plan: {Project Title}
## Summary ## 1. Summary
Core requirements, objectives, and technical approach. Core requirements, objectives, technical approach summary (2-3 paragraphs max).
## Context Analysis **Core Objectives**:
- **Project**: Type, patterns, tech stack - [Key objective 1]
- **Modules**: Components and integration points - [Key objective 2]
- **Dependencies**: External libraries and constraints
- **Patterns**: Code conventions and guidelines
## Brainstorming Artifacts **Technical Approach**:
- synthesis-specification.md (Highest priority) - [High-level approach]
- topic-framework.md (Medium priority)
- Role analyses: ui-designer, system-architect, etc.
## Task Breakdown ## 2. Context Analysis
- **Task Count**: N tasks, complexity level
- **Hierarchy**: Flat/Two-level structure
- **Dependencies**: Task dependency graph
## Implementation Plan ### CCW Workflow Context
- **Execution Strategy**: Sequential/Parallel approach **Phase Progression**:
- **Resource Requirements**: Tools, dependencies, artifacts - ✅ Phase 1: Brainstorming (synthesis-specification.md generated)
- **Success Criteria**: Metrics and acceptance conditions - ✅ 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 #### 3. TODO_LIST.md

272
.claude/commands/workflow/tools/task-generate-tdd.md
View File

@@ -305,27 +305,279 @@ For each feature, generate 3 tasks with ID format:
### Phase 4: Unified IMPL_PLAN.md Generation ### 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**: **Frontmatter**:
```yaml ```yaml
--- ---
identifier: WFS-{session-id} 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 feature_count: N
task_count: 3N task_count: 3N
tdd_chains: N tdd_chains: N
--- ---
``` ```
**Structure**: **Complete Structure** (8 Sections):
1. **Summary**: Project overview
2. **TDD Task Chains** (TDD-specific section): ```markdown
- Visual representation of TEST → IMPL → REFACTOR chains # Implementation Plan: {Project Title}
- Feature-by-feature breakdown with phase indicators
3. **Task Breakdown**: Standard task listing ## 1. Summary
4. **Implementation Strategy**: Execution approach Core requirements, objectives, and TDD-specific technical approach (2-3 paragraphs max).
5. **Success Criteria**: Acceptance conditions
**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 ### Phase 5: TODO_LIST.md Generation

234
.claude/commands/workflow/tools/task-generate.md
View File

@@ -240,33 +240,229 @@ Generate task JSON files and IMPL_PLAN.md from analysis results with automatic a
identifier: WFS-{session-id} identifier: WFS-{session-id}
source: "User requirements" | "File: path" | "Issue: ISS-001" source: "User requirements" | "File: path" | "Issue: ISS-001"
analysis: .workflow/{session-id}/.process/ANALYSIS_RESULTS.md 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} # Implementation Plan: {Project Title}
## Summary ## 1. Summary
Core requirements, objectives, and technical approach. Core requirements, objectives, technical approach summary (2-3 paragraphs max).
## Context Analysis **Core Objectives**:
- **Project**: Type, patterns, tech stack - [Key objective 1]
- **Modules**: Components and integration points - [Key objective 2]
- **Dependencies**: External libraries and constraints
- **Patterns**: Code conventions and guidelines
## Brainstorming Artifacts **Technical Approach**:
- synthesis-specification.md (Highest priority) - [High-level approach]
- topic-framework.md (Medium priority)
- Role analyses: ui-designer, system-architect, etc.
## Task Breakdown ## 2. Context Analysis
- **Task Count**: N tasks, complexity level
- **Hierarchy**: Flat/Two-level structure
- **Dependencies**: Task dependency graph
## Implementation Plan ### CCW Workflow Context
- **Execution Strategy**: Sequential/Parallel approach **Phase Progression**:
- **Resource Requirements**: Tools, dependencies, artifacts - ✅ Phase 1: Brainstorming (synthesis-specification.md generated)
- **Success Criteria**: Metrics and acceptance conditions - ✅ 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 ### Phase 5: TODO_LIST.md Generation

235
.github/release-notes-v3.5.0.md vendored Normal file
View 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
View File

@@ -19,4 +19,5 @@ Thumbs.db
.env .env
settings.local.json settings.local.json
.workflow .workflow
version.json version.json
ref