Skip to content

CLAUDE.md

Latest commit

 

History

History
529 lines (409 loc) · 18.3 KB

CLAUDE.md

File metadata and controls

529 lines (409 loc) · 18.3 KB

AOF - Agentic Ops Framework

OpsFlow Ecosystem Context

AOF is an Apache 2.0 open source Rust framework for building agentic applications.

Repository: https://github.com/agenticdevops/aof License: Apache 2.0 Type: Pure Rust library crates + CLI (NO desktop/Tauri)

Ecosystem Structure

/Users/gshah/work/opsflow-sh/
├── aof/          # THIS REPO - Open source framework
├── kubepilot/    # Closed source K8s desktop (imports AOF crates)
└── opspilot/     # Closed source enterprise (imports AOF crates)

AOF Crates (Pure Rust - No Tauri)

  • aof-core - Core traits, types, interfaces
  • aof-llm - LLM provider abstraction
  • aof-mcp - MCP client
  • aof-runtime - Agent execution
  • aof-memory - State management
  • aof-triggers - Event triggers
  • aofctl - CLI binary

Cross-Repo Integration

KubePilot and OpsPilot import AOF crates:

aof-core = { path = "../../aof/aof/crates/aof-core" }
aof-llm = { path = "../../aof/aof/crates/aof-llm" }

Release Process

Documentation: https://docs.aof.sh Installation: curl -sSL https://docs.aof.sh/install.sh | bash

Creating a Release (Automated)

The release process is fully automated via GitHub Actions. DO NOT create releases manually.

# 1. Create and push a version tag (triggers automated build)
git tag -a v0.1.14 -m "Release v0.1.14: Brief description"
git push origin v0.1.14

# 2. Monitor: https://github.com/agenticdevops/aof/actions
# 3. Verify: https://github.com/agenticdevops/aof/releases

The workflow will automatically:

  • Build binaries for Linux, macOS (Intel & Apple Silicon), Windows
  • Calculate SHA256 checksums
  • Create GitHub Release with formatted release notes
  • Include installation instructions

Release Notes Format (Auto-generated)

The workflow creates consistent release notes with:

  • Installation instructions (curl | bash)
  • Manual download links
  • Checksum verification commands
  • Getting started guide

Version Numbering

Use semantic versioning: vMAJOR.MINOR.PATCH

  • MAJOR: Breaking changes
  • MINOR: New features (backward compatible)
  • PATCH: Bug fixes

Full details: See RELEASE_PROCESS.md

Claude Code Configuration - SPARC Development Environment

🚨 CRITICAL: CONCURRENT EXECUTION & FILE MANAGEMENT

ABSOLUTE RULES:

  1. ALL operations MUST be concurrent/parallel in a single message
  2. NEVER save working files, text/mds and tests to the root folder
  3. ALWAYS organize files in appropriate subdirectories
  4. USE CLAUDE CODE'S TASK TOOL for spawning agents concurrently, not just MCP

⚡ GOLDEN RULE: "1 MESSAGE = ALL RELATED OPERATIONS"

MANDATORY PATTERNS:

  • TodoWrite: ALWAYS batch ALL todos in ONE call (5-10+ todos minimum)
  • Task tool (Claude Code): ALWAYS spawn ALL agents in ONE message with full instructions
  • File operations: ALWAYS batch ALL reads/writes/edits in ONE message
  • Bash commands: ALWAYS batch ALL terminal operations in ONE message
  • Memory operations: ALWAYS batch ALL memory store/retrieve in ONE message

🎯 CRITICAL: Claude Code Task Tool for Agent Execution

Claude Code's Task tool is the PRIMARY way to spawn agents:

// ✅ CORRECT: Use Claude Code's Task tool for parallel agent execution
[Single Message]:
  Task("Research agent", "Analyze requirements and patterns...", "researcher")
  Task("Coder agent", "Implement core features...", "coder")
  Task("Tester agent", "Create comprehensive tests...", "tester")
  Task("Reviewer agent", "Review code quality...", "reviewer")
  Task("Architect agent", "Design system architecture...", "system-architect")

MCP tools are ONLY for coordination setup:

  • mcp__claude-flow__swarm_init - Initialize coordination topology
  • mcp__claude-flow__agent_spawn - Define agent types for coordination
  • mcp__claude-flow__task_orchestrate - Orchestrate high-level workflows

📁 File Organization Rules

NEVER save to root folder. Use these directories:

  • /src - Source code files
  • /tests - Test files
  • /docs - Documentation and markdown files
  • /config - Configuration files
  • /scripts - Utility scripts
  • /examples - Example code

Project Overview

This project uses SPARC (Specification, Pseudocode, Architecture, Refinement, Completion) methodology with Claude-Flow orchestration for systematic Test-Driven Development.

SPARC Commands

Core Commands

  • npx claude-flow sparc modes - List available modes
  • npx claude-flow sparc run <mode> "<task>" - Execute specific mode
  • npx claude-flow sparc tdd "<feature>" - Run complete TDD workflow
  • npx claude-flow sparc info <mode> - Get mode details

Batchtools Commands

  • npx claude-flow sparc batch <modes> "<task>" - Parallel execution
  • npx claude-flow sparc pipeline "<task>" - Full pipeline processing
  • npx claude-flow sparc concurrent <mode> "<tasks-file>" - Multi-task processing

Build Commands

Quick validation (as needed):

# 1. Optional: Fast pre-compile checks (5 seconds) - catches 80% of errors
./scripts/test-pre-compile.sh

# 2. Build:
cargo build --release

# 3. Optional: End-to-end validation:
./scripts/test-agent.sh

When to use pre-compile tests:

  • ✅ Before major changes
  • ✅ When debugging issues
  • ✅ When testing new features
  • ✅ 9x faster than full build (5s vs 45s)
  • ✅ Catches syntax, unit tests, patterns in one go

Complete Build Process:

  1. ./scripts/test-pre-compile.sh - Fast validation
  2. cargo check --all-features - Syntax validation
  3. cargo test --lib - Unit tests
  4. cargo build --release - Full release build
  5. ./scripts/test-agent.sh - End-to-end validation

Rust-Specific Commands:

  • cargo check - Quick syntax check (no build)
  • cargo test --lib - Unit tests only
  • cargo build --release - Optimized release build
  • cargo clippy --all-targets - Static analysis

SPARC Workflow Phases

  1. Specification - Requirements analysis (sparc run spec-pseudocode)
  2. Pseudocode - Algorithm design (sparc run spec-pseudocode)
  3. Architecture - System design (sparc run architect)
  4. Refinement - TDD implementation (sparc tdd)
  5. Completion - Integration (sparc run integration)

Code Style & Best Practices

  • Modular Design: Files under 500 lines
  • Environment Safety: Never hardcode secrets
  • Test-First: Write tests before implementation
  • Clean Architecture: Separate concerns
  • Documentation: Keep updated
  • Helpful Error Messages: Use serde_path_to_error for YAML/JSON parsing to show exact field paths on errors

YAML/JSON Parsing Best Practice

Always use serde_path_to_error when deserializing user-provided config files. This gives precise error locations instead of vague "didn't match" errors.

// Bad: Generic error messages
let config: Config = serde_yaml::from_str(&content)?;
// Error: "data did not match any variant of untagged enum"

// Good: Precise field path errors
let deserializer = serde_yaml::Deserializer::from_str(&content);
let config: Config = serde_path_to_error::deserialize(deserializer)
    .map_err(|e| anyhow!("Field: {}\nError: {}", e.path(), e.inner()))?;
// Error: "Field: spec.memory\nError: invalid type: map, expected string"

Add to Cargo.toml:

serde_path_to_error = "0.1"

🧪 Testing Options (Rust/Cargo Projects)

Available Test Tools

Optional pre-compile validation (5 seconds):

./scripts/test-pre-compile.sh

This validates:

  • ✅ Syntax errors
  • ✅ Unit tests
  • ✅ Clippy static analysis
  • ✅ MCP initialization patterns
  • ✅ Common error patterns
  • ✅ Configuration consistency

Test Options by Use Case

Scenario Command Time
Quick check before building ./scripts/test-pre-compile.sh 5s
Unit tests only cargo test --lib 10s
MCP initialization cargo test --lib mcp_initialization 5s
Tool executor cargo test --lib tool_executor 5s
Full release build cargo build --release 45s
Full validation ./scripts/test-agent.sh 10s
All tests cargo test --all 30s

Error Prevention System

The codebase includes an Error Knowledge Base (RAG) that:

  • Tracks recurring errors
  • Stores solutions for known problems
  • Helps agents learn from past mistakes
  • Prevents the same error from happening twice

Access it in code:

use aof_core::ErrorKnowledgeBase;

let kb = ErrorKnowledgeBase::new();
let similar_errors = kb.find_similar("MCP", &["initialize"]);
let stats = kb.stats();

🚀 Available Agents (54 Total)

Core Development

coder, reviewer, tester, planner, researcher

Swarm Coordination

hierarchical-coordinator, mesh-coordinator, adaptive-coordinator, collective-intelligence-coordinator, swarm-memory-manager

Consensus & Distributed

byzantine-coordinator, raft-manager, gossip-coordinator, consensus-builder, crdt-synchronizer, quorum-manager, security-manager

Performance & Optimization

perf-analyzer, performance-benchmarker, task-orchestrator, memory-coordinator, smart-agent

GitHub & Repository

github-modes, pr-manager, code-review-swarm, issue-tracker, release-manager, workflow-automation, project-board-sync, repo-architect, multi-repo-swarm

SPARC Methodology

sparc-coord, sparc-coder, specification, pseudocode, architecture, refinement

Specialized Development

backend-dev, mobile-dev, ml-developer, cicd-engineer, api-docs, system-architect, code-analyzer, base-template-generator

Testing & Validation

tdd-london-swarm, production-validator

Migration & Planning

migration-planner, swarm-init

🎯 Claude Code vs MCP Tools

Claude Code Handles ALL EXECUTION:

  • Task tool: Spawn and run agents concurrently for actual work
  • File operations (Read, Write, Edit, MultiEdit, Glob, Grep)
  • Code generation and programming
  • Bash commands and system operations
  • Implementation work
  • Project navigation and analysis
  • TodoWrite and task management
  • Git operations
  • Package management
  • Testing and debugging

MCP Tools ONLY COORDINATE:

  • Swarm initialization (topology setup)
  • Agent type definitions (coordination patterns)
  • Task orchestration (high-level planning)
  • Memory management
  • Neural features
  • Performance tracking
  • GitHub integration

KEY: MCP coordinates the strategy, Claude Code's Task tool executes with real agents.

🚀 Quick Setup

# Add MCP servers (Claude Flow required, others optional)
claude mcp add claude-flow npx claude-flow@alpha mcp start
claude mcp add ruv-swarm npx ruv-swarm mcp start  # Optional: Enhanced coordination
claude mcp add flow-nexus npx flow-nexus@latest mcp start  # Optional: Cloud features

MCP Tool Categories

Coordination

swarm_init, agent_spawn, task_orchestrate

Monitoring

swarm_status, agent_list, agent_metrics, task_status, task_results

Memory & Neural

memory_usage, neural_status, neural_train, neural_patterns

GitHub Integration

github_swarm, repo_analyze, pr_enhance, issue_triage, code_review

System

benchmark_run, features_detect, swarm_monitor

Flow-Nexus MCP Tools (Optional Advanced Features)

Flow-Nexus extends MCP capabilities with 70+ cloud-based orchestration tools:

Key MCP Tool Categories:

  • Swarm & Agents: swarm_init, swarm_scale, agent_spawn, task_orchestrate
  • Sandboxes: sandbox_create, sandbox_execute, sandbox_upload (cloud execution)
  • Templates: template_list, template_deploy (pre-built project templates)
  • Neural AI: neural_train, neural_patterns, seraphina_chat (AI assistant)
  • GitHub: github_repo_analyze, github_pr_manage (repository management)
  • Real-time: execution_stream_subscribe, realtime_subscribe (live monitoring)
  • Storage: storage_upload, storage_list (cloud file management)

Authentication Required:

  • Register: mcp__flow-nexus__user_register or npx flow-nexus@latest register
  • Login: mcp__flow-nexus__user_login or npx flow-nexus@latest login
  • Access 70+ specialized MCP tools for advanced orchestration

🚀 Agent Execution Flow with Claude Code

The Correct Pattern:

  1. Optional: Use MCP tools to set up coordination topology
  2. REQUIRED: Use Claude Code's Task tool to spawn agents that do actual work
  3. REQUIRED: Each agent runs hooks for coordination
  4. REQUIRED: Batch all operations in single messages

Example Full-Stack Development:

// Single message with all agent spawning via Claude Code's Task tool
[Parallel Agent Execution]:
  Task("Backend Developer", "Build REST API with Express. Use hooks for coordination.", "backend-dev")
  Task("Frontend Developer", "Create React UI. Coordinate with backend via memory.", "coder")
  Task("Database Architect", "Design PostgreSQL schema. Store schema in memory.", "code-analyzer")
  Task("Test Engineer", "Write Jest tests. Check memory for API contracts.", "tester")
  Task("DevOps Engineer", "Setup Docker and CI/CD. Document in memory.", "cicd-engineer")
  Task("Security Auditor", "Review authentication. Report findings via hooks.", "reviewer")
  
  // All todos batched together
  TodoWrite { todos: [...8-10 todos...] }
  
  // All file operations together
  Write "backend/server.js"
  Write "frontend/App.jsx"
  Write "database/schema.sql"

📋 Agent Coordination Protocol

Every Agent Spawned via Task Tool MUST:

1️⃣ BEFORE Work:

npx claude-flow@alpha hooks pre-task --description "[task]"
npx claude-flow@alpha hooks session-restore --session-id "swarm-[id]"

2️⃣ DURING Work:

npx claude-flow@alpha hooks post-edit --file "[file]" --memory-key "swarm/[agent]/[step]"
npx claude-flow@alpha hooks notify --message "[what was done]"

3️⃣ AFTER Work:

npx claude-flow@alpha hooks post-task --task-id "[task]"
npx claude-flow@alpha hooks session-end --export-metrics true

🎯 Concurrent Execution Examples

✅ CORRECT WORKFLOW: MCP Coordinates, Claude Code Executes

// Step 1: MCP tools set up coordination (optional, for complex tasks)
[Single Message - Coordination Setup]:
  mcp__claude-flow__swarm_init { topology: "mesh", maxAgents: 6 }
  mcp__claude-flow__agent_spawn { type: "researcher" }
  mcp__claude-flow__agent_spawn { type: "coder" }
  mcp__claude-flow__agent_spawn { type: "tester" }

// Step 2: Claude Code Task tool spawns ACTUAL agents that do the work
[Single Message - Parallel Agent Execution]:
  // Claude Code's Task tool spawns real agents concurrently
  Task("Research agent", "Analyze API requirements and best practices. Check memory for prior decisions.", "researcher")
  Task("Coder agent", "Implement REST endpoints with authentication. Coordinate via hooks.", "coder")
  Task("Database agent", "Design and implement database schema. Store decisions in memory.", "code-analyzer")
  Task("Tester agent", "Create comprehensive test suite with 90% coverage.", "tester")
  Task("Reviewer agent", "Review code quality and security. Document findings.", "reviewer")
  
  // Batch ALL todos in ONE call
  TodoWrite { todos: [
    {id: "1", content: "Research API patterns", status: "in_progress", priority: "high"},
    {id: "2", content: "Design database schema", status: "in_progress", priority: "high"},
    {id: "3", content: "Implement authentication", status: "pending", priority: "high"},
    {id: "4", content: "Build REST endpoints", status: "pending", priority: "high"},
    {id: "5", content: "Write unit tests", status: "pending", priority: "medium"},
    {id: "6", content: "Integration tests", status: "pending", priority: "medium"},
    {id: "7", content: "API documentation", status: "pending", priority: "low"},
    {id: "8", content: "Performance optimization", status: "pending", priority: "low"}
  ]}
  
  // Parallel file operations
  Bash "mkdir -p app/{src,tests,docs,config}"
  Write "app/package.json"
  Write "app/src/server.js"
  Write "app/tests/server.test.js"
  Write "app/docs/API.md"

❌ WRONG (Multiple Messages):

Message 1: mcp__claude-flow__swarm_init
Message 2: Task("agent 1")
Message 3: TodoWrite { todos: [single todo] }
Message 4: Write "file.js"
// This breaks parallel coordination!

Performance Benefits

  • 84.8% SWE-Bench solve rate
  • 32.3% token reduction
  • 2.8-4.4x speed improvement
  • 27+ neural models

Hooks Integration

Pre-Operation

  • Auto-assign agents by file type
  • Validate commands for safety
  • Prepare resources automatically
  • Optimize topology by complexity
  • Cache searches

Post-Operation

  • Auto-format code
  • Train neural patterns
  • Update memory
  • Analyze performance
  • Track token usage

Session Management

  • Generate summaries
  • Persist state
  • Track metrics
  • Restore context
  • Export workflows

Advanced Features (v2.0.0)

  • 🚀 Automatic Topology Selection
  • ⚡ Parallel Execution (2.8-4.4x speed)
  • 🧠 Neural Training
  • 📊 Bottleneck Analysis
  • 🤖 Smart Auto-Spawning
  • 🛡️ Self-Healing Workflows
  • 💾 Cross-Session Memory
  • 🔗 GitHub Integration

Integration Tips

  1. Start with basic swarm init
  2. Scale agents gradually
  3. Use memory for context
  4. Monitor progress regularly
  5. Train patterns from success
  6. Enable hooks automation
  7. Use GitHub tools first

Support

Remember: Claude Flow coordinates, Claude Code creates!

important-instruction-reminders

Do what has been asked; nothing more, nothing less. NEVER create files unless they're absolutely necessary for achieving your goal. ALWAYS prefer editing an existing file to creating a new one. NEVER proactively create documentation files (*.md) or README files. Only create documentation files if explicitly requested by the User. Never save working files, text/mds and tests to the root folder.

  • Strictly follow kubectl style implementation for aofctl. For example use "aofctl run agent" instead of "aofctl agent run". If you find anything non compliant, correct it.
  • for every feature added, add/update docs/ so that we are keeping track of every single feautre the product has and how it works.
  • When you make changes, first update the internal docs, then implement, verify the impleemntation matches the docs, rhen also update the user docs with concepts, examples, resource spec, tutorials etc.