claude-flow-novice 1.2.1 → 1.3.1

package/examples/research-workflow.yaml

@@ -0,0 +1,302 @@
+# Advanced Research Workflow with Conditional Execution and Loops
+name: "Advanced Research Workflow"
+version: "2.0.0"
+description: "Multi-stage research workflow with conditional execution, loops, and error recovery"
+
+metadata:
+  author: "Claude-Flow Team"
+  category: "Research"
+  tags: ["research", "analysis", "automation"]
+
+variables:
+  topic: "artificial intelligence trends"
+  depth: "comprehensive"
+  sources_limit: 10
+  enable_analysis: true
+  enable_summarization: true
+  output_format: "markdown"
+
+agents:
+  - id: "primary-researcher"
+    type: "researcher"
+    name: "Primary Research Agent"
+    config:
+      model: "claude-3"
+      temperature: 0.3
+      max_tokens: 4000
+      timeout: 180
+    resources:
+      memory: "2GB"
+      cpu: "1 core"
+    retries: 2
+
+  - id: "data-analyst"
+    type: "analyst" 
+    name: "Data Analysis Agent"
+    config:
+      model: "claude-3"
+      specialization: "data-analysis"
+      temperature: 0.1
+      timeout: 120
+    resources:
+      memory: "1GB"
+      cpu: "0.5 core"
+    retries: 1
+
+  - id: "summarizer"
+    type: "documenter"
+    name: "Summary Agent"
+    config:
+      model: "claude-3"
+      style: "academic"
+      format: "markdown"
+      timeout: 60
+
+conditions:
+  - id: "analysis-enabled"
+    expression: "variables.enable_analysis === true"
+    type: "javascript"
+    description: "Check if detailed analysis should be performed"
+
+  - id: "has-sufficient-data"
+    expression: "outputs['research-task.sources'].length >= 3"
+    type: "javascript"
+    description: "Ensure minimum data quality for analysis"
+
+  - id: "summarization-needed"
+    expression: "variables.enable_summarization && outputs['research-task.word_count'] > 2000"
+    type: "javascript"
+    description: "Check if content needs summarization"
+
+loops:
+  - id: "source-validation"
+    type: "foreach"
+    condition: "outputs['research-task.sources']"
+    tasks: ["validate-source"]
+    maxIterations: 10
+    continueOnError: true
+
+tasks:
+  - id: "research-task"
+    name: "Primary Research"
+    type: "research"
+    description: "Conduct comprehensive research on the specified topic"
+    assignTo: "primary-researcher"
+    input:
+      topic: "${topic}"
+      depth: "${depth}"
+      max_sources: "${sources_limit}"
+      research_areas:
+        - "current trends"
+        - "future predictions"
+        - "key technologies"
+        - "market analysis"
+    output:
+      - "findings"
+      - "sources"
+      - "summary"
+      - "word_count"
+      - "confidence_score"
+    timeout: 300000  # 5 minutes
+    retries: 2
+    priority: 1
+    tags: ["research", "primary"]
+    onSuccess: ["validate-results"]
+    onFailure: ["research-fallback"]
+
+  - id: "validate-source"
+    name: "Source Validation"
+    type: "validation"
+    description: "Validate research source quality and relevance"
+    assignTo: "data-analyst"
+    input:
+      source: "${loop.current_item}"
+      topic: "${topic}"
+    output:
+      - "is_valid"
+      - "quality_score"
+      - "relevance_score"
+    timeout: 30000
+    retries: 1
+
+  - id: "validate-results"
+    name: "Results Validation"
+    type: "validation"
+    description: "Validate research results quality"
+    depends: ["research-task"]
+    assignTo: "data-analyst"
+    input:
+      findings: "${research-task.findings}"
+      sources: "${research-task.sources}"
+      minimum_confidence: 0.7
+    output:
+      - "validation_passed"
+      - "quality_metrics"
+    timeout: 60000
+    condition: "has-sufficient-data"
+
+  - id: "detailed-analysis"
+    name: "Detailed Analysis"
+    type: "analysis"
+    description: "Perform detailed analysis of research findings"
+    depends: ["research-task", "validate-results"]
+    assignTo: "data-analyst"
+    condition: "analysis-enabled"
+    input:
+      research_data: "${research-task.findings}"
+      sources: "${research-task.sources}"
+      analysis_type: "comprehensive"
+      include_statistics: true
+      include_trends: true
+    output:
+      - "insights"
+      - "trends"
+      - "recommendations"
+      - "statistics"
+      - "risk_analysis"
+    timeout: 240000  # 4 minutes
+    retries: 1
+    priority: 2
+    parallel: true
+
+  - id: "market-analysis"
+    name: "Market Analysis"
+    type: "analysis"
+    description: "Analyze market implications and opportunities"
+    depends: ["research-task"]
+    assignTo: "data-analyst"
+    condition: "analysis-enabled"
+    input:
+      research_data: "${research-task.findings}"
+      focus_areas:
+        - "market size"
+        - "growth potential"
+        - "competitive landscape"
+        - "investment opportunities"
+    output:
+      - "market_insights"
+      - "opportunities"
+      - "risks"
+      - "competitive_analysis"
+    timeout: 180000
+    priority: 2
+    parallel: true
+
+  - id: "generate-summary"
+    name: "Generate Summary"
+    type: "documentation"
+    description: "Generate comprehensive summary report"
+    depends: ["research-task", "detailed-analysis", "market-analysis"]
+    assignTo: "summarizer"
+    condition: "summarization-needed"
+    input:
+      research_summary: "${research-task.summary}"
+      detailed_insights: "${detailed-analysis.insights}"
+      market_analysis: "${market-analysis.market_insights}"
+      format: "${output_format}"
+      style: "executive"
+      max_length: 2000
+    output:
+      - "executive_summary"
+      - "detailed_report"
+      - "key_findings"
+      - "recommendations"
+    timeout: 120000
+    priority: 3
+
+  - id: "research-fallback"
+    name: "Fallback Research"
+    type: "research"
+    description: "Simplified research if primary task fails"
+    assignTo: "primary-researcher"
+    input:
+      topic: "${topic}"
+      depth: "basic"
+      max_sources: 5
+    output:
+      - "basic_findings"
+      - "basic_sources"
+    timeout: 120000
+    retries: 1
+
+  - id: "quality-check"
+    name: "Final Quality Check"
+    type: "validation"
+    description: "Final quality assurance check"
+    depends: ["generate-summary"]
+    input:
+      summary: "${generate-summary.executive_summary}"
+      research: "${research-task.findings}"
+      quality_criteria:
+        - "completeness"
+        - "accuracy"
+        - "relevance"
+        - "clarity"
+    output:
+      - "quality_score"
+      - "passed"
+      - "improvements"
+    timeout: 60000
+
+integrations:
+  - id: "notification-webhook"
+    type: "webhook"
+    config:
+      url: "https://hooks.slack.com/services/..."
+      method: "POST"
+      headers:
+        Content-Type: "application/json"
+    auth:
+      type: "bearer"
+      credentials:
+        token: "${SLACK_WEBHOOK_TOKEN}"
+
+  - id: "results-database"
+    type: "database"
+    config:
+      connectionString: "${DB_CONNECTION_STRING}"
+      table: "research_results"
+    auth:
+      type: "basic"
+      credentials:
+        username: "${DB_USER}"
+        password: "${DB_PASS}"
+
+settings:
+  maxConcurrency: 3
+  timeout: 900000  # 15 minutes
+  retryPolicy: "exponential"
+  failurePolicy: "continue"
+  errorHandler: "log-and-notify"
+  
+  monitoring:
+    enabled: true
+    interval: 5000
+    metrics:
+      - "progress"
+      - "performance" 
+      - "errors"
+      - "resource_usage"
+    alerts:
+      - condition: "error_rate > 0.3"
+        action: "notification-webhook"
+        threshold: 3
+        cooldown: 300000
+
+  resources:
+    limits:
+      memory: "8GB"
+      cpu: "4 cores"
+      disk: "1GB"
+    requests:
+      memory: "4GB"
+      cpu: "2 cores"
+      disk: "500MB"
+
+  notifications:
+    enabled: true
+    channels: ["webhook", "email"]
+    events: ["workflow.started", "workflow.completed", "workflow.failed", "task.failed"]
+    templates:
+      workflow.completed: "Research workflow '${workflow.name}' completed successfully"
+      workflow.failed: "Research workflow '${workflow.name}' failed: ${error.message}"

package/examples/rest-api-simple/.env.example

@@ -0,0 +1 @@
+PORT=3000

package/examples/rest-api-simple/README-ARCHITECTURE.md

@@ -0,0 +1,165 @@
+# Simple REST API - Architecture Summary
+
+## 📋 Architecture Overview
+
+This simple REST API demonstrates clean, minimal architecture patterns using Express.js. The design prioritizes simplicity, clarity, and extensibility while maintaining REST best practices.
+
+## 🏗️ Key Architecture Decisions
+
+### 1. **Single-File Architecture**
+- All server logic in one `server.js` file (~200 lines)
+- Easy to understand and modify
+- Perfect for learning and prototyping
+
+### 2. **In-Memory Data Storage**
+- No database complexity
+- Zero configuration
+- Fast development cycle
+- Data structure: Array of task objects
+
+### 3. **Minimal Dependencies**
+- Production: Only Express.js
+- Development: Jest, Supertest, Nodemon
+- No unnecessary packages
+
+### 4. **RESTful Design**
+- Resource-based URLs (`/api/v1/tasks`)
+- Proper HTTP methods and status codes
+- JSON request/response format
+- Consistent error handling
+
+## 📁 Project Structure
+
+```
+examples/rest-api-simple/
+├── server.js                    # Main application (all logic)
+├── server.test.js              # Comprehensive test suite
+├── package.json               # Project metadata and scripts
+├── README.md                 # User documentation
+├── architecture.md          # Detailed architecture (Mermaid diagrams)
+├── api-specification.md    # Complete API documentation
+├── implementation-plan.md  # Phased development plan
+└── README-ARCHITECTURE.md  # This summary
+```
+
+## 🔄 Data Flow
+
+1. **Client** sends HTTP request
+2. **Express middleware** processes request (JSON parsing)
+3. **Route handler** executes business logic
+4. **In-memory store** performs data operation
+5. **Response formatter** creates JSON response
+6. **Client** receives structured response
+
+## 🛡️ Security Considerations
+
+### Current (Simple) Implementation
+- No authentication/authorization
+- Basic input validation
+- Error messages don't expose internals
+- Suitable for development only
+
+### Production Recommendations
+- Add JWT authentication
+- Implement rate limiting
+- Use HTTPS
+- Add comprehensive validation
+- Implement CORS properly
+
+## 🚀 Quick Start Implementation
+
+### Option 1: Sequential SPARC Execution (~50 minutes)
+```bash
+# Phase 1: Setup
+npx claude-flow sparc run code "Setup Express server with health endpoint" --non-interactive
+
+# Phase 2: CRUD with TDD
+npx claude-flow sparc run tdd "Implement CRUD operations for tasks" --non-interactive
+
+# Phase 3: Validation
+npx claude-flow sparc run code "Add input validation and error handling" --non-interactive
+
+# Phase 4: Documentation
+npx claude-flow sparc run docs-writer "Create REST API documentation" --non-interactive
+
+# Phase 5: Security Review
+npx claude-flow sparc run security-review "Review API security" --non-interactive
+```
+
+### Option 2: Parallel Swarm Execution (~15 minutes)
+```bash
+# Complete implementation with parallel agents
+npx claude-flow swarm "Build complete simple REST API from architecture docs" \
+  --strategy development --background --parallel --testing \
+  --max-agents 4 --output ./examples/rest-api-simple/
+
+# Monitor progress
+npx claude-flow monitor
+```
+
+## 📊 API Endpoints Summary
+
+| Method | Endpoint | Description |
+|--------|----------|-------------|
+| GET | `/health` | Health check |
+| GET | `/api/v1/tasks` | List all tasks |
+| GET | `/api/v1/tasks/:id` | Get single task |
+| POST | `/api/v1/tasks` | Create new task |
+| PUT | `/api/v1/tasks/:id` | Update task |
+| DELETE | `/api/v1/tasks/:id` | Delete task |
+
+## 🧪 Testing Strategy
+
+- **Framework**: Jest + Supertest
+- **Coverage Goal**: > 90%
+- **Test Types**: Integration tests for all endpoints
+- **Test Scenarios**: Happy path, error cases, edge cases
+
+## 💡 Extension Points
+
+### Easy Additions
+1. **Pagination**: Add limit/offset query params
+2. **Filtering**: Add completed status filter
+3. **Sorting**: Add sort by date/title
+4. **Search**: Add title search capability
+
+### Advanced Extensions
+1. **Database**: Replace in-memory with MongoDB/PostgreSQL
+2. **Authentication**: Add JWT-based auth
+3. **Caching**: Add Redis for performance
+4. **Real-time**: Add WebSocket support
+5. **GraphQL**: Add GraphQL endpoint
+
+## 📈 Performance Characteristics
+
+- **Response Time**: < 10ms (in-memory operations)
+- **Throughput**: ~1000 req/sec (single instance)
+- **Memory Usage**: Grows with data (no persistence)
+- **Startup Time**: < 1 second
+
+## 🎯 Success Metrics
+
+- ✅ Clean, readable code
+- ✅ Full CRUD functionality
+- ✅ Comprehensive tests
+- ✅ Proper error handling
+- ✅ RESTful design
+- ✅ Easy to extend
+- ✅ Well-documented
+- ✅ No security vulnerabilities
+
+## 📚 Architecture Documents
+
+1. **[architecture.md](./architecture.md)** - System design with diagrams
+2. **[api-specification.md](./api-specification.md)** - Complete API reference
+3. **[implementation-plan.md](./implementation-plan.md)** - Development phases
+
+## 🏆 Architecture Principles Applied
+
+1. **KISS** (Keep It Simple, Stupid)
+2. **YAGNI** (You Aren't Gonna Need It)
+3. **DRY** (Don't Repeat Yourself)
+4. **SOLID** principles where applicable
+5. **REST** constraints
+
+This architecture provides a solid foundation for a simple REST API that can be easily understood, tested, and extended as requirements grow.

package/examples/rest-api-simple/README.md

@@ -0,0 +1,99 @@
+# Simple REST API
+
+A super simple REST API built with Express.js that demonstrates basic CRUD operations.
+
+## Features
+
+- In-memory data storage
+- Full CRUD operations (Create, Read, Update, Delete)
+- JSON request/response format
+- Health check endpoint
+- No database required
+
+## Installation
+
+```bash
+npm install
+```
+
+## Running the API
+
+```bash
+# Production mode
+npm start
+
+# Development mode with auto-reload
+npm run dev
+```
+
+The API will start on port 3000 by default, or use the PORT environment variable.
+
+## API Endpoints
+
+### Root Endpoint
+- **GET /** - Welcome message and endpoint list
+
+### Items Resource
+- **GET /api/items** - Get all items
+- **GET /api/items/:id** - Get a single item by ID
+- **POST /api/items** - Create a new item
+- **PUT /api/items/:id** - Update an existing item
+- **DELETE /api/items/:id** - Delete an item
+
+### Health Check
+- **GET /health** - API health status
+
+## Example Usage
+
+### Get all items
+```bash
+curl http://localhost:3000/api/items
+```
+
+### Get a single item
+```bash
+curl http://localhost:3000/api/items/1
+```
+
+### Create a new item
+```bash
+curl -X POST http://localhost:3000/api/items \
+  -H "Content-Type: application/json" \
+  -d '{"name": "New Item", "description": "This is a new item"}'
+```
+
+### Update an item
+```bash
+curl -X PUT http://localhost:3000/api/items/1 \
+  -H "Content-Type: application/json" \
+  -d '{"name": "Updated Item", "description": "This is an updated item"}'
+```
+
+### Delete an item
+```bash
+curl -X DELETE http://localhost:3000/api/items/1
+```
+
+## Response Format
+
+### Success Response
+```json
+{
+  "id": 1,
+  "name": "Item 1",
+  "description": "This is the first item"
+}
+```
+
+### Error Response
+```json
+{
+  "error": "Item not found"
+}
+```
+
+## Notes
+
+- Data is stored in memory and will be lost when the server restarts
+- No authentication or authorization is implemented
+- This is a demonstration API for learning purposes