Axon 2.0 Complete Guide

🧠 AI-Driven Development OS - From requirements to production-ready code.

Installation & Setup
Quick Start
Core Workflows
Requirement Analysis
PRD & Planning
Execution & Verification
Advanced Features
Best Practices
Troubleshooting

Installation & Setup

Prerequisites

Bun >= 1.1.0 (primary runtime)
Node.js >= 18 (fallback)
Git
OpenCode CLI: npm i -g opencode
ANTHROPIC_API_KEY: Required for AI capabilities

Install Axon

npm i -g @arrislink/axon

Verify Installation

ax doctor

Expected output:

🔍 Axon 2.0 环境诊断

  ✓ Runtime: Node v20.x.x, Bun 1.1.x
  ✓ Git: Installed
  ✓ OpenCode: Installed
  ✓ Repomix: Installed
  ✓ skills.sh: Installed
  ✓ ANTHROPIC_API_KEY: Configured
  ✓ API Connectivity: Reachable

Quick Start

1. Initialize a New Project

ax init my-project
cd my-project

This creates:

my-project/
├── .axon/              # Axon configuration
├── .openspec/          # Specification documents
├── .beads/             # Task execution graph
├── src/                # Source code
└── package.json

2. Execute Your First Task

Method 1: Direct Input (Quick & Simple)

ax drive "Implement a user login system with JWT authentication"

Method 2: From Requirement File (Recommended for complex features)

# Create a requirement document first
cat > requirements/auth.md << 'EOF'
# User Authentication System

## Requirements
- Email/password registration
- JWT-based login
- Password reset via email
- Token refresh mechanism

## Tech Stack
- Node.js + Express
- PostgreSQL
- JWT
- bcrypt
EOF

# Then execute with the requirement file
ax drive "Build authentication system" --req ./requirements/auth.md

Method 3: Analyze Only (Review PRD before execution)

ax drive "Build payment system" --req ./requirements/payment.md --analyze-only
# Review the generated PRD at .openspec/spec.enhanced.json
# Then execute normally
ax drive "Build payment system" --req ./requirements/payment.md

3. Monitor Progress

ax status

Core Workflows

Workflow 1: Rapid Prototyping

For quick experiments and MVPs:

ax drive "Create a REST API for a todo list with CRUD operations"

Axon will:

Analyze your request
Generate a PRD
Create implementation beads
Execute and verify

Workflow 2: Structured Development

For production features with clear requirements:

# Step 1: Write detailed requirements
cat > requirements/feature.md << 'EOF'
# Feature Specification

## User Stories
- As a user, I want to... so that...

## Acceptance Criteria
- [ ] Criterion 1
- [ ] Criterion 2

## Technical Requirements
- Database schema
- API endpoints
- Security considerations
EOF

# Step 2: Analyze and review
ax drive "Implement feature" --req ./requirements/feature.md --analyze-only

# Step 3: Review PRD at .openspec/spec.enhanced.json
# Step 4: Execute when ready
ax drive "Implement feature" --req ./requirements/feature.md

Workflow 3: Iterative Refinement

For evolving projects:

# First iteration
ax drive "Build basic user management" --analyze-only

# Review and refine requirements
vim requirements/feature.md

# Second iteration
ax drive "Build basic user management" --req ./requirements/feature.md --analyze-only

# Execute when satisfied
ax drive "Build basic user management" --req ./requirements/feature.md

Requirement Analysis

What Gets Analyzed

Axon's Unified Analyzer extracts:

Intent: Core goal of the request
Scope: What's in/out of scope
Entities: Domain models and data structures
Workflows: Business processes
Ambiguity Score: 0-100 (lower is better)
Clarification Questions: For vague requirements
Effort Estimation: hours/days/weeks/months

Example Analysis Output

📊 Analysis Results:
  Title: E-commerce Payment System
  Entities: 5 (Order, Payment, User, Product, Transaction)
  Stories: 8
  Workflows: 3 (checkout, refund, notification)
  Estimated Effort: weeks

⚠️  Clarification Recommended:
   ❓ Which payment providers should be supported? (Stripe, PayPal, etc.)
   ❓ Is PCI compliance required?
   ❓ What's the expected transaction volume?

✓ PRD saved to: .openspec/spec.enhanced.json

Requirement File Formats

Axon supports multiple formats:

Markdown (.md) - Recommended

# Feature Name

## Requirements
- [ ] Feature 1: Description
- [ ] Feature 2: Description

## Technical Stack
- Framework: Express.js
- Database: PostgreSQL

## Acceptance Criteria
- [ ] Criterion 1
- [ ] Criterion 2

JSON (.json)

{
  "title": "Feature Name",
  "requirements": ["req1", "req2"],
  "tech_stack": ["Express", "PostgreSQL"]
}

YAML (.yaml/.yml)

title: Feature Name
requirements:
  - req1
  - req2
tech_stack:
  - Express
  - PostgreSQL

PRD & Planning

Enhanced PRD Structure

The generated PRD (.openspec/spec.enhanced.json) includes:

{
  "metadata": {
    "title": "Project Name",
    "description": "...",
    "status": "draft"
  },
  "analysis": {
    "intent": "Core goal",
    "scope": { "in_scope": [], "out_of_scope": [] },
    "ambiguity_score": 25,
    "estimated_effort": "weeks"
  },
  "personas": [
    { "name": "User", "role": "...", "goals": [] }
  ],
  "stories": [
    { "id": "story_001", "action": "...", "acceptance_criteria": [] }
  ],
  "entities": [
    { "name": "User", "attributes": [] }
  ],
  "workflows": [
    { "name": "Login Flow", "steps": [] }
  ],
  "business_rules": [],
  "technical_constraints": [],
  "implementation": {
    "tech_stack": [],
    "architecture_decisions": []
  }
}

Bead Graph Generation

From the PRD, Axon generates an intelligent Bead Graph:

📈 Bead Graph Summary:
  Total Beads: 15
  Critical Path: 9 beads
  Parallel Groups: 4
  Risk Level: medium
  Estimated Hours: 120

Execution Plan:
  Phase 1: Setup & Foundation (sequential)
    - bead_001: Initialize project structure
    - bead_002: Setup database schema
  
  Phase 2: Parallel: Core API (parallel)
    - bead_003: Implement User model
    - bead_004: Implement Auth middleware
  
  Phase 3: Parallel: Features (parallel)
    - bead_005: Login endpoint
    - bead_006: Registration endpoint

Bead Properties

Each bead contains:

id: Unique identifier (bead_001)
title: Short, actionable title
description: What this bead accomplishes
instruction: Detailed implementation guidance
context: Related stories, entities, workflows
dependencies: Hard (blocking) and soft (preferred)
complexity: Story points, hours, risk factors
files_to_modify/create: Specific file paths
acceptance_criteria: Verifiable completion criteria
can_parallelize: Whether it can run in parallel

Execution & Verification

Execution Flow

Load Bead Graph: From .beads/graph.enhanced.json
Find Next Beads: Check dependencies, find executable
Build Context: Combine code context, skills, preferences
Execute via OMO: Spawn subprocess with context
Verify Results: Independent verification
Update Status: Mark complete/failed
Repeat: Until all beads complete

Verification Types

Axon performs "Trust but Verify":

Type Checking: bun run type-check
Linting: bun run lint
Testing: bun test
Acceptance Criteria: Custom verification per bead

Resume from Interruption

If the process is interrupted:

# Simply run ax drive again - it resumes automatically
ax drive "Continue implementation"

Axon will:

Detect interrupted beads (status: running)
Reset them to pending
Continue from where it left off

Advanced Features

Skills Management

Inject best practices into your project:

# Search for skills
ax skills find "JWT"
ax skills find "React"

# Install a skill
ax skills add vercel-labs/agent-skills

# List installed skills
ax skills list

Skills are automatically injected into:

PRD generation
Bead instructions
Code reviews

Custom Verification

Configure verification commands in .axon/verify.json:

{
  "testCommand": "bun test",
  "typeCheckCommand": "bun run type-check",
  "lintCommand": "bun run lint",
  "customChecks": [
    {
      "name": "Security Audit",
      "command": "npm audit"
    }
  ]
}

Environment Configuration

Create .env file:

# Required
ANTHROPIC_API_KEY=sk-ant-api03-...

# Optional
LLM_MODEL=claude-3-sonnet-20240229
LLM_MAX_TOKENS=4096

Or configure in ~/.omo/config.yaml:

api_key: sk-ant-api03-...
model: claude-3-sonnet-20240229
max_tokens: 4096
temperature: 0.2

Language Support

Axon auto-detects system language:

# English (default)
LANG=en_US.UTF-8 ax drive "..."

# Chinese
LANG=zh_CN.UTF-8 ax drive "..."

Best Practices

1. Start with Clear Requirements

❌ Vague:

ax drive "Build a website"

✅ Clear:

ax drive "Build a blog website with Next.js featuring: MDX support, dark mode, RSS feed, and SEO optimization"

2. Use Requirement Files for Complex Features

For features with multiple acceptance criteria:

# Create detailed requirements
cat > requirements/payment.md << 'EOF'
# Payment System

## User Stories
1. As a customer, I want to pay with credit card
2. As a customer, I want to receive email receipts

## Technical Requirements
- PCI DSS compliance
- Stripe integration
- Idempotency keys

## Acceptance Criteria
- [ ] Payment processed in < 3 seconds
- [ ] Idempotent requests handled correctly
- [ ] Webhooks processed reliably
EOF

# Execute
ax drive "Build payment system" --req ./requirements/payment.md

3. Review PRD Before Execution

# Generate PRD only
ax drive "Feature" --req ./req.md --analyze-only

# Review the generated PRD
vim .openspec/spec.enhanced.json

# Execute when ready
ax drive "Feature" --req ./req.md

4. Handle Clarification Questions

When Axon asks clarification questions:

⚠️  Clarification Recommended:
   ❓ Should we support OAuth providers (Google, GitHub)?
   ❓ What's the expected user load?

Options:

Answer inline: Update requirements file and re-run
Proceed anyway: Axon will make reasonable assumptions
Refine requirements: Make the requirements more specific

5. Use Skills for Domain Expertise

# Install relevant skills
ax skills add stripe-integration
ax skills add react-best-practices
ax skills add security-guidelines

6. Verify Regularly

Don't disable verification unless necessary:

# Good - verification enabled (default)
ax drive "Implement feature"

# Avoid - skipping verification
ax drive "Implement feature" --no-verify

Troubleshooting

Issue: "Analysis failed"

Cause: API key issue or malformed request

Solutions:

Check ANTHROPIC_API_KEY is set
Verify API key format: sk-ant-api03-...
Simplify your request
Check internet connectivity: ax doctor

Issue: "Requirement path not found"

Cause: File path is incorrect

Solutions:

Use relative path from project root: --req ./requirements/feature.md
Check file exists: ls requirements/
Use absolute path if needed

Issue: High ambiguity score

Cause: Request is too vague

Example:

⚠️  High ambiguity detected (85/100)

Solutions:

Answer clarification questions
Add more specific requirements
Define scope boundaries
Specify technical constraints

Issue: Verification keeps failing

Cause: Test/lint configuration issue

Solutions:

Check .axon/verify.json configuration
Run verification manually: bun test
Skip verification temporarily: --no-verify
Adjust verification commands

Issue: Process interrupted

Solution: Simply run ax drive again - it resumes automatically

Issue: "No executable beads found"

Cause: Dependencies not met or all beads completed

Solutions:

Check bead status: ax status
Review dependency graph: .beads/graph.enhanced.json
Check for failed beads blocking execution

Command Reference

ax init

ax init <project-name>    # Initialize new project

ax drive

ax drive "<instruction>"                    # Direct input
ax drive "<instruction>" --req <path>       # From requirement file/dir
ax drive "<instruction>" --analyze-only     # Generate PRD only
ax drive "<instruction>" --dry-run          # Preview without execution
ax drive "<instruction>" --no-verify        # Skip verification

ax status

ax status                   # Show project status

ax skills

ax skills find <query>      # Search for skills
ax skills add <package>     # Install a skill
ax skills list              # List installed skills

ax doctor

ax doctor                   # Check environment

File Structure Reference

my-project/
├── .axon/
│   ├── config.yaml         # Axon configuration
│   ├── verify.json         # Verification commands
│   └── prefs.md            # User preferences
├── .openspec/
│   ├── spec.md             # Legacy spec (if exists)
│   └── spec.enhanced.json  # Enhanced PRD
├── .beads/
│   ├── graph.json          # Legacy bead graph
│   └── graph.enhanced.json # Enhanced bead graph
├── .skills/                # Installed skills
├── requirements/           # Your requirement documents
├── src/                    # Source code
└── package.json

Next Steps

Axon 2.0 - From requirements to production-ready code.

FilesExpand file tree

GUIDE.md

Latest commit

History

GUIDE.md

File metadata and controls

Axon 2.0 Complete Guide

Table of Contents

Installation & Setup

Prerequisites

Install Axon

Verify Installation

Quick Start

1. Initialize a New Project

2. Execute Your First Task

3. Monitor Progress

Core Workflows

Workflow 1: Rapid Prototyping

Workflow 2: Structured Development

Workflow 3: Iterative Refinement

Requirement Analysis

What Gets Analyzed

Example Analysis Output

Requirement File Formats

PRD & Planning

Enhanced PRD Structure

Bead Graph Generation

Bead Properties

Execution & Verification

Execution Flow

Verification Types

Resume from Interruption

Advanced Features

Skills Management

Custom Verification

Environment Configuration

Language Support

Best Practices

1. Start with Clear Requirements

2. Use Requirement Files for Complex Features

3. Review PRD Before Execution

4. Handle Clarification Questions

5. Use Skills for Domain Expertise

6. Verify Regularly

Troubleshooting

Issue: "Analysis failed"

Issue: "Requirement path not found"

Issue: High ambiguity score

Issue: Verification keeps failing

Issue: Process interrupted

Issue: "No executable beads found"

Command Reference

ax init

ax drive

ax status

ax skills

ax doctor

File Structure Reference

Next Steps