Documentation

Everything you need to govern your AI development workflow

Quick Start

Install

Install the ArchonDev CLI globally

npm install -g archon

Initialize

Navigate to your project and run archon

cd your-project && archon

Plan and Execute

Create your first governed task

archon plan "Add user authentication"

Smart Onboarding: Three Scenarios

ArchonDev automatically detects your project state and offers the right workflow.

🎉

New Project

Empty folder, no source files

What happens:

• Interactive interview to define project
• Questions about stack, audience, preferences
• Generates customized ARCHITECTURE.md
• Creates governance files

📁

Adapt Existing

Has code, first time with ArchonDev

What happens:

• Offers to analyze codebase
• Option for code review first
• Adapts governance to match structure
• No code changes, only analysis

👋

Continue Session

Already set up, returning user

What happens:

• Shows last activity summary
• Checks for handoff from last session
• Displays review progress if applicable
• Goes straight to main menu

How It Works

Condition	Scenario
No source files + no progress.txt entries	→ New Project
Has source files + no progress.txt entries	→ Adapt Existing
Has progress.txt with dated entries	→ Continue Session

Task Extraction Protocol

When you describe multiple things at once, AI often loses items 3+ in the list. The Task Extraction Protocol fixes this by making AI confirm every item before starting.

How It Works

1
You describe work — "Fix the login bug, add password reset, and update the docs"
2
AI extracts & numbers — Presents a checklist: 1. Fix login bug, 2. Add password reset, 3. Update docs
3
You confirm — "Yes" to proceed, or add/remove/change items
4
AI tracks progress — Works through list systematically, reports "✅ 2/3 done"
5
Final verification — Shows all completed items before declaring done

Trigger Phrases

plan these tasks

Force task extraction mode

task status

Show current progress on active list

what's on my list

Show active task list

add to list: [item]

Add new item to active list

Pre-Deploy Accessibility Check

Before deploying a live website, ArchonDev checks for WCAG 2.2 AA compliance and warns about potential legal liability.

⚖️ Why This Matters

Websites that don't meet accessibility standards may violate:

ADA — Americans with Disabilities Act (US)
EAA — European Accessibility Act (EU, effective June 2025)
Section 508 — US federal agencies and contractors
AODA — Accessibility for Ontarians (Canada)

In 2023, over 4,600 ADA web accessibility lawsuits were filed in the US alone.

How It Works

1
Trigger — When you say "deploy", "go live", or "publish"
2
Audit — Checks color contrast, alt text, keyboard nav, forms, ARIA
3
Report — Lists issues with WCAG criteria and severity
4
Choose — Fix issues now, deploy anyway (with warning), or cancel
5
Badge — Add "WCAG 2.2 AA Accessible" badge to your footer

CLI Commands

archon a11y check

Run WCAG 2.2 AA audit

archon a11y fix

Auto-fix common issues

archon a11y badge

Add compliance badge to footer

archon a11y pre-deploy

Interactive pre-deployment check

Lite Package Trigger Phrases

check accessibility — Run full audit

fix accessibility — Auto-fix common issues

add accessibility badge — Add footer badge

CLI Reference

Core Commands

archon

Start interactive mode. Initializes project if needed.

archon init [--analyze]

Initialize ArchonDev in current project. Creates ARCHITECTURE.md and .archon directory.

archon plan <description>

Create a new atom with adversarial planning. Architect proposes, Sentinel validates.

archon execute <atom-id>

Execute a planned atom. Runs conflict check, implementation, and quality gates.

archon list [--status STATUS]

List all atoms in the project with status and priority.

archon show <atom-id>

Show detailed information about a specific atom.

archon watch

Open the live TUI dashboard showing atoms, credits, and activity.

Credits Commands

archon credits

Show current credit balance.

archon credits add [--amount DOLLARS]

Purchase credits via Stripe. Minimum $5.

archon credits history

Show recent token usage and costs.

Key Management — BYOK (Bring Your Own Key)

archon keys add <provider>

Add your own API key. Providers: anthropic, openai, google.

archon keys list

List configured API key providers.

archon keys remove <provider>

Remove stored API key for a provider.

Bug Workflow

archon bug report <title>

Create a bug report with automatic triage and root cause analysis.

Dependency Tracking — Regression prevention

archon deps init

Create a starter DEPENDENCIES.md file.

archon deps list [-v]

List all dependency rules. Use -v for detailed info.

archon deps add -s <source> -d <dependent>

Add a new dependency rule. Options: --severity, --reason, --id.

archon deps check -f <files>

Check if files have downstream dependency impacts.

archon deps graph [--output file]

Generate Mermaid diagram of dependencies.

Code Review — AI-powered analysis

archon review init

Initialize code review database for the project.

archon review analyze

Scan project structure and populate review tasks.

archon review run [--all] [--limit N]

Run AI-powered review on pending tasks.

archon review status

Show review progress and statistics.

archon review plan

Generate prioritized fix plan after reviews complete.

archon review export [--format json|markdown]

Export review report for sharing.

DEPENDENCIES.md — Regression Prevention

DEPENDENCIES.md is your "what-breaks-what" map — the most valuable asset for preventing regressions. It tracks file-level dependencies so AI (and humans) know which files to review when making changes.

🛡️ Why This Matters

Research shows that most bugs come from changes that break dependent code. When AI changes a file without knowing what depends on it, regressions happen. DEPENDENCIES.md prevents this by making dependencies explicit and checkable.

Format

Uses YAML frontmatter (same pattern as ARCHITECTURE.md):

---
version: "1.0"
updatedAt: "2026-01-22"
rules:
  - id: "DEP-001"
    source: "src/core/parser.ts"
    dependents:
      - "src/cli/**"
      - "src/agents/**"
    severity: "WARNING"
    reason: "CLI and agents depend on parser types"
    mustTest:
      - "pnpm test parser"
---

# Dependencies (File & Symbol Impact Map)
...

CLI Commands

archon deps init

Create a starter DEPENDENCIES.md file

archon deps list

View all dependency rules

archon deps add --source <path> --dependent <path>

Add a new dependency rule

archon deps check --files src/api.ts,src/db.ts

Check if files have downstream impacts

archon deps graph

Generate Mermaid diagram of dependencies

Severity Levels

INFO FYI — might want to review dependents

WARNING Should review dependents before merging

BLOCKER Must update dependents before this change can proceed

Automatic Integration

When you run archon execute, the ConflictChecker automatically reads DEPENDENCIES.md and warns you about downstream impacts before changes are applied. This happens without any additional configuration.

Code Review

ArchonDev's Code Review feature provides comprehensive, AI-powered analysis of any codebase. Unlike traditional linters, it understands your architecture and specifications to identify bugs, security issues, and deviations from requirements.

Key Features

✓ Non-destructive: AI reviews code without modifying it—findings only
✓ Works on any project: Not limited to ArchonDev-created projects
✓ Architecture-aware: Uses ARCHITECTURE.md to validate boundaries
✓ Prioritized fixes: Critical issues surface first with fix plans
✓ CLI-only: Full control from your terminal

Review Workflow

Initialize

archon review init

Creates SQLite database at docs/code-review/review-tasks.db

Analyze

archon review analyze

Scans project, identifies features, populates review tasks

Review

archon review run --all

AI reviews each task, identifies issues, records findings

Plan

archon review plan

Generates prioritized fix plan (critical → low)

Export

archon review export --format markdown

Share reports with your team

What It Finds

Security

Injection, auth issues, data exposure

Bugs

Logic errors, null references, edge cases

Performance

N+1 queries, memory leaks, bottlenecks

Architecture

Boundary violations, invariant breaks

Documentation

Missing docs, outdated comments

Style

Inconsistent patterns, naming issues

Working with Existing Projects

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

When to Use This Workflow

• You inherited a codebase from another AI agent (Claude, Cursor, Copilot, etc.)
• You want to audit code quality before adding governance
• You're converting a manual project to ArchonDev-governed development

Step-by-Step Workflow

Install ArchonDev

npm install -g archon

Initialize Code Review

Creates a local SQLite database for tracking review tasks

archon review init

Analyze Project

Scans your codebase and creates review tasks for each file

archon review analyze

Run AI Review

AI analyzes all files for bugs, security issues, and architecture concerns

archon review run --all

Export Report

Generate a Markdown report of all findings

archon review export > review-report.md

Set Up Governance

Creates ARCHITECTURE.md by analyzing your existing codebase structure

archon init --analyze

Start Governed Development

Address issues found in the review with adversarial planning

archon plan "fix issues from review"

What Happens

→ Code Review: Creates a local SQLite database at docs/code-review/review-tasks.db to track findings

→ archon init: Creates ARCHITECTURE.md and .archon/ directory for governance

→ Future Changes: All development goes through adversarial planning (Architect proposes, Sentinel validates)

ARCHITECTURE.md Format

Your ARCHITECTURE.md file is the source of truth for governance. It uses YAML frontmatter to define boundaries, invariants, and protected paths.

Example

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

boundaries:
  - path: "src/db/**"
    protection: STRICT
    description: "Database layer - no direct imports from CLI"
  - path: "src/api/**"
    protection: FLEXIBLE
    description: "API layer - prefer abstraction"

invariants:
  - id: INV-001
    type: NO_DIRECT_IMPORT
    path: "@supabase/supabase-js"
    description: "Use src/db/client.ts instead"
    enforcement: BLOCKING
  - id: INV-002
    type: NO_ANY
    description: "Avoid using 'any' type"
    enforcement: WARNING

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

# My Project Architecture

Describe your architecture here...

Boundaries

Define module boundaries with protection levels: STRICT (blocked), FLEXIBLE (warning), or OPEN (allowed).

Invariants

Define rules that must always hold. Types: NO_DIRECT_IMPORT, NO_ANY, NO_CONSOLE.

Protected Paths

Files requiring special attention when modified. Uses glob patterns.

Enforcement

BLOCKING (error), WARNING (warn), INFO (note). Control how violations are handled.

Tiers and Billing

FREE

- Fast models only (Haiku, Flash, Mini)
- 10,000 atoms/month
- No credit card required

CREDITS

Pay-as-you-go

- All models (Opus, Sonnet, GPT-4)
- Unlimited atoms
- 10% service fee on usage
- Min $5 purchase

BYOK (Bring Your Own Key)

Use your own API keys

- Use your own API keys
- All models available
- No service fee
- Pay providers directly

VS Code Extension

The ArchonDev VS Code extension provides real-time architectural governance with quick-fix suggestions as you type.

Features

- Real-time violation detection in the Problems panel
- Quick-fix suggestions — Lightbulb menu (Ctrl+. / Cmd+.) with auto-fixes
- Protected path warnings when editing governed files
- Boundary enforcement for cross-module imports
- Invariant checking (NO_DIRECT_IMPORT, NO_ANY, NO_CONSOLE)
- Architecture overview panel

Quick-Fix Actions

When a violation is detected, press Ctrl+. (Windows/Linux) or Cmd+. (Mac) for fix options:

Protected path: Add approval comment with reviewer template
Boundary violation: Comment out, add TODO, or delete import
NO_ANY: Replace with unknown or add @ts-expect-error
NO_CONSOLE: Remove, comment out, or replace with logger
NO_DIRECT_IMPORT: Comment out or delete the import

Installation

Download archondev-0.2.0.vsix from the downloads page
In VS Code: Extensions > ... > Install from VSIX
Select the downloaded file
Reload VS Code

Troubleshooting

"Command not found: archon"

Make sure npm global bin is in your PATH. Run npm bin -g to see the path, then add it to your shell config.

"Insufficient credits"

Run archon credits add to purchase more credits, or switch to BYOK (Bring Your Own Key) tier with your own API keys.

"ARCHITECTURE.md not found"

Run archon init in your project root to create the file.

VS Code extension not detecting violations

Ensure ARCHITECTURE.md is in your workspace root. Run the command "ArchonDev: Refresh Architecture" to reload.

Need Help?

Email us at techsupport@JumpingAhead.com