claude-flow-novice 1.5.20 → 1.5.22

package/.claude/agents/agent-principles/agent-type-guidelines.md

@@ -0,0 +1,328 @@
+# Agent Type Guidelines
+
+**Version:** 2.0.0
+**Last Updated:** 2025-09-30
+
+## Overview
+
+This document provides specific guidance for creating different types of agents based on their primary function.
+
+---
+
+## 1. Coder Agents
+
+### For Rust (VALIDATED)
+
+**Basic Tasks:** Use CODE-HEAVY
+
+```yaml
+Tasks:
+  - String processing
+  - Basic error handling
+  - Simple data structures
+  - CRUD operations
+  - Configuration parsing
+
+Expected Improvement: +43% quality vs Minimal
+```
+
+**Complex Tasks:** Use MINIMAL
+
+```yaml
+Tasks:
+  - Lock-free algorithms
+  - Lifetime-complex generics
+  - Unsafe code design
+  - Embedded HAL
+  - Async runtime design
+
+Expected Improvement: +31% quality vs Code-Heavy
+```
+
+**Example Agents:**
+- `benchmarking-tests/test-agent-code-heavy.md` - Basic tasks
+- `benchmarking-tests/test-agent-minimal.md` - Complex tasks
+
+### For JavaScript/TypeScript (HYPOTHESIS)
+
+Apply same principles but validate with testing:
+
+**Basic Tasks:** Code-Heavy
+- Simple React components
+- Express route handlers
+- Utility functions
+- Basic async/await
+
+**Complex Tasks:** Minimal
+- State management architecture
+- Complex React patterns (render props, HOCs)
+- Performance optimization
+- TypeScript advanced types
+
+---
+
+## 2. Reviewer Agents
+
+**Recommended Format:** MINIMAL
+
+**Rationale:**
+- Reviews require contextual reasoning
+- Over-specification creates checklist mentality
+- Need flexibility to identify novel issues
+- Trust AI's pattern recognition
+
+**Key Responsibilities:**
+- Assess code quality, readability, and maintainability
+- Identify bugs, security issues, and performance problems
+- Suggest architectural improvements
+- Ensure adherence to best practices
+
+**Review Approach:**
+
+### 1. Initial Assessment
+- Understand the change's purpose
+- Review related context (issues, documentation)
+- Identify the scope and impact
+
+### 2. Deep Analysis
+- **Correctness**: Does it work as intended?
+- **Security**: Any vulnerabilities?
+- **Performance**: Efficiency concerns?
+- **Maintainability**: Easy to understand and modify?
+- **Testing**: Adequate test coverage?
+
+### 3. Provide Feedback
+- Be specific and actionable
+- Explain the "why" behind suggestions
+- Offer alternatives when critiquing
+- Acknowledge good patterns
+
+**Example:** `quality/reviewer.md`
+
+---
+
+## 3. Architect Agents
+
+**Recommended Format:** MINIMAL
+
+**Rationale:**
+- Architecture requires strategic thinking
+- Solutions must be context-specific
+- Over-constraining limits creative solutions
+- Need to consider trade-offs dynamically
+
+**Core Responsibilities:**
+- Design system architectures from requirements
+- Make strategic technical decisions
+- Evaluate technology trade-offs
+- Create architectural documentation
+
+**Approach:**
+
+### Requirements Analysis
+Extract functional and non-functional requirements, identify constraints and quality attributes, understand stakeholder needs.
+
+### Architecture Design
+Apply appropriate patterns (microservices, event-driven, CQRS), consider trade-offs, document decisions with ADRs.
+
+### Decision Making
+Framework for evaluating options with explicit trade-off documentation.
+
+**Collaboration:**
+- Work with Coder agents for implementation guidance
+- Coordinate with Reviewer agents for design validation
+- Provide specifications to DevOps for infrastructure
+- Share ADRs via memory system
+
+**Example:** `architecture/system-architect.md`
+
+---
+
+## 4. Tester Agents
+
+**Recommended Format:** CODE-HEAVY for unit tests, METADATA for test strategy
+
+**Rationale:**
+- Unit tests benefit from concrete patterns
+- Test structure is often formulaic
+- Examples show proper assertion style
+- But test strategy needs metadata structure
+
+**Test Patterns:**
+
+### Rust Testing Pattern
+
+```rust
+#[cfg(test)]
+mod tests {
+    use super::*;
+
+    #[test]
+    fn test_success_case() {
+        let result = function_under_test(valid_input);
+        assert_eq!(result, expected_output);
+    }
+
+    #[test]
+    fn test_error_case() {
+        let result = function_under_test(invalid_input);
+        assert!(result.is_err());
+    }
+
+    #[test]
+    #[should_panic(expected = "error message")]
+    fn test_panic_case() {
+        function_that_should_panic();
+    }
+}
+```
+
+### JavaScript Testing Pattern
+
+```javascript
+describe('ModuleName', () => {
+  beforeEach(() => {
+    // Setup
+  });
+
+  afterEach(() => {
+    // Cleanup
+  });
+
+  test('should handle success case', () => {
+    const result = functionUnderTest(validInput);
+    expect(result).toEqual(expectedOutput);
+  });
+
+  test('should handle error case', async () => {
+    await expect(asyncFunction(invalidInput))
+      .rejects.toThrow('error message');
+  });
+});
+```
+
+**Test Strategy:**
+
+```yaml
+Coverage Requirements:
+  unit_tests: 85%
+  integration_tests: 70%
+  e2e_tests: 30%
+
+Test Categories:
+  - Happy path tests
+  - Error condition tests
+  - Edge case tests
+  - Performance tests (if applicable)
+```
+
+**Example:** `testing/unit/tdd-london-swarm.md`
+
+---
+
+## 5. Researcher Agents
+
+**Recommended Format:** MINIMAL
+
+**Rationale:**
+- Research requires open-ended exploration
+- Avoid bias from excessive structure
+- Let evidence guide conclusions
+- Need flexibility in methodology
+
+**Core Responsibilities:**
+- Research technologies, patterns, and best practices
+- Analyze trade-offs and alternatives
+- Provide evidence-based recommendations
+- Stay current with industry trends
+
+**Research Approach:**
+
+1. **Define Scope**: Clarify what needs research
+2. **Gather Information**: Use multiple sources
+3. **Analyze Findings**: Evaluate objectively
+4. **Synthesize**: Draw actionable conclusions
+5. **Document**: Clear, referenced reports
+
+**Success Metrics:**
+- Recommendations are actionable
+- Research is thorough and unbiased
+- Sources are credible and current
+
+**Example:** `researcher.md`
+
+---
+
+## 6. DevOps Agents
+
+**Recommended Format:** METADATA
+
+**Rationale:**
+- DevOps involves structured workflows
+- Clear requirements for CI/CD pipelines
+- Deployment checklists are essential
+- Balance structure with flexibility
+
+**Pipeline Structure:**
+
+```yaml
+CI Pipeline Stages:
+  1_build:
+    steps: [checkout, dependencies, compile]
+    failure_action: fail_fast
+
+  2_test:
+    steps: [unit_tests, integration_tests, e2e_tests]
+    coverage_threshold: 80%
+
+  3_quality:
+    steps: [lint, security_scan, dependency_audit]
+    blocking: true
+
+  4_deploy:
+    environments: [staging, production]
+    strategy: blue_green
+    rollback_enabled: true
+```
+
+**Deployment Strategy:**
+
+```yaml
+Deployment Process:
+  pre_deployment:
+    - backup_database
+    - notify_team
+    - create_deployment_tag
+
+  deployment:
+    - deploy_to_staging
+    - run_smoke_tests
+    - await_approval
+    - deploy_to_production
+
+  post_deployment:
+    - verify_health_checks
+    - monitor_metrics
+    - notify_completion
+
+  rollback_triggers:
+    - error_rate > 5%
+    - response_time > 2s
+    - health_check_failures > 3
+```
+
+**Example:** `devops/ci-cd/ops-cicd-github.md`
+
+---
+
+## Agent Selection Guide
+
+**Core Development**: coder, tester, reviewer
+**Backend**: backend-dev, api-docs, system-architect
+**Frontend**: coder (specialized), mobile-dev
+**Quality**: tester, reviewer, security-specialist, perf-analyzer
+**Planning**: researcher, planner, architect
+**Operations**: devops-engineer, cicd-engineer
+**Documentation**: api-docs, researcher
+
+**Select agents based on actual task needs, not predefined patterns.**

package/.claude/agents/agent-principles/format-selection.md

@@ -0,0 +1,204 @@
+# Agent Format Selection Principles
+
+**Version:** 2.0.0
+**Last Updated:** 2025-09-30
+
+## The Three Agent Formats
+
+### Format 1: MINIMAL (Complex Tasks)
+
+**Use For:**
+- Architectural design
+- Code review and analysis
+- Research and investigation
+- Strategic decision-making
+- Creative problem-solving
+
+**Characteristics:**
+- **Length**: 200-400 lines
+- **Structure**: Role definition + Core principles + Minimal constraints
+- **Philosophy**: Trust the AI's reasoning; provide direction, not prescription
+
+**Why Minimal Works for Complex Tasks:**
+- Avoids over-constraining the solution space
+- Allows creative application of principles
+- Reduces cognitive load from excessive instructions
+- Trusts AI's pattern recognition and reasoning
+
+---
+
+### Format 2: METADATA (Medium Complexity)
+
+**Use For:**
+- Structured workflows with clear steps
+- API development with specifications
+- DevOps pipeline automation
+- Data processing pipelines
+- Configuration management
+
+**Characteristics:**
+- **Length**: 400-700 lines
+- **Structure**: Detailed specifications + Requirements + Structured examples
+- **Philosophy**: Provide scaffolding through metadata; guide without examples
+
+**Why Metadata Works for Medium Tasks:**
+- Provides structure without over-prescribing implementation
+- Ensures completeness through checklists
+- Balances guidance with flexibility
+- Clearly defines requirements and success criteria
+
+---
+
+### Format 3: CODE-HEAVY (Basic Tasks)
+
+**Use For:**
+- Basic CRUD operations
+- Simple parsing and string manipulation
+- Standard configuration tasks
+- Common testing patterns
+- Straightforward implementations
+
+**Characteristics:**
+- **Length**: 700-1200 lines
+- **Structure**: Detailed examples + Code patterns + Step-by-step guidance
+- **Philosophy**: Show exactly what good looks like; prime with concrete examples
+
+**Why Code-Heavy Works for Basic Tasks:**
+- Concrete examples reduce ambiguity
+- Patterns prime the AI for correct idioms
+- Step-by-step guidance ensures completeness
+- Visual comparisons (❌ vs ✅) reinforce best practices
+- Reduces iteration cycles for straightforward tasks
+
+---
+
+## Format Selection Decision Tree
+
+```
+┌─────────────────────────────────────────────────────┐
+│  What is the PRIMARY task complexity?              │
+└─────────────────────────────────────────────────────┘
+                        │
+        ┌───────────────┼───────────────┐
+        │               │               │
+        ▼               ▼               ▼
+    ┌───────┐      ┌─────────┐    ┌─────────┐
+    │ BASIC │      │ MEDIUM  │    │ COMPLEX │
+    └───────┘      └─────────┘    └─────────┘
+        │               │               │
+        │               │               │
+        ▼               ▼               ▼
+
+┌─────────────┐  ┌───────────────┐  ┌──────────────┐
+│ CODE-HEAVY  │  │   METADATA    │  │   MINIMAL    │
+│   FORMAT    │  │    FORMAT     │  │   FORMAT     │
+└─────────────┘  └───────────────┘  └──────────────┘
+
+Examples:         Examples:          Examples:
+- Parsing         - API dev          - Architecture
+- CRUD ops        - CI/CD            - Code review
+- String manip    - Data pipeline    - Research
+- Config files    - Workflow auto    - Strategy
+- Unit tests      - ETL processes    - Design
+
+Quality:          Quality:           Quality:
++43% vs Min       Balanced           +31% vs Code
+
+Lines:            Lines:             Lines:
+700-1200          400-700            200-400
+```
+
+## Decision Factors Matrix
+
+| Factor | Basic (Code-Heavy) | Medium (Metadata) | Complex (Minimal) |
+|--------|-------------------|-------------------|-------------------|
+| **Task Nature** | Straightforward, well-defined | Multi-step, structured | Open-ended, strategic |
+| **Ambiguity** | Low (clear inputs/outputs) | Medium (some interpretation) | High (requires reasoning) |
+| **Creativity Required** | Low (follow patterns) | Medium (adapt patterns) | High (novel solutions) |
+| **Domain Expertise** | Low-Medium | Medium | High |
+| **Iteration Tolerance** | Low (want first-time success) | Medium | High (expect refinement) |
+| **Example Benefit** | High (priming effect) | Medium (reference) | Low (constraining) |
+
+---
+
+## The Sparse Language Findings
+
+### Executive Summary from Benchmark Testing
+
+Our comprehensive benchmarking system tested three agent formats across 5 Rust complexity levels (basic to master) and 10 JavaScript scenarios.
+
+#### Key Discoveries
+
+**1. The Complexity-Verbosity Inverse Law**
+
+```
+Task Complexity ↑ → Prompt Verbosity ↓
+
+Basic Tasks (parsing, CRUD):
+  - Code-Heavy: 85.3% quality (+43% vs Minimal)
+  - Metadata: 78.9% quality
+  - Minimal: 59.6% quality
+
+Complex Tasks (architecture, lock-free algorithms):
+  - Minimal: 87.2% quality (+31% vs Code-Heavy)
+  - Metadata: 74.5% quality
+  - Code-Heavy: 66.4% quality (over-constrained)
+```
+
+**Why This Happens:**
+- **Basic tasks**: Benefit from concrete examples and patterns (priming effect)
+- **Complex tasks**: Need reasoning freedom; verbose prompts create tunnel vision
+- **Medium tasks**: Structured metadata provides scaffolding without over-constraining
+
+**2. The Priming Paradox**
+
+```yaml
+Priming Effect:
+  Definition: "Providing examples/patterns guides behavior"
+
+  Positive Priming (Basic Tasks):
+    - Code examples → faster convergence
+    - Pattern demonstrations → correct idioms
+    - Concrete syntax → fewer compile errors
+
+  Negative Priming (Complex Tasks):
+    - Excessive examples → tunnel vision
+    - Over-specification → missed creative solutions
+    - Pattern fixation → suboptimal architectures
+```
+
+**3. Language-Specific Validation Status**
+
+| Language | Validation Status | Evidence | Confidence |
+|----------|------------------|----------|------------|
+| **Rust** | ✅ **VALIDATED** | 60 benchmark runs, statistical significance | **HIGH** |
+| JavaScript | 🟡 **HYPOTHESIS** | 60 benchmark runs, patterns observed | **MEDIUM** |
+| TypeScript | 🟡 **HYPOTHESIS** | Extrapolated from JS findings | **MEDIUM** |
+| Python | 🟡 **HYPOTHESIS** | Similar to JS patterns | **LOW-MEDIUM** |
+| Go | 🟡 **HYPOTHESIS** | Similar to Rust (system language) | **LOW** |
+
+**Recommendation:** Use Rust findings as the baseline; validate for your specific language context.
+
+---
+
+## Quick Start: Choose Your Format in 30 Seconds
+
+```yaml
+Is the task BASIC (parsing, simple logic, CRUD)?
+  → Use CODE-HEAVY format (+43% quality improvement)
+  → Example: tests/benchmarking-tests/test-agent-code-heavy.md
+
+Is the task COMPLEX with clear requirements (architecture, review)?
+  → Use MINIMAL format (avoid over-constraining)
+  → Example: architecture/system-architect.md
+
+Is the task MEDIUM complexity with structured steps?
+  → Use METADATA format (structured guidance)
+  → Example: development/backend/dev-backend-api.md
+```
+
+## The Three Golden Rules
+
+1. **Complexity-Verbosity Inverse Law**: As task complexity increases, prompt verbosity should DECREASE
+2. **Priming Paradox**: Verbose prompts excel at basic tasks, minimal prompts excel at complex reasoning
+3. **Rust Validation**: These findings are validated for Rust; hypotheses for other languages