APEX — Adaptive Product EXecution Framework

Spec-driven AI development for opencode, Claude Code, Gemini CLI, Cursor, Windsurf, and Antigravity.

APEX is a framework that takes any input — a vague product vision OR a specific feature request — and walks it through the complete software development lifecycle using structured AI personas and phase gates.

Install from npm (Online)

# Use directly without installing
npx apex-sdd-cli init my-project --ai opencode

# Install globally
npm install -g apex-sdd-cli
apex init my-project --ai opencode

# Add to your project
npm install --save-dev apex-sdd-cli
npx apex-sdd-cli init . --ai claude

Quick Start

1. Initialize APEX

npx apex-sdd-cli init my-app --ai opencode

2. Launch your AI agent

cd my-app
opencode

3. Start building

In your AI agent:

/apex:intake I want to build a task management app with Kanban boards

Installation Options

Option 1: NPX (No Installation)

Run directly without installing anything:

npx apex-sdd-cli init my-project --ai opencode
npx apex-sdd-cli init . --ai claude
npx apex-sdd-cli init --global --ai gemini

Option 2: Global Installation

Install once, use everywhere:

npm install -g apex-sdd-cli

# Then use directly
apex init my-project --ai opencode
apex init . --ai claude
apex init --global --ai gemini

Option 3: Project-Local

Add to your project as a dev dependency:

npm install --save-dev apex-sdd-cli

# Use via npx
npx apex-sdd-cli init . --ai claude

Installation Modes

Local (Per-Project)

Creates APEX files in your project directory:

# New project
npx apex-sdd-cli init my-project --ai opencode

# Existing project
cd my-existing-project
npx apex-sdd-cli init . --ai claude

# Force merge into non-empty directory
npx apex-sdd-cli init . --ai claude --force

What gets created:

your-project/
├── .apex/                    # Core framework files
│   ├── commands/             # Command definitions
│   ├── context/              # Session context bundles
│   └── constitution.md       # Hard gate rules
├── .opencode/commands/       # Agent-specific commands
├── AGENTS.md                 # AI agent instructions
├── specs/                    # Specifications
├── features/                 # Feature specs
└── design/                   # Prototypes

Global

Installs APEX commands globally for your AI agent (available in ANY project):

# Install globally for Claude Code
npx apex-sdd-cli init --global --ai claude

# Install globally for Gemini CLI
npx apex-sdd-cli init --global --ai gemini

# Install globally for Cursor
npx apex-sdd-cli init --global --ai cursor

# Install globally for Windsurf
npx apex-sdd-cli init --global --ai windsurf

# Install globally for Antigravity
npx apex-sdd-cli init --global --ai agy --ai-skills

Where commands are installed:

| Agent | Global Location | |-------|----------------| | Claude Code | ~/.claude/commands/ | | Gemini CLI | ~/.gemini/commands/ | | Cursor | ~/.cursor/commands/ | | Windsurf | ~/.windsurf/commands/ | | Antigravity (agy) | ~/.agy/commands/ and ~/.agy/skills/ |

Supported AI Agents

| Agent | Local Install | Global Install | Command Prefix | |-------|---------------|----------------|----------------| | opencode | ✅ | ❌ | /apex: | | Claude Code | ✅ | ✅ | /apex: | | Gemini CLI | ✅ | ✅ | /apex: | | Cursor | ✅ | ✅ | /apex: | | Windsurf | ✅ | ✅ | /apex: | | Antigravity (agy) | ✅ | ✅ | /apex: | | Antigravity | ✅ | ✅ | $apex- |

Agent-Specific Notes

• opencode: Local installation only (no global directory)
• Antigravity (agy): Use --ai-skills flag for skills mode
• Antigravity: Uses $apex- prefix instead of /apex:

CLI Reference

Commands

apex init [project-name]    Initialize a new APEX project
apex check                  Check for installed tools and dependencies
apex context7 <library>     Fetch documentation via Context7

apex init Options

| Option | Description | |--------|-------------| | --ai <agent> | AI assistant: opencode, claude, gemini, agy, antigravity, cursor, windsurf | | --global | Install APEX globally for the selected AI agent | | --here | Initialize in current directory (same as init .) | | --force | Force merge into non-empty directory | | --ai-skills | Install as agent skills (for Antigravity) | | --no-git | Skip git repository initialization | | --debug | Enable debug output for troubleshooting |

Examples

# LOCAL INSTALLATION EXAMPLES

# Create new project
npx apex-sdd-cli init my-app --ai opencode

# Initialize in current directory
npx apex-sdd-cli init . --ai claude

# Use shorthand for current directory
npx apex-sdd-cli init --here --ai gemini

# Force merge into existing project
npx apex-sdd-cli init . --ai cursor --force

# Skip git initialization
npx apex-sdd-cli init my-app --ai windsurf --no-git

# GLOBAL INSTALLATION EXAMPLES

# Install globally for Claude Code
npx apex-sdd-cli init --global --ai claude

# Install globally for Gemini CLI
npx apex-sdd-cli init --global --ai gemini

# Install globally for Cursor
npx apex-sdd-cli init --global --ai cursor

# Install globally for Windsurf
npx apex-sdd-cli init --global --ai windsurf

# Install globally for Antigravity with skills
npx apex-sdd-cli init --global --ai agy --ai-skills

Available Commands

After initializing APEX, your AI agent will have these slash commands:

Discovery

| Command | Description | |---------|-------------| | /apex:intake [description] | Classify scope, show recommended pipeline | | /apex:scan | Brownfield: reverse-engineer existing codebase | | /apex:constitution | Define hard gate rules for the project |

Planning

| Command | Description | |---------|-------------| | /apex:analyze | Requirements analysis (PM + QA personas) | | /apex:architect | System architecture + data model | | /apex:prd | Master PRD — all features trace here | | /apex:featuremap | Dependency graph + build order |

Feature Loop

| Command | Description | |---------|-------------| | /apex:spec [F-ID] | Feature spec + draft API contract | | /apex:wireframe [F-ID] | Screen flow diagram | | /apex:prototype [F-ID] | Clickable UI with mock API data | | /apex:review [F-ID] | Review prototype → freeze contract | | /apex:refactor [F-ID] | Optional rethink before backend | | /apex:implement [F-ID] | Backend implementation | | /apex:test [F-ID] | Full test suite |

Anytime

| Command | Description | |---------|-------------| | /apex:change [description] | Analyzed, approved, cascaded changes | | /apex:resume [F-ID] | Load context bundle for session | | /apex:status | Full project dashboard |

Project Structure

After running apex init, your project will have this structure:

your-project/
├── AGENTS.md                    # AI agent instructions
├── .apex/
│   ├── constitution.md          # Hard gate rules (optional)
│   ├── context/
│   │   ├── project-context.md   # Project-level context bundle
│   │   └── [F-ID]-context.md    # Per-feature context bundles
│   └── commands/                # Full command definitions
├── .opencode/commands/          # opencode slash commands
├── specs/
│   ├── 00-brief.md              # Greenfield project brief
│   ├── 00-existing-system.md    # Brownfield scan output
│   ├── 01-analysis.md           # Requirements analysis
│   ├── 02-architecture.md       # System architecture
│   ├── 03-prd.md                # MASTER PRD
│   ├── 04-feature-map.md        # Feature dependency graph
│   └── changes/
│       └── CHANGE-NNN.md        # Change records
├── features/
│   └── [F-ID]-[slug]/
│       ├── spec.md              # Feature specification
│       ├── api-contract.md      # API contract (DRAFT → FROZEN)
│       ├── tasks.md             # Implementation tasks
│       └── status.md            # Feature status
├── design/
│   └── prototypes/
│       └── [F-ID]-[slug]/
│           ├── mockApi.js       # Mock API mirroring contract
│           └── fixtures/        # Sample data
└── src/                     # Production code

How APEX Works

Expert Personas

APEX uses AI personas that change how the AI thinks:

| Persona | Mindset | Used In | |---------|---------|---------| | PM | User value, scope, priorities | intake, analyze, prd, review | | Architect | System design, scalability | architect, scan, featuremap | | UX Designer | User flows, usability | wireframe, review | | Developer | Code quality, contracts | prototype, implement | | QA Engineer | Edge cases, test coverage | test, analyze | | Tech Writer | Clarity, specificity | spec, constitution |

Phase Gates

APEX enforces hard stops that cannot be skipped:

| Gate | Requirement | |------|-------------| | GATE-1 | Analysis must exist before architecture | | GATE-2 | PRD must exist before feature specs | | GATE-3 | Feature spec must exist before wireframe | | GATE-4 | Wireframe must be approved before prototype | | GATE-5 | Contract must be frozen before implementation | | GATE-6 | Constitution rules must not be violated |

Development Workflow

1. /apex:intake "I want to build..."
   ↓
2. /apex:analyze
   ↓
3. /apex:architect
   ↓
4. /apex:prd
   ↓
5. /apex:featuremap
   ↓
6. For each feature:
   /apex:spec → /apex:wireframe → /apex:prototype → 
   /apex:review → /apex:implement → /apex:test

Requirements

• Node.js 18.0.0 or higher
• npm or npx
• Git (optional, for repository initialization)

Troubleshooting

"Cannot find module" Error

Make sure you're using Node.js 18+:

node --version

Directory Not Empty

Use --force to merge into existing directories:

npx apex-sdd-cli init . --ai claude --force

Global Commands Not Appearing

Check if commands were installed:

# Claude Code
ls ~/.claude/commands/

# Gemini CLI
ls ~/.gemini/commands/

# Cursor
ls ~/.cursor/commands/

Interactive Prompt Issues

Set CI environment variable to skip prompts:

CI=true npx apex-sdd-cli init my-project --ai opencode

Links

• npm Package
• GitHub Repository
• Report Issues

License

MIT © APEX Framework