claude-symphony 0.0.4 → 0.0.6

package/README.md

@@ -6,7 +6,6 @@
 
 Multi-AI Orchestration Framework for Software Development
 
-[![CI](https://github.com/znehraks/claude-symphony/actions/workflows/ci.yml/badge.svg)](https://github.com/znehraks/claude-symphony/actions/workflows/ci.yml)
 [![npm version](https://badge.fury.io/js/claude-symphony.svg)](https://www.npmjs.com/package/claude-symphony)
 [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
 

package/bin/create.js

@@ -3,7 +3,8 @@
 import fs from 'fs';
 import path from 'path';
 import { fileURLToPath } from 'url';
-import { input } from '@inquirer/prompts';
+import { input, confirm } from '@inquirer/prompts';
+import yaml from 'js-yaml';
 
 const __filename = fileURLToPath(import.meta.url);
 const __dirname = path.dirname(__filename);
@@ -79,9 +80,106 @@ async function collectBriefInfo() {
     featureNum++;
   }
 
+  // === Development mode configuration ===
+  console.log('');
+  log('⚙️ Development mode configuration', 'yellow');
+
+  info.sprintMode = await confirm({
+    message: '🔄 Enable sprint-based iterative development?',
+    default: true
+  });
+
+  if (info.sprintMode) {
+    info.defaultSprints = await input({
+      message: '📊 Default number of sprints:',
+      default: '3',
+      validate: (v) => {
+        const num = parseInt(v);
+        if (isNaN(num) || num < 1) return 'Enter a number >= 1';
+        if (num > 100) return '⚠️ Maximum 100 sprints allowed';
+        return true;
+      }
+    });
+  }
+
+  info.notionEnabled = await confirm({
+    message: '📋 Enable Notion task integration?',
+    default: true
+  });
+
   return info;
 }
 
+function applyConfigSettings(targetDir, info) {
+  const pipelinePath = path.join(targetDir, 'config', 'pipeline.yaml');
+  const taskConfigPath = path.join(targetDir, 'stages', '05-task-management', 'config.yaml');
+  const progressPath = path.join(targetDir, 'state', 'progress.json');
+
+  // Sprint mode settings
+  if (fs.existsSync(pipelinePath)) {
+    try {
+      let content = fs.readFileSync(pipelinePath, 'utf8');
+      const config = yaml.load(content);
+
+      if (config.sprint_mode) {
+        config.sprint_mode.enabled = info.sprintMode ?? true;
+        config.sprint_mode.sprint_config.default_sprints = parseInt(info.defaultSprints) || 3;
+      }
+
+      fs.writeFileSync(pipelinePath, yaml.dump(config, { lineWidth: -1 }));
+    } catch (e) {
+      // Silently continue if YAML parsing fails
+    }
+  }
+
+  // Notion settings (if config exists)
+  if (fs.existsSync(taskConfigPath)) {
+    try {
+      let content = fs.readFileSync(taskConfigPath, 'utf8');
+      const config = yaml.load(content);
+
+      if (config && !config.notion_integration) {
+        config.notion_integration = { enabled: info.notionEnabled ?? true };
+      } else if (config && config.notion_integration) {
+        config.notion_integration.enabled = info.notionEnabled ?? true;
+      }
+
+      fs.writeFileSync(taskConfigPath, yaml.dump(config, { lineWidth: -1 }));
+    } catch (e) {
+      // Silently continue if YAML parsing fails
+    }
+  }
+
+  // Update progress.json with sprint count
+  if (fs.existsSync(progressPath)) {
+    try {
+      const progress = JSON.parse(fs.readFileSync(progressPath, 'utf8'));
+      const sprintCount = parseInt(info.defaultSprints) || 3;
+
+      if (progress.current_iteration) {
+        progress.current_iteration.total_sprints = sprintCount;
+      }
+
+      // Regenerate sprints object based on count
+      if (progress.sprints) {
+        progress.sprints = {};
+        for (let i = 1; i <= sprintCount; i++) {
+          progress.sprints[`Sprint ${i}`] = {
+            status: "pending",
+            tasks_total: 0,
+            tasks_completed: 0,
+            checkpoint_id: null
+          };
+        }
+      }
+
+      fs.writeFileSync(progressPath, JSON.stringify(progress, null, 2));
+    } catch (e) {
+      // Silently continue if JSON parsing fails
+    }
+  }
+}
+
 function generateBriefContent(projectName, info) {
   // Core features formatting
   let featuresContent;
@@ -220,7 +318,13 @@ ${colors.yellow}After creation:${colors.reset}
     log('✓ progress.json initialized', 'green');
   }
 
-  // 5. Create project_brief.md
+  // 5. Apply configuration settings (sprint mode, notion)
+  if (!skipPrompts) {
+    applyConfigSettings(targetDir, briefInfo);
+    log('✓ Configuration settings applied', 'green');
+  }
+
+  // 6. Create project_brief.md
   const briefPath = path.join(targetDir, 'stages', '01-brainstorm', 'inputs', 'project_brief.md');
   const briefDir = path.dirname(briefPath);
 
@@ -232,7 +336,7 @@ ${colors.yellow}After creation:${colors.reset}
   fs.writeFileSync(briefPath, briefContent);
   log('✓ project_brief.md created', 'green');
 
-  // 6. Completion message
+  // 7. Completion message
   console.log('');
   log('━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━', 'green');
   log(`✓ Project '${actualProjectName}' created successfully!`, 'green');
@@ -253,6 +357,19 @@ ${colors.yellow}After creation:${colors.reset}
   console.log('  → 05-task-management → 06-implementation → 07-refactoring');
   console.log('  → 08-qa → 09-testing → 10-deployment');
   console.log('');
+  // Plugin installation message (more prominent)
+  console.log('');
+  log('━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━', 'yellow');
+  log('🎯 Recommended: Install claude-hud plugin', 'yellow');
+  log('━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━', 'yellow');
+  console.log('');
+  console.log('  claude-hud visualizes context usage, tool activity, and progress.');
+  console.log('');
+  console.log('  Run these commands in Claude Code:');
+  console.log('');
+  log('    /plugin marketplace add jarrodwatts/claude-hud', 'cyan');
+  log('    /plugin install claude-hud', 'cyan');
+  console.log('');
 }
 
 main().catch(err => {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "claude-symphony",
-  "version": "0.0.4",
+  "version": "0.0.6",
   "description": "Multi-AI Orchestration Framework - Create new projects with 10-stage development workflow",
   "type": "module",
   "bin": {
@@ -39,6 +39,7 @@
   },
   "homepage": "https://github.com/znehraks/claude-symphony#readme",
   "dependencies": {
-    "@inquirer/prompts": "^7.10.1"
+    "@inquirer/prompts": "^7.10.1",
+    "js-yaml": "^4.1.0"
   }
 }

package/template/.claude/settings.json

@@ -24,7 +24,6 @@
     "stop": ".claude/hooks/stop.sh - auto /compact",
     "session_start": ".claude/hooks/session-start.sh - auto recovery"
   },
-
   "commands": {
     "init-project": {
       "description": "Initialize new project",
@@ -127,7 +126,6 @@
       "file": "commands/validate.md"
     }
   },
-
   "skills": {
     "smart-handoff": {
       "description": "Smart context extraction and HANDOFF generation",

package/template/.claude/skills/context-compression/README.md

@@ -119,3 +119,42 @@ Adjust thresholds in settings.json:
   }
 }
 ```
+
+## Claude Code Built-in vs Custom Tools
+
+### Built-in Summarization (`/compact`)
+Claude Code has built-in context summarization that:
+- Automatically condenses conversation history
+- Preserves key decisions and context
+- Runs without external tools
+
+**When to use:** Quick compression when context is getting large
+
+### Custom Pipeline (`context-manager.sh`)
+This project provides additional tooling:
+- Token estimation based on file content
+- Auto-snapshot generation
+- Stage-aware context tracking
+- Recovery file generation
+
+**When to use:** Full state management with recovery capability
+
+### claude-hud Plugin Integration
+
+For real-time context monitoring, install the claude-hud plugin:
+
+```bash
+/plugin marketplace add jarrodwatts/claude-hud
+/plugin install claude-hud
+```
+
+**Benefits with claude-hud:**
+- Visual context usage in statusline
+- Proactive warnings before thresholds
+- No manual `/context` checks needed
+
+**Combined workflow:**
+1. claude-hud monitors context visually
+2. When warning appears, run `./scripts/context-manager.sh --auto-compact warning`
+3. Script saves snapshot then triggers `/compact`
+4. Recovery possible from saved snapshots

package/template/CLAUDE.md

@@ -71,6 +71,46 @@
 2. **externalize_code**: Replace code blocks with file references
 3. **handoff_generation**: Externalize current state to HANDOFF.md
 
+### Context Check Protocol
+
+> Run `/context` every 5 completed tasks to check token usage.
+
+| Remaining Context | Status | Recommended Action |
+|-------------------|--------|-------------------|
+| **60%+** | Normal | Continue working |
+| **50-60%** | Warning | Consider `/compact` |
+| **40-50%** | Action | Run `/compact`, save state |
+| **<40%** | Critical | `/clear` or handoff required |
+
+**Protocol Steps:**
+1. After every 5 tasks, run `/context` to check usage
+2. If warning level reached, run `./scripts/context-manager.sh --auto-compact warning`
+3. If critical level reached, generate HANDOFF.md before `/clear`
+
+## Recommended Plugins
+
+### 🎯 claude-hud (Context Monitoring) - Highly Recommended!
+
+Visualizes context usage, tool activity, and todo progress in the statusline.
+
+**Installation (run in Claude Code):**
+```bash
+/plugin marketplace add jarrodwatts/claude-hud
+/plugin install claude-hud
+
+# Step 3: Setup (optional)
+/claude-hud:setup
+```
+
+**Features:**
+- Context window usage visualization
+- Tool activity tracking
+- Agent state monitoring
+- Todo progress display
+- Git branch info
+
+**GitHub:** https://github.com/jarrodwatts/claude-hud
+
 ## Stage Transition Protocol
 
 ### Required Sequence
@@ -117,9 +157,32 @@
 ### Navigation Commands
 | Command | Description |
 |---------|-------------|
-| `/next` | Transition to next stage |
+| `/next` | Transition to next stage (or next Sprint in Stage 06) |
+| `/next --stage` | Force stage transition (skip Sprint check) |
 | `/restore` | Restore from checkpoint |
 
+### Sprint Commands
+| Command | Description |
+|---------|-------------|
+| `/sprint` | Show current sprint status |
+| `/sprint tasks` | List tasks for current sprint |
+| `/sprint complete` | Mark current sprint as complete |
+
+### Loop-back Commands
+| Command | Description |
+|---------|-------------|
+| `/goto <stage>` | Jump to previous stage (intentional loop-back) |
+| `/goto --list` | Show available stages for loop-back |
+| `/goto --history` | Show loop-back history |
+
+### Configuration Commands
+| Command | Description |
+|---------|-------------|
+| `/config sprint enable` | Enable sprint mode |
+| `/config sprint disable` | Disable sprint mode (single-pass) |
+| `/config sprint status` | Show current iteration settings |
+| `/config sprint count <n>` | Set default sprint count |
+
 ### Stage Shortcut Commands
 | Command | Stage |
 |---------|-------|

package/template/config/ai_fallbacks.yaml

@@ -0,0 +1,130 @@
+# AI Model Fallback Strategy
+# Principle: Claude=MCP tools, Codex=Pure code analysis, Gemini=Creative tasks
+
+fallback_strategy:
+  default_fallback: claude
+  auto_switch: true
+  retry_count: 2
+  retry_delay_ms: 3000
+
+# Stage-specific primary model (based on MCP usage)
+# MCP tools: exa, web_search, context7, playwright, notion, figma, etc.
+stage_overrides:
+  01-brainstorm:
+    primary: gemini      # Creative idea generation
+    fallback: claude
+    mcp_required: false
+    rationale: "Brainstorming benefits from Gemini's creative divergent thinking"
+
+  02-research:
+    primary: claude      # Uses exa, web_search MCP tools
+    fallback: gemini
+    mcp_required: true
+    mcp_tools: [exa, web_search]
+    rationale: "Research requires MCP tools for web search and data gathering"
+
+  03-planning:
+    primary: gemini      # Architecture design (creative)
+    fallback: claude
+    mcp_required: false
+    rationale: "System architecture benefits from creative exploration"
+
+  04-ui-ux:
+    primary: gemini      # Design creativity
+    fallback: claude
+    mcp_required: false  # figma MCP is optional
+    mcp_tools: [figma]
+    rationale: "UI/UX design requires creative visual thinking"
+
+  05-task-management:
+    primary: claude      # Uses notion MCP
+    fallback: gemini
+    mcp_required: true
+    mcp_tools: [notion]
+    rationale: "Task management integrates with Notion via MCP"
+
+  06-implementation:
+    primary: claude      # Uses context7 MCP for docs
+    fallback: codex
+    mcp_required: true
+    mcp_tools: [context7, serena]
+    rationale: "Implementation needs context7 for up-to-date documentation"
+
+  07-refactoring:
+    primary: codex       # Pure code analysis/refactoring
+    fallback: claude
+    mcp_required: false
+    rationale: "Refactoring is pure code analysis - Codex specialty"
+
+  08-qa:
+    primary: claude      # May use playwright MCP
+    fallback: codex
+    mcp_required: false  # playwright optional for manual QA
+    mcp_tools: [playwright]
+    rationale: "QA can benefit from browser automation via playwright"
+
+  09-testing:
+    primary: claude      # Uses playwright MCP for E2E tests
+    fallback: codex      # Unit tests don't need MCP
+    mcp_required: true
+    mcp_tools: [playwright]
+    rationale: "E2E testing requires playwright MCP for browser automation"
+
+  10-deployment:
+    primary: claude      # General task handling
+    fallback: codex
+    mcp_required: false
+    rationale: "Deployment scripts and CI/CD configuration"
+
+# Fallback trigger conditions
+triggers:
+  - api_failure          # API call failed
+  - rate_limit           # Rate limit exceeded
+  - quality_threshold_fail  # Output quality below threshold
+  - timeout              # Response timeout
+  - context_overflow     # Context window exceeded
+
+# Quality thresholds for auto-fallback
+quality_thresholds:
+  code_quality: 0.7      # Lint/typecheck pass rate
+  test_coverage: 0.6     # Minimum coverage for fallback
+  response_coherence: 0.8  # Response quality score
+
+# Logging configuration
+logging:
+  enabled: true
+  destination: HANDOFF.md
+  log_format: |
+    ## AI Model Switch Log
+    | Time | From | To | Reason | Stage |
+    |------|------|----|---------| ------|
+
+# Model capabilities reference
+model_capabilities:
+  claude:
+    strengths:
+      - MCP tool integration
+      - Code generation accuracy
+      - Context understanding
+    weaknesses:
+      - Creative brainstorming
+    best_for: [implementation, testing, task_management]
+
+  gemini:
+    strengths:
+      - Creative exploration
+      - Rapid ideation
+      - Visual thinking
+    weaknesses:
+      - No MCP integration
+    best_for: [brainstorming, planning, ui_ux]
+
+  codex:
+    strengths:
+      - Deep code analysis
+      - Refactoring patterns
+      - Code comprehension
+    weaknesses:
+      - No MCP integration
+      - Limited creativity
+    best_for: [refactoring, code_review, unit_testing]