claude-flow-novice 2.6.0 → 2.9.0

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

@@ -1,465 +0,0 @@
-# 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
-
-Validation Hooks:
-  - agent-template-validator (validates SQLite lifecycle, ACL declarations)
-  - cfn-loop-memory-validator (validates ACL levels for memory operations)
-  - test-coverage-validator (validates ≥80% line, ≥75% branch coverage)
-
-ACL Level: 1 (Private - agent-scoped data)
-SQLite: Persist confidence scores, implementation notes
-```
-
-**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
-
-Validation Hooks:
-  - agent-template-validator (validates SQLite lifecycle, ACL declarations)
-  - cfn-loop-memory-validator (validates ACL levels for memory operations)
-  - test-coverage-validator (validates ≥80% line, ≥75% branch coverage)
-
-ACL Level: 1 (Private - agent-scoped data)
-SQLite: Persist confidence scores, implementation notes
-```
-
-**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
-
-**Validation Hooks:**
-- `agent-template-validator` (validates SQLite lifecycle, ACL declarations)
-- `cfn-loop-memory-validator` (validates ACL levels for memory operations)
-
-**ACL Level:** 3 (Swarm - shared across validation team)
-
-**SQLite Requirements:**
-- Persist review feedback, validation consensus
-- Store findings with appropriate ACL for team access
-
-**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
-
-**Validation Hooks:**
-- `agent-template-validator` (validates SQLite lifecycle, ACL declarations)
-- `cfn-loop-memory-validator` (validates ACL levels for memory operations)
-
-**ACL Level:** 3 (Swarm - coordinate multiple agents)
-
-**SQLite Requirements:**
-- Persist ADRs (Architecture Decision Records) with 1 year retention
-- Store design decisions with appropriate ACL for team access
-- All architectural decisions MUST persist to SQLite for audit trail
-
-**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
-
-**Validation Hooks:**
-- `agent-template-validator` (validates SQLite lifecycle, ACL declarations)
-- `test-coverage-validator` (validates ≥80% line, ≥75% branch coverage)
-
-**ACL Level:** 3 (Swarm - shared across validation team)
-
-**SQLite Requirements:**
-- Persist test results, coverage metrics
-- Store test strategy with appropriate ACL for team access
-
-**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
-
-**Validation Hooks:**
-- `agent-template-validator` (validates SQLite lifecycle, ACL declarations)
-
-**ACL Level:** 1 (Private) or 3 (Swarm) depending on context
-
-**SQLite Requirements:**
-- Persist research findings, competitive analysis
-- Store with appropriate ACL based on sharing requirements
-
-**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
-
-**Validation Hooks:**
-- `agent-template-validator` (validates SQLite lifecycle, ACL declarations)
-- `cfn-loop-memory-validator` (validates ACL levels for memory operations)
-
-**ACL Level:** 3 (Swarm - coordinate with team)
-
-**SQLite Requirements:**
-- Persist deployment logs, infrastructure state
-- Store pipeline configurations with appropriate ACL
-
-**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`
-
----
-
-## 7. Coordinator Agents
-
-**Recommended Format:** METADATA
-
-**Rationale:**
-- Coordination involves structured workflows
-- Multi-agent orchestration requires clear patterns
-- Blocking coordination needs explicit signal handling
-- Balance structure with flexibility for agent management
-
-**Validation Hooks:**
-- `agent-template-validator` (validates SQLite lifecycle, ACL declarations)
-- `cfn-loop-memory-validator` (validates ACL levels for memory operations)
-- `blocking-coordination-validator` (validates HMAC secrets, signal ACK patterns, state machine logic)
-
-**ACL Level:** 3 (Swarm - coordinate multiple agents)
-
-**SQLite Requirements:**
-- Persist coordination signals, agent assignments
-- Store task delegation and progress tracking
-- All coordination state MUST persist for recovery
-
-**Blocking Coordination Requirements:**
-- Import `BlockingCoordinationSignals` and `CoordinatorTimeoutHandler`
-- Use HMAC secret from `process.env.BLOCKING_COORDINATION_SECRET`
-- Implement signal sending and ACK waiting patterns
-- Handle timeout scenarios with graceful degradation
-
-**Core Responsibilities:**
-- Orchestrate multi-agent workflows
-- Manage task delegation and dependencies
-- Handle blocking coordination with signal ACK protocol
-- Monitor agent progress and handle failures
-
-**Example:** Coordinator agents in CFN Loop phases
-
----
-
-## 8. Product Owner Agent (CFN Loop 4 Only)
-
-**Recommended Format:** MINIMAL
-
-**Rationale:**
-- Strategic GOAP decisions require high-level reasoning
-- Must evaluate complex trade-offs
-- Context-sensitive decision making
-- No over-specification to allow flexible analysis
-
-**Validation Hooks:**
-- `agent-template-validator` (validates SQLite lifecycle, ACL declarations)
-- `cfn-loop-memory-validator` (validates ACL levels for memory operations)
-
-**ACL Level:** 4 (Project - strategic decisions)
-
-**SQLite Requirements:**
-- Persist GOAP decisions (PROCEED/DEFER/ESCALATE) with 365 day retention for compliance
-- Store backlog items with appropriate ACL for project access
-- All strategic decisions MUST persist to SQLite for audit trail
-
-**Core Responsibilities:**
-- Make autonomous GOAP decisions after Loop 2 consensus validation
-- Evaluate PROCEED (relaunch Loop 3) vs DEFER (approve, backlog issues) vs ESCALATE (human review)
-- Manage backlog items and prioritization
-- Ensure compliance with retention policies
-
-**Example:** Product Owner agent in CFN Loop 4 decision gate
-
----
-
-## 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
-**Coordination**: coordinator (with blocking-coordination-validator)
-**Operations**: devops-engineer, cicd-engineer
-**Documentation**: api-docs, researcher
-**Strategic**: product-owner (CFN Loop 4 only)
-
-**Select agents based on actual task needs, not predefined patterns.**

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

@@ -1,224 +0,0 @@
-# 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
-
-**Validation Hooks Required:**
-- `agent-template-validator` (MANDATORY - validates SQLite lifecycle hooks)
-- `cfn-loop-memory-validator` (MANDATORY - validates ACL levels)
-
-**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
-
-**Validation Hooks Required:**
-- `agent-template-validator` (MANDATORY - validates SQLite lifecycle hooks)
-- `cfn-loop-memory-validator` (MANDATORY - validates ACL levels)
-- `test-coverage-validator` (MANDATORY - validates ≥80% line, ≥75% branch coverage)
-- `blocking-coordination-validator` (if coordinator - validates HMAC secrets, signal ACK patterns)
-
-**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
-
-**Validation Hooks Required:**
-- `agent-template-validator` (MANDATORY - validates SQLite lifecycle hooks)
-- `cfn-loop-memory-validator` (MANDATORY - validates ACL levels)
-- `test-coverage-validator` (MANDATORY - validates ≥80% line, ≥75% branch coverage)
-- `blocking-coordination-validator` (if coordinator - validates HMAC secrets, signal ACK patterns)
-
-**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
-  → Add to frontmatter: validation_hooks: [agent-template-validator, cfn-loop-memory-validator, test-coverage-validator]
-
-Is the task COMPLEX with clear requirements (architecture, review)?
-  → Use MINIMAL format (avoid over-constraining)
-  → Example: architecture/system-architect.md
-  → Add to frontmatter: validation_hooks: [agent-template-validator, cfn-loop-memory-validator]
-
-Is the task MEDIUM complexity with structured steps?
-  → Use METADATA format (structured guidance)
-  → Example: development/backend/dev-backend-api.md
-  → Add to frontmatter: validation_hooks: [agent-template-validator, cfn-loop-memory-validator, test-coverage-validator]
-  → If coordinator: Also add blocking-coordination-validator
-```
-
-## 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