From 3068c2ca839ddff4029cdba247204d13e8d41afa Mon Sep 17 00:00:00 2001 From: catlog22 Date: Fri, 24 Oct 2025 15:08:16 +0800 Subject: [PATCH] Refactor TDD Workflow: Update phases, introduce conflict resolution, and enhance task generation - Revised TDD workflow to reduce phases from 7 to 6, integrating conflict resolution as an optional phase. - Updated phase descriptions and execution logic to ensure automatic progression through phases based on TodoList status. - Removed the concept-enhanced command and its associated documentation, streamlining the analysis process. - Enhanced task generation to prioritize conflict resolution strategies and incorporate context package loading. - Updated UI design documentation to reflect changes in role analysis and design system references. - Improved error handling and validation checks across various commands to ensure robustness in execution. --- .../commands/workflow/brainstorm/synthesis.md | 937 +++++++----------- .claude/commands/workflow/tdd-plan.md | 139 ++- .../workflow/tools/concept-enhanced.md | 229 ----- .../workflow/tools/task-generate-tdd.md | 35 +- .../commands/workflow/tools/task-generate.md | 4 +- .claude/commands/workflow/ui-design/update.md | 105 +- 6 files changed, 589 insertions(+), 860 deletions(-) delete mode 100644 .claude/commands/workflow/tools/concept-enhanced.md diff --git a/.claude/commands/workflow/brainstorm/synthesis.md b/.claude/commands/workflow/brainstorm/synthesis.md index 501d2d95..6684ed87 100644 --- a/.claude/commands/workflow/brainstorm/synthesis.md +++ b/.claude/commands/workflow/brainstorm/synthesis.md @@ -1,561 +1,387 @@ --- name: synthesis -description: Analyze role analyses, identify ambiguities through clarification, and update role documents intelligently using conceptual-planning-agent +description: Clarify and refine role analyses through intelligent Q&A and targeted updates argument-hint: "[optional: --session session-id]" allowed-tools: Task(conceptual-planning-agent), TodoWrite(*), Read(*), Write(*), Edit(*), Glob(*), AskUserQuestion(*) --- -## 🧩 **Role Analysis Clarification & Refinement** +## Overview -### Core Function -**Specialized command for analyzing and refining role analysis documents** through intelligent clarification. Agent performs cross-role integration analysis, identifies ambiguities and gaps, interacts with user to clarify uncertainties, and intelligently updates relevant role analysis.md files. +Three-phase workflow to eliminate ambiguities and enhance conceptual depth in role analyses: -**Dynamic Role Discovery**: Automatically detects which roles participated in brainstorming by scanning for `*/analysis.md` files. Analyzes only actual participating roles, not predefined lists. +**Phase 1-2 (Main Flow)**: Session detection → File discovery → Path preparation -### Primary Capabilities -- **Dynamic Role Discovery**: Automatically identifies participating roles at runtime -- **Cross-Role Integration Analysis**: Internal analysis of consistency, conflicts, and gaps across roles -- **Ambiguity Detection**: Systematic scanning using 8-category taxonomy (user intent, requirements, architecture, etc.) -- **Interactive Clarification**: Priority-based question queue (max 5 questions) with user interaction -- **Intelligent Document Update**: Agent autonomously determines which role documents to update based on clarification answers -- **User Intent Validation**: Ensures role analyses align with user's original goals +**Phase 3A (Analysis Agent)**: Cross-role analysis → CLI concept enhancement → Generate recommendations -### Document Integration Model -**Role-Centric Architecture**: -1. **[role]/analysis.md** → Individual role analyses (input & output) -2. **guidance-specification.md** → Structured discussion framework (reference) -3. **User's Original Intent** → Primary alignment reference (from session metadata) -4. **Updated [role]/analysis.md** → Refined role analyses after clarification (output) +**Phase 4 (Main Flow)**: User selects enhancements → User answers clarifications → Build update plan -## ⚙️ **Execution Protocol** +**Phase 5 (Parallel Update Agents)**: Each agent updates ONE role document → Parallel execution -### ⚠️ Agent Execution with Interactive Clarification -**Execution Model**: Uses conceptual-planning-agent for cross-role analysis, clarification generation, user interaction, and intelligent document updates. +**Phase 6 (Main Flow)**: Metadata update → Completion report -**Rationale**: -- **Autonomous Analysis**: Agent independently loads and analyzes all role documents -- **Cognitive Complexity**: Leverages agent's capabilities for cross-role synthesis and ambiguity detection -- **Interactive Intelligence**: Agent manages question prioritization and document update decisions -- **Conceptual Focus**: Agent specializes in conceptual analysis and multi-perspective integration +**Key Features**: +- Multi-agent architecture (analysis agent + parallel update agents) +- Clear separation: Agent analysis vs Main flow interaction +- CLI-powered concept enhancement (Gemini) +- Parallel document updates (one agent per role) +- User intent alignment validation -**Agent Responsibility**: All file reading, analysis, clarification interaction, and document updates performed by conceptual-planning-agent. +**Document Flow**: +- Input: `[role]/analysis*.md`, `guidance-specification.md`, session metadata +- Output: Updated `[role]/analysis*.md` with Enhancements + Clarifications sections + +## Task Tracking -### 📋 Task Tracking Protocol -Initialize clarification task tracking using TodoWrite at command start: ```json [ - {"content": "Detect active session and validate role analyses existence", "status": "in_progress", "activeForm": "Detecting session and validating analyses"}, - {"content": "Discover participating role analyses dynamically", "status": "pending", "activeForm": "Discovering role analyses"}, - {"content": "Execute cross-role integration analysis using conceptual-planning-agent", "status": "pending", "activeForm": "Executing agent-based cross-role analysis"}, - {"content": "Execute CLI-powered concept enhancement analysis", "status": "pending", "activeForm": "Executing concept enhancement analysis"}, - {"content": "Present enhancement points and get user confirmation", "status": "pending", "activeForm": "Presenting enhancement points for user confirmation"}, - {"content": "Apply selected enhancements to role analysis documents", "status": "pending", "activeForm": "Applying selected enhancements"}, - {"content": "Agent performs ambiguity detection and generates clarification questions", "status": "pending", "activeForm": "Agent detecting ambiguities and generating questions"}, - {"content": "Interactive clarification loop with user (max 5 questions)", "status": "pending", "activeForm": "Interactive clarification with user"}, - {"content": "Agent intelligently updates relevant role analysis documents", "status": "pending", "activeForm": "Agent updating role documents"}, - {"content": "Update workflow-session.json with clarification completion status", "status": "pending", "activeForm": "Updating session metadata"} + {"content": "Detect session and validate analyses", "status": "in_progress", "activeForm": "Detecting session"}, + {"content": "Discover role analysis file paths", "status": "pending", "activeForm": "Discovering paths"}, + {"content": "Execute analysis agent (cross-role + CLI enhancement)", "status": "pending", "activeForm": "Executing analysis agent"}, + {"content": "Present enhancements for user selection", "status": "pending", "activeForm": "Presenting enhancements"}, + {"content": "Generate and present clarification questions", "status": "pending", "activeForm": "Clarifying with user"}, + {"content": "Build update plan from user input", "status": "pending", "activeForm": "Building update plan"}, + {"content": "Execute parallel update agents (one per role)", "status": "pending", "activeForm": "Updating documents in parallel"}, + {"content": "Update session metadata and generate report", "status": "pending", "activeForm": "Finalizing session"} ] ``` -### Phase 1: Document Discovery & Validation -```bash -# Detect active brainstorming 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 brainstorming session found" - EXIT +## Execution Phases -brainstorm_dir = .workflow/WFS-{session}/.brainstorming/ +### Phase 1: Discovery & Validation -# Validate topic framework (optional but recommended) -CHECK: brainstorm_dir/guidance-specification.md -IF NOT EXISTS: - WARN: "guidance-specification.md not found. Analysis will rely on role documents only." +1. **Detect Session**: Use `--session` parameter or `.workflow/.active-*` marker +2. **Validate Files**: + - `guidance-specification.md` (optional, warn if missing) + - `*/analysis*.md` (required, error if empty) +3. **Load User Intent**: Extract from `workflow-session.json` (project/description field) -# Validate role analyses exist -role_analyses = Glob(brainstorm_dir/*/analysis*.md) -IF role_analyses is empty: - ERROR: "No role analysis files found. Run role brainstorming commands first." - EXIT +### Phase 2: Role Discovery & Path Preparation -# Load user's original prompt from session metadata -session_metadata = Read(.workflow/WFS-{session}/workflow-session.json) -original_user_intent = session_metadata.project || session_metadata.description -IF NOT original_user_intent: - WARN: "No original user intent found in session metadata" - original_user_intent = "Not available" -``` +**Main flow prepares file paths for Agent**: -### Phase 2: Role Analysis Discovery -```bash -# Dynamically discover available role analyses -SCAN_DIRECTORY: .workflow/WFS-{session}/.brainstorming/ -FIND_ANALYSES: [ - Scan all subdirectories for */analysis*.md files (supports analysis.md, analysis-1.md, analysis-2.md, analysis-3.md) - Extract role names from directory names -] +1. **Discover Analysis Files**: + - Glob(.workflow/WFS-{session}/.brainstorming/*/analysis*.md) + - Supports: analysis.md, analysis-1.md, analysis-2.md, analysis-3.md + - Validate: At least one file exists (error if empty) -# Available roles (for reference, actual participation is dynamic): -# - product-manager -# - product-owner -# - scrum-master -# - system-architect -# - ui-designer -# - ux-expert -# - data-architect -# - subject-matter-expert -# - test-strategist -# - api-designer +2. **Extract Role Information**: + - `role_analysis_paths`: Relative paths from brainstorm_dir + - `participating_roles`: Role names extracted from directory paths -LOAD_DOCUMENTS: { - "original_user_intent": original_user_intent (from session metadata), - "topic_framework": guidance-specification.md (if exists), - "role_analyses": [dynamically discovered analysis*.md files], - "participating_roles": [extract role names from discovered directories] -} +3. **Pass to Agent** (Phase 3): + - `session_id` + - `brainstorm_dir`: .workflow/WFS-{session}/.brainstorming/ + - `role_analysis_paths`: ["product-manager/analysis.md", "system-architect/analysis-1.md", ...] + - `participating_roles`: ["product-manager", "system-architect", ...] -# Note: Not all roles participate in every brainstorming session -# Only analyze roles that actually produced analysis*.md files -# Each role may have 1-3 analysis files: analysis.md OR analysis-1.md, analysis-2.md, analysis-3.md -# CRITICAL: Original user intent MUST be primary reference for validation -``` +**Main Flow Responsibility**: File discovery and path preparation only (NO file content reading) -### Phase 3: Agent Execution with Interactive Clarification -**Clarification & Update using conceptual-planning-agent** +### Phase 3A: Analysis & Enhancement Agent -Delegate analysis, clarification, and update to conceptual-planning-agent: +**First agent call**: Cross-role analysis and generate enhancement recommendations ```bash Task(conceptual-planning-agent): " -[INTERACTIVE_CLARIFICATION_WORKFLOW] - -Execute comprehensive cross-role analysis, ambiguity detection, user clarification, and intelligent document updates - -## Context Loading -SESSION_ID: {session_id} -BRAINSTORM_DIR: .workflow/WFS-{session}/.brainstorming/ -ANALYSIS_MODE: cross_role_clarification_and_update -MAX_QUESTIONS: 5 - -## ⚠️ CRITICAL: User Intent Authority -**ORIGINAL USER INTENT IS THE PRIMARY REFERENCE**: {original_user_intent} -All analysis and updates MUST align with user's original intent. Topic framework and role analyses are supplementary context. - -## Workflow Steps - -### Step 1: Load All Context Documents -1. **load_original_user_intent** - - Action: Load user's original intent from session metadata - - Command: Read(.workflow/WFS-{session}/workflow-session.json) - - Extract: project field or description field - - Output: original_user_intent (PRIMARY REFERENCE) - - Priority: HIGHEST - This is the authoritative source of user intent - -2. **load_topic_framework** - - Action: Load structured topic discussion framework (optional) - - Command: Read(.workflow/WFS-{session}/.brainstorming/guidance-specification.md) [if exists] - - Output: topic_framework_content - - Note: Validate alignment with original_user_intent - -3. **discover_role_analyses** - - Action: Dynamically discover all participating role analysis files (supports multiple files per role) - - Command: Glob(.workflow/WFS-{session}/.brainstorming/*/analysis*.md) - - Output: role_analysis_paths, participating_roles - - Note: Each role may have 1-3 files (analysis.md OR analysis-1.md, analysis-2.md, analysis-3.md) - -4. **load_role_analyses** - - Action: Load all discovered role analysis documents - - Command: Read(each path from role_analysis_paths) - - Output: role_analyses_content_map = {role_name: [analysis_content_1, analysis_content_2, ...]} - - Note: Maintain role-to-content mapping for intelligent updates - -### Step 2: Cross-Role Integration Analysis (Internal) -Perform internal cross-role analysis following these steps (DO NOT OUTPUT TO USER): - -1. **Consensus Identification**: Identify common themes and agreement areas across all participating roles -2. **Conflict Detection**: Document conflicting views and track which specific roles disagree on each point -3. **Gap Analysis**: Identify missing information, underspecified areas, and ambiguous points -4. **User Intent Alignment Check**: Validate all role analyses align with user's original intent -5. **Innovation Extraction**: Identify breakthrough ideas and cross-role synergy opportunities - -### Step 2.5: Concept Enhancement (CLI-Powered) -Execute CLI-powered concept enhancement analysis to identify improvement opportunities: - -**Purpose**: Enhance role analyses with deeper architectural insights and best practices - -**CLI Execution**: -\`\`\`bash -cd .workflow/WFS-{session}/.brainstorming && gemini -p " -PURPOSE: Analyze role analyses for concept enhancement opportunities -TASK: -• Review all role analysis documents for architectural depth -• Identify underspecified design decisions -• Suggest concrete improvements with rationale -• Focus on technical feasibility and best practices -MODE: analysis -CONTEXT: @**/* @{session_metadata} -EXPECTED: Enhancement points list with specific recommendations -RULES: Focus on actionable improvements that add architectural value -" -m gemini-2.5-pro -\`\`\` - -**Fallback**: If CLI unavailable, use Claude analysis with Read tool - -**Enhancement Points Output**: -Generate list of enhancement opportunities: -\`\`\`markdown -### Enhancement Points - -**EP-001: {title}** -- **Affected Roles**: {role_list} -- **Category**: {Architecture | Design | Requirements | Risk} -- **Current State**: {what_exists_now} -- **Enhancement**: {what_to_add_or_improve} -- **Rationale**: {why_this_improves_quality} -- **Priority**: {Critical | High | Medium} - -**EP-002: {title}** -... -\`\`\` - -**User Confirmation**: -Present enhancement points to user using AskUserQuestion: -- Show top 3-5 enhancement opportunities -- User selects which enhancements to apply -- User can skip all if satisfied with current analyses - -**Apply Selected Enhancements**: -For each user-approved enhancement: -1. Identify affected role analysis files -2. Update relevant sections in analysis.md files -3. Add enhancement record to "## Enhancements" section -4. Maintain consistency across updated documents - -**Enhancement Record Format**: -\`\`\`markdown -## Enhancements - -### Session {date} -- **EP-001**: {title} - Applied to {section_name} - - Enhancement: {brief_description} -\`\`\` - -### Step 3: Ambiguity & Coverage Scan (Internal) -Perform structured scan using this taxonomy. For each category, mark status: **Clear** / **Partial** / **Missing**. - -**⚠️ User Intent Alignment** (HIGHEST PRIORITY): -- [ ] Role analyses alignment with original user intent -- [ ] Goal consistency between analyses and user's stated objectives -- [ ] Scope match with user's requirements -- [ ] Success criteria reflects user's expectations -- [ ] Any unexplained deviations from user intent - -**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 role analyses -- [ ] No unresolved placeholders (TODO, TBD, ???) - -### Step 4: Generate Prioritized Question Queue (Internal) -Internally generate prioritized queue of candidate questions (maximum 5): - -**Constraints**: -- Maximum 5 questions per session -- Each question must be answerable with: - * Multiple-choice (2-4 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**: Report success and proceed to Step 7 (Session Metadata Update). - -### Step 5: Sequential Clarification Loop (Interactive with User) -Present **EXACTLY ONE** question at a time using AskUserQuestion tool: - -**Question Format Template**: -```markdown -**Question {N}/5**: {Question text} - -**Category**: {Category name from taxonomy} -**Impact**: {Brief impact description} -**Affects Roles**: {List of roles that will be updated based on answer} - -| Option | Description | -|--------|-------------| -| A | {Option A description} | -| B | {Option B description} | -| C | {Option C description} | -| D | {Option D description} | -``` - -**Answer Handling**: -- Record answer in working memory with metadata: {question, answer, affected_roles, category} -- Store in clarification_results array for later batch processing -- Proceed to next question immediately (DO NOT update documents yet) - -**Stop Conditions**: -- All critical ambiguities resolved -- User signals completion ("done", "no more", "proceed") -- Reached 5 questions - -**Never reveal future queued questions in advance**. - -### Step 6: Intelligent Document Update (Batch Processing) -After all questions answered, process all clarifications in batch: - -**For each clarification in clarification_results**: - -1. **Determine Affected Roles** (Intelligent Judgment): - - Analyze question category and answer content - - Determine which role documents need updates - - Example mapping: - * Architecture questions → system-architect, data-architect - * UX questions → ui-designer, ux-expert - * Requirements questions → product-manager, product-owner - * Process questions → scrum-master, product-manager - - Cross-cutting concerns may update multiple roles - -2. **Create Clarifications Section** (If Not Exists): - ```bash - FOR each affected role analysis file: - IF file NOT contains "## Clarifications": - Insert "## Clarifications" section after first heading - - IF NOT contains "### Session YYYY-MM-DD": - Create "### Session {today's date}" under "## Clarifications" - - APPEND: "- **Q**: {question} ({category})" - APPEND: " **A**: {answer}" - ``` - -3. **Apply Clarification to Relevant Sections**: - ```bash - CASE category: - User Intent Alignment → Update "## Overview" or "## Executive Summary" - Functional Requirements → Update "## Requirements" or "## Functional Specifications" - Architecture → Update "## Architecture" or "## Design" sections - User Experience → Update "## UI/UX" or "## User Experience" sections - Risk → Update "## Risks" or "## Risk Assessment" sections - Process → Update "## Process" or "## Implementation" sections - Data Model → Update "## Data Model" or "## Database" sections - Non-Functional → Update "## Non-Functional Requirements" or equivalent - ``` - -4. **Remove Contradictions**: - ```bash - IF clarification invalidates existing statement: - Replace statement instead of duplicating - Mark removed content with comment: - ``` - -5. **Maintain Consistency**: - - Update terminology throughout document if clarification defines canonical terms - - Remove placeholders (TODO, TBD, ???) that were addressed - - Ensure no contradictory statements remain - -6. **Save Updates**: - ```bash - FOR each modified role analysis file: - Write(file_path, updated_content) - ``` - -### Step 7: Validation After Updates -Verify all updates meet quality standards: - -- [ ] Clarifications section contains exactly one bullet per question per affected role -- [ ] Total asked questions ≤ 5 -- [ ] Updated sections contain no lingering placeholders -- [ ] No contradictory earlier statements remain -- [ ] Markdown structure valid in all updated files -- [ ] Terminology consistent across all updated role analyses -- [ ] User intent alignment explicitly validated in affected documents - -### Step 8: Completion Report -Generate comprehensive completion report for user: - -```markdown -## ✅ Role Analysis Clarification Complete - -**Session**: WFS-{session-id} -**Questions Asked**: {count}/5 -**Role Documents Updated**: {list updated role names} -**Categories Clarified**: {list category names} - -### Coverage Summary - -| Category | Status | Notes | -|----------|--------|-------| -| User Intent Alignment | ✅ Resolved | Clarified {specific points} | -| Requirements Clarity | ✅ Clear | No ambiguities found | -| Architecture & Design | ⚠️ Partial | {specific gaps if any} | -| User Experience | ✅ Resolved | Updated UI/UX specs | -| Implementation Feasibility | ✅ Clear | Team capabilities validated | -| Risk & Mitigation | ✅ Resolved | Mitigation strategies defined | -| Process & Collaboration | ✅ Clear | Role handoffs clarified | -| Decision Traceability | ✅ Resolved | Alternatives documented | -| Terminology & Consistency | ✅ Resolved | Canonical terms defined | - -**Legend**: -- ✅ Resolved: Was Partial/Missing, now addressed -- ✅ Clear: Already sufficient -- ⚠️ Partial: Some gaps remain (details below) - -### Document Updates - -| Role | Files Updated | Sections Modified | -|------|---------------|-------------------| -{For each updated role} -| {role_name} | {file_name} | {section_list} | - -### Clarification Details - -{For each clarification} -**Q{N}**: {question} -**A**: {answer} -**Updated Roles**: {affected_roles} -**Category**: {category} - -### Recommendations - -- ✅ **PROCEED to /workflow:plan**: Conceptual foundation is clear and refined -- OR ⚠️ **Address Outstanding Items First**: {list critical outstanding items if any} -- OR 🔄 **Run /workflow:brainstorm:synthesis Again**: If new information or roles added - -### Next Steps - -**Standard Workflow (Recommended)**: -```bash -/workflow:plan --session WFS-{session-id} # Generate IMPL_PLAN.md and tasks from role analyses -``` - -**TDD Workflow**: -```bash -/workflow:tdd-plan --session WFS-{session-id} \"Feature description\" -``` -``` - -## Completion Criteria -- ⚠️ **USER INTENT ALIGNMENT**: Role analyses align with user's original intent -- All participating role analyses loaded and analyzed -- Cross-role integration analysis completed (consensus, conflicts, gaps identified) -- Ambiguity scan completed across all 9 categories -- Clarification questions prioritized (if needed) -- User interaction completed (max 5 questions) -- Affected role documents intelligently updated -- Clarifications section added to updated documents -- Contradictions removed, terminology consistent -- Session metadata updated with clarification results - -## Execution Notes -- Dynamic role participation: Only analyze roles that produced analysis.md files -- Internal analysis: Cross-role synthesis performed internally, not shown to user -- Interactive clarification: Present one question at a time -- Intelligent updates: Agent determines affected roles based on answer context -- Batch processing: Update all affected documents after all questions answered -- Timeout allocation: Complex clarification task (60-90 min recommended) -- Reference @intelligent-tools-strategy.md for timeout guidelines +## Agent Mission +Analyze role documents, identify conflicts/gaps, and generate enhancement recommendations + +## Input from Main Flow +- brainstorm_dir: {brainstorm_dir} +- role_analysis_paths: {role_analysis_paths} +- participating_roles: {participating_roles} + +## Execution Instructions +[FLOW_CONTROL] + +### Flow Control Steps +**AGENT RESPONSIBILITY**: Execute these analysis steps sequentially with context accumulation: + +1. **load_session_metadata** + - Action: Load original user intent as primary reference + - Command: Read({brainstorm_dir}/../workflow-session.json) + - Output: original_user_intent (from project/description field) + +2. **load_role_analyses** + - Action: Load all role analysis documents + - Command: For each path in role_analysis_paths: Read({brainstorm_dir}/{path}) + - Output: role_analyses_content_map = {role_name: content} + +3. **cross_role_analysis** + - Action: Identify consensus themes, conflicts, gaps, underspecified areas + - Output: consensus_themes, conflicting_views, gaps_list, ambiguities + +4. **cli_concept_enhancement** + - Action: Execute intelligent CLI analysis with fallback chain + - Dynamic Prompt: \"PURPOSE: Cross-role synthesis | TASK: conflicts/gaps/enhancements | MODE: analysis | CONTEXT: @**/* | EXPECTED: EP-001,EP-002,... | RULES: Eliminate ambiguities\" + - Fallback Chain: `cd {brainstorm_dir} && gemini -p \"$PROMPT\" -m gemini-2.5-pro` → (if fail) `qwen -p \"$PROMPT\"` → (if fail) `codex -C {brainstorm_dir} --full-auto exec \"$PROMPT\" -m gpt-5` + - Error Handling: Gemini 429 OK if results exist | 40min timeout | One attempt per tool + - Output: cli_enhancement_points + +5. **generate_recommendations** + - Action: Combine cross-role analysis + CLI enhancements into structured recommendations + - Format: EP-001, EP-002, ... (sequential numbering) + - Fields: id, title, affected_roles, category, current_state, enhancement, rationale, priority + - Taxonomy: Map to 9 categories (User Intent, Requirements, Architecture, UX, Feasibility, Risk, Process, Decisions, Terminology) + - Output: enhancement_recommendations (JSON array) + +### Output to Main Flow +Return JSON array: +[ + { + \"id\": \"EP-001\", + \"title\": \"API Contract Specification\", + \"affected_roles\": [\"system-architect\", \"api-designer\"], + \"category\": \"Architecture\", + \"current_state\": \"High-level API descriptions\", + \"enhancement\": \"Add detailed contract definitions with request/response schemas\", + \"rationale\": \"Enables precise implementation and testing\", + \"priority\": \"High\" + }, + ... +] + +### Agent Context Summary +**Tools Used**: Gemini (primary) → Qwen (fallback) → Codex (last resort) +**Mode**: analysis (read-only) +**Timeout**: 40min +**Dependencies**: @intelligent-tools-strategy.md +**Validation**: Enhancement recommendations + 9-category taxonomy mapping " ``` -## 📊 **Output Specification** +### Phase 4: Main Flow User Interaction -### Output Location -The clarification process **refines existing role analysis documents** without creating new consolidated files: +**Main flow handles all user interaction**: -``` -.workflow/WFS-{topic-slug}/.brainstorming/ -├── guidance-specification.md # Input: Framework structure (reference) -├── [role]/analysis*.md # Input & OUTPUT: Role analyses +1. **Present Enhancement Options**: +```python +AskUserQuestion( + questions=[{ + "question": "Which enhancements would you like to apply?", + "header": "Enhancements", + "multiSelect": true, + "options": [ + {"label": "EP-001: ...", "description": "... (affects: role1, role2)"}, + {"label": "EP-002: ...", "description": "..."}, + ... + ] + }] +) ``` -#### Updated Role Analysis Structure -Each updated role analysis.md will contain: +2. **Generate Clarification Questions** (based on analysis agent output): + - Use 9-category taxonomy scan results + - Create max 5 prioritized questions + - Each with 2-4 options + descriptions -**New Section - Clarifications**: +3. **Interactive Clarification Loop**: +```python +# Present ONE question at a time +FOR question in clarification_questions (max 5): + AskUserQuestion( + questions=[{ + "question": "Question {N}/5: {text}", + "header": "Clarification", + "multiSelect": false, + "options": [ + {"label": "Option A", "description": "..."}, + {"label": "Option B", "description": "..."}, + ... + ] + }] + ) + # Record answer + # Continue to next question +``` + +4. **Build Update Plan**: +```python +update_plan = { + "role1": { + "enhancements": [EP-001, EP-003], + "clarifications": [ + {"question": "...", "answer": "...", "category": "..."}, + ... + ] + }, + "role2": { + "enhancements": [EP-002], + "clarifications": [...] + }, + ... +} +``` + +### Phase 5: Parallel Document Update Agents + +**Parallel agent calls** (one per role needing updates): + +```bash +# Execute in parallel using single message with multiple Task calls + +Task(conceptual-planning-agent): " +## Agent Mission +Apply user-confirmed enhancements and clarifications to {role1} analysis document + +## Agent Intent +- **Goal**: Integrate synthesis results into role-specific analysis +- **Scope**: Update ONLY {role1}/analysis.md (isolated, no cross-role dependencies) +- **Constraints**: Preserve original insights, add refinements without deletion + +## Input from Main Flow +- role: {role1} +- analysis_path: {brainstorm_dir}/{role1}/analysis.md +- enhancements: [EP-001, EP-003] (user-selected improvements) +- clarifications: [{question, answer, category}, ...] (user-confirmed answers) +- original_user_intent: {from session metadata} + +## Execution Instructions +[FLOW_CONTROL] + +### Flow Control Steps +**AGENT RESPONSIBILITY**: Execute these update steps sequentially: + +1. **load_current_analysis** + - Action: Load existing role analysis document + - Command: Read({brainstorm_dir}/{role1}/analysis.md) + - Output: current_analysis_content + +2. **add_clarifications_section** + - Action: Insert Clarifications section with Q&A + - Format: \"## Clarifications\\n### Session {date}\\n- **Q**: {question} (Category: {category})\\n **A**: {answer}\" + - Output: analysis_with_clarifications + +3. **apply_enhancements** + - Action: Integrate EP-001, EP-003 into relevant sections + - Strategy: Locate section by category (Architecture → Architecture section, UX → User Experience section) + - Output: analysis_with_enhancements + +4. **resolve_contradictions** + - Action: Remove conflicts between original content and clarifications/enhancements + - Output: contradiction_free_analysis + +5. **enforce_terminology_consistency** + - Action: Align all terminology with user-confirmed choices from clarifications + - Output: terminology_consistent_analysis + +6. **validate_user_intent_alignment** + - Action: Verify all updates support original_user_intent + - Output: validated_analysis + +7. **write_updated_file** + - Action: Save final analysis document + - Command: Write({brainstorm_dir}/{role1}/analysis.md, validated_analysis) + - Output: File update confirmation + +### Output +Updated {role1}/analysis.md with Clarifications section + enhanced content +") + +Task(conceptual-planning-agent): " +## Agent Mission +Apply user-confirmed enhancements and clarifications to {role2} analysis document + +## Agent Intent +- **Goal**: Integrate synthesis results into role-specific analysis +- **Scope**: Update ONLY {role2}/analysis.md (isolated, no cross-role dependencies) +- **Constraints**: Preserve original insights, add refinements without deletion + +## Input from Main Flow +- role: {role2} +- analysis_path: {brainstorm_dir}/{role2}/analysis.md +- enhancements: [EP-002] (user-selected improvements) +- clarifications: [{question, answer, category}, ...] (user-confirmed answers) +- original_user_intent: {from session metadata} + +## Execution Instructions +[FLOW_CONTROL] + +### Flow Control Steps +**AGENT RESPONSIBILITY**: Execute same 7 update steps as {role1} agent (load → clarifications → enhancements → contradictions → terminology → validation → write) + +### Output +Updated {role2}/analysis.md with Clarifications section + enhanced content +") + +# ... repeat for each role in update_plan +``` + +**Agent Characteristics**: +- **Intent**: Integrate user-confirmed synthesis results (NOT generate new analysis) +- **Isolation**: Each agent updates exactly ONE role (parallel execution safe) +- **Context**: Minimal - receives only role-specific enhancements + clarifications +- **Dependencies**: Zero cross-agent dependencies (full parallelism) +- **Validation**: All updates must align with original_user_intent + +### Phase 6: Completion & Metadata Update + +**Main flow finalizes**: + +1. Wait for all parallel agents to complete +2. Update workflow-session.json: +```json +{ + "phases": { + "BRAINSTORM": { + "status": "clarification_completed", + "clarification_completed": true, + "completed_at": "timestamp", + "participating_roles": [...], + "clarification_results": { + "enhancements_applied": ["EP-001", "EP-002", ...], + "questions_asked": 3, + "categories_clarified": ["Architecture", "UX", ...], + "roles_updated": ["role1", "role2", ...], + "outstanding_items": [] + }, + "quality_metrics": { + "user_intent_alignment": "validated", + "requirement_coverage": "comprehensive", + "ambiguity_resolution": "complete", + "terminology_consistency": "enforced" + } + } + } +} +``` + +3. Generate completion report (show to user): +```markdown +## ✅ Clarification Complete + +**Enhancements Applied**: EP-001, EP-002, EP-003 +**Questions Answered**: 3/5 +**Roles Updated**: role1, role2, role3 + +### Next Steps +✅ PROCEED: `/workflow:plan --session WFS-{session-id}` +``` + +## Output + +**Location**: `.workflow/WFS-{session}/.brainstorming/[role]/analysis*.md` (in-place updates) + +**Updated Structure**: ```markdown ## Clarifications +### Session {date} +- **Q**: {question} (Category: {category}) + **A**: {answer} -### Session 2025-01-15 -- **Q**: {Question text} (Category: {category}) - **A**: {Answer} -- **Q**: {Question text} (Category: {category}) - **A**: {Answer} +## {Existing Sections} +{Refined content based on clarifications} ``` -**Updated Sections**: Existing sections refined based on clarifications: -- User intent alignment validated/corrected -- Requirements made more specific and measurable -- Architecture decisions clarified with rationale +**Changes**: +- User intent validated/corrected +- Requirements more specific/measurable +- Architecture with rationale - Ambiguities resolved, placeholders removed -- Terminology made consistent +- Consistent terminology +## Session Metadata - -## 🔄 **Session Integration** - -### Streamlined Status Synchronization -Upon completion, update `workflow-session.json`: - -**Dynamic Role Participation**: The `participating_roles` and `roles_updated` values are determined at runtime based on actual analysis.md files and clarification results. +Update `workflow-session.json`: ```json { @@ -564,12 +390,11 @@ Upon completion, update `workflow-session.json`: "status": "clarification_completed", "clarification_completed": true, "completed_at": "timestamp", - "participating_roles": ["", "", "..."], - "available_roles": ["product-manager", "product-owner", "scrum-master", "system-architect", "ui-designer", "ux-expert", "data-architect", "subject-matter-expert", "test-strategist", "api-designer"], + "participating_roles": ["product-manager", "system-architect", ...], "clarification_results": { - "questions_asked": , - "categories_clarified": [], - "roles_updated": [], + "questions_asked": 3, + "categories_clarified": ["Architecture & Design", ...], + "roles_updated": ["system-architect", "ui-designer", ...], "outstanding_items": [] }, "quality_metrics": { @@ -584,65 +409,43 @@ Upon completion, update `workflow-session.json`: } ``` -**Example with actual values**: -```json -{ - "phases": { - "BRAINSTORM": { - "status": "clarification_completed", - "participating_roles": ["product-manager", "system-architect", "ui-designer", "ux-expert", "scrum-master"], - "clarification_results": { - "questions_asked": 3, - "categories_clarified": ["Architecture & Design", "User Experience", "Risk & Mitigation"], - "roles_updated": ["system-architect", "ui-designer", "ux-expert"], - "outstanding_items": [] - } - } - } -} -``` +## Quality Checklist -## ✅ **Quality Assurance** +**Content**: +- All role analyses loaded/analyzed +- Cross-role analysis (consensus, conflicts, gaps) +- 9-category ambiguity scan +- Questions prioritized +- Clarifications documented -Verify clarification output meets these standards: +**Analysis**: +- User intent validated +- Cross-role synthesis complete +- Ambiguities resolved +- Correct roles updated +- Terminology consistent +- Contradictions removed -### Content Completeness -- [ ] All participating role analyses loaded and analyzed -- [ ] Cross-role integration analysis completed (consensus, conflicts, gaps) -- [ ] Ambiguity scan completed across all 9 categories -- [ ] Clarification questions prioritized appropriately -- [ ] All clarifications documented in affected role documents +**Documents**: +- Clarifications section formatted +- Sections reflect answers +- No placeholders (TODO/TBD) +- Valid Markdown +- Cross-references maintained -### Analysis Quality -- [ ] User intent alignment validated across all roles -- [ ] Cross-role synthesis identifies consensus and conflicts -- [ ] Ambiguities resolved through targeted clarification -- [ ] Intelligent role update decisions (correct roles updated) -- [ ] Terminology consistency enforced -- [ ] Contradictions removed from updated documents +## Next Steps -### Document Quality -- [ ] Clarifications section properly formatted -- [ ] Updated sections reflect clarification answers -- [ ] No placeholders remain (TODO, TBD, ???) -- [ ] Markdown structure valid in all updated files -- [ ] Cross-references maintained - -## 🚀 **Recommended Next Steps** - -After clarification completion, proceed to planning: - -### Standard Workflow (Recommended) +**Standard**: ```bash -/workflow:plan --session WFS-{session-id} # Generate IMPL_PLAN.md and tasks from refined role analyses -/workflow:action-plan-verify --session WFS-{session-id} # Optional: Verify plan quality -/workflow:execute --session WFS-{session-id} # Start implementation -``` - -### TDD Workflow -```bash -/workflow:tdd-plan --session WFS-{session-id} "Feature description" -/workflow:action-plan-verify --session WFS-{session-id} # Optional: Verify plan quality +/workflow:plan --session WFS-{session-id} +/workflow:action-plan-verify --session WFS-{session-id} # Optional +/workflow:execute --session WFS-{session-id} +``` + +**TDD**: +```bash +/workflow:tdd-plan --session WFS-{session-id} "description" +/workflow:action-plan-verify --session WFS-{session-id} # Optional /workflow:execute --session WFS-{session-id} ``` diff --git a/.claude/commands/workflow/tdd-plan.md b/.claude/commands/workflow/tdd-plan.md index 7ffa6233..6f58d5da 100644 --- a/.claude/commands/workflow/tdd-plan.md +++ b/.claude/commands/workflow/tdd-plan.md @@ -20,12 +20,12 @@ allowed-tools: SlashCommand(*), TodoWrite(*), Read(*), Bash(*) 1. **Start Immediately**: First action is TodoWrite initialization, second action is Phase 1 execution 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 7 completes (with concept verification) +4. **Auto-Continue via TodoList**: Check TodoList status to execute next pending phase automatically +5. **Track Progress**: Update TodoWrite after every phase completion 6. **TDD Context**: All descriptions include "TDD:" prefix -7. **Quality Gate**: Phase 5 concept verification ensures clarity before task generation +7. **Quality Gate**: Phase 4 conflict resolution (optional, auto-triggered) validates compatibility before task generation -## 7-Phase Execution (with Concept Verification) +## 6-Phase Execution (with Conflict Resolution) ### Phase 1: Session Discovery **Command**: `/workflow:session:start --auto "TDD: [structured-description]"` @@ -41,10 +41,32 @@ TEST_FOCUS: [Test scenarios] **Parse**: Extract sessionId +**TodoWrite**: Mark phase 1 completed, phase 2 in_progress + +**After Phase 1**: Return to user showing Phase 1 results, then auto-continue to Phase 2 + +--- + ### Phase 2: Context Gathering **Command**: `/workflow:tools:context-gather --session [sessionId] "TDD: [structured-description]"` -**Parse**: Extract contextPath +**Use Same Structured Description**: Pass the same structured format from Phase 1 + +**Input**: `sessionId` from Phase 1 + +**Parse Output**: +- Extract: context-package.json path (store as `contextPath`) +- Typical pattern: `.workflow/[sessionId]/.process/context-package.json` + +**Validation**: +- Context package path extracted +- File exists and is valid JSON + +**TodoWrite**: Mark phase 2 completed, phase 3 in_progress + +**After Phase 2**: Return to user showing Phase 2 results, then auto-continue to Phase 3 + +--- ### Phase 3: Test Coverage Analysis **Command**: `/workflow:tools:test-context-gather --session [sessionId]` @@ -63,34 +85,49 @@ TEST_FOCUS: [Test scenarios] - Prevents duplicate test creation - Enables integration with existing tests -### Phase 4: TDD Analysis -**Command**: `/workflow:tools:concept-enhanced --session [sessionId] --context [contextPath]` +**TodoWrite**: Mark phase 3 completed, phase 4 in_progress -**Note**: Generates ANALYSIS_RESULTS.md with TDD-specific structure: -- Feature list with testable requirements -- Test cases for Red phase -- Implementation requirements for Green phase -- Refactoring opportunities -- Task dependencies and execution order +**After Phase 3**: Return to user showing test coverage results, then auto-continue to Phase 4 -**Parse**: Verify ANALYSIS_RESULTS.md contains TDD breakdown sections +--- -### Phase 5: Concept Verification (NEW QUALITY GATE) -**Command**: `/workflow:concept-verify --session [sessionId]` +### Phase 4: Conflict Resolution (Optional - auto-triggered by conflict risk) -**Purpose**: Verify conceptual clarity before TDD task generation -- Clarify test requirements and acceptance criteria -- Resolve ambiguities in expected behavior -- Validate TDD approach is appropriate +**Trigger**: Only execute when context-package.json indicates conflict_risk is "medium" or "high" -**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 +**Command**: `SlashCommand(command="/workflow:tools:conflict-resolution --session [sessionId] --context [contextPath]")` -**Parse**: Verify concept verification completed (check for clarifications section in ANALYSIS_RESULTS.md or synthesis file if exists) +**Input**: +- sessionId from Phase 1 +- contextPath from Phase 2 +- conflict_risk from context-package.json -### Phase 6: TDD Task Generation +**Parse Output**: +- Extract: Execution status (success/skipped/failed) +- Verify: CONFLICT_RESOLUTION.md file path (if executed) + +**Validation**: +- File `.workflow/[sessionId]/.process/CONFLICT_RESOLUTION.md` exists (if executed) + +**Skip Behavior**: +- If conflict_risk is "none" or "low", skip directly to Phase 5 +- Display: "No significant conflicts detected, proceeding to TDD task generation" + +**TodoWrite**: Mark phase 4 completed (if executed) or skipped, phase 5 in_progress + +**After Phase 4**: Return to user showing conflict resolution results (if executed) and selected strategies, then auto-continue to Phase 5 + +**Memory State Check**: +- Evaluate current context window usage and memory state +- If memory usage is high (>110K tokens or approaching context limits): + - **Command**: `SlashCommand(command="/compact")` + - This optimizes memory before proceeding to Phase 5 +- Memory compaction is particularly important after analysis phase which may generate extensive documentation +- Ensures optimal performance and prevents context overflow + +--- + +### Phase 5: TDD Task Generation **Command**: - Manual: `/workflow:tools:task-generate-tdd --session [sessionId]` - Agent: `/workflow:tools:task-generate-tdd --session [sessionId] --agent` @@ -108,7 +145,7 @@ TEST_FOCUS: [Test scenarios] - IMPL_PLAN.md contains workflow_type: "tdd" in frontmatter - Task count ≤10 (compliance with task limit) -### Phase 7: TDD Structure Validation & Action Plan Verification (RECOMMENDED) +### Phase 6: TDD Structure Validation & Action Plan Verification (RECOMMENDED) **Internal validation first, then recommend external verification** **Internal Validation**: @@ -166,18 +203,44 @@ TDD Configuration: ## TodoWrite Pattern ```javascript -// 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 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"} -] +// Initialize (Phase 4 added dynamically after Phase 3 if conflict_risk ≥ medium) +TodoWrite({todos: [ + {"content": "Execute session discovery", "status": "in_progress", "activeForm": "Executing session discovery"}, + {"content": "Execute context gathering", "status": "pending", "activeForm": "Executing context gathering"}, + {"content": "Execute test coverage analysis", "status": "pending", "activeForm": "Executing test coverage analysis"}, + // Phase 4 todo added dynamically after Phase 3 if conflict_risk ≥ medium + {"content": "Execute TDD task generation", "status": "pending", "activeForm": "Executing TDD task generation"}, + {"content": "Validate TDD structure", "status": "pending", "activeForm": "Validating TDD structure"} +]}) -// Update after each phase: mark current "completed", next "in_progress" +// After Phase 3 (if conflict_risk ≥ medium, insert Phase 4 todo) +TodoWrite({todos: [ + {"content": "Execute session discovery", "status": "completed", "activeForm": "Executing session discovery"}, + {"content": "Execute context gathering", "status": "completed", "activeForm": "Executing context gathering"}, + {"content": "Execute test coverage analysis", "status": "completed", "activeForm": "Executing test coverage analysis"}, + {"content": "Execute conflict resolution", "status": "in_progress", "activeForm": "Executing conflict resolution"}, + {"content": "Execute TDD task generation", "status": "pending", "activeForm": "Executing TDD task generation"}, + {"content": "Validate TDD structure", "status": "pending", "activeForm": "Validating TDD structure"} +]}) + +// After Phase 3 (if conflict_risk is none/low, skip Phase 4, go directly to Phase 5) +TodoWrite({todos: [ + {"content": "Execute session discovery", "status": "completed", "activeForm": "Executing session discovery"}, + {"content": "Execute context gathering", "status": "completed", "activeForm": "Executing context gathering"}, + {"content": "Execute test coverage analysis", "status": "completed", "activeForm": "Executing test coverage analysis"}, + {"content": "Execute TDD task generation", "status": "in_progress", "activeForm": "Executing TDD task generation"}, + {"content": "Validate TDD structure", "status": "pending", "activeForm": "Validating TDD structure"} +]}) + +// After Phase 4 (if executed), continue to Phase 5 +TodoWrite({todos: [ + {"content": "Execute session discovery", "status": "completed", "activeForm": "Executing session discovery"}, + {"content": "Execute context gathering", "status": "completed", "activeForm": "Executing context gathering"}, + {"content": "Execute test coverage analysis", "status": "completed", "activeForm": "Executing test coverage analysis"}, + {"content": "Execute conflict resolution", "status": "completed", "activeForm": "Executing conflict resolution"}, + {"content": "Execute TDD task generation", "status": "in_progress", "activeForm": "Executing TDD task generation"}, + {"content": "Validate TDD structure", "status": "pending", "activeForm": "Validating TDD structure"} +]}) ``` ## Input Processing diff --git a/.claude/commands/workflow/tools/concept-enhanced.md b/.claude/commands/workflow/tools/concept-enhanced.md deleted file mode 100644 index 2cbcff59..00000000 --- a/.claude/commands/workflow/tools/concept-enhanced.md +++ /dev/null @@ -1,229 +0,0 @@ ---- -name: concept-enhanced -description: Architecture validation and implementation enhancement with CLI-powered analysis -argument-hint: "--session WFS-session-id --context path/to/context-package.json" -examples: - - /workflow:tools:concept-enhanced --session WFS-auth --context .workflow/WFS-auth/.process/context-package.json - - /workflow:tools:concept-enhanced --session WFS-payment --context .workflow/WFS-payment/.process/context-package.json ---- - -# Architecture Validation Command (/workflow:tools:concept-enhanced) - -## Overview -Architecture validation and implementation enhancement engine with CLI-powered analysis. Validates existing architectural approaches and enhances implementation details through Gemini/Codex analysis. - -**Scope**: Validation and enhancement only. Does NOT generate new designs, task breakdowns, or implementation plans. - -**Usage**: Optional enhancement in `/workflow:plan` (requires `--cli-enhance` flag). Accepts context packages and validates architectural soundness. - -## Core Philosophy & Responsibilities -- **Agent Coordination**: Delegate validation execution to specialized agent (cli-execution-agent) -- **Validation-Focused**: Verify architectural soundness, identify risks and quality issues -- **Context-Driven**: Parse and validate context-package.json for precise validation -- **Agent-Driven Tool Selection**: Agent autonomously selects Gemini/Codex based on validation needs -- **Architecture Validation**: Verify design decisions, assess technical feasibility and risks -- **Implementation Enhancement**: Identify optimization opportunities for performance, security, and quality -- **Output Validation**: Verify ANALYSIS_RESULTS.md generation and quality -- **Single Output**: Generate only ANALYSIS_RESULTS.md with validation findings and enhancement recommendations - -## Analysis Strategy Selection - -**Agent-Driven Strategy**: cli-execution-agent autonomously determines tool selection based on: -- **Task Complexity**: Number of modules, integration scope, technical depth -- **Tech Stack**: Frontend (Gemini-focused), Backend (Codex-preferred), Fullstack (hybrid) -- **Validation Focus**: Architecture validation (Gemini), Feasibility verification (Codex), Quality assessment (both) - -**Complexity Tiers** (Agent decides internally): -- **Simple (≤3 modules)**: Gemini-only analysis -- **Medium (4-6 modules)**: Gemini comprehensive analysis -- **Complex (>6 modules)**: Gemini + Codex parallel execution - -## Execution Lifecycle - -### Phase 1: Validation & Preparation -1. **Session Validation**: Verify `.workflow/{session_id}/` exists, load `workflow-session.json` -2. **Context Package Validation**: Verify path, validate JSON format and structure -3. **Task Analysis**: Extract keywords, identify domain/complexity, determine scope -4. **Agent Preparation**: Prepare agent task prompt with complete analysis requirements - -### Phase 2: Agent-Delegated Analysis - -**Agent Invocation**: -```javascript -Task( - subagent_type="cli-execution-agent", - description="Enhanced solution design and feasibility analysis", - prompt=` -## Execution Context - -**Session ID**: {session_id} -**Mode**: Enhanced Analysis with CLI Tool Orchestration - -## Input Context - -**Context Package**: {context_path} -**Session State**: .workflow/{session_id}/workflow-session.json -**Project Standards**: CLAUDE.md - -## Analysis Task - -### Analysis Templates (Use these to guide CLI tool execution) -- **Document Structure**: ~/.claude/workflows/cli-templates/prompts/workflow/analysis-results-structure.txt -- **Gemini Analysis**: ~/.claude/workflows/cli-templates/prompts/workflow/gemini-solution-design.txt -- **Codex Validation**: ~/.claude/workflows/cli-templates/prompts/workflow/codex-feasibility-validation.txt - -### Execution Strategy -1. **Load Context**: Read context-package.json to determine task complexity (module count, integration scope) -2. **Gemini Analysis** (ALL tasks): Execute using gemini-solution-design.txt template - - Output: .workflow/{session_id}/.process/gemini-solution-design.md -3. **Codex Validation** (COMPLEX tasks >6 modules only): Execute using codex-feasibility-validation.txt template - - Output: .workflow/{session_id}/.process/codex-feasibility-validation.md -4. **Synthesize Results**: Combine outputs into ANALYSIS_RESULTS.md following analysis-results-structure.txt - -### Output Requirements - -**Intermediate Outputs**: -- Gemini: \`.workflow/{session_id}/.process/gemini-solution-design.md\` (always required) -- Codex: \`.workflow/{session_id}/.process/codex-feasibility-validation.md\` (complex tasks only) - -**Final Output**: -- \`.workflow/{session_id}/.process/ANALYSIS_RESULTS.md\` (synthesized, required) - -**Required Sections** (7 sections per analysis-results-structure.txt): -1. Executive Summary -2. Current State Analysis -3. Proposed Solution Design -4. Implementation Strategy -5. Solution Optimization -6. Critical Success Factors -7. Reference Information - -### Synthesis Rules -- Follow 7-section structure from analysis-results-structure.txt -- Integrate Gemini insights as primary content -- Incorporate Codex validation findings (if executed) -- Resolve conflicts between tools with clear rationale -- Generate confidence scores (1-5 scale) for all assessment dimensions -- Provide final recommendation: PROCEED | PROCEED_WITH_MODIFICATIONS | RECONSIDER | REJECT - -## Output -Generate final ANALYSIS_RESULTS.md and report completion status: -- Gemini analysis: [completed/failed] -- Codex validation: [completed/skipped/failed] -- Synthesis: [completed/failed] -- Final output: .workflow/{session_id}/.process/ANALYSIS_RESULTS.md -` -) -``` - -**Agent Execution Flow** (Internal to cli-execution-agent): -1. Parse session ID and context path, load context-package.json -2. Analyze task complexity (module count, integration scope) -3. Discover additional context via MCP code-index -4. Execute Gemini analysis (all tasks) with template-guided prompt -5. Execute Codex validation (complex tasks >6 modules) with template-guided prompt -6. Synthesize Gemini + Codex outputs into ANALYSIS_RESULTS.md -7. Verify output file exists at correct path -8. Return execution log path - -**Command Execution**: Launch agent via Task tool, wait for completion - -### Phase 3: Output Validation -1. **File Verification**: Confirm `.workflow/{session_id}/.process/ANALYSIS_RESULTS.md` exists -2. **Content Validation**: Verify required sections present (Executive Summary, Solution Design, etc.) -3. **Quality Check**: Ensure design rationale, feasibility assessment, confidence scores included -4. **Agent Log**: Retrieve agent execution log from `.workflow/{session_id}/.chat/` -5. **Success Criteria**: File exists, contains all required sections, meets quality standards - -## Analysis Results Format - -**Template Reference**: `~/.claude/workflows/cli-templates/prompts/workflow/analysis-results-structure.txt` - -Generated ANALYSIS_RESULTS.md focuses on **validation findings, quality assessment, and enhancement recommendations** (NOT new designs or task planning). - -### Required Structure (7 Sections) - -1. **Executive Summary**: Validation focus, tools used, overall assessment (X/5), recommendation status -2. **Current State Analysis**: Architecture overview, compatibility/dependencies, critical findings -3. **Architecture Validation**: Verify design soundness, assess feasibility, identify risks with rationale -4. **Implementation Enhancement**: Code quality improvements, optimization opportunities, risk mitigation -5. **Quality Optimization**: Performance, security, code quality recommendations -6. **Critical Success Factors**: Technical requirements, quality metrics, validation criteria -7. **Reference Information**: Tool analysis summary, context & resources - -### Key Requirements - -**Code Modification Targets**: -- Existing files: `file:function:lines` (e.g., `src/auth/login.ts:validateUser:45-52`) -- New files: `file` only (e.g., `src/auth/PasswordReset.ts`) -- Unknown lines: `file:function:*` - -**Validation Findings** (minimum 2): -- Finding statement (what was validated/discovered) -- Assessment (risks, quality issues, improvement opportunities) -- Recommendations (specific actions to address findings) -- Impact (implications on implementation) - -**Assessment Scores** (1-5 scale): -- Conceptual Integrity, Architectural Soundness, Technical Feasibility, Implementation Readiness -- Overall Confidence score -- Final Recommendation: PROCEED | PROCEED_WITH_MODIFICATIONS | RECONSIDER | REJECT - -### Content Focus -- ✅ Validation findings and quality assessment -- ✅ Enhancement opportunities with specific recommendations -- ✅ Risk identification and mitigation strategies -- ✅ Optimization recommendations (performance, security, quality) -- ❌ New design proposals or architectural changes -- ❌ Task lists or implementation steps -- ❌ Code examples or snippets -- ❌ Project management timelines - -## Execution Management - -### Error Handling & Recovery -1. **Pre-execution**: Verify session/context package exists and is valid -2. **Agent Monitoring**: Track agent execution status via Task tool -3. **Validation**: Check ANALYSIS_RESULTS.md generation on completion -4. **Error Recovery**: - - Agent execution failure → report error, check agent logs - - Missing output file → retry agent execution once - - Incomplete output → use agent logs to diagnose issue -5. **Graceful Degradation**: If agent fails, report specific error and suggest manual analysis - -### Agent Delegation Benefits -- **Autonomous Tool Selection**: Agent decides Gemini/Codex based on complexity -- **Context Discovery**: Agent discovers additional relevant files via MCP -- **Prompt Enhancement**: Agent optimizes prompts with discovered patterns -- **Error Handling**: Agent manages CLI tool failures internally -- **Log Tracking**: Agent execution logs saved to `.workflow/{session_id}/.chat/` - -## Integration & Success Criteria - -### Input/Output Interface -**Input**: -- `--session` (required): Session ID (e.g., WFS-auth) -- `--context` (required): Context package path - -**Output**: -- Single file: `ANALYSIS_RESULTS.md` at `.workflow/{session_id}/.process/` -- No supplementary files (JSON, roadmap, templates) - -### Quality & Success Validation -**Quality Checks**: Completeness, consistency, feasibility validation - -**Success Criteria**: -- ✅ Validation-focused analysis (quality assessment, enhancement recommendations, NO new designs or task planning) -- ✅ Single output file only (ANALYSIS_RESULTS.md) -- ✅ Validation findings depth with assessment/recommendations/impact -- ✅ Quality assessment (risks, improvement opportunities, readiness) -- ✅ Enhancement strategies (performance, security, quality optimization) -- ✅ Agent-driven tool selection (autonomous Gemini/Codex execution) -- ✅ Robust error handling (validation, retry, graceful degradation) -- ✅ Confidence scoring with clear recommendation status -- ✅ Agent execution log saved to session chat directory - -## Related Commands -- `/context:gather` - Generate context packages required by this command -- `/workflow:plan --cli-enhance` - Optionally call this command for validation enhancement -- `/task:create` - Create specific tasks based on validation results \ No newline at end of file diff --git a/.claude/commands/workflow/tools/task-generate-tdd.md b/.claude/commands/workflow/tools/task-generate-tdd.md index cbffd438..4f6faeed 100644 --- a/.claude/commands/workflow/tools/task-generate-tdd.md +++ b/.claude/commands/workflow/tools/task-generate-tdd.md @@ -72,25 +72,35 @@ Generate TDD-specific tasks from analysis results with complete Red-Green-Refact - If session metadata in memory → Skip loading - Else: Load `.workflow/{session_id}/workflow-session.json` -2. **Analysis Results Loading** - - If ANALYSIS_RESULTS.md in memory → Skip loading - - Else: Read `.workflow/{session_id}/.process/ANALYSIS_RESULTS.md` +2. **Conflict Resolution Check** (NEW - Priority Input) + - If CONFLICT_RESOLUTION.md exists → Load selected strategies + - Else: Skip to brainstorming artifacts + - Path: `.workflow/{session_id}/.process/CONFLICT_RESOLUTION.md` 3. **Artifact Discovery** - If artifact inventory in memory → Skip scanning - Else: Scan `.workflow/{session_id}/.brainstorming/` directory - Detect: role analysis documents, guidance-specification.md, role analyses +4. **Context Package Loading** + - Load `.workflow/{session_id}/.process/context-package.json` + - Load `.workflow/{session_id}/.process/test-context-package.json` (if exists) + ### Phase 2: TDD Task JSON Generation -**Input**: Use `.process/ANALYSIS_RESULTS.md` directly (enhanced with TDD structure from concept-enhanced phase) +**Input Sources** (priority order): +1. **Conflict Resolution** (if exists): `.process/CONFLICT_RESOLUTION.md` - Selected resolution strategies +2. **Brainstorming Artifacts**: Role analysis documents (system-architect, product-owner, etc.) +3. **Context Package**: `.process/context-package.json` - Project structure and requirements +4. **Test Context**: `.process/test-context-package.json` - Existing test patterns -**ANALYSIS_RESULTS.md includes**: +**TDD Task Structure includes**: - Feature list with testable requirements - Test cases for Red phase -- Implementation requirements for Green phase +- Implementation requirements for Green phase (with test-fix cycle) - Refactoring opportunities - Task dependencies and execution order +- Conflict resolution decisions (if applicable) ### Phase 3: Task JSON & IMPL_PLAN.md Generation @@ -247,13 +257,14 @@ Generate IMPL_PLAN.md with 8-section structure: --- identifier: WFS-{session-id} source: "User requirements" | "File: path" -analysis: .workflow/{session-id}/.process/ANALYSIS_RESULTS.md +conflict_resolution: .workflow/{session-id}/.process/CONFLICT_RESOLUTION.md # if exists context_package: .workflow/{session-id}/.process/context-package.json +test_context: .workflow/{session-id}/.process/test-context-package.json # if exists workflow_type: "tdd" verification_history: - concept_verify: "passed | skipped | pending" + conflict_resolution: "executed | skipped" # based on conflict_risk action_plan_verify: "pending" -phase_progression: "brainstorm → context → test_context → analysis → concept_verify → tdd_planning" +phase_progression: "brainstorm → context → test_context → conflict_resolution → tdd_planning" feature_count: N task_count: N # ≤10 total task_breakdown: @@ -283,10 +294,10 @@ tdd_workflow: true ## 3. Brainstorming Artifacts Reference - Artifact Usage Strategy + - CONFLICT_RESOLUTION.md (if exists - selected resolution strategies) - role analysis documents (primary reference) - test-context-package.json (test patterns) - context-package.json (smart context) - - ANALYSIS_RESULTS.md (technical analysis) - Artifact Priority in Development ## 4. Implementation Strategy @@ -397,7 +408,7 @@ Update workflow-session.json with TDD metadata: │ ├── IMPL-3.2.json # Complex feature subtask (if needed) │ └── ... └── .process/ - ├── ANALYSIS_RESULTS.md # Enhanced with TDD breakdown from concept-enhanced + ├── CONFLICT_RESOLUTION.md # Conflict resolution strategies (if conflict_risk ≥ medium) ├── test-context-package.json # Test coverage analysis ├── context-package.json # Input from context-gather └── green-fix-iteration-*.md # Fix logs from Green phase test-fix cycles @@ -438,7 +449,7 @@ Update workflow-session.json with TDD metadata: | Error | Cause | Resolution | |-------|-------|------------| | Session not found | Invalid session ID | Verify session exists | -| Analysis missing | Incomplete planning | Run concept-enhanced first | +| Context missing | Incomplete planning | Run context-gather first | ### TDD Generation Errors | Error | Cause | Resolution | diff --git a/.claude/commands/workflow/tools/task-generate.md b/.claude/commands/workflow/tools/task-generate.md index 40d7b2d1..4ddc2803 100644 --- a/.claude/commands/workflow/tools/task-generate.md +++ b/.claude/commands/workflow/tools/task-generate.md @@ -784,7 +784,7 @@ When using `--cli-execute`, each step in `implementation_approach` includes a `c | Error | Cause | Resolution | |-------|-------|------------| | Session not found | Invalid session ID | Verify session exists | -| Analysis missing | Incomplete planning | Run concept-enhanced first | +| Context missing | Incomplete planning | Run context-gather first | | Invalid format | Corrupted results | Regenerate analysis | ### Task Generation Errors @@ -817,5 +817,5 @@ When using `--cli-execute`, each step in `implementation_approach` includes a `c - `/workflow:plan` - Orchestrates entire planning - `/workflow:plan --cli-execute` - Planning with CLI execution mode - `/workflow:tools:context-gather` - Provides context package -- `/workflow:tools:concept-enhanced` - Provides analysis results +- `/workflow:tools:conflict-resolution` - Provides conflict resolution strategies (optional) - `/workflow:execute` - Executes generated tasks diff --git a/.claude/commands/workflow/ui-design/update.md b/.claude/commands/workflow/ui-design/update.md index 01979e9d..48265467 100644 --- a/.claude/commands/workflow/ui-design/update.md +++ b/.claude/commands/workflow/ui-design/update.md @@ -122,12 +122,77 @@ IF section not found: Edit(file_path="...", old_string="[end of document]", new_string="\n\n## UI/UX Guidelines\n\n[new design reference content]") ``` -### Phase 4: Update UI Designer Style Guide +### Phase 4A: Update Relevant Role Analysis Documents -Create or update `.brainstorming/ui-designer/style-guide.md`: +**Discovery**: Find role analysis.md files affected by design outputs + +```bash +# Always update ui-designer +ui_designer_files = Glob(".workflow/WFS-{session}/.brainstorming/ui-designer/analysis*.md") + +# Conditionally update other roles +has_animations = exists({latest_design}/animation-extraction/animation-tokens.json) +has_layouts = exists({latest_design}/layout-extraction/layout-templates.json) + +IF has_animations: ux_expert_files = Glob(".workflow/WFS-{session}/.brainstorming/ux-expert/analysis*.md") +IF has_layouts: architect_files = Glob(".workflow/WFS-{session}/.brainstorming/system-architect/analysis*.md") +IF selected_list: pm_files = Glob(".workflow/WFS-{session}/.brainstorming/product-manager/analysis*.md") +``` + +**Content Templates**: + +**ui-designer/analysis.md** (append if not exists): +```markdown +## Design System Implementation Reference + +**Design Tokens**: @../../design-{run_id}/{design_tokens_path} +**Style Guide**: @../../design-{run_id}/{style_guide_path} +**Prototypes**: {FOR each: @../../design-{run_id}/prototypes/{prototype}.html} + +*Reference added by /workflow:ui-design:update* +``` + +**ux-expert/analysis.md** (if animations): +```markdown +## Animation & Interaction Reference + +**Animations**: @../../design-{run_id}/animation-extraction/animation-tokens.json +**Prototypes**: {FOR each: @../../design-{run_id}/prototypes/{prototype}.html} + +*Reference added by /workflow:ui-design:update* +``` + +**system-architect/analysis.md** (if layouts): +```markdown +## Layout Structure Reference + +**Layout Templates**: @../../design-{run_id}/layout-extraction/layout-templates.json + +*Reference added by /workflow:ui-design:update* +``` + +**product-manager/analysis.md** (if prototypes): +```markdown +## Prototype Validation Reference + +**Prototypes**: {FOR each: @../../design-{run_id}/prototypes/{prototype}.html} + +*Reference added by /workflow:ui-design:update* +``` + +**Implementation**: +```bash +FOR file IN [ui_designer_files, ux_expert_files, architect_files, pm_files]: + IF file exists AND section_not_exists(file): + Edit(file, old_string="[end of document]", new_string="\n\n{role-specific section}") +``` + +### Phase 4B: Create UI Designer Design System Reference + +Create or update `.brainstorming/ui-designer/design-system-reference.md`: ```markdown -# UI Designer Style Guide +# UI Designer Design System Reference ## Design System Integration This style guide references the finalized design system from the design refinement phase. @@ -158,7 +223,7 @@ For complete token definitions and usage examples, see: **Implementation**: ```bash -Write(file_path=".workflow/WFS-{session}/.brainstorming/ui-designer/style-guide.md", +Write(file_path=".workflow/WFS-{session}/.brainstorming/ui-designer/design-system-reference.md", content="[generated content with @ references]") ``` @@ -169,7 +234,8 @@ TodoWrite({todos: [ {content: "Validate session and design system artifacts", status: "completed", activeForm: "Validating artifacts"}, {content: "Load target brainstorming artifacts", status: "completed", activeForm: "Loading target files"}, {content: "Update role analysis documents with design references", status: "completed", activeForm: "Updating synthesis spec"}, - {content: "Create/update ui-designer/style-guide.md", status: "completed", activeForm: "Updating UI designer guide"} + {content: "Update relevant role analysis.md documents", status: "completed", activeForm: "Updating role analysis files"}, + {content: "Create/update ui-designer/design-system-reference.md", status: "completed", activeForm: "Creating design system reference"} ]}); ``` @@ -179,7 +245,8 @@ TodoWrite({todos: [ Updated artifacts: ✓ role analysis documents - UI/UX Guidelines section with @ references -✓ ui-designer/style-guide.md - Design system reference guide +✓ {role_count} role analysis.md files - Design system references +✓ ui-designer/design-system-reference.md - Design system reference guide Design system assets ready for /workflow:plan: - design-tokens.json | style-guide.md | {prototype_count} reference prototypes @@ -193,9 +260,13 @@ Next: /workflow:plan [--agent] "" **Updated Files**: ``` .workflow/WFS-{session}/.brainstorming/ -├── role analysis documents # Updated with UI/UX Guidelines section -└── ui-designer/ - └── style-guide.md # New or updated design reference guide +├── role analysis documents # Updated with UI/UX Guidelines section +├── ui-designer/ +│ ├── analysis*.md # Updated with design system references +│ └── design-system-reference.md # New or updated design reference guide +├── ux-expert/analysis*.md # Updated if animations exist +├── product-manager/analysis*.md # Updated if prototypes exist +└── system-architect/analysis*.md # Updated if layouts exist ``` **@ Reference Format** (role analysis documents): @@ -205,13 +276,21 @@ Next: /workflow:plan [--agent] "" @../design-{run_id}/prototypes/{prototype}.html ``` -**@ Reference Format** (ui-designer/style-guide.md): +**@ Reference Format** (ui-designer/design-system-reference.md): ``` @../../design-{run_id}/style-extraction/style-1/design-tokens.json @../../design-{run_id}/style-extraction/style-1/style-guide.md @../../design-{run_id}/prototypes/{prototype}.html ``` +**@ Reference Format** (role analysis.md files): +``` +@../../design-{run_id}/style-extraction/style-1/design-tokens.json +@../../design-{run_id}/animation-extraction/animation-tokens.json +@../../design-{run_id}/layout-extraction/layout-templates.json +@../../design-{run_id}/prototypes/{prototype}.html +``` + ## Integration with /workflow:plan After this update, `/workflow:plan` will discover design assets through: @@ -249,7 +328,9 @@ After this update, `/workflow:plan` will discover design assets through: After update, verify: - [ ] role analysis documents contains UI/UX Guidelines section - [ ] UI/UX Guidelines include @ references (not content duplication) -- [ ] ui-designer/style-guide.md created or updated +- [ ] ui-designer/analysis*.md updated with design system references +- [ ] ui-designer/design-system-reference.md created or updated +- [ ] Relevant role analysis.md files updated (ux-expert, product-manager, system-architect) - [ ] All @ referenced files exist and are accessible - [ ] @ reference paths are relative and correct @@ -264,7 +345,7 @@ After update, verify: ## Integration Points - **Input**: Design system artifacts from `/workflow:ui-design:style-extract` and `/workflow:ui-design:generate` -- **Output**: Updated role analysis documents, ui-designer/style-guide.md with @ references +- **Output**: Updated role analysis documents, role analysis.md files, ui-designer/design-system-reference.md with @ references - **Next Phase**: `/workflow:plan` discovers and utilizes design system through @ references - **Auto Integration**: Automatically triggered by `/workflow:ui-design:auto` workflow