Documentation

Quick Start

npm install -g archondev

cd your-project && archon

archon plan "Add user authentication"

Smart Onboarding: Three Scenarios

After startup, ArchonDev reads the folder and routes you to the right workflow without guesswork.

User Journey Governance (Lite + CLI)

ArchonDev is optimized as a full journey system, not just command docs. Both Lite and CLI flows are designed to reduce decision fatigue, prevent dead ends, and move users from setup to confident execution quickly.

Quality Level / Posture

Set how strict your AI should be. Run lean in prototypes and lock discipline in production and enterprise.

5-Phase Interview System

A conversational interview that guides you through defining your project, then generates a formal specification.

Project Constitution

The Constitution is a formal, immutable specification generated from the interview. It's the contract between you and the AI for what gets built.

Generate prd.json from Constitution

Once frozen, transform your Constitution into executable atoms:

CLI Reference

Use these commands to keep execution on course: approve design, execute with gates, and review in the right order.

.archon/active/architecture.md Format

Your source of truth for governance. Uses YAML frontmatter.

---
name: My Project
version: "1.0"

boundaries:
  - path: "src/db/**"
    protection: STRICT
    description: "Database layer"

invariants:
  - id: INV-001
    type: NO_DIRECT_IMPORT
    path: "@supabase/supabase-js"
    enforcement: BLOCKING

protectedPaths:
  - pattern: "src/db/schema.ts"
    reason: "Schema changes require migration"
---

DEPENDENCIES.md

Track file-level dependencies to prevent regressions.

Code Review

AI-powered code review for any codebase. Non-destructive analysis.

Task Extraction Protocol

AI confirms all items from multi-part requests before starting. Nothing gets forgotten.

Context-Aware Intelligence

Instead of requiring slash commands, ArchonDev detects what you're doing and proactively offers help. The AI reads context — file types, error output, milestones, scope changes — and presents relevant options with a skip choice.

Every trigger includes a skip option. The AI never forces a capability — it just makes sure you know what's available.

Fix-First Code Review

Instead of listing issues for you to fix, ArchonDev auto-fixes mechanical problems and only asks about genuinely ambiguous ones.

AI Slop Detection

AI-generated designs have recognizable patterns. ArchonDev checks frontend code against a 10-item blacklist and scores A through F.

Grading: A (no patterns, intentional design) through F (7+ patterns, obvious AI slop). Score C or below triggers a flag.

Systematic Debugging

When a bug is detected, the AI follows a structured protocol instead of guessing at fixes.

Ship Readiness Dashboard

Before deploying, see a dashboard of what's been checked and what's missing.

Ship Readiness Dashboard
========================
[x] Architecture review — no violations
[x] Dependency check — verified safe
[x] Code review — 3 auto-fixed, 0 blockers
[x] Tests — all passing
[ ] Design review — NOT RUN
[x] Accessibility — WCAG 2.2 AA compliant

Ready to ship: NO — Design review pending

Required checks: architecture, dependencies, code review, tests. Conditional: design review (if frontend), accessibility (if web), SEO/GEO (if public), security (if API/auth).

Scope Management

When scope changes mid-feature, the AI detects it and offers four options:

The AI recommends based on your project posture: prototype favors EXPAND or REDUCE; production favors HOLD or SELECTIVE.

Self-Regulation Guardrails

Hard limits that prevent the AI from going off the rails during complex tasks.

Accessibility Check

If Archon detects a web project, it will prompt you to run A11y/SEO/GEO checks and remember your preference in .archon/config.yaml.

WCAG 2.2 AA compliance checks with legal liability warnings.

SEO Optimization

GEO for AI Search

Generative Engine Optimization — get your product cited by AI assistants.

Retired Remote Paths

Remote account, GitHub, cloud execution, saved-session, Stripe credits, and Supabase usage paths are retired. Hidden compatibility commands print a retirement message instead of calling Archon-managed Supabase or Fly services.

Semantic Indexing

Semantic search across your codebase. The primary path is now local-first.

Local Indexing

# Install Ollama first: https://ollama.ai
ollama pull nomic-embed-text
archon index init
archon index update
archon index search "authentication flow"

Retired Remote Indexing

Remote indexing through Archon-managed infrastructure is retired. Use the local index commands below; cloud index flags print retirement guidance instead of calling Supabase or Fly.

Smart Model Routing

Automatically routes operations to the optimal AI model tier for cost optimization. Simple tasks use cheap/fast models; complex planning uses powerful models.

Model Tiers

Configure Preferences

Parallel Execution

Run multiple agents simultaneously using git worktrees with dependency-aware scheduling.

Dependency Scheduling

ArchonDev analyzes atom dependencies and file conflicts to schedule execution in parallel waves.

Manual Parallel

Parallel Cloud (Disabled)

History & Revert

Each atom execution creates a git commit. Revert individual atoms without affecting other changes.

CLI Users

Lite Package Users

Say show atom history or revert atom to your AI. Uses git under the hood:

# List atom commits
git log --oneline | grep -E '\[(ATOM|US)-[0-9]+\]'

# Revert specific commit
git revert <commit-hash>

Eject

Remove all ArchonDev metadata, leaving a clean standalone codebase you fully own.

CLI Users

Lite Package Users

Say eject archondev to your AI, or manually remove:

• • .archon/, archondev-skills/, AGENTS.md
• • IDE rules: .cursorrules / .windsurfrules / CLAUDE.md / etc.

Keep: .archon/active/architecture.md (useful standalone), progress.txt (history)

Deploy

One-click deployment with automatic platform detection.

Supported: Fly.io, Vercel, Netlify, Railway, Render

Cleanup

Keep your workspace lean for optimal AI performance. Large files consume context.

Working with Existing Projects

Add governance to projects created by other AI agents or manual coding.

# Step 1: Review existing code
archon review init
archon review analyze
archon review run --all

# Step 2: Set up governance
archon init --analyze

# Step 3: Fix issues
archon plan "fix critical issues from review"

VS Code Extension

Real-time architectural governance with quick-fix suggestions.

• • Real-time violation detection in Problems panel
• • Quick-fix suggestions (Ctrl+. / Cmd+.)
• • Protected path warnings
• • Boundary enforcement for cross-module imports

Installation: Download archondev-0.2.0.vsix from the downloads page, then Extensions → ... → Install from VSIX

Modes & BYOK

BYOK Key Security

• • Your API keys stay on your machine and are never uploaded to ArchonDev servers.
• • Keys are encrypted at rest with AES-256-GCM in ~/.archon/keys.json.
• • The key file is set to owner-only permissions (0600).
• • BYOK runs locally with your own provider keys.

If your device is compromised, an attacker could access local files. Treat API keys as sensitive secrets.

Troubleshooting