claude-flow-novice 1.0.0

package/src/npx/claude-md-protection.js

@@ -0,0 +1,169 @@
+/**
+ * NPX CLAUDE.md Protection System
+ *
+ * Prevents NPX installs from overwriting user's customized CLAUDE.md files
+ * Creates claude-copy-to-main.md for safe manual merging
+ */
+
+import { ClaudeMdSlashCommand } from '../slash-commands/claude-md.js';
+import fs from 'fs/promises';
+import path from 'path';
+
+export class NpxClaudeMdProtection {
+  constructor(projectPath = process.cwd()) {
+    this.projectPath = projectPath;
+    this.claudeMdPath = path.join(projectPath, 'CLAUDE.md');
+    this.packageJsonPath = path.join(projectPath, 'package.json');
+  }
+
+  /**
+   * Main NPX protection workflow
+   */
+  async protectAndGenerate() {
+    try {
+      console.log('🛡️ NPX CLAUDE.md Protection Active...');
+
+      // Check if this is an NPX environment
+      const isNpxInstall = await this.detectNpxInstall();
+
+      if (!isNpxInstall) {
+        console.log('ℹ️ Not an NPX install - proceeding normally');
+        return await this.generateNormal();
+      }
+
+      // Check if user has existing CLAUDE.md
+      const hasExistingClaude = await this.hasExistingClaudeMd();
+
+      if (!hasExistingClaude) {
+        console.log('📄 No existing CLAUDE.md - safe to create new one');
+        return await this.generateNormal();
+      }
+
+      // Protection scenario: Generate claude-copy-to-main.md
+      console.log('🔒 Existing CLAUDE.md detected - activating protection');
+      return await this.generateProtected();
+
+    } catch (error) {
+      console.error('❌ NPX protection failed:', error.message);
+      throw error;
+    }
+  }
+
+  /**
+   * Detect if this is running in NPX context
+   */
+  async detectNpxInstall() {
+    // Check environment variables
+    if (process.env.NPX_INSTALL === 'true' || process.env.npm_command === 'exec') {
+      return true;
+    }
+
+    // Check if we're in a temporary NPX directory
+    if (this.projectPath.includes('/.npm/_npx/') || this.projectPath.includes('\\.npm\\_npx\\')) {
+      return true;
+    }
+
+    // Check if package.json indicates fresh install
+    try {
+      const packageJson = await fs.readFile(this.packageJsonPath, 'utf8');
+      const pkg = JSON.parse(packageJson);
+
+      // If claude-flow-novice was just installed
+      if (pkg.dependencies?.['claude-flow-novice'] || pkg.devDependencies?.['claude-flow-novice']) {
+        return true;
+      }
+    } catch {
+      // No package.json or parsing error - probably not NPX
+    }
+
+    return false;
+  }
+
+  /**
+   * Check if user has existing CLAUDE.md with customizations
+   */
+  async hasExistingClaudeMd() {
+    try {
+      const content = await fs.readFile(this.claudeMdPath, 'utf8');
+
+      // Simple heuristic: if file is longer than default template,
+      // it probably has customizations
+      return content.length > 1000;
+    } catch {
+      return false;
+    }
+  }
+
+  /**
+   * Generate CLAUDE.md normally (no protection needed)
+   */
+  async generateNormal() {
+    const command = new ClaudeMdSlashCommand(this.projectPath);
+    return await command.execute({
+      backup: true,
+      force: false,
+      isNpxInstall: false
+    });
+  }
+
+  /**
+   * Generate with protection (create claude-copy-to-main.md)
+   */
+  async generateProtected() {
+    const command = new ClaudeMdSlashCommand(this.projectPath);
+    const result = await command.execute({
+      backup: false, // Don't backup since we're not overwriting
+      force: false,
+      isNpxInstall: true // This triggers the protection
+    });
+
+    // Show user-friendly instructions
+    this.showProtectionInstructions();
+
+    return result;
+  }
+
+  /**
+   * Show clear instructions to user about the protection
+   */
+  showProtectionInstructions() {
+    console.log('\n🎉 Your CLAUDE.md is protected!');
+    console.log('━'.repeat(50));
+    console.log('📋 What happened:');
+    console.log('  • NPX detected an existing CLAUDE.md file');
+    console.log('  • To protect your customizations, we created:');
+    console.log('    → claude-copy-to-main.md');
+    console.log('');
+    console.log('🔄 Next steps:');
+    console.log('  1. Review: cat claude-copy-to-main.md');
+    console.log('  2. Merge desired changes into your CLAUDE.md');
+    console.log('  3. Delete: rm claude-copy-to-main.md');
+    console.log('');
+    console.log('💡 Your original CLAUDE.md remains untouched!');
+    console.log('━'.repeat(50));
+  }
+
+  /**
+   * Hook for package.json postinstall script
+   */
+  static async postInstallHook(projectPath) {
+    try {
+      const protection = new NpxClaudeMdProtection(projectPath);
+      await protection.protectAndGenerate();
+    } catch (error) {
+      console.warn('⚠️ CLAUDE.md protection failed:', error.message);
+      // Don't fail the install if this fails
+    }
+  }
+}
+
+/**
+ * CLI entry point for NPX protection
+ */
+if (import.meta.url === `file://${process.argv[1]}`) {
+  const projectPath = process.argv[2] || process.cwd();
+
+  NpxClaudeMdProtection.postInstallHook(projectPath)
+    .then(() => process.exit(0))
+    .catch(() => process.exit(1));
+}

package/wiki/INDEX.md

@@ -0,0 +1,264 @@
+# Claude Flow Novice Wiki - Complete Index
+
+> **Comprehensive navigation guide for the entire claude-flow-novice documentation**
+
+## 📊 Wiki Statistics
+
+- **Total Documentation**: 115,113 lines across 150 markdown files
+- **Coverage Areas**: 19 major sections with 122 subsections
+- **Content Links**: 1,296 internal references and external resources
+- **Size**: 3.7MB of comprehensive documentation
+
+## 🗺️ Master Navigation
+
+### 🚀 Getting Started (Essential Reading)
+- **[Quick Start](getting-started/quick-start/README.md)** - 5-minute setup guide
+- **[Installation Guide](getting-started/installation/README.md)** - Complete platform setup
+- **[CLI Access](getting-started/cli-access/README.md)** - Command-line interface setup
+- **[Claude Code MCP](getting-started/claude-code-mcp/README.md)** - Integrated IDE experience
+
+### 🧠 Core Concepts (Understanding the System)
+- **[Agents Overview](core-concepts/agents/README.md)** - 54+ specialized AI agents
+- **[SPARC Methodology](core-concepts/sparc-methodology/README.md)** - Systematic development approach
+- **[Swarm Coordination](core-concepts/swarm-coordination/README.md)** - Multi-agent orchestration
+- **[Memory System](core-concepts/memory-system/README.md)** - Cross-session intelligence
+- **[Hooks Lifecycle](core-concepts/hooks-lifecycle/README.md)** - Automation and coordination
+
+### 📚 Learning Paths (Progressive Education)
+
+#### Beginner Track (5-10 hours)
+- **[First Agent Project](tutorials/beginner/first-agent-project.md)** - Build your first AI-assisted project
+- **[Basic Commands](command-reference/novice/README.md)** - 5 essential commands
+- **[Simple Examples](examples/basic/hello-world/README.md)** - Hello world projects
+
+#### Intermediate Track (15-25 hours)
+- **[Multi-Agent Workflows](tutorials/intermediate/multi-agent-webapp.md)** - Team coordination
+- **[Intermediate Commands](command-reference/intermediate/README.md)** - 15 workflow commands
+- **[Real Projects](examples/intermediate/README.md)** - Production-ready examples
+
+#### Advanced Track (30+ hours)
+- **[Enterprise Patterns](tutorials/advanced/enterprise-patterns.md)** - Large-scale development
+- **[Expert Commands](command-reference/expert/README.md)** - 112+ MCP tools
+- **[Complex Systems](examples/advanced/README.md)** - Architectural examples
+
+### 💻 Language-Specific Guides
+- **[JavaScript](languages/javascript/README.md)** - Node.js ecosystem integration
+- **[TypeScript](languages/typescript/README.md)** - Type-safe development patterns
+- **[Python](languages/python/README.md)** - Python ecosystem workflows
+- **[Rust](languages/rust/README.md)** - High-performance applications
+- **[Go](languages/go/README.md)** - Microservices and API development
+- **[Java](languages/java/README.md)** - Enterprise application patterns
+
+### 📖 Command Reference (Complete Documentation)
+- **[Progressive CLI System](command-reference/README.md)** - Tier-based command system
+- **[Novice Commands (5)](command-reference/novice/README.md)** - Essential beginner commands
+- **[Intermediate Commands (15)](command-reference/intermediate/README.md)** - Workflow commands
+- **[Expert Commands (112+)](command-reference/expert/README.md)** - Full MCP tool access
+- **[MCP Tools](command-reference/mcp-tools/README.md)** - Claude Code integration
+
+### 🎯 Real-World Examples
+
+#### Basic Projects
+- **[Hello World](examples/basic/hello-world/README.md)** - First steps
+- **[Todo Application](examples/basic-projects/todo-app/README.md)** - Classic beginner project
+- **[Simple API](examples/basic-projects/simple-api/README.md)** - REST API basics
+
+#### Intermediate Projects
+- **[Full-Stack Web App](examples/intermediate/fullstack-webapp/README.md)** - Complete application
+- **[E-commerce Platform](examples/intermediate/ecommerce-platform/README.md)** - Business application
+- **[Mobile App Backend](examples/intermediate/mobile-backend/README.md)** - API services
+
+#### Advanced Projects
+- **[Microservices Architecture](examples/advanced/microservices/README.md)** - Distributed systems
+- **[Machine Learning Pipeline](examples/advanced/ml-pipeline/README.md)** - AI/ML workflows
+- **[Enterprise Integration](examples/advanced/enterprise-integration/README.md)** - Large-scale systems
+
+#### Automation Examples
+- **[CI/CD Pipeline](examples/automation/cicd-pipeline/README.md)** - Deployment automation
+- **[Testing Automation](examples/automation/testing-automation/README.md)** - Quality assurance
+- **[Monitoring Setup](examples/automation/monitoring-setup/README.md)** - Observability
+
+### 🔧 API & Technical Reference
+
+#### Complete API Documentation
+- **[CLI API](api-reference/cli-api.md)** - Command-line interface
+- **[Agent Management API](api-reference/agent-management-api.md)** - Agent control
+- **[Hooks & Coordination API](api-reference/hooks-coordination-api.md)** - Lifecycle management
+- **[Configuration API](api-reference/configuration-api.md)** - System configuration
+- **[MCP Tool Specifications](api-reference/mcp-tool-specifications.md)** - MCP integration
+
+#### Plugin Development
+- **[Plugin Development Guide](api-reference/plugin-development.md)** - Extend functionality
+- **[Custom Agent Creation](api-reference/custom-agents.md)** - Build specialized agents
+- **[Hook Development](api-reference/hook-development.md)** - Custom automation
+
+### ♿ Accessibility & Inclusion
+
+#### Comprehensive Accessibility Support
+- **[WCAG Compliance](accessibility/guidelines/wcag-compliance.md)** - 2.1 AA standards
+- **[Screen Reader Support](accessibility/assistive-tech/screen-reader-support.md)** - AT compatibility
+- **[Inclusive Design Patterns](accessibility/patterns/inclusive-design-patterns.md)** - Accessible components
+- **[Testing Automation](accessibility/testing/automated-testing.md)** - Accessibility validation
+
+#### Internationalization
+- **[i18n Strategies](accessibility/i18n/internationalization-strategies.md)** - Global accessibility
+- **[RTL Support](accessibility/i18n/rtl-complex-scripts.md)** - Right-to-left languages
+- **[Cultural Adaptation](accessibility/i18n/localization-guidelines.md)** - Localization patterns
+
+### 🏢 Enterprise & Team Coordination
+
+#### Enterprise Architecture
+- **[Enterprise Patterns](enterprise-architecture/patterns/README.md)** - Large-scale architecture
+- **[Scalability Guidelines](enterprise-architecture/scalability/README.md)** - Growth strategies
+- **[Performance Optimization](enterprise-architecture/performance/README.md)** - System efficiency
+
+#### Team Collaboration
+- **[Team Coordination](team-coordination/workflows/README.md)** - Multi-team workflows
+- **[Role-Based Access](team-coordination/roles/README.md)** - Permission management
+- **[Knowledge Sharing](team-coordination/knowledge-sharing/README.md)** - Team learning
+
+#### Governance & Compliance
+- **[Governance Framework](governance/framework/README.md)** - Organizational control
+- **[Compliance Monitoring](governance/compliance/README.md)** - Regulatory adherence
+- **[Audit Trails](governance/audit/README.md)** - Change tracking
+
+### 🔒 Security & Best Practices
+
+#### Security Documentation
+- **[Security Best Practices](security/best-practices/README.md)** - Secure development
+- **[Authentication Patterns](security/authentication/README.md)** - Identity management
+- **[Compliance Frameworks](security/compliance/README.md)** - Regulatory requirements
+- **[Secure Coding](security/secure-coding/README.md)** - Code security patterns
+
+#### Cost Optimization
+- **[Resource Optimization](cost-optimization/resource-management/README.md)** - Efficient usage
+- **[Performance Monitoring](cost-optimization/monitoring/README.md)** - Usage tracking
+- **[Scaling Strategies](cost-optimization/scaling/README.md)** - Growth management
+
+### 🚀 Deployment & Operations
+
+#### Deployment Strategies
+- **[Deployment Patterns](deployment/strategies/README.md)** - Release approaches
+- **[Environment Management](deployment/environments/README.md)** - Stage management
+- **[Rollback Procedures](deployment/rollback/README.md)** - Recovery strategies
+
+#### Monitoring & Observability
+- **[Monitoring Setup](monitoring/setup/README.md)** - System observability
+- **[Performance Tracking](monitoring/performance/README.md)** - Metrics collection
+- **[Alert Management](monitoring/alerts/README.md)** - Incident response
+
+### 🎥 Video Tutorials & Interactive Learning
+
+#### Video Learning Paths
+- **[Getting Started Videos](video-tutorials/getting-started/README.md)** - Visual learning
+- **[Advanced Techniques](video-tutorials/advanced/README.md)** - Expert demonstrations
+- **[Live Workshops](video-tutorials/workshops/README.md)** - Interactive sessions
+
+#### Interactive Content
+- **[Hands-On Labs](tutorials/interactive/labs/README.md)** - Practice exercises
+- **[Code Challenges](tutorials/interactive/challenges/README.md)** - Skill building
+- **[Project Templates](tutorials/interactive/templates/README.md)** - Quick starts
+
+### 🛠️ Troubleshooting & Support
+
+#### Problem Resolution
+- **[Common Issues](troubleshooting/common-issues/README.md)** - FAQ solutions
+- **[Error Analysis](troubleshooting/error-analysis/README.md)** - Diagnostic guides
+- **[Performance Issues](troubleshooting/performance/README.md)** - Optimization fixes
+
+#### Platform-Specific Help
+- **[CLI Troubleshooting](troubleshooting/cli/README.md)** - Command-line issues
+- **[MCP Integration Issues](troubleshooting/mcp/README.md)** - Integration problems
+- **[Configuration Problems](troubleshooting/configuration/README.md)** - Setup issues
+
+### 🤝 Community & Contributing
+
+#### Community Resources
+- **[Contributing Guide](community/contributing/README.md)** - How to contribute
+- **[Discussion Forums](community/discussions/README.md)** - Community support
+- **[Project Showcase](community/showcase/README.md)** - User projects
+
+#### Development Resources
+- **[Development Setup](community/development/README.md)** - Contributor setup
+- **[Code Standards](community/standards/README.md)** - Quality guidelines
+- **[Release Process](community/releases/README.md)** - Version management
+
+## 🔍 Search Optimization & Discoverability
+
+### Quick Reference Cards
+- **[Command Cheat Sheet](quick-reference/commands.md)** - Essential commands
+- **[Agent Quick Reference](quick-reference/agents.md)** - Agent capabilities
+- **[Workflow Patterns](quick-reference/workflows.md)** - Common patterns
+
+### Topic-Based Navigation
+- **[By Use Case](navigation/by-use-case.md)** - Problem-solution mapping
+- **[By Technology](navigation/by-technology.md)** - Technology-specific guides
+- **[By Skill Level](navigation/by-skill-level.md)** - Progressive learning paths
+
+### Cross-References
+- **[Glossary](reference/glossary.md)** - Term definitions
+- **[Concept Map](reference/concept-map.md)** - Relationship visualization
+- **[Learning Dependencies](reference/dependencies.md)** - Prerequisite tracking
+
+## 📊 Performance Metrics & Benefits
+
+### Proven Results
+- **84.8% SWE-Bench solve rate** with multi-agent coordination
+- **32.3% token reduction** through intelligent optimization
+- **2.8-4.4x speed improvement** over traditional development
+- **90%+ test coverage** with automated testing agents
+
+### User Success Stories
+- **[Case Studies](community/case-studies/README.md)** - Real implementations
+- **[Performance Benchmarks](reference/benchmarks.md)** - Measured improvements
+- **[ROI Analysis](reference/roi-analysis.md)** - Business value
+
+## 🎯 Quick Start by Goal
+
+### "I want to build an app"
+1. [Installation Guide](getting-started/installation/README.md)
+2. [Quick Start Tutorial](getting-started/quick-start/README.md)
+3. [First Project](tutorials/beginner/first-agent-project.md)
+
+### "I want to understand the system"
+1. [Core Concepts](core-concepts/README.md)
+2. [Agent Overview](core-concepts/agents/README.md)
+3. [SPARC Methodology](core-concepts/sparc-methodology/README.md)
+
+### "I want to see examples"
+1. [Basic Examples](examples/basic/README.md)
+2. [Language-Specific Guides](languages/README.md)
+3. [Real-World Projects](examples/intermediate/README.md)
+
+### "I need reference material"
+1. [Command Reference](command-reference/README.md)
+2. [API Documentation](api-reference/README.md)
+3. [Troubleshooting Guide](troubleshooting/README.md)
+
+### "I want to contribute"
+1. [Contributing Guide](community/contributing/README.md)
+2. [Development Setup](community/development/README.md)
+3. [Code Standards](community/standards/README.md)
+
+## 🔗 External Resources
+
+### Official Links
+- **GitHub Repository**: [claude-flow-novice](https://github.com/ruvnet/claude-flow)
+- **Issue Tracker**: [GitHub Issues](https://github.com/ruvnet/claude-flow/issues)
+- **Discussions**: [GitHub Discussions](https://github.com/ruvnet/claude-flow/discussions)
+
+### Related Projects
+- **Claude Flow**: Core orchestration engine
+- **RUV Swarm**: Enhanced coordination capabilities
+- **Flow Nexus**: Cloud-based enterprise features
+
+### Learning Resources
+- **WCAG Guidelines**: [Web Accessibility Guidelines](https://www.w3.org/WAI/WCAG21/quickref/)
+- **WAI-ARIA**: [Accessible Rich Internet Applications](https://www.w3.org/WAI/ARIA/apg/)
+- **Inclusive Design**: [Principles and Practices](https://inclusivedesignprinciples.org/)
+
+---
+
+**📚 Total Documentation**: This index covers **115,113 lines** of comprehensive documentation across **150 markdown files** in **19 major sections**, providing complete coverage of the claude-flow-novice platform.
+
+**🎯 Navigation Tip**: Use your browser's search function (Ctrl+F) to quickly find specific topics in this index, then follow the links to detailed documentation.