Atlas · How it works
The factory, on one page
A supervised software factory: three AI roles do the work, you hold the gates, and every durable fact lives in a file. This is the manual. The Deck is the reference, one card per skill and role.
01
The factory map
One spine, two chassis, five places you act, two where nothing moves without you.
Every piece of work enters the same way and passes the same gates. Research is the usual first rung; a change you already understand can go straight to a mode, and a one-file lookup needs no run at all. What differs after that is the bus: in kit mode the roles run as fresh-context subagents inside one session; in manual mode each role has its own window and you carry the artifacts between them, one slice at a time. Nodes with a dotted underline jump to the section that explains them.
02
The ladder
Match the process to the size of the uncertainty, not the size of the diff.
The most-asked question after "what is this" is "when do I use which." Three rungs, one discipline.
Rung one: research first
For bugs and small tasks. /atlas:research takes a work item or a plain question and fans out a read-only team, scaled to the question: a one-file lookup gets no agents, a broad architectural question gets four or more in parallel. It verifies the load-bearing claims itself at file:line, runs a skeptic on substantial questions, and writes a document that stands alone. Two exits: the fix is now obvious and small, so do it in the same session; or the research shows structural work, so hand the document to the next rung and its Phase 0 starts from your findings instead of from scratch.
Why research comes before any fix: the wrong-root-cause trap. Fixing the symptom a bug report names is the most common way assisted bug work goes wrong. Research separates what the report says from what the code does before anyone edits anything.
Rung two: kit mode (single-session)
For work-item-sized features: one plan, one pull request. /atlas:feature-workflow runs the three roles inside one session, unattended between the touchpoints, from work item to an open pull request. Signals it's a kit ticket: three or more real tasks, an open design question, shared code with many call sites, or a bug whose root cause is still unknown after research.
Rung three: manual mode (multi-window)
For feature-sized work that needs a spec gate, spans several slices and weeks, or would not fit one session's context. The same roles run as separate windows and you are the bus. /atlas:launch-supervisor writes the kickoff prompt that boots the supervisor window. Manual mode adds two artifacts: a dossier whose opening block makes the whole feature resumable from disk after any window dies, and a commit ledger that turns weeks of commits into something a reviewer can read as prose.
The cost of the wrong rung
- Kit mode on an epic. The supervisor's context degrades across weeks, then dies mid-feature with the state in its head.
- Manual mode on a ticket. Pure ceremony: four windows and a bus for a change one session handles in ninety minutes.
- No research on a bug. A confident fix to the wrong cause, shipped with tests that lock the wrong behavior in.
- No ladder at all. One chat window for everything: it grades its own homework, forgets Monday's constraint by Tuesday, and gates nothing.
| Signal | Rung |
|---|---|
| Quick lookup, one file | plain session, just ask |
| Bug ticket, small task | research first, then fix or escalate |
| Three or more tasks, a design question, shared code | kit mode |
| Spec gate, multi-slice, weeks | manual mode |
03
The cast
Three roles that check each other. One of you.
Your session. Researches the work item, writes every prompt the other roles see, reviews every artifact against the live code, filters all feedback. Never merges.
Fresh context. Re-verifies the supervisor's research at the cited lines before writing the plan. When it refutes a claim with evidence, that's the design working, not failing.
Fresh context. Builds exactly what was signed off, commit by commit, in an isolated worktree. It never sees the research, so it has nothing to redesign from.
Answer the scope questions. Approve or hold the plan. Smoke-test what agents can't see. Merge, or don't. Judgment stays where judgment lives.
Behind them stands the read-only research team the supervisor fans out: a codebase locator (where things live), an analyzer (how they actually work), a pattern-finder (the closest existing implementation to model on), and two journal agents that surface and read prior research and decisions. They report; they never edit.
The point of the split: every catch comes from fresh context with a verification mandate. The planner re-verifies the supervisor's research. The supervisor reviews a plan and a diff it did not write. The implementor executes without the temptation to redesign. Inside a run, no role grades its own output. Around the run, the grade itself comes from a session that ran none of it.
The roles talk through one file. The plan carries a status handshake in its frontmatter (ready-for-supervisor-review → approved-with-amendments → signed-off → merged), the supervisor's review section, the planner's questions and responses, the implementor's progress notes and declared deviations. Agents exchange file paths, never pasted contents.
04
The gates
Unattended between gates. Never past one.
Five touchpoints per run of the feature workflow (rung one, research, has none; it only writes a document). Two are hard gates that no configuration can remove: plan approval, because nothing is built before it, and merge, because judgment stays with you. Everything between the gates runs at machine speed inside the rails described in the next section.
- Scope. Your answers to the research questions become constraints no role may re-litigate.
- Plan, a hard stop. Read the signed-off plan. Approve it, or hold it and say what to change; the amendments are folded in and the plan comes back. Nothing is built until you approve. Branch handling is settled here too.
- Smoke test. Agents can't drive your app. The review names exactly what to check.
- Feedback triage. Reviewer comments, human or automated, reach the implementor only through the supervisor, as a scoped fix list, never as the whole review.
- Merge, a hard stop. Yours. Then the close-out: worktree removed without force, plan stamped merged, scorecard started, and a RUN COMPLETE message that leaves nothing implicit.
Autonomy is a padded room, not an open door.what the gates are for
05
The doorman
Three layers between an agent and your shell.
The banned list, eight entries: force-push in both spellings, hard reset, git clean, forced worktree removal, gh pr merge, repository deletion, and rm -rf. Refused before they run, no discussion. The merge entry is the mechanical form of the core promise: merge is never automated, even if a prompt goes wrong.
The regulars: reads, searches, your build and test commands. Silent, so agents run at full speed without paging you a hundred times an hour. Build yours from what you actually approve during the first few runs; approvals accumulate.
Everything else prompts. Anything with a blast radius pauses and calls the owner. That's you, and that's the design, not a defect.
Atlas never edits your permission settings. The setup wizard offers to print the recommended deny rail; you paste it. Honest caveat: these are prefix rules, so a flag typed after its arguments evades them. The rail is a floor, not a proof. Judgment and review do the real work. The full text lives in docs/permissions.md.
06
Memory and compaction
The session is expected to die. The work isn't.
A long session gets compacted, and eventually it ends. The design assumption is that nothing important lives in the conversation: the transcript is a workspace, and every durable fact has a file. That is what makes compaction a non-event instead of a loss.
The durable layers
| Layer | What it holds | Written |
|---|---|---|
The journal (~/AtlasJournal by default) | Every research document, plan, review, dossier, and scorecard, outside your repositories | as the work happens |
HOUSE_RULES.md | Your standing rules with their reasons. Every skill reads it first and treats it as senior to the plugin's defaults; updates never touch it | by you, at gates; the run may propose, never write |
| The plan file (kit mode) or the dossier (manual mode) | Per run: the status handshake, amendments, progress notes, deviations. The dossier opens with a RESUME BLOCK: current phase, live threads, pending prompts verbatim | at every handoff and halt |
| Claude Code's own memory | Short pointers the model saves on its own; a signpost to the journal, not a copy of it | when the model judges a fact durable |
The wake sequence
- Read
HOUSE_RULES.md: the rules and their reasons. - Find the run's own file: the plan in kit mode, the dossier in manual mode. Both name the branch, the status, and the next action.
- Read the journal's recent research and reviews on the same subject before trusting anything from memory.
That combination restores the working state without the old transcript. A feature mid-flight resumes from its plan or dossier; a fresh session on a new task starts from the journal and the rules.
Compaction hygiene
- Compact at boundaries: after a work item closes and its files are current, not mid-task.
- Know what is safe to lose: raw tool output and evaluations whose verdicts already live in files, and the mechanics of past work whose pattern is in git history.
- Convert relative dates before writing them down. "Last week" is worthless to the session that reads it next month; a date is not.
07
The quality loop
The factory grades its own runs. Then it tries to break them.
A workflow that only produces merged pull requests tells you nothing about whether it is any good. So every feature-workflow run ends with a scorecard on the same form. Research runs carry a skeptic pass inside the document instead; the multi-session supervisor reads scorecards today and does not yet write one. The run fills in what it can see about itself; Part 3 and the grade are left to a session that did not run the work, which today you launch yourself and point at the file and the PR (a grader skill is planned). Every friction the run produced becomes an edit: to a rule, a template, or an agent definition. Almost every rule in this plugin was bought with a friction.
What the scorecard asks
| Part | What it checks |
|---|---|
| 1 · Process fidelity | Phases in order; the status handshake transitioned correctly; hard gate one held (nothing built before approval); hard gate two held (close-out only after your merge confirmation); roles exchanged paths, not contents; per-task commits; every deviation declared. |
| 2 · Role quality | The planner's verification table filled with real evidence and its refutations listed; the supervisor spot-checking claims itself and reviewing task by task; the implementor building only the plan, with any extra verification leaving no trace in commits. |
| 3 · Outcome quality | Graded by an independent session you launch. A fresh-context re-review of the diff; the findings the run's own review missed; alignment with the work item in both directions; and proof that guard-locking tests actually lock: revert the fix in a scratch worktree and watch the new tests fail. Tests that don't scream when the fix is gone are decoration. |
| 4 · Friction log | Each friction paired with its correction and target file. This is the part that changes the plugin. |
| 5 · Verdict | A grade, plus three honest questions: would a plain session have done this better or cheaper; what did the workflow prescribe that the model would have done anyway (three runs agreeing makes a component a retirement candidate, but gates, independent review, and rails never qualify); and what does the run say about the system itself. |
Zero refutations on a research-heavy run is a yellow flag, not a green one.the scorecard, on what healthy disagreement looks like
The flywheel
Frictions go into the scorecard. Scorecard entries become house rules. Rules you set at a gate are recorded with their reasons; rules the run derives from its own frictions are proposed for you to accept or reject. Either way, the factory that built your last feature is not the one that builds your next. And the redundancy question lets it shrink as well as grow: hand-coded structure that the model no longer needs is retired on evidence, while the parts that exist for people stay.
08
What's in the box
Four skills, seven agents, seven templates, one file that outranks them all.
| Piece | What it is |
|---|---|
/atlas:setup | The first-run wizard: preflight, journal, tracker, proven read, config. Never touches your settings. |
/atlas:research | Rung one. A verified research document, then fix in-session or escalate. |
/atlas:feature-workflow | Rung two. The three roles in one session, two hard gates, one PR. |
/atlas:launch-supervisor | Rung three. Writes the prompt that boots a supervisor window for manual mode. |
| workflow-planner · workflow-implementor | The two role agents, described on their cards. |
| The research team | Codebase locator, analyzer, pattern-finder; journal locator and analyzer. Read-only. |
| Templates | Plan, research, review, dossier, ledger, scorecard, and the house-rules seed. Copied into your journal at setup. Plugin-owned templates can be refreshed later with the diff shown first; your own files are never overwritten. |
HOUSE_RULES.md | Your standing rules. Senior to everything above. Survives every update. |
Install is three commands in any Claude Code session inside a git repository. The marketplace and the plugin are both named atlas:
/plugin marketplace add slhernandez/atlas
/plugin install atlas@atlas
/atlas:setupThen the Deck for one card per skill and role, two-modes.md for the decision table, and the README for the journal layout and the one-paste install. Honest v0.1 boundaries: the fresh-machine validation ran on GitHub Issues, so the Jira tracker path follows the same steps but has had no live run yet; without gh, pull requests degrade to a push plus a compare URL you open by hand; and it is opinionated on purpose.