autoarchitect

Autonomous system design — research, spec, and implementation plan from a single instruction.

Point autoarchitect at a requirement, go get coffee, come back to a researched, reviewed, executable system design. Every architectural decision is documented with reasoning, rejected alternatives, and a trail of the research that informed it.

Works with Claude Code and Codex CLI via the Agent Skills standard, and ships as a standalone CLI for everything else. See Inspired By below for the projects that informed its design.

Two ways to run

| Form | Best for | Installs | |------|----------|----------| | Plugin (pure markdown) | Inside Claude Code or Codex CLI — richest integration with native web search, file tools, codebase scan | /plugin install autoarchitect@autoarchitect | | Standalone CLI (TypeScript) | CI/CD, scripts, any environment outside an agent — brings its own Anthropic / OpenAI / OpenAI-compatible backend | npx autoarchitect "..." or npm i -g autoarchitect |

Both produce identical output: a design spec, an implementation plan, and a research journal — all in superpowers format and directly executable.

Table of Contents

• Quick Start
• Plugin Installation
• CLI Installation
• Usage
• How It Works
• What You Get
• CLI Reference
• Long-Running Sessions
• Permissions
• Session Files
• Development
• Inspired By
• Contributing
• License

Quick Start

Inside Claude Code:

/autoarchitect:design-loop "Build a real-time collaborative document editor"

Standalone CLI:

export ANTHROPIC_API_KEY=sk-...
npx autoarchitect "Build a real-time collaborative document editor"

Both produce the same output files in docs/superpowers/.

Plugin Installation

autoarchitect ships as a pure-markdown Agent Skills plugin, so it works with any agent that supports the standard. Installation differs by platform.

Claude Code

Register the autoarchitect marketplace, then install:

/plugin marketplace add pawanpaudel93/autoarchitect
/plugin install autoarchitect@autoarchitect

To remove:

/plugin uninstall autoarchitect@autoarchitect
/plugin marketplace remove pawanpaudel93/autoarchitect

OpenAI Codex CLI

Codex doesn't support GitHub-sourced marketplaces yet, so installation is done through a personal local marketplace. Paste this into Codex and it will install itself:

Fetch and follow the instructions at https://raw.githubusercontent.com/pawanpaudel93/autoarchitect/main/.codex/INSTALL.md

Or read .codex/INSTALL.md and run the steps manually.

Verify

Once installed, these skills are available:

| Skill | Purpose | |-------|---------| | /autoarchitect:design-loop | Run the full autonomous design loop | | /autoarchitect:research | Research a specific design question | | /autoarchitect:spec-assembly | Assemble spec from answered questions | | /autoarchitect:self-review | Run quality gates on a design |

CLI Installation

The CLI is a standalone Node.js package — no agent required. It calls LLM APIs directly.

One-shot (no install)

npx autoarchitect "Build a URL shortener with click analytics"

Global install

npm install -g autoarchitect
# or
pnpm add -g autoarchitect

autoarchitect "Build a URL shortener with click analytics"

As a library

import { DesignLoop } from 'autoarchitect';

const loop = new DesignLoop(process.cwd(), {
  directive: 'Build a URL shortener',
  outputDir: 'docs/superpowers',
  agentOptions: { backend: 'anthropic', apiKey: process.env.ANTHROPIC_API_KEY },
  resume: false,
  planDepth: 'standard',
  decomposeThreshold: 15,
  maxReviewPasses: 3,
});

await loop.run();

Requirements

• Node.js 18+
• LLM API key for your chosen backend:
  • ANTHROPIC_API_KEY (default backend)
  • OPENAI_API_KEY (for --backend openai or --backend openai-compatible)
• Optional: AUTOARCHITECT_SEARCH_KEY (Tavily API key) — enables live web research. Without it, the CLI falls back to the LLM's training knowledge and logs the fallback in the journal.

Usage

autoarchitect adapts to the kind of input you give it.

From an instruction

# Plugin
/autoarchitect:design-loop "Build a real-time collaborative document editor"

# CLI
npx autoarchitect "Build a real-time collaborative document editor"

From a requirements document

Supports .md, .txt, and .pdf inputs.

# Plugin
/autoarchitect:design-loop docs/requirements.md

# CLI
npx autoarchitect --input docs/requirements.md

Targeting an existing codebase

# Plugin
# "Design a notification system for our app. Target: src/. Requirements: docs/notification-prd.md"

# CLI
npx autoarchitect "Add a notification system" --codebase ./src --input docs/notification-prd.md

Resume an interrupted session

# Plugin
# "Resume the autoarchitect design session"

# CLI
npx autoarchitect --resume

How It Works

autoarchitect runs a structured 7-phase loop, fully autonomous after an optional triage round:

Requirement (instruction / document / codebase)
    │
    ▼
Parse & Understand  — extract what, who, constraints
    │
    ▼
Triage              — 0-3 questions only you can answer (scale? tech? compliance?)
    │
    ▼
════════════════════ AUTONOMOUS FROM HERE ════════════════════
    │
    ▼
Decompose           — design questions across 9 dimensions
    │
    ▼
Research            — web search, codebase scan, document parsing
    │
    ▼
Decide              — pick approach, document reasoning, log alternatives
    │
    ▼
Assemble            — spec (Mermaid diagrams) + plan (superpowers format)
    │
    ▼
Self-Review         — 9 quality gates, auto-fix loop (max 3 passes)
    │
    ▼
Present             — deliver spec + plan + journal, offer execution handoff

Decomposition dimensions

Each requirement is broken into design questions across nine concerns:

| Dimension | What it covers | |-----------|----------------| | Data | Model, storage, access patterns, consistency | | Compute | Sync vs async, resource profile | | Communication | REST, gRPC, events, queues | | Users | Auth, access patterns, personas | | Scale | Users, requests, data volume, growth | | Reliability | Availability, failure modes, recovery | | Security | Threat model, encryption, compliance | | Integration | External systems, brittleness, vendor lock-in | | Operability | Observability, deployment, testing, versioning, maintainability |

Quality gates

Before delivery, every generated design passes nine quality checks:

1. Contradiction — no decision conflicts with another
2. Completeness — every question answered, every component documented
3. Scalability — design holds at stated scale, no hidden bottlenecks or SPOFs
4. Security — auth, authorization, encryption, input validation addressed
5. Feasibility — tech stack can actually deliver the design
6. Spec Format — all 11 required sections present, Mermaid diagrams valid
7. Plan Format — valid superpowers writing-plans format, executable
8. Observability — logs, metrics, traces, SLOs, deployment strategy defined
9. Testability — test strategy covers required layers; design has testability seams

Failed gates trigger an auto-fix loop (up to 3 passes). Anything still unresolved is surfaced as ## Known Limitations in the spec rather than silently dropped.

Auto-decomposition

For large systems (15+ design questions), autoarchitect auto-decomposes into subsystems with a system-level architecture doc and per-subsystem specs.

What You Get

Output files

| File | Purpose | |------|---------| | docs/superpowers/specs/YYYY-MM-DD-<topic>-design.md | Full system design | | docs/superpowers/plans/YYYY-MM-DD-<topic>.md | Step-by-step implementation plan | | docs/superpowers/specs/YYYY-MM-DD-<topic>-journal.md | Decision audit trail |

Spec sections (11 total)

1. Overview
2. Architecture (with Mermaid component diagram)
3. Components
4. Data Model (with ER diagram, when applicable)
5. Key Flows (with Mermaid sequence diagrams)
6. API Contracts (when applicable)
7. Error Handling
8. Security
9. Architectural Decisions (one callout per major fork)
10. Operations — observability (logs/metrics/traces/SLOs), deployment (release strategy, rollback, migrations), testing matrix, versioning, maintainability
11. Known Limitations (only if self-review could not resolve all issues)

Plan format

Plans are in superpowers writing-plans format and directly executable by superpowers:subagent-driven-development or superpowers:executing-plans.

CLI Reference

autoarchitect [options] [directive]

| Flag | Default | Description | |------|---------|-------------| | [directive] | — | System requirement as a positional string | | --input <path> | — | Path to a requirements document (.md, .txt, .pdf) | | --codebase <path> | — | Path to an existing codebase to analyze | | --output-dir <path> | docs/superpowers | Where to write spec and plan | | --backend <type> | anthropic | anthropic, openai, or openai-compatible | | --model <model> | SDK default | Override the model (e.g. claude-sonnet-4-6, gpt-4o) | | --base-url <url> | — | Base URL for openai-compatible (Ollama, vLLM, Together, etc.) | | --search-api-key <key> | $AUTOARCHITECT_SEARCH_KEY | Tavily/Brave key for live web research | | --resume | false | Resume the most recent incomplete session | | --plan-depth <depth> | standard | full, standard, or overview — controls code detail in the plan | | --decompose-threshold <n> | 15 | Question count that triggers subsystem decomposition | | --max-review-passes <n> | 3 | Hard cap on self-review passes | | -v, --verbose | false | Log each tool call and result to stderr |

Backend examples

# Anthropic (default)
export ANTHROPIC_API_KEY=sk-ant-...
npx autoarchitect "Build a chat system"

# OpenAI
export OPENAI_API_KEY=sk-...
npx autoarchitect "Build a chat system" --backend openai --model gpt-4o

# Ollama (local, OpenAI-compatible)
export OPENAI_API_KEY=ollama
npx autoarchitect "Build a chat system" \
  --backend openai-compatible \
  --base-url http://localhost:11434/v1 \
  --model llama3.1

With live web search (Tavily)

export ANTHROPIC_API_KEY=sk-ant-...
export AUTOARCHITECT_SEARCH_KEY=tvly-...
npx autoarchitect "Build a URL shortener with click analytics"

Without a search key the CLI uses the LLM's training knowledge and notes the fallback in the journal. You still get a useful design — just without live research.

Verbose mode

npx autoarchitect "Build a chat system" --verbose

Streams each tool call and result to stderr. Useful for observing long sessions and debugging prompts.

Long-Running Sessions

For large systems that require extensive research, run inside a Ralph Wiggum loop:

/loop /autoarchitect:design-loop "Design a multi-tenant SaaS analytics platform"

The plugin includes a stop hook that keeps the agent alive until the design is complete. State is persisted after every phase transition, so resumption across context window resets is seamless.

To resume a previous session manually:

# Plugin — just ask
"Resume the autoarchitect design session"

# CLI
npx autoarchitect --resume

The agent reads .autoarchitect/sessions/<latest>/state.json and picks up where it left off.

Permissions

autoarchitect uses the following tools during the design loop:

| Tool | Purpose | Required? | |------|---------|-----------| | WebSearch | Research prior art, patterns, trade-offs | Recommended | | WebFetch | Read web pages found during research | Recommended | | Read | Read input documents, existing codebase | Required | | Write | Write spec, plan, session files | Required | | Bash(mkdir *) | Create session directories | Required |

See permissions.md for detailed setup options (Auto Mode or granular allowlist).

CLI safety: the standalone CLI sandboxes all file operations to the project directory — it will reject writes to paths outside the working directory to prevent accidental or malicious file access.

Session Files

Everything lives in .autoarchitect/sessions/<session-id>/:

| File | Purpose | Git tracked? | |------|---------|--------------| | state.json | Machine-readable progress (phase, questions answered, review passes) | No | | design-plan.yaml | Design questions with dependencies, priorities, decisions | No | | journal.md | Running design notes — research, strategy, decisions | Yes (companion to spec) | | research-cache.json | Cached web search results to avoid re-searching | No |

Session IDs use millisecond precision (YYYYMMDD-HHMMSS-mmm) and concurrent sessions that collide on the same millisecond get a numeric suffix — safe for parallel runs.

Development

Repo layout

autoarchitect/
├── .claude-plugin/        # Claude Code plugin manifest
├── .codex-plugin/         # Codex CLI plugin manifest
├── .codex/INSTALL.md      # Manual Codex install steps
├── hooks/hooks.json       # Stop hook keeping long sessions alive
├── skills/                # The pure-markdown plugin (design-loop, research, spec-assembly, self-review)
│   └── design-loop/scripts/check-complete.sh   # Stop-hook helper
├── cli/                   # The standalone TypeScript CLI (published as `autoarchitect` on npm)
│   ├── src/cli.ts         #   Entry point (commander + loop wiring)
│   ├── src/cli-config.ts  #   CLI flag + env validation (pure, testable)
│   ├── src/core/          #   SessionState, DesignPlan, Journal, DesignLoop, tool handler
│   ├── src/agents/        #   Anthropic, OpenAI (+ openai-compatible) backends
│   ├── src/tools/         #   web-search (Tavily), file-ops, document parser (md/txt/pdf)
│   └── tests/             #   vitest unit + integration tests
└── permissions.md         # Granular tool allowlist for CI / locked-down environments

Build and test the CLI

cd cli
pnpm install
pnpm run verify      # typecheck + vitest
pnpm run build       # tsup to dist/ (ESM + CJS + .d.ts)

After a build you can run the CLI from source: node dist/cli.cjs --version.

Cut a release

pnpm run release:patch  # or release:minor / release:major

Under the hood that runs verify → build → bumpp → pnpm publish. bumpp bumps cli/package.json, tags the commit, and pushes; cli/src/version.ts reads the version from package.json so autoarchitect --version and the exported VERSION constant stay in sync automatically.

Debug a session

ANTHROPIC_API_KEY=sk-... node cli/dist/cli.cjs "Design a URL shortener" --verbose

--verbose streams every tool call and its truncated result to stderr. Session state is always persisted after every phase — inspect .autoarchitect/sessions/<id>/ to see exactly what the agent wrote.

Test the plugin locally

Before publishing skill changes, you can install the plugin directly from a local checkout:

/plugin marketplace add /absolute/path/to/autoarchitect
/plugin install autoarchitect@autoarchitect

Re-run the two commands after edits to pick up changes, or use /plugin uninstall first.

Inspired By

• Autolab — question decomposition, research loop, escape/self-review strategies, state tracking, journal pattern
• Labrat — agent-native plugin architecture, lean autonomous loop philosophy
• Superpowers — spec and plan format compatibility, execution handoff workflow
• Karpathy's autoresearch — the original autonomous research-loop pattern

Contributing

Issues and PRs welcome. Please open an issue first for larger changes.

License

MIT © Pawan Paudel