From 25f07657397cdc86569a44ab65c02e3caad6eac5 Mon Sep 17 00:00:00 2001 From: "qingdong.zhang" Date: Tue, 4 Nov 2025 11:42:08 +0800 Subject: [PATCH] feat: Add /speckit.innovate command for parallel brainstorming - Add new /speckit.innovate command template with dynamic multi-role system - Support three brainstorming modes (Quick/Standard/Deep) - Implement cross-domain inspiration system - Add structured challenge-rebuttal debates between agents - Include session persistence and resumability features - Add user impact analysis from multiple stakeholder perspectives - Create comprehensive agent-roles.yaml configuration with 15+ role categories - Add brainstorms directory structure template and documentation - Update README.md to document the new command - Update CHANGELOG.md with complete feature description This command facilitates creative ideation using parallel subagent discussions, helping teams brainstorm innovative solutions through diverse expert perspectives. --- CHANGELOG.md | 23 ++ README.md | 1 + templates/agent-roles.yaml | 484 ++++++++++++++++++++++++ templates/brainstorms-readme.md | 135 +++++++ templates/commands/innovate.md | 641 ++++++++++++++++++++++++++++++++ 5 files changed, 1284 insertions(+) create mode 100644 templates/agent-roles.yaml create mode 100644 templates/brainstorms-readme.md create mode 100644 templates/commands/innovate.md diff --git a/CHANGELOG.md b/CHANGELOG.md index ea6729145..fc8a812d4 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -7,6 +7,29 @@ All notable changes to the Specify CLI and templates are documented here. The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/), and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html). +## [Unreleased] + +### Added + +- **New `/speckit.innovate` Command**: Advanced brainstorming command that facilitates creative ideation using parallel subagent discussions + - 🎭 Dynamic multi-role system (2-4 experts) based on topic analysis using configurable role definitions + - 🌍 Cross-domain inspiration system that identifies analogies from unrelated fields before ideation + - ⚔️ Structured challenge-rebuttal debates where agents constructively critique each other's ideas + - 👥 User impact analysis evaluating solutions from multiple stakeholder perspectives + - 🎚️ Three brainstorming modes: + - **Quick Mode** ⚡ (15-20 min, 2 rounds): Rapid ideation for simple topics + - **Standard Mode** ⚖️ (30-45 min, 3 rounds): Balanced exploration (default) + - **Deep Mode** 🔬 (60+ min, 4-5 rounds): Comprehensive analysis with risk assessment and implementation roadmaps + - 💾 Session persistence and resumability: + - Auto-save after each round with structured directory layout + - Resume interrupted sessions with `--resume [session-id]` + - Session metadata tracking (status, roles, timestamps, rounds completed) + - Quick-access symbolic links to final reports + - 📊 Multi-agent evaluation matrix for consensus building + - 🎯 Hybrid idea formation by combining best elements from different perspectives +- **Agent Roles Configuration Template** (`templates/agent-roles.yaml`): Comprehensive role definitions for 15+ categories including authentication, performance, architecture, data, API design, testing, DevOps, UI/UX, code quality, migration, documentation, and monitoring +- **Brainstorms Directory Structure Template** (`templates/brainstorms-readme.md`): Documentation for session management, directory layout, and best practices + ## [0.0.20] - 2025-10-14 ### Added diff --git a/README.md b/README.md index 1c7dda215..e71d73066 100644 --- a/README.md +++ b/README.md @@ -246,6 +246,7 @@ Additional commands for enhanced quality and validation: | `/speckit.clarify` | Clarify underspecified areas (recommended before `/speckit.plan`; formerly `/quizme`) | | `/speckit.analyze` | Cross-artifact consistency & coverage analysis (run after `/speckit.tasks`, before `/speckit.implement`) | | `/speckit.checklist` | Generate custom quality checklists that validate requirements completeness, clarity, and consistency (like "unit tests for English") | +| `/speckit.innovate` | Brainstorm innovative ideas and solutions using parallel subagent discussions with dynamic multi-role system (Quick/Standard/Deep modes) | ### Environment Variables diff --git a/templates/agent-roles.yaml b/templates/agent-roles.yaml new file mode 100644 index 000000000..ae5f3d99c --- /dev/null +++ b/templates/agent-roles.yaml @@ -0,0 +1,484 @@ +# Agent Roles Configuration for /specify.innovate +# +# This file defines expert role personas used in brainstorming sessions. +# Roles are dynamically selected based on topic keywords. +# +# Format: +# category_name: +# keywords: [list of keywords to match in user input] +# roles: +# - name: Role Name +# focus: What they focus on +# approach: Their methodology +# questions: +# - Key questions they ask +# +# Usage: +# When user runs /specify.innovate, the command: +# 1. Extracts keywords from topic +# 2. Finds best matching category +# 3. Assigns roles from that category (2-4 roles) +# 4. Falls back to 'default' if no match found + +# ============================================================================ +# DEFAULT ROLES (Used when no specific category matches) +# ============================================================================ +default: + keywords: [] # Matches when no other category matches + roles: + - name: The Optimizer + focus: Efficiency, practicality, resource optimization + approach: Data-driven analysis, cost-benefit thinking, incremental improvement + questions: + - How can we minimize waste and maximize value? + - What's the most resource-efficient approach? + - How does this scale with growth? + - What are the maintenance costs? + + - name: The Innovator + focus: Creativity, disruption, novel approaches + approach: First-principles thinking, analogies, challenging assumptions + questions: + - What if we started from scratch? + - How do other industries solve this? + - What assumptions can we challenge? + - What's the 10x solution, not 10% improvement? + +# ============================================================================ +# SECURITY & AUTHENTICATION +# ============================================================================ +authentication: + keywords: [auth, login, authentication, password, sso, oauth, identity, credential, mfa, 2fa] + roles: + - name: Security Expert + focus: Threat modeling, vulnerability assessment, attack vectors + approach: Zero-trust principles, defense in depth, security by design + questions: + - What are the attack vectors? + - How do we prevent credential theft? + - What happens if the auth system is compromised? + - How do we handle session management securely? + + - name: UX Designer + focus: User experience, friction reduction, accessibility + approach: User journey mapping, usability testing, inclusive design + questions: + - How seamless is the login flow? + - What happens when users forget passwords? + - Is this accessible to all user groups? + - How do we balance security and convenience? + + - name: Compliance Officer + focus: Regulatory requirements, data protection, audit trails + approach: GDPR/CCPA compliance, SOC2, audit readiness + questions: + - Are we compliant with data protection laws? + - How do we handle data retention? + - What audit logs do we need? + - How do we document consent? + +# ============================================================================ +# PERFORMANCE & OPTIMIZATION +# ============================================================================ +performance: + keywords: [performance, optimize, speed, latency, throughput, cache, slow, bottleneck, scale] + roles: + - name: Performance Engineer + focus: Benchmarking, profiling, optimization techniques + approach: Data-driven analysis, A/B testing, incremental optimization + questions: + - What are the current bottlenecks? + - How do we measure success? + - What's the 80/20 optimization opportunity? + - How does this perform under load? + + - name: Cost Analyst + focus: Resource utilization, cost-effectiveness, ROI + approach: Total cost of ownership, cost-benefit analysis + questions: + - What's the cost per improvement? + - Are there cheaper alternatives? + - What's the payback period? + - How does this impact infrastructure costs? + + - name: Infrastructure Architect + focus: Scalability, reliability, system design + approach: Distributed systems thinking, capacity planning + questions: + - How does this scale horizontally? + - What are the failure modes? + - How do we handle traffic spikes? + - What's the degradation strategy? + +# ============================================================================ +# FEATURE DESIGN & PRODUCT +# ============================================================================ +feature_design: + keywords: [feature, design, product, ui, ux, interface, dashboard, report, visualization] + roles: + - name: Product Manager + focus: User needs, business value, prioritization + approach: User stories, outcome-driven, market analysis + questions: + - Who is this for and what problem does it solve? + - How does this align with business goals? + - What's the MVP vs. nice-to-have? + - How do we measure adoption? + + - name: Developer + focus: Technical feasibility, implementation complexity, maintainability + approach: Iterative development, technical debt management + questions: + - How complex is this to build? + - What dependencies do we need? + - How maintainable is this long-term? + - What edge cases exist? + + - name: End User Advocate + focus: Actual user needs, accessibility, real-world usage + approach: User research, empathy mapping, usability testing + questions: + - Will users actually use this? + - Is it intuitive for non-technical users? + - What happens when users make mistakes? + - How does this fit their workflow? + +# ============================================================================ +# ARCHITECTURE & SYSTEM DESIGN +# ============================================================================ +architecture: + keywords: [architecture, microservices, monolith, system design, distributed, api, service, infrastructure] + roles: + - name: Solution Architect + focus: System design patterns, trade-offs, long-term strategy + approach: Domain-driven design, event-driven architecture + questions: + - What are the architectural trade-offs? + - How does this fit our overall system? + - What are the coupling points? + - How do we handle failure domains? + + - name: DevOps Engineer + focus: Deployment, monitoring, operational excellence + approach: CI/CD, infrastructure as code, observability + questions: + - How do we deploy this safely? + - What monitoring do we need? + - How do we roll back if needed? + - What's the operational burden? + + - name: Cost Analyst + focus: Infrastructure costs, resource efficiency + approach: Total cost of ownership, cloud cost optimization + questions: + - What's the cost per service? + - Are there cheaper alternatives? + - How does this scale cost-wise? + - What's the long-term financial impact? + + - name: Performance Engineer + focus: System performance, scalability, reliability + approach: Load testing, capacity planning, optimization + questions: + - How does this perform at scale? + - What are the latency implications? + - How do we handle traffic spikes? + - What's the degradation strategy? + +# ============================================================================ +# DATA & ANALYTICS +# ============================================================================ +data: + keywords: [data, analytics, database, query, storage, etl, pipeline, warehouse, lake] + roles: + - name: Data Engineer + focus: Data pipelines, ETL, data quality + approach: Schema design, data modeling, pipeline orchestration + questions: + - How do we ensure data quality? + - What's the data freshness requirement? + - How do we handle schema evolution? + - What's the data retention policy? + + - name: Analytics Lead + focus: Business insights, reporting, metrics + approach: Metrics definition, dashboard design, storytelling + questions: + - What business questions do we answer? + - How do we measure success? + - What visualizations are most valuable? + - How do we avoid vanity metrics? + + - name: Infrastructure Architect + focus: Scalability, cost, performance + approach: Data architecture, storage optimization + questions: + - How does this scale with data volume? + - What's the query performance? + - What storage solution fits best? + - How do we handle backups? + +# ============================================================================ +# API DESIGN +# ============================================================================ +api_design: + keywords: [api, rest, graphql, endpoint, integration, webhook, sdk] + roles: + - name: API Designer + focus: Developer experience, consistency, versioning + approach: REST/GraphQL best practices, API-first design + questions: + - Is this API intuitive for developers? + - How do we handle versioning? + - What's the error handling strategy? + - How do we document this? + + - name: Backend Developer + focus: Implementation, performance, security + approach: Scalable backend design, caching strategies + questions: + - How do we validate requests? + - What's the rate limiting strategy? + - How do we handle authentication? + - What's the caching approach? + + - name: Integration Engineer + focus: Third-party integrations, compatibility + approach: Middleware design, adapter patterns + questions: + - How do we integrate with existing systems? + - What backward compatibility do we need? + - How do we handle breaking changes? + - What testing strategy ensures compatibility? + +# ============================================================================ +# TESTING & QUALITY +# ============================================================================ +testing: + keywords: [test, testing, quality, qa, bug, defect, coverage, automation] + roles: + - name: QA Engineer + focus: Test coverage, quality metrics, bug prevention + approach: Test pyramid, risk-based testing + questions: + - What test strategy gives best coverage? + - How do we catch regressions? + - What edge cases need testing? + - How do we automate this? + + - name: Developer + focus: Testability, maintainability, implementation + approach: TDD, unit testing, integration testing + questions: + - Is this code testable? + - What mocking strategy works best? + - How do we test async behavior? + - What's the test execution time? + + - name: Product Owner + focus: User acceptance, business logic validation + approach: BDD, acceptance criteria, user scenarios + questions: + - Does this meet user requirements? + - What business scenarios need testing? + - How do we validate in production? + - What's the acceptance criteria? + +# ============================================================================ +# DEVOPS & DEPLOYMENT +# ============================================================================ +devops: + keywords: [deploy, deployment, ci/cd, pipeline, kubernetes, docker, container, infrastructure] + roles: + - name: DevOps Engineer + focus: Deployment pipelines, automation, reliability + approach: GitOps, infrastructure as code, progressive delivery + questions: + - How do we deploy safely? + - What's the rollback strategy? + - How do we handle secrets? + - What monitoring do we need? + + - name: SRE (Site Reliability Engineer) + focus: Reliability, observability, incident response + approach: SLO/SLI definition, chaos engineering + questions: + - What are the failure modes? + - How do we detect issues quickly? + - What's the MTTR (mean time to recovery)? + - How do we prevent similar incidents? + + - name: Security Engineer + focus: Secure deployments, vulnerability scanning + approach: Security scanning, least privilege, secrets management + questions: + - How do we scan for vulnerabilities? + - What secrets need protection? + - How do we enforce security policies? + - What compliance requirements exist? + +# ============================================================================ +# UI/UX DESIGN +# ============================================================================ +ui_ux: + keywords: [ui, ux, design, interface, user experience, usability, accessibility, a11y] + roles: + - name: UX Designer + focus: User research, journey mapping, interaction design + approach: User-centered design, iterative prototyping + questions: + - Who are our users and what do they need? + - What's the user journey? + - How do we reduce friction? + - What accessibility needs exist? + + - name: UI Designer + focus: Visual design, design systems, consistency + approach: Design tokens, component libraries, visual hierarchy + questions: + - Is this visually consistent? + - How does this fit our design system? + - What's the mobile experience? + - How do we handle dark mode? + + - name: Frontend Developer + focus: Implementation, performance, browser compatibility + approach: Component-based architecture, progressive enhancement + questions: + - How do we implement this efficiently? + - What's the performance impact? + - How do we handle browser differences? + - What's the accessibility implementation? + +# ============================================================================ +# CODE QUALITY & REFACTORING +# ============================================================================ +code_quality: + keywords: [refactor, refactoring, code quality, clean code, technical debt, maintainability] + roles: + - name: Senior Developer + focus: Code quality, maintainability, best practices + approach: SOLID principles, design patterns, code reviews + questions: + - Is this code maintainable? + - What design patterns apply? + - How do we reduce duplication? + - What's the long-term technical debt? + + - name: Tech Lead + focus: Team alignment, standards, architecture + approach: Team guidelines, architectural decisions + questions: + - Does this align with team standards? + - How do we document decisions? + - What impact does this have on the team? + - How do we enforce consistency? + + - name: Product Manager + focus: Business value, prioritization, ROI + approach: Outcome-driven, value stream mapping + questions: + - What business value does this create? + - How does this impact feature velocity? + - What's the opportunity cost? + - When should we prioritize this? + +# ============================================================================ +# MIGRATION & LEGACY SYSTEMS +# ============================================================================ +migration: + keywords: [migrate, migration, legacy, upgrade, modernize, transition] + roles: + - name: Migration Specialist + focus: Migration strategies, risk mitigation, rollback plans + approach: Strangler pattern, phased migration, parallel run + questions: + - What's the migration path? + - How do we minimize downtime? + - What's the rollback strategy? + - How do we validate success? + + - name: Risk Manager + focus: Risk assessment, contingency planning + approach: Risk matrix, impact analysis + questions: + - What could go wrong? + - What's the blast radius? + - How do we mitigate risks? + - What's the contingency plan? + + - name: Business Analyst + focus: Business continuity, stakeholder management + approach: Impact assessment, communication planning + questions: + - How does this affect users? + - What's the business impact? + - How do we communicate changes? + - What training is needed? + +# ============================================================================ +# DOCUMENTATION +# ============================================================================ +documentation: + keywords: [documentation, docs, document, readme, guide, tutorial] + roles: + - name: Technical Writer + focus: Clarity, structure, audience needs + approach: Information architecture, plain language + questions: + - Who is the audience? + - What do they need to accomplish? + - How do we structure information? + - What examples help understanding? + + - name: Developer Advocate + focus: Developer experience, adoption, discoverability + approach: Tutorials, code examples, interactive guides + questions: + - Is this easy to get started with? + - What code examples are needed? + - How do we make this discoverable? + - What common pitfalls should we warn about? + + - name: Support Engineer + focus: Troubleshooting, FAQ, common issues + approach: Issue-based documentation, troubleshooting guides + questions: + - What problems do users encounter? + - How do we guide troubleshooting? + - What information do we need for support? + - What are the common misunderstandings? + +# ============================================================================ +# MONITORING & OBSERVABILITY +# ============================================================================ +monitoring: + keywords: [monitoring, observability, metrics, logging, tracing, alerting, apm] + roles: + - name: SRE (Site Reliability Engineer) + focus: SLOs, incident detection, alerting strategy + approach: Golden signals, distributed tracing, log aggregation + questions: + - What are the key signals to monitor? + - How do we detect issues quickly? + - What alerts are actionable? + - How do we reduce alert fatigue? + + - name: Performance Engineer + focus: Performance metrics, bottleneck detection + approach: APM tools, profiling, benchmarking + questions: + - What performance metrics matter? + - How do we identify bottlenecks? + - What's the baseline performance? + - How do we track improvements? + + - name: Operations Manager + focus: Operational excellence, team efficiency + approach: Runbooks, incident management, postmortems + questions: + - How do we respond to incidents? + - What runbooks do we need? + - How do we learn from incidents? + - What operational metrics matter? + diff --git a/templates/brainstorms-readme.md b/templates/brainstorms-readme.md new file mode 100644 index 000000000..b8852ab30 --- /dev/null +++ b/templates/brainstorms-readme.md @@ -0,0 +1,135 @@ +# Example Brainstorm Session Directory Structure + +This directory contains saved brainstorming sessions from the `/specify.innovate` command. + +## Directory Structure + +``` +.specify/brainstorms/ +├── sessions/ +│ ├── 20251104-103042-code-review-improvement/ +│ │ ├── metadata.json +│ │ ├── round-0-inspiration.md +│ │ ├── round-1-ideas.md +│ │ ├── round-2-debate.md +│ │ ├── round-3-synthesis.md +│ │ └── final-report.md +│ └── 20251104-140520-authentication-redesign/ +│ ├── metadata.json +│ ├── round-0-inspiration.md +│ ├── round-1-ideas.md +│ ├── round-2-debate.md +│ ├── round-3-synthesis.md +│ └── final-report.md +└── reports/ + ├── 2025-11-04-code-review-improvement.md -> ../sessions/20251104-103042-code-review-improvement/final-report.md + └── 2025-11-04-authentication-redesign.md -> ../sessions/20251104-140520-authentication-redesign/final-report.md +``` + +## Session Naming Convention + +Session IDs follow the format: `YYYYMMDD-HHMMSS-[topic-slug]` + +- `YYYYMMDD`: Date the session started +- `HHMMSS`: Time the session started (24-hour format) +- `[topic-slug]`: URL-friendly version of the topic (lowercase, hyphens) + +## Files in Each Session + +### `metadata.json` +Contains session metadata: +```json +{ + "session_id": "20251104-103042-code-review-improvement", + "topic": "How can we improve our code review process?", + "mode": "standard", + "status": "completed", + "started_at": "2025-11-04T10:30:42Z", + "completed_at": "2025-11-04T11:15:20Z", + "rounds_completed": 3, + "roles": ["Developer", "Product Manager", "End User Advocate"], + "can_resume": false +} +``` + +### `round-0-inspiration.md` +Cross-domain inspiration and analogies identified before ideation. + +### `round-1-ideas.md` +Initial ideas generated by each expert role independently. + +### `round-2-debate.md` +Challenge-rebuttal phase and hybrid idea formation. + +### `round-3-synthesis.md` +Multi-agent evaluation matrix, consensus recommendations, and user impact analysis. + +### `final-report.md` +Comprehensive brainstorming report with top recommendations and next steps. + +## Quick Access Reports + +The `reports/` directory contains symbolic links to final reports for easy access: + +- Named with date and topic slug: `YYYY-MM-DD-[topic-slug].md` +- Points to the actual final report in the session directory +- Easier to browse and find recent sessions + +## Resuming Sessions + +To resume an interrupted session: + +```bash +/specify.innovate --resume 20251104-103042-code-review-improvement +``` + +The command will: +1. Load the metadata to check session status +2. Load completed rounds from the session directory +3. Continue from where it left off +4. Save the completed session back to the same directory + +## Session Status + +Sessions can have the following statuses: + +- `in_progress`: Session was interrupted before completion +- `completed`: Session finished all planned rounds +- `cancelled`: Session was explicitly cancelled by user + +Only sessions with `status: "in_progress"` and `can_resume: true` can be resumed. + +## Viewing Past Sessions + +To view a past session report: + +1. Navigate to `.specify/brainstorms/reports/` +2. Find the report by date and topic +3. Open the markdown file in your editor or viewer + +Or directly open a session's final report: + +```bash +cat .specify/brainstorms/sessions/[session-id]/final-report.md +``` + +## Cleaning Up Old Sessions + +To remove old brainstorming sessions: + +1. Delete the session directory: `rm -rf .specify/brainstorms/sessions/[session-id]/` +2. Remove the corresponding report symlink: `rm .specify/brainstorms/reports/[report-name].md` + +Or to remove all sessions: + +```bash +rm -rf .specify/brainstorms/ +``` + +## Notes + +- Sessions are automatically saved after each round for crash recovery +- All session data is stored locally in your project +- Session files are plain Markdown and JSON for easy viewing and version control +- The `.specify/brainstorms/` directory is typically added to `.gitignore` to avoid committing brainstorm sessions + diff --git a/templates/commands/innovate.md b/templates/commands/innovate.md new file mode 100644 index 000000000..b681aac2c --- /dev/null +++ b/templates/commands/innovate.md @@ -0,0 +1,641 @@ +--- +description: Brainstorm innovative ideas and solutions using parallel subagent discussions. +--- + +## User Input + +```text +$ARGUMENTS +``` + +You **MUST** consider the user input before proceeding (if not empty). + +## Overview + +This command facilitates creative brainstorming by spawning multiple independent expert perspectives that discuss and debate ideas in parallel. The goal is to generate diverse, innovative solutions by exploring different viewpoints simultaneously. + +**Key Features:** + +- 🎭 Dynamic multi-role system (2-4 experts based on topic) +- 🌍 Cross-domain inspiration from unrelated fields +- ⚔️ Structured challenge-rebuttal debates +- 👥 User impact analysis from multiple stakeholder perspectives +- 🎚️ Flexible modes: Quick, Standard, or Deep brainstorming + +## Execution Flow + +### 0. Select Brainstorming Mode + +Determine the appropriate mode based on topic complexity and available time: + +**Mode Selection Logic:** + +1. Analyze user input length and complexity +2. Check for explicit mode request (e.g., "--quick", "--deep") +3. Recommend mode, allow user override + +**Available Modes:** + +| Mode | Duration | Rounds | Depth | Best For | +|------|----------|--------|-------|----------| +| **Quick** ⚡ | 15-20 min | 2 rounds | Shallow | Rapid ideation, simple topics, time-constrained | +| **Standard** ⚖️ | 30-45 min | 3 rounds | Medium | Most topics, balanced exploration (DEFAULT) | +| **Deep** 🔬 | 60+ min | 4-5 rounds | Deep | Complex topics, critical decisions, high stakes | + +**Mode Configurations:** + +**Quick Mode** ⚡: + +- Round 0: Cross-domain inspiration (optional, can skip) +- Round 1: Initial ideas (3 per agent, brief) +- Round 2: Quick critique + 2 hybrid ideas +- Output: Top 3 recommendations with minimal analysis + +**Standard Mode** ⚖️ (Current default): + +- Round 0: Cross-domain inspiration +- Round 1: Initial ideas (3-5 per agent) +- Round 2: Challenge-rebuttal + hybrid formation +- Round 3: Full synthesis + user impact matrix +- Output: Comprehensive report + +**Deep Mode** 🔬: + +- Round 0: Cross-domain inspiration + competitive analysis +- Round 1: Initial ideas (5-7 per agent) +- Round 2: Challenge-rebuttal + hybrid formation +- Round 3: Synthesis + user impact matrix +- Round 4: Risk analysis + failure modes +- Round 5: Implementation roadmap + validation plan +- Output: Executive report with detailed analysis + +**Mode Selection Output:** + +```markdown +## Brainstorming Session Configuration + +**Topic**: [User's topic] +**Selected Mode**: [Quick/Standard/Deep] [emoji] +**Estimated Duration**: [timeframe] +**Rounds**: [number] +**Rationale**: [Why this mode was selected/recommended] + +[If not default] User can override by saying "use [mode] mode" or "switch to [mode]" +``` + +### 1. Initialize Context + +Extract the brainstorming topic from user input: + +- If `$ARGUMENTS` is empty, ask user: "What topic would you like to brainstorm about?" +- Parse the topic to understand: + - Problem domain + - Desired outcome + - Any constraints or context provided + +### 1.5. Cross-Domain Inspiration (Round 0) + +Before diving into solutions, activate creative thinking through cross-domain analogies: + +1. **Identify 3 unrelated domains** that have solved similar challenges: + - Use pattern matching: "optimization" → manufacturing, biology, economics + - Use abstraction: "collaboration" → orchestras, sports teams, ecosystems + - Use transformation: "security" → castles, immune systems, cryptography + +2. **Brief description** (2-3 sentences each): + - Domain name + - How they approach similar problems + - Key insight or pattern + +3. **Mandate inspiration**: Each agent must reference at least ONE cross-domain insight in their Round 1 ideas + +**Example Output:** + +```markdown +## Round 0: Cross-Domain Inspiration + +**Topic**: Improve code review process + +**Analogous Domains:** + +1. **Medical Diagnosis** - Doctors use checklists, peer consultation, and differential diagnosis + - Key insight: Multiple review passes catch different types of issues + +2. **Restaurant Quality Control** - Chefs taste dishes, sous chefs inspect, customers provide feedback + - Key insight: Different stakeholders have different quality standards + +3. **Academic Peer Review** - Anonymous reviewers, revision rounds, editor oversight + - Key insight: Blind review reduces bias, revision cycles improve quality +``` + +### 2. Determine Agent Roles (Dynamic Multi-Role System) + +Instead of fixed 2-agent system, dynamically configure 2-4 expert roles based on the topic: + +1. **Load role configuration** from `.specify/memory/agent-roles.yaml` + +2. **Match topic to category** using keyword detection: + - Extract keywords from user input + - Find best matching category from config + - If no strong match, use default roles (Optimizer + Innovator) + +3. **Select optimal roles** (2-4 roles): + - If category found: use its predefined roles + - Limit to 4 roles maximum to avoid discussion fragmentation + - Minimum 2 roles for diverse perspectives + +4. **Role assignment output**: + + ```markdown + ## Assigned Expert Roles + + Based on topic analysis, the following experts will participate: + + **Role 1: [Name]** + - Focus: [key areas] + - Approach: [methodology] + - Key Questions: [questions they ask] + + **Role 2: [Name]** + - Focus: [key areas] + - Approach: [methodology] + - Key Questions: [questions they ask] + + [... additional roles if 3-4 selected] + ``` + +**Examples:** + +- Topic: "Improve our authentication system" + - Matched category: `authentication` + - Roles: Security Expert, UX Designer, Compliance Officer + +- Topic: "Optimize database query performance" + - Matched category: `performance` + - Roles: Performance Engineer, Cost Analyst, Infrastructure Architect + +- Topic: "Design a new reporting dashboard" + - Matched category: `feature_design` + - Roles: Product Manager, Developer, End User Advocate + +- Topic: "How to make better coffee" (no tech match) + - Matched category: `default` + - Roles: The Optimizer, The Innovator + +### 3. Parallel Discussion Rounds + +Execute 3 rounds of parallel thinking, where ALL assigned agents respond simultaneously: + +#### Round 1: Initial Ideas Generation (5 minutes thinking time per agent) + +- **Each agent's task**: From their unique perspective, propose 3-5 ideas +- **Mandate**: Must reference at least ONE cross-domain insight from Round 0 +- **Format**: Structured with reasoning, pros/cons, and feasibility assessment + +**Output Format for Round 1:** + +```markdown +## Round 1: Initial Ideas + +### [Role 1 Name]'s Perspective + +**Inspired by**: [Which cross-domain insight influenced this thinking] + +1. [Idea 1 title] + - Why: [reasoning] + - Pros: [benefits] + - Cons: [limitations] + - Feasibility: [Low/Medium/High] + +2. [Idea 2 title] + ... + +### [Role 2 Name]'s Perspective + +**Inspired by**: [Which cross-domain insight influenced this thinking] + +1. [Idea 1 title] + - Why: [reasoning] + - Pros: [benefits] + - Cons: [limitations] + - Feasibility: [Low/Medium/High] + +[... additional roles if 3-4 assigned] +``` + +#### Round 2: Challenge-Rebuttal & Cross-Pollination + +This round introduces structured debate to stress-test ideas: + +**Phase 2A: Constructive Challenges (Each agent challenges another)** + +- Each agent selects ONE idea from a different agent to challenge +- Challenge must be specific and constructive (not just "I disagree") +- Focus on hidden assumptions, edge cases, or overlooked constraints + +**Phase 2B: Rebuttals & Improvements** + +- Original proposer responds to challenge +- Options: Refute, Acknowledge & Improve, or Pivot to new approach +- Both parties collaborate to strengthen the idea + +**Phase 2C: Hybrid Formation** + +- Agents identify synergies between their ideas +- Propose 2-3 hybrid approaches combining best elements +- Cross-pollinate: practical + innovative elements + +**Output Format for Round 2:** + +```markdown +## Round 2: Challenge-Rebuttal & Cross-Pollination + +### Phase A: Constructive Challenges + +**[Role 1] challenges [Role 2]'s Idea [X]:** +- **Challenge**: [Specific concern or overlooked issue] +- **Why this matters**: [Impact if not addressed] + +**[Role 2] challenges [Role 3]'s Idea [Y]:** +- **Challenge**: [Specific concern] +- **Why this matters**: [Impact] + +[Continue pattern for all roles - each challenges exactly one other role] + +### Phase B: Rebuttals & Improvements + +**[Role 2] responds to challenge on Idea [X]:** +- **Response**: [Refutation or acknowledgment] +- **Improvement**: [How the idea evolves to address the challenge] +- **New version**: [Updated idea if significantly changed] + +[Continue for all challenged ideas] + +### Phase C: Hybrid Ideas + +**Hybrid 1: [Descriptive Name]** +- **Combines**: [Role X's Idea A] + [Role Y's Idea B] +- **Synthesis**: [How they complement each other] +- **Unique value**: [What's gained by combining] + +**Hybrid 2: [Descriptive Name]** +- **Combines**: [Ideas and roles] +- **Synthesis**: [Integration approach] +- **Unique value**: [Combined benefits] + +[2-3 hybrid ideas total] +``` + +#### Round 3: Synthesis & Recommendation + +- **All agents collaborate**: Rank top 3-5 combined/hybrid ideas +- **Multi-criteria evaluation**: Each agent scores from their perspective +- **User impact analysis**: Evaluate from multiple stakeholder viewpoints +- **Consensus building**: Identify which ideas have broad support vs. niche appeal + +**Output Format for Round 3:** + +```markdown +## Round 3: Synthesis + +### Multi-Agent Evaluation Matrix + +| Idea | [Role 1] Score | [Role 2] Score | [Role 3] Score | Consensus | +|------|---------------|---------------|---------------|-----------| +| Hybrid Idea 1 | 8/10 | 9/10 | 7/10 | Strong ⭐⭐⭐ | +| Original Idea from Role 2 | 9/10 | 6/10 | 8/10 | Moderate ⭐⭐ | +| Hybrid Idea 2 | 7/10 | 8/10 | 9/10 | Strong ⭐⭐⭐ | + +**Scoring criteria per role:** +- [Role 1]: [Their specific evaluation criteria] +- [Role 2]: [Their specific evaluation criteria] +- [Role 3]: [Their specific evaluation criteria] + +### Top 3 Consensus Recommendations + +#### Recommendation 1: [Idea Name] ⭐⭐⭐ + +- **What it is**: [Clear description] +- **Why it's strong**: [Multi-perspective strengths] +- **Implementation complexity**: [Low/Medium/High] +- **Time to value**: [Timeframe estimate] +- **Innovation score**: [1-10] +- **Key risks**: [What could go wrong] + +#### Recommendation 2: [Idea Name] ⭐⭐⭐ + +[Same structure] + +#### Recommendation 3: [Idea Name] ⭐⭐ + +[Same structure] + +### User Impact Matrix + +Evaluate the top 3 consensus ideas from different stakeholder perspectives: + +| Solution | Novice Users 👶 | Power Users 💪 | Administrators 👨‍💼 | Overall Sentiment | +|----------|----------------|----------------|---------------------|-------------------| +| Idea 1 | 😊 [reason] | 😐 [reason] | 😊 [reason] | Positive | +| Idea 2 | 😐 [reason] | 😊 [reason] | 😊 [reason] | Very Positive | +| Idea 3 | 😊 [reason] | 😊 [reason] | 😐 [reason] | Positive | + +**Legend**: 😊 Positive | 😐 Neutral/Mixed | 😟 Negative concern + +**Key Insights:** +- Which user group benefits most from each solution? +- Are there any "lose-lose" scenarios where multiple groups suffer? +- Can we adjust any solution to improve stakeholder alignment? +``` + +### 4. Convergence & Final Output + +After 3 rounds, synthesize findings into a unified brainstorm report: + +```markdown +## Brainstorming Report: [Topic] + +**Date**: [YYYY-MM-DD] +**Duration**: 3 rounds of parallel discussion + +### Top Recommended Ideas (Consensus) + +#### Idea 1: [Best Combined Approach] + +- **Description**: [Clear explanation] +- **Practical Strengths**: [From Optimizer] +- **Innovation Strengths**: [From Innovator] +- **Implementation Path**: [High-level steps] +- **Unique Value**: [Differentiation] +- **Risk Assessment**: [Key considerations] + +#### Idea 2: [Second Best Approach] + +[Same structure as above] + +#### Idea 3: [Third Best Approach] + +[Same structure as above] + +### Alternative Approaches Worth Exploring + +- [Other notable ideas from discussion] + +### Key Insights & Patterns + +- [Common themes across both perspectives] +- [Surprising synergies discovered] +- [Assumptions challenged successfully] + +### Next Steps + +1. [Immediate action items] +2. [Further research needed] +3. [Prototype/validation suggestions] +``` + +### 5. Save Output & Session Management + +**Session Persistence:** + +All brainstorming sessions are automatically saved with incremental checkpoints for resumability. + +**Directory Structure:** + +``` +.specify/brainstorms/ +├── sessions/ +│ ├── [session-id]/ +│ │ ├── metadata.json +│ │ ├── round-0-inspiration.md +│ │ ├── round-1-ideas.md +│ │ ├── round-2-debate.md +│ │ ├── round-3-synthesis.md +│ │ └── final-report.md +│ └── ... +└── reports/ + ├── YYYY-MM-DD-[topic-slug].md (symbolic link to final report) + └── ... +``` + +**Session Metadata (metadata.json):** + +```json +{ + "session_id": "20251104-103042-innovate-optimization", + "topic": "Optimize innovate command workflow", + "mode": "standard", + "status": "completed", + "started_at": "2025-11-04T10:30:42Z", + "completed_at": "2025-11-04T11:15:20Z", + "rounds_completed": 3, + "roles": ["The Optimizer", "The Innovator"], + "can_resume": false +} +``` + +**Save Process:** + +1. **Generate session ID**: `YYYYMMDD-HHMMSS-[topic-slug]` +2. **Create session directory**: `.specify/brainstorms/sessions/[session-id]/` +3. **Save incrementally after each round**: + - Round 0 → `round-0-inspiration.md` + - Round 1 → `round-1-ideas.md` + - Round 2 → `round-2-debate.md` + - Round 3 → `round-3-synthesis.md` + - Final report → `final-report.md` +4. **Update metadata.json** after each round: + - `rounds_completed`: increment + - `status`: "in_progress" → "completed" + - `can_resume`: true if interrupted, false if completed +5. **Create quick-access link**: + - Symlink in `reports/`: `YYYY-MM-DD-[topic-slug].md` → `sessions/[session-id]/final-report.md` + +**Resume Capability:** + +Users can resume interrupted sessions: + +```bash +/specify.innovate --resume [session-id] +``` + +**Resume Logic:** + +1. Load `metadata.json` to check status +2. If `status == "in_progress"`: + - Load completed rounds from session directory + - Display summary: "Resuming from Round [N+1]" + - Continue execution +3. If `status == "completed"`: + - Ask: "Session already complete. View report or start new iteration?" + - Options: View, Iterate (adds rounds 4-5), New session + +**Output to User:** + +```markdown +## Session Saved ✅ + +**Session ID**: [session-id] +**Location**: `.specify/brainstorms/sessions/[session-id]/` +**Quick access**: `.specify/brainstorms/reports/YYYY-MM-DD-[topic-slug].md` + +**Files created:** +- ✅ Round 0: Cross-domain inspiration +- ✅ Round 1: Initial ideas +- ✅ Round 2: Challenge-rebuttal +- ✅ Round 3: Synthesis +- ✅ Final report + +**To resume later**: `/specify.innovate --resume [session-id]` +**To view report**: Check the quick-access link above +``` + +**If not in a feature context:** + +- Only display the report in conversation +- Ask user: "Would you like to save this session? If yes, I'll create the directory structure." +- If user confirms, create `.specify/brainstorms/` in current directory + +## Operating Principles + +### Parallel Thinking Rules + +1. **True Independence**: All agents must develop their ideas independently in Round 1 +2. **No Premature Convergence**: Encourage divergent thinking before synthesizing +3. **Constructive Critique**: When challenging ideas, focus on improvement not destruction +4. **Evidence-Based**: Support claims with reasoning, examples, or analogies +5. **Time-Boxed**: Each round should produce focused output, not exhaustive analysis +6. **Cross-Domain Inspiration**: Each agent must reference at least one insight from Round 0 +7. **Mandatory Challenges**: In Round 2, each agent must challenge at least one other agent's idea + +### Quality Standards + +- **Clarity**: Each idea must be understandable to a non-expert +- **Actionability**: Include enough detail to evaluate feasibility +- **Originality**: Challenge conventional approaches +- **Balance**: Maintain tension between practical and innovative +- **Testability**: Ideas should be specific enough to prototype or validate +- **Diversity**: Avoid groupthink - actively seek contrarian perspectives + +### User Interaction + +- **After Mode Selection**: Confirm mode or allow user to override +- **After Round 0**: Ask if user wants to add custom analogies +- **After Round 1**: Ask user if they want to focus on specific ideas (optional filter) +- **After Round 2**: Ask if any direction should be explored deeper +- **After Round 3**: Ask if synthesis captures their needs or needs iteration +- **Allow interruption**: User can interrupt at any point with new constraints or directions +- **Support mode switching**: User can say "switch to deep mode" mid-session + +### Session Management + +- **Auto-save**: Save after each round automatically +- **Resumable**: All sessions can be resumed after interruption +- **Versioned**: Keep all intermediate rounds for traceability +- **Quick access**: Provide simple paths to final reports +- **Metadata tracking**: Record decisions, roles, and timing for future reference + +## Edge Cases + +- **Vague Topic**: Ask 2-3 clarifying questions before starting rounds +- **Technical Topic**: Agents should understand domain context; briefly research if needed +- **Early Termination**: User says "stop" → save current progress, provide summary so far +- **Iteration Request**: User says "iterate on idea X" → run focused micro-session on that idea +- **No Clear Winner**: Present all top ideas as equally valid options with tradeoffs +- **Mode Switch Mid-Session**: User requests deeper analysis → switch to Deep mode, add rounds 4-5 +- **Session Resumption**: Load interrupted session → verify context, continue from last checkpoint +- **Role Mismatch**: If no roles match topic → gracefully fall back to default (Optimizer + Innovator) +- **Too Many Roles**: If config returns >4 roles → pick top 4 by relevance +- **Custom Roles**: User specifies "--roles 'Security, UX, Performance'" → use custom roles instead of auto-detection +- **Save Failure**: If directory creation fails → display report only, warn about missing persistence +- **Cross-Domain Shortage**: Can't find 3 good analogies → use 1-2 strong ones rather than weak matches + +## Example Usage + +### Example 1: Standard Mode (Default) + +``` +User: /specify.innovate How can we improve our code review process? +``` + +Expected flow: + +1. **Mode Selection**: Analyzes topic, recommends Standard mode (30-45 min, 3 rounds) +2. **Role Assignment**: Detects "code review" + "improve" → assigns Developer, Product Manager, End User Advocate +3. **Round 0**: Generates cross-domain analogies (Medical peer review, Restaurant quality control, Academic publishing) +4. **Round 1**: Each of 3 agents proposes 3-5 ideas inspired by analogies +5. **Round 2**: + - Phase A: Each agent challenges another's idea + - Phase B: Rebuttals and improvements + - Phase C: Generate 2-3 hybrid ideas +6. **Round 3**: + - Multi-agent evaluation matrix (all agents score top ideas) + - User impact analysis (novice, power users, admins) + - Top 3 consensus recommendations +7. **Save**: Auto-save to `.specify/brainstorms/sessions/[id]/`, create quick-access link +8. **Output**: Comprehensive report with actionable recommendations + +### Example 2: Quick Mode for Simple Topics + +``` +User: /specify.innovate --quick What's a catchy name for our new feature? +``` + +Expected flow: + +1. **Mode Selection**: User specified Quick mode (15-20 min, 2 rounds) +2. **Role Assignment**: Creative task → uses default (Optimizer + Innovator) +3. **Round 0**: Skipped (optional in Quick mode) +4. **Round 1**: Each agent proposes 3 name ideas +5. **Round 2**: Quick critique + 2 hybrid suggestions +6. **Output**: Top 3 name recommendations with brief rationale + +### Example 3: Deep Mode for Critical Decisions + +``` +User: /specify.innovate --deep Should we migrate to microservices or stay monolithic? +``` + +Expected flow: + +1. **Mode Selection**: Deep mode (60+ min, 5 rounds) +2. **Role Assignment**: Architecture topic → Solution Architect, DevOps Engineer, Cost Analyst, Performance Engineer +3. **Round 0**: Cross-domain + competitive analysis (Netflix, Uber, Shopify case studies) +4. **Round 1**: Each of 4 agents proposes 5-7 ideas +5. **Round 2**: Challenge-rebuttal + hybrid formation +6. **Round 3**: Full synthesis + user impact +7. **Round 4**: Risk analysis + failure modes for top 3 +8. **Round 5**: Implementation roadmap + validation plan +9. **Output**: Executive-level report with detailed analysis, risks, and migration plan + +### Example 4: Resume Interrupted Session + +``` +User: /specify.innovate --resume 20251104-103042-code-review-improvement +``` + +Expected flow: + +1. Load metadata.json from session +2. Verify status = "in_progress", rounds_completed = 2 +3. Display: "Resuming from Round 3 - Synthesis & Recommendation" +4. Load Round 1 and Round 2 results from saved files +5. Continue with Round 3 +6. Update session status to "completed" + +### Example 5: Custom Roles + +``` +User: /specify.innovate --roles "Security Expert, Privacy Officer, Compliance" Design a new user authentication system +``` + +Expected flow: + +1. Override auto-detection, use custom roles specified +2. Proceed with 3 specified expert roles +3. Standard 3-round flow with custom perspectives + +## Context + +$ARGUMENTS +