mirror of
https://github.com/catlog22/Claude-Code-Workflow.git
synced 2026-02-13 02:41:50 +08:00
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.
This commit is contained in:
catlog22
@@ -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]
|
||||
## Agent Mission
|
||||
Analyze role documents, identify conflicts/gaps, and generate enhancement recommendations
|
||||
|
||||
Execute comprehensive cross-role analysis, ambiguity detection, user clarification, and intelligent document updates
|
||||
## Input from Main Flow
|
||||
- brainstorm_dir: {brainstorm_dir}
|
||||
- role_analysis_paths: {role_analysis_paths}
|
||||
- participating_roles: {participating_roles}
|
||||
|
||||
## Context Loading
|
||||
SESSION_ID: {session_id}
|
||||
BRAINSTORM_DIR: .workflow/WFS-{session}/.brainstorming/
|
||||
ANALYSIS_MODE: cross_role_clarification_and_update
|
||||
MAX_QUESTIONS: 5
|
||||
## Execution Instructions
|
||||
[FLOW_CONTROL]
|
||||
|
||||
## ⚠️ 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.
|
||||
### Flow Control Steps
|
||||
**AGENT RESPONSIBILITY**: Execute these analysis steps sequentially with context accumulation:
|
||||
|
||||
## Workflow Steps
|
||||
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)
|
||||
|
||||
### 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_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}
|
||||
|
||||
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. **cross_role_analysis**
|
||||
- Action: Identify consensus themes, conflicts, gaps, underspecified areas
|
||||
- Output: consensus_themes, conflicting_views, gaps_list, ambiguities
|
||||
|
||||
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. **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
|
||||
|
||||
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
|
||||
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)
|
||||
|
||||
### 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}**
|
||||
### 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\"
|
||||
},
|
||||
...
|
||||
\`\`\`
|
||||
]
|
||||
|
||||
**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: <!-- Superseded by clarification {date} -->
|
||||
```
|
||||
|
||||
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 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": ["<dynamically-discovered-role-1>", "<dynamically-discovered-role-2>", "..."],
|
||||
"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": <count>,
|
||||
"categories_clarified": [<list of categories>],
|
||||
"roles_updated": [<list of updated role names>],
|
||||
"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}
|
||||
```
|
||||
|
||||
|
||||
@@ -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
|
||||
|
||||
@@ -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
|
||||
@@ -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 |
|
||||
|
||||
@@ -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
|
||||
|
||||
@@ -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
|
||||
@@ -194,8 +261,12 @@ Next: /workflow:plan [--agent] "<task description>"
|
||||
```
|
||||
.workflow/WFS-{session}/.brainstorming/
|
||||
├── role analysis documents # Updated with UI/UX Guidelines section
|
||||
└── ui-designer/
|
||||
└── style-guide.md # New or updated design reference guide
|
||||
├── 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] "<task description>"
|
||||
@../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
|
||||
|
||||
|
||||
Reference in New Issue
Block a user