claude-flow-novice 1.5.21 → 1.5.22

package/.claude/agents/CLAUDE.md

@@ -11,1550 +11,218 @@ This document is the single source of truth for creating, editing, and validatin
 ## Table of Contents
 
 1. [Quick Start](#quick-start)
-2. [The Sparse Language Findings](#the-sparse-language-findings)
+2. [Core Universal Principles](#core-universal-principles)
 3. [Agent Profile Structure](#agent-profile-structure)
-4. [The Three Agent Formats](#the-three-agent-formats)
-5. [Format Selection Decision Tree](#format-selection-decision-tree)
-6. [Agent Type Guidelines](#agent-type-guidelines)
-7. [Prompt Engineering Best Practices](#prompt-engineering-best-practices)
-8. [Quality Metrics & Validation](#quality-metrics--validation)
-9. [Integration with Claude Flow](#integration-with-claude-flow)
-10. [Examples & Templates](#examples--templates)
-11. [Validation Checklist](#validation-checklist)
+4. [Examples & Templates](#examples--templates)
+5. [Specialized Guidance](#specialized-guidance)
 
 ---
 
 ## 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
-
----
-
-## 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. Here are the empirical findings:
-
-#### 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.
-
----
-
-## Agent Profile Structure
-
-### Frontmatter (YAML)
-
-```yaml
----
-name: agent-name                    # REQUIRED: Lowercase with hyphens
-description: |                      # REQUIRED: Clear, keyword-rich description
-  MUST BE USED when [primary use case].
-  Use PROACTIVELY for [specific scenarios].
-  ALWAYS delegate when user asks [trigger phrases].
-  Keywords - [comma-separated keywords for search]
-tools:                              # REQUIRED: Array of tool names
-  - Read
-  - Write
-  - Edit
-  - Bash
-  - TodoWrite
-model: sonnet                       # REQUIRED: sonnet | opus | haiku
-color: seagreen                     # REQUIRED: Visual identifier
-type: specialist                    # OPTIONAL: specialist | coordinator | swarm
-capabilities:                       # OPTIONAL: Array of capability tags
-  - rust
-  - error-handling
-  - concurrent-programming
-lifecycle:                          # OPTIONAL: Hooks for agent lifecycle
-  pre_task: "npx claude-flow@alpha hooks pre-task"
-  post_task: "npx claude-flow@alpha hooks post-task"
-hooks:                             # OPTIONAL: Integration points
-  memory_key: "agent-name/context"
-  validation: "post-edit"
-triggers:                          # OPTIONAL: Automatic activation patterns
-  - "build rust"
-  - "implement concurrent"
-constraints:                       # OPTIONAL: Limitations and boundaries
-  - "Do not modify production database"
-  - "Require approval for breaking changes"
----
-```
-
-### Body Structure
-
-```markdown
-# Agent Name
-
-[Opening paragraph: WHO you are, WHAT you do]
-
-## 🚨 MANDATORY POST-EDIT VALIDATION
-
-**CRITICAL**: After **EVERY** file edit operation, you **MUST** run:
-
-```bash
-npx claude-flow@alpha hooks post-edit [FILE_PATH] --memory-key "agent/step" --structured
-```
-
-[Why this matters and what it provides]
-
-## Core Responsibilities
-
-[Primary duties in clear, actionable bullet points]
-
-## Approach & Methodology
-
-[HOW the agent accomplishes tasks - frameworks, patterns, decision-making]
-
-## Integration & Collaboration
-
-[How this agent works with other agents and the broader system]
-
-## Examples & Best Practices
-
-[Concrete examples showing the agent in action]
-
-## Success Metrics
-
-[How to measure agent effectiveness]
-```
-
----
-
-## 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
-
-**Template:**
-
-```markdown
----
-name: system-architect
-description: Expert in designing scalable systems
-tools: [Read, Write, Edit, Bash, TodoWrite]
-model: sonnet
-color: seagreen
----
-
-# System Architect Agent
-
-You are a senior system architect specializing in [domain]. You excel at [key strengths].
-
-## 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
-- Map stakeholder needs to technical solutions
-
-### Architecture Design
-- Apply appropriate patterns (microservices, event-driven, etc.)
-- Consider scalability, security, maintainability
-- Document decisions with Architecture Decision Records (ADRs)
-
-### Collaboration
-- Work with [other agents] to [integration points]
-- Share [outputs] for downstream consumption
-
-## Success Metrics
-
-- System meets quality attributes
-- Team can implement the architecture
-- Documentation is clear and comprehensive
-```
-
-**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
-
-**Example:** `architecture/system-architect.md`
-
----
-
-### 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
-
-**Template:**
-
-```markdown
----
-name: backend-api-dev
-description: Backend API development specialist
-tools: [Read, Write, Edit, Bash, Grep, Glob, TodoWrite]
-model: sonnet
-color: royalblue
----
-
-# Backend API Developer
-
-You specialize in building robust, scalable backend APIs.
-
-## API Development Framework
-
-### 1. Requirements Analysis
-
-```yaml
-API Specification:
-  endpoints:
-    - method: GET/POST/PUT/DELETE
-      path: /api/resource
-      authentication: required/optional
-      authorization: role-based
-
-  data_models:
-    - name: Resource
-      fields:
-        - name: id
-          type: UUID
-          required: true
-        - name: status
-          type: enum
-          values: [active, inactive]
-
-  quality_requirements:
-    - response_time_p95: 200ms
-    - throughput: 1000 req/s
-    - availability: 99.9%
-```
-
-### 2. Implementation Patterns
-
-```yaml
-Layered Architecture:
-  controller_layer:
-    responsibilities: [request validation, response formatting]
-    patterns: [DTO pattern, dependency injection]
-
-  service_layer:
-    responsibilities: [business logic, transaction management]
-    patterns: [service pattern, repository pattern]
-
-  data_layer:
-    responsibilities: [data persistence, query optimization]
-    patterns: [repository pattern, active record]
-```
-
-### 3. Error Handling Strategy
-
-```yaml
-Error Classification:
-  client_errors:
-    - 400: Bad Request (validation failures)
-    - 401: Unauthorized (missing/invalid auth)
-    - 403: Forbidden (insufficient permissions)
-    - 404: Not Found (resource doesn't exist)
-
-  server_errors:
-    - 500: Internal Server Error (unexpected failures)
-    - 503: Service Unavailable (dependency failures)
-
-Error Response Format:
-  structure:
-    - error: {code, message, details}
-    - request_id: for tracing
-    - timestamp: ISO 8601
-```
-
-### 4. Testing Strategy
-
-```yaml
-Test Pyramid:
-  unit_tests:
-    coverage_target: 85%
-    focus: [business logic, utility functions]
-
-  integration_tests:
-    coverage_target: 70%
-    focus: [API endpoints, database interactions]
-
-  e2e_tests:
-    coverage_target: 30%
-    focus: [critical user journeys]
-```
-
-## Implementation Approach
-
-1. **Define API Contract**: Create OpenAPI specification
-2. **Implement Data Models**: Define schemas and validation
-3. **Build Service Layer**: Implement business logic with tests
-4. **Create Controllers**: Wire up endpoints with middleware
-5. **Add Documentation**: Generate API docs and examples
-
-## Success Metrics
-
-- All endpoints documented in OpenAPI spec
-- Test coverage meets targets
-- Response times within SLA
-- Error handling is comprehensive
-```
-
-**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
-
-**Example:** `development/backend/dev-backend-api.md`
-
----
-
-### 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
-
-**Template:**
-
-```markdown
----
-name: rust-coder-basic
-description: Rust implementation specialist for basic tasks
-tools: [Read, Write, Edit, Bash, Grep, Glob, TodoWrite]
-model: sonnet
-color: mediumblue
----
-
-# Rust Coder - Basic Tasks
-
-You excel at implementing clean, idiomatic Rust code for common programming tasks.
-
-## Implementation Patterns
-
-### Error Handling with Result<T, E>
-
-**Pattern: Custom Error Types**
-
-```rust
-use thiserror::Error;
-
-#[derive(Error, Debug)]
-pub enum ConfigError {
-    #[error("Missing required field: {field}")]
-    MissingField { field: String },
-
-    #[error("Parse error in field {field}: {cause}")]
-    ParseError { field: String, cause: String },
-
-    #[error("IO error: {0}")]
-    IoError(#[from] std::io::Error),
-}
-
-// Usage example
-fn parse_config(path: &str) -> Result<Config, ConfigError> {
-    let content = std::fs::read_to_string(path)?;  // Auto-converts io::Error
-
-    let port = content
-        .lines()
-        .find(|line| line.starts_with("PORT="))
-        .ok_or_else(|| ConfigError::MissingField {
-            field: "PORT".to_string()
-        })?
-        .strip_prefix("PORT=")
-        .unwrap()
-        .parse::<u16>()
-        .map_err(|e| ConfigError::ParseError {
-            field: "PORT".to_string(),
-            cause: e.to_string(),
-        })?;
-
-    Ok(Config { port })
-}
-```
-
-**Key Patterns Demonstrated:**
-- Custom error enum with `thiserror` crate
-- `?` operator for error propagation
-- `.ok_or_else()` for Option to Result conversion
-- `.map_err()` for error transformation
-
-### String Processing with Iterators
-
-**Pattern: Word Reversal**
-
-```rust
-/// Reverses the order of words in a string
-///
-/// # Examples
-///
-/// ```
-/// let result = reverse_words("hello world");
-/// assert_eq!(result, Ok("world hello"));
-/// ```
-///
-/// # Errors
-///
-/// Returns `Err` if the input string is empty
-pub fn reverse_words(input: &str) -> Result<String, &'static str> {
-    if input.trim().is_empty() {
-        return Err("Input cannot be empty");
-    }
-
-    let reversed = input
-        .split_whitespace()           // Iterator over words
-        .rev()                         // Reverse the iterator
-        .collect::<Vec<_>>()          // Collect to vector
-        .join(" ");                    // Join with spaces
-
-    Ok(reversed)
-}
-
-#[cfg(test)]
-mod tests {
-    use super::*;
-
-    #[test]
-    fn test_basic_reversal() {
-        assert_eq!(reverse_words("hello world"), Ok("world hello".to_string()));
-    }
-
-    #[test]
-    fn test_single_word() {
-        assert_eq!(reverse_words("hello"), Ok("hello".to_string()));
-    }
-
-    #[test]
-    fn test_empty_string() {
-        assert!(reverse_words("").is_err());
-    }
-
-    #[test]
-    fn test_multiple_spaces() {
-        assert_eq!(reverse_words("hello   world"), Ok("world hello".to_string()));
-    }
-}
-```
-
-**Key Patterns Demonstrated:**
-- Rustdoc comments with examples
-- Iterator methods (split_whitespace, rev, collect)
-- Proper Result usage with meaningful error messages
-- Comprehensive test coverage with #[test] attributes
-
-### Type Conversions and Parsing
-
-**Pattern: Safe Parsing with TryFrom**
-
-```rust
-use std::convert::TryFrom;
-
-#[derive(Debug, Clone)]
-pub struct Port(u16);
-
-impl TryFrom<&str> for Port {
-    type Error = PortParseError;
-
-    fn try_from(value: &str) -> Result<Self, Self::Error> {
-        let port = value
-            .parse::<u16>()
-            .map_err(|_| PortParseError::InvalidNumber)?;
-
-        if port < 1024 {
-            return Err(PortParseError::Privileged);
-        }
-
-        Ok(Port(port))
-    }
-}
-
-#[derive(Debug)]
-pub enum PortParseError {
-    InvalidNumber,
-    Privileged,
-}
-
-// Usage
-let port = Port::try_from("8080")?;
-```
-
-### CRUD Operations Pattern
-
-**Pattern: Repository Pattern in Rust**
-
-```rust
-use std::collections::HashMap;
-use uuid::Uuid;
-
-pub trait Repository<T> {
-    fn create(&mut self, item: T) -> Result<Uuid, RepositoryError>;
-    fn read(&self, id: &Uuid) -> Result<&T, RepositoryError>;
-    fn update(&mut self, id: &Uuid, item: T) -> Result<(), RepositoryError>;
-    fn delete(&mut self, id: &Uuid) -> Result<T, RepositoryError>;
-    fn list(&self) -> Vec<&T>;
-}
-
-pub struct InMemoryRepository<T> {
-    store: HashMap<Uuid, T>,
-}
-
-impl<T> Repository<T> for InMemoryRepository<T> {
-    fn create(&mut self, item: T) -> Result<Uuid, RepositoryError> {
-        let id = Uuid::new_v4();
-        self.store.insert(id, item);
-        Ok(id)
-    }
-
-    fn read(&self, id: &Uuid) -> Result<&T, RepositoryError> {
-        self.store
-            .get(id)
-            .ok_or(RepositoryError::NotFound)
-    }
-
-    fn update(&mut self, id: &Uuid, item: T) -> Result<(), RepositoryError> {
-        if !self.store.contains_key(id) {
-            return Err(RepositoryError::NotFound);
-        }
-        self.store.insert(*id, item);
-        Ok(())
-    }
-
-    fn delete(&mut self, id: &Uuid) -> Result<T, RepositoryError> {
-        self.store
-            .remove(id)
-            .ok_or(RepositoryError::NotFound)
-    }
-
-    fn list(&self) -> Vec<&T> {
-        self.store.values().collect()
-    }
-}
-```
-
-## Implementation Workflow
-
-### Step 1: Understand Requirements
-```bash
-# Read specification
-# Identify input/output types
-# Note error conditions
-```
-
-### Step 2: Define Types and Errors
-```rust
-// Define domain types
-// Create error enums
-// Add type conversions
-```
-
-### Step 3: Implement Core Logic
-```rust
-// Write main function with proper signature
-// Use iterator methods where applicable
-// Add error handling with ?
-```
-
-### Step 4: Write Tests
-```rust
-#[cfg(test)]
-mod tests {
-    // Test happy path
-    // Test error conditions
-    // Test edge cases
-}
-```
-
-### Step 5: Add Documentation
-```rust
-/// Documentation with examples
-///
-/// # Examples
-/// # Errors
-/// # Panics (if any)
-```
-
-## Success Criteria
-
-- [ ] Code compiles without warnings
-- [ ] All functions have rustdoc comments
-- [ ] Error handling uses Result<T, E> (no .unwrap())
-- [ ] Tests cover >85% of code
-- [ ] Idiomatic iterator usage where appropriate
-- [ ] Proper borrowing (minimal clones)
-
-## Common Pitfalls to Avoid
-
-### ❌ DON'T: Use .unwrap() in production code
-```rust
-let value = some_option.unwrap();  // Panics on None
-```
-
-### ✅ DO: Handle errors explicitly
-```rust
-let value = some_option.ok_or(MyError::MissingValue)?;
-```
-
-### ❌ DON'T: Clone unnecessarily
-```rust
-fn process(data: Vec<String>) {  // Takes ownership
-    for item in data.clone() {   // Unnecessary clone
-        // ...
-    }
-}
-```
-
-### ✅ DO: Borrow when possible
-```rust
-fn process(data: &[String]) {    // Borrows instead
-    for item in data {           // No clone needed
-        // ...
-    }
-}
-```
-```
-
-**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
-
-**Example:** `benchmarking-tests/test-agent-code-heavy.md`
-
----
-
-## 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) |
-
----
-
-## Agent Type Guidelines
-
-### 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
-
-**Example Structure:**
-
-```markdown
----
-name: code-reviewer
-description: Expert code reviewer focusing on quality and maintainability
-tools: [Read, Grep, Bash]
-model: sonnet
-color: orange
----
-
-# Code Reviewer
-
-You are an experienced code reviewer who identifies issues and suggests improvements.
-
-## Core 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
-
-## Success Metrics
-
-- Issues identified before production
-- Suggestions are implemented
-- Team learns from feedback
-```
-
-**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
-
-**Example Structure:**
-
-```markdown
----
-name: system-architect
-description: Senior system architect for scalable software design
-tools: [Read, Write, Edit, Bash, TodoWrite]
-model: sonnet
-color: seagreen
----
-
-# System Architect
-
-You are a senior system architect specializing in [domain].
-
-## Core Responsibilities
-
-- Design system architectures from requirements
-- Make strategic technical decisions
-- Evaluate technology trade-offs
-- Create architectural documentation
-
-## Approach
-
-### Requirements Analysis
-[Minimal guidance on extracting requirements]
-
-### Architecture Design
-[High-level patterns and considerations]
-
-### Decision Making
-[Framework for evaluating options]
-
-## Collaboration
-[How to work with other agents]
-
-## Success Metrics
-[How to measure architectural success]
-```
-
-**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
-
-**Example Structure:**
-
-```markdown
----
-name: unit-tester
-description: Comprehensive unit test specialist
-tools: [Read, Write, Edit, Bash, Grep, TodoWrite]
-model: sonnet
-color: mediumvioletred
----
-
-# Unit Test Specialist
-
-## 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
-
-**Example Structure:**
-
-```markdown
----
-name: tech-researcher
-description: Technology research and analysis specialist
-tools: [Read, WebSearch, Bash, TodoWrite]
-model: sonnet
-color: steelblue
----
-
-# Technology Researcher
-
-You conduct thorough research to inform technical decisions.
-
-## 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
-
-**Example Structure:**
-
-```markdown
----
-name: cicd-engineer
-description: CI/CD pipeline specialist
-tools: [Read, Write, Edit, Bash, Grep, Glob, TodoWrite]
-model: sonnet
-color: darkkhaki
----
-
-# CI/CD Pipeline Engineer
-
-## 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`
-
----
-
-## Prompt Engineering Best Practices
-
-### 1. Clear Role Definition
-
-```yaml
-GOOD:
-  "You are a senior Rust developer specializing in concurrent programming"
-
-BAD:
-  "You write code"
-
-WHY:
-  - Clear expertise domain
-  - Sets expectations for quality
-  - Activates relevant knowledge
-```
-
-### 2. Specific Responsibilities
-
-```yaml
-GOOD:
-  - Implement lock-free data structures using atomics
-  - Ensure memory safety with proper synchronization
-  - Write linearizability tests using loom
-
-BAD:
-  - Write concurrent code
-  - Make it safe
-
-WHY:
-  - Concrete and actionable
-  - Measurable outcomes
-  - Clear scope
-```
+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
 
-### 3. Appropriate Tool Selection
+### Format Selection in 30 Seconds
 
 ```yaml
-Essential Tools:
-  - Read: Required for all agents (must read before editing)
-  - Write: For creating new files
-  - Edit: For modifying existing files
-  - Bash: For running commands
-  - Grep: For searching code
-  - Glob: For finding files
-  - TodoWrite: For task tracking
-
-Optional Tools:
-  - WebSearch: For research agents
-  - Task: For coordinator agents (spawning sub-agents)
-
-AVOID:
-  - Giving unnecessary tools
-  - Restricting essential tools
-```
+Is the task BASIC (parsing, simple logic, CRUD)?
+  → Use CODE-HEAVY format (+43% quality improvement)
 
-### 4. Integration Points
+Is the task COMPLEX with clear requirements (architecture, review)?
+  → Use MINIMAL format (avoid over-constraining)
 
-```yaml
-GOOD:
-  Collaboration:
-    - Architect: Provides design constraints
-    - Reviewer: Validates implementation
-    - Tester: Ensures correctness
-
-BAD:
-  "Works with other agents"
-
-WHY:
-  - Specific integration contracts
-  - Clear handoff points
-  - Defined outputs/inputs
+Is the task MEDIUM complexity with structured steps?
+  → Use METADATA format (structured guidance)
 ```
 
-### 5. Validation and Hooks
+**For detailed format guidance:** See [Format Selection Principles](./agent-principles/format-selection.md)
 
-```markdown
-## 🚨 MANDATORY POST-EDIT VALIDATION
+---
 
-**CRITICAL**: After **EVERY** file edit operation:
+## Core Universal Principles
 
-```bash
-npx claude-flow@alpha hooks post-edit [FILE_PATH] --memory-key "agent/step" --structured
-```
+### 1. Agent Profile Structure **REQUIRED FORMAT**
 
-**Benefits:**
-- TDD compliance checking
-- Security analysis (XSS, eval, credentials)
-- Formatting validation
-- Coverage analysis
-- Actionable recommendations
-```
+Every agent MUST include:
 
-**Rationale:**
-- Ensures quality gates
-- Provides immediate feedback
-- Coordinates with other agents via memory
-- Maintains system-wide standards
+#### Frontmatter (YAML)
 
+```yaml
 ---
+name: agent-name                    # REQUIRED: Lowercase with hyphens
+description: |                      # REQUIRED: Clear, keyword-rich description
+  MUST BE USED when [primary use case].
+  Use PROACTIVELY for [specific scenarios].
+  ALWAYS delegate when user asks [trigger phrases].
+  Keywords - [comma-separated keywords for search]
+tools: [Read, Write, Edit, Bash, TodoWrite, mcp__claude-flow__swarm_init, mcp__claude-flow__agent_spawn]  # REQUIRED: Comma-separated list, can include MCP commands
+model: sonnet                       # REQUIRED: sonnet | opus | haiku
+color: seagreen                     # REQUIRED: Visual identifier
+type: specialist                    # OPTIONAL: specialist | coordinator | swarm
+capabilities:                       # OPTIONAL: Array of capability tags
+  - rust
+  - error-handling
+lifecycle:                          # OPTIONAL: Hooks for agent lifecycle
+  pre_task: "npx claude-flow@alpha hooks pre-task"
+  post_task: "npx claude-flow@alpha hooks post-task"
+hooks:                             # OPTIONAL: Integration points
+  memory_key: "agent-name/context"
+  validation: "post-edit"
+triggers:                          # OPTIONAL: Automatic activation patterns
+  - "build rust"
+  - "implement concurrent"
+constraints:                       # OPTIONAL: Limitations and boundaries
+  - "Do not modify production database"
+---
+```
 
-### 6. Anti-Patterns to Avoid
-
-#### ❌ Over-Specification (Tunnel Vision)
+#### Body Structure
 
 ```markdown
-BAD (for complex tasks):
-
-## Strict Algorithm
+# Agent Name
 
-1. ALWAYS use bubble sort for sorting
-2. NEVER use built-in sort functions
-3. MUST iterate exactly 10 times
-4. Check each element precisely in this order: [detailed steps]
+[Opening paragraph: WHO you are, WHAT you do]
 
-WHY BAD:
-- Prevents optimal solutions
-- Ignores context-specific needs
-- Reduces AI reasoning ability
-- May enforce suboptimal patterns
-```
+## 🚨 MANDATORY POST-EDIT VALIDATION
 
-#### ❌ Under-Specification (Too Vague)
+**CRITICAL**: After **EVERY** file edit operation, you **MUST** run:
 
-```markdown
-BAD (for basic tasks):
+```bash
+npx claude-flow@alpha hooks post-edit [FILE_PATH] --memory-key "agent/step" --structured
+```
 
-## Implementation
+[Why this matters and what it provides]
 
-Write some code that works.
+## Core Responsibilities
 
-WHY BAD:
-- No guidance on patterns
-- Unclear success criteria
-- High iteration count
-- Inconsistent quality
-```
+[Primary duties in clear, actionable bullet points]
 
-#### ❌ Example Overload
+## Approach & Methodology
 
-```markdown
-BAD (for complex tasks):
+[HOW the agent accomplishes tasks - frameworks, patterns, decision-making]
 
-[50 code examples of every possible pattern]
+## Integration & Collaboration
 
-WHY BAD:
-- Cognitive overload
-- Priming bias
-- Reduces creative problem-solving
-- Makes prompt harder to maintain
-```
+[How this agent works with other agents and the broader system]
 
-#### ❌ Rigid Checklists
+## Success Metrics
 
-```markdown
-BAD (for architecture):
-
-You MUST:
-[ ] Use exactly these 5 patterns
-[ ] Never deviate from this structure
-[ ] Follow these steps in exact order
-[ ] Use only these technologies
-
-WHY BAD:
-- Context-insensitive
-- Prevents trade-off analysis
-- Enforces solutions before understanding problems
+[How to measure agent effectiveness]
 ```
 
 ---
 
-## Quality Metrics & Validation
-
-### Measuring Agent Effectiveness
+### 2. The Complexity-Verbosity Inverse Law
 
-#### 1. Quantitative Metrics
+**Empirical Finding:** Task complexity and prompt verbosity have an inverse relationship.
 
-```yaml
-Code Quality:
-  compilation_success_rate: "First-time compile success"
-  test_pass_rate: "Tests passing on first run"
-  coverage: "Code coverage percentage"
-  performance: "Execution time vs baseline"
-  idiomaticity_score: "Language-specific best practices"
-
-Process Metrics:
-  iteration_count: "Revisions needed to complete task"
-  time_to_completion: "Duration from start to finish"
-  error_rate: "Errors encountered during execution"
-
-Agent-Specific:
-  architect_score: "Design quality assessment"
-  reviewer_score: "Issues found / total issues"
-  tester_score: "Bug catch rate"
 ```
+Basic Tasks (parsing, CRUD):
+  - Code-Heavy: 85.3% quality (+43% vs Minimal)
+  - Best approach: Detailed examples with step-by-step guidance
 
-#### 2. Qualitative Metrics
-
-```yaml
-Code Review Criteria:
-  - Readability: Easy to understand
-  - Maintainability: Easy to modify
-  - Correctness: Works as intended
-  - Safety: No security vulnerabilities
-  - Performance: Meets efficiency requirements
-
-Architecture Criteria:
-  - Scalability: Can grow with demand
-  - Flexibility: Adapts to changing requirements
-  - Simplicity: No unnecessary complexity
-  - Documentation: Well-explained decisions
+Complex Tasks (architecture, lock-free algorithms):
+  - Minimal: 87.2% quality (+31% vs Code-Heavy)
+  - Best approach: High-level principles with reasoning freedom
 ```
 
-### Validation Checklist
-
-Use this checklist before deploying an agent:
+**Why This Matters:**
+- Basic tasks benefit from concrete patterns (priming effect)
+- Complex tasks need creative freedom (over-specification creates tunnel vision)
+- Medium tasks need structured scaffolding without over-constraining
 
-#### Pre-Deployment Validation
+**For detailed analysis:** See [Format Selection Principles](./agent-principles/format-selection.md)
 
-```markdown
-## Agent Profile Validation
+---
 
-### Structure ✓
-- [ ] Valid YAML frontmatter
-- [ ] All required fields present (name, description, tools, model, color)
-- [ ] Clear role definition in opening paragraph
-- [ ] Appropriate section structure
+### 3. Mandatory Post-Edit Validation
 
-### Format Selection ✓
-- [ ] Format matches task complexity (Basic→Code-Heavy, Medium→Metadata, Complex→Minimal)
-- [ ] Length appropriate (Minimal: 200-400, Metadata: 400-700, Code-Heavy: 700-1200)
-- [ ] Examples present and relevant (for Code-Heavy)
-- [ ] Structure/metadata present (for Metadata)
+**UNIVERSAL REQUIREMENT:** Every agent MUST run post-edit hooks after file modifications.
 
-### Content Quality ✓
-- [ ] Clear responsibilities defined
-- [ ] Approach/methodology explained
-- [ ] Integration points specified
-- [ ] Success metrics defined
-- [ ] Post-edit validation hook included
-
-### Language-Specific ✓
-- [ ] If Rust: Format validated against benchmark findings
-- [ ] If other language: Format choice documented as hypothesis
-- [ ] Language-specific patterns included (for Code-Heavy)
-- [ ] Idiomatic code examples (for Code-Heavy)
-
-### Testing ✓
-- [ ] Agent tested on representative tasks
-- [ ] Quality metrics meet targets
-- [ ] Integration with hooks verified
-- [ ] Collaboration with other agents confirmed
+```bash
+npx claude-flow@alpha hooks post-edit [FILE_PATH] \
+  --memory-key "agent-name/context" \
+  --structured
 ```
 
-#### Post-Deployment Monitoring
+**Benefits:**
+- TDD compliance verification
+- Security analysis (XSS, eval(), hardcoded credentials)
+- Formatting validation
+- Test coverage analysis
+- Cross-agent memory coordination
+- Actionable recommendations
 
-```markdown
-## Ongoing Validation
-
-### Performance Tracking
-- [ ] Monitor iteration counts
-- [ ] Track first-time success rate
-- [ ] Measure time to completion
-- [ ] Collect user feedback
-
-### Quality Assurance
-- [ ] Review output quality regularly
-- [ ] Check adherence to format guidelines
-- [ ] Validate tool usage patterns
-- [ ] Assess collaboration effectiveness
-
-### Continuous Improvement
-- [ ] Document failure modes
-- [ ] Refine based on metrics
-- [ ] Update with new patterns
-- [ ] Validate format choice periodically
-```
+**For integration details:** See [Prompt Engineering Best Practices](./agent-principles/prompt-engineering.md)
 
 ---
 
-## Integration with Claude Flow
-
-### Hook System Integration
-
-Every agent should integrate with the Claude Flow hook system for coordination:
+### 4. Integration with Claude Flow
 
-#### 1. Pre-Task Hook
+#### Hook System
 
-```bash
-npx claude-flow@alpha hooks pre-task --description "Implementing authentication system"
-```
+Every agent integrates with:
+- **Pre-task hooks**: Initialize context, set up memory namespace
+- **Post-edit hooks**: Validate quality, coordinate with other agents
+- **Post-task hooks**: Finalize task, export metrics
+- **Session management**: Persist state across sessions
 
-**Purpose:**
-- Initialize task context
-- Set up memory namespace
-- Log task start
-- Coordinate with other agents
+#### Memory Coordination
 
-#### 2. Post-Edit Hook (MANDATORY)
-
-```bash
-npx claude-flow@alpha hooks post-edit src/auth/login.rs \
-  --memory-key "coder/auth/login" \
-  --structured
+```javascript
+// Memory key pattern: {agent-type}/{domain}/{aspect}
+"architect/auth/design"
+"coder/auth/implementation"
+"reviewer/auth/feedback"
+"tester/auth/coverage"
 ```
 
-**Purpose:**
-- Validate TDD compliance
-- Run security analysis
-- Check code formatting
-- Analyze test coverage
-- Store results in shared memory
-- Provide actionable recommendations
-
-**Output Includes:**
-- ✅/❌ Compliance status
-- 🔒 Security findings
-- 🎨 Formatting issues
-- 📊 Coverage metrics
-- 🤖 Improvement suggestions
-
-#### 3. Post-Task Hook
+#### Swarm Coordination
 
-```bash
-npx claude-flow@alpha hooks post-task --task-id "auth-implementation"
-```
+When spawning multiple agents:
+1. Run pre-task hook
+2. Execute work
+3. Run post-edit hook for each file
+4. Store results in memory
+5. Run post-task hook
 
-**Purpose:**
-- Finalize task
-- Export metrics
-- Update coordination state
-- Trigger downstream agents
+**For detailed integration:** See [Prompt Engineering Best Practices](./agent-principles/prompt-engineering.md)
 
-#### 4. Session Management
+---
 
-```bash
-# Restore session context
-npx claude-flow@alpha hooks session-restore --session-id "swarm-auth-2025-09-30"
+## Agent Profile Structure
 
-# End session and export metrics
-npx claude-flow@alpha hooks session-end --export-metrics true
-```
+### The Three Formats
 
-### Memory Coordination
+1. **MINIMAL (200-400 lines)**: For complex, strategic tasks requiring reasoning freedom
+2. **METADATA (400-700 lines)**: For medium complexity with structured workflows
+3. **CODE-HEAVY (700-1200 lines)**: For basic tasks benefiting from concrete examples
 
-Agents share context through the memory system:
+**Detailed format specifications:** [Format Selection Principles](./agent-principles/format-selection.md)
 
-```javascript
-// Store context for other agents
-npx claude-flow@alpha memory store \
-  --key "architect/design/decision" \
-  --value '{"pattern": "microservices", "rationale": "..."}'
-
-// Retrieve context from other agents
-npx claude-flow@alpha memory retrieve \
-  --key "architect/design/decision"
-```
+### Format Selection Decision Tree
 
-**Memory Key Patterns:**
 ```
-{agent-type}/{domain}/{aspect}
-
-Examples:
-- architect/auth/design
-- coder/auth/implementation
-- reviewer/auth/feedback
-- tester/auth/coverage
+Task Complexity Assessment
+        │
+    ┌───┴────┐
+    │        │
+  BASIC   COMPLEX
+    │        │
+CODE-HEAVY MINIMAL
 ```
 
-### Swarm Coordination
-
-When spawning multiple agents concurrently:
-
-```javascript
-// Coordinator spawns specialist agents
-Task("Rust Coder", "Implement auth with proper error handling", "coder")
-Task("Unit Tester", "Write comprehensive tests for auth", "tester")
-Task("Code Reviewer", "Review auth implementation", "reviewer")
-
-// Each agent MUST:
-// 1. Run pre-task hook
-// 2. Execute work
-// 3. Run post-edit hook for each file
-// 4. Store results in memory
-// 5. Run post-task hook
-```
+**Full decision tree and factors:** [Format Selection Principles](./agent-principles/format-selection.md)
 
 ---
 
 ## Examples & Templates
 
-### Example 1: Minimal Format Agent (Complex Task)
+### Example 1: Minimal Format (Complex Tasks)
 
 **File:** `.claude/agents/architecture/system-architect.md`
 
@@ -1563,8 +231,7 @@ Task("Code Reviewer", "Review auth implementation", "reviewer")
 name: system-architect
 description: |
   MUST BE USED when designing enterprise-grade system architecture.
-  Use PROACTIVELY for distributed systems, event-driven architecture,
-  microservices decomposition, scalability planning.
+  Use PROACTIVELY for distributed systems, event-driven architecture.
   Keywords - architecture, system design, microservices, scalability
 tools: [Read, Write, Edit, Bash, Grep, Glob, TodoWrite]
 model: sonnet
@@ -1623,907 +290,81 @@ trade-offs, document decisions with ADRs.
 - Trade-offs are explicitly documented
 ```
 
----
-
-### Example 2: Metadata Format Agent (Medium Task)
-
-**File:** `.claude/agents/development/backend/api-developer.md`
-
-```markdown
----
-name: api-developer
-description: |
-  Backend API development specialist for RESTful and GraphQL APIs.
-  Use for endpoint implementation, data modeling, API documentation.
-  Keywords - API, REST, GraphQL, backend, endpoints
-tools: [Read, Write, Edit, Bash, Grep, Glob, TodoWrite]
-model: sonnet
-color: royalblue
----
-
-# Backend API Developer
-
-You specialize in building robust, scalable backend APIs.
-
-## 🚨 MANDATORY POST-EDIT VALIDATION
-
-After EVERY file edit:
-```bash
-npx claude-flow@alpha hooks post-edit [FILE] --memory-key "api-dev/step" --structured
-```
-
-## API Development Framework
-
-### 1. API Specification
-
-```yaml
-Endpoint Structure:
-  method: [GET, POST, PUT, DELETE, PATCH]
-  path: /api/v1/resource
-  authentication: jwt | oauth | api_key
-  rate_limiting: true
-
-Request Validation:
-  - Schema validation (JSON Schema)
-  - Type checking
-  - Range validation
-  - Business rule validation
-
-Response Format:
-  success:
-    status: 200-299
-    body: { data, metadata }
-  error:
-    status: 400-599
-    body: { error: {code, message, details}, request_id, timestamp }
-```
-
-### 2. Implementation Layers
-
-```yaml
-Controller Layer:
-  responsibilities:
-    - Request validation
-    - Response formatting
-    - Error handling
-    - HTTP status codes
-  patterns:
-    - DTO (Data Transfer Objects)
-    - Dependency injection
-
-Service Layer:
-  responsibilities:
-    - Business logic
-    - Transaction management
-    - External service coordination
-  patterns:
-    - Service pattern
-    - Use case pattern
-
-Data Layer:
-  responsibilities:
-    - Data persistence
-    - Query optimization
-    - Cache management
-  patterns:
-    - Repository pattern
-    - Unit of Work
-```
-
-### 3. Error Handling
-
-```yaml
-Error Classification:
-  validation_errors:
-    status: 400
-    action: Return detailed field errors
-
-  authentication_errors:
-    status: 401
-    action: Return authentication challenge
-
-  authorization_errors:
-    status: 403
-    action: Log attempt, return generic message
-
-  not_found_errors:
-    status: 404
-    action: Return resource not found
-
-  server_errors:
-    status: 500
-    action: Log full error, return generic message
-```
-
-### 4. Testing Strategy
-
-```yaml
-Test Pyramid:
-  unit_tests:
-    target_coverage: 85%
-    focus: [business logic, utility functions]
-    tools: [jest, mocha]
-
-  integration_tests:
-    target_coverage: 70%
-    focus: [API endpoints, database interactions]
-    tools: [supertest, testcontainers]
-
-  contract_tests:
-    target_coverage: 100% of APIs
-    focus: [API contracts, schema validation]
-    tools: [pact, openapi-validator]
-```
-
-## Implementation Workflow
-
-1. **Define API Contract**: Create OpenAPI/GraphQL schema
-2. **Implement Models**: Define data models with validation
-3. **Build Services**: Implement business logic with tests
-4. **Create Controllers**: Wire up endpoints with middleware
-5. **Add Documentation**: Generate API docs and examples
-6. **Deploy & Monitor**: Set up logging and metrics
-
-## Success Metrics
-
-- All endpoints documented in OpenAPI spec
-- Test coverage meets targets (85% unit, 70% integration)
-- Response times < 200ms (p95)
-- Error handling is comprehensive
-- API follows RESTful conventions
-```
-
----
-
-### Example 3: Code-Heavy Format Agent (Basic Task)
-
-**File:** `.claude/agents/benchmarking-tests/test-agent-code-heavy.md`
-
-```markdown
----
-name: rust-coder-basic
-description: |
-  Rust implementation specialist for basic string processing,
-  error handling, and CRUD operations.
-  Keywords - rust, basic tasks, string processing, error handling
-tools: [Read, Write, Edit, Bash, Grep, Glob, TodoWrite]
-model: sonnet
-color: mediumblue
----
-
-# Rust Coder - Basic Tasks Specialist
-
-You excel at writing clean, idiomatic Rust code for common programming tasks.
-
-## 🚨 MANDATORY POST-EDIT VALIDATION
-
-After EVERY file edit:
-```bash
-npx claude-flow@alpha hooks post-edit [FILE] --memory-key "rust-coder/step" --structured
-```
-
-## Core Patterns
-
-### Pattern 1: Error Handling with Result<T, E>
-
-#### Custom Error Types with thiserror
-
-```rust
-use thiserror::Error;
-
-#[derive(Error, Debug)]
-pub enum ConfigError {
-    #[error("Missing required field: {field}")]
-    MissingField { field: String },
-
-    #[error("Parse error in field {field}: {cause}")]
-    ParseError { field: String, cause: String },
-
-    #[error("IO error: {0}")]
-    IoError(#[from] std::io::Error),
-
-    #[error("Environment variable error: {0}")]
-    EnvError(#[from] std::env::VarError),
-}
-
-pub type Result<T> = std::result::Result<T, ConfigError>;
-```
-
-#### Error Propagation with ? Operator
-
-```rust
-pub fn load_config(path: &Path) -> Result<Config> {
-    // Read file - io::Error auto-converts to ConfigError
-    let content = std::fs::read_to_string(path)?;
-
-    // Parse port - convert parse error
-    let port = content
-        .lines()
-        .find(|line| line.starts_with("PORT="))
-        .ok_or_else(|| ConfigError::MissingField {
-            field: "PORT".to_string(),
-        })?
-        .strip_prefix("PORT=")
-        .unwrap()
-        .parse::<u16>()
-        .map_err(|e| ConfigError::ParseError {
-            field: "PORT".to_string(),
-            cause: e.to_string(),
-        })?;
-
-    // Parse host with environment fallback
-    let host = content
-        .lines()
-        .find(|line| line.starts_with("HOST="))
-        .and_then(|line| line.strip_prefix("HOST="))
-        .map(|s| s.to_string())
-        .or_else(|| std::env::var("HOST").ok())
-        .ok_or_else(|| ConfigError::MissingField {
-            field: "HOST".to_string(),
-        })?;
-
-    Ok(Config { port, host })
-}
-```
-
-**Key Patterns:**
-- ✅ Custom error enum with descriptive variants
-- ✅ `#[from]` attribute for automatic conversion
-- ✅ `?` operator for propagation
-- ✅ `.ok_or_else()` for Option→Result conversion
-- ✅ `.map_err()` for error transformation
-
-**Anti-Patterns:**
-- ❌ `.unwrap()` or `.expect()` (panics on error)
-- ❌ String-based errors (`Result<T, String>`)
-- ❌ Ignoring errors (`.unwrap_or_default()` without justification)
-
----
-
-### Pattern 2: String Processing with Iterators
-
-#### Word Reversal Function
-
-```rust
-/// Reverses the order of words in a string.
-///
-/// Words are defined by whitespace separation. Multiple consecutive
-/// whitespace characters are treated as a single separator.
-///
-/// # Examples
-///
-/// ```
-/// use mylib::reverse_words;
-///
-/// assert_eq!(reverse_words("hello world")?, "world hello");
-/// assert_eq!(reverse_words("one")?, "one");
-/// assert_eq!(reverse_words("a  b   c")?, "c b a");
-/// ```
-///
-/// # Errors
-///
-/// Returns `Err` if the input string is empty or contains only whitespace.
-///
-/// ```
-/// # use mylib::reverse_words;
-/// assert!(reverse_words("").is_err());
-/// assert!(reverse_words("   ").is_err());
-/// ```
-pub fn reverse_words(input: &str) -> Result<String, &'static str> {
-    let trimmed = input.trim();
-
-    if trimmed.is_empty() {
-        return Err("Input cannot be empty or whitespace-only");
-    }
-
-    let reversed = trimmed
-        .split_whitespace()        // Iterator over words
-        .rev()                      // Reverse the iterator
-        .collect::<Vec<_>>()       // Collect to Vec<&str>
-        .join(" ");                 // Join with single space
-
-    Ok(reversed)
-}
-
-#[cfg(test)]
-mod tests {
-    use super::*;
-
-    #[test]
-    fn test_basic_reversal() {
-        assert_eq!(
-            reverse_words("hello world").unwrap(),
-            "world hello"
-        );
-    }
-
-    #[test]
-    fn test_single_word() {
-        assert_eq!(
-            reverse_words("hello").unwrap(),
-            "hello"
-        );
-    }
-
-    #[test]
-    fn test_multiple_spaces() {
-        assert_eq!(
-            reverse_words("hello   world  rust").unwrap(),
-            "rust world hello"
-        );
-    }
-
-    #[test]
-    fn test_empty_string() {
-        assert!(reverse_words("").is_err());
-    }
-
-    #[test]
-    fn test_whitespace_only() {
-        assert!(reverse_words("   ").is_err());
-    }
-
-    #[test]
-    fn test_leading_trailing_whitespace() {
-        assert_eq!(
-            reverse_words("  hello world  ").unwrap(),
-            "world hello"
-        );
-    }
-}
-```
-
-**Key Patterns:**
-- ✅ Rustdoc comments with examples
-- ✅ `split_whitespace()` for proper word splitting
-- ✅ `.rev()` for efficient reversal
-- ✅ `.collect()` with type annotation
-- ✅ Comprehensive test coverage
-- ✅ Edge case handling (empty, whitespace, multiple spaces)
-
-**Anti-Patterns:**
-- ❌ Manual string splitting with `.split(' ')`
-- ❌ Using `String::new()` and loops instead of iterators
-- ❌ Not handling leading/trailing whitespace
-
----
-
-### Pattern 3: Type-Safe Parsing
-
-#### Safe Type Conversion with TryFrom
-
-```rust
-use std::convert::TryFrom;
-use std::net::IpAddr;
-use std::str::FromStr;
-
-/// A validated network port number (1024-65535).
-#[derive(Debug, Clone, Copy, PartialEq, Eq)]
-pub struct Port(u16);
-
-impl Port {
-    pub const MIN: u16 = 1024;
-    pub const MAX: u16 = 65535;
-
-    pub fn new(value: u16) -> Result<Self, PortError> {
-        if value < Self::MIN {
-            return Err(PortError::TooLow);
-        }
-        if value > Self::MAX {
-            return Err(PortError::TooHigh);
-        }
-        Ok(Port(value))
-    }
-
-    pub fn get(&self) -> u16 {
-        self.0
-    }
-}
-
-#[derive(Debug, Error)]
-pub enum PortError {
-    #[error("Port number too low (minimum is 1024)")]
-    TooLow,
-
-    #[error("Port number too high (maximum is 65535)")]
-    TooHigh,
-
-    #[error("Invalid port format: {0}")]
-    ParseError(String),
-}
-
-impl TryFrom<&str> for Port {
-    type Error = PortError;
-
-    fn try_from(value: &str) -> Result<Self, Self::Error> {
-        let port = value
-            .parse::<u16>()
-            .map_err(|e| PortError::ParseError(e.to_string()))?;
-
-        Port::new(port)
-    }
-}
-
-impl FromStr for Port {
-    type Err = PortError;
-
-    fn from_str(s: &str) -> Result<Self, Self::Err> {
-        Self::try_from(s)
-    }
-}
-
-// Usage examples
-#[cfg(test)]
-mod tests {
-    use super::*;
-
-    #[test]
-    fn test_valid_port() {
-        let port = Port::try_from("8080").unwrap();
-        assert_eq!(port.get(), 8080);
-    }
-
-    #[test]
-    fn test_privileged_port() {
-        assert!(matches!(
-            Port::try_from("80"),
-            Err(PortError::TooLow)
-        ));
-    }
-
-    #[test]
-    fn test_invalid_number() {
-        assert!(matches!(
-            Port::try_from("not_a_number"),
-            Err(PortError::ParseError(_))
-        ));
-    }
-
-    #[test]
-    fn test_from_str() {
-        let port: Port = "3000".parse().unwrap();
-        assert_eq!(port.get(), 3000);
-    }
-}
-```
-
-**Key Patterns:**
-- ✅ Newtype pattern for type safety (`Port(u16)`)
-- ✅ Validation in constructor
-- ✅ `TryFrom` for fallible conversions
-- ✅ `FromStr` for `.parse()` support
-- ✅ Descriptive error variants
-- ✅ Getter method for inner value
-
----
-
-### Pattern 4: CRUD Operations
-
-#### Repository Pattern with Generic Interface
-
-```rust
-use std::collections::HashMap;
-use uuid::Uuid;
-
-/// Generic CRUD operations for any data type.
-pub trait Repository<T> {
-    type Error;
-
-    fn create(&mut self, item: T) -> Result<Uuid, Self::Error>;
-    fn read(&self, id: &Uuid) -> Result<&T, Self::Error>;
-    fn update(&mut self, id: &Uuid, item: T) -> Result<(), Self::Error>;
-    fn delete(&mut self, id: &Uuid) -> Result<T, Self::Error>;
-    fn list(&self) -> Vec<&T>;
-}
-
-#[derive(Debug, Error)]
-pub enum RepositoryError {
-    #[error("Item not found with ID: {0}")]
-    NotFound(Uuid),
-
-    #[error("Item already exists with ID: {0}")]
-    AlreadyExists(Uuid),
-}
-
-/// In-memory implementation of Repository.
-pub struct InMemoryRepository<T> {
-    store: HashMap<Uuid, T>,
-}
-
-impl<T> InMemoryRepository<T> {
-    pub fn new() -> Self {
-        Self {
-            store: HashMap::new(),
-        }
-    }
-
-    pub fn with_capacity(capacity: usize) -> Self {
-        Self {
-            store: HashMap::with_capacity(capacity),
-        }
-    }
-}
-
-impl<T> Repository<T> for InMemoryRepository<T> {
-    type Error = RepositoryError;
-
-    fn create(&mut self, item: T) -> Result<Uuid, Self::Error> {
-        let id = Uuid::new_v4();
-        self.store.insert(id, item);
-        Ok(id)
-    }
-
-    fn read(&self, id: &Uuid) -> Result<&T, Self::Error> {
-        self.store
-            .get(id)
-            .ok_or(RepositoryError::NotFound(*id))
-    }
-
-    fn update(&mut self, id: &Uuid, item: T) -> Result<(), Self::Error> {
-        if !self.store.contains_key(id) {
-            return Err(RepositoryError::NotFound(*id));
-        }
-        self.store.insert(*id, item);
-        Ok(())
-    }
-
-    fn delete(&mut self, id: &Uuid) -> Result<T, Self::Error> {
-        self.store
-            .remove(id)
-            .ok_or(RepositoryError::NotFound(*id))
-    }
-
-    fn list(&self) -> Vec<&T> {
-        self.store.values().collect()
-    }
-}
-
-// Example usage
-#[derive(Debug, Clone, PartialEq)]
-struct User {
-    name: String,
-    email: String,
-}
-
-#[cfg(test)]
-mod tests {
-    use super::*;
-
-    #[test]
-    fn test_create_and_read() {
-        let mut repo = InMemoryRepository::new();
-        let user = User {
-            name: "Alice".to_string(),
-            email: "alice@example.com".to_string(),
-        };
-
-        let id = repo.create(user.clone()).unwrap();
-        let retrieved = repo.read(&id).unwrap();
-
-        assert_eq!(retrieved, &user);
-    }
-
-    #[test]
-    fn test_update() {
-        let mut repo = InMemoryRepository::new();
-        let user = User {
-            name: "Bob".to_string(),
-            email: "bob@example.com".to_string(),
-        };
-
-        let id = repo.create(user).unwrap();
-
-        let updated_user = User {
-            name: "Robert".to_string(),
-            email: "robert@example.com".to_string(),
-        };
-
-        repo.update(&id, updated_user.clone()).unwrap();
-        let retrieved = repo.read(&id).unwrap();
-
-        assert_eq!(retrieved, &updated_user);
-    }
-
-    #[test]
-    fn test_delete() {
-        let mut repo = InMemoryRepository::new();
-        let user = User {
-            name: "Charlie".to_string(),
-            email: "charlie@example.com".to_string(),
-        };
-
-        let id = repo.create(user.clone()).unwrap();
-        let deleted = repo.delete(&id).unwrap();
-
-        assert_eq!(deleted, user);
-        assert!(matches!(
-            repo.read(&id),
-            Err(RepositoryError::NotFound(_))
-        ));
-    }
-
-    #[test]
-    fn test_list() {
-        let mut repo = InMemoryRepository::new();
-
-        repo.create(User {
-            name: "User1".to_string(),
-            email: "user1@example.com".to_string(),
-        }).unwrap();
-
-        repo.create(User {
-            name: "User2".to_string(),
-            email: "user2@example.com".to_string(),
-        }).unwrap();
-
-        let all_users = repo.list();
-        assert_eq!(all_users.len(), 2);
-    }
-}
-```
-
-**Key Patterns:**
-- ✅ Generic trait for reusability
-- ✅ Associated type for errors
-- ✅ UUID for unique identifiers
-- ✅ Proper error handling (not found, already exists)
-- ✅ Comprehensive CRUD operations
-- ✅ Test coverage for all operations
-
----
-
-## Implementation Workflow
-
-### Step-by-Step Process
-
-1. **Understand Requirements**
-   ```bash
-   # Read specification files
-   # Identify input/output types
-   # Note error conditions and edge cases
-   ```
-
-2. **Define Types and Errors**
-   ```rust
-   // Define domain types (structs, enums)
-   // Create error enum with thiserror
-   // Add type conversions (TryFrom, FromStr)
-   ```
-
-3. **Implement Core Logic**
-   ```rust
-   // Write main function with proper signature
-   // Use iterator methods where applicable
-   // Add error handling with ? operator
-   // Ensure proper borrowing (minimize clones)
-   ```
-
-4. **Write Tests**
-   ```rust
-   #[cfg(test)]
-   mod tests {
-       use super::*;
-
-       // Test happy path
-       // Test error conditions
-       // Test edge cases
-       // Test boundary conditions
-   }
-   ```
-
-5. **Add Documentation**
-   ```rust
-   /// Brief description
-   ///
-   /// Detailed explanation if needed
-   ///
-   /// # Examples
-   ///
-   /// ```
-   /// // Example usage
-   /// ```
-   ///
-   /// # Errors
-   ///
-   /// Returns `Err` if...
-   ///
-   /// # Panics
-   ///
-   /// Panics if... (if applicable)
-   ```
-
-6. **Run Validation Hook**
-   ```bash
-   npx claude-flow@alpha hooks post-edit src/module.rs \
-     --memory-key "rust-coder/module" \
-     --structured
-   ```
-
----
-
-## Success Criteria
-
-- [ ] Code compiles without warnings (`cargo build`)
-- [ ] All functions have rustdoc comments
-- [ ] Error handling uses `Result<T, E>` (no `.unwrap()` in production)
-- [ ] Tests cover >85% of code (`cargo tarpaulin`)
-- [ ] Idiomatic iterator usage where appropriate
-- [ ] Proper borrowing (minimal unnecessary clones)
-- [ ] Clippy has no warnings (`cargo clippy`)
-- [ ] Formatting is correct (`cargo fmt --check`)
+**For more examples:** [Format Selection Principles](./agent-principles/format-selection.md)
 
 ---
 
-## Common Pitfalls to Avoid
-
-### ❌ DON'T: Use .unwrap() in Production
-
-```rust
-// BAD - Panics on None
-let value = some_option.unwrap();
+### Example 2: Metadata Format (Medium Tasks)
 
-// BAD - Panics on Err
-let result = some_result.unwrap();
-```
-
-### ✅ DO: Handle Errors Explicitly
-
-```rust
-// GOOD - Propagates error
-let value = some_option.ok_or(MyError::MissingValue)?;
-
-// GOOD - Handles error
-let result = some_result.map_err(|e| MyError::from(e))?;
-```
+**For complete example:** See API Developer template in [Format Selection Principles](./agent-principles/format-selection.md)
 
 ---
 
-### ❌ DON'T: Clone Unnecessarily
-
-```rust
-// BAD - Takes ownership but clones
-fn process(data: Vec<String>) {
-    for item in data.clone() {  // Unnecessary allocation
-        println!("{}", item);
-    }
-}
-```
-
-### ✅ DO: Borrow When Possible
+### Example 3: Code-Heavy Format (Basic Tasks)
 
-```rust
-// GOOD - Borrows instead of owning
-fn process(data: &[String]) {
-    for item in data {  // No clone needed
-        println!("{}", item);
-    }
-}
-```
+**For complete example:** See Rust Coder template in [Format Selection Principles](./agent-principles/format-selection.md)
 
 ---
 
-### ❌ DON'T: Use Manual Loops for Iteration
+## Specialized Guidance
 
-```rust
-// BAD - Manual index loop
-for i in 0..vec.len() {
-    println!("{}", vec[i]);
-}
-```
+### By Agent Type
 
-### ✅ DO: Use Iterator Methods
+Different agent types have different format requirements:
 
-```rust
-// GOOD - Iterator-based
-vec.iter().for_each(|item| println!("{}", item));
+- **Coder Agents**: Code-Heavy for basic tasks, Minimal for complex algorithms
+- **Reviewer Agents**: Minimal format (requires contextual reasoning)
+- **Architect Agents**: Minimal format (strategic thinking)
+- **Tester Agents**: Code-Heavy for unit tests, Metadata for test strategy
+- **Researcher Agents**: Minimal format (open-ended exploration)
+- **DevOps Agents**: Metadata format (structured workflows)
 
-// Or even better
-for item in &vec {
-    println!("{}", item);
-}
-```
+**Full type-specific guidance:** [Agent Type Guidelines](./agent-principles/agent-type-guidelines.md)
 
 ---
 
-### ❌ DON'T: Use String-Based Errors
+### Prompt Engineering
 
-```rust
-// BAD - Not type-safe
-fn parse() -> Result<Value, String> {
-    Err("Parse error".to_string())
-}
-```
+Key principles for effective agent prompts:
 
-### ✅ DO: Use Custom Error Types
+1. **Clear Role Definition**: Establish expertise domain
+2. **Specific Responsibilities**: Concrete, actionable duties
+3. **Appropriate Tool Selection**: Only essential tools
+4. **Integration Points**: Explicit collaboration contracts
+5. **Validation Hooks**: Mandatory quality gates
 
-```rust
-// GOOD - Type-safe with details
-#[derive(Error, Debug)]
-enum ParseError {
-    #[error("Parse error: {0}")]
-    Format(String),
-}
+**Anti-patterns to avoid:**
+- Over-specification (tunnel vision)
+- Under-specification (too vague)
+- Example overload (cognitive burden)
+- Rigid checklists (context-insensitive)
 
-fn parse() -> Result<Value, ParseError> {
-    Err(ParseError::Format("Invalid format".to_string()))
-}
-```
-```
+**Detailed best practices:** [Prompt Engineering Best Practices](./agent-principles/prompt-engineering.md)
 
 ---
 
-## Validation Checklist
+### Quality Metrics & Validation
 
-Before considering an agent complete:
-
-### Structure ✓
+**Pre-Deployment Checklist:**
 - [ ] Valid YAML frontmatter
-- [ ] All required fields present
-- [ ] Clear role definition
-- [ ] Appropriate section organization
-
-### Format Selection ✓
 - [ ] Format matches task complexity
-- [ ] Length is appropriate
-- [ ] Examples/structure present as needed
-
-### Content Quality ✓
-- [ ] Clear responsibilities
-- [ ] Methodology explained
-- [ ] Integration points defined
-- [ ] Success metrics specified
+- [ ] Clear responsibilities defined
+- [ ] Integration points specified
 - [ ] Post-edit hook included
 
-### Language-Specific ✓
-- [ ] Format validated for language
-- [ ] Idiomatic patterns included
-- [ ] Common pitfalls addressed
-
-### Testing ✓
-- [ ] Tested on representative tasks
-- [ ] Metrics meet targets
-- [ ] Integration verified
-
----
-
-## Continuous Improvement
-
-### Metrics to Track
-
-```yaml
-Agent Performance Metrics:
-  first_time_success_rate:
-    target: ">80%"
-    measure: "Compiles/runs on first attempt"
-
-  iteration_count:
-    target: "<3"
-    measure: "Revisions needed to complete"
-
-  quality_score:
-    target: ">85%"
-    measure: "Benchmark quality assessment"
-
-  user_satisfaction:
-    target: ">4.5/5"
-    measure: "Feedback from users"
-```
+**Ongoing Monitoring:**
+- First-time success rate (>80%)
+- Iteration count (<3)
+- Quality score (>85%)
+- User satisfaction (>4.5/5)
 
-### Feedback Loop
-
-1. **Collect Data**: Track metrics for each agent usage
-2. **Analyze**: Identify patterns in failures or low quality
-3. **Hypothesize**: Determine likely causes
-4. **Experiment**: Adjust agent format or content
-5. **Validate**: Test changes with benchmark system
-6. **Deploy**: Update agent if improvements confirmed
-7. **Monitor**: Continue tracking metrics
+**Comprehensive validation guide:** [Quality Metrics & Validation](./agent-principles/quality-metrics.md)
 
 ---
 
-## Appendix: Benchmark System
+## Benchmark System
 
-### Running Agent Benchmarks
+### Running Benchmarks
 
 ```bash
 cd benchmark/agent-benchmarking
@@ -2534,75 +375,25 @@ node index.js run 5 --rust --verbose
 # Run JavaScript benchmarks (HYPOTHESIS)
 node index.js run 5 --verbose
 
-# Run specific scenario
-node index.js run 3 --rust --scenario=rust-01-basic
-
-# List available scenarios
-node index.js list --scenarios --rust
-
 # Analyze results
 node index.js analyze
 ```
 
-### Interpreting Results
-
-```yaml
-Quality Score Breakdown:
-  Correctness (30%):
-    - Basic functionality works
-    - Edge cases handled
-    - Error conditions managed
-
-  Idiomaticity (25%):
-    - Language best practices
-    - Proper pattern usage
-    - Efficient algorithms
-
-  Code Quality (20%):
-    - Readability
-    - Documentation
-    - Naming conventions
-
-  Testing (15%):
-    - Test coverage
-    - Assertion quality
-    - Edge case tests
-
-  Performance (10%):
-    - Execution efficiency
-    - Memory usage
-    - Optimization
-```
-
-### Statistical Significance
-
-```yaml
-ANOVA Analysis:
-  f_statistic: "Variance between groups"
-  p_value: "Probability results are random"
-  significant_if: "p < 0.05"
-
-Effect Size (Cohen's d):
-  negligible: "d < 0.2"
-  small: "0.2 ≤ d < 0.5"
-  medium: "0.5 ≤ d < 0.8"
-  large: "d ≥ 0.8"
-```
+**Detailed benchmarking guide:** [Quality Metrics & Validation](./agent-principles/quality-metrics.md)
 
 ---
 
 ## Conclusion
 
-This guide establishes evidence-based best practices for agent design in the Claude Flow ecosystem. The key insights:
+### Key Takeaways
 
 1. **Format matters**: Choose based on task complexity (inverse relationship)
-2. **Validation is critical**: Rust findings validated, others hypothetical
-3. **Integration is essential**: Hooks and memory coordinate agents
+2. **Validation is critical**: Hooks ensure quality and coordination
+3. **Integration is essential**: Memory and swarm systems enable collaboration
 4. **Continuous improvement**: Use metrics to refine agents
 
-By following these guidelines, you'll create agents that are effective, maintainable, and measurable.
+### Next Steps
 
-**Next Steps:**
 1. Choose appropriate format for your agent
 2. Use templates as starting points
 3. Test with benchmark system
@@ -2611,7 +402,16 @@ By following these guidelines, you'll create agents that are effective, maintain
 
 ---
 
+## Reference Documents
+
+- **[Format Selection Principles](./agent-principles/format-selection.md)**: Detailed format guidance, benchmarking findings, decision tree
+- **[Agent Type Guidelines](./agent-principles/agent-type-guidelines.md)**: Type-specific recommendations for coders, reviewers, architects, testers, researchers, DevOps
+- **[Prompt Engineering Best Practices](./agent-principles/prompt-engineering.md)**: Effective prompt patterns, anti-patterns, integration with Claude Flow
+- **[Quality Metrics & Validation](./agent-principles/quality-metrics.md)**: Validation checklists, benchmark system, continuous improvement
+
+---
+
 **Document Version:** 2.0.0
 **Last Updated:** 2025-09-30
 **Maintained By:** Claude Flow Core Team
-**Feedback:** Document improvements and findings for future versions
+**Feedback:** Document improvements and findings for future versions