claude-symphony 0.0.9 → 0.0.11

package/README.md

@@ -22,6 +22,10 @@ claude-symphony is a 10-stage software development workflow pipeline that orches
 - **Pipeline Forking**: Branch exploration for architecture alternatives with merge capabilities
 - **Stage Personas**: Optimized AI behavior profiles per stage (Creative Explorer, Precise Builder, etc.)
 - **Output Validation**: Automated quality checks with lint, typecheck, and coverage verification
+- **Epic Cycles**: User-defined stage range repetition with context preservation between cycles
+- **Implementation Order**: Frontend-first or backend-first development approach with reference links
+- **Requirements Refinement**: 4-level breakdown system (Epic → Feature → Task → Subtask) with INVEST validation
+- **Moodboard UX**: Interactive design reference collection with Claude Vision/Figma MCP analysis
 - **Dual Distribution**: Both NPM CLI and Claude Code plugin available
 
 ### Pipeline Stages
@@ -170,6 +174,15 @@ This monorepo contains three packages:
 | Pipeline Fork | `symphony fork` | `/fork` | Create/manage pipeline branches for exploration |
 | Output Validation | `symphony validate` | `/validate` | Validate stage outputs against quality criteria |
 
+### Workflow Commands
+
+| Command | Plugin | Description |
+|---------|--------|-------------|
+| Epic Cycle | `/epic` | Manage epic cycles (new, set-scope, set-count, history) |
+| Implementation Order | `/config order` | Set development order (frontend/backend/parallel) |
+| Moodboard | `/moodboard` | Interactive design reference collection and analysis |
+| Requirements Refine | `/refine` | Break down requirements (Epic → Feature → Task → Subtask) |
+
 ### Stage Shortcuts
 
 | Stage | CLI | Plugin |
@@ -226,7 +239,12 @@ Each project is fully self-contained with all pipeline components:
 ```
 my-project/                        # PROJECT_ROOT
 ├── .claude/                       # Claude Code configuration
-│   ├── commands/                  # Slash commands (26 commands)
+│   ├── commands/                  # Slash commands (30+ commands)
+│   │   ├── epic.md                # /epic - Epic cycle management
+│   │   ├── moodboard.md           # /moodboard - Design collection
+│   │   ├── refine.md              # /refine - Requirements refinement
+│   │   ├── config.md              # /config - Implementation order
+│   │   └── ...
 │   ├── hooks/                     # Lifecycle hooks
 │   ├── skills/                    # AI skills
 │   └── settings.json
@@ -242,14 +260,22 @@ my-project/                        # PROJECT_ROOT
 │   ├── 02-research/
 │   └── ... (10 stages total)
 ├── config/                        # Pipeline configuration
-│   ├── pipeline.yaml
-│   ├── context.yaml
-│   └── ... (15+ config files)
+│   ├── pipeline.yaml              # Core pipeline settings
+│   ├── context.yaml               # Context management
+│   ├── epic_cycles.yaml           # Epic cycle configuration
+│   ├── implementation_order.yaml  # Dev order settings
+│   ├── requirements_refinement.yaml # Refinement rules
+│   ├── ui-ux.yaml                 # Moodboard & design settings
+│   └── ... (20+ config files)
 ├── state/                         # Project state
 │   ├── progress.json              # Pipeline progress
 │   ├── checkpoints/               # Recovery points
 │   └── context/                   # Context snapshots
 ├── scripts/                       # Helper scripts
+│   ├── epic-cycle.sh              # Epic cycle management
+│   ├── moodboard-manager.sh       # Moodboard collection
+│   ├── requirements-refine.sh     # Requirements refinement
+│   └── ...
 ├── CLAUDE.md                      # Main AI instructions
 ├── src/                           # Source code (from stage 06)
 └── package.json
@@ -266,6 +292,8 @@ my-project/                        # PROJECT_ROOT
 7. **Multi-AI Collaboration** - Parallel, sequential, and debate modes for AI coordination
 8. **Pipeline Forking** - Branch exploration with merge capabilities
 9. **Smart Context Management** - Semantic compression and AI memory integration
+10. **Iterative Refinement Loops** - Epic cycles, requirements refinement, and moodboard feedback
+11. **Hierarchical Decomposition** - 4-level requirement breakdown (Epic → Feature → Task → Subtask)
 
 ## Documentation
 

package/bin/create.js

@@ -3,7 +3,7 @@
 import fs from 'fs';
 import path from 'path';
 import { fileURLToPath } from 'url';
-import { input, confirm } from '@inquirer/prompts';
+import { input, confirm, select } from '@inquirer/prompts';
 import yaml from 'js-yaml';
 
 const __filename = fileURLToPath(import.meta.url);
@@ -111,6 +111,66 @@ async function collectBriefInfo() {
     default: true
   });
 
+  // === Epic & Workflow Configuration ===
+  console.log('');
+  log('🔄 Epic & Workflow Configuration', 'yellow');
+  log('   (All settings can be modified later via commands)', 'reset');
+
+  // 1. Epic Cycles (High priority)
+  info.epicEnabled = await confirm({
+    message: '🔄 Enable Epic Cycles? (repeat stages for iterative refinement)',
+    default: false
+  });
+
+  if (info.epicEnabled) {
+    // 2. Epic Scope (High priority)
+    info.epicScope = await select({
+      message: '📍 Epic cycle scope: (which stages to repeat)',
+      choices: [
+        { name: 'Ideation (01-03) - concept exploration', value: 'ideation' },
+        { name: 'Design (01-05) - full design iteration', value: 'design' },
+        { name: 'Implementation (06-09) - code sprints', value: 'implementation' },
+        { name: 'Full Pipeline (01-10) - end-to-end', value: 'full' }
+      ],
+      default: 'design'
+    });
+
+    // 3. Total Cycles (High priority)
+    info.epicTotalCycles = await input({
+      message: '🔢 Total Epic cycles (1-5): (iterations for refinement)',
+      default: '2',
+      validate: (v) => {
+        const num = parseInt(v);
+        if (isNaN(num) || num < 1 || num > 5) return 'Enter 1-5';
+        return true;
+      }
+    });
+  }
+
+  // 4. Implementation Order (Medium priority)
+  info.implementationOrder = await select({
+    message: '🏗️ Implementation order: (frontend-first vs backend-first)',
+    choices: [
+      { name: 'Frontend First - UI then APIs', value: 'frontend_first' },
+      { name: 'Backend First - APIs then UI', value: 'backend_first' },
+      { name: 'Parallel - both simultaneously', value: 'parallel' },
+      { name: 'Decide Later', value: null }
+    ],
+    default: null
+  });
+
+  // 5. Requirements Refinement (Medium priority)
+  info.requirementsRefinement = await confirm({
+    message: '📋 Enable Requirements Refinement? (Epic→Feature→Task breakdown)',
+    default: true
+  });
+
+  // 6. Moodboard (Low priority)
+  info.moodboardEnabled = await confirm({
+    message: '🎨 Enable Moodboard collection? (visual references for UI/UX)',
+    default: true
+  });
+
   return info;
 }
 
@@ -182,6 +242,98 @@ function applyConfigSettings(targetDir, info) {
       // Silently continue if JSON parsing fails
     }
   }
+
+  // Scope preset mapping
+  const scopes = {
+    ideation: { start: '01-brainstorm', end: '03-planning' },
+    design: { start: '01-brainstorm', end: '05-task-management' },
+    implementation: { start: '06-implementation', end: '09-testing' },
+    full: { start: '01-brainstorm', end: '10-deployment' }
+  };
+
+  // Epic Cycles YAML
+  const epicPath = path.join(targetDir, 'config', 'epic_cycles.yaml');
+  if (fs.existsSync(epicPath)) {
+    try {
+      const config = yaml.load(fs.readFileSync(epicPath, 'utf8'));
+      config.epic_cycles.enabled = info.epicEnabled ?? false;
+      if (info.epicEnabled) {
+        config.epic_cycles.cycle_config.default_cycles = parseInt(info.epicTotalCycles) || 2;
+        const scope = scopes[info.epicScope] || scopes.design;
+        config.epic_cycles.cycle_scope.start_stage = scope.start;
+        config.epic_cycles.cycle_scope.end_stage = scope.end;
+      }
+      fs.writeFileSync(epicPath, yaml.dump(config, { lineWidth: -1 }));
+    } catch (e) { /* silent */ }
+  }
+
+  // Implementation Order YAML
+  const implPath = path.join(targetDir, 'config', 'implementation_order.yaml');
+  if (fs.existsSync(implPath)) {
+    try {
+      const config = yaml.load(fs.readFileSync(implPath, 'utf8'));
+      config.implementation_order.current_order = info.implementationOrder ?? null;
+      fs.writeFileSync(implPath, yaml.dump(config, { lineWidth: -1 }));
+    } catch (e) { /* silent */ }
+  }
+
+  // Requirements Refinement YAML
+  const reqPath = path.join(targetDir, 'config', 'requirements_refinement.yaml');
+  if (fs.existsSync(reqPath)) {
+    try {
+      const config = yaml.load(fs.readFileSync(reqPath, 'utf8'));
+      config.requirements_refinement.enabled = info.requirementsRefinement ?? true;
+      fs.writeFileSync(reqPath, yaml.dump(config, { lineWidth: -1 }));
+    } catch (e) { /* silent */ }
+  }
+
+  // UI-UX YAML (Moodboard)
+  const uiPath = path.join(targetDir, 'config', 'ui-ux.yaml');
+  if (fs.existsSync(uiPath)) {
+    try {
+      const config = yaml.load(fs.readFileSync(uiPath, 'utf8'));
+      if (config.moodboard?.collection_flow) {
+        config.moodboard.collection_flow.enabled = info.moodboardEnabled ?? true;
+      }
+      fs.writeFileSync(uiPath, yaml.dump(config, { lineWidth: -1 }));
+    } catch (e) { /* silent */ }
+  }
+
+  // Update progress.json with epic fields
+  if (fs.existsSync(progressPath)) {
+    try {
+      const progress = JSON.parse(fs.readFileSync(progressPath, 'utf8'));
+
+      // Epic cycle settings
+      if (progress.epic_cycle) {
+        progress.epic_cycle.enabled = info.epicEnabled ?? false;
+        if (info.epicEnabled) {
+          progress.epic_cycle.total_cycles = parseInt(info.epicTotalCycles) || 2;
+          const scope = scopes[info.epicScope] || scopes.design;
+          progress.epic_cycle.scope.start_stage = scope.start;
+          progress.epic_cycle.scope.end_stage = scope.end;
+        }
+      }
+
+      // Epic context in current_iteration
+      if (progress.current_iteration?.epic_context) {
+        progress.current_iteration.epic_context.enabled = info.epicEnabled ?? false;
+        progress.current_iteration.epic_context.total_cycles = parseInt(info.epicTotalCycles) || 1;
+      }
+
+      // Implementation order
+      if (progress.implementation_order) {
+        progress.implementation_order.selected = info.implementationOrder ?? null;
+      }
+
+      // Requirements refinement
+      if (progress.requirements_refinement) {
+        progress.requirements_refinement.active = info.requirementsRefinement ?? true;
+      }
+
+      fs.writeFileSync(progressPath, JSON.stringify(progress, null, 2));
+    } catch (e) { /* silent */ }
+  }
 }
 
 function generateBriefContent(projectName, info) {
@@ -305,6 +457,32 @@ ${colors.yellow}After creation:${colors.reset}
   copyRecursiveSync(templateDir, targetDir);
   log('✓ Template copy complete', 'green');
 
+  // 3.1 Remove any nested .git directories from the copied template
+  // This prevents nested git repositories which cause tracking issues
+  function removeNestedGitDirs(dir, isRoot = true) {
+    if (!fs.existsSync(dir)) return;
+
+    const items = fs.readdirSync(dir);
+    for (const item of items) {
+      const itemPath = path.join(dir, item);
+      const stat = fs.statSync(itemPath);
+
+      if (stat.isDirectory()) {
+        if (item === '.git' && !isRoot) {
+          // Remove nested .git directories (not the root one if it exists)
+          fs.rmSync(itemPath, { recursive: true, force: true });
+          log(`  Removed nested .git from ${path.relative(targetDir, dir)}`, 'yellow');
+        } else if (item !== '.git') {
+          // Recurse into non-.git directories
+          removeNestedGitDirs(itemPath, false);
+        }
+      }
+    }
+  }
+
+  removeNestedGitDirs(targetDir);
+  log('✓ Cleaned up nested .git directories', 'green');
+
   // 4. Initialize progress.json
   const progressTemplatePath = path.join(targetDir, 'state', 'progress.json.template');
   const progressPath = path.join(targetDir, 'state', 'progress.json');

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "claude-symphony",
-  "version": "0.0.9",
+  "version": "0.0.11",
   "description": "Multi-AI Orchestration Framework - Create new projects with 10-stage development workflow",
   "type": "module",
   "bin": {

package/template/.claude/skills/synthesis-consolidator/README.md

@@ -0,0 +1,41 @@
+# Synthesis Consolidator Skill
+
+Consolidates outputs from parallel AI execution into a unified result.
+
+## Overview
+
+When multiple AI models execute the same task in parallel, this skill helps Claude Code synthesize their outputs into a single, high-quality deliverable.
+
+## Trigger
+
+- `/synthesize` command
+- Auto-triggered after parallel execution completes
+
+## Workflow
+
+1. **Collect** - Gather all parallel model outputs
+2. **Analyze** - Identify commonalities and consensus
+3. **Evaluate** - Compare differences and unique insights
+4. **Synthesize** - Create unified output
+5. **Validate** - Verify completeness and quality
+
+## Configuration
+
+See `config/ai_collaboration.yaml` for:
+- `consolidation_workflow.synthesizer` - Default: claudecode
+- `consolidation_workflow.quality_threshold` - Default: 0.8
+
+## Parallel-Capable Stages
+
+| Stage | Primary Model | Secondary Model |
+|-------|---------------|-----------------|
+| 01-brainstorm | Gemini | ClaudeCode |
+| 03-planning | Gemini | ClaudeCode |
+| 04-ui-ux | Gemini | ClaudeCode |
+| 07-refactoring | Codex | ClaudeCode |
+| 09-testing | Codex | ClaudeCode |
+
+## Output
+
+- Final synthesized output: Stage's required output file
+- Synthesis log: `state/collaborations/synthesis_log.md`

package/template/.claude/skills/synthesis-consolidator/prompts/CLAUDE.md

@@ -0,0 +1,96 @@
+# Synthesis Consolidator - Claude Code Instructions
+
+## Role
+You are the **Synthesis Consolidator** for parallel AI execution results.
+
+## Protocol
+
+### Step 1: Collect Outputs
+Read all parallel execution outputs:
+- `outputs/output_gemini.md`
+- `outputs/output_codex.md`
+- `outputs/output_claudecode.md`
+
+### Step 2: Analyze Commonalities
+Identify consensus items (present in 2+ outputs):
+- Shared recommendations
+- Common structural patterns
+- Agreed approaches
+
+### Step 3: Evaluate Differences
+For unique contributions:
+| Situation | Action |
+|-----------|--------|
+| Unique + valuable | Include |
+| Unique + questionable | Omit or flag |
+| Conflicts consensus | Document as alternative |
+
+### Step 4: Create Synthesis
+Generate unified output with:
+- Consensus items (high confidence)
+- Integrated unique insights
+- Alternative approaches noted
+
+### Step 5: Validate
+- [ ] All required sections present
+- [ ] No critical information lost
+- [ ] Reads as coherent document
+
+## Output
+Save to stage's required output file and log to `state/collaborations/synthesis_log.md`
+
+## Synthesis Log Format
+
+```markdown
+# Synthesis Log - {{STAGE_NAME}}
+
+## Timestamp
+{{TIMESTAMP}}
+
+## Input Sources
+| Model | Output File | Status |
+|-------|-------------|--------|
+| {{MODEL}} | {{FILE}} | {{STATUS}} |
+
+## Consensus Analysis
+### High Confidence Items (2+ models agree)
+- {{ITEM}}
+
+### Unique Contributions
+| Source | Contribution | Decision |
+|--------|--------------|----------|
+| {{MODEL}} | {{CONTRIBUTION}} | {{INCLUDED/EXCLUDED}} |
+
+## Quality Metrics
+- Completeness: {{SCORE}}
+- Coherence: {{SCORE}}
+- Coverage: {{SCORE}}
+
+## Final Output
+- File: {{OUTPUT_FILE}}
+- Sections: {{SECTION_COUNT}}
+- Word Count: {{WORD_COUNT}}
+```
+
+## Conflict Resolution Priority
+
+1. **Factual consistency** - Prefer verifiable facts
+2. **Technical accuracy** - Prefer correct technical details
+3. **Completeness** - Include rather than exclude when uncertain
+4. **Clarity** - Prefer clearer explanations
+
+## Commands
+
+```bash
+# Trigger synthesis for current stage
+/synthesize
+
+# Verbose mode with detailed analysis
+/synthesize --verbose
+
+# Dry run - show what would be synthesized
+/synthesize --dry-run
+
+# Force re-synthesis even if output exists
+/synthesize --force
+```

package/template/CLAUDE.md

@@ -197,6 +197,15 @@ Visualizes context usage, tool activity, and todo progress in the statusline.
 | `/test` | 09-testing |
 | `/deploy` | 10-deployment |
 
+### Requirements & Design Commands
+| Command | Description |
+|---------|-------------|
+| `/refine` | Interactive requirements refinement (Epic → Feature → Task) |
+| `/refine --validate` | Validate requirements against INVEST criteria |
+| `/moodboard` | Collect design references and analyze design tokens |
+| `/moodboard analyze` | Extract colors, fonts, styles from collected images |
+| `/moodboard skip` | Skip moodboard collection (use AI-generated design) |
+
 ## Skills (Auto-Activated)
 
 | Skill | Trigger | Description |
@@ -366,6 +375,19 @@ state/
   templates/           # State templates
 ```
 
+## Key File Locations
+
+Quick reference for frequently accessed files:
+
+| File | Location | Description |
+|------|----------|-------------|
+| **Project Brief** | `stages/01-brainstorm/inputs/project_brief.md` | Initial project requirements and scope |
+| **Progress State** | `state/progress.json` | Pipeline progress and current state |
+| **Configuration** | `config/*.yaml` | All configuration files |
+| **HANDOFF** | `stages/XX-stage/HANDOFF.md` | Stage transition documents |
+| **Checkpoints** | `state/checkpoints/` | Saved checkpoint files |
+| **Stage Outputs** | `stages/XX-stage/outputs/` | Generated deliverables per stage |
+
 ## Design Patterns Applied
 
 1. **Sequential Workflow Architecture** - Sequential stage definition and auto-progression
@@ -377,6 +399,36 @@ state/
 
 ---
 
+## MCP Server Selection Guide
+
+> Configuration file: `config/mcp_fallbacks.yaml`
+
+### Use Case by MCP Server
+
+| MCP Server | Best For | Example Use Cases |
+|------------|----------|-------------------|
+| **Exa Search** | Web research, market analysis | Competitor research, trend analysis, API docs |
+| **Context7** | Code documentation, library references | Framework docs, package APIs, code examples |
+| **Firecrawl** | Deep website scraping | Extracting structured data, full page content |
+| **Notion** | Task management, collaboration | Creating/updating tasks, project tracking |
+| **Figma** | Design token extraction | Colors, typography, component specs |
+
+### Stage-Specific Recommendations
+
+| Stage | Primary MCP | Fallback | Notes |
+|-------|-------------|----------|-------|
+| 02-research | Exa Search | Context7 | Use Exa for market data, Context7 for tech docs |
+| 03-planning | Context7 | Exa Search | Architecture patterns, framework best practices |
+| 04-ui-ux | Figma | - | Extract design tokens if Figma file available |
+| 05-task-management | Notion | Markdown files | Falls back to local files if Notion not configured |
+
+### Fallback Conditions
+- **API quota exceeded**: Automatic switch to fallback provider
+- **Response quality insufficient**: Manual switch recommended
+- **Timeout**: Retry with fallback after 30 seconds
+
+---
+
 ## Multi-AI Orchestration
 
 > Configuration files: `config/ai_collaboration.yaml`, `config/ai_benchmarking.yaml`
@@ -441,6 +493,50 @@ All defined AI models execute the same task in parallel, and each output is synt
 
 ---
 
+## Default Parallel Execution
+
+### Parallel Mode is NOW DEFAULT for:
+| Stage | Models | Synthesizer |
+|-------|--------|-------------|
+| 01-brainstorm | Gemini + ClaudeCode | ClaudeCode |
+| 03-planning | Gemini + ClaudeCode | ClaudeCode |
+| 04-ui-ux | Gemini + ClaudeCode | ClaudeCode |
+| 07-refactoring | Codex + ClaudeCode | ClaudeCode |
+| 09-testing | Codex + ClaudeCode | ClaudeCode |
+
+### Execution Policy Configuration
+> Configuration file: `config/ai_collaboration.yaml`
+
+```yaml
+execution_policy:
+  default_mode: "parallel"
+  stage_classification:
+    parallel_capable: [01-brainstorm, 03-planning, 04-ui-ux, 07-refactoring, 09-testing]
+    sequential_only: [02-research, 05-task-management, 06-implementation, 08-qa, 10-deployment]
+```
+
+### Consolidation Workflow
+Claude Code automatically consolidates parallel outputs:
+1. **Collect** - Gather all model outputs
+2. **Analyze** - Identify commonalities → HIGH CONFIDENCE
+3. **Evaluate** - Compare unique contributions
+4. **Synthesize** - Create final unified output
+5. **Validate** - Verify completeness and quality
+
+### Synthesis Commands
+```bash
+/synthesize              # Consolidate current stage outputs
+/synthesize --verbose    # Show detailed analysis
+/synthesize --dry-run    # Preview without writing
+/synthesize --force      # Re-synthesize even if output exists
+```
+
+### Quality Threshold
+- Default: 0.8 (80%)
+- Outputs below threshold trigger review prompt
+
+---
+
 ## Smart HANDOFF System
 
 > Configuration files: `config/handoff_intelligence.yaml`, `config/memory_integration.yaml`

package/template/config/ai_collaboration.yaml

@@ -1,6 +1,47 @@
 # claude-symphony AI Collaboration Configuration
 # Multi-AI orchestration modes and collaboration strategies
 
+# Default execution policy for parallel-capable stages
+execution_policy:
+  default_mode: "parallel"
+
+  stage_classification:
+    parallel_capable:
+      - "01-brainstorm"
+      - "03-planning"
+      - "04-ui-ux"
+      - "07-refactoring"
+      - "09-testing"
+    sequential_only:
+      - "02-research"
+      - "05-task-management"
+      - "06-implementation"
+      - "08-qa"
+      - "10-deployment"
+
+# Consolidation workflow - Claude Code synthesis protocol
+consolidation_workflow:
+  synthesizer: "claudecode"
+
+  phases:
+    - name: "collect"
+      description: "Gather all parallel model outputs"
+    - name: "analyze"
+      description: "Identify commonalities and consensus"
+    - name: "evaluate"
+      description: "Compare differences and unique insights"
+    - name: "synthesize"
+      description: "Create unified output"
+    - name: "validate"
+      description: "Verify completeness and quality"
+
+  output:
+    storage_path: "state/collaborations/"
+    input_pattern: "output_{model}.md"
+    synthesis_log: "synthesis_log.md"
+
+  quality_threshold: 0.8
+
 collaboration_modes:
   # Parallel Execution: Execute same task with multiple AIs simultaneously and synthesize
   parallel_execution:

package/template/config/models.yaml

@@ -187,13 +187,13 @@ stage_assignments:
 
   "03-planning":
     primary: "gemini"
-    secondary: null
-    collaboration: null
+    secondary: "claudecode"
+    collaboration: "parallel"
 
   "04-ui-ux":
     primary: "gemini"
-    secondary: null
-    collaboration: null
+    secondary: "claudecode"
+    collaboration: "parallel"
 
   "05-task-management":
     primary: "claudecode"
@@ -208,7 +208,7 @@ stage_assignments:
   "07-refactoring":
     primary: "codex"
     secondary: "claudecode"
-    collaboration: "sequential"
+    collaboration: "parallel"
 
   "08-qa":
     primary: "claudecode"
@@ -217,8 +217,8 @@ stage_assignments:
 
   "09-testing":
     primary: "codex"
-    secondary: null
-    collaboration: null
+    secondary: "claudecode"
+    collaboration: "parallel"
 
   "10-deployment":
     primary: "claudecode"