claude-flow 2.7.0-alpha.9 → 2.7.1

package/docs/COMMANDS_TO_SKILLS_MIGRATION.md

@@ -0,0 +1,382 @@
+# Commands → Skills Migration Analysis
+
+## Executive Summary
+**Total Commands**: 150 files
+**Recommended for Skills**: 35 files (23%)
+**Keep as Commands**: 115 files (77%)
+
+---
+
+## ✅ RECOMMENDED: Convert to Skills
+
+### 1. **Pair Programming Skill** (6 files → 1 skill)
+**Rationale**: Complex multi-step workflow with modes, configuration, sessions
+- `/pair/commands.md` (545 lines)
+- `/pair/examples.md` (511 lines)
+- `/pair/config.md` (509 lines)
+- `/pair/session.md` (406 lines)
+- `/pair/modes.md` (347 lines)
+- `/pair/start.md` (208 lines)
+
+**Total**: 2,526 lines of comprehensive workflow documentation
+**Skill Name**: `pair-programming`
+
+---
+
+### 2. **GitHub Workflow Automation Skills** (12 files → 5 skills)
+
+#### 2a. **GitHub Release Management Skill**
+- `/github/release-swarm.md` (543 lines)
+- `/github/release-manager.md` (337 lines)
+
+**Skill Name**: `github-release-management`
+
+#### 2b. **GitHub Multi-Repo Coordination Skill**
+- `/github/multi-repo-swarm.md` (518 lines)
+- `/github/sync-coordinator.md` (300 lines)
+- `/github/repo-architect.md` (366 lines)
+
+**Skill Name**: `github-multi-repo`
+
+#### 2c. **GitHub Code Review Skill**
+- `/github/code-review-swarm.md` (513 lines)
+- `/github/swarm-pr.md` (284 lines)
+- `/github/pr-manager.md` (169 lines)
+
+**Skill Name**: `github-code-review`
+
+#### 2d. **GitHub Issue & Project Management Skill**
+- `/github/swarm-issue.md` (481 lines)
+- `/github/project-board-sync.md` (470 lines)
+- `/github/issue-tracker.md` (291 lines)
+
+**Skill Name**: `github-project-management`
+
+#### 2e. **GitHub Workflow Automation Skill**
+- `/github/workflow-automation.md` (441 lines)
+- `/github/github-modes.md` (146 lines)
+
+**Skill Name**: `github-workflow-automation`
+
+---
+
+### 3. **Verification & Quality Skill** (3+ files → 1 skill)
+- `/truth/start.md` (142 lines)
+- `/verify/start.md`
+- `/verify/check.md`
+
+**Skill Name**: `verification-quality`
+
+---
+
+### 4. **SPARC Development Methodology Skill** (3+ files → 1 skill)
+- `/sparc/sparc-modes.md` (174 lines)
+- `/sparc/orchestrator.md` (131 lines)
+- Additional SPARC files
+
+**Skill Name**: `sparc-methodology`
+
+---
+
+### 5. **Flow Nexus Cloud Workflows Skills** (9 files → 3 skills)
+
+#### 5a. **Flow Nexus Neural Network Training Skill**
+- `/flow-nexus/neural-network.md` (133 lines)
+
+**Skill Name**: `flow-nexus-neural`
+
+#### 5b. **Flow Nexus Swarm Deployment Skill**
+- `/flow-nexus/swarm.md`
+- `/flow-nexus/workflow.md`
+
+**Skill Name**: `flow-nexus-swarm`
+
+#### 5c. **Flow Nexus Platform Management Skill**
+- `/flow-nexus/user-tools.md` (151 lines)
+- `/flow-nexus/sandbox.md`
+- `/flow-nexus/app-store.md`
+- `/flow-nexus/payments.md`
+- `/flow-nexus/challenges.md`
+- `/flow-nexus/login-registration.md`
+
+**Skill Name**: `flow-nexus-platform`
+
+---
+
+### 6. **Advanced Swarm Orchestration Skill** (3 files → 1 skill)
+- `/swarm/examples.md` (168 lines)
+- `/swarm/research.md` (136 lines)
+- `/swarm/testing.md` (131 lines)
+
+**Skill Name**: `swarm-advanced`
+
+---
+
+### 7. **Bottleneck Analysis & Performance Skill** (3 files → 1 skill)
+- `/analysis/bottleneck-detect.md` (162 lines)
+- `/analysis/performance-bottlenecks.md`
+- `/analysis/performance-report.md`
+
+**Skill Name**: `performance-analysis`
+
+---
+
+### 8. **Stream Chain Workflow Skill** (2 files → 1 skill)
+- `/stream-chain/pipeline.md`
+- `/stream-chain/run.md`
+
+**Skill Name**: `stream-chain`
+
+---
+
+### 9. **Hive Mind Advanced Workflows Skill** (11+ files → 1 skill)
+- `/hive-mind/` comprehensive documentation
+- Multiple coordination patterns
+
+**Skill Name**: `hive-mind-advanced`
+
+---
+
+### 10. **Hooks & Automation Framework Skill** (5+ files → 1 skill)
+- `/hooks/overview.md` (131 lines)
+- Additional hook documentation
+
+**Skill Name**: `hooks-automation`
+
+---
+
+## ❌ KEEP AS COMMANDS (Simple CLI operations)
+
+### Analysis Commands (Keep)
+- `token-usage.md` (26 lines) - Simple CLI query
+- `token-efficiency.md` - Simple reporting
+
+### Memory Commands (Keep)
+- `memory-usage.md` - Simple memory operations
+- `memory-search.md` - Quick searches
+- `memory-persist.md` - Save/load operations
+- `neural.md` - Neural status queries
+- `usage.md` - Usage stats
+
+### Monitoring Commands (Keep)
+- Simple monitoring operations
+- Status checks
+- Metric queries
+
+### Automation Commands (Keep)
+- Simple automation triggers
+- Basic workflow starts
+
+### Swarm Commands (Keep as simple triggers)
+- `swarm.md` (28 lines) - Simple CLI trigger
+- `swarm-init.md` - Initialize swarm
+- `swarm-status.md` - Check status
+- `swarm-spawn.md` - Spawn agents
+- `swarm-monitor.md` - Monitor swarm
+- `swarm-background.md` - Background execution
+- `development.md` - Dev mode
+- `maintenance.md` - Maintenance mode
+- `analysis.md` - Analysis mode
+- `optimization.md` - Optimization mode
+
+### Agents Commands (Keep)
+- Simple agent spawning commands
+
+### Training Commands (Keep)
+- Simple training triggers
+
+### Workflows Commands (Keep)
+- Simple workflow triggers
+
+### Coordination Commands (Keep)
+- Simple coordination operations
+
+---
+
+## 📊 Summary Statistics
+
+| Category | Files | Keep as Commands | Convert to Skills |
+|----------|-------|------------------|-------------------|
+| pair/ | 6 | 0 | 6 (→ 1 skill) |
+| github/ | 12 | 0 | 12 (→ 5 skills) |
+| flow-nexus/ | 9 | 0 | 9 (→ 3 skills) |
+| sparc/ | 3+ | 0 | 3+ (→ 1 skill) |
+| truth/ | 1 | 0 | 1 (→ 1 skill) |
+| verify/ | 2 | 0 | 2 (→ 1 skill) |
+| swarm/ | 16 | 13 | 3 (→ 1 skill) |
+| analysis/ | 6 | 3 | 3 (→ 1 skill) |
+| hooks/ | 5+ | 0 | 5+ (→ 1 skill) |
+| hive-mind/ | 11+ | 0 | 11+ (→ 1 skill) |
+| stream-chain/ | 2 | 0 | 2 (→ 1 skill) |
+| **Simple Commands** | ~85 | ~85 | 0 |
+
+**Total Skills to Create**: ~18-20 comprehensive skills
+**Commands to Remove**: ~35 files (will be consolidated)
+**Commands to Keep**: ~115 files
+
+---
+
+## 🎯 Implementation Priority
+
+### Phase 1: High Impact (Immediate)
+1. ✅ **skill-builder** (DONE)
+2. **pair-programming** - Most comprehensive workflow (2,526 lines)
+3. **verification-quality** - Critical for code quality
+4. **github-code-review** - High usage workflow
+
+### Phase 2: GitHub Integration
+5. **github-release-management**
+6. **github-multi-repo**
+7. **github-project-management**
+8. **github-workflow-automation**
+
+### Phase 3: Advanced Features
+9. **flow-nexus-neural**
+10. **flow-nexus-swarm**
+11. **flow-nexus-platform**
+12. **sparc-methodology**
+
+### Phase 4: Specialized Workflows
+13. **swarm-advanced**
+14. **performance-analysis**
+15. **stream-chain**
+16. **hive-mind-advanced**
+17. **hooks-automation**
+
+---
+
+## 🔧 Migration Guidelines
+
+### For each skill conversion:
+
+1. **Create YAML frontmatter**:
+```yaml
+---
+name: "Skill Name"
+description: "Brief description of what this skill does and when Claude should use it. Maximum 1024 characters."
+---
+```
+
+2. **Structure with progressive disclosure**:
+```markdown
+# Skill Name
+
+## What This Skill Does
+[Brief overview - always visible]
+
+## Prerequisites
+[Requirements - always visible]
+
+## Quick Start
+[Simple example - always visible]
+
+---
+
+## Complete Guide
+[Detailed instructions - behind progressive disclosure fold]
+
+### Step 1: Setup
+...
+
+### Step 2: Configuration
+...
+
+### Step 3: Execution
+...
+
+## Advanced Usage
+...
+
+## Troubleshooting
+...
+
+## Examples
+...
+```
+
+3. **Remove from commands/**:
+- Delete original .md files after migration
+- Update any cross-references in other files
+- Update README files in command directories
+
+4. **Create skill directory structure**:
+```
+.claude/skills/
+  ├── skill-builder/
+  │   └── SKILL.md
+  ├── pair-programming/
+  │   └── SKILL.md
+  ├── verification-quality/
+  │   └── SKILL.md
+  └── github-code-review/
+      └── SKILL.md
+```
+
+---
+
+## 🚫 Preventing Duplicates
+
+### Current State
+- **Commands**: 150 files in `.claude/commands/`
+- **Skills**: 1 file in `.claude/skills/` (skill-builder)
+
+### After Migration
+- **Commands**: ~115 files (simple CLI operations)
+- **Skills**: ~20 files (complex workflows)
+- **Reduction**: ~35 command files removed (consolidated into skills)
+
+### No Duplicates Because:
+1. **Complex workflows** → **Skills** (with YAML frontmatter, progressive disclosure)
+2. **Simple CLI triggers** → **Commands** (without YAML, concise reference)
+3. **Clear separation of concerns**:
+   - Commands: Execute operations (`npx claude-flow swarm "task"`)
+   - Skills: Teach workflows (Claude learns patterns and best practices)
+4. **Different discovery mechanisms**:
+   - Commands: CLI help, documentation
+   - Skills: Claude's autonomous discovery via YAML metadata
+
+### Decision Criteria
+| Aspect | Command | Skill |
+|--------|---------|-------|
+| Length | <100 lines | >200 lines |
+| Complexity | Single operation | Multi-step workflow |
+| Usage | CLI trigger | Learning resource |
+| Structure | Simple markdown | YAML + progressive disclosure |
+| Examples | 1-2 examples | 5-10+ examples |
+| Config | Minimal | Extensive configuration |
+
+---
+
+## 📝 Next Steps
+
+1. ✅ Review this analysis
+2. Approve priority order
+3. Begin Phase 1 skill creation:
+   - [ ] Create `pair-programming` skill
+   - [ ] Create `verification-quality` skill
+   - [ ] Create `github-code-review` skill
+4. Test each skill with Claude Code
+5. Remove consolidated command files
+6. Update documentation and references
+7. Update `skills-copier.js` to handle new skills
+
+---
+
+## 💡 Benefits of Migration
+
+1. **Better Organization**: Complex workflows in one place
+2. **Improved Discovery**: Claude can find and use skills autonomously
+3. **Reduced Duplication**: Consolidate related commands
+4. **Enhanced Learning**: Progressive disclosure teaches best practices
+5. **Cleaner Commands**: Keep only simple CLI triggers
+6. **Better Maintenance**: Easier to update comprehensive workflows
+
+---
+
+## ⚠️ Important Notes
+
+- **DO NOT** convert simple CLI commands to skills
+- **DO NOT** duplicate content between commands and skills
+- **DO** ensure skills have complete, standalone workflows
+- **DO** keep commands as lightweight CLI triggers
+- **DO** test each skill in Claude Code before removing commands

package/docs/FINAL_INIT_STRUCTURE.md

@@ -0,0 +1,320 @@
+# Final .claude/ Structure Generated by Init
+
+## Executive Summary
+
+After cleanup and migration, `npx claude-flow init` now generates a clean, organized structure with:
+- **76 agent files** across 20 specialized categories
+- **81 command files** - simple CLI references only
+- **21 comprehensive skills** - complex workflows with YAML frontmatter
+
+**Total reduction:** 69 command files consolidated into skills (from 150 → 81)
+
+---
+
+## Complete Structure
+
+### 📁 `.claude/agents/` (76 files, 20 categories)
+
+Specialized AI agents for different tasks:
+
+```
+agents/
+├── analysis/        (3 files) - Code analysis and metrics
+├── architecture/    (4 files) - System architecture and design
+├── consensus/       (6 files) - Byzantine, Raft, Gossip consensus
+├── core/            (6 files) - Coder, Researcher, Planner, Reviewer, Tester
+├── data/            (3 files) - Data processing and transformation
+├── development/     (4 files) - Full-stack development specialists
+├── devops/          (3 files) - CI/CD and deployment automation
+├── documentation/   (3 files) - Documentation generation
+├── flow-nexus/      (6 files) - Cloud platform integration
+├── github/          (8 files) - Repository management and automation
+├── goal/            (4 files) - Goal-oriented action planning (GOAP)
+├── hive-mind/       (4 files) - Queen-worker collective intelligence
+├── neural/          (3 files) - Neural network training and patterns
+├── optimization/    (5 files) - Performance and resource optimization
+├── reasoning/       (3 files) - Advanced reasoning algorithms
+├── sparc/           (5 files) - SPARC methodology specialists
+├── specialized/     (2 files) - Domain-specific experts
+├── swarm/           (6 files) - Swarm coordination and topology
+├── templates/       (1 file)  - Template generation
+└── testing/         (1 file)  - Quality assurance specialists
+```
+
+**Total:** 76 agent definition files
+
+---
+
+### 📁 `.claude/commands/` (81 files, 14 categories)
+
+Simple CLI command references (all <100 lines):
+
+```
+commands/
+├── agents/          (4 files)
+│   ├── agent-capabilities.md
+│   ├── agent-coordination.md
+│   ├── agent-spawning.md
+│   └── agent-types.md
+│
+├── analysis/        (2 files)
+│   ├── token-efficiency.md
+│   └── token-usage.md
+│
+├── automation/      (6 files)
+│   ├── auto-agent.md
+│   ├── self-healing.md
+│   ├── session-memory.md
+│   ├── smart-agents.md
+│   ├── smart-spawn.md
+│   └── workflow-select.md
+│
+├── coordination/    (6 files)
+│   ├── agent-spawn.md
+│   ├── init.md
+│   ├── orchestrate.md
+│   ├── spawn.md
+│   ├── swarm-init.md
+│   └── task-orchestrate.md
+│
+├── github/          (5 files)
+│   ├── code-review.md
+│   ├── github-swarm.md
+│   ├── issue-triage.md
+│   ├── pr-enhance.md
+│   └── repo-analyze.md
+│
+├── hive-mind/       (6 files)
+│   ├── hive-mind-consensus.md
+│   ├── hive-mind-init.md
+│   ├── hive-mind-memory.md
+│   ├── hive-mind-metrics.md
+│   ├── hive-mind-spawn.md
+│   └── hive-mind-status.md
+│
+├── hooks/           (6 files)
+│   ├── post-edit.md
+│   ├── post-task.md
+│   ├── pre-edit.md
+│   ├── pre-task.md
+│   ├── session-end.md
+│   └── setup.md
+│
+├── memory/          (4 files)
+│   ├── memory-persist.md
+│   ├── memory-search.md
+│   ├── memory-usage.md
+│   └── neural.md
+│
+├── monitoring/      (5 files)
+│   ├── agent-metrics.md
+│   ├── agents.md
+│   ├── real-time-view.md
+│   ├── status.md
+│   └── swarm-monitor.md
+│
+├── optimization/    (5 files)
+│   ├── auto-topology.md
+│   ├── cache-manage.md
+│   ├── parallel-execute.md
+│   ├── parallel-execution.md
+│   └── topology-optimize.md
+│
+├── sparc/           (16 files)
+│   ├── analyzer.md
+│   ├── architect.md
+│   ├── batch-executor.md
+│   ├── coder.md
+│   ├── debugger.md
+│   ├── designer.md
+│   ├── documenter.md
+│   ├── innovator.md
+│   ├── memory-manager.md
+│   ├── optimizer.md
+│   ├── researcher.md
+│   ├── reviewer.md
+│   ├── swarm-coordinator.md
+│   ├── tdd.md
+│   ├── tester.md
+│   └── workflow-manager.md
+│
+├── swarm/           (6 files)
+│   ├── swarm-background.md
+│   ├── swarm-init.md
+│   ├── swarm-modes.md
+│   ├── swarm-monitor.md
+│   ├── swarm-status.md
+│   └── swarm.md
+│
+├── training/        (5 files)
+│   ├── model-update.md
+│   ├── neural-patterns.md
+│   ├── neural-train.md
+│   ├── pattern-learn.md
+│   └── specialization.md
+│
+└── workflows/       (5 files)
+    ├── development.md
+    ├── research.md
+    ├── workflow-create.md
+    ├── workflow-execute.md
+    └── workflow-export.md
+```
+
+**Total:** 81 simple command reference files
+
+---
+
+### 📁 `.claude/skills/` (21 skills)
+
+Comprehensive workflow skills with YAML frontmatter and progressive disclosure:
+
+```
+skills/
+├── agentdb-memory-patterns/SKILL.md
+│   Memory patterns and caching strategies for distributed agents
+│
+├── agentdb-vector-search/SKILL.md
+│   Semantic search and RAG implementation with vector databases
+│
+├── flow-nexus-neural/SKILL.md
+│   Distributed neural network training in cloud sandboxes
+│
+├── flow-nexus-platform/SKILL.md
+│   Platform management: sandboxes, app store, payments, challenges
+│
+├── flow-nexus-swarm/SKILL.md
+│   Cloud swarm deployment and workflow automation
+│
+├── github-code-review/SKILL.md
+│   Multi-agent code review with PR coordination
+│
+├── github-multi-repo/SKILL.md
+│   Cross-repository synchronization and coordination
+│
+├── github-project-management/SKILL.md
+│   Issue tracking, project boards, and team coordination
+│
+├── github-release-management/SKILL.md
+│   Automated release coordination and deployment
+│
+├── github-workflow-automation/SKILL.md
+│   GitHub Actions workflow automation and CI/CD
+│
+├── hive-mind-advanced/SKILL.md
+│   Queen-led hierarchical coordination with consensus
+│
+├── hooks-automation/SKILL.md
+│   Intelligent hooks for coordination, formatting, learning
+│
+├── pair-programming/SKILL.md
+│   AI-assisted pair programming with modes and sessions
+│
+├── performance-analysis/SKILL.md
+│   Bottleneck detection and performance optimization
+│
+├── reasoningbank-intelligence/SKILL.md
+│   Advanced reasoning with WASM-powered memory and intelligence
+│
+├── skill-builder/SKILL.md
+│   Create new Claude Code skills with proper structure
+│
+├── sparc-methodology/SKILL.md
+│   Complete SPARC development workflow
+│
+├── stream-chain/SKILL.md
+│   Stream-JSON pipeline processing and automation
+│
+├── swarm-advanced/SKILL.md
+│   Advanced swarm orchestration patterns and examples
+│
+├── swarm-orchestration/SKILL.md
+│   Swarm coordination patterns and best practices
+│
+└── verification-quality/SKILL.md
+    Truth scoring, verification, and quality assurance
+```
+
+**Total:** 21 comprehensive skill files
+
+---
+
+## Key Differences: Commands vs Skills
+
+| Aspect | Commands | Skills |
+|--------|----------|--------|
+| **Purpose** | CLI quick reference | Comprehensive learning resource |
+| **Length** | <100 lines | >200 lines |
+| **Structure** | Simple markdown | YAML frontmatter + progressive disclosure |
+| **Examples** | 1-2 basic examples | 5-10+ detailed examples |
+| **Discovery** | CLI help, docs | Claude's autonomous discovery |
+| **When to Use** | Quick CLI syntax | Learn complex workflows |
+
+---
+
+## Distribution
+
+All files are included in the npm package via `package.json`:
+
+```json
+{
+  "files": [
+    ".claude/",
+    "bin/",
+    "dist/",
+    "src/"
+  ]
+}
+```
+
+When users run `npx claude-flow init`:
+1. ✅ All 76 agent files are copied
+2. ✅ All 81 command files are copied
+3. ✅ All 21 skill files are copied
+4. ✅ Helper scripts and configurations are created
+5. ✅ Hive Mind system is initialized
+
+---
+
+## Migration Summary
+
+**Consolidated from commands/ to skills/:**
+- 6 pair programming files → `pair-programming` skill
+- 12 GitHub workflow files → 5 GitHub skills
+- 9 Flow Nexus files → 3 Flow Nexus skills
+- 3 SPARC files → `sparc-methodology` skill
+- 3 verification files → `verification-quality` skill
+- 3 swarm files → `swarm-advanced` skill
+- 3 analysis files → `performance-analysis` skill
+- 2 stream-chain files → `stream-chain` skill
+- 11 hive-mind files → `hive-mind-advanced` skill
+- 5 hooks files → `hooks-automation` skill
+
+**Total:** 69 files consolidated into 16 new skills
+
+**Benefits:**
+- ✅ Cleaner command structure (simple references only)
+- ✅ Better organization (complex workflows in skills)
+- ✅ Improved discovery (Claude finds skills autonomously)
+- ✅ No duplication between commands and skills
+- ✅ Easier maintenance and updates
+
+---
+
+## Verification
+
+```bash
+# Test the init process
+npx claude-flow init --force
+
+# Expected output:
+# ✅ Copied 76 agent files
+# ✅ Copied 81 command files
+# ✅ Copied 21 skill files
+# ✅ Skill system setup complete
+# ✅ Agent system setup complete with 64 specialized agents
+```
+
+---
+
+**Status:** ✅ COMPLETE - Ready for distribution