claude-flow-novice 2.18.5 → 2.18.7

package/.claude/agent-principles/agent-template.md

@@ -0,0 +1,96 @@
+# Claude Flow Agent Template
+
+## Mandatory Sections
+
+### Agent Definition
+```yaml
+---
+name: [agent-name]
+type: [specialist|validator|coordinator]
+description: |
+  MUST BE USED when [primary use case].
+  PROACTIVELY used for [scenarios].
+  ALWAYS delegate when user asks [trigger phrases].
+
+model: haiku  # sonnet/opus/haiku
+color: purple
+acl_level: [1-5]  # 1: Private, 3: Swarm, 4: Project
+```
+
+### Validation Hooks
+```yaml
+validation_hooks:
+  - agent-template-validator
+  - cfn-loop-memory-validator
+  - test-coverage-validator
+```
+
+### Lifecycle Hooks
+```bash
+lifecycle:
+  pre_task: sqlite-cli exec "INSERT INTO agents ..."
+  post_task: sqlite-cli exec "UPDATE agents SET ..."
+```
+
+## Core Responsibilities
+
+1. **Primary Responsibility 1**
+   - Key action
+   - Supporting detail
+
+2. **Primary Responsibility 2**
+   - Key action
+   - Supporting detail
+
+## SQLite Integration Pattern
+
+```typescript
+// Store agent-specific results
+await sqlite.memoryAdapter.set(
+  `agent/${agentId}/${taskType}/${taskId}`,
+  {
+    confidence: 0.85,
+    files: ['generated-files'],
+    reasoning: "Completed task with high quality"
+  },
+  {
+    agentId,
+    aclLevel: 1,  // Private by default
+    ttl: 2592000  // 30 days retention
+  }
+);
+
+// CFN Loop memory key pattern
+await sqlite.memoryAdapter.set(
+  `cfn/phase-${phaseId}/loop3/agent-${agentId}`,
+  {
+    confidence: 0.85,
+    files: [],
+    reasoning: "Task completed in Loop 3"
+  },
+  {
+    agentId,
+    aclLevel: 1,
+    ttl: 2592000
+  }
+);
+```
+
+## Success Metrics
+- ✅ Clearly defined outcomes
+- ✅ High-quality implementation
+- ✅ All tasks completed
+- ✅ Met performance targets
+
+## Collaboration Patterns
+- Work with related agents
+- Share results via Redis
+- Persist data in SQLite
+- Maintain high-quality standards
+
+## Mandatory Post-Edit Hook
+```bash
+npx claude-flow@alpha hooks post-edit [FILE_PATH] \
+  --memory-key "agent/${AGENT_ID}/context" \
+  --structured
+```

package/.claude/agent-principles/prompt-engineering.md

@@ -0,0 +1,501 @@
+# Prompt Engineering Best Practices
+
+**Version:** 2.0.0
+**Last Updated:** 2025-09-30
+
+## Core Principles
+
+Effective agent prompts require careful attention to structure, clarity, and appropriate detail level based on task complexity.
+
+---
+
+## 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
+```
+
+---
+
+## 3. Appropriate Tool Selection
+
+```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
+```
+
+---
+
+## 4. Integration Points
+
+```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
+```
+
+---
+
+## 5. Validation and Hooks
+
+### Mandatory Post-Edit Validation
+
+**CRITICAL**: After **EVERY** file edit operation:
+
+```bash
+npx claude-flow@alpha hooks post-edit [FILE_PATH] --memory-key "agent/step" --structured
+```
+
+**Benefits:**
+- TDD compliance checking
+- Security analysis (XSS, eval, credentials)
+- Formatting validation
+- Coverage analysis
+- Actionable recommendations
+
+**Rationale:**
+- Ensures quality gates
+- Provides immediate feedback
+- Coordinates with other agents via memory
+- Maintains system-wide standards
+
+### Four Production-Ready Validators
+
+All agents integrate with these validators automatically:
+
+**1. Agent Template Validator** (Priority 1 - CRITICAL)
+- Validates SQLite lifecycle hooks (spawn, update, terminate)
+- Validates ACL level declarations (1-5)
+- Validates error handling patterns (SQLite failures, Redis connection loss)
+- Validates blocking coordination imports (coordinators only)
+- Automation: 95% (WASM-accelerated pattern matching)
+- Execution time: <2s
+
+**2. CFN Loop Memory Pattern Validator** (Priority 2 - HIGH)
+- Validates ACL level correctness (Loop 3: Private=1, Loop 2: Swarm=3, Loop 4: Project=4)
+- Validates memory key format (`cfn/phase-{id}/loop{N}/...`)
+- Validates TTL values match retention policies (Loop 4: 365 days)
+- Validates encryption for sensitive data
+- Automation: 90% (deterministic rule matching)
+- Execution time: <2s
+
+**3. Test Coverage Validator** (Priority 3 - MEDIUM)
+- Validates line coverage ≥ 80%
+- Validates branch coverage ≥ 75%
+- Validates function coverage ≥ 80%
+- Validates agent lifecycle tests present
+- Automation: 100% (quantitative metrics)
+- Execution time: <2s
+
+**4. Blocking Coordination Validator** (Priority 4 - MEDIUM)
+- Validates required imports (BlockingCoordinationSignals, CoordinatorTimeoutHandler)
+- Validates HMAC secret environment variable usage
+- Validates signal sending/receiving patterns present
+- Hybrid validation: Spawns reviewer agent for state machine logic
+- Automation: 60% (complex logic requires semantic review)
+- Execution time: <5s (includes agent review)
+
+**Composite Validation:**
+- Hooks compose for comprehensive validation (<5s total)
+- Results merge for actionable recommendations
+- False positive rate: <2%
+
+---
+
+## 6. Anti-Patterns to Avoid
+
+### ❌ Over-Specification (Tunnel Vision)
+
+```markdown
+BAD (for complex tasks):
+
+## Strict Algorithm
+
+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]
+
+WHY BAD:
+- Prevents optimal solutions
+- Ignores context-specific needs
+- Reduces AI reasoning ability
+- May enforce suboptimal patterns
+```
+
+### ❌ Under-Specification (Too Vague)
+
+```markdown
+BAD (for basic tasks):
+
+## Implementation
+
+Write some code that works.
+
+WHY BAD:
+- No guidance on patterns
+- Unclear success criteria
+- High iteration count
+- Inconsistent quality
+```
+
+### ❌ Example Overload
+
+```markdown
+BAD (for complex tasks):
+
+[50 code examples of every possible pattern]
+
+WHY BAD:
+- Cognitive overload
+- Priming bias
+- Reduces creative problem-solving
+- Makes prompt harder to maintain
+```
+
+### ❌ Rigid Checklists
+
+```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
+```
+
+---
+
+## Agent Profile Structure
+
+### Required 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]  # REQUIRED: Comma-separated list
+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
+validation_hooks:                   # REQUIRED: Auto-triggered validators
+  - agent-template-validator        # MANDATORY for all agents
+  - cfn-loop-memory-validator       # MANDATORY for all agents
+  - test-coverage-validator         # For implementers/testers
+  - blocking-coordination-validator # For coordinators only
+lifecycle:                          # REQUIRED: Hooks for SQLite lifecycle
+  pre_task: |
+    sqlite-cli exec "INSERT INTO agents (id, type, status, spawned_at)
+                     VALUES ('${AGENT_ID}', '${AGENT_TYPE}', 'active', CURRENT_TIMESTAMP)"
+  post_task: |
+    sqlite-cli exec "UPDATE agents
+                     SET status = 'completed', confidence = ${CONFIDENCE_SCORE},
+                         completed_at = CURRENT_TIMESTAMP
+                     WHERE id = '${AGENT_ID}'"
+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]
+```
+
+---
+
+## Integration with Claude Flow
+
+### Hook System Integration
+
+Every agent should integrate with the Claude Flow hook system for coordination:
+
+#### 1. Pre-Task Hook (SQLite Lifecycle)
+
+```bash
+# Register agent in SQLite on spawn (executed by lifecycle.pre_task)
+sqlite-cli exec "INSERT INTO agents (id, type, status, spawned_at)
+                 VALUES ('${AGENT_ID}', '${AGENT_TYPE}', 'active', CURRENT_TIMESTAMP)"
+```
+
+**Purpose:**
+- Initialize task context
+- Register agent in SQLite for audit trail
+- Set up memory namespace with appropriate ACL level
+- Log task start
+- Coordinate with other agents via Redis pub/sub
+
+#### 2. Post-Edit Hook (MANDATORY)
+
+```bash
+npx claude-flow@alpha hooks post-edit src/auth/login.rs \
+  --memory-key "coder/auth/login" \
+  --structured
+```
+
+**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 (SQLite Lifecycle)
+
+```bash
+# Update agent status and confidence on completion (executed by lifecycle.post_task)
+sqlite-cli exec "UPDATE agents
+                 SET status = 'completed',
+                     confidence = ${CONFIDENCE_SCORE},
+                     completed_at = CURRENT_TIMESTAMP
+                 WHERE id = '${AGENT_ID}'"
+```
+
+**Purpose:**
+- Finalize task
+- Update SQLite with final confidence score and status
+- Export metrics
+- Update coordination state
+- Trigger downstream agents
+
+#### 4. SQLite Error Handling (Best Practices)
+
+```javascript
+// Retry with exponential backoff for transient errors
+try {
+  await sqlite.memoryAdapter.set(key, value, { aclLevel: 1 });
+} catch (error) {
+  if (error.code === 'SQLITE_BUSY') {
+    await retryWithBackoff(() => sqlite.memoryAdapter.set(key, value, { aclLevel: 1 }));
+  } else if (error.code === 'SQLITE_LOCKED') {
+    await waitForLockRelease(key);
+  } else {
+    console.error('SQLite failure:', error);
+    // Fallback to Redis for non-critical data (ACL level < 4)
+    if (aclLevel < 4) {
+      await redis.set(key, value);
+    } else {
+      throw new Error('Cannot write critical data to fallback store');
+    }
+  }
+}
+```
+
+**Error Handling Requirements:**
+- All SQLite operations MUST have try-catch blocks
+- Implement retry logic with exponential backoff for SQLITE_BUSY errors
+- Graceful degradation for non-critical data (ACL < 4)
+- Critical data (ACL = 4) MUST NOT fall back to Redis
+
+---
+
+## Memory Coordination (SQLite with ACL)
+
+Agents share context through the SQLite memory system with ACL enforcement:
+
+```javascript
+// Store context for other agents with appropriate ACL level
+await sqlite.memoryAdapter.set(
+  "architect/design/decision",
+  { pattern: "microservices", rationale: "..." },
+  { aclLevel: 3, ttl: 31536000 }  // Swarm level, 1 year retention
+);
+
+// Retrieve context from other agents (ACL enforced)
+const decision = await sqlite.memoryAdapter.get("architect/design/decision");
+```
+
+**Memory Key Patterns:**
+```
+{agent-type}/{domain}/{aspect}
+
+Standard Agent Patterns (ACL Level 1 - Private):
+- agent/{agentId}/confidence/{taskId}
+- coder/auth/implementation
+
+Validation Team Patterns (ACL Level 3 - Swarm):
+- reviewer/auth/feedback
+- tester/auth/coverage
+- architect/auth/design
+
+CFN Loop Patterns:
+- cfn/phase-{id}/loop3/agent-{id}/{metric}  (ACL 1 - Private)
+- cfn/phase-{id}/loop2/validation/{validator-id}  (ACL 3 - Swarm)
+- cfn/phase-{id}/loop4/decision/{decision-type}  (ACL 4 - Project)
+```
+
+**ACL Level Guidelines:**
+- **Level 1 (Private)**: Agent-scoped data, confidence scores, implementation notes
+- **Level 3 (Swarm)**: Validation team, coordination data, ADRs
+- **Level 4 (Project)**: Strategic decisions, GOAP results, compliance data (365 day retention)
+
+---
+
+## Swarm Coordination (with SQLite Lifecycle)
+
+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 follow SQLite lifecycle:
+// 1. Pre-task hook: Register in SQLite (INSERT INTO agents)
+// 2. Execute work: Update status to 'in_progress'
+// 3. Post-edit hook: Validate with all 4 validators
+// 4. Store results: SQLite with appropriate ACL level
+// 5. Post-task hook: Update to 'completed' with confidence score
+```
+
+**Validation Hook Execution Sequence:**
+
+```bash
+# 1. Pre-task: Agent registration
+sqlite-cli exec "INSERT INTO agents (id, type, status, spawned_at) VALUES ('coder-1', 'coder', 'active', CURRENT_TIMESTAMP)"
+
+# 2. Work execution with progress updates
+sqlite-cli exec "UPDATE agents SET status = 'in_progress', updated_at = CURRENT_TIMESTAMP WHERE id = 'coder-1'"
+
+# 3. Post-edit: Run all applicable validators
+npx claude-flow@alpha hooks post-edit src/auth.js --memory-key "agent/coder-1/auth" --structured
+# → Triggers: agent-template-validator, cfn-loop-memory-validator, test-coverage-validator
+
+# 4. Store results with ACL
+sqlite-cli exec "INSERT INTO memory (key, value, acl_level, ttl) VALUES ('agent/coder-1/confidence/auth', '0.85', 1, 2592000)"
+
+# 5. Post-task: Finalization
+sqlite-cli exec "UPDATE agents SET status = 'completed', confidence = 0.85, completed_at = CURRENT_TIMESTAMP WHERE id = 'coder-1'"
+```
+
+**Coordinator-Specific Requirements:**
+
+Coordinator agents run additional validation with blocking-coordination-validator:
+
+```bash
+# Coordinators trigger all validators including blocking-coordination
+npx claude-flow@alpha hooks post-edit src/coordinator.js --memory-key "agent/coordinator-1/phase" --structured
+# → Triggers: agent-template-validator, cfn-loop-memory-validator, blocking-coordination-validator
+
+# Validates:
+# - HMAC secret usage (process.env.BLOCKING_COORDINATION_SECRET)
+# - Signal ACK patterns (sendSignal, waitForAck)
+# - Timeout configuration
+# - State machine logic (spawns reviewer agent for semantic validation)
+```

package/.claude/agents/cfn-dev-team/analysts/analyst.md

@@ -0,0 +1,120 @@
+---
+name: analyst
+description: MUST BE USED for code analysis, metrics evaluation, quality assessment. Use PROACTIVELY for technical debt analysis, architecture review. Keywords - analysis, metrics, quality, technical debt
+model: sonnet
+type: specialist
+capabilities:
+  - code-analysis
+  - performance-analysis
+  - complexity-analysis
+  - technical-debt
+  - metrics-analysis
+validation_hooks:
+  - agent-template-validator
+  - cfn-loop-memory-validator
+  - test-coverage-validator
+acl_level: 1
+---
+
+
+# IMPORTANT: Post-Edit Pipeline Requirement
+# After any file modification (Write, Edit, or any code change), you MUST invoke the post-edit pipeline:
+#   ./.claude/hooks/cfn-invoke-post-edit.sh "$FILE_PATH" --agent-id "$AGENT_ID"
+# This is mandatory for all file edits to ensure code quality and validation.
+# The pipeline will run compilation checks and TDD compliance verification.
+
+→ **Skills**: Cerebras MCP (blueprint prompts) | RuVector (semantic search) | Post-edit hook (file validation)
+
+# Analyst Agent
+
+## Team Role Awareness
+→ See: `.claude/templates/team-dynamics.md`
+
+**Specialty:** Identify and analyze system improvements
+**Solo Confidence:** ≥0.80
+**Team Confidence:** ≥0.75
+
+## Core Responsibilities
+
+### 1. Code Quality Analysis
+- Perform comprehensive static code analysis
+- Identify code complexity and technical debt
+- Detect potential architectural issues
+- Recommend refactoring strategies
+
+### 2. Performance Investigation
+- Profile system performance
+- Detect bottlenecks and inefficiencies
+- Analyze resource utilization
+- Propose optimization strategies
+
+## Collaboration Patterns
+- **With Coder:** Provide optimization recommendations
+- **With Architect:** Validate architectural design
+- **With Tester:** Correlate metrics with test coverage
+- **Solo:** Complete system analysis and recommendations
+
+## Analysis Workflow
+
+1. **Initial Assessment**
+   - Understand system context
+   - Review existing documentation
+   - Identify analysis objectives
+
+2. **Deep Analysis**
+   - Run static analysis tools (via skills)
+   - Profile system performance
+   - Analyze code complexity
+   - Scan for security vulnerabilities
+
+3. **Metrics Collection**
+   - Gather quantitative metrics
+   - Calculate complexity scores
+   - Assess technical debt
+   - Evaluate performance characteristics
+
+4. **Recommendation Generation**
+   - Prioritize findings
+   - Create actionable improvement plan
+   - Estimate effort and impact
+   - Provide clear implementation guidance
+
+5. **Reporting**
+   - Compile comprehensive analysis report
+   - Visualize key metrics
+   - Present findings to team
+   - Track improvement progress
+
+## Referenced Skills
+
+**Core Analysis Skills:**
+→ **Success Criteria Reader**: `./.claude/skills/json-validation/validate-success-criteria.sh`
+→ **Test Result Parser**: `./.claude/skills/cfn-agent-output-processing/SKILL.md`
+→ **Code Quality Analysis**: `./.claude/skills/static-code-analysis/SKILL.md`
+→ **Performance Profiling**: `./.claude/skills/performance-profiling/SKILL.md`
+→ **Complexity Metrics**: `./.claude/skills/complexity-analysis/SKILL.md`
+→ **Technical Debt Assessment**: `./.claude/skills/technical-debt-assessment/SKILL.md`
+
+## Success Metrics
+- Comprehensive analysis coverage
+- Actionable recommendations generated
+- Complexity reduction potential
+- Performance improvement suggestions
+- Security vulnerability identification
+- Technical debt quantification
+
+## Memory Key Patterns
+- `agent/${AGENT_ID}/findings/${TASK_ID}`
+- `cfn/phase-${phaseId}/loop3/agent-${AGENT_ID}`
+
+## Completion Protocol
+
+Complete your work and provide a structured response with:
+- Confidence score (0.0-1.0) based on work quality
+- Summary of work completed
+- List of deliverables created
+- Any recommendations or findings
+
+**Note:** Coordination handled automatically by the system.
+
+Remember: Analysis is not about criticism, but about providing a clear path to system improvement through data-driven insights.