diff --git a/.claude/commands/workflow/action-plan-verify.md b/.claude/commands/workflow/action-plan-verify.md new file mode 100644 index 00000000..67278674 --- /dev/null +++ b/.claude/commands/workflow/action-plan-verify.md @@ -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 ] +argument-hint: "optional: --session " +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 " + 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} diff --git a/.claude/commands/workflow/brainstorm/synthesis.md b/.claude/commands/workflow/brainstorm/synthesis.md index a1de20ea..284536be 100644 --- a/.claude/commands/workflow/brainstorm/synthesis.md +++ b/.claude/commands/workflow/brainstorm/synthesis.md @@ -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 \ No newline at end of file +- [ ] **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. \ No newline at end of file diff --git a/.claude/commands/workflow/concept-verify.md b/.claude/commands/workflow/concept-verify.md new file mode 100644 index 00000000..318d6e75 --- /dev/null +++ b/.claude/commands/workflow/concept-verify.md @@ -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 ] +argument-hint: "optional: --session " +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 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} diff --git a/.claude/commands/workflow/plan.md b/.claude/commands/workflow/plan.md index 2d1ad324..8a18e3d9 100644 --- a/.claude/commands/workflow/plan.md +++ b/.claude/commands/workflow/plan.md @@ -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 diff --git a/.claude/commands/workflow/tdd-plan.md b/.claude/commands/workflow/tdd-plan.md index 36868d88..9f01299b 100644 --- a/.claude/commands/workflow/tdd-plan.md +++ b/.claude/commands/workflow/tdd-plan.md @@ -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"} ] diff --git a/.claude/commands/workflow/tools/task-generate-agent.md b/.claude/commands/workflow/tools/task-generate-agent.md index 2ba89ec6..e36f4150 100644 --- a/.claude/commands/workflow/tools/task-generate-agent.md +++ b/.claude/commands/workflow/tools/task-generate-agent.md @@ -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 diff --git a/.claude/commands/workflow/tools/task-generate-tdd.md b/.claude/commands/workflow/tools/task-generate-tdd.md index 1f77da38..272c78c4 100644 --- a/.claude/commands/workflow/tools/task-generate-tdd.md +++ b/.claude/commands/workflow/tools/task-generate-tdd.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 diff --git a/.claude/commands/workflow/tools/task-generate.md b/.claude/commands/workflow/tools/task-generate.md index 6ab68a5b..f9491edc 100644 --- a/.claude/commands/workflow/tools/task-generate.md +++ b/.claude/commands/workflow/tools/task-generate.md @@ -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 diff --git a/.github/release-notes-v3.5.0.md b/.github/release-notes-v3.5.0.md new file mode 100644 index 00000000..23dfd34b --- /dev/null +++ b/.github/release-notes-v3.5.0.md @@ -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) diff --git a/.gitignore b/.gitignore index 62123034..e264aa4d 100644 --- a/.gitignore +++ b/.gitignore @@ -19,4 +19,5 @@ Thumbs.db .env settings.local.json .workflow -version.json \ No newline at end of file +version.json +ref \ No newline at end of file