SWE-ATLAS — a senior AI software engineer for Claude Code

The senior-engineer layer for Claude Code. Explore before you build, clarify only what matters, capture it in living HTML, then hand it to Claude Code's native plan / goal / workflow loop. Fewer tokens, less ceremony, faster to the thing people actually pictured.

npx swe-atlas@latest new-project                 # in your current project
npx swe-atlas@latest new-project my-workspace    # …or scaffold a new folder

One command. Full setup. No copy-pasting prompts every session.

ATLAS is an open-source Claude Code template: a curated set of skills, subagents, slash commands, and engineering conventions that turn Claude Code into a production-grade AI software engineer, with a wireframe-and-prototype workflow in place of heavyweight spec-driven development.

It ships in three CLAUDE.md modes, so you choose how much of the wheel to hand over:

• Vanilla — minimal footprint, no ATLAS identity.
• Collaborative (default) — the full senior-engineer identity with a review-and-commit loop; you stay in the driver's seat.
• Autonomous — the approval loop removed and free-will wired in (alongside super-product-owner and super-ui-ux-design): the skill that lets ATLAS decide for itself on the high-stakes forks — hold real alternatives open, ground each in evidence, refute the winner, then log the call in docs/decision_logs/. That's what lets it one-shot an app and run unattended without going off the rails.

The innovation isn't another spec pipeline — it's giving the agent engineered judgment: a way to make the calls a senior engineer would, on its own, and leave a trail you can audit. (Jump to the full mode comparison →)

---

Claude Code already has the engine. ATLAS helps you discover what to build.

Claude Code now plans before it edits, works toward a goal across turns, runs autonomously with safety checks, and orchestrates fleets of subagents, natively, in the box:

| Native capability | What it does | |---|---| | Plan mode | Reads the codebase and proposes a plan; touches no files until you approve | | /goal | Keeps working across turns until a checked completion condition holds | | Auto mode | Approves its own safe tool calls, blocks destructive ones | | Dynamic workflows | Writes a script that fans out dozens of subagents and cross-checks their findings |

Kick off a workflow — describe the task and ask for a workflow in your own words, or include the keyword ultracode, and Claude writes one for it. Want it always-on? Set /effort ultracode and Claude plans a workflow for every substantive task in the session. (How workflows work →)

That is the execution loop, and it keeps getting better. So ATLAS doesn't try to rebuild it.

What Claude Code still won't do for you is decide what's worth building, prove the shape works before you spend tokens generating it, and leave behind a document you can actually trust. That part is on you. And that part is ATLAS.

_{Auto mode and dynamic workflows are in research preview at the time of writing; plan mode and /goal are generally available.}

---

Why not another spec framework

The popular answer to "make the AI build the right thing" has been to bolt a process framework onto the model — Spec-Driven Development (SDD) and the agent frameworks in the same vein (spec-kit, BMAD, Get Shit Done, and the rest): write exhaustive specifications first, then generate the code from them. A constitution. A spec. A plan. A task breakdown. Five to seven Markdown files and a multi-phase pipeline, most of it produced before a single screen has been seen.

Four things go wrong:

• You plan before you've learned. The requirements, the task breakdown: most of it is a guess made before anyone has seen the thing work. You pay full freight to formalize guesses, build to them task by task, and find out at the end it isn't what anyone pictured. That's premature investment: detailed plans and guardrails poured around an idea nobody has validated yet.
• Text leaves room to disagree. A written spec is open to interpretation. You and the model can read the same paragraph and picture two different screens, and the gap only surfaces once the code exists. Prose is the wrong medium for "do we mean the same thing?"
• Markdown drifts. Keeping spec.md, plan.md, and tasks.md consistent with each other and with the code is its own tax, and plain .md can't even render the wireframe, flow, or matrix it's straining to describe.
• The loop is already native. Spec → plan → tasks → implement is precisely what plan mode, /goal, and workflows now do on their own. Wrapping a framework around the model to make it loop reinvents what ships in the box, at a heavy token premium, and slower, because every step waits on ceremony.

ATLAS takes the opposite bet: do the minimum upfront thinking that actually de-risks the build, make it cheap, fast, and visual, so a human and the model can look at the same thing and agree before a line is written, then hand a clean artifact to the native loop.

---

What ATLAS does instead

1. Explore before you commit

Cheap, throwaway-friendly artifacts that let you see the thing before generating code for it:

• /brainstorm:wireframe: a low-fi wireframe as one self-contained HTML file
• /brainstorm:prototype: a clickable, multi-screen React prototype
• /design:create-design-md: three real design variants you compare in a browser, then lock as DESIGN.md
• or /plan:visual: any non-UI change (refactor, migration, architecture call) as a visual HTML plan — Mermaid diagrams, change map, decision matrices

You validate the shape for the price of a sketch, not the price of a spec, in minutes, not phases. And a picture is the fastest way for a human and a model to agree on what to build: text invites interpretation, a wireframe pins it down.

2. Clarify only the essentials

/plan:create-phase resolves the load-bearing unknowns through targeted Q&A, and stops there. No constitution, no task ledger. The ambiguity that would actually derail the build gets surfaced and answered; the rest stays out of your way.

3. Document in HTML, not Markdown sprawl

A phase is captured as one self-contained HTML document: wireframe, data flow, clarifications, and decision matrices in a single file that opens in any browser. HTML is a far richer canvas than Markdown: real tables, SVG diagrams, annotated code, even sliders you tweak and copy back into a prompt. And people actually read it: a 100-line Markdown plan goes unopened; a shareable HTML link gets clicked. One robust artifact instead of a drift-prone pile of .md, and plan mode builds straight from it.

The Claude Code team makes this exact case in The Unreasonable Effectiveness of HTML. The honest tradeoff (HTML costs more tokens and time to generate than .md) is one ATLAS takes gladly: spend it on the one document that matters, not on seven that drift.

4. Bring senior judgment to every turn

A persistent engineering identity (principles, roles, and conventions) plus a library of skills and agents that load automatically. The model stops reaching for generic defaults and starts behaving like someone who has shipped before.

At the center of that judgment is free-will. On any medium-to-high-stakes fork — picking a stack, designing a schema, deprecating something others depend on — it refuses the first plausible answer: it holds real alternatives open (urge · contrarian · synthesis · precedent · first-principles), grounds each in evidence from the codebase or docs, simulates the blast radius, tries to refute the winner before committing, then logs the call in docs/decision_logs/. And it fires autonomously on mechanical triggers — a fix that failed twice, a new dependency, a migration — so the judgment shows up whether or not you remember to ask for it.

---

Where ATLAS fits

flowchart LR
    subgraph ATL["ATLAS · decide what to build"]
        direction TB
        a1["Explore<br/>wireframe + prototype"]
        a2["Clarify essentials<br/>self-contained HTML phase doc"]
        a1 --> a2
    end
    subgraph CC["Claude Code · build it (native)"]
        direction TB
        b1["Plan mode"]
        b2["goal + auto mode"]
        b3["Dynamic workflows"]
        b1 --> b2 --> b3
    end
    a2 --> b1
    b3 --> v["Verify<br/>ATLAS QA agents + skills"]
    v -.lessons learned.-> a1

ATLAS owns the front of the loop (explore, clarify) and the judgment that runs through all of it; Claude Code owns execution. No overlap, no reinvention.

---

Getting Started

Quick start

# Scaffold into an existing project
cd your-project
npx swe-atlas@latest new-project

# Or scaffold into a new folder
npx swe-atlas@latest new-project my-workspace

The CLI walks you through: CLAUDE.md flavor, your name, project type, which skills to install (interactive checkbox: ↑/↓ move, space toggles, a selects all; none preselected), the DESIGN.md template, browser automation (Playwright MCP or Playwright CLI, isolated or persistent profile), and PostgreSQL, then scaffolds everything, copying each file from this repo as the single source of truth. Piped input still works: the skills picker falls back to comma-separated numbers (* = all) when stdin isn't a terminal.

Pick your CLAUDE.md flavor

| Flavor | What you get | |---|---| | Vanilla | Minimal CLAUDE.md: just NOTES.md and docs/decision_logs/, no ATLAS identity | | ATLAS — autonomous | Full identity, no approval loop, built for unattended runs and one-shotting apps. Auto-installs free-will, super-product-owner, and super-ui-ux-design: the skills that stand in for the missing approval loop. free-will fires on medium-to-high-stakes forks: hold real alternatives open, ground them in evidence, refute the winner, log the decision | | ATLAS — collaborative (default) | Full identity with the partner review/commit loop. You stay in the driver's seat |

Every flavor records important decisions (architecture, library choices, tradeoff calls) in docs/decision_logs/, ADR-style, with the rejected alternatives and the rationale, so future sessions know why, not just what.

Manual setup

git clone --recurse-submodules https://github.com/syahiidkamil/Software-Engineer-AI-Agent-Atlas
cd Software-Engineer-AI-Agent-Atlas

Then run /atlas:get-to-know inside Claude Code.

A typical first loop

/atlas:get-to-know                  # Configure ATLAS for your project
/design:create-design-md            # Lock visual identity via HTML variant prototyping
/brainstorm:prototype               # Validate the idea as a clickable prototype
/plan:create-phase "phase-01-mvp"   # Capture the essentials as a self-contained phase.html
# → switch to plan mode and let Claude Code build from it

Going autonomous

ATLAS is built to hand you the wheel — or take it. When you want it running hands-off:

• Scaffold the autonomous flavor — full ATLAS identi