diff --git a/.claude/agents/action-planning-agent.md b/.claude/agents/action-planning-agent.md index 883b2035..7bbe6353 100644 --- a/.claude/agents/action-planning-agent.md +++ b/.claude/agents/action-planning-agent.md @@ -26,7 +26,7 @@ You are a pure execution agent specialized in creating actionable implementation - `session_id`: Workflow session identifier (WFS-[topic]) - `session_metadata`: Session configuration and state - `analysis_results`: Analysis recommendations and task breakdown - - `artifacts_inventory`: Detected brainstorming outputs (synthesis-spec, topic-framework, role analyses) + - `artifacts_inventory`: Detected brainstorming outputs (role analyses, guidance-specification, role analyses) - `context_package`: Project context and assets - `mcp_capabilities`: Available MCP tools (code-index, exa-code, exa-web) - `mcp_analysis`: Optional pre-executed MCP analysis results @@ -77,8 +77,8 @@ Phase 2: Document Generation (Autonomous Output) "dependencies": [...] }, "artifacts_inventory": { - "synthesis_specification": ".workflow/WFS-auth/.brainstorming/synthesis-specification.md", - "topic_framework": ".workflow/WFS-auth/.brainstorming/topic-framework.md", + "synthesis_specification": ".workflow/WFS-auth/.brainstorming/role analysis documents", + "topic_framework": ".workflow/WFS-auth/.brainstorming/guidance-specification.md", "role_analyses": [ ".workflow/WFS-auth/.brainstorming/system-architect/analysis.md", ".workflow/WFS-auth/.brainstorming/subject-matter-expert/analysis.md" @@ -194,17 +194,17 @@ Generate individual `.task/IMPL-*.json` files with: "implementation_approach": [ { "step": 1, - "title": "Load and analyze synthesis specification", - "description": "Load synthesis specification from artifacts and extract requirements", - "modification_points": ["Load synthesis specification", "Extract requirements and design patterns"], - "logic_flow": ["Read synthesis specification from artifacts", "Parse architecture decisions", "Extract implementation requirements"], + "title": "Load and analyze role analyses", + "description": "Load role analyses from artifacts and extract requirements", + "modification_points": ["Load role analyses", "Extract requirements and design patterns"], + "logic_flow": ["Read role analyses from artifacts", "Parse architecture decisions", "Extract implementation requirements"], "depends_on": [], "output": "synthesis_requirements" }, { "step": 2, "title": "Implement following specification", - "description": "Implement task requirements following consolidated synthesis specification", + "description": "Implement task requirements following consolidated role analyses", "modification_points": ["Apply requirements from [synthesis_requirements]", "Modify target files", "Integrate with existing code"], "logic_flow": ["Apply changes based on [synthesis_requirements]", "Implement core logic", "Validate against acceptance criteria"], "depends_on": [1], diff --git a/.claude/agents/conceptual-planning-agent.md b/.claude/agents/conceptual-planning-agent.md index 0466be86..5ab26724 100644 --- a/.claude/agents/conceptual-planning-agent.md +++ b/.claude/agents/conceptual-planning-agent.md @@ -99,7 +99,7 @@ This agent processes **simplified inline [FLOW_CONTROL]** format from brainstorm ### Flow Control Steps 1. **load_topic_framework** - Action: Load structured topic framework - - Command: Read(.workflow/WFS-{session}/.brainstorming/topic-framework.md) + - Command: Read(.workflow/WFS-{session}/.brainstorming/guidance-specification.md) - Output: topic_framework 2. **load_role_template** diff --git a/.claude/agents/ui-design-agent.md b/.claude/agents/ui-design-agent.md index 6f69600a..4bc8c988 100644 --- a/.claude/agents/ui-design-agent.md +++ b/.claude/agents/ui-design-agent.md @@ -35,7 +35,7 @@ You are a specialized **UI Design Agent** that executes design generation tasks ### 2. Layout Strategy Generation **Invoked by**: `consolidate.md` Phase 2.5 -**Input**: Project context from synthesis-specification.md +**Input**: Project context from role analysis documents **Task**: Research and generate adaptive layout strategies via Exa MCP (2024-2025 trends) **Output**: layout-strategies.json with strategy definitions and rationale diff --git a/.claude/commands/workflow/action-plan-verify.md b/.claude/commands/workflow/action-plan-verify.md index 563552f3..c090bac1 100644 --- a/.claude/commands/workflow/action-plan-verify.md +++ b/.claude/commands/workflow/action-plan-verify.md @@ -15,13 +15,13 @@ You **MUST** consider the user input before proceeding (if not empty). ## Goal -Identify inconsistencies, duplications, ambiguities, and underspecified items between action planning artifacts (`IMPL_PLAN.md`, `task.json`) and brainstorming artifacts (`synthesis-specification.md`) before implementation. This command MUST run only after `/workflow:plan` has successfully produced complete `IMPL_PLAN.md` and task JSON files. +Identify inconsistencies, duplications, ambiguities, and underspecified items between action planning artifacts (`IMPL_PLAN.md`, `task.json`) and brainstorming artifacts (`role analysis documents`) before implementation. This command MUST run only after `/workflow:plan` has successfully produced complete `IMPL_PLAN.md` and task JSON files. ## Operating Constraints **STRICTLY READ-ONLY**: Do **not** modify any files. Output a structured analysis report. Offer an optional remediation plan (user must explicitly approve before any follow-up editing commands). -**Synthesis Authority**: The `synthesis-specification.md` is **authoritative** for requirements and design decisions. Any conflicts between IMPL_PLAN/tasks and synthesis are automatically CRITICAL and require adjustment of the plan/tasksβ€”not reinterpretation of requirements. +**Synthesis Authority**: The `role analysis documents` is **authoritative** for requirements and design decisions. Any conflicts between IMPL_PLAN/tasks and synthesis are automatically CRITICAL and require adjustment of the plan/tasksβ€”not reinterpretation of requirements. ## Execution Steps @@ -45,13 +45,13 @@ brainstorm_dir = session_dir/.brainstorming task_dir = session_dir/.task # Validate required artifacts -SYNTHESIS = brainstorm_dir/synthesis-specification.md +SYNTHESIS = brainstorm_dir/role analysis documents IMPL_PLAN = session_dir/IMPL_PLAN.md TASK_FILES = Glob(task_dir/*.json) # Abort if missing IF NOT EXISTS(SYNTHESIS): - ERROR: "synthesis-specification.md not found. Run /workflow:brainstorm:synthesis first" + ERROR: "role analysis documents not found. Run /workflow:brainstorm:synthesis first" EXIT IF NOT EXISTS(IMPL_PLAN): @@ -72,7 +72,7 @@ Load only minimal necessary context from each artifact: - User's stated goals and objectives - User's scope definition -**From synthesis-specification.md**: +**From role analysis documents**: - Functional Requirements (IDs, descriptions, acceptance criteria) - Non-Functional Requirements (IDs, targets) - Business Requirements (IDs, success metrics) @@ -210,7 +210,7 @@ Output a Markdown report (no file writes) with the following structure: **Session**: WFS-{session-id} **Generated**: {timestamp} -**Artifacts Analyzed**: synthesis-specification.md, IMPL_PLAN.md, {N} task files +**Artifacts Analyzed**: role analysis documents, IMPL_PLAN.md, {N} task files --- diff --git a/.claude/commands/workflow/brainstorm/api-designer.md b/.claude/commands/workflow/brainstorm/api-designer.md index e9041e81..b747aa9f 100644 --- a/.claude/commands/workflow/brainstorm/api-designer.md +++ b/.claude/commands/workflow/brainstorm/api-designer.md @@ -1,6 +1,6 @@ --- name: api-designer -description: Generate or update api-designer/analysis.md addressing topic-framework discussion points +description: Generate or update api-designer/analysis.md addressing guidance-specification discussion points argument-hint: "optional topic - uses existing framework if available" allowed-tools: Task(conceptual-planning-agent), TodoWrite(*), Read(*), Write(*) --- @@ -8,10 +8,10 @@ allowed-tools: Task(conceptual-planning-agent), TodoWrite(*), Read(*), Write(*) ## πŸ”Œ **API Designer Analysis Generator** ### Purpose -**Specialized command for generating api-designer/analysis.md** that addresses topic-framework.md discussion points from backend API design perspective. Creates or updates role-specific analysis with framework references. +**Specialized command for generating api-designer/analysis.md** that addresses guidance-specification.md discussion points from backend API design perspective. Creates or updates role-specific analysis with framework references. ### Core Function -- **Framework-based Analysis**: Address each discussion point in topic-framework.md +- **Framework-based Analysis**: Address each discussion point in guidance-specification.md - **API Design Focus**: RESTful/GraphQL API design, endpoint structure, and contract definition - **Update Mechanism**: Create new or update existing analysis.md - **Agent Delegation**: Use conceptual-planning-agent for analysis generation @@ -51,7 +51,7 @@ IF active_session EXISTS: session_id = get_active_session() brainstorm_dir = .workflow/WFS-{session}/.brainstorming/ - CHECK: brainstorm_dir/topic-framework.md + CHECK: brainstorm_dir/guidance-specification.md IF EXISTS: framework_mode = true load_framework = true @@ -78,20 +78,20 @@ ELSE: ``` ### Phase 3: Agent Task Generation -**Framework-Based Analysis** (when topic-framework.md exists): +**Framework-Based Analysis** (when guidance-specification.md exists): ```bash Task(subagent_type="conceptual-planning-agent", prompt="Generate API designer analysis addressing topic framework ## Framework Integration Required - **MANDATORY**: Load and address topic-framework.md discussion points - **Framework Reference**: @{session.brainstorm_dir}/topic-framework.md + **MANDATORY**: Load and address guidance-specification.md discussion points + **Framework Reference**: @{session.brainstorm_dir}/guidance-specification.md **Output Location**: {session.brainstorm_dir}/api-designer/analysis.md ## Analysis Requirements - 1. **Load Topic Framework**: Read topic-framework.md completely + 1. **Load Topic Framework**: Read guidance-specification.md completely 2. **Address Each Discussion Point**: Respond to all 5 framework sections from API design perspective - 3. **Include Framework Reference**: Start analysis.md with @../topic-framework.md + 3. **Include Framework Reference**: Start analysis.md with @../guidance-specification.md 4. **API Design Focus**: Emphasize endpoint structure, data contracts, versioning strategies 5. **Structured Response**: Use framework structure for analysis organization @@ -106,7 +106,7 @@ Task(subagent_type="conceptual-planning-agent", ```markdown # API Designer Analysis: [Topic] - **Framework Reference**: @../topic-framework.md + **Framework Reference**: @../guidance-specification.md **Role Focus**: Backend API Design and Contract Definition ## Core Requirements Analysis @@ -140,14 +140,14 @@ IF update_mode = "incremental": ## Current Analysis Context **Existing Analysis**: @{session.brainstorm_dir}/api-designer/analysis.md - **Framework Reference**: @{session.brainstorm_dir}/topic-framework.md + **Framework Reference**: @{session.brainstorm_dir}/guidance-specification.md ## Update Requirements 1. **Preserve Structure**: Maintain existing analysis structure 2. **Add New Insights**: Integrate new API design insights and recommendations 3. **Framework Alignment**: Ensure continued alignment with topic framework 4. **API Updates**: Add new endpoint patterns, versioning strategies, documentation improvements - 5. **Maintain References**: Keep @../topic-framework.md reference + 5. **Maintain References**: Keep @../guidance-specification.md reference ## Update Instructions - Read existing analysis completely @@ -163,14 +163,14 @@ IF update_mode = "incremental": ### Output Files ``` .workflow/WFS-[topic]/.brainstorming/ -β”œβ”€β”€ topic-framework.md # Input: Framework (if exists) +β”œβ”€β”€ guidance-specification.md # Input: Framework (if exists) └── api-designer/ └── analysis.md # β˜… OUTPUT: Framework-based analysis ``` ### Analysis Structure **Required Elements**: -- **Framework Reference**: @../topic-framework.md (if framework exists) +- **Framework Reference**: @../guidance-specification.md (if framework exists) - **Role Focus**: Backend API Design and Contract Definition perspective - **5 Framework Sections**: Address each framework discussion point - **API Design Recommendations**: Endpoint-specific insights and solutions diff --git a/.claude/commands/workflow/brainstorm/artifacts.md b/.claude/commands/workflow/brainstorm/artifacts.md index 379aa13b..4925b77a 100644 --- a/.claude/commands/workflow/brainstorm/artifacts.md +++ b/.claude/commands/workflow/brainstorm/artifacts.md @@ -1,229 +1,556 @@ --- name: artifacts -description: Generate role-specific topic-framework.md dynamically based on selected roles -argument-hint: "topic or challenge description for framework generation" -allowed-tools: TodoWrite(*), Read(*), Write(*), Bash(*), Glob(*) +description: Multi-phase clarification workflow generating confirmed guidance specification +argument-hint: "topic or challenge description for clarification" +allowed-tools: TodoWrite(*), Read(*), Write(*), AskUserQuestion(*), Bash(*), Glob(*) --- -# Topic Framework Generator Command +# Brainstorm Clarification Command -## Usage +## πŸ“– Overview + +### Purpose +**Multi-phase interactive clarification workflow** that collects user decisions through intelligent questioning, generating a **confirmed guidance specification** (declarative statements) rather than open-ended questions (interrogative sentences). + +### Core Philosophy Change +- ❌ **OLD**: Generate guidance-specification.md with open questions ("What are...?", "How should...?") +- βœ… **NEW**: Multi-step clarification β†’ Generate guidance-specification.md with confirmed decisions + +### User Intent Preservation +Topic description is stored in session metadata and serves as authoritative reference throughout workflow lifecycle. + +--- + +## 🎯 Usage + +### Basic Command ```bash -/workflow:brainstorm:artifacts "" [--roles "role1,role2,role3"] +/workflow:brainstorm:artifacts "" ``` -**Recommended Structured Format**: +### Recommended Structured Format ```bash -/workflow:brainstorm:artifacts "GOAL: [objective] SCOPE: [boundaries] CONTEXT: [background]" [--roles "..."] +/workflow:brainstorm:artifacts "GOAL: [objective] SCOPE: [boundaries] CONTEXT: [background]" ``` -## Purpose -**Generate dynamic topic-framework.md tailored to selected roles**. Creates role-specific discussion frameworks that address relevant perspectives. If no roles specified, generates comprehensive framework covering common analysis areas. - -**⚠️ User Intent Preservation**: Topic description is stored in session metadata and serves as authoritative reference throughout workflow lifecycle. - -## Role-Based Framework Generation - -**Dynamic Generation**: Framework content adapts based on selected roles -- **With roles**: Generate targeted discussion points for specified roles only -- **Without roles**: Generate comprehensive framework covering all common areas - -## Core Workflow - -### Topic Framework Generation Process - -**Phase 1: Session Management** ⚠️ FIRST STEP -- **Active session detection**: Check `.workflow/.active-*` markers -- **Session selection**: Prompt user if multiple active sessions found -- **Auto-creation**: Create `WFS-[topic-slug]` only if no active session exists -- **Framework check**: Check if `topic-framework.md` exists (update vs create mode) - -**Phase 2: Role Analysis** ⚠️ NEW -- **Parse roles parameter**: Extract roles from `--roles "role1,role2,role3"` if provided -- **Role validation**: Verify each role is valid (matches available role commands) -- **Store role list**: Save selected roles to session metadata for reference -- **Default behavior**: If no roles specified, use comprehensive coverage - -**Phase 3: Dynamic Topic Analysis** -- **Scope definition**: Define topic boundaries and objectives -- **Stakeholder identification**: Identify key users and stakeholders based on selected roles -- **Requirements gathering**: Extract requirements relevant to selected roles -- **Context collection**: Gather context appropriate for role perspectives - -**Phase 4: Role-Specific Framework Generation** -- **Discussion points creation**: Generate 3-5 discussion areas **tailored to selected roles** -- **Role-targeted questions**: Create questions specifically for chosen roles -- **Framework document**: Generate `topic-framework.md` with role-specific sections -- **Validation check**: Ensure framework addresses all selected role perspectives - -**Phase 5: Metadata Storage** -- **Save role assignment**: Store selected roles in session metadata -- **Framework versioning**: Track which roles framework addresses -- **Update tracking**: Maintain role evolution if framework updated - -## Implementation Standards - -### Discussion-Driven Analysis -**Interactive Approach**: Direct conversation and exploration without predefined role constraints - -**Process Flow**: -1. **Topic introduction**: Understanding scope and context -2. **Exploratory questioning**: Open-ended investigation -3. **Component identification**: Breaking down into manageable pieces -4. **Relationship analysis**: Understanding connections and dependencies -5. **Documentation generation**: Structured capture of insights - -**Key Areas of Investigation**: -- **Functional aspects**: What the topic needs to accomplish -- **Technical considerations**: Implementation constraints and requirements -- **User perspectives**: How different stakeholders are affected -- **Business implications**: Cost, timeline, and strategic considerations -- **Risk assessment**: Potential challenges and mitigation strategies - -### Document Generation Standards - -**Always Created**: -- **discussion-summary.md**: Main conversation points and key insights -- **component-analysis.md**: Detailed breakdown of topic components - -## Document Generation - -**Primary Output**: Single structured `topic-framework.md` document - -**Document Structure**: +### Example +```bash +/workflow:brainstorm:artifacts "GOAL: Build real-time collaboration platform SCOPE: Support 100 concurrent users CONTEXT: Existing monolithic architecture needs refactoring" ``` -.workflow/WFS-[topic]/.brainstorming/ -└── topic-framework.md # β˜… STRUCTURED FRAMEWORK DOCUMENT -``` - -**Note**: `workflow-session.json` is located at `.workflow/WFS-[topic]/workflow-session.json` (session root), not inside `.brainstorming/`. - -## Framework Template Structures - -### Dynamic Role-Based Framework - -Framework content adapts based on `--roles` parameter: - -#### Option 1: Specific Roles Provided -```markdown -# [Topic] - Discussion Framework - -## Topic Overview -- **Scope**: [Topic boundaries relevant to selected roles] -- **Objectives**: [Goals from perspective of selected roles] -- **Context**: [Background focusing on role-specific concerns] -- **Target Roles**: ui-designer, system-architect, subject-matter-expert - -## Role-Specific Discussion Points - -### For UI Designer -1. **User Interface Requirements** - - What interface components are needed? - - What user interactions must be supported? - - What visual design considerations apply? - -2. **User Experience Challenges** - - What are the key user journeys? - - What accessibility requirements exist? - - How to balance aesthetics with functionality? - -### For System Architect -1. **Architecture Decisions** - - What architectural patterns fit this solution? - - What scalability requirements exist? - - How does this integrate with existing systems? - -2. **Technical Implementation** - - What technology stack is appropriate? - - What are the performance requirements? - - What dependencies must be managed? - -### For Subject Matter Expert -1. **Domain Expertise & Standards** - - What industry standards and best practices apply? - - What regulatory compliance requirements exist? - - What domain-specific patterns should be followed? - -2. **Technical Quality & Risk** - - What technical debt considerations exist? - - What scalability and maintenance implications apply? - - What knowledge transfer and documentation is needed? - -## Cross-Role Integration Points -- How do UI decisions impact architecture? -- How does architecture constrain UI possibilities? -- What domain standards affect both UI and architecture? - -## Framework Usage -**For Role Agents**: Address your specific section + integration points -**Reference Format**: @../topic-framework.md in your analysis.md -**Update Process**: Use /workflow:brainstorm:artifacts to update --- -*Generated for roles: ui-designer, system-architect, subject-matter-expert* -*Last updated: [timestamp]* + +## πŸ”„ Multi-Phase Workflow + +### Workflow Diagram + +``` +Phase 1: Intent Classification + β”‚ (Understand project type and focus) + β”‚ β†’ 2-3 questions, 3 choices each + ↓ +Phase 2: Role Selection + β”‚ (Determine participating roles) + β”‚ β†’ Recommend 3-5 roles, multiSelect + ↓ +Phase 3: Role-Specific Questions + β”‚ (Collect professional domain decisions) + β”‚ β†’ 3-5 questions per role, 3 choices each + ↓ +Phase 4: Cross-Role Clarification + β”‚ (Ensure inter-role consistency) + β”‚ β†’ 1-2 questions per role from related role perspectives + ↓ +Phase 5: Generate Guidance Specification + β”‚ (Create confirmed guidance document) + └─→ guidance-specification.md (declarative statements) ``` - -#### Option 2: No Roles Specified (Comprehensive) -```markdown -# [Topic] - Discussion Framework - -## Topic Overview -- **Scope**: [Comprehensive topic boundaries] -- **Objectives**: [All-encompassing goals] -- **Context**: [Full background and constraints] -- **Stakeholders**: [All relevant parties] - -## Core Discussion Areas - -### 1. Requirements & Objectives -- What are the fundamental requirements? -- What are the critical success factors? -- What constraints must be considered? - -### 2. Technical & Architecture -- What are the technical challenges? -- What architectural decisions are needed? -- What integration points exist? - -### 3. User Experience & Design -- Who are the primary users? -- What are the key user journeys? -- What usability requirements exist? - -### 4. Security & Compliance -- What security requirements exist? -- What compliance considerations apply? -- What data protection is needed? - -### 5. Implementation & Operations -- What are the implementation risks? -- What resources are required? -- How will this be maintained? - -## Available Role Perspectives -Framework supports analysis from any of these roles: -- **Technical**: system-architect, data-architect, subject-matter-expert -- **Product & Design**: ui-designer, ux-expert, product-manager, product-owner -- **Agile & Quality**: scrum-master, test-strategist --- -*Comprehensive framework - adaptable to any role* -*Last updated: [timestamp]* + +## πŸ“‹ Phase 1: Intent Classification + +### Purpose +Understand project type and focus areas to customize subsequent questions. + +### Implementation +Use **AskUserQuestion** tool to intelligently generate 2-3 classification questions based on user's topic description. + +### Question Types (Intelligently Generated) +1. **Project Type**: New feature / Optimization / Refactoring +2. **Value Focus**: UX-driven / Technical capability / Business value +3. **System Scale**: Small (MVP) / Medium / Large (Enterprise) + +### Output +- **intent_context**: Classification results +- Stored in session metadata for Phase 2-4 customization + +### Example Flow +```javascript +AskUserQuestion({ + questions: [{ + question: "What is the project type?", + header: "Project Type", + multiSelect: false, + options: [ + {label: "New Feature Development", description: "Build new features or products from scratch"}, + {label: "System Optimization", description: "Improve performance, experience, or architecture"}, + {label: "Architecture Migration", description: "Technology stack upgrade or system migration"} + ] + }] + // ... Generate 2-3 classification questions similarly +}) ``` -## Role-Specific Content Generation +--- -### Available Roles and Their Focus Areas +## πŸ‘₯ Phase 2: Role Selection + +### Purpose +Determine which roles should participate in analysis. + +### Implementation Steps + +**1. Analyze Topic + Phase 1 Results** +Intelligently recommend 3-5 relevant roles based on keywords. + +**2. Role Recommendation Logic** +- **Technical keywords** (architecture, system, performance, database) + β†’ system-architect, data-architect, subject-matter-expert +- **API/Backend keywords** (api, endpoint, rest, graphql, service) + β†’ api-designer, system-architect, data-architect +- **UX keywords** (user, ui, ux, design, experience) + β†’ ui-designer, ux-expert, product-manager +- **Business keywords** (business, process, workflow, cost) + β†’ product-manager, product-owner +- **Agile keywords** (sprint, scrum, team, delivery) + β†’ scrum-master, product-owner + +**3. Present to User** +Use AskUserQuestion with multiSelect for role selection. + +### Available Roles + +**Technical**: `system-architect`, `data-architect`, `subject-matter-expert`, `api-designer` +**Product & Design**: `ui-designer`, `ux-expert`, `product-manager`, `product-owner` +**Agile & Quality**: `scrum-master`, `test-strategist` + +**Detailed role descriptions**: See "Reference Information > Available Roles Reference" + +### Output +- **selected_roles**: List of user-selected roles +- Stored in session metadata + +--- + +## πŸŽ“ Phase 3: Role-Specific Professional Questions + +### Purpose +Collect decisions for each role's professional domain. + +### Implementation +For each selected role, **intelligently generate 3-5 core questions** based on: +- Role's professional expertise area +- User's topic description +- Phase 1 intent context + +### Question Generation Rules +1. **Exactly 3 options** per question (MECE principle) +2. **Concrete and actionable** options +3. **Avoid vague options** like "depends on situation" +4. **Use AskUserQuestion** with multiSelect: false + +### Role Question Focus Areas + +**system-architect**: +- Architecture style (microservices/monolith/hybrid) +- Data consistency (strong/eventual/hybrid) +- Performance priority (latency/throughput/resource) +- Deployment model (cloud-native/VM/serverless) + +**ui-designer**: +- Visual style (minimalist/rich/professional) +- Component complexity (simple/moderate/complex) +- Design system maturity (full/basic/lightweight) +- Responsive strategy (mobile-first/desktop-first/adaptive) + +**ux-expert**: +- User persona (novice/intermediate/expert) +- Interaction complexity (simple/rich/professional) +- Accessibility level (WCAG AA/AAA/basic) +- Testing strategy (comprehensive/targeted/minimal) + +**product-manager**: +- MVP scope (minimal core/core+hooks/full feature set) +- Timeline expectation (fast iteration/standard/robust) +- Priority strategy (user value/technical debt/innovation) +- Success metrics (usage/satisfaction/revenue) + +**data-architect**: +- Storage technology (relational/NoSQL/polyglot) +- Data model complexity (simple/moderate/complex domain) +- Analytics needs (basic/moderate/advanced) +- Compliance requirements (GDPR/HIPAA/none) + +**Other roles** (api-designer, product-owner, scrum-master, subject-matter-expert, test-strategist): +Similar 3-5 questions tailored to their domains. + +### Example: System Architect Questions + +For topic "Build real-time collaboration platform": + +```javascript +AskUserQuestion({ + questions: [ + { + question: "System architecture style preference?", + header: "Architecture Style", + multiSelect: false, + options: [ + {label: "Microservices", description: "Independent service deployment, suitable for large teams"}, + {label: "Modular Monolith", description: "Single deployment unit, suitable for small to medium teams"}, + {label: "Hybrid Architecture", description: "Core monolith + partial microservices"} + ] + } + // ... Generate 3-5 questions similarly + ] +}) +``` + +**Other roles**: Generate similarly based on professional domains (see "Role Question Focus Areas") + +### Output +- **role_decisions**: Map of {role: [answers]} for all selected roles +- Stored in session metadata + +--- + +## πŸ”— Phase 4: Cross-Role Clarification Questions + +### Purpose +Ensure consistency across roles and identify potential conflicts. + +### Implementation +For each selected role, **intelligently generate 1-2 cross-role questions** from perspectives of 2-3 related roles. + +### Cross-Role Relationship Matrix + +| Current Role | Question from Role Perspectives | Question Topics | +|---------|------------------|---------| +| system-architect | ui-designer, product-manager, data-architect | Frontend stack, MVP scope, storage choice | +| ui-designer | ux-expert, system-architect, product-owner | Design system, technical constraints, feature priority | +| product-manager | system-architect, ux-expert, scrum-master | Technical feasibility, user pain points, delivery rhythm | +| ux-expert | ui-designer, product-manager, subject-matter-expert | Visual style, user goals, industry norms | +| data-architect | system-architect, subject-matter-expert, api-designer | Integration patterns, compliance requirements, API design | + +### Example: Cross-Role Question + +System-architect asking from ui-designer perspective: + +```javascript +AskUserQuestion({ + questions: [{ + question: "Frontend technology stack choice? (Impacts frontend-backend separation strategy)", + header: "Frontend Stack", + multiSelect: false, + options: [ + {label: "Modern Framework (React/Vue)", description: "Requires dedicated frontend team"}, + {label: "Server-Side Rendering (Next.js)", description: "SEO-friendly"}, + {label: "Lightweight (jQuery)", description: "Backend-driven"} + ] + }] + // ... 1-2 cross-role questions per role +}) +``` + +### Output +- **cross_role_decisions**: Map of {role: {from_role: [answers]}} +- Stored in session metadata + +--- + +## πŸ“„ Phase 5: Generate Guidance Specification + +### Purpose +Based on all user choices, generate a confirmed guidance document with **declarative statements**, not questions. + +### Implementation +1. **Consolidate all decisions**: + - intent_context (Phase 1) + - selected_roles (Phase 2) + - role_decisions (Phase 3) + - cross_role_decisions (Phase 4) + +2. **Generate guidance-specification.md** with confirmed decisions + +### Output Document Structure + +See **"Output Specification"** section below for complete template. + +### Output Location +``` +.workflow/WFS-[topic]/.brainstorming/guidance-specification.md +``` + +**Detailed file structure**: See "Reference Information > File Structure" + +--- + +## πŸ”§ Implementation Details + +### Session Management ⚠️ CRITICAL + +**⚑ First Step**: Check `.workflow/.active-*` markers + +**Logic**: +- Multiple active sessions β†’ Prompt user to select +- Single active session β†’ Use that session +- No active session β†’ Create new `WFS-[topic-slug]` + +**Session Data Storage**: +- Decision data: `workflow-session.json` +- Output file: `.brainstorming/guidance-specification.md` + +### Implementation Workflow + +**Execution Flow**: +1. **Session Management**: Detect or create session +2. **Phase 1**: Intent classification (2-3 questions) +3. **Phase 2**: Role selection (recommendations + multiSelect) +4. **Phase 3**: Role professional questions (3-5 questions per role) +5. **Phase 4**: Cross-role clarification (1-2 questions per role) +6. **Phase 5**: Generate guidance-specification.md +7. **Update Metadata**: Save all decisions to session + +**TodoWrite tracking**: Update progress at each Phase + +**Decision storage**: All user choices saved to `workflow-session.json` + +--- + +## πŸ€– Intelligent Question Generation + +### Core Principle +All questions are **intelligently generated by Claude** based on: +- Role professional domain +- User's topic description +- Previous decision context +- Phase 1 intent classification + +**No Template Library Required**: Questions are dynamically created to fit specific task context. + +### Question Generation Guidelines + +**For Phase 3 (Role Questions)**: +``` +INPUT: role + topic + intent_context +OUTPUT: 3-5 questions, each with 3 MECE options + +Example: +- Role: system-architect +- Topic: "Build real-time collaboration platform" +- Intent: {type: "new_feature", scale: "medium", focus: "technical"} + +Generated Questions: +1. Architecture style? [Microservices/Modular Monolith/Hybrid] +2. Real-time communication tech? [WebSocket/SSE/Polling] +3. Data consistency? [Strong/Eventual/Hybrid] +4. Deployment model? [Cloud-native/Traditional VM/Serverless] +``` + +**For Phase 4 (Cross-Role Questions)**: +``` +INPUT: current_role + related_role + role_decisions + topic +OUTPUT: 1-2 questions from related_role perspective + +Example: +- Current: system-architect +- Related: ui-designer +- Topic: "Build real-time collaboration platform" +- Context: ui-designer chose "Modern Framework (React)" + +Generated Question: +"Frontend technology stack choice? (Impacts frontend-backend separation strategy)" +[Modern Framework/Server-Side Rendering/Lightweight] +``` + +--- + +## βœ… Validation & Quality Assurance + +### Output Validation + +**Guidance Specification Must Contain**: +- βœ… **All declarative statements**: No question marks in decision sections +- βœ… **Clear decisions**: Every decision point has explicit choice +- βœ… **Decision traceability**: Can trace back to user answers +- βœ… **Cross-role consistency**: Conflicts resolved or noted +- βœ… **Actionability**: Next steps are clear + +### Validation Checklist + +The generated guidance-specification.md must pass these checks: + +βœ… **No interrogative sentences**: Decision sections should not end with question marks +βœ… **Clear decisions**: Every decision point has explicit choice (not "TBD"/"Pending") +βœ… **Traceable**: Every decision can be traced back to user answers +βœ… **Cross-role consistency**: Cross-role decision count β‰₯ number of selected roles +βœ… **Actionable**: "Next steps" are clear and specific + +**Automatic validation**: Execute checks after generation, prompt if issues found + +--- + +## πŸ“ Output Specification + +### Document Structure Overview + +**Output file**: `.workflow/WFS-[topic]/.brainstorming/guidance-specification.md` + +### Template Structure + +```markdown +# [Project] - Confirmed Guidance Specification + +**Metadata**: [timestamp, type, focus, roles] + +## 1. Project Positioning & Goals +**CONFIRMED**: [objectives, success criteria] + +## 2-5. Role-Specific Decisions +Each participating role has one section containing: +- **SELECTED**: [confirmed choices] +- **Rationale**: [reasoning] +- **Constraints/Impact**: [implications] +- **Cross-Role Confirmed**: [dependencies] + +## 6. Cross-Role Integration +**CONFIRMED**: [API style, data format, auth, collaboration model] + +## 7. Risks & Constraints +**Identified**: [risks with mitigation, constraints] + +## 8. Next Steps +**Immediate Actions**: [action items] +**Role Assignments**: [tasks per role] + +## Appendix: Decision Tracking +**Key Decisions**: [table] +**Open Items**: [list] +``` + +**Core principles**: +- All decisions use declarative statements (CONFIRMED/SELECTED) +- Every decision is traceable to user answers +- Cross-role decisions ensure consistency +- Next steps are clear and specific + +--- + +## πŸ”„ Update Mechanism + +### Existing Guidance Update + +```bash +IF guidance-specification.md EXISTS: + SHOW current guidance summary to user + ASK: "Guidance exists. Do you want to:" + OPTIONS: + 1. "Regenerate completely" β†’ Start full clarification flow + 2. "Update specific sections" β†’ Target specific roles/decisions + 3. "Cancel" β†’ Exit without changes +ELSE: + CREATE new guidance through full clarification +``` + +**Update Strategies**: +1. **Complete Regeneration**: Backup existing β†’ Full clarification flow +2. **Targeted Update**: Update specific role sections or cross-role decisions +3. **Incremental Addition**: Add new roles or decision areas + +--- + +## ⚠️ Error Handling + +| Error Type | Handling Strategy | +|-----------|-------------------| +| Session creation failed | Error details + retry option + check permissions | +| AskUserQuestion timeout | Save progress + allow resumption + provide instructions | +| Incomplete clarification | Mark open items + suggest follow-up clarification | +| Conflicting decisions | Highlight conflicts + show disagreeing roles + suggest resolution | + +--- + +## πŸ”— Integration with Downstream Workflow + +### Core Principles & Governance Rules + +**GOVERNANCE_RULES** for guidance-specification.md output: + +βœ… **Declarative Statements Only** +- All decisions MUST use CONFIRMED/SELECTED format +- NO interrogative sentences (no "?" in decision sections) +- NO open questions or TBD items in confirmed decisions + +βœ… **Decision Traceability** +- Every decision MUST trace back to specific user answer +- Cross-reference to Phase 1-4 clarification responses +- Document rationale for each confirmed choice + +βœ… **Cross-Role Consistency** +- Cross-role decisions count β‰₯ number of selected roles +- Conflicts MUST be resolved or explicitly documented +- Dependencies between roles clearly stated + +βœ… **Actionability Requirements** +- Next steps MUST be concrete and specific +- Role assignments clearly defined +- Success criteria measurable and verifiable + +βœ… **Session Integrity** +- All decisions stored in `workflow-session.json` +- Topic description preserved as authoritative reference +- Session lifecycle properly managed (active markers, metadata) + +**CRITICAL**: Generated guidance is the **single source of truth** for all downstream workflow phases. Any ambiguity violates governance rules and MUST be resolved before proceeding. + +--- + +### Next Steps After Guidance Generation + +**Standard Workflow**: +```bash +/workflow:concept-clarify --session WFS-{session-id} # Optional: Further clarification +/workflow:plan --session WFS-{session-id} # Generate IMPL_PLAN.md and tasks +/workflow:action-plan-verify --session WFS-{session-id} # Optional: Verify plan quality +/workflow:execute --session WFS-{session-id} # Start implementation +``` + +--- + +## πŸ“š Reference Information + +### File Structure +``` +.workflow/WFS-[topic]/ +β”œβ”€β”€ workflow-session.json # Session metadata with all decisions +└── .brainstorming/ + β”œβ”€β”€ guidance-specification.md # β˜… PRIMARY OUTPUT (declarative statements) + └── [role]/ + └── analysis.md # Role deepening analysis (generated later) +``` + +### Available Roles Reference **Technical Roles**: - `system-architect`: Architecture patterns, scalability, technology stack, integration -- `data-architect`: Data modeling, processing workflows, analytics, storage -- `subject-matter-expert`: Domain expertise, industry standards, compliance, best practices +- `data-architect`: Data modeling, storage workflows, analytics, compliance +- `subject-matter-expert`: Domain expertise, industry standards, best practices +- `api-designer`: API design, versioning, contracts, authentication **Product & Design Roles**: -- `ui-designer`: User interface, visual design, interaction patterns, accessibility -- `ux-expert`: User experience optimization, usability testing, interaction design, design systems +- `ui-designer`: User interface, visual design, components, accessibility +- `ux-expert`: User experience, usability testing, interaction design, design systems - `product-manager`: Business value, feature prioritization, market positioning, roadmap - `product-owner`: Backlog management, user stories, acceptance criteria, stakeholder alignment @@ -231,143 +558,13 @@ Framework supports analysis from any of these roles: - `scrum-master`: Sprint planning, team dynamics, process optimization, delivery management - `test-strategist`: Testing strategies, quality assurance, test automation, validation approaches -### Dynamic Discussion Point Generation +### Architecture Reference +- **Workflow Architecture**: @~/.claude/workflows/workflow-architecture.md +- **Clarification Plan**: @~/.claude/workflows/brainstorm-clarification-plan.md -**For each selected role, generate**: -1. **2-3 core discussion areas** specific to that role's perspective -2. **3-5 targeted questions** per discussion area -3. **Cross-role integration points** showing how roles interact - -**Example mapping**: -```javascript -// If roles = ["ui-designer", "system-architect"] -Generate: -- UI Designer section: UI Requirements, UX Challenges -- System Architect section: Architecture Decisions, Technical Implementation -- Integration Points: UI↔Architecture dependencies -``` - -### Framework Generation Examples - -#### Example 1: Architecture-Heavy Topic -```bash -/workflow:brainstorm:artifacts "Design scalable microservices platform" --roles "system-architect,data-architect,subject-matter-expert" -``` -**Generated framework focuses on**: -- Service architecture and communication patterns -- Data flow and storage strategies -- Domain standards and best practices - -#### Example 2: User-Focused Topic -```bash -/workflow:brainstorm:artifacts "Improve user onboarding experience" --roles "ui-designer,ux-expert,product-manager" -``` -**Generated framework focuses on**: -- Onboarding flow and UI components -- User experience optimization and usability -- Business value and success metrics - -#### Example 3: Agile Delivery Topic -```bash -/workflow:brainstorm:artifacts "Optimize sprint delivery process" --roles "scrum-master,product-owner,test-strategist" -``` -**Generated framework focuses on**: -- Sprint planning and team collaboration -- Backlog management and prioritization -- Quality assurance and testing strategies - -#### Example 4: Comprehensive Analysis -```bash -/workflow:brainstorm:artifacts "Build real-time collaboration feature" -``` -**Generated framework covers** all aspects (no roles specified) - -## Session Management ⚠️ CRITICAL -- **⚑ FIRST ACTION**: Check for all `.workflow/.active-*` markers before processing -- **Multiple sessions support**: Different Claude instances can have different active sessions -- **User selection**: If multiple active sessions found, prompt user to select which one to work with -- **Auto-session creation**: `WFS-[topic-slug]` only if no active session exists -- **Session continuity**: MUST use selected active session for all processing -- **Context preservation**: All discussion and analysis stored in session directory -- **Session isolation**: Each session maintains independent state - -## Discussion Areas - -### Core Investigation Topics -- **Purpose & Goals**: What are we trying to achieve? -- **Scope & Boundaries**: What's included and excluded? -- **Success Criteria**: How do we measure success? -- **Constraints**: What limitations exist? -- **Stakeholders**: Who is affected or involved? - -### Technical Considerations -- **Requirements**: What must the solution provide? -- **Dependencies**: What does it rely on? -- **Integration**: How does it connect to existing systems? -- **Performance**: What are the speed/scale requirements? -- **Security**: What protection is needed? - -### Implementation Factors -- **Timeline**: When is it needed? -- **Resources**: What people/budget/tools are available? -- **Risks**: What could go wrong? -- **Alternatives**: What other approaches exist? -- **Migration**: How do we transition from current state? - -## Update Mechanism ⚠️ SMART UPDATES - -### Framework Update Logic -```bash -# Check existing framework -IF topic-framework.md EXISTS: - SHOW current framework to user - ASK: "Framework exists. Do you want to:" - OPTIONS: - 1. "Replace completely" β†’ Generate new framework - 2. "Add discussion points" β†’ Append to existing - 3. "Refine existing points" β†’ Interactive editing - 4. "Cancel" β†’ Exit without changes -ELSE: - CREATE new framework -``` - -### Update Strategies - -**1. Complete Replacement** -- Backup existing framework as `topic-framework-[timestamp].md.backup` -- Generate completely new framework -- Preserve role-specific analysis points from previous version - -**2. Incremental Addition** -- Load existing framework -- Identify new discussion areas through user interaction -- Add new sections while preserving existing structure -- Update framework usage instructions - -**3. Refinement Mode** -- Interactive editing of existing discussion points -- Allow modification of scope, objectives, and questions -- Preserve framework structure and role assignments -- Update timestamp and version info - -### Version Control -- **Backup Creation**: Always backup before major changes -- **Change Tracking**: Include change summary in framework footer -- **Rollback Support**: Keep previous version accessible - -## Error Handling -- **Session creation failure**: Provide clear error message and retry option -- **Discussion stalling**: Offer structured prompts to continue exploration -- **Documentation issues**: Graceful handling of file creation problems -- **Missing context**: Prompt for additional information when needed - -## Reference Information - -### File Structure Reference -**Architecture**: @~/.claude/workflows/workflow-architecture.md -**Session Management**: Standard workflow session protocols - -### Integration Points -- **Compatible with**: Other brainstorming commands in the same session -- **Builds foundation for**: More detailed planning and implementation phases -- **Outputs used by**: `/workflow:brainstorm:synthesis` command for cross-analysis integration +### Related Commands +- `/workflow:brainstorm:auto-parallel` - Parallel role analysis execution +- `/workflow:brainstorm:synthesis` - Synthesize role analyses +- `/workflow:brainstorm:[role]` - Individual role analysis commands +- `/workflow:concept-clarify` - Further concept clarification +- `/workflow:plan` - Generate implementation plan diff --git a/.claude/commands/workflow/brainstorm/auto-parallel.md b/.claude/commands/workflow/brainstorm/auto-parallel.md index fb72a8e1..27f43f35 100644 --- a/.claude/commands/workflow/brainstorm/auto-parallel.md +++ b/.claude/commands/workflow/brainstorm/auto-parallel.md @@ -173,7 +173,7 @@ Task(subagent_type="conceptual-planning-agent", 1. **load_topic_framework** - Action: Load structured topic discussion framework - - Command: Read(.workflow/WFS-{topic}/.brainstorming/topic-framework.md) + - Command: Read(.workflow/WFS-{topic}/.brainstorming/guidance-specification.md) - Output: topic_framework - Fallback: Continue with session metadata if file not found @@ -189,7 +189,7 @@ Task(subagent_type="conceptual-planning-agent", ### Implementation Context **User Intent Authority**: Original user prompt from session_metadata.project is PRIMARY reference -**Topic Framework**: Use loaded topic-framework.md for structured analysis +**Topic Framework**: Use loaded guidance-specification.md for structured analysis **Role Focus**: {role-name} domain expertise and perspective aligned with user intent **Analysis Type**: Address framework discussion points from role perspective, filtered by user objectives **Template Framework**: Combine role template with topic framework structure @@ -208,13 +208,13 @@ Task(subagent_type="conceptual-planning-agent", ## Completion Requirements 1. Execute all flow control steps in sequence (load topic framework, role template, session metadata with user intent) 2. User Intent Alignment: Validate analysis aligns with original user objectives from session_metadata -3. Address Topic Framework: Respond to all discussion points in topic-framework.md from role perspective +3. Address Topic Framework: Respond to all discussion points in guidance-specification.md from role perspective 4. Filter by User Goals: Prioritize insights directly relevant to user's stated objectives 5. Apply role template guidelines within topic framework structure 6. Generate structured role analysis addressing framework points aligned with user intent 7. Create single comprehensive deliverable in OUTPUT_LOCATION: - analysis.md (structured analysis addressing all topic framework points with role-specific insights filtered by user goals) -8. Include framework reference: @../topic-framework.md in analysis.md +8. Include framework reference: @../guidance-specification.md in analysis.md 9. Update workflow-session.json with completion status""", description="Execute {role-name} brainstorming analysis") ``` diff --git a/.claude/commands/workflow/brainstorm/data-architect.md b/.claude/commands/workflow/brainstorm/data-architect.md index d049c4aa..6c164796 100644 --- a/.claude/commands/workflow/brainstorm/data-architect.md +++ b/.claude/commands/workflow/brainstorm/data-architect.md @@ -1,6 +1,6 @@ --- name: data-architect -description: Generate or update data-architect/analysis.md addressing topic-framework discussion points +description: Generate or update data-architect/analysis.md addressing guidance-specification discussion points argument-hint: "optional topic - uses existing framework if available" allowed-tools: Task(conceptual-planning-agent), TodoWrite(*), Read(*), Write(*) --- @@ -8,10 +8,10 @@ allowed-tools: Task(conceptual-planning-agent), TodoWrite(*), Read(*), Write(*) ## πŸ“Š **Data Architect Analysis Generator** ### Purpose -**Specialized command for generating data-architect/analysis.md** that addresses topic-framework.md discussion points from data architecture perspective. Creates or updates role-specific analysis with framework references. +**Specialized command for generating data-architect/analysis.md** that addresses guidance-specification.md discussion points from data architecture perspective. Creates or updates role-specific analysis with framework references. ### Core Function -- **Framework-based Analysis**: Address each discussion point in topic-framework.md +- **Framework-based Analysis**: Address each discussion point in guidance-specification.md - **Data Architecture Focus**: Data models, pipelines, governance, and analytics perspective - **Update Mechanism**: Create new or update existing analysis.md - **Agent Delegation**: Use conceptual-planning-agent for analysis generation @@ -52,7 +52,7 @@ IF active_session EXISTS: session_id = get_active_session() brainstorm_dir = .workflow/WFS-{session}/.brainstorming/ - CHECK: brainstorm_dir/topic-framework.md + CHECK: brainstorm_dir/guidance-specification.md IF EXISTS: framework_mode = true load_framework = true @@ -93,7 +93,7 @@ ANALYSIS_MODE: {framework_mode ? "framework_based" : "standalone"} ## Flow Control Steps 1. **load_topic_framework** - Action: Load structured topic discussion framework - - Command: Read(.workflow/WFS-{session}/.brainstorming/topic-framework.md) + - Command: Read(.workflow/WFS-{session}/.brainstorming/guidance-specification.md) - Output: topic_framework_content 2. **load_role_template** @@ -107,17 +107,17 @@ ANALYSIS_MODE: {framework_mode ? "framework_based" : "standalone"} - Output: session_context ## Analysis Requirements -**Framework Reference**: Address all discussion points in topic-framework.md from data architecture perspective +**Framework Reference**: Address all discussion points in guidance-specification.md from data architecture perspective **Role Focus**: Data models, pipelines, governance, analytics platforms **Structured Approach**: Create analysis.md addressing framework discussion points **Template Integration**: Apply role template guidelines within framework structure ## Expected Deliverables 1. **analysis.md**: Comprehensive data architecture analysis addressing all framework discussion points -2. **Framework Reference**: Include @../topic-framework.md reference in analysis +2. **Framework Reference**: Include @../guidance-specification.md reference in analysis ## Completion Criteria -- Address each discussion point from topic-framework.md with data architecture expertise +- Address each discussion point from guidance-specification.md with data architecture expertise - Provide data model designs, pipeline architectures, and governance strategies - Include scalability, performance, and quality considerations - Reference framework document using @ notation for integration @@ -136,7 +136,7 @@ TodoWrite({ activeForm: "Detecting session and framework" }, { - content: "Load topic-framework.md and session metadata for context", + content: "Load guidance-specification.md and session metadata for context", status: "pending", activeForm: "Loading framework and session context" }, @@ -164,7 +164,7 @@ TodoWrite({ ### Framework-Based Analysis ``` .workflow/WFS-{session}/.brainstorming/data-architect/ -└── analysis.md # Structured analysis addressing topic-framework.md discussion points +└── analysis.md # Structured analysis addressing guidance-specification.md discussion points ``` ### Analysis Document Structure @@ -172,11 +172,11 @@ TodoWrite({ # Data Architect Analysis: [Topic from Framework] ## Framework Reference -**Topic Framework**: @../topic-framework.md +**Topic Framework**: @../guidance-specification.md **Role Focus**: Data Architecture perspective ## Discussion Points Analysis -[Address each point from topic-framework.md with data architecture expertise] +[Address each point from guidance-specification.md with data architecture expertise] ### Core Requirements (from framework) [Data architecture perspective on requirements] @@ -209,12 +209,12 @@ TodoWrite({ "status": "completed", "framework_addressed": true, "output_location": ".workflow/WFS-{session}/.brainstorming/data-architect/analysis.md", - "framework_reference": "@../topic-framework.md" + "framework_reference": "@../guidance-specification.md" } } ``` ### Integration Points -- **Framework Reference**: @../topic-framework.md for structured discussion points +- **Framework Reference**: @../guidance-specification.md for structured discussion points - **Cross-Role Synthesis**: Data architecture insights available for synthesis-report.md integration - **Agent Autonomy**: Independent execution with framework guidance diff --git a/.claude/commands/workflow/brainstorm/product-manager.md b/.claude/commands/workflow/brainstorm/product-manager.md index 8ed60789..770b7136 100644 --- a/.claude/commands/workflow/brainstorm/product-manager.md +++ b/.claude/commands/workflow/brainstorm/product-manager.md @@ -1,6 +1,6 @@ --- name: product-manager -description: Generate or update product-manager/analysis.md addressing topic-framework discussion points +description: Generate or update product-manager/analysis.md addressing guidance-specification discussion points argument-hint: "optional topic - uses existing framework if available" allowed-tools: Task(conceptual-planning-agent), TodoWrite(*), Read(*), Write(*) --- @@ -8,10 +8,10 @@ allowed-tools: Task(conceptual-planning-agent), TodoWrite(*), Read(*), Write(*) ## 🎯 **Product Manager Analysis Generator** ### Purpose -**Specialized command for generating product-manager/analysis.md** that addresses topic-framework.md discussion points from product strategy perspective. Creates or updates role-specific analysis with framework references. +**Specialized command for generating product-manager/analysis.md** that addresses guidance-specification.md discussion points from product strategy perspective. Creates or updates role-specific analysis with framework references. ### Core Function -- **Framework-based Analysis**: Address each discussion point in topic-framework.md +- **Framework-based Analysis**: Address each discussion point in guidance-specification.md - **Product Strategy Focus**: User needs, business value, and market positioning - **Update Mechanism**: Create new or update existing analysis.md - **Agent Delegation**: Use conceptual-planning-agent for analysis generation @@ -32,7 +32,7 @@ IF active_session EXISTS: session_id = get_active_session() brainstorm_dir = .workflow/WFS-{session}/.brainstorming/ - CHECK: brainstorm_dir/topic-framework.md + CHECK: brainstorm_dir/guidance-specification.md IF EXISTS: framework_mode = true load_framework = true @@ -73,7 +73,7 @@ ANALYSIS_MODE: {framework_mode ? "framework_based" : "standalone"} ## Flow Control Steps 1. **load_topic_framework** - Action: Load structured topic discussion framework - - Command: Read(.workflow/WFS-{session}/.brainstorming/topic-framework.md) + - Command: Read(.workflow/WFS-{session}/.brainstorming/guidance-specification.md) - Output: topic_framework_content 2. **load_role_template** @@ -87,17 +87,17 @@ ANALYSIS_MODE: {framework_mode ? "framework_based" : "standalone"} - Output: session_context ## Analysis Requirements -**Framework Reference**: Address all discussion points in topic-framework.md from product strategy perspective +**Framework Reference**: Address all discussion points in guidance-specification.md from product strategy perspective **Role Focus**: User value, business impact, market positioning, product strategy **Structured Approach**: Create analysis.md addressing framework discussion points **Template Integration**: Apply role template guidelines within framework structure ## Expected Deliverables 1. **analysis.md**: Comprehensive product strategy analysis addressing all framework discussion points -2. **Framework Reference**: Include @../topic-framework.md reference in analysis +2. **Framework Reference**: Include @../guidance-specification.md reference in analysis ## Completion Criteria -- Address each discussion point from topic-framework.md with product management expertise +- Address each discussion point from guidance-specification.md with product management expertise - Provide actionable business strategies and user value propositions - Include market analysis and competitive positioning insights - Reference framework document using @ notation for integration @@ -116,7 +116,7 @@ TodoWrite({ activeForm: "Detecting session and framework" }, { - content: "Load topic-framework.md and session metadata for context", + content: "Load guidance-specification.md and session metadata for context", status: "pending", activeForm: "Loading framework and session context" }, @@ -144,7 +144,7 @@ TodoWrite({ ### Framework-Based Analysis ``` .workflow/WFS-{session}/.brainstorming/product-manager/ -└── analysis.md # Structured analysis addressing topic-framework.md discussion points +└── analysis.md # Structured analysis addressing guidance-specification.md discussion points ``` ### Analysis Document Structure @@ -152,11 +152,11 @@ TodoWrite({ # Product Manager Analysis: [Topic from Framework] ## Framework Reference -**Topic Framework**: @../topic-framework.md +**Topic Framework**: @../guidance-specification.md **Role Focus**: Product Strategy perspective ## Discussion Points Analysis -[Address each point from topic-framework.md with product management expertise] +[Address each point from guidance-specification.md with product management expertise] ### Core Requirements (from framework) [Product strategy perspective on user needs and requirements] @@ -189,12 +189,12 @@ TodoWrite({ "status": "completed", "framework_addressed": true, "output_location": ".workflow/WFS-{session}/.brainstorming/product-manager/analysis.md", - "framework_reference": "@../topic-framework.md" + "framework_reference": "@../guidance-specification.md" } } ``` ### Integration Points -- **Framework Reference**: @../topic-framework.md for structured discussion points +- **Framework Reference**: @../guidance-specification.md for structured discussion points - **Cross-Role Synthesis**: Product strategy insights available for synthesis-report.md integration - **Agent Autonomy**: Independent execution with framework guidance diff --git a/.claude/commands/workflow/brainstorm/product-owner.md b/.claude/commands/workflow/brainstorm/product-owner.md index 3b306513..57d18809 100644 --- a/.claude/commands/workflow/brainstorm/product-owner.md +++ b/.claude/commands/workflow/brainstorm/product-owner.md @@ -1,6 +1,6 @@ --- name: product-owner -description: Generate or update product-owner/analysis.md addressing topic-framework discussion points +description: Generate or update product-owner/analysis.md addressing guidance-specification discussion points argument-hint: "optional topic - uses existing framework if available" allowed-tools: Task(conceptual-planning-agent), TodoWrite(*), Read(*), Write(*) --- @@ -8,10 +8,10 @@ allowed-tools: Task(conceptual-planning-agent), TodoWrite(*), Read(*), Write(*) ## 🎯 **Product Owner Analysis Generator** ### Purpose -**Specialized command for generating product-owner/analysis.md** that addresses topic-framework.md discussion points from product backlog and feature prioritization perspective. Creates or updates role-specific analysis with framework references. +**Specialized command for generating product-owner/analysis.md** that addresses guidance-specification.md discussion points from product backlog and feature prioritization perspective. Creates or updates role-specific analysis with framework references. ### Core Function -- **Framework-based Analysis**: Address each discussion point in topic-framework.md +- **Framework-based Analysis**: Address each discussion point in guidance-specification.md - **Product Backlog Focus**: Feature prioritization, user stories, and acceptance criteria - **Update Mechanism**: Create new or update existing analysis.md - **Agent Delegation**: Use conceptual-planning-agent for analysis generation @@ -32,7 +32,7 @@ IF active_session EXISTS: session_id = get_active_session() brainstorm_dir = .workflow/WFS-{session}/.brainstorming/ - CHECK: brainstorm_dir/topic-framework.md + CHECK: brainstorm_dir/guidance-specification.md IF EXISTS: framework_mode = true load_framework = true @@ -73,7 +73,7 @@ ANALYSIS_MODE: {framework_mode ? "framework_based" : "standalone"} ## Flow Control Steps 1. **load_topic_framework** - Action: Load structured topic discussion framework - - Command: Read(.workflow/WFS-{session}/.brainstorming/topic-framework.md) + - Command: Read(.workflow/WFS-{session}/.brainstorming/guidance-specification.md) - Output: topic_framework_content 2. **load_role_template** @@ -87,17 +87,17 @@ ANALYSIS_MODE: {framework_mode ? "framework_based" : "standalone"} - Output: session_context ## Analysis Requirements -**Framework Reference**: Address all discussion points in topic-framework.md from product backlog and feature prioritization perspective +**Framework Reference**: Address all discussion points in guidance-specification.md from product backlog and feature prioritization perspective **Role Focus**: Backlog management, stakeholder alignment, feature prioritization, acceptance criteria **Structured Approach**: Create analysis.md addressing framework discussion points **Template Integration**: Apply role template guidelines within framework structure ## Expected Deliverables 1. **analysis.md**: Comprehensive product ownership analysis addressing all framework discussion points -2. **Framework Reference**: Include @../topic-framework.md reference in analysis +2. **Framework Reference**: Include @../guidance-specification.md reference in analysis ## Completion Criteria -- Address each discussion point from topic-framework.md with product ownership expertise +- Address each discussion point from guidance-specification.md with product ownership expertise - Provide actionable user stories and acceptance criteria definitions - Include feature prioritization and stakeholder alignment strategies - Reference framework document using @ notation for integration @@ -116,7 +116,7 @@ TodoWrite({ activeForm: "Detecting session and framework" }, { - content: "Load topic-framework.md and session metadata for context", + content: "Load guidance-specification.md and session metadata for context", status: "pending", activeForm: "Loading framework and session context" }, @@ -144,7 +144,7 @@ TodoWrite({ ### Framework-Based Analysis ``` .workflow/WFS-{session}/.brainstorming/product-owner/ -└── analysis.md # Structured analysis addressing topic-framework.md discussion points +└── analysis.md # Structured analysis addressing guidance-specification.md discussion points ``` ### Analysis Document Structure @@ -152,11 +152,11 @@ TodoWrite({ # Product Owner Analysis: [Topic from Framework] ## Framework Reference -**Topic Framework**: @../topic-framework.md +**Topic Framework**: @../guidance-specification.md **Role Focus**: Product Backlog & Feature Prioritization perspective ## Discussion Points Analysis -[Address each point from topic-framework.md with product ownership expertise] +[Address each point from guidance-specification.md with product ownership expertise] ### Core Requirements (from framework) [User story formulation and backlog refinement perspective] @@ -189,12 +189,12 @@ TodoWrite({ "status": "completed", "framework_addressed": true, "output_location": ".workflow/WFS-{session}/.brainstorming/product-owner/analysis.md", - "framework_reference": "@../topic-framework.md" + "framework_reference": "@../guidance-specification.md" } } ``` ### Integration Points -- **Framework Reference**: @../topic-framework.md for structured discussion points +- **Framework Reference**: @../guidance-specification.md for structured discussion points - **Cross-Role Synthesis**: Product ownership insights available for synthesis-report.md integration - **Agent Autonomy**: Independent execution with framework guidance diff --git a/.claude/commands/workflow/brainstorm/scrum-master.md b/.claude/commands/workflow/brainstorm/scrum-master.md index 872d7419..8988ddbb 100644 --- a/.claude/commands/workflow/brainstorm/scrum-master.md +++ b/.claude/commands/workflow/brainstorm/scrum-master.md @@ -1,6 +1,6 @@ --- name: scrum-master -description: Generate or update scrum-master/analysis.md addressing topic-framework discussion points +description: Generate or update scrum-master/analysis.md addressing guidance-specification discussion points argument-hint: "optional topic - uses existing framework if available" allowed-tools: Task(conceptual-planning-agent), TodoWrite(*), Read(*), Write(*) --- @@ -8,10 +8,10 @@ allowed-tools: Task(conceptual-planning-agent), TodoWrite(*), Read(*), Write(*) ## 🎯 **Scrum Master Analysis Generator** ### Purpose -**Specialized command for generating scrum-master/analysis.md** that addresses topic-framework.md discussion points from agile process and team collaboration perspective. Creates or updates role-specific analysis with framework references. +**Specialized command for generating scrum-master/analysis.md** that addresses guidance-specification.md discussion points from agile process and team collaboration perspective. Creates or updates role-specific analysis with framework references. ### Core Function -- **Framework-based Analysis**: Address each discussion point in topic-framework.md +- **Framework-based Analysis**: Address each discussion point in guidance-specification.md - **Agile Process Focus**: Sprint planning, team dynamics, and delivery optimization - **Update Mechanism**: Create new or update existing analysis.md - **Agent Delegation**: Use conceptual-planning-agent for analysis generation @@ -32,7 +32,7 @@ IF active_session EXISTS: session_id = get_active_session() brainstorm_dir = .workflow/WFS-{session}/.brainstorming/ - CHECK: brainstorm_dir/topic-framework.md + CHECK: brainstorm_dir/guidance-specification.md IF EXISTS: framework_mode = true load_framework = true @@ -73,7 +73,7 @@ ANALYSIS_MODE: {framework_mode ? "framework_based" : "standalone"} ## Flow Control Steps 1. **load_topic_framework** - Action: Load structured topic discussion framework - - Command: Read(.workflow/WFS-{session}/.brainstorming/topic-framework.md) + - Command: Read(.workflow/WFS-{session}/.brainstorming/guidance-specification.md) - Output: topic_framework_content 2. **load_role_template** @@ -87,17 +87,17 @@ ANALYSIS_MODE: {framework_mode ? "framework_based" : "standalone"} - Output: session_context ## Analysis Requirements -**Framework Reference**: Address all discussion points in topic-framework.md from agile process and team collaboration perspective +**Framework Reference**: Address all discussion points in guidance-specification.md from agile process and team collaboration perspective **Role Focus**: Sprint planning, team dynamics, process optimization, delivery management **Structured Approach**: Create analysis.md addressing framework discussion points **Template Integration**: Apply role template guidelines within framework structure ## Expected Deliverables 1. **analysis.md**: Comprehensive agile process analysis addressing all framework discussion points -2. **Framework Reference**: Include @../topic-framework.md reference in analysis +2. **Framework Reference**: Include @../guidance-specification.md reference in analysis ## Completion Criteria -- Address each discussion point from topic-framework.md with scrum mastery expertise +- Address each discussion point from guidance-specification.md with scrum mastery expertise - Provide actionable sprint planning and team facilitation strategies - Include process optimization and impediment removal insights - Reference framework document using @ notation for integration @@ -116,7 +116,7 @@ TodoWrite({ activeForm: "Detecting session and framework" }, { - content: "Load topic-framework.md and session metadata for context", + content: "Load guidance-specification.md and session metadata for context", status: "pending", activeForm: "Loading framework and session context" }, @@ -144,7 +144,7 @@ TodoWrite({ ### Framework-Based Analysis ``` .workflow/WFS-{session}/.brainstorming/scrum-master/ -└── analysis.md # Structured analysis addressing topic-framework.md discussion points +└── analysis.md # Structured analysis addressing guidance-specification.md discussion points ``` ### Analysis Document Structure @@ -152,11 +152,11 @@ TodoWrite({ # Scrum Master Analysis: [Topic from Framework] ## Framework Reference -**Topic Framework**: @../topic-framework.md +**Topic Framework**: @../guidance-specification.md **Role Focus**: Agile Process & Team Collaboration perspective ## Discussion Points Analysis -[Address each point from topic-framework.md with scrum mastery expertise] +[Address each point from guidance-specification.md with scrum mastery expertise] ### Core Requirements (from framework) [Sprint planning and iteration breakdown perspective] @@ -189,12 +189,12 @@ TodoWrite({ "status": "completed", "framework_addressed": true, "output_location": ".workflow/WFS-{session}/.brainstorming/scrum-master/analysis.md", - "framework_reference": "@../topic-framework.md" + "framework_reference": "@../guidance-specification.md" } } ``` ### Integration Points -- **Framework Reference**: @../topic-framework.md for structured discussion points +- **Framework Reference**: @../guidance-specification.md for structured discussion points - **Cross-Role Synthesis**: Agile process insights available for synthesis-report.md integration - **Agent Autonomy**: Independent execution with framework guidance diff --git a/.claude/commands/workflow/brainstorm/subject-matter-expert.md b/.claude/commands/workflow/brainstorm/subject-matter-expert.md index f704438d..718491cb 100644 --- a/.claude/commands/workflow/brainstorm/subject-matter-expert.md +++ b/.claude/commands/workflow/brainstorm/subject-matter-expert.md @@ -1,6 +1,6 @@ --- name: subject-matter-expert -description: Generate or update subject-matter-expert/analysis.md addressing topic-framework discussion points +description: Generate or update subject-matter-expert/analysis.md addressing guidance-specification discussion points argument-hint: "optional topic - uses existing framework if available" allowed-tools: Task(conceptual-planning-agent), TodoWrite(*), Read(*), Write(*) --- @@ -8,10 +8,10 @@ allowed-tools: Task(conceptual-planning-agent), TodoWrite(*), Read(*), Write(*) ## 🎯 **Subject Matter Expert Analysis Generator** ### Purpose -**Specialized command for generating subject-matter-expert/analysis.md** that addresses topic-framework.md discussion points from domain knowledge and technical expertise perspective. Creates or updates role-specific analysis with framework references. +**Specialized command for generating subject-matter-expert/analysis.md** that addresses guidance-specification.md discussion points from domain knowledge and technical expertise perspective. Creates or updates role-specific analysis with framework references. ### Core Function -- **Framework-based Analysis**: Address each discussion point in topic-framework.md +- **Framework-based Analysis**: Address each discussion point in guidance-specification.md - **Domain Expertise Focus**: Deep technical knowledge, industry standards, and best practices - **Update Mechanism**: Create new or update existing analysis.md - **Agent Delegation**: Use conceptual-planning-agent for analysis generation @@ -32,7 +32,7 @@ IF active_session EXISTS: session_id = get_active_session() brainstorm_dir = .workflow/WFS-{session}/.brainstorming/ - CHECK: brainstorm_dir/topic-framework.md + CHECK: brainstorm_dir/guidance-specification.md IF EXISTS: framework_mode = true load_framework = true @@ -73,7 +73,7 @@ ANALYSIS_MODE: {framework_mode ? "framework_based" : "standalone"} ## Flow Control Steps 1. **load_topic_framework** - Action: Load structured topic discussion framework - - Command: Read(.workflow/WFS-{session}/.brainstorming/topic-framework.md) + - Command: Read(.workflow/WFS-{session}/.brainstorming/guidance-specification.md) - Output: topic_framework_content 2. **load_role_template** @@ -87,17 +87,17 @@ ANALYSIS_MODE: {framework_mode ? "framework_based" : "standalone"} - Output: session_context ## Analysis Requirements -**Framework Reference**: Address all discussion points in topic-framework.md from domain expertise and technical standards perspective +**Framework Reference**: Address all discussion points in guidance-specification.md from domain expertise and technical standards perspective **Role Focus**: Domain knowledge, technical standards, risk assessment, knowledge transfer **Structured Approach**: Create analysis.md addressing framework discussion points **Template Integration**: Apply role template guidelines within framework structure ## Expected Deliverables 1. **analysis.md**: Comprehensive domain expertise analysis addressing all framework discussion points -2. **Framework Reference**: Include @../topic-framework.md reference in analysis +2. **Framework Reference**: Include @../guidance-specification.md reference in analysis ## Completion Criteria -- Address each discussion point from topic-framework.md with subject matter expertise +- Address each discussion point from guidance-specification.md with subject matter expertise - Provide actionable technical standards and best practices recommendations - Include risk assessment and compliance considerations - Reference framework document using @ notation for integration @@ -116,7 +116,7 @@ TodoWrite({ activeForm: "Detecting session and framework" }, { - content: "Load topic-framework.md and session metadata for context", + content: "Load guidance-specification.md and session metadata for context", status: "pending", activeForm: "Loading framework and session context" }, @@ -144,7 +144,7 @@ TodoWrite({ ### Framework-Based Analysis ``` .workflow/WFS-{session}/.brainstorming/subject-matter-expert/ -└── analysis.md # Structured analysis addressing topic-framework.md discussion points +└── analysis.md # Structured analysis addressing guidance-specification.md discussion points ``` ### Analysis Document Structure @@ -152,11 +152,11 @@ TodoWrite({ # Subject Matter Expert Analysis: [Topic from Framework] ## Framework Reference -**Topic Framework**: @../topic-framework.md +**Topic Framework**: @../guidance-specification.md **Role Focus**: Domain Expertise & Technical Standards perspective ## Discussion Points Analysis -[Address each point from topic-framework.md with subject matter expertise] +[Address each point from guidance-specification.md with subject matter expertise] ### Core Requirements (from framework) [Domain-specific requirements and industry standards perspective] @@ -189,12 +189,12 @@ TodoWrite({ "status": "completed", "framework_addressed": true, "output_location": ".workflow/WFS-{session}/.brainstorming/subject-matter-expert/analysis.md", - "framework_reference": "@../topic-framework.md" + "framework_reference": "@../guidance-specification.md" } } ``` ### Integration Points -- **Framework Reference**: @../topic-framework.md for structured discussion points +- **Framework Reference**: @../guidance-specification.md for structured discussion points - **Cross-Role Synthesis**: Domain expertise insights available for synthesis-report.md integration - **Agent Autonomy**: Independent execution with framework guidance diff --git a/.claude/commands/workflow/brainstorm/synthesis.md b/.claude/commands/workflow/brainstorm/synthesis.md index 0fa5505d..501d2d95 100644 --- a/.claude/commands/workflow/brainstorm/synthesis.md +++ b/.claude/commands/workflow/brainstorm/synthesis.md @@ -1,55 +1,59 @@ --- name: synthesis -description: Generate synthesis-specification.md from topic-framework and role analyses with @ references using conceptual-planning-agent +description: Analyze role analyses, identify ambiguities through clarification, and update role documents intelligently using conceptual-planning-agent argument-hint: "[optional: --session session-id]" -allowed-tools: Task(conceptual-planning-agent), TodoWrite(*), Read(*), Write(*) +allowed-tools: Task(conceptual-planning-agent), TodoWrite(*), Read(*), Write(*), Edit(*), Glob(*), AskUserQuestion(*) --- -## 🧩 **Synthesis Document Generator** +## 🧩 **Role Analysis Clarification & Refinement** ### Core Function -**Specialized command for generating synthesis-specification.md** that integrates topic-framework.md and all role analysis.md files using @ reference system. Creates comprehensive implementation specification with cross-role insights. +**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. -**Dynamic Role Discovery**: Automatically detects which roles participated in brainstorming by scanning for `*/analysis.md` files. Synthesizes only actual participating roles, not predefined lists. +**Dynamic Role Discovery**: Automatically detects which roles participated in brainstorming by scanning for `*/analysis.md` files. Analyzes only actual participating roles, not predefined lists. ### Primary Capabilities - **Dynamic Role Discovery**: Automatically identifies participating roles at runtime -- **Framework Integration**: Reference topic-framework.md discussion points across all discovered roles -- **Role Analysis Integration**: Consolidate all discovered role/analysis.md files using @ references -- **Cross-Framework Comparison**: Compare how each participating role addressed framework discussion points -- **@ Reference System**: Create structured references to source documents -- **Update Detection**: Smart updates when new role analyses are added -- **Flexible Participation**: Supports any subset of available roles (1 to 9+) +- **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 ### Document Integration Model -**Three-Document Reference System**: -1. **topic-framework.md** β†’ Structured discussion framework (input) -2. **[role]/analysis.md** β†’ Role-specific analyses addressing framework (input) -3. **synthesis-specification.md** β†’ Complete integrated specification (output) +**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) ## βš™οΈ **Execution Protocol** -### ⚠️ Agent Execution with Flow Control -**Execution Model**: Uses conceptual-planning-agent for synthesis generation with structured file loading. +### ⚠️ Agent Execution with Interactive Clarification +**Execution Model**: Uses conceptual-planning-agent for cross-role analysis, clarification generation, user interaction, and intelligent document updates. **Rationale**: -- **Autonomous Execution**: Agent independently loads and processes all required documents -- **Flow Control**: Structured document loading ensures systematic analysis -- **Complex Cognitive Analysis**: Leverages agent's analytical capabilities for cross-role synthesis +- **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 -**Agent Responsibility**: All file reading and synthesis generation performed by conceptual-planning-agent with FLOW_CONTROL instructions. +**Agent Responsibility**: All file reading, analysis, clarification interaction, and document updates performed by conceptual-planning-agent. ### πŸ“‹ Task Tracking Protocol -Initialize synthesis task tracking using TodoWrite at command start: +Initialize clarification task tracking using TodoWrite at command start: ```json [ - {"content": "Detect active session and validate topic-framework.md existence", "status": "in_progress", "activeForm": "Detecting session and validating framework"}, + {"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": "Check existing synthesis and confirm user action", "status": "pending", "activeForm": "Checking update mechanism"}, - {"content": "Execute synthesis generation using conceptual-planning-agent with FLOW_CONTROL", "status": "pending", "activeForm": "Executing agent-based synthesis generation"}, - {"content": "Agent performs cross-role analysis and generates synthesis-specification.md", "status": "pending", "activeForm": "Agent analyzing and generating synthesis"}, - {"content": "Update workflow-session.json with synthesis completion status", "status": "pending", "activeForm": "Updating session metadata"} + {"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"} ] ``` @@ -68,18 +72,23 @@ ELSE: brainstorm_dir = .workflow/WFS-{session}/.brainstorming/ -# Validate required documents -CHECK: brainstorm_dir/topic-framework.md +# Validate topic framework (optional but recommended) +CHECK: brainstorm_dir/guidance-specification.md IF NOT EXISTS: - ERROR: "topic-framework.md not found. Run /workflow:brainstorm:artifacts first" + WARN: "guidance-specification.md not found. Analysis will rely on role documents only." + +# 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 # Load user's original prompt from session metadata session_metadata = Read(.workflow/WFS-{session}/workflow-session.json) -original_user_prompt = session_metadata.project || session_metadata.description -IF NOT original_user_prompt: - WARN: "No original user prompt found in session metadata" - original_user_prompt = "Not available" +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" ``` ### Phase 2: Role Analysis Discovery @@ -101,69 +110,57 @@ FIND_ANALYSES: [ # - data-architect # - subject-matter-expert # - test-strategist +# - api-designer LOAD_DOCUMENTS: { - "original_user_prompt": original_user_prompt (from session metadata), - "topic_framework": topic-framework.md, + "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], - "existing_synthesis": synthesis-specification.md (if exists) + "participating_roles": [extract role names from discovered directories] } # Note: Not all roles participate in every brainstorming session -# Only synthesize roles that actually produced analysis*.md files +# 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 prompt MUST be primary reference for synthesis +# CRITICAL: Original user intent MUST be primary reference for validation ``` -### Phase 3: Update Mechanism Check -```bash -# Check for existing synthesis -IF synthesis-specification.md EXISTS: - SHOW current synthesis summary to user - ASK: "Synthesis exists. Do you want to:" - OPTIONS: - 1. "Regenerate completely" β†’ Create new synthesis - 2. "Update with new analyses" β†’ Integrate new role analyses - 3. "Preserve existing" β†’ Exit without changes -ELSE: - CREATE new synthesis -``` +### Phase 3: Agent Execution with Interactive Clarification +**Clarification & Update using conceptual-planning-agent** -### Phase 4: Agent Execution with Flow Control -**Synthesis Generation using conceptual-planning-agent** - -Delegate synthesis generation to conceptual-planning-agent with structured file loading: +Delegate analysis, clarification, and update to conceptual-planning-agent: ```bash Task(conceptual-planning-agent): " -[FLOW_CONTROL] +[INTERACTIVE_CLARIFICATION_WORKFLOW] -Execute comprehensive synthesis generation from topic framework and role analyses +Execute comprehensive cross-role analysis, ambiguity detection, user clarification, and intelligent document updates ## Context Loading -OUTPUT_FILE: synthesis-specification.md -OUTPUT_PATH: .workflow/WFS-{session}/.brainstorming/synthesis-specification.md SESSION_ID: {session_id} -ANALYSIS_MODE: cross_role_synthesis +BRAINSTORM_DIR: .workflow/WFS-{session}/.brainstorming/ +ANALYSIS_MODE: cross_role_clarification_and_update +MAX_QUESTIONS: 5 ## ⚠️ CRITICAL: User Intent Authority -**ORIGINAL USER PROMPT IS THE PRIMARY REFERENCE**: {original_user_prompt} -All synthesis MUST align with user's original intent. Topic framework and role analyses are supplementary context. +**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 -1. **load_original_user_prompt** +## 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_prompt (PRIMARY REFERENCE) + - 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 - - Command: Read(.workflow/WFS-{session}/.brainstorming/topic-framework.md) + - 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_prompt + - Note: Validate alignment with original_user_intent 3. **discover_role_analyses** - Action: Dynamically discover all participating role analysis files (supports multiple files per role) @@ -174,78 +171,347 @@ All synthesis MUST align with user's original intent. Topic framework and role a 4. **load_role_analyses** - Action: Load all discovered role analysis documents - Command: Read(each path from role_analysis_paths) - - Output: role_analyses_content - - Note: Filter insights relevant to original_user_prompt + - Output: role_analyses_content_map = {role_name: [analysis_content_1, analysis_content_2, ...]} + - Note: Maintain role-to-content mapping for intelligent updates -5. **check_existing_synthesis** - - Action: Check if synthesis-specification.md already exists - - Command: Read(.workflow/WFS-{session}/.brainstorming/synthesis-specification.md) [if exists] - - Output: existing_synthesis_content [optional] +### Step 2: Cross-Role Integration Analysis (Internal) +Perform internal cross-role analysis following these steps (DO NOT OUTPUT TO USER): -6. **load_synthesis_template** - - Action: Load synthesis role template for structure and guidelines - - Command: Read(~/.claude/workflows/cli-templates/planning-roles/synthesis-role.md) - - Output: synthesis_template_guidelines +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 -## Synthesis Requirements +### Step 2.5: Concept Enhancement (CLI-Powered) +Execute CLI-powered concept enhancement analysis to identify improvement opportunities: -### ⚠️ PRIMARY REQUIREMENT: User Intent Alignment -**User's Original Goal is Supreme**: Synthesis MUST directly address {original_user_prompt} -**Intent Validation**: Every requirement, design decision, and recommendation must trace back to user's original intent -**Deviation Detection**: Flag any role analysis points that drift from user's stated goals -**Refocus Mechanism**: When role discussions diverge, explicitly refocus on original user prompt -**Traceability**: Each section should reference how it fulfills user's original intent +**Purpose**: Enhance role analyses with deeper architectural insights and best practices -### Core Integration -**Cross-Role Analysis**: Integrate all discovered role analyses with comprehensive coverage -**Framework Integration**: Address how each role responded to topic-framework.md discussion points -**User Intent Filter**: Prioritize insights that directly serve user's original prompt -**Decision Transparency**: Document both adopted solutions and rejected alternatives with rationale -**Process Integration**: Include team capability gaps, process risks, and collaboration patterns -**Visual Documentation**: Include key diagrams (architecture, data model, user journey) via Mermaid -**Priority Matrix**: Create quantified recommendation matrix aligned with user's goals -**Actionable Plan**: Provide phased implementation roadmap addressing user's original objectives +**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 +\`\`\` -### Cross-Role Analysis Process (Agent Internal Execution) -Perform systematic cross-role analysis following these steps: +**Fallback**: If CLI unavailable, use Claude analysis with Read tool -1. **Data Collection**: Extract key insights, recommendations, concerns, and diagrams from each discovered role analysis -2. **Consensus Identification**: Identify common themes and agreement areas across all participating roles -3. **Disagreement Analysis**: Document conflicting views and track which specific roles disagree on each point -4. **Innovation Extraction**: Identify breakthrough ideas and cross-role synergy opportunities -5. **Priority Scoring**: Calculate multi-dimensional priority scores (impact, feasibility, effort, risk) for each recommendation -6. **Decision Matrix**: Create comprehensive evaluation matrix and sort recommendations by priority +**Enhancement Points Output**: +Generate list of enhancement opportunities: +\`\`\`markdown +### Enhancement Points -## Synthesis Quality Standards -Follow synthesis-specification.md structure defined in synthesis-role.md template: -- Use template structure for comprehensive document organization -- Apply analysis guidelines for cross-role synthesis process -- Include all required sections from template (Executive Summary, Key Designs, Requirements, etc.) -- Follow @ reference system for traceability to source role analyses -- Apply quality standards from template (completeness, visual clarity, decision transparency) -- Validate output against template's output validation checklist +**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} -## Expected Deliverables -1. **synthesis-specification.md**: Complete integrated specification consolidating all role perspectives -2. **@ References**: Include cross-references to source role analyses -3. **Session Metadata Update**: Update workflow-session.json with synthesis completion status +**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**: Synthesis directly addresses user's original prompt -- All discovered role analyses integrated without gaps -- Framework discussion points addressed across all roles -- **Intent traceability**: Each major section references user's original goals -- Controversial points documented with dissenting roles identified -- Process concerns (team capabilities, risks, collaboration) captured -- Quantified priority recommendations aligned with user's objectives -- Actionable implementation plan addressing user's stated goals -- Comprehensive risk assessment with mitigation strategies -- **Deviation warnings**: Any significant departures from user intent flagged explicitly +- ⚠️ **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 synthesize roles that produced analysis.md files -- Update mechanism: If synthesis exists, prompt user for regenerate/update/preserve decision -- Timeout allocation: Complex synthesis task (60-90 min recommended) +- 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 " ``` @@ -253,70 +519,65 @@ Follow synthesis-specification.md structure defined in synthesis-role.md templat ## πŸ“Š **Output Specification** ### Output Location -The synthesis process creates **one consolidated document** that integrates all role perspectives: +The clarification process **refines existing role analysis documents** without creating new consolidated files: ``` .workflow/WFS-{topic-slug}/.brainstorming/ -β”œβ”€β”€ topic-framework.md # Input: Framework structure -β”œβ”€β”€ [role]/analysis*.md # Input: Role analyses (supports analysis.md or analysis-1/2/3.md per role) -└── synthesis-specification.md # β˜… OUTPUT: Complete integrated specification +β”œβ”€β”€ guidance-specification.md # Input: Framework structure (reference) +β”œβ”€β”€ [role]/analysis*.md # Input & OUTPUT: Role analyses ``` -#### synthesis-specification.md Structure +#### Updated Role Analysis Structure +Each updated role analysis.md will contain: -**Document Purpose**: Defines **"WHAT"** to build - comprehensive requirements and design blueprint. -**Scope**: High-level features, requirements, and design specifications. Does NOT include executable task breakdown (that's IMPL_PLAN.md's responsibility). +**New Section - Clarifications**: +```markdown +## Clarifications + +### Session 2025-01-15 +- **Q**: {Question text} (Category: {category}) + **A**: {Answer} +- **Q**: {Question text} (Category: {category}) + **A**: {Answer} +``` + +**Updated Sections**: Existing sections refined based on clarifications: +- User intent alignment validated/corrected +- Requirements made more specific and measurable +- Architecture decisions clarified with rationale +- Ambiguities resolved, placeholders removed +- Terminology made consistent -**Template Reference**: Complete document structure and content guidelines available in `synthesis-role.md` template, including: -- Executive Summary with strategic overview -- Key Designs & Decisions (architecture diagrams, ADRs, user journeys) -- Controversial Points & Alternatives (decision transparency) -- Requirements & Acceptance Criteria (Functional, Non-Functional, Business) -- Design Specifications (UI/UX, Architecture, Domain Expertise) -- Process & Collaboration Concerns (team skills, risks, patterns, constraints) -- Implementation Roadmap (high-level phases) -- Risk Assessment & Mitigation strategies -**Agent Usage**: The conceptual-planning-agent loads this template to understand expected structure and quality standards. ## πŸ”„ **Session Integration** ### Streamlined Status Synchronization Upon completion, update `workflow-session.json`: -**Dynamic Role Participation**: The `participating_roles` and `roles_synthesized` values are determined at runtime based on actual analysis.md files discovered. +**Dynamic Role Participation**: The `participating_roles` and `roles_updated` values are determined at runtime based on actual analysis.md files and clarification results. ```json { "phases": { "BRAINSTORM": { - "status": "completed", - "synthesis_completed": true, + "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"], - "consolidated_output": { - "synthesis_specification": ".workflow/WFS-{topic}/.brainstorming/synthesis-specification.md" + "available_roles": ["product-manager", "product-owner", "scrum-master", "system-architect", "ui-designer", "ux-expert", "data-architect", "subject-matter-expert", "test-strategist", "api-designer"], + "clarification_results": { + "questions_asked": , + "categories_clarified": [], + "roles_updated": [], + "outstanding_items": [] }, - "synthesis_quality": { - "role_integration": "complete", + "quality_metrics": { + "user_intent_alignment": "validated", "requirement_coverage": "comprehensive", - "decision_transparency": "alternatives_documented", - "process_risks_identified": true, - "implementation_readiness": "ready" - }, - "content_metrics": { - "roles_synthesized": "", - "functional_requirements": "", - "non_functional_requirements": "", - "business_requirements": "", - "architecture_decisions": "", - "controversial_points": "", - "diagrams_included": "", - "process_risks": "", - "team_skill_gaps": "", - "implementation_phases": "", - "risk_factors_identified": "" + "ambiguity_resolution": "complete", + "terminology_consistency": "enforced", + "decision_transparency": "documented" } } } @@ -328,12 +589,13 @@ Upon completion, update `workflow-session.json`: { "phases": { "BRAINSTORM": { - "status": "completed", + "status": "clarification_completed", "participating_roles": ["product-manager", "system-architect", "ui-designer", "ux-expert", "scrum-master"], - "content_metrics": { - "roles_synthesized": 5, - "functional_requirements": 18, - "controversial_points": 2 + "clarification_results": { + "questions_asked": 3, + "categories_clarified": ["Architecture & Design", "User Experience", "Risk & Mitigation"], + "roles_updated": ["system-architect", "ui-designer", "ux-expert"], + "outstanding_items": [] } } } @@ -342,39 +604,45 @@ Upon completion, update `workflow-session.json`: ## βœ… **Quality Assurance** -Verify synthesis output meets these standards (detailed criteria in `synthesis-role.md` template): +Verify clarification output meets these standards: ### Content Completeness -- [ ] All discovered role analyses integrated without gaps -- [ ] Key designs documented (architecture diagrams, ADRs, user journeys via Mermaid) -- [ ] Controversial points captured with alternatives and rationale -- [ ] Process concerns included (team skills, risks, collaboration patterns) -- [ ] Requirements documented (Functional, Non-Functional, Business) with sources +- [ ] 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 ### Analysis Quality +- [ ] User intent alignment validated across all roles - [ ] Cross-role synthesis identifies consensus and conflicts -- [ ] Decision transparency documents both adopted and rejected alternatives -- [ ] Priority recommendations with multi-dimensional evaluation -- [ ] Implementation roadmap with phased approach -- [ ] Risk assessment with mitigation strategies -- [ ] @ references to source role analyses throughout +- [ ] Ambiguities resolved through targeted clarification +- [ ] Intelligent role update decisions (correct roles updated) +- [ ] Terminology consistency enforced +- [ ] Contradictions removed from updated documents + +### 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 synthesis completion, proceed to action planning: +After clarification completion, proceed to planning: ### Standard Workflow (Recommended) ```bash -/workflow:concept-clarify --session WFS-{session-id} # Optional: Clarify ambiguities -/workflow:plan --session WFS-{session-id} # Generate IMPL_PLAN.md and tasks +/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 +/workflow:execute --session WFS-{session-id} # Start implementation ``` ### TDD Workflow ```bash -/workflow:concept-clarify --session WFS-{session-id} # Optional: Clarify ambiguities /workflow:tdd-plan --session WFS-{session-id} "Feature description" /workflow:action-plan-verify --session WFS-{session-id} # Optional: Verify plan quality /workflow:execute --session WFS-{session-id} ``` + diff --git a/.claude/commands/workflow/brainstorm/system-architect.md b/.claude/commands/workflow/brainstorm/system-architect.md index bade34f9..024f55a0 100644 --- a/.claude/commands/workflow/brainstorm/system-architect.md +++ b/.claude/commands/workflow/brainstorm/system-architect.md @@ -1,6 +1,6 @@ --- name: system-architect -description: Generate or update system-architect/analysis.md addressing topic-framework discussion points +description: Generate or update system-architect/analysis.md addressing guidance-specification discussion points argument-hint: "optional topic - uses existing framework if available" allowed-tools: Task(conceptual-planning-agent), TodoWrite(*), Read(*), Write(*) --- @@ -8,10 +8,10 @@ allowed-tools: Task(conceptual-planning-agent), TodoWrite(*), Read(*), Write(*) ## πŸ—οΈ **System Architect Analysis Generator** ### Purpose -**Specialized command for generating system-architect/analysis.md** that addresses topic-framework.md discussion points from system architecture perspective. Creates or updates role-specific analysis with framework references. +**Specialized command for generating system-architect/analysis.md** that addresses guidance-specification.md discussion points from system architecture perspective. Creates or updates role-specific analysis with framework references. ### Core Function -- **Framework-based Analysis**: Address each discussion point in topic-framework.md +- **Framework-based Analysis**: Address each discussion point in guidance-specification.md - **Architecture Focus**: Technical architecture, scalability, and system design perspective - **Update Mechanism**: Create new or update existing analysis.md - **Agent Delegation**: Use conceptual-planning-agent for analysis generation @@ -51,7 +51,7 @@ IF active_session EXISTS: session_id = get_active_session() brainstorm_dir = .workflow/WFS-{session}/.brainstorming/ - CHECK: brainstorm_dir/topic-framework.md + CHECK: brainstorm_dir/guidance-specification.md IF EXISTS: framework_mode = true load_framework = true @@ -78,20 +78,20 @@ ELSE: ``` ### Phase 3: Agent Task Generation -**Framework-Based Analysis** (when topic-framework.md exists): +**Framework-Based Analysis** (when guidance-specification.md exists): ```bash Task(subagent_type="conceptual-planning-agent", prompt="Generate system architect analysis addressing topic framework ## Framework Integration Required - **MANDATORY**: Load and address topic-framework.md discussion points - **Framework Reference**: @{session.brainstorm_dir}/topic-framework.md + **MANDATORY**: Load and address guidance-specification.md discussion points + **Framework Reference**: @{session.brainstorm_dir}/guidance-specification.md **Output Location**: {session.brainstorm_dir}/system-architect/analysis.md ## Analysis Requirements - 1. **Load Topic Framework**: Read topic-framework.md completely + 1. **Load Topic Framework**: Read guidance-specification.md completely 2. **Address Each Discussion Point**: Respond to all 5 framework sections from system architecture perspective - 3. **Include Framework Reference**: Start analysis.md with @../topic-framework.md + 3. **Include Framework Reference**: Start analysis.md with @../guidance-specification.md 4. **Technical Focus**: Emphasize scalability, architecture patterns, technology decisions 5. **Structured Response**: Use framework structure for analysis organization @@ -106,7 +106,7 @@ Task(subagent_type="conceptual-planning-agent", ```markdown # System Architect Analysis: [Topic] - **Framework Reference**: @../topic-framework.md + **Framework Reference**: @../guidance-specification.md **Role Focus**: System Architecture and Technical Design ## Core Requirements Analysis @@ -140,14 +140,14 @@ IF update_mode = "incremental": ## Current Analysis Context **Existing Analysis**: @{session.brainstorm_dir}/system-architect/analysis.md - **Framework Reference**: @{session.brainstorm_dir}/topic-framework.md + **Framework Reference**: @{session.brainstorm_dir}/guidance-specification.md ## Update Requirements 1. **Preserve Structure**: Maintain existing analysis structure 2. **Add New Insights**: Integrate new technical insights and recommendations 3. **Framework Alignment**: Ensure continued alignment with topic framework 4. **Technical Updates**: Add new architecture patterns, technology considerations - 5. **Maintain References**: Keep @../topic-framework.md reference + 5. **Maintain References**: Keep @../guidance-specification.md reference ## Update Instructions - Read existing analysis completely @@ -163,14 +163,14 @@ IF update_mode = "incremental": ### Output Files ``` .workflow/WFS-[topic]/.brainstorming/ -β”œβ”€β”€ topic-framework.md # Input: Framework (if exists) +β”œβ”€β”€ guidance-specification.md # Input: Framework (if exists) └── system-architect/ └── analysis.md # β˜… OUTPUT: Framework-based analysis ``` ### Analysis Structure **Required Elements**: -- **Framework Reference**: @../topic-framework.md (if framework exists) +- **Framework Reference**: @../guidance-specification.md (if framework exists) - **Role Focus**: System Architecture and Technical Design perspective - **5 Framework Sections**: Address each framework discussion point - **Technical Recommendations**: Architecture-specific insights and solutions diff --git a/.claude/commands/workflow/brainstorm/ui-designer.md b/.claude/commands/workflow/brainstorm/ui-designer.md index 699172f9..9516b7c4 100644 --- a/.claude/commands/workflow/brainstorm/ui-designer.md +++ b/.claude/commands/workflow/brainstorm/ui-designer.md @@ -1,6 +1,6 @@ --- name: ui-designer -description: Generate or update ui-designer/analysis.md addressing topic-framework discussion points +description: Generate or update ui-designer/analysis.md addressing guidance-specification discussion points argument-hint: "optional topic - uses existing framework if available" allowed-tools: Task(conceptual-planning-agent), TodoWrite(*), Read(*), Write(*) --- @@ -8,10 +8,10 @@ allowed-tools: Task(conceptual-planning-agent), TodoWrite(*), Read(*), Write(*) ## 🎨 **UI Designer Analysis Generator** ### Purpose -**Specialized command for generating ui-designer/analysis.md** that addresses topic-framework.md discussion points from UI/UX design perspective. Creates or updates role-specific analysis with framework references. +**Specialized command for generating ui-designer/analysis.md** that addresses guidance-specification.md discussion points from UI/UX design perspective. Creates or updates role-specific analysis with framework references. ### Core Function -- **Framework-based Analysis**: Address each discussion point in topic-framework.md +- **Framework-based Analysis**: Address each discussion point in guidance-specification.md - **UI/UX Focus**: User experience, interface design, and accessibility perspective - **Update Mechanism**: Create new or update existing analysis.md - **Agent Delegation**: Use conceptual-planning-agent for analysis generation @@ -53,7 +53,7 @@ IF active_session EXISTS: session_id = get_active_session() brainstorm_dir = .workflow/WFS-{session}/.brainstorming/ - CHECK: brainstorm_dir/topic-framework.md + CHECK: brainstorm_dir/guidance-specification.md IF EXISTS: framework_mode = true load_framework = true @@ -94,7 +94,7 @@ ANALYSIS_MODE: {framework_mode ? "framework_based" : "standalone"} ## Flow Control Steps 1. **load_topic_framework** - Action: Load structured topic discussion framework - - Command: Read(.workflow/WFS-{session}/.brainstorming/topic-framework.md) + - Command: Read(.workflow/WFS-{session}/.brainstorming/guidance-specification.md) - Output: topic_framework_content 2. **load_role_template** @@ -108,17 +108,17 @@ ANALYSIS_MODE: {framework_mode ? "framework_based" : "standalone"} - Output: session_context ## Analysis Requirements -**Framework Reference**: Address all discussion points in topic-framework.md from UI/UX perspective +**Framework Reference**: Address all discussion points in guidance-specification.md from UI/UX perspective **Role Focus**: User experience design, interface optimization, accessibility compliance **Structured Approach**: Create analysis.md addressing framework discussion points **Template Integration**: Apply role template guidelines within framework structure ## Expected Deliverables 1. **analysis.md**: Comprehensive UI/UX analysis addressing all framework discussion points -2. **Framework Reference**: Include @../topic-framework.md reference in analysis +2. **Framework Reference**: Include @../guidance-specification.md reference in analysis ## Completion Criteria -- Address each discussion point from topic-framework.md with UI/UX design expertise +- Address each discussion point from guidance-specification.md with UI/UX design expertise - Provide actionable design recommendations and interface solutions - Include accessibility considerations and WCAG compliance planning - Reference framework document using @ notation for integration @@ -137,7 +137,7 @@ TodoWrite({ activeForm: "Detecting session and framework" }, { - content: "Load topic-framework.md and session metadata for context", + content: "Load guidance-specification.md and session metadata for context", status: "pending", activeForm: "Loading framework and session context" }, @@ -165,7 +165,7 @@ TodoWrite({ ### Framework-Based Analysis ``` .workflow/WFS-{session}/.brainstorming/ui-designer/ -└── analysis.md # Structured analysis addressing topic-framework.md discussion points +└── analysis.md # Structured analysis addressing guidance-specification.md discussion points ``` ### Analysis Document Structure @@ -173,11 +173,11 @@ TodoWrite({ # UI Designer Analysis: [Topic from Framework] ## Framework Reference -**Topic Framework**: @../topic-framework.md +**Topic Framework**: @../guidance-specification.md **Role Focus**: UI/UX Design perspective ## Discussion Points Analysis -[Address each point from topic-framework.md with UI/UX expertise] +[Address each point from guidance-specification.md with UI/UX expertise] ### Core Requirements (from framework) [UI/UX perspective on requirements] @@ -210,12 +210,12 @@ TodoWrite({ "status": "completed", "framework_addressed": true, "output_location": ".workflow/WFS-{session}/.brainstorming/ui-designer/analysis.md", - "framework_reference": "@../topic-framework.md" + "framework_reference": "@../guidance-specification.md" } } ``` ### Integration Points -- **Framework Reference**: @../topic-framework.md for structured discussion points +- **Framework Reference**: @../guidance-specification.md for structured discussion points - **Cross-Role Synthesis**: UI/UX insights available for synthesis-report.md integration - **Agent Autonomy**: Independent execution with framework guidance diff --git a/.claude/commands/workflow/brainstorm/ux-expert.md b/.claude/commands/workflow/brainstorm/ux-expert.md index 1af5d88e..c4ef4d53 100644 --- a/.claude/commands/workflow/brainstorm/ux-expert.md +++ b/.claude/commands/workflow/brainstorm/ux-expert.md @@ -1,6 +1,6 @@ --- name: ux-expert -description: Generate or update ux-expert/analysis.md addressing topic-framework discussion points +description: Generate or update ux-expert/analysis.md addressing guidance-specification discussion points argument-hint: "optional topic - uses existing framework if available" allowed-tools: Task(conceptual-planning-agent), TodoWrite(*), Read(*), Write(*) --- @@ -8,10 +8,10 @@ allowed-tools: Task(conceptual-planning-agent), TodoWrite(*), Read(*), Write(*) ## 🎯 **UX Expert Analysis Generator** ### Purpose -**Specialized command for generating ux-expert/analysis.md** that addresses topic-framework.md discussion points from user experience and interface design perspective. Creates or updates role-specific analysis with framework references. +**Specialized command for generating ux-expert/analysis.md** that addresses guidance-specification.md discussion points from user experience and interface design perspective. Creates or updates role-specific analysis with framework references. ### Core Function -- **Framework-based Analysis**: Address each discussion point in topic-framework.md +- **Framework-based Analysis**: Address each discussion point in guidance-specification.md - **UX Design Focus**: User interface, interaction patterns, and usability optimization - **Update Mechanism**: Create new or update existing analysis.md - **Agent Delegation**: Use conceptual-planning-agent for analysis generation @@ -53,7 +53,7 @@ IF active_session EXISTS: session_id = get_active_session() brainstorm_dir = .workflow/WFS-{session}/.brainstorming/ - CHECK: brainstorm_dir/topic-framework.md + CHECK: brainstorm_dir/guidance-specification.md IF EXISTS: framework_mode = true load_framework = true @@ -94,7 +94,7 @@ ANALYSIS_MODE: {framework_mode ? "framework_based" : "standalone"} ## Flow Control Steps 1. **load_topic_framework** - Action: Load structured topic discussion framework - - Command: Read(.workflow/WFS-{session}/.brainstorming/topic-framework.md) + - Command: Read(.workflow/WFS-{session}/.brainstorming/guidance-specification.md) - Output: topic_framework_content 2. **load_role_template** @@ -108,17 +108,17 @@ ANALYSIS_MODE: {framework_mode ? "framework_based" : "standalone"} - Output: session_context ## Analysis Requirements -**Framework Reference**: Address all discussion points in topic-framework.md from user experience and interface design perspective +**Framework Reference**: Address all discussion points in guidance-specification.md from user experience and interface design perspective **Role Focus**: UI design, interaction patterns, usability optimization, design systems **Structured Approach**: Create analysis.md addressing framework discussion points **Template Integration**: Apply role template guidelines within framework structure ## Expected Deliverables 1. **analysis.md**: Comprehensive UX design analysis addressing all framework discussion points -2. **Framework Reference**: Include @../topic-framework.md reference in analysis +2. **Framework Reference**: Include @../guidance-specification.md reference in analysis ## Completion Criteria -- Address each discussion point from topic-framework.md with UX design expertise +- Address each discussion point from guidance-specification.md with UX design expertise - Provide actionable interface design and usability optimization strategies - Include accessibility considerations and interaction pattern recommendations - Reference framework document using @ notation for integration @@ -137,7 +137,7 @@ TodoWrite({ activeForm: "Detecting session and framework" }, { - content: "Load topic-framework.md and session metadata for context", + content: "Load guidance-specification.md and session metadata for context", status: "pending", activeForm: "Loading framework and session context" }, @@ -165,7 +165,7 @@ TodoWrite({ ### Framework-Based Analysis ``` .workflow/WFS-{session}/.brainstorming/ux-expert/ -└── analysis.md # Structured analysis addressing topic-framework.md discussion points +└── analysis.md # Structured analysis addressing guidance-specification.md discussion points ``` ### Analysis Document Structure @@ -173,11 +173,11 @@ TodoWrite({ # UX Expert Analysis: [Topic from Framework] ## Framework Reference -**Topic Framework**: @../topic-framework.md +**Topic Framework**: @../guidance-specification.md **Role Focus**: User Experience & Interface Design perspective ## Discussion Points Analysis -[Address each point from topic-framework.md with UX design expertise] +[Address each point from guidance-specification.md with UX design expertise] ### Core Requirements (from framework) [User interface and interaction design requirements perspective] @@ -210,12 +210,12 @@ TodoWrite({ "status": "completed", "framework_addressed": true, "output_location": ".workflow/WFS-{session}/.brainstorming/ux-expert/analysis.md", - "framework_reference": "@../topic-framework.md" + "framework_reference": "@../guidance-specification.md" } } ``` ### Integration Points -- **Framework Reference**: @../topic-framework.md for structured discussion points +- **Framework Reference**: @../guidance-specification.md for structured discussion points - **Cross-Role Synthesis**: UX design insights available for synthesis-report.md integration - **Agent Autonomy**: Independent execution with framework guidance diff --git a/.claude/commands/workflow/concept-clarify.md b/.claude/commands/workflow/concept-clarify.md deleted file mode 100644 index 7d5c86fa..00000000 --- a/.claude/commands/workflow/concept-clarify.md +++ /dev/null @@ -1,353 +0,0 @@ ---- -name: concept-clarify -description: Identify underspecified areas in brainstorming artifacts through targeted clarification questions before action planning -argument-hint: "[optional: --session session-id]" -allowed-tools: Read(*), Write(*), Edit(*), TodoWrite(*), Glob(*), Bash(*) ---- - -## User Input - -```text -$ARGUMENTS -``` - -You **MUST** consider the user input before proceeding (if not empty). - -## Outline - -**Goal**: Detect and reduce ambiguity or missing decision points in planning artifacts before moving to task generation. Supports both brainstorm and plan workflows. - -**Timing**: -- **Brainstorm mode**: Runs AFTER `/workflow:brainstorm:synthesis` and BEFORE `/workflow:plan` -- **Plan mode**: Runs AFTER Phase 3 (concept-enhanced) and BEFORE Phase 4 (task-generate) within `/workflow:plan` - -This serves as a quality gate to ensure conceptual clarity before detailed task planning or generation. - -**Execution steps**: - -1. **Session Detection & Validation** - ```bash - # Detect active workflow session - IF --session parameter provided: - session_id = provided session - ELSE: - CHECK: .workflow/.active-* marker files - IF active_session EXISTS: - session_id = get_active_session() - ELSE: - ERROR: "No active workflow session found. Use --session or start a session." - EXIT - - # Mode detection: plan vs brainstorm - brainstorm_dir = .workflow/WFS-{session}/.brainstorming/ - process_dir = .workflow/WFS-{session}/.process/ - - IF EXISTS(process_dir/ANALYSIS_RESULTS.md): - clarify_mode = "plan" - primary_artifact = process_dir/ANALYSIS_RESULTS.md - INFO: "Plan mode: Analyzing ANALYSIS_RESULTS.md" - ELSE IF EXISTS(brainstorm_dir/synthesis-specification.md): - clarify_mode = "brainstorm" - primary_artifact = brainstorm_dir/synthesis-specification.md - INFO: "Brainstorm mode: Analyzing synthesis-specification.md" - ELSE: - ERROR: "No valid artifact found. Run /workflow:brainstorm:synthesis or /workflow:plan first" - EXIT - - # Mode-specific validation - IF clarify_mode == "brainstorm": - CHECK: brainstorm_dir/topic-framework.md - IF NOT EXISTS: - WARN: "topic-framework.md not found. Verification will be limited." - ``` - -2. **Load Artifacts (Mode-Aware)** - ```bash - # Load primary artifact (determined in step 1) - primary_content = Read(primary_artifact) - - # Load user's original intent 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" - - # Load mode-specific supplementary artifacts - IF clarify_mode == "brainstorm": - topic_framework = Read(brainstorm_dir + "/topic-framework.md") # if exists - role_analyses = Glob(brainstorm_dir + "/*/analysis.md") - participating_roles = extract_role_names(role_analyses) - # Plan mode: primary_content (ANALYSIS_RESULTS.md) is self-contained - ``` - -3. **Ambiguity & Coverage Scan** - - Perform structured scan using this taxonomy. For each category, mark status: **Clear** / **Partial** / **Missing**. - - **⚠️ User Intent Alignment** (NEW - HIGHEST PRIORITY): - - Primary artifact alignment with original user intent - - Goal consistency between artifact 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 artifacts - - No unresolved placeholders (TODO, TBD, ???) - - For each category with **Partial** or **Missing** status, add to candidate question queue unless: - - Clarification would not materially change implementation strategy - - Information is better deferred to planning phase - -4. **Generate Prioritized Question Queue** - - Internally generate prioritized queue of candidate questions (maximum 5): - - **Constraints**: - - Maximum 5 questions per session - - Each question must be answerable with: - * Multiple-choice (2-5 mutually exclusive options), OR - * Short answer (≀5 words) - - Only include questions whose answers materially impact: - * Architecture decisions - * Data modeling - * Task decomposition - * Risk mitigation - * Success criteria - - Ensure category coverage balance - - Favor clarifications that reduce downstream rework risk - - **Prioritization Heuristic**: - ``` - priority_score = (impact_on_planning * 0.4) + - (uncertainty_level * 0.3) + - (risk_if_unresolved * 0.3) - ``` - - If zero high-impact ambiguities found, proceed to **Step 8** (report success). - -5. **Sequential Question Loop** (Interactive) - - Present **EXACTLY ONE** question at a time: - - **Multiple-choice format**: - ```markdown - **Question {N}/5**: {Question text} - - | Option | Description | - |--------|-------------| - | A | {Option A description} | - | B | {Option B description} | - | C | {Option C description} | - | D | {Option D description} | - | Short | Provide different answer (≀5 words) | - ``` - - **Short-answer format**: - ```markdown - **Question {N}/5**: {Question text} - - Format: Short answer (≀5 words) - ``` - - **Answer Validation**: - - Validate answer maps to option or fits ≀5 word constraint - - If ambiguous, ask quick disambiguation (doesn't count as new question) - - Once satisfactory, record in working memory and proceed to next question - - **Stop Conditions**: - - All critical ambiguities resolved - - User signals completion ("done", "no more", "proceed") - - Reached 5 questions - - **Never reveal future queued questions in advance**. - -6. **Integration After Each Answer** (Incremental Update) - - After each accepted answer: - - ```bash - # Ensure Clarifications section exists - IF primary_content NOT contains "## Clarifications": - Insert "## Clarifications" section after first heading - - # Create session subsection - IF NOT contains "### Session YYYY-MM-DD": - Create "### Session {today's date}" under "## Clarifications" - - # Append clarification entry - APPEND: "- Q: {question} β†’ A: {answer}" - - # Apply clarification to appropriate section - CASE category: - Functional Requirements β†’ Update "## Requirements" or equivalent section - 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 - - # Remove obsolete/contradictory statements - IF clarification invalidates existing statement: - Replace statement instead of duplicating - - # Save immediately to primary_artifact - Write(primary_artifact) - ``` - -7. **Validation After Each Write** - - - [ ] Clarifications section contains exactly one bullet per accepted answer - - [ ] Total asked questions ≀ 5 - - [ ] Updated sections contain no lingering placeholders - - [ ] No contradictory earlier statements remain - - [ ] Markdown structure valid - - [ ] Terminology consistent across all updated sections - -8. **Completion Report** - - After questioning loop ends or early termination: - - ```markdown - ## βœ… Concept Verification Complete - - **Session**: WFS-{session-id} - **Mode**: {clarify_mode} - **Questions Asked**: {count}/5 - **Artifacts Updated**: {primary_artifact filename} - **Sections Touched**: {list section names} - - ### Coverage Summary - - | Category | Status | Notes | - |----------|--------|-------| - | Requirements Clarity | βœ… Resolved | Acceptance criteria quantified | - | Architecture & Design | βœ… Clear | No ambiguities found | - | Implementation Feasibility | ⚠️ Deferred | Team training plan to be defined in IMPL_PLAN | - | Risk & Mitigation | βœ… Resolved | Critical risks now have mitigation strategies | - | ... | ... | ... | - - **Legend**: - - βœ… Resolved: Was Partial/Missing, now addressed - - βœ… Clear: Already sufficient - - ⚠️ Deferred: Low impact, better suited for planning phase - - ❌ Outstanding: Still Partial/Missing but question quota reached - - ### Recommendations - - - βœ… **PROCEED to /workflow:plan**: Conceptual foundation is clear - - OR ⚠️ **Address Outstanding Items First**: {list critical outstanding items} - - OR πŸ”„ **Run /workflow:concept-clarify Again**: If new information available - - ### Next Steps - - **If Outstanding Items Exist**: - 1. TodoWrite tracking for outstanding issues - 2. Call conceptual-planning-agent to fix conceptual gaps - 3. Wait for user confirmation before proceeding - - **If No Issues**: - ```bash - /workflow:plan # Generate IMPL_PLAN.md and task.json - ``` - ``` - -9. **Update Session Metadata** - - ```bash - # Update metadata based on mode - IF clarify_mode == "brainstorm": - phase_key = "BRAINSTORM" - ELSE: # plan mode - phase_key = "PLAN" - - # Update session metadata - { - "phases": { - "{phase_key}": { - "status": "concept_verified", - "concept_verification": { - "completed": true, - "completed_at": "timestamp", - "mode": "{clarify_mode}", - "questions_asked": {count}, - "categories_clarified": [{list}], - "outstanding_items": [], - "recommendation": "PROCEED" # or "ADDRESS_OUTSTANDING" - } - } - } - } - ``` - -## Behavior Rules - -- **If no meaningful ambiguities found**: Report "No critical ambiguities detected. Conceptual foundation is clear." and suggest proceeding to `/workflow:plan`. -- **If synthesis-specification.md missing**: Instruct user to run `/workflow:brainstorm:synthesis` first. -- **Never exceed 5 questions** (disambiguation retries don't count as new questions). -- **Respect user early termination**: Signals like "stop", "done", "proceed" should stop questioning. -- **If quota reached with high-impact items unresolved**: Explicitly flag them under "Outstanding" with recommendation to address before planning. -- **Avoid speculative tech stack questions** unless absence blocks conceptual clarity. - -## Operating Principles - -### Context Efficiency -- **Minimal high-signal tokens**: Focus on actionable clarifications -- **Progressive disclosure**: Load artifacts incrementally -- **Deterministic results**: Rerunning without changes produces consistent analysis - -### Verification Guidelines -- **NEVER hallucinate missing sections**: Report them accurately -- **Prioritize high-impact ambiguities**: Focus on what affects planning -- **Use examples over exhaustive rules**: Cite specific instances -- **Report zero issues gracefully**: Emit success report with coverage statistics -- **Update incrementally**: Save after each answer to minimize context loss - -## Context - -{ARGS} diff --git a/.claude/commands/workflow/execute.md b/.claude/commands/workflow/execute.md index 9c32023d..2d32738a 100644 --- a/.claude/commands/workflow/execute.md +++ b/.claude/commands/workflow/execute.md @@ -349,7 +349,7 @@ TodoWrite({ #### Context Sources (Priority Order) 1. **Complete Task JSON**: Full task definition including all fields and artifacts -2. **Artifacts Context**: Brainstorming outputs and synthesis specifications from task.context.artifacts +2. **Artifacts Context**: Brainstorming outputs and role analysess from task.context.artifacts 3. **Flow Control Context**: Accumulated outputs from pre_analysis steps (including artifact loading) 4. **Dependency Summaries**: Previous task completion summaries 5. **Session Context**: Workflow paths and session metadata @@ -370,8 +370,8 @@ TodoWrite({ { "task": { /* Complete task JSON with artifacts array */ }, "artifacts": { - "synthesis_specification": { "path": ".workflow/WFS-session/.brainstorming/synthesis-specification.md", "priority": "highest" }, - "topic_framework": { "path": ".workflow/WFS-session/.brainstorming/topic-framework.md", "priority": "medium" }, + "synthesis_specification": { "path": ".workflow/WFS-session/.brainstorming/role analysis documents", "priority": "highest" }, + "topic_framework": { "path": ".workflow/WFS-session/.brainstorming/guidance-specification.md", "priority": "medium" }, "role_analyses": [ /* Individual role analysis files */ ], "available_artifacts": [ /* All detected brainstorming artifacts */ ] }, @@ -417,7 +417,7 @@ Task(subagent_type="{meta.agent}", ## Instructions 1. **Load Complete Task JSON**: Read and validate all fields (id, title, status, meta, context, flow_control) 2. **Execute Flow Control**: If `flow_control.pre_analysis` exists, execute steps sequentially: - - Load artifacts (synthesis-specification.md, role analyses) using commands in each step + - Load artifacts (role analysis documents, role analyses) using commands in each step - Accumulate context from step outputs using variable substitution [variable_name] - Handle errors per step.on_error (skip_optional | fail | retry_once) 3. **Implement Solution**: Follow `flow_control.implementation_approach` using accumulated context @@ -478,7 +478,7 @@ Task(subagent_type="{meta.agent}", { "type": "synthesis_specification", "source": "brainstorm_synthesis", - "path": ".workflow/WFS-[session]/.brainstorming/synthesis-specification.md", + "path": ".workflow/WFS-[session]/.brainstorming/role analysis documents", "priority": "highest", "contains": "complete_integrated_specification" }, @@ -495,10 +495,10 @@ Task(subagent_type="{meta.agent}", "pre_analysis": [ { "step": "load_synthesis_specification", - "action": "Load consolidated synthesis specification from brainstorming", + "action": "Load consolidated role analyses from brainstorming", "commands": [ - "bash(ls .workflow/WFS-[session]/.brainstorming/synthesis-specification.md 2>/dev/null || echo 'synthesis specification not found')", - "Read(.workflow/WFS-[session]/.brainstorming/synthesis-specification.md)" + "bash(ls .workflow/WFS-[session]/.brainstorming/role analysis documents 2>/dev/null || echo 'role analyses not found')", + "Read(.workflow/WFS-[session]/.brainstorming/role analysis documents)" ], "output_to": "synthesis_specification", "on_error": "skip_optional" @@ -513,16 +513,16 @@ Task(subagent_type="{meta.agent}", "implementation_approach": [ { "step": 1, - "title": "Implement task following synthesis specification", - "description": "Implement '[title]' following synthesis specification. PRIORITY: Use synthesis-specification.md as primary requirement source. When implementation needs technical details (e.g., API schemas, caching configs, design tokens), refer to artifacts[] for detailed specifications from original role analyses.", + "title": "Implement task following role analyses", + "description": "Implement '[title]' following role analyses. PRIORITY: Use role analysis documents as primary requirement source. When implementation needs technical details (e.g., API schemas, caching configs, design tokens), refer to artifacts[] for detailed specifications from original role analyses.", "modification_points": [ - "Apply consolidated requirements from synthesis-specification.md", + "Apply consolidated requirements from role analysis documents", "Follow technical guidelines from synthesis", "Consult artifacts for implementation details when needed", "Integrate with existing patterns" ], "logic_flow": [ - "Load synthesis specification", + "Load role analyses", "Parse architecture and requirements", "Implement following specification", "Consult artifacts for technical details when needed", diff --git a/.claude/commands/workflow/plan.md b/.claude/commands/workflow/plan.md index 210e5408..a1c873ac 100644 --- a/.claude/commands/workflow/plan.md +++ b/.claude/commands/workflow/plan.md @@ -13,12 +13,12 @@ allowed-tools: SlashCommand(*), TodoWrite(*), Read(*), Bash(*) **Execution Model - Auto-Continue Workflow with Quality Gate**: -This workflow runs **mostly autonomously** once triggered, with one interactive quality gate (Phase 3.5). Phases 3 and 4 are delegated to specialized agents for complex analysis and task generation. +This workflow runs **mostly autonomously** once triggered, with one interactive quality gate (Phase 3.5). Phase 3 (conflict resolution) and Phase 4 (task generation) are delegated to specialized agents. 1. **User triggers**: `/workflow:plan "task"` 2. **Phase 1 executes** β†’ Session discovery β†’ Auto-continues 3. **Phase 2 executes** β†’ Context gathering β†’ Auto-continues -4. **Phase 3 executes** (cli-execution-agent) β†’ Intelligent analysis β†’ Auto-continues +4. **Phase 3 executes** (optional, if conflict_risk β‰₯ medium) β†’ Conflict resolution β†’ Auto-continues 5. **Phase 3.5 executes** β†’ **Pauses for user Q&A** β†’ User answers clarification questions β†’ Auto-continues 6. **Phase 4 executes** (task-generate-agent if --agent) β†’ Task generation β†’ Reports final summary @@ -96,23 +96,31 @@ CONTEXT: Existing user database schema, REST API endpoints --- -### Phase 3: Intelligent Analysis +### Phase 3: Conflict Resolution (Optional - auto-triggered by conflict risk) -**Command**: `SlashCommand(command="/workflow:tools:concept-enhanced --session [sessionId] --context [contextPath]")` +**Trigger**: Only execute when context-package.json indicates conflict_risk is "medium" or "high" -**Input**: `sessionId` from Phase 1, `contextPath` from Phase 2 +**Command**: `SlashCommand(command="/workflow:tools:conflict-resolution --session [sessionId] --context [contextPath]")` + +**Input**: +- sessionId from Phase 1 +- contextPath from Phase 2 +- conflict_risk from context-package.json **Parse Output**: -- Extract: Execution status (success/failed) -- Verify: ANALYSIS_RESULTS.md file path +- Extract: Execution status (success/skipped/failed) +- Verify: CONFLICT_RESOLUTION.md file path (if executed) **Validation**: -- File `.workflow/[sessionId]/.process/ANALYSIS_RESULTS.md` exists +- File `.workflow/[sessionId]/.process/CONFLICT_RESOLUTION.md` exists (if executed) +**Skip Behavior**: +- If conflict_risk is "none" or "low", skip directly to Phase 3.5 +- Display: "No significant conflicts detected, proceeding to clarification" -**TodoWrite**: Mark phase 3 completed, phase 3.5 in_progress +**TodoWrite**: Mark phase 3 completed (if executed) or skipped, phase 3.5 in_progress -**After Phase 3**: Return to user showing Phase 3 results, then auto-continue to Phase 3.5 +**After Phase 3**: Return to user showing conflict resolution results (if executed) and selected strategies, then auto-continue to Phase 3.5 **Memory State Check**: - Evaluate current context window usage and memory state @@ -133,17 +141,17 @@ CONTEXT: Existing user database schema, REST API endpoints **Input**: `sessionId` from Phase 1 **Behavior**: -- Auto-detects plan mode (ANALYSIS_RESULTS.md exists) +- Auto-detects plan mode (ANALYSIS_RESULTS.md exists if Phase 3 executed) - Interactively asks up to 5 targeted questions to resolve ambiguities -- Updates ANALYSIS_RESULTS.md with clarifications +- Updates ANALYSIS_RESULTS.md with clarifications (if file exists from Phase 3) - Pauses workflow for user input (breaks auto-continue temporarily) **Parse Output**: -- Verify clarifications added to ANALYSIS_RESULTS.md +- Verify clarifications added to ANALYSIS_RESULTS.md (if Phase 3 executed) - Check recommendation: "PROCEED" or "ADDRESS_OUTSTANDING" **Validation**: -- ANALYSIS_RESULTS.md updated with `## Clarifications` section +- If Phase 3 executed: ANALYSIS_RESULTS.md updated with `## Clarifications` section - All critical ambiguities resolved or documented as outstanding **TodoWrite**: Mark phase 3.5 completed, phase 4 in_progress @@ -159,12 +167,12 @@ CONTEXT: Existing user database schema, REST API endpoints ### Phase 4: Task Generation **Relationship with Brainstorm Phase**: -- If brainstorm synthesis exists (synthesis-specification.md), Phase 3 analysis incorporates it as input -- **⚠️ User's original intent is ALWAYS primary**: New or refined user goals override synthesis recommendations -- **synthesis-specification.md defines "WHAT"**: Requirements, design specs, high-level features +- If brainstorm role analyses exist ([role]/analysis.md files), Phase 3 analysis incorporates them as input +- **⚠️ User's original intent is ALWAYS primary**: New or refined user goals override brainstorm recommendations +- **Role analysis.md files define "WHAT"**: Requirements, design specs, role-specific insights - **IMPL_PLAN.md defines "HOW"**: Executable task breakdown, dependencies, implementation sequence -- Task generation translates high-level specifications into concrete, actionable work items -- **Intent priority**: Current user prompt > synthesis-specification.md > topic-framework.md +- Task generation translates high-level role analyses into concrete, actionable work items +- **Intent priority**: Current user prompt > role analysis.md files > guidance-specification.md **Command Selection**: - Manual: `SlashCommand(command="/workflow:tools:task-generate --session [sessionId]")` @@ -211,24 +219,33 @@ Plan: .workflow/[sessionId]/IMPL_PLAN.md ```javascript // Initialize (before Phase 1) +// Note: Phase 3 todo only included when conflict_risk β‰₯ medium (determined after Phase 2) 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 intelligent analysis", "status": "pending", "activeForm": "Executing intelligent analysis"}, + // Phase 3 todo added dynamically after Phase 2 if conflict_risk β‰₯ medium {"content": "Execute concept clarification", "status": "pending", "activeForm": "Executing concept clarification"}, {"content": "Execute task generation", "status": "pending", "activeForm": "Executing task generation"} ]}) -// After Phase 1 +// After Phase 2 (if conflict_risk β‰₯ medium, insert Phase 3 todo) TodoWrite({todos: [ {"content": "Execute session discovery", "status": "completed", "activeForm": "Executing session discovery"}, - {"content": "Execute context gathering", "status": "in_progress", "activeForm": "Executing context gathering"}, - {"content": "Execute intelligent analysis", "status": "pending", "activeForm": "Executing intelligent analysis"}, + {"content": "Execute context gathering", "status": "completed", "activeForm": "Executing context gathering"}, + {"content": "Execute conflict resolution", "status": "in_progress", "activeForm": "Executing conflict resolution"}, {"content": "Execute concept clarification", "status": "pending", "activeForm": "Executing concept clarification"}, {"content": "Execute task generation", "status": "pending", "activeForm": "Executing task generation"} ]}) -// Continue pattern for Phase 2, 3, 3.5, 4... +// After Phase 2 (if conflict_risk is none/low, skip Phase 3) +TodoWrite({todos: [ + {"content": "Execute session discovery", "status": "completed", "activeForm": "Executing session discovery"}, + {"content": "Execute context gathering", "status": "completed", "activeForm": "Executing context gathering"}, + {"content": "Execute concept clarification", "status": "in_progress", "activeForm": "Executing concept clarification"}, + {"content": "Execute task generation", "status": "pending", "activeForm": "Executing task generation"} +]}) + +// Continue pattern for Phase 3 (if executed), 3.5, 4... ``` ## Input Processing @@ -277,20 +294,21 @@ Phase 1: session:start --auto "structured-description" ↓ Phase 2: context-gather --session sessionId "structured-description" ↓ Input: sessionId + session memory + structured description - ↓ Output: contextPath (context-package.json) + ↓ Output: contextPath (context-package.json) + conflict_risk ↓ -Phase 3: cli-execution-agent (Intelligent Analysis) - ↓ Input: sessionId + contextPath + task description - ↓ Agent discovers context, enhances prompt, executes with Gemini - ↓ Output: ANALYSIS_RESULTS.md + execution log +Phase 3: conflict-resolution [AUTO-TRIGGERED if conflict_risk β‰₯ medium] + ↓ Input: sessionId + contextPath + conflict_risk + ↓ CLI-powered conflict detection and resolution strategy generation + ↓ Output: CONFLICT_RESOLUTION.md (if conflict_risk β‰₯ medium) + ↓ Skip if conflict_risk is none/low ↓ Phase 3.5: concept-clarify --session sessionId (Quality Gate) - ↓ Input: sessionId + ANALYSIS_RESULTS.md (auto-detected) + ↓ Input: sessionId + CONFLICT_RESOLUTION.md (if Phase 3 executed) ↓ Interactive: User answers clarification questions - ↓ Output: Updated ANALYSIS_RESULTS.md with clarifications + ↓ Output: Updated clarifications ↓ Phase 4: task-generate[--agent] --session sessionId - ↓ Input: sessionId + clarified ANALYSIS_RESULTS.md + session memory + ↓ Input: sessionId + conflict resolution decisions (if exists) + session memory ↓ Output: IMPL_PLAN.md, task JSONs, TODO_LIST.md ↓ Return summary to user @@ -300,6 +318,7 @@ Return summary to user - Previous task summaries - Existing context and analysis - Brainstorming artifacts +- Conflict resolution decisions (if Phase 3 executed) - Session-specific configuration **Structured Description Benefits**: @@ -317,17 +336,18 @@ Return summary to user ## Coordinator Checklist βœ… **Pre-Phase**: Convert user input to structured format (GOAL/SCOPE/CONTEXT) -βœ… Initialize TodoWrite before any command (include Phase 3.5) +βœ… Initialize TodoWrite before any command (Phase 3 added dynamically after Phase 2) βœ… Execute Phase 1 immediately with structured description βœ… Parse session ID from Phase 1 output, store in memory βœ… Pass session ID and structured description to Phase 2 command βœ… Parse context path from Phase 2 output, store in memory -βœ… **Launch Phase 3 agent**: Build Task prompt with sessionId and contextPath -βœ… Wait for agent completion, parse execution log path -βœ… Verify ANALYSIS_RESULTS.md created by agent +βœ… **Extract conflict_risk from context-package.json**: Determine Phase 3 execution +βœ… **If conflict_risk β‰₯ medium**: Launch Phase 3 conflict-resolution with sessionId and contextPath +βœ… Wait for Phase 3 completion (if executed), verify CONFLICT_RESOLUTION.md created +βœ… **If conflict_risk is none/low**: Skip Phase 3, proceed directly to Phase 3.5 βœ… **Execute Phase 3.5**: Pass session ID to `/workflow:concept-clarify` βœ… Wait for user interaction (clarification Q&A) -βœ… Verify ANALYSIS_RESULTS.md updated with clarifications +βœ… Verify clarifications completed βœ… Check recommendation: proceed if "PROCEED", otherwise alert user βœ… **Build Phase 4 command** based on flags: - Base command: `/workflow:tools:task-generate` (or `-agent` if `--agent` flag) @@ -335,7 +355,7 @@ Return summary to user - Add `--cli-execute` if flag present βœ… Pass session ID to Phase 4 command βœ… Verify all Phase 4 outputs -βœ… Update TodoWrite after each phase +βœ… Update TodoWrite after each phase (dynamically adjust for Phase 3 presence) βœ… After each phase, automatically continue to next phase based on TodoList status ## Structure Template Reference diff --git a/.claude/commands/workflow/tools/concept-enhanced.md b/.claude/commands/workflow/tools/concept-enhanced.md index a700071f..2cbcff59 100644 --- a/.claude/commands/workflow/tools/concept-enhanced.md +++ b/.claude/commands/workflow/tools/concept-enhanced.md @@ -1,38 +1,37 @@ --- name: concept-enhanced -description: Enhanced intelligent analysis with parallel CLI execution and design blueprint generation +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 --- -# Enhanced Analysis Command (/workflow:tools:concept-enhanced) +# Architecture Validation Command (/workflow:tools:concept-enhanced) ## Overview -Advanced solution design and feasibility analysis engine with parallel CLI execution. Processes standardized context packages to produce ANALYSIS_RESULTS.md focused on solution improvements, key design decisions, and critical insights. +Architecture validation and implementation enhancement engine with CLI-powered analysis. Validates existing architectural approaches and enhances implementation details through Gemini/Codex analysis. -**Scope**: Solution-focused technical analysis only. Does NOT generate task breakdowns or implementation plans. +**Scope**: Validation and enhancement only. Does NOT generate new designs, task breakdowns, or implementation plans. -**Usage**: Standalone command or integrated into `/workflow:plan`. Accepts context packages and orchestrates Gemini/Codex for comprehensive analysis. +**Usage**: Optional enhancement in `/workflow:plan` (requires `--cli-enhance` flag). Accepts context packages and validates architectural soundness. ## Core Philosophy & Responsibilities -- **Agent Coordination**: Delegate analysis execution to specialized agent (cli-execution-agent) -- **Solution-Focused Analysis**: Emphasize design decisions, architectural rationale, and critical insights (exclude task planning) -- **Context-Driven**: Parse and validate context-package.json for precise analysis -- **Agent-Driven Tool Selection**: Agent autonomously selects Gemini/Codex based on task complexity -- **Solution Design**: Evaluate architecture, identify key design decisions with rationale -- **Feasibility Assessment**: Analyze technical complexity, risks, implementation readiness -- **Optimization Recommendations**: Performance, security, and code quality improvements +- **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 technical analysis +- **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) -- **Analysis Focus**: Architecture design (Gemini), Feasibility validation (Codex), Performance optimization (both) +- **Validation Focus**: Architecture validation (Gemini), Feasibility verification (Codex), Quality assessment (both) **Complexity Tiers** (Agent decides internally): - **Simple (≀3 modules)**: Gemini-only analysis @@ -140,16 +139,16 @@ Generate final ANALYSIS_RESULTS.md and report completion status: **Template Reference**: `~/.claude/workflows/cli-templates/prompts/workflow/analysis-results-structure.txt` -Generated ANALYSIS_RESULTS.md focuses on **solution improvements, key design decisions, and critical insights** (NOT task planning). +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**: Analysis focus, tools used, overall assessment (X/5), recommendation status +1. **Executive Summary**: Validation focus, tools used, overall assessment (X/5), recommendation status 2. **Current State Analysis**: Architecture overview, compatibility/dependencies, critical findings -3. **Proposed Solution Design**: Core principles, system design, key decisions with rationale, technical specs -4. **Implementation Strategy**: Development approach, code modification targets, feasibility assessment, risk mitigation -5. **Solution Optimization**: Performance, security, code quality recommendations -6. **Critical Success Factors**: Technical requirements, quality metrics, success validation +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 @@ -159,11 +158,11 @@ Generated ANALYSIS_RESULTS.md focuses on **solution improvements, key design dec - New files: `file` only (e.g., `src/auth/PasswordReset.ts`) - Unknown lines: `file:function:*` -**Key Design Decisions** (minimum 2): -- Decision statement -- Rationale (why this approach) -- Alternatives considered (tradeoffs) -- Impact (implications on architecture) +**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 @@ -171,10 +170,11 @@ Generated ANALYSIS_RESULTS.md focuses on **solution improvements, key design dec - Final Recommendation: PROCEED | PROCEED_WITH_MODIFICATIONS | RECONSIDER | REJECT ### Content Focus -- βœ… Solution improvements and architectural decisions -- βœ… Design rationale, alternatives, and tradeoffs -- βœ… Risk assessment with mitigation strategies -- βœ… Optimization opportunities (performance, security, quality) +- βœ… 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 @@ -213,11 +213,11 @@ Generated ANALYSIS_RESULTS.md focuses on **solution improvements, key design dec **Quality Checks**: Completeness, consistency, feasibility validation **Success Criteria**: -- βœ… Solution-focused analysis (design decisions, critical insights, NO task planning) +- βœ… Validation-focused analysis (quality assessment, enhancement recommendations, NO new designs or task planning) - βœ… Single output file only (ANALYSIS_RESULTS.md) -- βœ… Design decision depth with rationale/alternatives/tradeoffs -- βœ… Feasibility assessment (complexity, risks, readiness) -- βœ… Optimization strategies (performance, security, quality) +- βœ… 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 @@ -225,5 +225,5 @@ Generated ANALYSIS_RESULTS.md focuses on **solution improvements, key design dec ## Related Commands - `/context:gather` - Generate context packages required by this command -- `/workflow:plan` - Call this command for analysis -- `/task:create` - Create specific tasks based on analysis results \ No newline at end of file +- `/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/conflict-resolution.md b/.claude/commands/workflow/tools/conflict-resolution.md new file mode 100644 index 00000000..08930245 --- /dev/null +++ b/.claude/commands/workflow/tools/conflict-resolution.md @@ -0,0 +1,365 @@ +--- +name: conflict-resolution +description: Detect and resolve conflicts between plan and existing codebase using CLI-powered analysis +argument-hint: "--session WFS-session-id --context path/to/context-package.json" +examples: + - /workflow:tools:conflict-resolution --session WFS-auth --context .workflow/WFS-auth/.process/context-package.json + - /workflow:tools:conflict-resolution --session WFS-payment --context .workflow/WFS-payment/.process/context-package.json +--- + +# Conflict Resolution Command (/workflow:tools:conflict-resolution) + +## Overview +Analyzes potential conflicts between implementation plan and existing codebase, generating multiple resolution strategies for user selection. + +**Trigger Condition**: Only execute when context-package.json indicates conflict_risk is "medium" or "high" + +**Scope**: Conflict detection and resolution strategy generation only. Does NOT modify code or generate tasks. + +**Usage**: Automatically triggered in `/workflow:plan` Phase 3 when conflict risk detected. + +## Core Philosophy & Responsibilities +- **Conflict Detection**: Analyze plan vs existing code architecture inconsistencies +- **Multi-Strategy Generation**: Generate 2-4 resolution options per conflict +- **CLI-Powered Analysis**: Use Gemini/Qwen/Codex for deep code analysis +- **Graceful Fallback**: Use Claude analysis if CLI tools unavailable +- **User Decision**: Present strategies for user selection, never auto-apply +- **Single Output**: Generate CONFLICT_RESOLUTION.md with findings and options + +## Conflict Detection Categories + +**Architecture Conflicts**: +- New architecture incompatible with existing patterns +- Module structure changes affecting existing components +- Design pattern migrations required + +**API & Interface Conflicts**: +- Breaking changes to existing API contracts +- Function signature modifications +- Public interface changes affecting dependents + +**Data Model Conflicts**: +- Database schema modifications +- Data type changes breaking compatibility +- Migration requirements for existing data + +**Dependency Conflicts**: +- Version conflicts with existing dependencies +- New dependencies incompatible with current setup +- Breaking changes in dependency updates + +## Execution Lifecycle + +### Phase 1: Validation & Trigger Check +1. **Session Validation**: Verify `.workflow/{session_id}/` exists +2. **Context Package Loading**: Read and parse context-package.json +3. **Conflict Risk Check**: + ```javascript + if (context_package.conflict_detection.conflict_risk in ["none", "low"]) { + SKIP: "No significant conflicts detected" + EXIT + } + ``` +4. **Agent Preparation**: Prepare agent task prompt with conflict analysis requirements + +### Phase 2: Agent-Delegated Conflict Analysis + +**Agent Invocation**: +```javascript +Task( + subagent_type="cli-execution-agent", + description="Detect and analyze code conflicts", + prompt=` +## Execution Context + +**Session ID**: {session_id} +**Mode**: Conflict Detection and Resolution Strategy Generation +**Conflict Risk**: {conflict_risk} + +## Input Context + +**Context Package**: {context_path} +**Existing Files**: {existing_files_list} +**Affected Modules**: {affected_modules} + +## Analysis Task + +### Step 1: Load Existing Codebase Context +1. **Load Existing Files** (from context package existing_files) + - Read all files listed in conflict_detection.existing_files + - Analyze current architecture patterns + - Identify current API contracts and interfaces + +2. **Load Plan Requirements** (from session context) + - Read .workflow/{session_id}/.brainstorming/*/analysis.md (if exists) + - Extract requirements and design decisions + - Identify planned changes + +### Step 2: CLI-Powered Conflict Analysis +Execute conflict analysis using CLI tools: + +**Primary Tool - Gemini Analysis**: +\`\`\`bash +cd {project_root} && gemini -p " +PURPOSE: Analyze conflicts between plan and existing code +TASK: +β€’ Compare existing architecture with planned changes +β€’ Identify API contract breaking changes +β€’ Detect data model incompatibilities +β€’ Assess dependency conflicts +MODE: analysis +CONTEXT: @{existing_files_pattern} @.workflow/{session_id}/**/* +EXPECTED: Conflict list with severity and affected areas +RULES: Focus on breaking changes and migration complexity +" +\`\`\` + +**Fallback - Qwen Analysis** (if Gemini unavailable): +Same prompt structure, replace 'gemini' with 'qwen' + +**Fallback - Claude Analysis** (if CLI unavailable): +- Manual file reading and comparison +- Pattern matching for common conflict types +- Heuristic-based conflict detection + +### Step 3: Generate Resolution Strategies +For each detected conflict, generate 2-4 resolution options: + +**Strategy Template**: +```markdown +### Conflict: {conflict_name} +**Severity**: Critical | High | Medium +**Category**: Architecture | API | Data Model | Dependency +**Affected Files**: {file_list} +**Impact**: {impact_description} + +#### Option 1: {strategy_name} +**Approach**: {brief_description} +**Pros**: +- {advantage_1} +- {advantage_2} +**Cons**: +- {disadvantage_1} +- {disadvantage_2} +**Effort**: Low | Medium | High +**Risk**: Low | Medium | High + +#### Option 2: {strategy_name} +... + +**Recommended**: Option {N} - {rationale} +``` + +### Step 4: Generate CONFLICT_RESOLUTION.md +Create comprehensive conflict resolution document: + +**Output Location**: \`.workflow/{session_id}/.process/CONFLICT_RESOLUTION.md\` + +**Required Structure**: +1. **Executive Summary**: Total conflicts, severity distribution, overall risk +2. **Conflict Analysis**: Detailed per-conflict analysis with categories +3. **Resolution Strategies**: Multiple options per conflict with pros/cons +4. **Recommended Actions**: Prioritized recommendations with rationale +5. **Migration Considerations**: Data/API migration requirements if any + +### Output Requirements + +**Quality Standards**: +- Minimum 2 resolution options per conflict +- Clear pros/cons for each strategy +- Effort and risk estimates included +- Recommended strategy with clear rationale +- Actionable migration steps if required + +## Output +Generate CONFLICT_RESOLUTION.md and report completion status: +- Conflicts detected: {count} +- Severity distribution: Critical: {N}, High: {N}, Medium: {N} +- Resolution strategies: {total_options} +- Output location: .workflow/{session_id}/.process/CONFLICT_RESOLUTION.md +\` +) +``` + +**Agent Execution Flow** (Internal to cli-execution-agent): +1. Parse session ID and context path, load context-package.json +2. Check conflict_risk, exit if none/low +3. Load existing codebase files from conflict_detection.existing_files +4. Load plan requirements from session brainstorming artifacts +5. Execute CLI tool analysis (Gemini/Qwen/Claude fallback) +6. Parse conflict findings from CLI output +7. Generate resolution strategies (2-4 options per conflict) +8. Create CONFLICT_RESOLUTION.md with structured findings +9. Verify output file exists at correct path +10. 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/CONFLICT_RESOLUTION.md` exists +2. **Content Validation**: Verify required sections present +3. **Strategy Quality**: Ensure minimum 2 options per conflict +4. **Agent Log**: Retrieve agent execution log from `.workflow/{session_id}/.chat/` +5. **Success Criteria**: File exists, contains all required sections, strategies actionable + +## CONFLICT_RESOLUTION.md Format + +**Template Reference**: Resolution document focuses on **conflict identification, impact analysis, and strategic options** (NOT implementation). + +### Required Structure + +```markdown +# Conflict Resolution Report + +**Session**: WFS-{session-id} +**Generated**: {timestamp} +**Conflict Risk**: {medium|high} +**Total Conflicts**: {count} + +## Executive Summary + +**Overall Assessment**: {summary_paragraph} + +**Severity Distribution**: +- Critical: {count} - Blocking issues requiring immediate resolution +- High: {count} - Significant issues affecting core functionality +- Medium: {count} - Moderate issues with workarounds available + +**Recommended Priority**: {conflict_id_1}, {conflict_id_2}, ... + +--- + +## Conflict Analysis + +### Conflict 1: {conflict_name} +**ID**: CON-001 +**Severity**: Critical | High | Medium +**Category**: Architecture | API | Data Model | Dependency +**Affected Files**: +- {file_1} +- {file_2} + +**Description**: {detailed_conflict_description} + +**Impact Analysis**: +- **Scope**: {which_modules_affected} +- **Backward Compatibility**: {yes/no/partial} +- **Migration Required**: {yes/no} +- **Estimated Effort**: {person-days} + +#### Resolution Strategies + +##### Option 1: {strategy_name} +**Approach**: {implementation_approach} + +**Pros**: +- {advantage_1} +- {advantage_2} + +**Cons**: +- {disadvantage_1} +- {disadvantage_2} + +**Implementation Complexity**: Low | Medium | High +**Risk Level**: Low | Medium | High +**Estimated Effort**: {time_estimate} + +##### Option 2: {strategy_name} +... + +**Recommended Strategy**: Option {N} +**Rationale**: {why_this_option_is_best} + +--- + +## Recommended Actions + +### Priority 1: Address Critical Conflicts +1. {conflict_id}: {brief_action} - {recommended_strategy} +2. ... + +### Priority 2: Resolve High-Severity Issues +1. {conflict_id}: {brief_action} - {recommended_strategy} +2. ... + +### Priority 3: Handle Medium Issues +1. {conflict_id}: {brief_action} - {recommended_strategy} +2. ... + +## Migration Considerations + +**Data Migration**: +- {migration_task_1} +- {migration_task_2} + +**API Versioning**: +- {versioning_strategy} + +**Rollback Strategy**: +- {rollback_plan} + +--- + +## Next Steps + +**Before Implementation**: +1. Review and select resolution strategies +2. Update IMPL_PLAN.md with conflict resolution decisions +3. Validate migration requirements + +**Proceed to**: +- /workflow:plan continue β†’ Proceed with task generation +``` + +### Content Focus +- βœ… Conflict detection with severity classification +- βœ… Multiple resolution strategies per conflict +- βœ… Pros/cons analysis for each strategy +- βœ… Effort and risk estimates +- βœ… Migration considerations +- ❌ Direct code changes or patches +- ❌ Implementation details (save for IMPL_PLAN) +- ❌ Task breakdowns (handled by task generation) + +## Execution Management + +### Error Handling & Recovery +1. **Pre-execution**: Verify conflict_risk warrants execution +2. **Agent Monitoring**: Track agent execution status via Task tool +3. **Validation**: Check CONFLICT_RESOLUTION.md generation on completion +4. **Error Recovery**: + - Agent execution failure β†’ report error, check agent logs + - Missing output file β†’ retry agent execution once + - CLI tool failure β†’ fallback to Claude analysis +5. **Graceful Degradation**: If all analysis methods fail, generate basic conflict report from heuristics + +## Integration & Success Criteria + +### Input/Output Interface +**Input**: +- `--session` (required): Session ID (e.g., WFS-auth) +- `--context` (required): Context package path +- Context package must have conflict_risk β‰₯ medium + +**Output**: +- Single file: `CONFLICT_RESOLUTION.md` at `.workflow/{session_id}/.process/` +- No code modifications + +### Quality & Success Validation +**Quality Checks**: Completeness, strategy diversity, actionability + +**Success Criteria**: +- βœ… Conflict detection complete (all categories scanned) +- βœ… Minimum 2 resolution strategies per conflict +- βœ… Clear pros/cons for each strategy +- βœ… Effort and risk estimates provided +- βœ… Recommended strategy with rationale +- βœ… Migration considerations documented +- βœ… CLI-powered analysis (with fallback handling) +- βœ… Robust error handling (validation, retry, degradation) +- βœ… Agent execution log saved to session chat directory + +## Related Commands +- `/context:gather` - Generates conflict_detection data required by this command +- `/workflow:plan` - Automatically calls this command when conflict_risk β‰₯ medium +- `/task:create` - Creates tasks based on selected resolution strategies diff --git a/.claude/commands/workflow/tools/context-gather.md b/.claude/commands/workflow/tools/context-gather.md index 6d7bf632..b7c25b36 100644 --- a/.claude/commands/workflow/tools/context-gather.md +++ b/.claude/commands/workflow/tools/context-gather.md @@ -158,6 +158,36 @@ Task( #### Step 4: Context Packaging Generate standardized context-package.json following the format below +#### Step 5: Conflict Detection & Risk Assessment +**Purpose**: Analyze existing codebase to determine conflict risk level + +1. **Existing Code Detection** + - Count relevant existing source files discovered in Step 2 + - Identify modules that overlap with task scope + - Flag existence of implementations related to task keywords + +2. **Architecture Analysis** + - Compare task requirements with existing architecture patterns + - Identify potential architectural changes required + - Detect breaking changes to current structure + +3. **API & Dependency Analysis** + - Check for existing API endpoints/contracts that may change + - Identify shared dependencies and interface changes + - Detect potential breaking changes to public APIs + +4. **Data Model Analysis** + - Identify existing data models/schemas in task scope + - Check for schema modification requirements + - Detect potential data migration needs + +5. **Risk Level Calculation** + Calculate conflict_risk based on: + - **none**: No existing code, new feature/module + - **low**: < 5 existing files, minimal changes + - **medium**: 5-15 existing files OR architectural changes OR API changes + - **high**: >15 existing files OR data model changes OR breaking changes + ### Required Output **Output Location**: \`.workflow/{session-id}/.process/context-package.json\` @@ -222,6 +252,23 @@ Generate standardized context-package.json following the format below "docs_files": 4, "config_files": 2, "test_files": 1 + }, + "conflict_detection": { + "conflict_risk": "medium", + "existing_files": [ + "src/auth/AuthService.ts", + "src/models/User.ts", + "src/middleware/auth.ts" + ], + "has_existing_code": true, + "affected_modules": ["auth", "user-model"], + "detection_criteria": { + "existing_code_count": 8, + "architecture_changes": false, + "api_changes": true, + "data_model_changes": false + }, + "risk_rationale": "Medium risk due to existing auth code and potential API changes" } } \`\`\` diff --git a/.claude/commands/workflow/tools/task-generate-agent.md b/.claude/commands/workflow/tools/task-generate-agent.md index 134949e1..3e2be872 100644 --- a/.claude/commands/workflow/tools/task-generate-agent.md +++ b/.claude/commands/workflow/tools/task-generate-agent.md @@ -301,7 +301,7 @@ Before completion, verify: Generate all three documents and report completion status: - Task JSON files created: N files -- Artifacts integrated: synthesis-spec, topic-framework, N role analyses +- Artifacts integrated: synthesis-spec, guidance-specification, N role analyses - MCP enhancements: code-index, exa-research - Session ready for execution: /workflow:execute ` diff --git a/.claude/commands/workflow/tools/task-generate-tdd.md b/.claude/commands/workflow/tools/task-generate-tdd.md index 1f55fcd4..cbffd438 100644 --- a/.claude/commands/workflow/tools/task-generate-tdd.md +++ b/.claude/commands/workflow/tools/task-generate-tdd.md @@ -79,7 +79,7 @@ Generate TDD-specific tasks from analysis results with complete Red-Green-Refact 3. **Artifact Discovery** - If artifact inventory in memory β†’ Skip scanning - Else: Scan `.workflow/{session_id}/.brainstorming/` directory - - Detect: synthesis-specification.md, topic-framework.md, role analyses + - Detect: role analysis documents, guidance-specification.md, role analyses ### Phase 2: TDD Task JSON Generation @@ -283,7 +283,7 @@ tdd_workflow: true ## 3. Brainstorming Artifacts Reference - Artifact Usage Strategy - - synthesis-specification.md (primary reference) + - role analysis documents (primary reference) - test-context-package.json (test patterns) - context-package.json (smart context) - ANALYSIS_RESULTS.md (technical analysis) diff --git a/.claude/commands/workflow/tools/task-generate.md b/.claude/commands/workflow/tools/task-generate.md index c3630dcd..c0666111 100644 --- a/.claude/commands/workflow/tools/task-generate.md +++ b/.claude/commands/workflow/tools/task-generate.md @@ -38,7 +38,7 @@ When the `--cli-execute` flag is used, each step in `implementation_approach` ** This command is built on a set of core principles to ensure efficient and reliable task generation. - **Analysis-Driven**: All generated tasks originate from `ANALYSIS_RESULTS.md`, ensuring a direct link between analysis and implementation -- **Artifact-Aware**: Automatically detects and integrates brainstorming outputs (`synthesis-specification.md`, role analyses) to enrich task context +- **Artifact-Aware**: Automatically detects and integrates brainstorming outputs (role analyses, guidance-specification.md) to enrich task context - **Context-Rich**: Embeds comprehensive context (requirements, focus paths, acceptance criteria, artifact references) directly into each task JSON - **Flow-Control Ready**: Pre-defines clear execution sequence (`pre_analysis`, `implementation_approach`) within each task - **Memory-First**: Prioritizes using documents already loaded in conversation memory to avoid redundant file operations @@ -53,7 +53,7 @@ The command follows a streamlined, three-step process to convert analysis into e The process begins by gathering all necessary inputs. It follows a **Memory-First Rule**, skipping file reads if documents are already in the conversation memory. 1. **Session Validation**: Loads and validates the session from `.workflow/{session_id}/workflow-session.json`. 2. **Analysis Loading**: Reads the primary input, `.workflow/{session_id}/.process/ANALYSIS_RESULTS.md`. -3. **Artifact Discovery**: Scans the `.workflow/{session_id}/.brainstorming/` directory to find `synthesis-specification.md`, `topic-framework.md`, and various role analyses. +3. **Artifact Discovery**: Scans the `.workflow/{session_id}/.brainstorming/` directory to find `guidance-specification.md` and various role analyses ([role]/analysis*.md). ### Step 2: Task Decomposition & Grouping Once all inputs are loaded, the command analyzes the tasks defined in the analysis results and groups them based on shared context. @@ -188,9 +188,9 @@ This enhanced 5-field schema embeds all necessary context, artifacts, and execut "shared_context": {"tech_stack": [], "conventions": []}, "artifacts": [ { - "path": ".workflow/WFS-[session]/.brainstorming/synthesis-specification.md", + "path": ".workflow/WFS-[session]/.brainstorming/[role-name]/analysis*.md", "priority": "highest", - "usage": "Primary requirement source - use for consolidated requirements and cross-role alignment" + "usage": "Role-specific insights and requirements from brainstorming (may have multiple files per role: analysis.md OR analysis-1/2/3.md). Common roles: product-manager (user stories, business requirements), system-architect (ADRs, APIs, architecture), ui-designer (design tokens, layouts), data-architect (data models, schemas), ux-expert (user journeys)" }, { "path": ".workflow/WFS-[session]/.process/ANALYSIS_RESULTS.md", @@ -203,13 +203,8 @@ This enhanced 5-field schema embeds all necessary context, artifacts, and execut "usage": "Smart context with focus paths, module structure, dependency graph, existing patterns. Use for: environment setup, dependency resolution, pattern discovery" }, { - "path": ".workflow/WFS-[session]/.brainstorming/[role-name]/analysis*.md", - "priority": "high", - "usage": "Technical/design/business details from specific roles (may have multiple files: analysis.md OR analysis-1/2/3.md). Common roles: system-architect (ADRs, APIs, caching), ui-designer (design tokens, layouts), product-manager (user stories, metrics)" - }, - { - "path": ".workflow/WFS-[session]/.brainstorming/topic-framework.md", - "priority": "low", + "path": ".workflow/WFS-[session]/.brainstorming/guidance-specification.md", + "priority": "medium", "usage": "Discussion context and framework structure" } ] @@ -217,19 +212,20 @@ This enhanced 5-field schema embeds all necessary context, artifacts, and execut "flow_control": { "pre_analysis": [ { - "step": "load_synthesis_specification", - "action": "Load consolidated synthesis specification", + "step": "load_role_analyses", + "action": "Load role analysis documents from brainstorming", "commands": [ - "bash(ls .workflow/WFS-[session]/.brainstorming/synthesis-specification.md 2>/dev/null || echo 'not found')", - "Read(.workflow/WFS-[session]/.brainstorming/synthesis-specification.md)" + "bash(ls .workflow/WFS-[session]/.brainstorming/*/analysis*.md 2>/dev/null || echo 'not found')", + "Glob(.workflow/WFS-[session]/.brainstorming/*/analysis*.md)", + "Read(each discovered role analysis file)" ], - "output_to": "synthesis_specification", + "output_to": "role_analyses", "on_error": "skip_optional" }, { "step": "load_role_analysis_artifacts", "action": "Load role-specific analysis documents for technical details (supports multiple files per role)", - "note": "These artifacts contain implementation details not in synthesis. Consult when needing: API schemas, caching configs, design tokens, ADRs, performance metrics. Each role may have analysis.md OR analysis-1/2/3.md.", + "note": "These artifacts contain role-specific implementation details. Consult when needing: API schemas, caching configs, design tokens, ADRs, performance metrics. Each role may have analysis.md OR analysis-1/2/3.md.", "commands": [ "bash(find .workflow/WFS-[session]/.brainstorming/ -name 'analysis*.md' 2>/dev/null | sort | head -24)", "Read(.workflow/WFS-[session]/.brainstorming/system-architect/analysis.md)", @@ -265,7 +261,7 @@ This enhanced 5-field schema embeds all necessary context, artifacts, and execut "action": "Analyze existing code patterns and identify modification targets", "commands": [ "bash(cd \"[focus_paths]\")", - "bash(gemini \"PURPOSE: Identify modification targets TASK: Analyze '[title]' and locate specific files/functions/lines to modify CONTEXT: [synthesis_specification] [individual_artifacts] EXPECTED: Code locations in format 'file:function:lines' RULES: Prioritize synthesis-specification.md, identify exact modification points\")" + "bash(gemini \"PURPOSE: Identify modification targets TASK: Analyze '[title]' and locate specific files/functions/lines to modify CONTEXT: [role_analyses] [individual_artifacts] EXPECTED: Code locations in format 'file:function:lines' RULES: Consult role analyses for requirements, identify exact modification points\")" ], "output_to": "task_context_with_targets", "on_error": "fail" @@ -274,23 +270,23 @@ This enhanced 5-field schema embeds all necessary context, artifacts, and execut "implementation_approach": [ { "step": 1, - "title": "Implement task following synthesis specification", - "description": "Implement '[title]' following this priority: 1) synthesis-specification.md (primary requirements), 2) ANALYSIS_RESULTS.md (technical guidance and risk mitigation from planning phase), 3) context-package.json (smart context and patterns), 4) role artifacts (detailed specs). Consult ANALYSIS_RESULTS.md for optimization strategies, performance considerations, and architecture review insights before implementation.", + "title": "Implement task following role analyses and technical guidance", + "description": "Implement '[title]' following this priority: 1) role analysis.md files (requirements and design specs from brainstorming), 2) ANALYSIS_RESULTS.md (technical guidance and risk mitigation from planning phase), 3) context-package.json (smart context and patterns). Consult ANALYSIS_RESULTS.md for optimization strategies, performance considerations, and architecture review insights before implementation.", "modification_points": [ - "Apply consolidated requirements from synthesis-specification.md", + "Apply requirements from role analysis documents", "Follow technical guidelines from ANALYSIS_RESULTS.md", "Use context-package.json for focus paths and dependency resolution", - "Consult role artifacts for implementation details when needed", + "Consult specific role artifacts for implementation details when needed", "Integrate with existing patterns" ], "logic_flow": [ - "Load synthesis specification (requirements baseline)", + "Load role analyses (requirements and design decisions from brainstorming)", "Load ANALYSIS_RESULTS.md (technical guidance and risk mitigation strategies)", "Load context-package.json (smart context: focus paths, dependencies, existing patterns)", - "Extract requirements and design decisions", + "Extract requirements and design decisions from role documents", "Review technical analysis and optimization strategies from ANALYSIS_RESULTS.md", "Identify modification targets using context package", - "Implement following specification and technical guidance", + "Implement following role requirements and technical guidance", "Apply optimization patterns from ANALYSIS_RESULTS.md", "Consult role artifacts for detailed specifications when needed", "Validate against acceptance criteria" @@ -337,10 +333,10 @@ Core requirements, objectives, technical approach summary (2-3 paragraphs max). ### CCW Workflow Context **Phase Progression**: -- βœ… Phase 1: Brainstorming (synthesis-specification.md generated) +- βœ… Phase 1: Brainstorming (role analyses clarified and refined) - βœ… Phase 2: Context Gathering (context-package.json: {N} files, {M} modules analyzed) - βœ… Phase 3: Enhanced Analysis (ANALYSIS_RESULTS.md: Gemini/Qwen/Codex parallel insights) -- βœ… Phase 4: Concept Verification ({X} clarifications answered, synthesis updated | skipped) +- βœ… Phase 4: Concept Verification (integrated in brainstorming phase | skipped) - ⏳ Phase 5: Action Planning (current phase - generating IMPL_PLAN.md) **Quality Gates**: @@ -378,12 +374,12 @@ Core requirements, objectives, technical approach summary (2-3 paragraphs max). ## 3. Brainstorming Artifacts Reference ### Artifact Usage Strategy -**Primary Reference (synthesis-specification.md)**: -- **What**: Comprehensive implementation blueprint from multi-role synthesis -- **When**: Every task references this first for requirements and design decisions -- **How**: Extract architecture decisions, UI/UX patterns, functional requirements, non-functional requirements -- **Priority**: Authoritative - overrides role-specific analyses when conflicts arise -- **CCW Value**: Consolidates insights from all brainstorming roles into single source of truth +**Primary Reference (Role Analyses)**: +- **What**: Role-specific analyses from brainstorming phase providing multi-perspective insights +- **When**: Every task references relevant role analyses for requirements and design decisions +- **How**: Extract requirements, architecture decisions, UI/UX patterns from applicable role documents +- **Priority**: Collective authoritative source - multiple role perspectives provide comprehensive coverage +- **CCW Value**: Maintains role-specific expertise while enabling cross-role integration during planning **Context Intelligence (context-package.json)**: - **What**: Smart context gathered by CCW's context-gather phase @@ -393,25 +389,27 @@ Core requirements, objectives, technical approach summary (2-3 paragraphs max). **Technical Analysis (ANALYSIS_RESULTS.md)**: - **What**: Gemini/Qwen/Codex parallel analysis results -- **Content**: Optimization strategies, risk assessment, architecture review, implementation patterns +- **Content**: Optimization strategies, risk assessment, architecture review, implementation patterns, cross-role synthesis - **Usage**: Referenced in task planning for technical guidance and risk mitigation -- **CCW Value**: Multi-model parallel analysis providing comprehensive technical intelligence +- **CCW Value**: Multi-model parallel analysis providing comprehensive technical intelligence and cross-role integration -### Integrated Specifications (Highest Priority) -- **synthesis-specification.md**: Comprehensive implementation blueprint - - Contains: Architecture design, UI/UX guidelines, functional/non-functional requirements, implementation roadmap, risk assessment +### Role Analysis Documents (Highest Priority) +Role analyses provide specialized perspectives on the implementation: +- **system-architect/analysis.md**: Architecture design, ADRs, API specifications, caching strategies +- **ui-designer/analysis.md**: Design tokens, layout specifications, component patterns +- **ux-expert/analysis.md**: User journeys, interaction flows, accessibility requirements +- **guidance-specification/analysis.md**: Product vision, user stories, business requirements, success metrics +- **data-architect/analysis.md**: Data models, schemas, database design, migration strategies +- **api-designer/analysis.md**: API contracts, endpoint specifications, integration patterns ### Supporting Artifacts (Reference) - **topic-framework.md**: Role-specific discussion points and analysis framework -- **system-architect/analysis.md**: Detailed architecture specifications -- **ui-designer/analysis.md**: Layout and component specifications -- **product-manager/analysis.md**: Product vision and user stories **Artifact Priority in Development**: -1. synthesis-specification.md (primary reference for all tasks) -2. context-package.json (smart context for execution environment) -3. ANALYSIS_RESULTS.md (technical analysis and optimization strategies) -4. Role-specific analyses (fallback for detailed specifications) +1. Role analysis.md files (primary requirements and design specs from brainstorming) +2. ANALYSIS_RESULTS.md (technical analysis, optimization strategies, and cross-role synthesis from planning) +3. context-package.json (smart context for execution environment) +4. topic-framework.md (discussion framework structure) ## 4. Implementation Strategy @@ -428,7 +426,7 @@ Core requirements, objectives, technical approach summary (2-3 paragraphs max). ### Architectural Approach **Key Architecture Decisions**: -- [ADR references from synthesis] +- [ADR references from role analyses] - [Justification for architecture patterns] **Integration Strategy**: @@ -520,7 +518,7 @@ Core requirements, objectives, technical approach summary (2-3 paragraphs max). ## 8. Success Criteria **Functional Completeness**: -- [ ] All requirements from synthesis-specification.md implemented +- [ ] All requirements from role analysis documents implemented - [ ] All acceptance criteria from task.json files met **Technical Quality**: @@ -534,7 +532,7 @@ Core requirements, objectives, technical approach summary (2-3 paragraphs max). - [ ] Documentation complete **Business Metrics**: -- [ ] [Key business metrics from synthesis] +- [ ] [Key business metrics from role analyses] ``` ### 6.3. TODO_LIST.md Structure @@ -567,10 +565,9 @@ The command organizes outputs into a standard directory structure. β”‚ β”œβ”€β”€ IMPL-1.json # Container task β”‚ β”œβ”€β”€ IMPL-1.1.json # Leaf task with flow_control β”‚ └── IMPL-1.2.json # Leaf task with flow_control -β”œβ”€β”€ .brainstorming/ # Input artifacts -β”‚ β”œβ”€β”€ synthesis-specification.md +β”œβ”€β”€ .braguidance-specification # Input artifacts β”‚ β”œβ”€β”€ topic-framework.md -β”‚ └── {role}/analysis.md +β”‚ └── {role}/analysis*.md # Role analyses (may have multiple files per role) └── .process/ β”œβ”€β”€ ANALYSIS_RESULTS.md # Input from concept-enhanced └── context-package.json # Input from context-gather @@ -580,28 +577,28 @@ The command organizes outputs into a standard directory structure. The command intelligently detects and integrates artifacts from the `.brainstorming/` directory. #### Artifact Priority -1. **synthesis-specification.md** (highest): Comprehensive implementation blueprint from brainstorming synthesis -2. **ANALYSIS_RESULTS.md** (critical): Technical analysis, risk assessment, and optimization strategies from planning phase (generated by concept-enhanced) -3. **context-package.json** (critical): Smart context with focus paths, module structure, and dependency graph from planning phase (generated by context-gather) +1. **role/analysis*.md** (highest): Role-specific requirements and design specs from brainstorming (product-manager, system-architect, ui-designer, etc.) +2. **ANALYSIS_RESULTS.md** (critical): Technical analysis, risk assessment, optimization strategies, and cross-role synthesis from planning phase (generated by concept-enhanced) +3. **guidance-specification.json** (critical): Smart context with focus paths, module structure, and dependency graph from planning phase (generated by context-gather) 4. **topic-framework.md** (medium): Discussion framework structure from brainstorming -5. **role/analysis.md** (low): Individual role-based analyses for detailed specifications #### Artifact-Task Mapping Artifacts are mapped to tasks based on their relevance to the task's domain. -- **synthesis-specification.md**: Included in all tasks as the primary reference. -- **ui-designer/analysis.md**: Mapped to UI/Frontend tasks. -- **system-architect/analysis.md**: Mapped to Architecture/Backend tasks. -- **subject-matter-expert/analysis.md**: Mapped to tasks related to domain logic or standards. -- **data-architect/analysis.md**: Mapped to tasks involving data models or APIs. +- **Role analysis.md files**: Primary requirements source - all relevant role analyses included based on task type +- **ui-designer/analysis.md**: Mapped to UI/Frontend tasks for design tokens, layouts, components +- **system-architect/analysis.md**: Mapped to Architecture/Backend tasks for ADRs, APIs, patterns +- **subject-matter-expert/analysis.md**: Mapped to tasks related to domain logic or standards +- **data-architect/analysis.md**: Mapped to tasks involving data models, schemas, or APIs +- **product-manager/analysis.md**: Mapped to all tasks for business requirements and user stories -This ensures that each task has access to the most relevant and detailed specifications, from the high-level synthesis down to the role-specific details. +This ensures that each task has access to the most relevant and detailed specifications from role-specific analyses. ## 8. CLI Execute Mode Details When using `--cli-execute`, each step in `implementation_approach` includes a `command` field with the execution command. **Key Points**: - **Sequential Steps**: Steps execute in order defined in `implementation_approach` array -- **Context Delivery**: Each codex command receives context via CONTEXT field: `@{.workflow/{session}/.process/context-package.json}` and `@{.workflow/{session}/.brainstorming/synthesis-specification.md}` +- **Context Delivery**: Each codex command receives context via CONTEXT field: `@{.workflow/{session}/.process/context-package.json}` and role analysis files from `.brainstorming/*/analysis*.md` - **Multi-Step Tasks**: First step provides full context, subsequent steps use `resume --last` to maintain session continuity - **Step Dependencies**: Later steps reference outputs from earlier steps via `depends_on` field @@ -623,10 +620,10 @@ When using `--cli-execute`, each step in `implementation_approach` includes a `c "flow_control": { "pre_analysis": [ { - "step": "load_synthesis", - "action": "Load synthesis specification for requirements", - "commands": ["Read(.workflow/WFS-session/.brainstorming/synthesis-specification.md)"], - "output_to": "synthesis_spec", + "step": "load_role_analyses", + "action": "Load role analyses for requirements", + "commands": ["Read(.workflow/WFS-session/.brainstorming/*/analysis*.md)"], + "output_to": "role_analyses", "on_error": "fail" }, { @@ -641,7 +638,7 @@ When using `--cli-execute`, each step in `implementation_approach` includes a `c { "step": 1, "title": "Implement JWT-based authentication", - "description": "Create authentication module using JWT following [synthesis_spec] requirements and [context_pkg] patterns", + "description": "Create authentication module using JWT following [role_analyses] requirements and [context_pkg] patterns", "modification_points": [ "Create auth service with JWT generation", "Implement login endpoint with credential validation", @@ -676,10 +673,10 @@ When using `--cli-execute`, each step in `implementation_approach` includes a `c "flow_control": { "pre_analysis": [ { - "step": "load_synthesis", - "action": "Load synthesis specification", - "commands": ["Read(.workflow/WFS-session/.brainstorming/synthesis-specification.md)"], - "output_to": "synthesis_spec", + "step": "load_role_analyses", + "action": "Load role analyses", + "commands": ["Read(.workflow/WFS-session/.brainstorming/*/analysis*.md)"], + "output_to": "role_analyses", "on_error": "fail" } ], @@ -688,7 +685,7 @@ When using `--cli-execute`, each step in `implementation_approach` includes a `c "step": 1, "title": "Implement authentication with Codex", "description": "Create JWT-based authentication module", - "command": "bash(codex -C src/auth --full-auto exec \"PURPOSE: Implement user authentication TASK: JWT-based auth with login/registration MODE: auto CONTEXT: @{.workflow/WFS-session/.process/context-package.json} @{.workflow/WFS-session/.brainstorming/synthesis-specification.md} EXPECTED: Complete auth module with tests RULES: Follow synthesis specification\" --skip-git-repo-check -s danger-full-access)", + "command": "bash(codex -C src/auth --full-auto exec \"PURPOSE: Implement user authentication TASK: JWT-based auth with login/registration MODE: auto CONTEXT: @{.workflow/WFS-session/.process/context-package.json} @{.workflow/WFS-session/.brainstorming/*/analysis*.md} EXPECTED: Complete auth module with tests RULES: Follow role analyses\" --skip-git-repo-check -s danger-full-access)", "modification_points": ["Create auth service", "Implement endpoints", "Add JWT middleware"], "logic_flow": ["Validate credentials", "Generate JWT", "Return token"], "depends_on": [], @@ -715,10 +712,10 @@ When using `--cli-execute`, each step in `implementation_approach` includes a `c "pre_analysis": [ { "step": "load_context", - "action": "Load context and synthesis", + "action": "Load context and role analyses", "commands": [ "Read(.workflow/WFS-session/.process/context-package.json)", - "Read(.workflow/WFS-session/.brainstorming/synthesis-specification.md)" + "Read(.workflow/WFS-session/.brainstorming/*/analysis*.md)" ], "output_to": "full_context", "on_error": "fail" @@ -729,7 +726,7 @@ When using `--cli-execute`, each step in `implementation_approach` includes a `c "step": 1, "title": "Create RBAC models", "description": "Define role and permission data models", - "command": "bash(codex -C src/auth --full-auto exec \"PURPOSE: Create RBAC models TASK: Role and permission models MODE: auto CONTEXT: @{.workflow/WFS-session/.process/context-package.json} @{.workflow/WFS-session/.brainstorming/synthesis-specification.md} EXPECTED: Models with migrations RULES: Follow synthesis spec\" --skip-git-repo-check -s danger-full-access)", + "command": "bash(codex -C src/auth --full-auto exec \"PURPOSE: Create RBAC models TASK: Role and permission models MODE: auto CONTEXT: @{.workflow/WFS-session/.process/context-package.json} @{.workflow/WFS-session/.brainstorming/*/analysis*.md} EXPECTED: Models with migrations RULES: Follow role analyses\" --skip-git-repo-check -s danger-full-access)", "modification_points": ["Define role model", "Define permission model", "Create migrations"], "logic_flow": ["Design schema", "Implement models", "Generate migrations"], "depends_on": [], diff --git a/.claude/commands/workflow/ui-design/explore-auto.md b/.claude/commands/workflow/ui-design/explore-auto.md index 7e6708bc..c707a88f 100644 --- a/.claude/commands/workflow/ui-design/explore-auto.md +++ b/.claude/commands/workflow/ui-design/explore-auto.md @@ -205,7 +205,7 @@ ELSE IF --prompt: target_source = "prompt_analysis" # Step 4: Session synthesis -ELSE IF --session AND exists(synthesis-specification.md): +ELSE IF --session AND exists(role analysis documents): target_list = extract_targets_from_synthesis(); target_type = "page"; target_source = "synthesis" # Step 5: Fallback diff --git a/.claude/commands/workflow/ui-design/style-extract.md b/.claude/commands/workflow/ui-design/style-extract.md index 411beee6..17782901 100644 --- a/.claude/commands/workflow/ui-design/style-extract.md +++ b/.claude/commands/workflow/ui-design/style-extract.md @@ -154,7 +154,7 @@ IF exists: SKIP to completion ### Step 2: Load Project Context (Explore Mode) ```bash # Load brainstorming context if available -bash(test -f {base_path}/.brainstorming/synthesis-specification.md && cat it) +bash(test -f {base_path}/.brainstorming/role analysis documents && cat it) ``` ### Step 3: Generate Design Direction Options (Agent Task 1) @@ -541,7 +541,7 @@ bash(cat {base_path}/style-extraction/style-1/design-tokens.json | grep -q "colo ### File Operations ```bash # Load brainstorming context -bash(test -f .brainstorming/synthesis-specification.md && cat it) +bash(test -f .brainstorming/role analysis documents && cat it) # Create directories bash(mkdir -p {base_path}/style-extraction/style-{{1..3}}) diff --git a/.claude/commands/workflow/ui-design/update.md b/.claude/commands/workflow/ui-design/update.md index 45ddb9cc..01979e9d 100644 --- a/.claude/commands/workflow/ui-design/update.md +++ b/.claude/commands/workflow/ui-design/update.md @@ -15,7 +15,7 @@ Synchronize finalized design system references to brainstorming artifacts, prepa - **Reference-Only Updates**: Use @ references, no content duplication - **Main Claude Execution**: Direct updates by main Claude (no Agent handoff) -- **Synthesis Alignment**: Update synthesis-specification.md UI/UX Guidelines section +- **Synthesis Alignment**: Update role analysis documents UI/UX Guidelines section - **Plan-Ready Output**: Ensure design artifacts discoverable by task-generate - **Minimal Reading**: Verify file existence, don't read design content @@ -50,8 +50,8 @@ REPORT: "Found {count} design artifacts, {prototype_count} prototypes" ### Phase 1.1: Memory Check (Skip if Already Updated) ```bash -# Check if synthesis-specification.md contains current design run reference -synthesis_spec_path = ".workflow/WFS-{session}/.brainstorming/synthesis-specification.md" +# Check if role analysis documents contains current design run reference +synthesis_spec_path = ".workflow/WFS-{session}/.brainstorming/role analysis documents" current_design_run = basename(latest_design) # e.g., "design-run-20250109-143022" IF exists(synthesis_spec_path): @@ -68,7 +68,7 @@ IF exists(synthesis_spec_path): ```bash # Load target brainstorming artifacts (files to be updated) -Read(.workflow/WFS-{session}/.brainstorming/synthesis-specification.md) +Read(.workflow/WFS-{session}/.brainstorming/role analysis documents) IF exists(.workflow/WFS-{session}/.brainstorming/ui-designer/analysis.md): Read(analysis.md) # Optional: Read prototype notes for descriptions (minimal context) @@ -80,7 +80,7 @@ FOR each selected_prototype IN selected_list: ### Phase 3: Update Synthesis Specification -Update `.brainstorming/synthesis-specification.md` with design system references. +Update `.brainstorming/role analysis documents` with design system references. **Target Section**: `## UI/UX Guidelines` @@ -113,7 +113,7 @@ Update `.brainstorming/synthesis-specification.md` with design system references **Implementation**: ```bash # Option 1: Edit existing section -Edit(file_path=".workflow/WFS-{session}/.brainstorming/synthesis-specification.md", +Edit(file_path=".workflow/WFS-{session}/.brainstorming/role analysis documents", old_string="## UI/UX Guidelines\n[existing content]", new_string="## UI/UX Guidelines\n\n[new design reference content]") @@ -168,7 +168,7 @@ Write(file_path=".workflow/WFS-{session}/.brainstorming/ui-designer/style-guide. 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 synthesis-specification.md with design references", status: "completed", activeForm: "Updating synthesis spec"}, + {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"} ]}); ``` @@ -178,7 +178,7 @@ TodoWrite({todos: [ βœ… Design system references updated for session: WFS-{session} Updated artifacts: -βœ“ synthesis-specification.md - UI/UX Guidelines section with @ references +βœ“ role analysis documents - UI/UX Guidelines section with @ references βœ“ ui-designer/style-guide.md - Design system reference guide Design system assets ready for /workflow:plan: @@ -193,12 +193,12 @@ Next: /workflow:plan [--agent] "" **Updated Files**: ``` .workflow/WFS-{session}/.brainstorming/ -β”œβ”€β”€ synthesis-specification.md # Updated with UI/UX Guidelines section +β”œβ”€β”€ role analysis documents # Updated with UI/UX Guidelines section └── ui-designer/ └── style-guide.md # New or updated design reference guide ``` -**@ Reference Format** (synthesis-specification.md): +**@ Reference Format** (role analysis documents): ``` @../design-{run_id}/style-extraction/style-1/design-tokens.json @../design-{run_id}/style-extraction/style-1/style-guide.md @@ -217,7 +217,7 @@ Next: /workflow:plan [--agent] "" After this update, `/workflow:plan` will discover design assets through: **Phase 3: Intelligent Analysis** (`/workflow:tools:concept-enhanced`) -- Reads synthesis-specification.md β†’ Discovers @ references β†’ Includes design system context in ANALYSIS_RESULTS.md +- Reads role analysis documents β†’ Discovers @ references β†’ Includes design system context in ANALYSIS_RESULTS.md **Phase 4: Task Generation** (`/workflow:tools:task-generate`) - Reads ANALYSIS_RESULTS.md β†’ Discovers design assets β†’ Includes design system paths in task JSON files @@ -239,7 +239,7 @@ After this update, `/workflow:plan` will discover design assets through: ## Error Handling - **Missing design artifacts**: Error with message "Run /workflow:ui-design:style-extract and /workflow:ui-design:generate first" -- **synthesis-specification.md not found**: Warning, create minimal version with just UI/UX Guidelines +- **role analysis documents not found**: Warning, create minimal version with just UI/UX Guidelines - **ui-designer/ directory missing**: Create directory and file - **Edit conflicts**: Preserve existing content, append or replace only UI/UX Guidelines section - **Invalid prototype names**: Skip invalid entries, continue with valid ones @@ -247,7 +247,7 @@ After this update, `/workflow:plan` will discover design assets through: ## Validation Checks After update, verify: -- [ ] synthesis-specification.md contains UI/UX Guidelines section +- [ ] role analysis documents contains UI/UX Guidelines section - [ ] UI/UX Guidelines include @ references (not content duplication) - [ ] ui-designer/style-guide.md created or updated - [ ] All @ referenced files exist and are accessible @@ -264,7 +264,7 @@ After update, verify: ## Integration Points - **Input**: Design system artifacts from `/workflow:ui-design:style-extract` and `/workflow:ui-design:generate` -- **Output**: Updated synthesis-specification.md, ui-designer/style-guide.md with @ references +- **Output**: Updated role analysis documents, ui-designer/style-guide.md with @ references - **Next Phase**: `/workflow:plan` discovers and utilizes design system through @ references - **Auto Integration**: Automatically triggered by `/workflow:ui-design:auto` workflow diff --git a/.claude/workflows/cli-templates/planning-roles/synthesis-role.md b/.claude/workflows/cli-templates/planning-roles/synthesis-role.md index 26877a6a..29ee2606 100644 --- a/.claude/workflows/cli-templates/planning-roles/synthesis-role.md +++ b/.claude/workflows/cli-templates/planning-roles/synthesis-role.md @@ -1,4 +1,25 @@ -# Synthesis Role Template +# ⚠️ DEPRECATED: Synthesis Role Template + +## DEPRECATION NOTICE + +**This template is DEPRECATED and no longer used.** + +### Why Deprecated +The `/workflow:brainstorm:synthesis` command has been redesigned: +- **Old behavior**: Generated synthesis-specification.md consolidating all role analyses +- **New behavior**: Performs cross-role analysis, identifies ambiguities, interacts with user for clarification, and updates role analysis.md files directly + +### Migration +- **Role analyses are the source of truth**: Each role's analysis.md file is updated directly +- **Planning reads role documents**: The planning phase dynamically reads all role analysis.md files +- **No template needed**: The clarification workflow doesn't require a document template + +### Historical Context +This template was used to guide the generation of synthesis-specification.md from multiple role perspectives. It is preserved for historical reference but should not be used in the new architecture. + +--- + +# Original Template (Historical Reference) ## Purpose Generate comprehensive synthesis-specification.md that consolidates all role perspectives from brainstorming into actionable implementation specification. @@ -18,7 +39,7 @@ Generate comprehensive synthesis-specification.md that consolidates all role per ```markdown # [Topic] - Integrated Implementation Specification -**Framework Reference**: @topic-framework.md | **Generated**: [timestamp] | **Session**: WFS-[topic-slug] +**Framework Reference**: @guidance-specification.md | **Generated**: [timestamp] | **Session**: WFS-[topic-slug] **Source Integration**: All brainstorming role perspectives consolidated **Document Type**: Requirements & Design Specification (WHAT to build) @@ -344,7 +365,7 @@ Document known constraints that affect planning: ### Cross-Role Synthesis Process -1. **Load All Role Analyses**: Read topic-framework.md and all discovered */analysis.md files +1. **Load All Role Analyses**: Read guidance-specification.md and all discovered */analysis.md files 2. **Extract Key Insights**: Identify main recommendations, concerns, and innovations from each role 3. **Identify Consensus Areas**: Find common themes across multiple roles 4. **Document Disagreements**: Capture controversial points where roles differ @@ -371,7 +392,7 @@ Document known constraints that affect planning: Use @ references to link back to source role analyses: - `@role/analysis.md` - Reference entire role analysis - `@role/analysis.md#section` - Reference specific section -- `@topic-framework.md#point-3` - Reference framework discussion point +- `@guidance-specification.md#point-3` - Reference framework discussion point ### Dynamic Role Handling diff --git a/.claude/workflows/cli-templates/prompts/workflow/analysis-results-structure.txt b/.claude/workflows/cli-templates/prompts/workflow/analysis-results-structure.txt index bc05ae1f..163f3279 100644 --- a/.claude/workflows/cli-templates/prompts/workflow/analysis-results-structure.txt +++ b/.claude/workflows/cli-templates/prompts/workflow/analysis-results-structure.txt @@ -187,8 +187,8 @@ Generate ANALYSIS_RESULTS.md with comprehensive solution design and technical an ### Analysis Priority Sources 1. **PRIMARY**: Individual role analysis.md files (system-architect, ui-designer, etc.) - technical details, ADRs, decision context -2. **SECONDARY**: synthesis-specification.md - integrated requirements, cross-role alignment -3. **REFERENCE**: topic-framework.md - discussion context +2. **SECONDARY**: role analysis documents - multi-perspective requirements and design specs +3. **REFERENCE**: guidance-specification.md - discussion context ### Focus Areas - **SOLUTION IMPROVEMENTS**: How to enhance current design diff --git a/.claude/workflows/cli-templates/prompts/workflow/gemini-solution-design.txt b/.claude/workflows/cli-templates/prompts/workflow/gemini-solution-design.txt index 9c4c10e7..1d00878b 100644 --- a/.claude/workflows/cli-templates/prompts/workflow/gemini-solution-design.txt +++ b/.claude/workflows/cli-templates/prompts/workflow/gemini-solution-design.txt @@ -15,12 +15,12 @@ Analyze and design optimal solution with comprehensive architecture evaluation a - Architecture Decision Records (ADRs) - Design decision context and rationale -2. **SECONDARY**: synthesis-specification.md +2. **SECONDARY**: role analysis documents - Integrated requirements across roles - Cross-role alignment and dependencies - Unified feature specifications -3. **REFERENCE**: topic-framework.md +3. **REFERENCE**: guidance-specification.md - Discussion context and background - Initial problem framing @@ -104,8 +104,8 @@ For each target: ### Brainstorm Context If brainstorming artifacts exist: - Prioritize individual role analysis.md files -- Use synthesis-specification.md for integrated view -- Reference topic-framework.md for context +- Use role analysis documents for integrated view +- Reference guidance-specification.md for context ### Codebase Context - Identify similar patterns in existing code diff --git a/.claude/workflows/cli-templates/prompts/workflow/impl-plan-template.txt b/.claude/workflows/cli-templates/prompts/workflow/impl-plan-template.txt index e67f8e58..4d8e376f 100644 --- a/.claude/workflows/cli-templates/prompts/workflow/impl-plan-template.txt +++ b/.claude/workflows/cli-templates/prompts/workflow/impl-plan-template.txt @@ -35,10 +35,10 @@ Core requirements, objectives, technical approach summary (2-3 paragraphs max). ### CCW Workflow Context **Phase Progression**: -- βœ… Phase 1: Brainstorming (synthesis-specification.md generated) +- βœ… Phase 1: Brainstorming (role analyses generated) - βœ… Phase 2: Context Gathering (context-package.json: {N} files, {M} modules analyzed) - βœ… Phase 3: Enhanced Analysis (ANALYSIS_RESULTS.md: Gemini/Qwen/Codex parallel insights) -- βœ… Phase 4: Concept Verification ({X} clarifications answered, synthesis updated | skipped) +- βœ… Phase 4: Concept Verification ({X} clarifications answered, role analyses updated | skipped) - ⏳ Phase 5: Action Planning (current phase - generating IMPL_PLAN.md) **Quality Gates**: @@ -76,12 +76,12 @@ Core requirements, objectives, technical approach summary (2-3 paragraphs max). ## 3. Brainstorming Artifacts Reference ### Artifact Usage Strategy -**Primary Reference (synthesis-specification.md)**: -- **What**: Comprehensive implementation blueprint from multi-role synthesis -- **When**: Every task references this first for requirements and design decisions -- **How**: Extract architecture decisions, UI/UX patterns, functional requirements, non-functional requirements -- **Priority**: Authoritative - overrides role-specific analyses when conflicts arise -- **CCW Value**: Consolidates insights from all brainstorming roles into single source of truth +**Primary Reference (role analyses)**: +- **What**: Role-specific analyses from brainstorming providing multi-perspective insights +- **When**: Every task references relevant role analyses for requirements and design decisions +- **How**: Extract requirements, architecture decisions, UI/UX patterns from applicable role documents +- **Priority**: Collective authoritative source - multiple role perspectives provide comprehensive coverage +- **CCW Value**: Maintains role-specific expertise while enabling cross-role integration during planning **Context Intelligence (context-package.json)**: - **What**: Smart context gathered by CCW's context-gather phase @@ -96,17 +96,17 @@ Core requirements, objectives, technical approach summary (2-3 paragraphs max). - **CCW Value**: Multi-model parallel analysis providing comprehensive technical intelligence ### Integrated Specifications (Highest Priority) -- **synthesis-specification.md**: Comprehensive implementation blueprint +- **role analyses**: Comprehensive implementation blueprint - Contains: Architecture design, UI/UX guidelines, functional/non-functional requirements, implementation roadmap, risk assessment ### Supporting Artifacts (Reference) -- **topic-framework.md**: Role-specific discussion points and analysis framework +- **guidance-specification.md**: Role-specific discussion points and analysis framework - **system-architect/analysis.md**: Detailed architecture specifications - **ui-designer/analysis.md**: Layout and component specifications - **product-manager/analysis.md**: Product vision and user stories **Artifact Priority in Development**: -1. synthesis-specification.md (primary reference for all tasks) +1. role analyses (primary reference for all tasks) 2. context-package.json (smart context for execution environment) 3. ANALYSIS_RESULTS.md (technical analysis and optimization strategies) 4. Role-specific analyses (fallback for detailed specifications) @@ -126,7 +126,7 @@ Core requirements, objectives, technical approach summary (2-3 paragraphs max). ### Architectural Approach **Key Architecture Decisions**: -- [ADR references from synthesis] +- [ADR references from role analyses] - [Justification for architecture patterns] **Integration Strategy**: @@ -218,7 +218,7 @@ Core requirements, objectives, technical approach summary (2-3 paragraphs max). ## 8. Success Criteria **Functional Completeness**: -- [ ] All requirements from synthesis-specification.md implemented +- [ ] All requirements from role analyses implemented - [ ] All acceptance criteria from task.json files met **Technical Quality**: @@ -232,7 +232,7 @@ Core requirements, objectives, technical approach summary (2-3 paragraphs max). - [ ] Documentation complete **Business Metrics**: -- [ ] [Key business metrics from synthesis] +- [ ] [Key business metrics from role analyses] ## Template Usage Guidelines @@ -269,7 +269,7 @@ Core requirements, objectives, technical approach summary (2-3 paragraphs max). - Create dependency graph visualization 7. **Set Success Criteria**: - - Extract from synthesis-specification.md + - Extract from role analyses - Include measurable metrics - Define quality gates diff --git a/.claude/workflows/cli-templates/prompts/workflow/task-json-agent-mode.txt b/.claude/workflows/cli-templates/prompts/workflow/task-json-agent-mode.txt index f58d8455..5cb3ba58 100644 --- a/.claude/workflows/cli-templates/prompts/workflow/task-json-agent-mode.txt +++ b/.claude/workflows/cli-templates/prompts/workflow/task-json-agent-mode.txt @@ -34,8 +34,8 @@ Task JSON Schema - Agent Mode (No Command Field) "flow_control": { "pre_analysis": [ { - "step": "load_synthesis_specification", - "action": "Load consolidated synthesis specification", + "step": "load_role_analyses_specification", + "action": "Load consolidated role analyses", "commands": [ "Read({synthesis_spec_path})" ], @@ -62,16 +62,16 @@ Task JSON Schema - Agent Mode (No Command Field) "implementation_approach": [ { "step": 1, - "title": "Implement task following synthesis specification", - "description": "Implement '{title}' following [synthesis_specification] requirements and [context_pkg] patterns. Use synthesis-specification.md as primary source, consult artifacts for technical details.", + "title": "Implement task following role analyses", + "description": "Implement '{title}' following [synthesis_specification] requirements and [context_pkg] patterns. Use role analyses as primary source, consult artifacts for technical details.", "modification_points": [ - "Apply consolidated requirements from synthesis-specification.md", + "Apply consolidated requirements from role analyses", "Follow technical guidelines from synthesis", "Consult artifacts for implementation details when needed", "Integrate with existing patterns" ], "logic_flow": [ - "Load synthesis specification and context package", + "Load role analyses and context package", "Analyze existing patterns from [codebase_structure]", "Implement following specification", "Consult artifacts for technical details when needed", diff --git a/.claude/workflows/workflow-architecture.md b/.claude/workflows/workflow-architecture.md index a1115e21..6b108af4 100644 --- a/.claude/workflows/workflow-architecture.md +++ b/.claude/workflows/workflow-architecture.md @@ -132,11 +132,11 @@ All task files use this unified 5-field schema with optional artifacts enhanceme }, "artifacts": [ { - "type": "synthesis_specification", - "source": "brainstorm_synthesis", - "path": ".workflow/WFS-session/.brainstorming/synthesis-specification.md", + "type": "role_analyses", + "source": "brainstorm_clarification", + "path": ".workflow/WFS-session/.brainstorming/*/analysis*.md", "priority": "highest", - "contains": "complete_integrated_specification" + "contains": "role_specific_requirements_and_design" } ] }, @@ -241,15 +241,15 @@ Optional field referencing brainstorming outputs for task execution: ```json "artifacts": [ { - "type": "synthesis_specification|topic_framework|individual_role_analysis", - "source": "brainstorm_synthesis|brainstorm_framework|brainstorm_roles", + "type": "role_analyses|topic_framework|individual_role_analysis", + "source": "brainstorm_clarification|brainstorm_framework|brainstorm_roles", "path": ".workflow/WFS-session/.brainstorming/document.md", "priority": "highest|high|medium|low" } ] ``` -**Types & Priority**: synthesis_specification (highest) β†’ topic_framework (medium) β†’ individual_role_analysis (low) +**Types & Priority**: role_analyses (highest) β†’ topic_framework (medium) β†’ individual_role_analysis (low) #### Flow Control Configuration The **flow_control** field manages task execution through structured sequential steps. For complete format specifications and usage guidelines, see [Flow Control Format Guide](#flow-control-format-guide) below. @@ -296,7 +296,7 @@ The `[FLOW_CONTROL]` marker indicates that a task or prompt contains flow contro 1. **load_topic_framework** - Action: Load structured topic discussion framework - - Command: Read(.workflow/WFS-{session}/.brainstorming/topic-framework.md) + - Command: Read(.workflow/WFS-{session}/.brainstorming/guidance-specification.md) - Output: topic_framework 2. **load_role_template** @@ -332,13 +332,14 @@ The `[FLOW_CONTROL]` marker indicates that a task or prompt contains flow contro "flow_control": { "pre_analysis": [ { - "step": "load_synthesis_specification", - "action": "Load consolidated synthesis specification", + "step": "load_role_analyses", + "action": "Load role analysis documents from brainstorming", "commands": [ - "bash(ls .workflow/WFS-{session}/.brainstorming/synthesis-specification.md 2>/dev/null || echo 'not found')", - "Read(.workflow/WFS-{session}/.brainstorming/synthesis-specification.md)" + "bash(ls .workflow/WFS-{session}/.brainstorming/*/analysis*.md 2>/dev/null || echo 'not found')", + "Glob(.workflow/WFS-{session}/.brainstorming/*/analysis*.md)", + "Read(each discovered role analysis file)" ], - "output_to": "synthesis_specification", + "output_to": "role_analyses", "on_error": "skip_optional" }, { @@ -352,14 +353,14 @@ The `[FLOW_CONTROL]` marker indicates that a task or prompt contains flow contro { "step": 1, "title": "Setup infrastructure", - "description": "Install JWT library and create config following [synthesis_specification]", + "description": "Install JWT library and create config following [role_analyses]", "modification_points": [ "Add JWT library dependencies to package.json", "Create auth configuration file" ], "logic_flow": [ "Install jsonwebtoken library via npm", - "Configure JWT secret from [synthesis_specification]", + "Configure JWT secret from [role_analyses]", "Export auth config for use by [jwt_generator]" ], "depends_on": [], @@ -406,7 +407,7 @@ The `[FLOW_CONTROL]` marker indicates that a task or prompt contains flow contro **Structure**: Array of step objects with sequential execution **Step Fields**: -- **step**: Step identifier (string, e.g., "load_synthesis_specification") +- **step**: Step identifier (string, e.g., "load_role_analyses") - **action**: Human-readable description of the step - **command** or **commands**: Single command string or array of command strings - **output_to**: Variable name for storing step output @@ -567,7 +568,7 @@ Both formats use `[variable_name]` syntax for referencing outputs from previous **Examples**: ```json // Reference pre_analysis output -"description": "Install JWT library following [synthesis_specification]" +"description": "Install JWT library following [role_analyses]" // Reference previous step output "description": "Create middleware using [auth_config] and [jwt_generator]" @@ -636,7 +637,7 @@ Both formats use `[variable_name]` syntax for referencing outputs: ```json { "step": 2, - "description": "Implement following [synthesis_specification] and [codebase_structure]", + "description": "Implement following [role_analyses] and [codebase_structure]", "depends_on": [1], "output": "implementation" } diff --git a/COMMAND_REFERENCE.md b/COMMAND_REFERENCE.md index 109cf5d9..1c87fb09 100644 --- a/COMMAND_REFERENCE.md +++ b/COMMAND_REFERENCE.md @@ -45,18 +45,18 @@ These commands orchestrate complex, multi-phase development processes, from plan | Command | Description | |---|---| -| `/workflow:brainstorm:artifacts` | Generate role-specific topic-framework.md dynamically based on selected roles. | +| `/workflow:brainstorm:artifacts` | Generate role-specific guidance-specification.md dynamically based on selected roles. | | `/workflow:brainstorm:auto-parallel` | Parallel brainstorming automation with dynamic role selection and concurrent execution. | -| `/workflow:brainstorm:synthesis` | Generate synthesis-specification.md from topic-framework and role analyses with @ references using conceptual-planning-agent. | -| `/workflow:brainstorm:api-designer` | Generate or update api-designer/analysis.md addressing topic-framework discussion points. | -| `/workflow:brainstorm:data-architect` | Generate or update data-architect/analysis.md addressing topic-framework discussion points. | -| `/workflow:brainstorm:product-manager` | Generate or update product-manager/analysis.md addressing topic-framework discussion points. | -| `/workflow:brainstorm:product-owner` | Generate or update product-owner/analysis.md addressing topic-framework discussion points. | -| `/workflow:brainstorm:scrum-master` | Generate or update scrum-master/analysis.md addressing topic-framework discussion points. | -| `/workflow:brainstorm:subject-matter-expert` | Generate or update subject-matter-expert/analysis.md addressing topic-framework discussion points. | -| `/workflow:brainstorm:system-architect` | Generate or update system-architect/analysis.md addressing topic-framework discussion points. | -| `/workflow:brainstorm:ui-designer` | Generate or update ui-designer/analysis.md addressing topic-framework discussion points. | -| `/workflow:brainstorm:ux-expert` | Generate or update ux-expert/analysis.md addressing topic-framework discussion points. | +| `/workflow:brainstorm:synthesis` | Generate synthesis-specification.md from guidance-specification and role analyses with @ references using conceptual-planning-agent. | +| `/workflow:brainstorm:api-designer` | Generate or update api-designer/analysis.md addressing guidance-specification discussion points. | +| `/workflow:brainstorm:data-architect` | Generate or update data-architect/analysis.md addressing guidance-specification discussion points. | +| `/workflow:brainstorm:product-manager` | Generate or update product-manager/analysis.md addressing guidance-specification discussion points. | +| `/workflow:brainstorm:product-owner` | Generate or update product-owner/analysis.md addressing guidance-specification discussion points. | +| `/workflow:brainstorm:scrum-master` | Generate or update scrum-master/analysis.md addressing guidance-specification discussion points. | +| `/workflow:brainstorm:subject-matter-expert` | Generate or update subject-matter-expert/analysis.md addressing guidance-specification discussion points. | +| `/workflow:brainstorm:system-architect` | Generate or update system-architect/analysis.md addressing guidance-specification discussion points. | +| `/workflow:brainstorm:ui-designer` | Generate or update ui-designer/analysis.md addressing guidance-specification discussion points. | +| `/workflow:brainstorm:ux-expert` | Generate or update ux-expert/analysis.md addressing guidance-specification discussion points. | ### Quality & Verification @@ -102,7 +102,8 @@ These commands are primarily used internally by other workflow commands but can | Command | Description | |---|---| | `/workflow:tools:concept-enhanced` | Enhanced intelligent analysis with parallel CLI execution and design blueprint generation. | -| `/workflow:tools:context-gather` | Intelligently collect project context using general-purpose agent based on task description and package into standardized JSON. | +| `/workflow:tools:conflict-resolution` | Detect and resolve conflicts between plan and existing codebase using CLI-powered analysis. | +| `/workflow:tools:context-gather` | Intelligently collect project context using universal-executor agent based on task description and package into standardized JSON. | | `/workflow:tools:task-generate` | Generate task JSON files and IMPL_PLAN.md from analysis results with artifacts integration. | | `/workflow:tools:task-generate-agent` | Autonomous task generation using action-planning-agent with discovery and output phases. | | `/workflow:tools:task-generate-tdd` | Generate TDD task chains with Red-Green-Refactor dependencies. |