# Claude Flow V3

> Multi-agent orchestration framework for agentic coding

## Project Overview

{{PROJECT_DESCRIPTION}}

**Tech Stack**: {{TECH_STACK}}
**Architecture**: Domain-Driven Design with bounded contexts

## Quick Start

### Installation
```bash
npm install

{{BUILD_COMMAND}}

{{TEST_COMMAND}}

{{DEV_COMMAND}}

<type>(<scope>): <description>

[optional body]

Co-Authored-By: claude-flow <[email protected]>

# Unit tests
npm test

# Integration tests
npm run test:integration

# Coverage
npm run test:coverage

npx claude-flow@v3alpha memory store \
  --key "pattern-name" \
  --value "pattern description" \
  --namespace patterns

npx claude-flow@v3alpha memory search \
  --query "search terms" \
  --namespace patterns

# Start MCP server
npx claude-flow@v3alpha mcp start

npx claude-flow@v3alpha hooks pre-task \
  --description "implementing authentication"

### Minimal Template

```markdown
# {{PROJECT_NAME}}

## Setup
```bash
npm install && npm run build

npm test

### AGENTS.override.md Template (Local Overrides)

```markdown
# Local Development Overrides

## Environment
- Development mode: full-auto
- Sandbox: workspace-write
- Web search: live

## Personal Preferences
[User can add their specific preferences here]

## Debug Settings
Enable verbose logging for development.

## Notes
This file is gitignored and contains local-only settings.

---
name: swarm-orchestration
description: >
  Multi-agent swarm coordination for complex tasks.
  Use when: 3+ files need changes, new features, refactoring.
  Skip when: single file edits, simple fixes, documentation.
---

# Swarm Orchestration Skill

## Purpose
Coordinate multiple specialized agents to work on complex tasks in parallel.

## When to Trigger
- Multi-file changes (3+ files)
- New feature implementation
- Cross-module refactoring
- Performance optimization
- Security audits

## Agent Routing

| Task Type | Agents |
|-----------|--------|
| Bug Fix | researcher, coder, tester |
| Feature | architect, coder, tester, reviewer |
| Refactor | architect, coder, reviewer |
| Performance | perf-engineer, coder |
| Security | security-architect, auditor |

## Execution Steps

### 1. Initialize Swarm
```bash
npx claude-flow@v3alpha swarm init \
  --topology hierarchical \
  --max-agents 8 \
  --strategy specialized

npx claude-flow@v3alpha hooks route --task "[task description]"

npx claude-flow@v3alpha swarm status

npx claude-flow@v3alpha memory search --query "[task keywords]"

npx claude-flow@v3alpha memory store \
  --key "[pattern-name]" \
  --value "[what worked]" \
  --namespace patterns

topology = "hierarchical"
max_agents = 8
strategy = "specialized"
consensus = "raft"

### memory-management/SKILL.md

```yaml
---
name: memory-management
description: >
  AgentDB memory system with HNSW vector search.
  Use when: need to store/retrieve patterns, search semantically.
  Skip when: no learning or pattern matching needed.
---

# Memory Management Skill

## Purpose
Interact with the AgentDB memory system for pattern storage, retrieval, and semantic search.

## Capabilities

| Operation | Performance |
|-----------|-------------|
| Store | ~1ms |
| Retrieve | ~0.5ms |
| Search (HNSW) | 150x-12,500x faster than brute force |

## Commands

### Store Data
```bash
npx claude-flow@v3alpha memory store \
  --key "unique-key" \
  --value "data to store" \
  --namespace patterns \
  --tags "tag1,tag2"

npx claude-flow@v3alpha memory search \
  --query "semantic search terms" \
  --namespace patterns \
  --limit 10

npx claude-flow@v3alpha memory retrieve \
  --key "unique-key" \
  --namespace patterns

npx claude-flow@v3alpha memory list \
  --namespace patterns \
  --limit 50

### sparc-methodology/SKILL.md

```yaml
---
name: sparc-methodology
description: >
  SPARC development workflow (Specification, Pseudocode, Architecture, Refinement, Completion).
  Use when: starting new features, complex implementations.
  Skip when: simple fixes, documentation.
---

# SPARC Methodology Skill

## Purpose
Structured development workflow ensuring thorough planning before implementation.

## Phases

### 1. Specification
Define requirements and acceptance criteria.

```bash
npx claude-flow@v3alpha hooks route --task "specification: [requirements]"

npx claude-flow@v3alpha hooks route --task "pseudocode: [algorithm design]"

npx claude-flow@v3alpha hooks route --task "architecture: [system design]"

npx claude-flow@v3alpha hooks route --task "refinement: [improvements]"

npx claude-flow@v3alpha hooks route --task "completion: [validation]"

1. SPECIFICATION
   └─ Define: "User authentication with JWT"
   └─ Criteria: Secure, Scalable, <100ms latency

2. PSEUDOCODE
   └─ Login flow algorithm
   └─ Token refresh mechanism
   └─ Session management

3. ARCHITECTURE
   └─ Component diagram
   └─ API contracts
   └─ Security boundaries

4. REFINEMENT
   └─ TDD implementation
   └─ Security hardening
   └─ Performance optimization

5. COMPLETION
   └─ Integration tests
   └─ Documentation
   └─ Deployment checklist

### security-audit/SKILL.md

```yaml
---
name: security-audit
description: >
  Security scanning and vulnerability detection.
  Use when: security review needed, handling sensitive data.
  Always trigger for: authentication, authorization, payment processing.
---

# Security Audit Skill

## Purpose
Comprehensive security analysis including vulnerability scanning, CVE detection, and code review.

## Automatic Triggers
Always invoke for:
- Authentication systems
- Authorization/permissions
- Payment processing
- User data handling
- External API integrations
- File uploads

## Security Checks

### 1. Input Validation
```bash
npx claude-flow@v3alpha security scan --check input-validation

npx claude-flow@v3alpha security scan --check path-traversal

npx claude-flow@v3alpha security scan --check command-injection

npx claude-flow@v3alpha security scan --depth full

const userSchema = z.object({
  email: z.string().email(),
  password: z.string().min(8),
});

const safePath = await validatePath(userInput);
if (!safePath.isValid) throw new PathTraversalError();

const safeExec = new SafeExecutor();
await safeExec.run(command, { sanitize: true });

## config.toml Templates

### Default Configuration

```toml
# Claude Flow V3 - Codex Configuration
# Generated by: claude-flow init --codex
# Documentation: https://github.com/ruvnet/claude-flow

# =============================================================================
# Core Settings
# =============================================================================

# Model selection
model = "gpt-5.3-codex"

# Approval policy: untrusted | on-failure | on-request | never
approval_policy = "on-request"

# Sandbox mode: read-only | workspace-write | danger-full-access
sandbox_mode = "workspace-write"

# Web search: disabled | cached | live
web_search = "cached"

# =============================================================================
# Project Documentation
# =============================================================================

# Maximum bytes to read from AGENTS.md files
project_doc_max_bytes = 65536

# Fallback filenames if AGENTS.md not found
project_doc_fallback_filenames = [
  "AGENTS.md",
  "TEAM_GUIDE.md",
  ".agents.md"
]

# =============================================================================
# Features
# =============================================================================

[features]
# Enable child AGENTS.md guidance
child_agents_md = true

# Cache shell environment for faster repeated commands
shell_snapshot = true

# Smart approvals based on request context
request_rule = true

# Enable remote compaction for large histories
remote_compaction = true

# =============================================================================
# MCP Servers
# =============================================================================

[mcp_servers.claude-flow]
command = "npx"
args = ["-y", "@claude-flow/cli@latest"]
enabled = true
tool_timeout_sec = 120

[mcp_servers.ruv-swarm]
command = "npx"
args = ["-y", "ruv-swarm", "mcp", "start"]
enabled = true
tool_timeout_sec = 120

# =============================================================================
# Skills Configuration
# =============================================================================

[[skills.config]]
path = ".agents/skills/swarm-orchestration"
enabled = true

[[skills.config]]
path = ".agents/skills/memory-management"
enabled = true

[[skills.config]]
path = ".agents/skills/sparc-methodology"
enabled = true

[[skills.config]]
path = ".agents/skills/security-audit"
enabled = true

[[skills.config]]
path = ".agents/skills/performance-analysis"
enabled = true

[[skills.config]]
path = ".agents/skills/github-automation"
enabled = true

# =============================================================================
# Profiles
# =============================================================================

# Development profile - more permissive for local work
[profiles.dev]
approval_policy = "never"
sandbox_mode = "danger-full-access"
web_search = "live"

# Safe profile - maximum restrictions
[profiles.safe]
approval_policy = "untrusted"
sandbox_mode = "read-only"
web_search = "disabled"

# CI profile - for automated pipelines
[profiles.ci]
approval_policy = "never"
sandbox_mode = "workspace-write"
web_search = "cached"

# =============================================================================
# History
# =============================================================================

[history]
# Save all session transcripts
persistence = "save-all"

# Maximum history file size (optional)
# max_bytes = 10485760

# =============================================================================
# Shell Environment
# =============================================================================

[shell_environment_policy]
# Inherit environment variables
inherit = "core"

# Exclude sensitive variables
exclude = ["*_KEY", "*_SECRET", "*_TOKEN", "*_PASSWORD"]

# =============================================================================
# Sandbox Workspace Write Settings
# =============================================================================

[sandbox_workspace_write]
# Additional writable paths beyond workspace
writable_roots = []

# Allow network access
network_access = true

# Exclude temp directories
exclude_slash_tmp = false

# Claude Flow V3 - Minimal Codex Configuration

model = "gpt-5.3-codex"
approval_policy = "on-request"
sandbox_mode = "workspace-write"

[mcp_servers.claude-flow]
command = "npx"
args = ["-y", "@claude-flow/cli@latest"]
enabled = true

# Claude Flow V3 - CI/CD Pipeline Configuration

model = "gpt-5.3-codex"
approval_policy = "never"
sandbox_mode = "workspace-write"
web_search = "disabled"

[features]
shell_snapshot = false
remote_compaction = false

[mcp_servers.claude-flow]
command = "npx"
args = ["-y", "@claude-flow/cli@latest"]
enabled = true

[history]
persistence = "none"

project/
├── AGENTS.md                          # Main project instructions
├── .agents/
│   ├── config.toml                    # Project-level Codex config
│   └── skills/
│       ├── swarm-orchestration/
│       │   ├── SKILL.md
│       │   ├── scripts/
│       │   │   └── init-swarm.sh
│       │   └── references/
│       │       └── topology-guide.md
│       ├── memory-management/
│       │   ├── SKILL.md
│       │   └── references/
│       │       └── hnsw-guide.md
│       ├── sparc-methodology/
│       │   ├── SKILL.md
│       │   └── references/
│       │       └── sparc-phases.md
│       ├── security-audit/
│       │   ├── SKILL.md
│       │   └── scripts/
│       │       └── security-scan.sh
│       ├── performance-analysis/
│       │   ├── SKILL.md
│       │   └── scripts/
│       │       └── benchmark.sh
│       └── github-automation/
│           ├── SKILL.md
│           └── scripts/
│               ├── create-pr.sh
│               └── run-ci.sh
├── .codex/                            # User-local overrides (gitignored)
│   ├── config.toml                    # Personal config overrides
│   └── AGENTS.override.md             # Local instruction overrides
└── .claude-flow/                      # Runtime data (shared)
    ├── config.yaml
    ├── data/
    └── logs/

# .agents/skills/swarm-orchestration/agents/openai.yaml

interface:
  display_name: "Swarm Orchestration"
  short_description: "Multi-agent task coordination"
  icon_small: "./assets/swarm-icon-sm.svg"
  icon_large: "./assets/swarm-icon-lg.png"
  brand_color: "#7C3AED"
  default_prompt: "Coordinate multiple agents to work on this task"

dependencies:
  tools:
    - type: "mcp"
      value: "claude-flow"
      description: "Claude Flow MCP server for swarm coordination"
      transport: "stdio"
      command: "npx"
      args: ["-y", "@claude-flow/cli@latest"]

// Usage in claude-flow CLI or standalone
// Package: @claude-flow/codex (first step toward coflow rebranding)

import {
  generateAgentsMd,
  generateSkillMd,
  generateConfigToml,
  CodexInitializer
} from '@claude-flow/codex';

// Or via the CLI
// npx @claude-flow/codex init
// npx @claude-flow/codex generate-skill --name my-skill

// Generate AGENTS.md
const agentsMd = await generateAgentsMd({
  projectName: 'my-project',
  description: 'Project description',
  buildCommand: 'npm run build',
  testCommand: 'npm test',
  template: 'default' // 'default' | 'minimal' | 'full'
});

// Generate a skill
const skill = await generateSkillMd({
  name: 'custom-skill',
  description: 'Custom skill description',
  triggers: ['when to use'],
  skipWhen: ['when to skip']
});

// Generate config.toml
const config = await generateConfigToml({
  model: 'gpt-5.3-codex',
  approvalPolicy: 'on-request',
  sandboxMode: 'workspace-write',
  mcpServers: [
    { name: 'claude-flow', command: 'npx', args: ['-y', '@claude-flow/cli@latest'] }
  ],
  skills: [
    { path: '.agents/skills/swarm-orchestration', enabled: true }
  ]
});

// Full initialization
const initializer = new CodexInitializer();
const result = await initializer.initialize({
  projectPath: '/path/to/project',
  template: 'default',
  skills: ['swarm', 'memory', 'sparc', 'security'],
  force: false
});

# Initialize a new Codex project
npx @claude-flow/codex init

# Initialize with specific template
npx @claude-flow/codex init --template minimal

# Generate a new skill
npx @claude-flow/codex generate-skill --name custom-skill

# Migrate from Claude Code to Codex
npx @claude-flow/codex migrate --from claude.md

# Validate AGENTS.md and skills
npx @claude-flow/codex validate

# Generate dual-platform setup (Claude Code + Codex)
npx @claude-flow/codex init --dual

# Initialize with Codex support
npx claude-flow@v3alpha init --codex

# Initialize with dual-platform support
npx claude-flow@v3alpha init --dual

# Future (after coflow rebrand)
npx coflow init --codex
npx coflow init --dual