A Claude Code layer that argues against writing the spec first

One npx command writes the .claude directory

Installation is two forms of the same line, and the distinction is whether you already have a project:

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

The first scaffolds into the directory you are standing in, the second creates a named folder and scaffolds there. The summary the README gives is one command, full setup, no copy-pasting prompts every session.

What gets installed is a curated set of skills, subagents, slash commands and engineering conventions, and the published npm file list shows exactly where they live: .claude/agents/, .claude/commands/, .claude/hooks/, .claude/rules/ and .claude/skills/, alongside a claude_md_variants/ directory, the installer at bin/install.js, and two hooks reference documents under docs/external-information/.

Three files in that list tell you what the template expects from your environment. A .mcp.json declares MCP servers, a .playwright/cli.config.json declares a browser automation config, which matches the React prototypes the workflow produces, and a NOTES.md is shipped as part of the package rather than generated for you.

Three CLAUDE.md modes, and one removes your veto

The template ships in three flavours of CLAUDE.md, and the choice is how much of the wheel you hand over.

Vanilla is a minimal footprint with no ATLAS identity at all. Collaborative is the default: the full senior-engineer identity with a review-and-commit loop, with you staying in the driver's seat. Autonomous removes the approval loop entirely.

What Autonomous adds is named in the README: free-will, alongside super-product-owner and super-ui-ux-design. Free-will is the skill that lets the agent decide for itself on the high-stakes forks. The described behaviour is specific: hold real alternatives open, ground each in evidence, refute the winner, then log the call in docs/decision_logs/.

That last clause is what makes the mode defensible rather than merely reckless. The judgement is autonomous but the record is not, so a reviewer can read the reasoning after the fact rather than approving it before.

The README's own framing of the project is worth quoting as a position rather than a feature list: the innovation is not another spec pipeline, it is giving the agent engineered judgment and leaving a trail you can audit.

The argument is against five Markdown files written too early

ATLAS names its opposition, which is unusual and useful. The target is Spec-Driven Development and the agent frameworks in the same vein, with spec-kit, BMAD and Get Shit Done given as examples. The SDD shape it describes is a constitution, a spec, a plan and 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 failures are listed, and each one is specific enough to argue with.

You plan before you have learned, which is framed as premature investment: detailed plans and guardrails poured around an idea nobody has validated. Text leaves room to disagree, since you and the model can read the same paragraph and picture two different screens, and the gap only surfaces once code exists. Markdown drifts, because keeping spec.md, plan.md and tasks.md consistent with each other and with the code is its own tax, and plain Markdown cannot render the wireframe it is straining to describe. And the loop is already native, since spec to plan to tasks to implement is what plan mode, /goal and workflows now do on their own.

The conclusion drawn from the fourth point is the design constraint for everything else: wrap a framework around the model and you pay for it in tokens and in waiting.

Four commands produce something you can look at

The replacement for the spec phase is a set of commands that emit artifacts a browser can open.

/brainstorm:wireframe produces a low-fi wireframe as one self-contained HTML file. /brainstorm:prototype produces a clickable, multi-screen React prototype. /design:create-design-md produces three real design variants you compare in a browser and then lock as DESIGN.md. And /plan:visual covers the non-UI cases: a refactor, a migration or an architecture call rendered as a visual HTML plan with Mermaid diagrams, a change map and decision matrices.

The claim attached to these is that you validate the shape for the price of a sketch rather than the price of a specification, in minutes rather than phases, and that a picture is the fastest way for a human and a model to agree on what to build.

The third command is the one with a lasting artifact, since DESIGN.md survives the session. The React prototype option is the most expensive of the four and the one most likely to turn into work you now own, which is worth knowing before you generate three screens of clickable UI to answer a layout question.

/plan:create-phase asks only the questions that would derail the build

Clarification is the step the template is most careful about, and the wording is deliberate: /plan:create-phase resolves the load-bearing unknowns through targeted Q&A, and stops there. No constitution, no task ledger.

That is the direct counterpart to the five-file pipeline it is arguing with. A constitution is a document you write before you know what you are building, and a task ledger is a document you maintain while building. The template's claim is that the only ambiguity worth resolving is the ambiguity that would actually derail the build.

The output is where the second design decision lands. A phase is captured as one self-contained HTML document containing the wireframe, the data flow, the clarifications and the decision matrices in a single file that opens in any browser. The argument made for HTML is a canvas argument: real tables, SVG diagrams, annotated code, and sliders you can tweak and copy back into a prompt.

One phase, one file, no drift between documents is the mechanism. Whether a single large HTML file ages better than several small Markdown files is a question the project is betting on rather than proving.

It sits on the plan, goal and workflow loop already in the box

The template explicitly refuses to rebuild the execution loop. Claude Code's own capabilities are listed first: plan mode, which reads the codebase and proposes a plan and touches no files until you approve; /goal, which keeps working across turns until a checked completion condition holds; auto mode, which approves its own safe tool calls and blocks destructive ones; and dynamic workflows, which write a script that fans out dozens of subagents and cross-checks their findings.

Workflows are kicked off by describing the task and asking for one in your own words, or by including the keyword ultracode, and /effort ultracode makes Claude plan a workflow for every substantive task in the session.

Two of those four are qualified. The README notes that auto mode and dynamic workflows are in research preview at the time of writing, while plan mode and /goal are generally available. Since two of the three CLAUDE.md modes are described against that surface, that caveat is load-bearing rather than a footnote.

What the template claims Claude Code will not do is decide what is worth building, prove the shape works before tokens are spent generating it, and leave behind a document you can trust. Everything in the package exists to fill one of those three gaps.

The npm manifest is the real documentation

Because this is a template rather than a library, the published file list tells you more than the feature list does. Alongside the .claude subdirectories and the installer, the package ships misc/self/, misc/archive/ and misc/images/, the claude_md_variants/ directory that holds the three CLAUDE.md modes, the hooks guide and hooks reference, repos/, and a gitignore copied in at pack time.

The packaging scripts explain that last item. prepack copies .gitignore to a file named gitignore so npm does not drop it, and postpack removes it again, which is a small piece of care that tells you the author has published this more than once.

Other details worth having: the package is swe-atlas at version 2.6.4 under MIT, authored by Syahiid Kamil, with postversion set to push tags. The repository itself keeps a .gitmodules file, a NOTES.md, a docs/ directory and a neuron-activation.gif.

On cadence, v2.6.4 shipped on 2026-06-25 after v2.6.3 on 2026-06-18 and v2.6.2 on 2026-06-17, and the last push was on 2026-06-25. One caveat on this review: the README is cut off partway through the section on documenting in HTML, so the later parts of the workflow are worth reading in the repository.

Editorial conclusion

Adopt swe-atlas if your team keeps re-pasting the same prompts into Claude Code and your spec documents are written before anyone has validated the shape, since the wireframe-first workflow and the HTML phase document are the parts that change how a session starts. Do not adopt it in Autonomous mode on a regulated or client codebase, because that mode removes the approval loop and hands high-stakes calls to a skill called free-will. Verify first that your Claude Code version has the native features it builds on, since auto mode and dynamic workflows are described as being in research preview.

Frequently asked questions

Official sources

1. Issues
2. README
3. Releases
4. syahiidkamil/Software-Engineer-AI-Agent-Atlas on GitHub