archondev 2.19.56 → 3.0.0

package/README.md

@@ -25,24 +25,40 @@ npm install -g archondev; archon
 - Bug reporting with root cause analysis
 - AI-powered code review for any codebase
 - Multi-provider key support with adversarial features
+- **Risk scoring** — 0-100 risk assessment before every execution
+- **Ship pipeline** — `archon ship`: review → test → version → changelog → PR
+- **Visual QA** — `archon qa`: headless browser health checks with diff-aware page testing
+- **Session retrospective** — `archon retro`: quantitative metrics on your session
 
 ### Option 2: Lite Package
-Copy governance files into any project. Works with your existing AI tools: **Cursor, Claude Code, Windsurf, Amp, Copilot, Gemini**, and more.
+Context-aware intelligence for your existing AI tools: **Cursor, Claude Code, Windsurf, Amp, Copilot, Gemini**, and more. Your AI detects what you're doing and proactively offers the right help — no commands to memorize.
 
 [Download Lite Packages →](https://archondev.io/download)
 
-**What you get:**
+**Context-Aware Intelligence (NEW):**
+- **Fix-First Code Review** — Auto-fixes mechanical issues, only asks about ambiguous ones
+- **AI Slop Detection** — 10-item blacklist catches generic AI design patterns, scored A-F
+- **Systematic Debugging** — Root cause first, 3-strike hypothesis testing, regression prevention
+- **Ship Readiness Dashboard** — Pre-deploy checklist tracks all quality gates across your session
+- **Scope Management** — 4 modes (expand/selective/hold/reduce) when scope creep detected
+- **Self-Regulation Guardrails** — Blast radius checks, file limits, automatic checkpoints
+- **Design Governance** — DESIGN.md as design source of truth with visual audit
+- **Completion Status** — Clear DONE/CONCERNS/BLOCKED/NEEDS_CONTEXT reporting
+- **Progress Reflection** — Solo retro at natural milestones
+- **Expert Review Spec** — Generate a consultant-ready technical spec (gap analysis, approach review, UX enhancement) at any milestone
+- **Features Dashboard** — Live HTML page tracking which capabilities you've used, what's available, and what's recommended next
+
+**Governance Foundation:**
 - .archon/active/architecture.md template with best practices
-- **Quality Level / Posture** — Tell AI if it's prototype, production, or enterprise-grade
+- **Quality Level / Posture** — prototype/production/enterprise-grade behavior
+- **DEPENDENCIES.md** — File-level dependency tracking to prevent regressions
 - IDE-specific rule files (.cursorrules, CLAUDE.md, GEMINI.md, etc.)
-- Progress tracking templates
-- **DEPENDENCIES.md** — Track file-level dependencies to prevent regressions
-- **First-Run Walkthrough** — Guided onboarding when AI detects your governance files
-- **Code Review Mode** — Structured code review without changing your code
-- **Local Database** — Track atoms and learnings in SQLite (no CLI required)
-- **Memory Management** — Context handoff protocol for long sessions
-- **Task Extraction Protocol** — AI confirms all items before starting, nothing gets forgotten
-- **Pre-Deploy Accessibility** — WCAG 2.2 AA check before going live, legal liability warnings
+- **24 on-demand AI skills** — Design review, debugging, ship readiness, scope review, accessibility, SEO/GEO, color scheme picker, expert review, features dashboard, and more — loaded only when triggered, keeping context lean
+- **Skills-based architecture** — 80% smaller context footprint (8.6 KB core vs 42 KB monolithic). Skills load on-demand with progressive disclosure
+- **Claude Code: 16 native slash commands** — `/debug`, `/design-review`, `/ship-readiness`, `/code-review`, `/scope-check`, `/expert-review`, `/geo-optimize`, `/seo-check`, `/accessibility`, `/reflect`, `/handoff`, `/plan-tasks`, `/color-scheme`, `/rollback`, `/dashboard`, `/constitution`
+- **GEO Optimization** — 7-phase protocol for AI search citation: identity phrases, atomic claims, JSON-LD schemas, and audit ([free tools](https://archondev.io/geo))
+- **Task Extraction** — AI confirms all items before starting, nothing gets forgotten
+- **Context Handoff** — Memory management for long sessions
 - Works with any AI coding assistant
 
 ### Local Governance SQLite (Dev Only)
@@ -60,12 +76,11 @@ pnpm exec tsx scripts/init-governance-db.ts
 
 | Command | Description |
 |---------|-------------|
-| `archon` | Interactive mode — just run and follow prompts |
+| `archon` | Chat-first interactive mode — just run and start talking |
 | `archon init` | Initialize in your project |
-| `archon login` | Authenticate with ArchonDev |
-| `archon upgrade` | Switch between Free and BYOK modes |
-| `archon config ai` | Guided BYOK setup (providers + key entry) |
-| `archon status` | Show login status and current mode |
+| `archon mode` | Choose local governance mode or BYOK AI mode |
+| `archon config ai` | Guided BYOK provider-key setup |
+| `archon status` | Show local mode, auth, and project status |
 | `archon plan <description>` | Create a work item with AI planning (extracts and confirms multi-item requests) |
 | `archon execute <atom-id>` | Execute with quality gates |
 | `archon list` | List all work items |
@@ -98,17 +113,15 @@ pnpm exec tsx scripts/init-governance-db.ts
 | `archon governance handoff` | Log handoff + current context |
 | `archon governance migrate` | Migrate legacy governance files |
 | `archon governance sqlite-init` | Initialize or refresh local governance SQLite DB |
-| `archon github connect` | Link GitHub account for cloud execution |
-| `archon github status` | Check GitHub connection status |
-| `archon session save [name]` | Save current session to cloud |
-| `archon session resume [id]` | Resume session on another device |
-| `archon execute ATOM --cloud` | Execute in cloud (creates PR when done) |
-| `archon cloud status` | List cloud executions |
-| `archon parallel cloud ATOM-001 ATOM-002` | Legacy command (disabled in free/BYOK mode) |
-| `archon index init [--local\|--cloud]` | Initialize semantic indexing |
-| `archon index update [--cloud]` | Index changed files |
-| `archon index search "query" [--cloud]` | Semantic code search |
+| `archon index init` | Initialize local semantic indexing |
+| `archon index update` | Index changed files |
+| `archon index search "query"` | Semantic code search |
 | `archon parallel status` | Show parallel execution status |
+| `archon ship` | Ship pipeline: review → test → version → changelog → PR |
+| `archon ship --dry-run` | Run all ship checks without committing |
+| `archon qa` | Visual QA with headless browser health checks |
+| `archon qa --url <url>` | Test specific URL |
+| `archon retro` | Session retrospective with quantitative metrics |
 | `archon deploy` | One-click deploy (auto-detect platform) |
 | `archon cleanup check` | Analyze workspace for bloat |
 | `archon cleanup run` | Execute cleanup tasks |
@@ -130,12 +143,14 @@ pnpm exec tsx scripts/init-governance-db.ts
 
 ## Pricing
 
-| Mode | Cost | What You Get |
-|------|------|--------------|
-| **Free (Download / Governance)** | $0 | Governance/workflow layer with no built-in AI calls |
-| **BYOK (CLI + AI)** | $0 to ArchonDev | Use your own provider keys; provider bills tokens directly |
+**ArchonDev is Free.** There are no paid tiers, no subscriptions, and no credit card required.
+
+| Mode | Cost to ArchonDev | What You Get |
+|------|-------------------|--------------|
+| **Download / Governance** | $0 | Governance/workflow layer with no built-in AI calls |
+| **CLI + AI (BYOK)** | $0 | Full CLI with AI — bring your own API keys; your provider bills tokens directly at cost |
 
-No paid tiers, no credit purchases, and no Archon token markup.
+No Archon token markup. You pay your LLM provider directly at their published rates.
 
 ### BYOK Key Security
 
@@ -146,12 +161,12 @@ No paid tiers, no credit purchases, and no Archon token markup.
 
 ## How It Works
 
-1. **Login & Choose Mode** — Create account, choose Free or BYOK
-2. **AI Interview** — Natural conversation about your project (or skip to defaults)
-3. **Define Your Rules** — ARCHITECTURE.md with boundaries and invariants
-4. **AI Reads Rules First** — Every session starts by understanding your architecture
-5. **Changes Are Validated** — Quality gates check code before it's applied
-6. **Learnings Persist** — Insights saved for future sessions
+1. **Run `archon`** — Archon inspects the current folder and governance state
+2. **Add keys only if needed** — BYOK setup is local-only and optional until you want AI actions
+3. **Start in chat** — Ask naturally; Archon decides when to stay conversational vs create atoms
+4. **Governance loads first** — Architecture, dependencies, and progress are respected automatically
+5. **Changes are validated** — Quality gates and approval policy stay active
+6. **Continuity persists** — Handoffs, pending work, and learnings stay local across sessions
 
 ## First Run Experience
 
@@ -161,15 +176,14 @@ $ archon
 ArchonDev - AI-Powered Development Governance
 ────────────────────────────────────────────────
 
-Logged in as: you@example.com
-Mode: Free (download-only governance)
+AI mode: Local governance only
 
-FREE mode: no built-in AI calls.
+No provider keys configured yet.
 → Run 'archon config ai' to enable BYOK for CLI AI features
 
 → What kind of project are you building?
   [AI asks natural follow-up questions based on your answers]
-  (Type "upgrade" or "help" anytime)
+  (Type "mode" or "help" anytime)
 
 ✓ Project initialized!
 ```
@@ -180,15 +194,16 @@ Type these anytime during interactive prompts:
 
 | Command | Description |
 |---------|-------------|
-| `upgrade` | Open tier upgrade menu |
-| `status` | Show login and mode info |
+| `config ai` | Open BYOK key setup |
+| `status` | Show local mode and optional auth info |
 | `keys` | List configured API keys |
 | `help` | Show available commands |
 | `quit` | Exit ArchonDev |
 
 ## Cloud Execution (Legacy)
 
-Run AI agents in the cloud — close your laptop and get a PR when it's done.
+These commands are preserved only for backward compatibility and are hidden from the normal CLI surface.
+They are not part of the current local-first product path.
 
 ```bash
 # 1. Authenticate
@@ -202,7 +217,7 @@ archon github status        # Verify connection
 archon plan "add user settings page"
 archon execute ATOM-001 --cloud
 
-# 3b. Queue multiple atoms in parallel (Credits tier)
+# 3b. Queue multiple atoms in parallel (legacy command; disabled in free/BYOK mode)
 archon parallel cloud ATOM-001 ATOM-002
 
 # 4. Check progress
@@ -210,7 +225,6 @@ archon cloud status         # List all cloud executions
 archon cloud logs <id>      # View execution logs
 ```
 
-The cloud worker clones your repo, runs the Executor agent, creates a feature branch, and opens a PR. You can close your terminal after queuing.
 Cloud execution is currently disabled in the free/BYOK model. Use local execution with BYOK keys.
 
 ## Working with Existing Projects
@@ -237,7 +251,9 @@ The CLI detects existing projects and suggests this workflow automatically.
 
 ## Documentation
 
-- [archondev.io](https://archondev.io) — Main website with animated AI problems story
+- [archondev.io](https://archondev.io) — Main website
+- [archondev.io/geo](https://archondev.io/geo) — Free GEO optimization tools (Claude skill + prompt generator)
+- [archondev.io/color-schemes](https://archondev.io/color-schemes) — Color Scheme Picker (26 curated schemes)
 - [AI Coding Problems Research](docs/ai-coding-problems-research.md) — Market research on AI coding assistant issues
 
 ## Website Deploy (Bunny.net)

package/dist/{auth-XRKCCFJ3.js → auth-T4C7OQWO.js}

@@ -2,7 +2,7 @@ import {
   login,
   logout,
   status
-} from "./chunk-6TBYNRNF.js";
+} from "./chunk-57NSGWWD.js";
 import "./chunk-M4LGRTLC.js";
 import "./chunk-ONH6Y3CS.js";
 import "./chunk-GGRW4NTA.js";

package/dist/{chunk-F3DZZHZB.js → chunk-43IIEFB2.js}

@@ -1,6 +1,6 @@
 import {
   listLocalAtoms
-} from "./chunk-OHIN6OHU.js";
+} from "./chunk-7RXZTPXY.js";
 
 // src/cli/list.ts
 import chalk from "chalk";

package/dist/{chunk-4K3XNRU6.js → chunk-45T2VB5R.js}

@@ -4,7 +4,7 @@ import {
 import {
   listLocalAtoms,
   loadAtom
-} from "./chunk-OHIN6OHU.js";
+} from "./chunk-7RXZTPXY.js";
 import {
   SUPABASE_ANON_KEY,
   SUPABASE_URL
@@ -748,7 +748,7 @@ async function parallelClean() {
 }
 function toSchedulableAtom(atom) {
   return {
-    id: atom.id,
+    id: atom.externalId,
     title: atom.title,
     dependencies: atom.plan?.dependencies,
     filesTouched: atom.plan?.files_to_modify
@@ -809,8 +809,15 @@ async function parallelSchedule(options) {
 }
 async function parallelRunWaves(options) {
   const atoms = await listLocalAtoms();
-  const readyAtoms = atoms.filter((a) => a.status === "READY");
+  const scopeIds = options.onlyAtomIds ? new Set(options.onlyAtomIds) : null;
+  const readyAtoms = atoms.filter(
+    (a) => a.status === "READY" && (!scopeIds || scopeIds.has(a.externalId))
+  );
   if (readyAtoms.length === 0) {
+    if (scopeIds && scopeIds.size > 0) {
+      console.log(chalk2.yellow("No READY atoms found in the approved scope."));
+      return;
+    }
     console.log(chalk2.yellow("No READY atoms found."));
     return;
   }
@@ -875,7 +882,8 @@ async function parallelRunWaves(options) {
 }
 async function executeAtomInWorktree(atomId, worktreePath) {
   return new Promise((resolve) => {
-    const child = spawn("npx", ["archon", "execute", atomId, "--skip-gates"], {
+    const cliEntry = process.argv[1] ?? "archon";
+    const child = spawn(process.execPath, [cliEntry, "execute", atomId, "--skip-gates"], {
       cwd: worktreePath,
       stdio: "pipe"
     });
@@ -900,6 +908,8 @@ async function executeAtomInWorktree(atomId, worktreePath) {
 }
 
 export {
+  buildDependencyGraph,
+  scheduleExecution,
   cloudStatus,
   cloudCancel,
   cloudLogs,

package/dist/{chunk-6TBYNRNF.js → chunk-57NSGWWD.js}

@@ -228,22 +228,24 @@ async function logout() {
 async function status() {
   const config = await loadConfig();
   if (!config.accessToken) {
-    console.log(chalk.yellow("Not logged in"));
-    console.log(chalk.dim("Run `archon login` to authenticate"));
+    console.log(chalk.green("Local-only mode active"));
+    console.log(chalk.dim(`AI mode: ${formatTier(config.tier ?? "FREE")}`));
+    console.log(chalk.dim("Platform login is optional and only needed for legacy remote features."));
     return;
   }
   if (config.expiresAt) {
     const expiresAt = new Date(config.expiresAt);
     if (expiresAt < /* @__PURE__ */ new Date()) {
       console.log(chalk.yellow("Session expired"));
-      console.log(chalk.dim("Run `archon login` to re-authenticate"));
+      console.log(chalk.dim(`AI mode: ${formatTier(config.tier ?? "FREE")}`));
+      console.log(chalk.dim("Re-authenticate only if you need legacy remote features."));
       return;
     }
   }
-  console.log(chalk.green("\u2713 Authenticated"));
+  console.log(chalk.green("\u2713 Optional remote session available"));
   console.log();
   console.log(`  ${chalk.dim("Email:")} ${config.email}`);
-  console.log(`  ${chalk.dim("Tier:")}  ${formatTier(config.tier ?? "FREE")}`);
+  console.log(`  ${chalk.dim("AI mode:")} ${formatTier(config.tier ?? "FREE")}`);
   console.log(`  ${chalk.dim("User:")}  ${config.userId}`);
   if (config.expiresAt) {
     const expiresAt = new Date(config.expiresAt);
@@ -254,10 +256,10 @@ async function status() {
 function formatTier(tier) {
   switch (tier) {
     case "BYOK":
-      return chalk.blue("BYOK (Bring Your Own Key)");
+      return chalk.blue("BYOK (your provider keys)");
     case "FREE":
     default:
-      return chalk.gray("FREE (Download-only mode)");
+      return chalk.gray("Local governance only");
   }
 }
 

package/dist/{chunk-OHIN6OHU.js → chunk-7RXZTPXY.js}

@@ -1,6 +1,7 @@
 import {
+  appendLocalUsageEntry,
   debugLog
-} from "./chunk-R664NEAA.js";
+} from "./chunk-I3BBA7MB.js";
 import {
   ArchitectureParser
 } from "./chunk-5EVHUDQX.js";
@@ -440,9 +441,8 @@ async function plan(description, options) {
   const conversational = options.conversational === true;
   const concise = options.conciseOutput === true;
   try {
-    if (!await isAuthenticated()) {
-      console.log(chalk.yellow('Not authenticated. Run "archon login" first.'));
-      console.log(chalk.dim("For local development, you can continue without authentication."));
+    if (!await isAuthenticated() && !concise) {
+      console.log(chalk.dim("Running in local mode. Platform login is optional and not required for planning."));
     }
     const archPath = join2(process.cwd(), "ARCHITECTURE.md");
     if (!existsSync2(archPath)) {
@@ -771,6 +771,16 @@ Next steps:`));
       console.log(chalk.dim(`
 Token usage: ${planResult.totalUsage.inputTokens} input, ${planResult.totalUsage.outputTokens} output`));
     }
+    await appendLocalUsageEntry({
+      timestamp: (/* @__PURE__ */ new Date()).toISOString(),
+      projectPath: process.cwd(),
+      model: planner.getBillingModel().model,
+      provider: planner.getBillingModel().provider,
+      operation: "ADVERSARIAL_PLANNING",
+      inputTokens: planResult.totalUsage.inputTokens,
+      outputTokens: planResult.totalUsage.outputTokens,
+      baseCost: planResult.totalUsage.baseCost
+    });
     if (conversational) {
       atom.plan = planResult.finalPlan ?? buildConversationalFallbackPlan({
         description,