claude-flow 1.0.31 → 1.0.32

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "claude-flow",
-  "version": "1.0.31",
+  "version": "1.0.32",
   "description": "Advanced AI agent orchestration system for Claude Code",
   "main": "src/cli/main.ts",
   "bin": {

package/src/cli/command-registry.js

@@ -16,13 +16,22 @@ export const commandRegistry = new Map();
 export function registerCoreCommands() {
   commandRegistry.set('init', {
     handler: initCommand,
-    description: 'Initialize Claude Code integration files',
+    description: 'Initialize Claude Code integration files and SPARC development environment',
     usage: 'init [--force] [--minimal] [--sparc]',
     examples: [
-      'init --sparc',
-      'init --force --minimal',
-      'init --sparc --force'
-    ]
+      'npx claude-flow@latest init --sparc  # Recommended: Full SPARC setup',
+      'init --sparc                         # Initialize with SPARC modes',
+      'init --force --minimal               # Minimal setup, overwrite existing',
+      'init --sparc --force                 # Force SPARC setup'
+    ],
+    details: `
+The --sparc flag creates a complete development environment:
+  • .roomodes file containing 17 specialized SPARC modes
+  • CLAUDE.md for AI-readable project instructions
+  • Pre-configured modes: architect, code, tdd, debug, security, and more
+  • Ready for TDD workflows and automated code generation
+  
+First-time users should run: npx claude-flow@latest init --sparc`
   });
 
   commandRegistry.set('memory', {
@@ -40,12 +49,13 @@ export function registerCoreCommands() {
   commandRegistry.set('sparc', {
     handler: sparcCommand,
     description: 'SPARC development mode operations',
-    usage: 'sparc <subcommand> [options]',
+    usage: 'sparc [subcommand] [options]',
     examples: [
-      'sparc modes',
-      'sparc run code "implement feature"',
-      'sparc tdd "feature description"',
-      'sparc info architect'
+      'sparc "orchestrate full app development"  # Default: sparc orchestrator',
+      'sparc modes                               # List available modes',
+      'sparc run code "implement feature"        # Run specific mode',
+      'sparc tdd "feature description"           # TDD workflow',
+      'sparc info architect                      # Mode details'
     ]
   });
 
@@ -184,12 +194,20 @@ export function showCommandHelp(name) {
   
   console.log(`Command: ${name}`);
   console.log(`Description: ${command.description}`);
-  console.log(`Usage: ${command.usage}`);
+  console.log(`Usage: claude-flow ${command.usage}`);
+  
+  if (command.details) {
+    console.log(command.details);
+  }
   
   if (command.examples.length > 0) {
     console.log('\nExamples:');
     for (const example of command.examples) {
-      console.log(`  claude-flow ${example}`);
+      if (example.startsWith('npx')) {
+        console.log(`  ${example}`);
+      } else {
+        console.log(`  claude-flow ${example}`);
+      }
     }
   }
 }

package/src/cli/simple-cli.js

@@ -22,6 +22,14 @@ function printHelp() {
 USAGE:
   claude-flow <command> [options]
 
+INSTALLATION & SETUP:
+  npx claude-flow@latest init --sparc  # Initialize SPARC development environment
+  
+  The --sparc flag creates:
+  • .roomodes file with 17 pre-configured SPARC modes
+  • CLAUDE.md for project instructions
+  • Ready-to-use TDD and code generation environment
+
 KEY COMMANDS:
   init [--sparc]                       Initialize project with Claude integration
   agent spawn <type> [--name <name>]   Create AI agent (researcher, coder, analyst)
@@ -38,10 +46,11 @@ COMMAND CATEGORIES:
   Enterprise:   project, deploy, cloud, security, analytics
 
 QUICK START:
-  claude-flow init --sparc             # Initialize with SPARC development
-  claude-flow agent spawn researcher   # Create research agent
-  claude-flow sparc modes              # List SPARC development modes
-  claude-flow sparc tdd "feature"      # Run TDD workflow
+  npx claude-flow@latest init --sparc  # First-time setup with SPARC modes
+  claude-flow sparc modes              # List available development modes
+  claude-flow sparc "build app"        # Run SPARC orchestrator (default)
+  claude-flow sparc run code "feature" # Run specific mode (auto-coder)
+  claude-flow sparc tdd "tests"        # Run test-driven development
   claude-flow memory store key "data"  # Store information
   claude-flow status                   # Check system status
 

package/src/cli/simple-commands/init.js

@@ -2,6 +2,12 @@
 import { printSuccess, printError, printWarning } from '../utils.js';
 
 export async function initCommand(subArgs, flags) {
+  // Show help if requested
+  if (flags.help || flags.h || subArgs.includes('--help') || subArgs.includes('-h')) {
+    showInitHelp();
+    return;
+  }
+  
   // Parse init options
   const initForce = subArgs.includes('--force') || subArgs.includes('-f') || flags.force;
   const initMinimal = subArgs.includes('--minimal') || subArgs.includes('-m') || flags.minimal;
@@ -905,4 +911,39 @@ You can customize this environment by:
 
 For more information, see: https://github.com/ruvnet/claude-code-flow/docs/sparc.md
 `;
+}
+
+function showInitHelp() {
+  console.log('Initialize Claude Code integration files');
+  console.log();
+  console.log('Usage: claude-flow init [options]');
+  console.log();
+  console.log('Options:');
+  console.log('  --sparc, -s     Initialize with SPARC development environment (recommended)');
+  console.log('  --minimal, -m   Create minimal configuration files');
+  console.log('  --force, -f     Overwrite existing files');
+  console.log('  --help, -h      Show this help message');
+  console.log();
+  console.log('Examples:');
+  console.log('  npx claude-flow@latest init --sparc   # Recommended first-time setup');
+  console.log('  claude-flow init --sparc              # Initialize with SPARC modes');
+  console.log('  claude-flow init --minimal            # Minimal setup');
+  console.log('  claude-flow init --force              # Overwrite existing files');
+  console.log();
+  console.log('What --sparc creates:');
+  console.log('  • .roomodes file with 17 specialized SPARC development modes');
+  console.log('  • CLAUDE.md with SPARC-enhanced project instructions');
+  console.log('  • memory/ directory for persistent context storage');
+  console.log('  • .roo/ directory with templates and workflows');
+  console.log('  • Pre-configured for TDD, architecture, and code generation');
+  console.log();
+  console.log('Available SPARC modes include:');
+  console.log('  - architect: System design and architecture');
+  console.log('  - code: Clean, modular implementation');
+  console.log('  - tdd: Test-driven development');
+  console.log('  - debug: Advanced debugging and optimization');
+  console.log('  - security-review: Security analysis and hardening');
+  console.log('  - And 12 more specialized modes...');
+  console.log();
+  console.log('Learn more: https://github.com/ruvnet/claude-code-flow');
 }

package/src/cli/simple-commands/sparc-modes/architect.js

@@ -36,7 +36,21 @@ export function getArchitectOrchestration(taskDescription, memoryNamespace) {
    - Identify tasks for other SPARC modes
    - Store plan: \`npx claude-flow memory store ${memoryNamespace}_implementation_plan "Phase 1: Core auth (tdd mode). Phase 2: User management (code mode). Phase 3: Integration (integration mode)."\`
 
-5. **Deliverables**
+5. **Directory Safety**
+   - **IMPORTANT**: All files should be created in the current working directory
+   - **DO NOT** create files in system directories or node_modules
+   - For named projects, create a subdirectory: \\\`mkdir project-name && cd project-name\\\`
+   - Use relative paths from your working directory
+   - Example structure:
+     \\\`\\\`\\\`
+     ./ (current directory)
+     ├── architecture/
+     │   ├── system-overview.md
+     │   └── api-specifications.md
+     └── implementation-plan.md
+     \\\`\\\`\\\`
+
+6. **Deliverables**
    - architecture/
      - system-overview.md (with Mermaid diagrams)
      - api-specifications.md (OpenAPI/AsyncAPI specs)
@@ -49,5 +63,33 @@ export function getArchitectOrchestration(taskDescription, memoryNamespace) {
 After completing architecture, delegate to appropriate modes:
 - \`npx claude-flow sparc run spec-pseudocode "Create detailed pseudocode for ${taskDescription}" --non-interactive\`
 - \`npx claude-flow sparc run tdd "Implement core authentication module" --non-interactive\`
-- \`npx claude-flow sparc run security-review "Review architecture for vulnerabilities" --non-interactive\``;
+- \`npx claude-flow sparc run security-review "Review architecture for vulnerabilities" --non-interactive\`
+
+## 🏗️ Parallel Architecture Analysis with BatchTool
+Leverage concurrent analysis for comprehensive system design:
+
+\`\`\`bash
+# Parallel architecture research and analysis
+batchtool run --parallel --tag "architecture-${taskDescription}" \\
+  "npx claude-flow sparc run ask 'research scalability patterns for ${taskDescription}' --non-interactive" \\
+  "npx claude-flow sparc run security-review 'analyze security requirements' --non-interactive" \\
+  "npx claude-flow sparc run ask 'research integration patterns' --non-interactive" \\
+  "npx claude-flow sparc run ask 'analyze performance requirements' --non-interactive"
+
+# Boomerang architecture refinement
+batchtool orchestrate --boomerang --name "architecture-refinement" \\
+  --analyze "npx claude-flow sparc run architect 'initial system design' --non-interactive" \\
+  --review "npx claude-flow sparc run security-review 'review architecture' --non-interactive" \\
+  --refine "npx claude-flow sparc run architect 'refine based on security feedback' --non-interactive" \\
+  --validate "npx claude-flow sparc run integration 'validate integration points' --non-interactive" \\
+  --finalize "npx claude-flow sparc run docs-writer 'document final architecture' --non-interactive"
+
+# Component-wise architecture development
+batchtool run --component-parallel \\
+  --frontend "npx claude-flow sparc run architect 'design frontend architecture' --non-interactive" \\
+  --backend "npx claude-flow sparc run architect 'design backend architecture' --non-interactive" \\
+  --data "npx claude-flow sparc run architect 'design data architecture' --non-interactive" \\
+  --infra "npx claude-flow sparc run devops 'design infrastructure' --non-interactive" \\
+  --integrate "npx claude-flow sparc run integration 'design integration layer' --non-interactive:wait-for=all"
+\`\`\``;
 }

package/src/cli/simple-commands/sparc-modes/code.js

@@ -3,7 +3,9 @@ export function getCodeOrchestration(taskDescription, memoryNamespace) {
   return `
 ## Task Orchestration Steps
 
-1. **Context & Architecture Review** (5 mins)
+1. **Project Directory Setup & Context Review** (5 mins)
+   - Verify current working directory and create project structure
+   - For named projects (e.g., "hello-world"), create as subdirectory
    - Review implementation task: "${taskDescription}"
    - Query architecture and pseudocode: 
      \`\`\`bash
@@ -16,7 +18,8 @@ export function getCodeOrchestration(taskDescription, memoryNamespace) {
    - Check for any blocking dependencies
 
 2. **Project Setup & Configuration** (10 mins)
-   - Initialize project structure following clean architecture
+   - Initialize project structure in current directory or subdirectory
+   - IMPORTANT: Use pwd to verify you're NOT in node_modules/
    - Set up environment configuration (NO hardcoded values):
      - Create .env.example with all required variables
      - Set up config/ directory with environment loaders
@@ -55,7 +58,15 @@ export function getCodeOrchestration(taskDescription, memoryNamespace) {
    - Update README with setup instructions
    - Store completion: \`npx claude-flow memory store ${memoryNamespace}_code_complete "Implementation complete. All modules < 500 lines. No hardcoded secrets. Ready for testing and integration."\`
 
+## Directory Safety Check
+Before creating any files:
+1. Run \`pwd\` to verify current directory
+2. Ensure you're NOT in /node_modules/ or any system directory
+3. If creating a named project, create it as a subdirectory
+4. Example: For "hello-world", create ./hello-world/ in current directory
+
 ## Deliverables
+All files should be created relative to the current working directory:
 - src/
   - domain/ (business logic, < 500 lines per file)
   - application/ (use cases, < 500 lines per file)
@@ -81,5 +92,32 @@ export function getCodeOrchestration(taskDescription, memoryNamespace) {
 After implementation, delegate to:
 - \`npx claude-flow sparc run tdd "Write comprehensive tests for ${taskDescription}" --non-interactive\`
 - \`npx claude-flow sparc run integration "Integrate ${taskDescription} with existing systems" --non-interactive\`
-- \`npx claude-flow sparc run security-review "Security audit for ${taskDescription}" --non-interactive\``;
+- \`npx claude-flow sparc run security-review "Security audit for ${taskDescription}" --non-interactive\`
+
+## 🚀 Parallel Development with BatchTool
+Accelerate development by running multiple tasks concurrently:
+
+\`\`\`bash
+# Parallel feature implementation
+batchtool run --parallel --max-concurrent 4 \\
+  "npx claude-flow sparc run code 'implement user model' --non-interactive" \\
+  "npx claude-flow sparc run code 'implement auth middleware' --non-interactive" \\
+  "npx claude-flow sparc run code 'implement API endpoints' --non-interactive" \\
+  "npx claude-flow sparc run code 'implement database schema' --non-interactive"
+
+# Boomerang pattern for feature development
+batchtool orchestrate --boomerang \\
+  --research "npx claude-flow sparc run ask 'best practices for ${taskDescription}' --non-interactive" \\
+  --design "npx claude-flow sparc run architect 'design ${taskDescription}' --non-interactive" \\
+  --implement "npx claude-flow sparc run code 'build ${taskDescription}' --non-interactive" \\
+  --test "npx claude-flow sparc run tdd 'test ${taskDescription}' --non-interactive" \\
+  --optimize "npx claude-flow sparc run optimization 'optimize ${taskDescription}' --non-interactive"
+
+# Concurrent module development with dependencies
+batchtool run --dependency-aware \\
+  --task "auth:npx claude-flow sparc run code 'auth module' --non-interactive" \\
+  --task "user:npx claude-flow sparc run code 'user module' --non-interactive" \\
+  --task "api:npx claude-flow sparc run code 'API layer' --non-interactive:depends=auth,user" \\
+  --task "tests:npx claude-flow sparc run tdd 'all tests' --non-interactive:depends=api"
+\`\`\``;
 }

package/src/cli/simple-commands/sparc-modes/index.js

@@ -64,12 +64,23 @@ export function getModeOrchestration(modeSlug, taskDescription, memoryNamespace)
  */
 export function createSparcPrompt(mode, taskDescription, memoryNamespace) {
   const orchestration = getModeOrchestration(mode.slug, taskDescription, memoryNamespace);
+  const cwd = Deno.cwd();
   
   return `# ${mode.name} - Task Execution
 
 ## 🎯 Your Mission
 Build exactly what the user requested: "${taskDescription}"
 
+## 📁 IMPORTANT: Project Directory
+**Current Working Directory:** ${cwd}
+
+⚠️ **CRITICAL INSTRUCTIONS:**
+- Create ALL project files in the current working directory: ${cwd}
+- NEVER create files in node_modules/ or any claude-flow directories
+- If the task specifies a project name (e.g., "hello-world"), create it as a subdirectory in ${cwd}
+- Use paths relative to ${cwd} for all file operations
+- Example: If creating "hello-world" app, use ${cwd}/hello-world/
+
 ## 🚀 Your Role
 ${mode.roleDefinition}
 
@@ -110,20 +121,70 @@ npx claude-flow agent list
 npx claude-flow monitor
 \`\`\`
 
+### 🚀 Parallel Execution with BatchTool
+Use BatchTool to orchestrate multiple SPARC modes concurrently in a boomerang pattern:
+
+\`\`\`bash
+# Example: Parallel development workflow
+batchtool run --parallel \\
+  "npx claude-flow sparc run architect 'design user authentication system' --non-interactive" \\
+  "npx claude-flow sparc run security-review 'analyze authentication requirements' --non-interactive" \\
+  "npx claude-flow sparc run spec-pseudocode 'create auth flow pseudocode' --non-interactive"
+
+# Boomerang Pattern: Research → Design → Implement → Test → Refine
+batchtool orchestrate --boomerang \\
+  --phase1 "npx claude-flow sparc run ask 'research best auth practices' --non-interactive" \\
+  --phase2 "npx claude-flow sparc run architect 'design based on research' --non-interactive" \\
+  --phase3 "npx claude-flow sparc run code 'implement auth system' --non-interactive" \\
+  --phase4 "npx claude-flow sparc run tdd 'test auth implementation' --non-interactive" \\
+  --phase5 "npx claude-flow sparc run optimization 'refine auth performance' --non-interactive"
+
+# Concurrent Feature Development
+batchtool run --concurrent --max-parallel 3 \\
+  "npx claude-flow sparc run code 'implement login feature' --non-interactive" \\
+  "npx claude-flow sparc run code 'implement registration feature' --non-interactive" \\
+  "npx claude-flow sparc run code 'implement password reset' --non-interactive" \\
+  "npx claude-flow sparc run tdd 'create auth test suite' --non-interactive"
+\`\`\`
+
+#### Boomerang Orchestration Pattern
+The boomerang pattern allows for iterative development where results from one phase inform the next:
+1. **Research Phase**: Gather requirements and best practices
+2. **Design Phase**: Create architecture based on research
+3. **Implementation Phase**: Build according to design
+4. **Testing Phase**: Validate implementation
+5. **Refinement Phase**: Optimize based on test results
+6. **Loop Back**: Results feed back to improve the cycle
+
+Benefits of --non-interactive mode with BatchTool:
+- No manual intervention required
+- Parallel execution of independent tasks
+- Automatic result collection and aggregation
+- Progress tracking across all concurrent operations
+- Efficient resource utilization
+
 ## ⚡ Execution Guidelines
 
 1. **Focus on User's Project**
    - Build what they asked for, not improvements to claude-flow
-   - Create files in the current directory for their project
-   - Use appropriate project structure for their needs
-
-2. **Quality Standards**
+   - Create files ONLY in the current working directory: ${cwd}
+   - NEVER create files in node_modules/ or system directories
+   - If creating a named project, make it a subdirectory of ${cwd}
+   - Use appropriate project structure relative to ${cwd}
+
+2. **Directory Rules**
+   - Current directory: ${cwd}
+   - Create new projects as: ${cwd}/<project-name>/
+   - Use relative paths from ${cwd} for all operations
+   - Verify you're in the correct directory before creating files
+
+3. **Quality Standards**
    - Keep all files under 500 lines
    - Never hardcode secrets or credentials
    - Use environment variables and config files
    - Write clean, maintainable code
 
-3. **Communication**
+4. **Communication**
    - Store progress updates in memory
    - Document key decisions
    - Ask for clarification if needed

package/src/cli/simple-commands/sparc-modes/integration.js

@@ -30,7 +30,24 @@ export function getIntegrationOrchestration(taskDescription, memoryNamespace) {
    - Check performance metrics
    - Validate data integrity
 
-5. **Deliverables**
+5. **Directory Safety**
+   - **IMPORTANT**: All integration files should be created in the current working directory
+   - **DO NOT** create files in system directories or node_modules
+   - For named projects, create a subdirectory: \`mkdir project-name && cd project-name\`
+   - Use relative paths from your working directory
+   - Suggested structure for integration code:
+     \`\`\`
+     ./ (current directory)
+     ├── integrations/
+     │   ├── adapters/
+     │   ├── transformers/
+     │   └── handlers/
+     ├── config/
+     └── tests/
+         └── integration/
+     \`\`\`
+
+6. **Deliverables**
    - Integration layer code
    - Configuration templates
    - Integration test suite

package/src/cli/simple-commands/sparc-modes/sparc-orchestrator.js

@@ -5,6 +5,34 @@ export function getSparcOrchestratorOrchestration(taskDescription, memoryNamespa
 
 Welcome! I'm your SPARC Orchestrator, ready to break down "${taskDescription}" into manageable subtasks following the SPARC methodology.
 
+## 🎯 BatchTool Parallel Orchestration
+For maximum efficiency, I can orchestrate multiple SPARC modes concurrently using BatchTool:
+
+\`\`\`bash
+# Full SPARC Workflow with BatchTool (Boomerang Pattern)
+batchtool orchestrate --boomerang --name "${taskDescription}" \\
+  --phase1-parallel \\
+    "npx claude-flow sparc run ask 'research requirements for ${taskDescription}' --non-interactive" \\
+    "npx claude-flow sparc run security-review 'identify security needs for ${taskDescription}' --non-interactive" \\
+  --phase2-sequential \\
+    "npx claude-flow sparc run spec-pseudocode 'create specifications from research' --non-interactive" \\
+    "npx claude-flow sparc run architect 'design system architecture' --non-interactive" \\
+  --phase3-parallel \\
+    "npx claude-flow sparc run code 'implement core features' --non-interactive" \\
+    "npx claude-flow sparc run code 'implement authentication' --non-interactive" \\
+    "npx claude-flow sparc run code 'implement data layer' --non-interactive" \\
+  --phase4-sequential \\
+    "npx claude-flow sparc run integration 'integrate all components' --non-interactive" \\
+    "npx claude-flow sparc run tdd 'comprehensive testing' --non-interactive" \\
+  --phase5-parallel \\
+    "npx claude-flow sparc run optimization 'performance tuning' --non-interactive" \\
+    "npx claude-flow sparc run docs-writer 'create documentation' --non-interactive" \\
+    "npx claude-flow sparc run devops 'deployment setup' --non-interactive"
+
+# Monitor all parallel executions
+batchtool monitor --dashboard
+\`\`\`
+
 ## Task Orchestration Steps
 
 1. **Project Analysis & Planning** (15 mins)

package/src/cli/simple-commands/sparc-modes/tdd.js

@@ -6,11 +6,11 @@ export function getTddOrchestration(taskDescription, memoryNamespace) {
 1. **Test Planning & Analysis** (10 mins)
    - Analyze requirements: "${taskDescription}"
    - Query existing code and architecture:
-     \`\`\`bash
+     \\\`\\\`\\\`bash
      npx claude-flow memory query ${memoryNamespace}_architecture
      npx claude-flow memory query ${memoryNamespace}_implementation
      npx claude-flow memory query ${memoryNamespace}_tech_specs
-     \`\`\`
+     \\\`\\\`\\\`
    - Define test boundaries and acceptance criteria
    - Plan test structure (unit, integration, e2e)
    - Identify test doubles needed (mocks, stubs, spies)
@@ -18,13 +18,13 @@ export function getTddOrchestration(taskDescription, memoryNamespace) {
 
 2. **Red Phase - Write Failing Tests** (20 mins)
    - Create comprehensive test structure:
-     \`\`\`
+     \\\`\\\`\\\`
      tests/
      ├── unit/          # Isolated component tests
      ├── integration/   # Component interaction tests
      ├── e2e/          # End-to-end workflow tests
      └── fixtures/      # Test data and mocks
-     \`\`\`
+     \\\`\\\`\\\`
    - Write tests following London School TDD:
      - Start with behavior/contract tests
      - Use test doubles for dependencies
@@ -65,6 +65,22 @@ export function getTddOrchestration(taskDescription, memoryNamespace) {
    - Validate against acceptance criteria
    - Store completion: \`npx claude-flow memory store ${memoryNamespace}_tdd_complete "TDD cycle complete. Coverage: 95%. All acceptance criteria met. Tests documented. CI/CD ready."\`
 
+## Directory Safety
+- **IMPORTANT**: All test files should be created in the current working directory
+- **DO NOT** create files in system directories or node_modules
+- For named projects, create a subdirectory: \\\`mkdir project-name && cd project-name\\\`
+- Use relative paths from your working directory
+- Test files should follow project structure:
+  \\\`\\\`\\\`
+  ./ (current directory)
+  ├── tests/
+  │   ├── unit/
+  │   ├── integration/
+  │   └── e2e/
+  ├── coverage/
+  └── docs/
+  \\\`\\\`\\\`
+
 ## Deliverables
 - tests/
   - unit/ (isolated component tests)

package/src/cli/simple-commands/sparc.js

@@ -5,8 +5,8 @@ import { createSparcPrompt } from './sparc-modes/index.js';
 export async function sparcCommand(subArgs, flags) {
   const sparcCmd = subArgs[0];
   
-  // Show help if requested
-  if (flags.help || flags.h || sparcCmd === '--help' || sparcCmd === '-h' || !sparcCmd) {
+  // Show help if requested or no args
+  if (flags.help || flags.h || sparcCmd === '--help' || sparcCmd === '-h' || (!sparcCmd && Object.keys(flags).length === 0)) {
     showSparcHelp();
     return;
   }
@@ -22,6 +22,8 @@ export async function sparcCommand(subArgs, flags) {
       mergedArgs.push('--verbose');
     } else if (key === 'no-permissions') {
       mergedArgs.push('--no-permissions');
+    } else if (key === 'enable-permissions') {
+      mergedArgs.push('--enable-permissions');
     } else if (key === 'namespace') {
       mergedArgs.push('--namespace', value);
     } else if (key === 'config') {
@@ -31,7 +33,19 @@ export async function sparcCommand(subArgs, flags) {
     }
   }
   
-  switch (sparcCmd) {
+  // Check if first arg is a known subcommand
+  const knownSubcommands = ['modes', 'info', 'run', 'tdd'];
+  
+  if (!knownSubcommands.includes(sparcCmd)) {
+    // If not a known subcommand, treat it as a task description for sparc orchestrator
+    // Insert 'run' and 'sparc' to make it: ['run', 'sparc', ...rest of args]
+    mergedArgs.unshift('run', 'sparc');
+  }
+  
+  // Now process the command
+  const actualCmd = mergedArgs[0];
+  
+  switch (actualCmd) {
     case 'modes':
       await listSparcModes(mergedArgs);
       break;
@@ -178,6 +192,14 @@ async function runSparcMode(subArgs, flags) {
     console.log(`📋 Task: ${taskDescription}`);
     
     const isNonInteractive = subArgs.includes('--non-interactive') || subArgs.includes('-n');
+    const enablePermissions = subArgs.includes('--enable-permissions');
+    
+    if (!enablePermissions) {
+      console.log(`⚡ Permissions: Auto-skipped (--dangerously-skip-permissions)`);
+    } else {
+      console.log(`✅ Permissions: Enabled (will prompt for actions)`);
+    }
+    
     if (isNonInteractive) {
       console.log(`🚀 Running in non-interactive mode with stream-json output`);
       console.log();
@@ -262,25 +284,24 @@ function buildToolsFromGroups(groups) {
 async function executeClaude(enhancedTask, toolsList, instanceId, memoryNamespace, subArgs) {
   // Check for non-interactive mode
   const isNonInteractive = subArgs.includes('--non-interactive') || subArgs.includes('-n');
+  const enablePermissions = subArgs.includes('--enable-permissions');
   
   // Build arguments array correctly
   const claudeArgs = [];
+  claudeArgs.push(enhancedTask);
   
-  if (isNonInteractive) {
-    // Non-interactive mode: prompt first, then flags
-    // The enhanced task contains the full SPARC prompt with orchestration
-    claudeArgs.push(enhancedTask);
+  // Add --dangerously-skip-permissions by default unless --enable-permissions is set
+  if (!enablePermissions) {
     claudeArgs.push('--dangerously-skip-permissions');
+  }
+  
+  if (isNonInteractive) {
+    // Non-interactive mode: add additional flags
     claudeArgs.push('-p'); // Use short form for print
     claudeArgs.push('--output-format', 'stream-json');
     claudeArgs.push('--verbose');
   } else {
-    // Interactive mode (default behavior)
-    claudeArgs.push(enhancedTask);
-    if (subArgs.includes('--no-permissions')) {
-      claudeArgs.push('--dangerously-skip-permissions');
-    }
-    
+    // Interactive mode - check for verbose flag
     if (subArgs.includes('--verbose') || subArgs.includes('-v')) {
       claudeArgs.push('--verbose');
     }
@@ -294,23 +315,28 @@ async function executeClaude(enhancedTask, toolsList, instanceId, memoryNamespac
     claudeArgs.push('--mcp-config', subArgs[configIndex + 1]);
   }
   
-  // Always show debug info for non-interactive mode
-  if (isNonInteractive) {
+  // Show debug info for non-interactive mode or when verbose
+  if (isNonInteractive || subArgs.includes('--verbose') || subArgs.includes('-v')) {
     console.log('\n🔍 Debug: Executing claude with:');
     console.log('Command: claude');
+    console.log('Permissions:', enablePermissions ? '✅ Enabled (will prompt)' : '⚡ Skipped (--dangerously-skip-permissions)');
+    console.log('Mode:', isNonInteractive ? '🤖 Non-interactive' : '💬 Interactive');
     console.log('Args array length:', claudeArgs.length);
     console.log('First arg (prompt) length:', claudeArgs[0].length, 'characters');
-    console.log('First 200 chars of prompt:', claudeArgs[0].substring(0, 200) + '...');
-    console.log('\nAll arguments:');
-    claudeArgs.forEach((arg, i) => {
-      if (i === 0) {
-        console.log(`  [0] <SPARC prompt with ${arg.length} characters>`);
-      } else {
-        console.log(`  [${i}] ${arg}`);
-      }
-    });
-    console.log('\nFull command structure:');
-    console.log('claude "<SPARC prompt>" ' + claudeArgs.slice(1).join(' '));
+    
+    if (isNonInteractive) {
+      console.log('First 200 chars of prompt:', claudeArgs[0].substring(0, 200) + '...');
+      console.log('\nAll arguments:');
+      claudeArgs.forEach((arg, i) => {
+        if (i === 0) {
+          console.log(`  [0] <SPARC prompt with ${arg.length} characters>`);
+        } else {
+          console.log(`  [${i}] ${arg}`);
+        }
+      });
+      console.log('\nFull command structure:');
+      console.log('claude "<SPARC prompt>" ' + claudeArgs.slice(1).join(' '));
+    }
     console.log();
   }
   
@@ -370,12 +396,14 @@ async function executeClaude(enhancedTask, toolsList, instanceId, memoryNamespac
 
 function showSparcHelp() {
   console.log('SPARC commands:');
+  console.log('  <task>                   Run SPARC orchestrator (default mode)');
   console.log('  modes                    List available SPARC development modes');
   console.log('  info <mode>              Show detailed information about a mode');
   console.log('  run <mode> <task>        Execute a task in specified SPARC mode');
   console.log('  tdd <task>               Run Test-Driven Development workflow');
   console.log();
   console.log('Examples:');
+  console.log('  claude-flow sparc "orchestrate app development"    # Uses sparc orchestrator');
   console.log('  claude-flow sparc modes --verbose');
   console.log('  claude-flow sparc info architect');
   console.log('  claude-flow sparc run code "implement user authentication"');
@@ -383,19 +411,42 @@ function showSparcHelp() {
   console.log('  claude-flow sparc run tdd "create test suite" --namespace tests');
   console.log('  claude-flow sparc tdd "payment processing system" --interactive');
   console.log();
+  console.log('Parallel Execution with BatchTool:');
+  console.log('  # Run multiple SPARC modes concurrently');
+  console.log('  batchtool run --parallel \\');
+  console.log('    "npx claude-flow sparc run code \'user service\' --non-interactive" \\');
+  console.log('    "npx claude-flow sparc run code \'auth service\' --non-interactive" \\');
+  console.log('    "npx claude-flow sparc run tdd \'test suite\' --non-interactive"');
+  console.log();
+  console.log('  # Boomerang orchestration pattern');
+  console.log('  batchtool orchestrate --boomerang \\');
+  console.log('    --research "npx claude-flow sparc run ask \'requirements\' --non-interactive" \\');
+  console.log('    --design "npx claude-flow sparc run architect \'system\' --non-interactive" \\');
+  console.log('    --implement "npx claude-flow sparc run code \'features\' --non-interactive" \\');
+  console.log('    --test "npx claude-flow sparc run tdd \'validation\' --non-interactive"');
+  console.log();
   console.log('Flags:');
   console.log('  --dry-run, -d            Show configuration without executing');
   console.log('  --verbose, -v            Show detailed output');
   console.log('  --interactive, -i        Run TDD workflow interactively');
   console.log('  --non-interactive, -n    Run in non-interactive mode with stream-json output');
-  console.log('  --no-permissions         Skip Claude permissions prompts (dangerous)');
+  console.log('  --enable-permissions     Enable permission prompts (default: skip permissions)');
   console.log('  --namespace <ns>         Use custom memory namespace (default: mode slug)');
   console.log('  --config <path>          Use custom MCP configuration file');
   console.log();
+  console.log('Permission Behavior:');
+  console.log('  By default, SPARC runs with --dangerously-skip-permissions for efficiency');
+  console.log('  Use --enable-permissions to restore permission prompts if needed');
+  console.log();
   console.log('Non-Interactive Mode:');
   console.log('  When using --non-interactive, claude will be executed with:');
-  console.log('  - --dangerously-skip-permissions (auto-approve all actions)');
+  console.log('  - --dangerously-skip-permissions (unless --enable-permissions is set)');
   console.log('  - -p (print mode for streaming output)');
   console.log('  - --output-format stream-json (structured output format)');
   console.log('  - --verbose (detailed execution logs)');
+  console.log();
+  console.log('Boomerang Pattern:');
+  console.log('  A cyclical orchestration where outputs from one phase feed into the next:');
+  console.log('  Research → Design → Implement → Test → Optimize → Loop back');
+  console.log('  Perfect for iterative development with continuous refinement');
 }