claude-flow-novice 1.2.1 → 1.3.1

package/examples/06-tutorials/README.md

@@ -0,0 +1,121 @@
+# Tutorials and Guides
+
+Step-by-step tutorials and comprehensive guides for using Claude Flow features.
+
+## Directory Structure
+
+```
+06-tutorials/
+├── getting-started/    # Beginner tutorials
+├── sparc/              # SPARC methodology guides
+├── workflows/          # Workflow orchestration tutorials
+├── advanced/           # Advanced features and patterns
+└── sparc-batchtool-orchestration.md  # Original BatchTool guide
+```
+
+## Tutorial Categories
+
+### Getting Started (`getting-started/`)
+- **01-first-swarm.md**: Create your first swarm and understand basics
+  - Swarm creation and execution
+  - Understanding agent roles
+  - Customizing behavior
+  - Running generated applications
+
+### SPARC Methodology (`sparc/`)
+- **sparc-tdd-guide.md**: Complete SPARC TDD workflow guide
+  - Specification → Pseudocode → Architecture → Refinement → Completion
+  - Test-driven development with AI
+  - Security reviews and integration
+  - Best practices and patterns
+
+### Workflow Orchestration (`workflows/`)
+- **multi-agent-coordination.md**: Advanced multi-agent coordination
+  - Agent specialization and roles
+  - Dependency management
+  - Coordination patterns (hub-spoke, mesh, pipeline)
+  - Performance optimization
+  - Error handling and recovery
+
+## Legacy Tutorial
+
+### sparc-batchtool-orchestration.md
+Original comprehensive guide to BatchTool with SPARC modes covering:
+- Parallel execution patterns
+- Dependency management
+- CI/CD integration
+
+## Tutorial Topics
+
+### Getting Started
+1. System setup and configuration
+2. First swarm creation
+3. Understanding agent roles
+4. Basic task execution
+
+### Advanced Features
+1. Custom agent capabilities
+2. Memory persistence
+3. Quality thresholds
+4. Monitoring and logging
+5. Error recovery
+
+### Integration Patterns
+1. CI/CD pipelines
+2. Automated testing
+3. Code generation workflows
+4. Documentation automation
+
+### Best Practices
+1. Agent specialization
+2. Task decomposition
+3. Resource optimization
+4. Security considerations
+
+## Using Tutorials
+
+Each tutorial includes:
+- **Prerequisites**: What you need to know
+- **Step-by-step instructions**: Clear, numbered steps
+- **Code examples**: Working demonstrations
+- **Troubleshooting**: Common issues and solutions
+- **Next steps**: Where to go from here
+
+## Contributing Tutorials
+
+When writing new tutorials:
+1. Start with clear objectives
+2. Include working examples
+3. Explain the "why" not just "how"
+4. Add diagrams where helpful
+5. Test all code examples
+6. Include common pitfalls
+
+## Tutorial Format
+
+```markdown
+# Tutorial Title
+
+## Overview
+Brief description of what will be learned
+
+## Prerequisites
+- Required knowledge
+- System requirements
+- Previous tutorials
+
+## Steps
+1. **Step Title**
+   - Explanation
+   - Code example
+   - Expected output
+
+## Troubleshooting
+- Common error: Solution
+- Issue: Resolution
+
+## Summary
+- What was learned
+- Key takeaways
+- Next tutorials
+```

package/examples/06-tutorials/getting-started/01-first-swarm.md

@@ -0,0 +1,121 @@
+# Your First Claude Flow Swarm
+
+This tutorial will guide you through creating your first swarm and understanding how Claude Flow works.
+
+## Prerequisites
+
+- Claude Flow installed (`npm install -g claude-flow`)
+- Basic command line knowledge
+- Node.js 18+ installed
+
+## Step 1: Understanding Swarms
+
+A swarm is a coordinated group of AI agents working together to complete a task. Each agent has specific capabilities and roles.
+
+## Step 2: Create a Simple Swarm
+
+Let's create a basic "Hello World" application:
+
+```bash
+cd examples
+../claude-flow swarm create "Build a hello world CLI application" \
+  --name my-first-swarm \
+  --output ./output/hello-world
+```
+
+### What happens:
+1. Claude Flow creates a swarm coordinator
+2. Assigns agents based on the task
+3. Agents work together to build the application
+4. Output is saved to the specified directory
+
+## Step 3: Examine the Output
+
+```bash
+cd ./output/hello-world
+ls -la
+```
+
+You should see:
+- `index.js` - Main application file
+- `package.json` - Node.js configuration
+- `README.md` - Documentation
+- `test.js` - Test file (if tests were requested)
+
+## Step 4: Run Your Application
+
+```bash
+npm install  # Install any dependencies
+npm start    # Run the application
+```
+
+## Step 5: Understanding Agent Roles
+
+Check the swarm logs to see how agents collaborated:
+
+```bash
+cat ../../logs/swarm-*.log
+```
+
+You'll see agents like:
+- **Analyzer**: Understood requirements
+- **Developer**: Wrote the code
+- **Documenter**: Created README
+- **Tester**: Added tests
+
+## Step 6: Customizing Your Swarm
+
+Try with more specific requirements:
+
+```bash
+../claude-flow swarm create \
+  "Build a CLI calculator that supports add, subtract, multiply, divide" \
+  --agents 3 \
+  --strategy development \
+  --name calculator-swarm
+```
+
+### Parameters explained:
+- `--agents 3`: Use 3 specialized agents
+- `--strategy development`: Focus on code creation
+- `--name`: Give your swarm a memorable name
+
+## Next Steps
+
+1. Try different strategies:
+   - `research`: For gathering information
+   - `analysis`: For code review
+   - `testing`: For test creation
+   - `optimization`: For performance improvements
+
+2. Use configuration files:
+   ```bash
+   ../claude-flow swarm create "Your task" \
+     --config ../01-configurations/basic/simple-config.json
+   ```
+
+3. Monitor swarm progress:
+   ```bash
+   ../claude-flow swarm create "Your task" --monitor
+   ```
+
+## Common Issues
+
+**Problem**: Swarm takes too long
+- **Solution**: Use `--timeout 60000` to set limits
+
+**Problem**: Not enough detail in output
+- **Solution**: Be more specific in your task description
+
+**Problem**: Want different output structure
+- **Solution**: Include structure requirements in your prompt
+
+## Summary
+
+You've learned to:
+- ✅ Create a basic swarm
+- ✅ Understand agent collaboration
+- ✅ Customize swarm behavior
+- ✅ Run generated applications
+
+Continue to [Tutorial 2: Working with Workflows](./02-workflows-intro.md)

package/examples/06-tutorials/sparc/sparc-tdd-guide.md

@@ -0,0 +1,269 @@
+# SPARC Test-Driven Development Guide
+
+Learn how to use SPARC methodology for systematic TDD with Claude Flow.
+
+## What is SPARC?
+
+SPARC stands for:
+- **S**pecification: Define requirements clearly
+- **P**seudocode: Plan the logic
+- **A**rchitecture: Design the structure
+- **R**efinement: Implement with TDD
+- **C**ompletion: Integrate and polish
+
+## Prerequisites
+
+- Claude Flow with SPARC modes configured
+- Understanding of TDD principles
+- Basic programming knowledge
+
+## Tutorial: Building a User Authentication System
+
+### Step 1: Specification Phase
+
+Define what we're building:
+
+```bash
+cd examples
+../claude-flow sparc run spec-pseudocode \
+  "Design a user authentication system with:
+   - Email/password login
+   - JWT tokens
+   - Password reset
+   - Rate limiting
+   - Security best practices"
+```
+
+This creates:
+- Detailed requirements document
+- User stories
+- Acceptance criteria
+- Edge cases
+
+### Step 2: Pseudocode Phase
+
+Plan the implementation logic:
+
+```bash
+../claude-flow sparc run spec-pseudocode \
+  "Create pseudocode for authentication flow:
+   - Login process
+   - Token generation
+   - Password hashing
+   - Session management"
+```
+
+Output includes:
+- Algorithm descriptions
+- Data flow diagrams
+- State transitions
+- Error handling logic
+
+### Step 3: Architecture Phase
+
+Design the system structure:
+
+```bash
+../claude-flow sparc run architect \
+  "Design authentication service architecture:
+   - API endpoints
+   - Database schema
+   - Security layers
+   - Integration points"
+```
+
+Creates:
+- System diagrams
+- API specifications
+- Database designs
+- Security architecture
+
+### Step 4: TDD Implementation (Refinement)
+
+Now we implement using Test-Driven Development:
+
+```bash
+../claude-flow sparc tdd \
+  "Implement user authentication system" \
+  --spec ./output/auth-spec.md \
+  --architecture ./output/auth-architecture.md
+```
+
+#### The TDD Cycle:
+
+1. **RED Phase** - Write failing tests first:
+   ```javascript
+   // Generated test example
+   describe('Authentication', () => {
+     it('should hash passwords securely', async () => {
+       const password = 'testPass123';
+       const hash = await authService.hashPassword(password);
+       expect(hash).not.toBe(password);
+       expect(hash.length).toBeGreaterThan(50);
+     });
+   });
+   ```
+
+2. **GREEN Phase** - Implement minimal code to pass:
+   ```javascript
+   // Generated implementation
+   async hashPassword(password) {
+     const salt = await bcrypt.genSalt(10);
+     return bcrypt.hash(password, salt);
+   }
+   ```
+
+3. **REFACTOR Phase** - Optimize and clean up:
+   ```javascript
+   // Refactored version
+   async hashPassword(password, rounds = 10) {
+     if (!password || password.length < 8) {
+       throw new Error('Invalid password');
+     }
+     const salt = await bcrypt.genSalt(rounds);
+     return bcrypt.hash(password, salt);
+   }
+   ```
+
+### Step 5: Integration Testing
+
+Test the complete system:
+
+```bash
+../claude-flow sparc run integration \
+  "Test authentication system integration:
+   - API endpoints
+   - Database operations
+   - Token validation
+   - Error handling"
+```
+
+### Step 6: Security Review
+
+Ensure security best practices:
+
+```bash
+../claude-flow sparc run security-review \
+  "Review authentication system for:
+   - OWASP compliance
+   - SQL injection
+   - XSS vulnerabilities
+   - Token security"
+```
+
+## Advanced SPARC Features
+
+### Parallel Mode Execution
+
+Run multiple SPARC modes simultaneously:
+
+```bash
+../claude-flow sparc run parallel \
+  --modes "spec-pseudocode,architect,code" \
+  "Create payment processing system"
+```
+
+### Memory Integration
+
+Store and retrieve SPARC artifacts:
+
+```bash
+# Store specifications
+../claude-flow memory store auth_spec "$(cat ./output/auth-spec.md)"
+
+# Retrieve for future work
+../claude-flow memory query auth_spec > ./restored-spec.md
+```
+
+### Custom Test Patterns
+
+Define test templates:
+
+```bash
+../claude-flow sparc tdd \
+  "Create user service" \
+  --test-pattern "AAA" \  # Arrange-Act-Assert
+  --coverage-threshold 90
+```
+
+## Best Practices
+
+### 1. Specification Quality
+- Be specific about requirements
+- Include error scenarios
+- Define performance criteria
+- Document security needs
+
+### 2. TDD Discipline
+- Always write tests first
+- One test at a time
+- Keep tests simple
+- Test behavior, not implementation
+
+### 3. Architecture Decisions
+- Document why, not just what
+- Consider scalability early
+- Plan for change
+- Keep it simple
+
+### 4. Integration Points
+- Test boundaries thoroughly
+- Mock external services
+- Verify error propagation
+- Check edge cases
+
+## Common Patterns
+
+### Authentication Flow
+```bash
+../claude-flow sparc tdd "implement login flow" \
+  --pattern "request-validate-authenticate-respond"
+```
+
+### CRUD Operations
+```bash
+../claude-flow sparc tdd "implement user CRUD" \
+  --pattern "rest-api" \
+  --with-validation
+```
+
+### Event-Driven Systems
+```bash
+../claude-flow sparc tdd "implement event handlers" \
+  --pattern "pub-sub" \
+  --async
+```
+
+## Troubleshooting
+
+### Tests Not Running
+- Check test file naming (*.test.js)
+- Verify test runner configuration
+- Ensure dependencies installed
+
+### Coverage Too Low
+- Add edge case tests
+- Test error conditions
+- Cover all branches
+
+### Integration Failures
+- Check service dependencies
+- Verify environment variables
+- Test in isolation first
+
+## Summary
+
+You've learned:
+- ✅ SPARC methodology phases
+- ✅ TDD implementation cycle
+- ✅ Integration and security testing
+- ✅ Best practices and patterns
+
+## Next Steps
+
+1. Try building a complete feature with SPARC
+2. Explore other SPARC modes
+3. Create custom test patterns
+4. Integrate with CI/CD
+
+Continue to [Advanced SPARC Patterns](./sparc-advanced-patterns.md)