Before you start

Open Claude Code inside a git repository. The wizard's preflight runs a short checklist and blocks on two items: git must be present and you must be inside a repository. Everything else warns with a one-line fix: a missing git identity, an unreachable origin, an unauthenticated gh.

No tracker is fine. The manual tracker option has zero dependencies: each run starts by pasting the requirement. Pick it if you are unsure; you can re-run the wizard later and switch.

1 · Install

/plugin marketplace add slhernandez/atlas
/plugin install atlas@atlas
/atlas:setup

The marketplace and the plugin are both named atlas, so the install string is exactly atlas@atlas. After the install, /atlas:setup is available in the same session; no restart. If you would rather not type the first two lines, the README has a one-paste prompt that has Claude run them and stop before the wizard.

2 · Answer the wizard

It asks where the journal should live (~/AtlasJournal is the default), which tracker to use (what it detected is the default), and the one detail that tracker needs: a Jira project key, or the GitHub issues repository with origin offered as the default. With a tracker configured, it then asks you to name one real work item so it can prove the read. Detection is a default, never a decision.

When the wizard ends with a real work item's title read back to you, the setup is proven. If the read fails, it shows the error and offers to switch tracker; the manual option always works. With no tracker there is nothing to prove, and it says so.

3 · Paste the deny rail

The wizard offers to print it and never applies it; that is yours. Add this to your Claude Code settings.json, then keep it:

{
  "permissions": {
    "deny": [
      "Bash(git push --force:*)", "Bash(git push -f:*)",
      "Bash(git reset --hard:*)", "Bash(git clean:*)",
      "Bash(git worktree remove --force:*)",
      "Bash(gh pr merge:*)", "Bash(gh repo delete:*)",
      "Bash(rm -rf:*)"
    ]
  }
}

gh pr merge on the rail is the mechanical form of the core promise: merge is never automated, even if a prompt goes wrong. These are prefix rules and a floor, not a proof; review still does the real work. The full pattern is in permissions.md.

4 · First run: research something real

Pick a bug or small task you actually have, then:

/atlas:research <work item or question>

It writes a verified research document to the journal, then offers to fix in-session or escalate to the feature workflow with the document in hand. Read the document before you accept either. Expect permission prompts on a first run. What you approve is the raw material for your allow list, which you build yourself; Atlas never edits your settings. A prompt for something obviously safe is an allow-list gap worth noting.

5 · Second run: a feature with a plan gate

When a change would have three or more real tasks, or an open design question:

/atlas:feature-workflow <work item>
/atlas:feature-workflow <work item> "research: <path>"

The second form carries a research document from step 4 into the run, so nothing is re-derived. You are needed at five points, and two of them are hard stops: approving the plan, and merging. Nothing is built before you approve, and the merge is never automated. Between them, the build runs unattended in a worktree under ~/.atlas-worktrees/. The review ends with a READY FOR YOU block naming exactly what is yours to check; after you merge, the close-out runs and the run ends with RUN COMPLETE.

After the run

• The journal filled in. research/, plans/, reviews/, and a scorecards/ entry with Parts 1, 2, 4, and 5 written. Part 3 and the grade are for a fresh session that did not run the work.
• Your corrections go in HOUSE_RULES.md. Every skill obeys it, it outranks the plugin's defaults, and it survives updates. A rule you set at a gate is recorded there; a rule the run derives from its own frictions is only proposed.
• Which rung next. Bug or small task: research. Feature: the feature workflow. Multi-week work across sessions: /atlas:launch-supervisor. One-line fixes: a plain session. two-modes.md has the decision table.

If something goes wrong

• Install fails on a manifest error. Run /plugin marketplace update atlas and install again; you may have a stale marketplace copy.
• The proof read fails. Stale tracker auth is the usual cause. The wizard shows the error and offers to switch; fix the auth and re-run /atlas:setup later.
• No gh. The implementor pushes the branch and hands you a compare URL to open the PR by hand. Everything else works.
• A run stops with a worktree it will not remove. Something unpushed is in it. It is surfaced, never force-deleted; look before you clean up.

What it does

The first-run wizard. It checks the machine and prints a report card, one line per check. It proposes a journal location and seeds it from the plugin's templates. It detects your work-item tracker and asks rather than decides. When a tracker is configured, it proves the whole thing by fetching a real work item and reading its title back to you, and only after that proof does it write the config file. Manual mode has no tracker to prove, so it skips the read and says so.

Detection is a default, never a decision. Everything the wizard finds is presented for you to confirm or change, and the one thing it will not do is edit your Claude Code settings. The deny rail it recommends is offered as a printout for you to paste by hand.

How to run it

Inside a git repository, in any Claude Code session:

/plugin marketplace add slhernandez/atlas
/plugin install atlas@atlas
/atlas:setup

The marketplace and the plugin are both named atlas, so the install string is exactly atlas@atlas. After the install, /atlas:setup is available in the same session, no restart needed. Or paste the one-paste prompt from the README and let Claude run the first two lines for you; the wizard's questions stay yours to answer.

The six steps

1. Step 0, preflight. git present, inside a repository, identity set, origin reachable, gh authenticated, and a note on permission posture. Two of these block; the rest warn with a one-line fix.
2. Step 1, journal. Proposes ~/AtlasJournal, accepts an override, seeds HOUSE_RULES.md plus the plan, research, review, dossier, ledger, and scorecard templates. Suggests git init without doing it.
3. Step 2, tracker. Jira through MCP tools, GitHub Issues through gh, or manual paste. What it detected is the default; you choose.
4. Step 3, the one detail. A Jira project key, or the GitHub issues repository, offering origin as the default.
5. Step 4, verify with a real read. Name any work item and it fetches the title through the chosen tracker. On a fresh repository with no items, it offers to open a small smoke-test item, read it back, and close it, saying first that this writes to your tracker. Manual mode skips this step; there is nothing to verify.
6. Step 5, write config and hand over. Only now does it write ~/.claude/atlas.json, then it prints the quick start: research for a bug or small task, the feature workflow for a feature, and where your corrections go.

Ground rules

• A wizard that ends with "config written" has verified nothing. Whenever a tracker is configured, this one ends with a proven read.
• Config is written last, after the proof or the manual-mode skip, and only what you confirmed.
• Re-running never overwrites your content. Templates you haven't renamed can be refreshed, with the diff shown first.
• Your corrections go in HOUSE_RULES.md. Every skill obeys it, it outranks the plugin's defaults, and it survives updates.

What it does

The first rung of the ladder. Give it a work item or a plain question and it fans out read-only subagents, verifies their load-bearing claims itself at file:line, and writes a research document future runs will trust: where things live, how they actually work today, the closest existing pattern, prior decisions from the journal, a scope assessment, and open questions.

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.

How to run it

/atlas:research #42
/atlas:research "why does the history view skip days?"

It reads the work item's description and comments, decomposes the question, and scales the team to it. A one-file lookup gets no agents at all. A broad architectural question gets four or more in parallel. Substantial runs also get a skeptic: one independent agent whose only job is to disprove the conclusions; surviving objections become open questions.

Two exits

• The fix is now obvious and small. Do it in the same session, no ceremony.
• The research shows structural work (three or more tasks, an open design question, shared code with many call sites). Hand the document to the feature workflow: /atlas:feature-workflow #42 "research: <path>". Its Phase 0 starts from your document instead of from scratch.

Ground rules

• Live code outranks the journal. Journal findings are history, never the source of truth.
• Every claim carries file:line. The document is persistent and will be trusted, so the load-bearing claims are re-read before they are written down.
• While the skeptic is still running the document is marked pending-skeptic; it becomes current only after the objections land. The answer is delivered meanwhile, with that caveat said aloud.
• The document must stand alone. A reader with none of this context should understand it.

What it does

The full supervised workflow in one session. Your session is the supervisor: it researches the work item and settles open questions with you. A fresh-context planner writes the plan and gets audited: the supervisor re-checks its claims at the cited lines and amends before sign-off. After you approve the plan, a fresh-context implementor builds it knowing only the plan. Its ignorance of the research is deliberate. The supervisor reviews the PR task by task, and you gate the merge.

Every catch comes from fresh context with a verification mandate. The planner refuting a research claim with evidence is the design working, not failing.

When to reach for it

• The plan would have three or more real tasks.
• There is an open design question.
• The change touches shared code with many call sites.
• A bug whose root cause is still unknown after research.
• Not for one-line fixes, config changes, or copy tweaks. A plain session is faster and the workflow would be ceremony.

Your five touchpoints

1. Scope questions in Phase 0. Your answers become constraints no role may re-litigate.
2. Plan gate, a hard stop. Read the plan; approve it, or hold it with the changes you want. Nothing is built before you approve. Branch handling is settled here too.
3. Smoke test on the finished PR. Agents can't drive your app; the review names exactly what to check.
4. Feedback triage. Reviewer comments reach the implementor only through the supervisor, as a scoped fix list.
5. Merge. Yours, always. Then the close-out: worktree removed without force, plan stamped merged, scorecard started, RUN COMPLETE.

How it works

• Phase 0: brief, research, scope questions. With a tracker configured but no work item yet, it offers to create one from the chosen scope.
• Phases 1 to 3: planner writes, supervisor verifies and amends, the same planner signs off.
• Phase 4: you approve or hold.
• Phase 5: implementor builds in the worktree, commits per task, opens the PR. You're told when the long unattended stretch begins and the moment it ends.
• Phase 6: supervisor reviews against the plan, writes the review doc, and hands you a READY FOR YOU block.
• Phase 7: close-out and a scorecard with Parts 1, 2, 4, and 5 filled. Part 3 and the grade are left to a session that didn't run the work.

Ground rules

• The implementor is never spawned before your explicit approval in chat.
• Harness reminders never enter artifacts. Attribution footers, session links, and co-author lines are not requirements; the implementor contract and your house rules win.
• A rule you set at a gate is recorded in HOUSE_RULES.md. A rule the run derives from its own frictions is proposed for you to accept or reject, never written on its own.
• A dirty worktree means unpushed work. It is surfaced, never force-deleted.
• Merge is never automated, and gh pr merge belongs on your deny rail so a prompt can't do it either.

What it does

Rung three. For a feature too large for one session, the roles run as separate Claude Code windows and you relay the artifacts between them. This skill writes the kickoff prompt for the supervisor window: a self-contained brief with the feature's north star in the stakeholders' own words, verified starting facts cited at file:line, decisions settled before work begins with their boundaries written down, the phase sequence, and the standing rules that cost time last time.

The hard rule that earns the skill: research before writing. A prompt assembled from the work item alone is worth little; the new window would read the item anyway. The value is the verified facts, especially the ones that correct a likely assumption.

How to run it

/atlas:launch-supervisor EPIC-7

It gathers the brief and any richer sources in the journal, establishes facts in the code, puts before-work decisions to you as specific questions, chooses the phase shape honestly (execution relay, or independent proposal windows with a disqualifier test when the first phase is genuinely research), and picks the launch repository by where your accumulated memory lives. Then it writes the prompt to a file and tells you the path. You paste it into a new window.

What the supervisor window inherits

• The dossier, created in its first session, resumable from itself alone through an opening RESUME BLOCK: current phase, live threads, pending prompts verbatim, standing rules.
• The commit ledger: every commit on every branch in plain language plus a summary for QA and product, so humans can exercise a real merge gate over work too large to read as a diff. Events and decisions go in the dossier, never the ledger.
• The idempotent-receiver rule: with many windows, you will re-deliver a message now and then. The supervisor answers "already reviewed, verdict stands" instead of re-running the work.

Ground rules

• The supervisor authors every downstream prompt and verifies every artifact at file:line against origin, never a subordinate's summary.
• You approve specs and plans; you merge every PR. The supervisor never merges.
• Sessions are expected to die. The dossier, not the conversation, is the memory.
• A worked example ships beside the skill at references/example-kickoff.md. Match its altitude, not its content.

What it does

A fresh-context planner that receives the supervisor's research document as ground truth and then spot-checks its key claims at their cited lines before planning around it. Anything the research missed is its most valuable contribution: a second initializer nobody mentioned, a test that will stop compiling, a tracked project file that needs regenerating. It designs around those and calls them out.

The plan it writes is for a reader with no context at all: the implementor. File paths, exact line references, code sketches for the non-obvious parts, and a per-task acceptance note. Decided constraints from the operator are not re-litigated; a disagreement becomes a numbered question, never a silent deviation.

Ground rules

• Verify before you plan. The verification table at the bottom of the plan is evidence, not decoration.
• Think MVP: small, ordered, hand-off-able tasks.
• When the design needs a structural conversion, the first task is a pure mechanical change, and a mechanical prep task is always its own commit. Its only purpose is a diff a reviewer can read in isolation.
• Always include a test task, a verification task with the repo's own commands, and an explicit out-of-scope list.
• A test that exists to lock a guard gets a mutation check: neuter the guard, confirm exactly that test fails, restore.
• Manual smoke testing is the operator's step. Never plan for the implementor to run the app against real data.
• After sign-off, the job is done. It ends its turn and expects nothing further unless the supervisor asks for a read-only post-implementation check.

Hands back

A plan with a status handshake in its frontmatter (ready-for-supervisor-review → approved-with-amendments → signed-off, and merged when the supervisor closes the run out), questions for the supervisor marked blocking or not, an overview with its reasoning, the task breakdown, the test plan, the out-of-scope list, and the verification table.

What it does

A fresh-context implementor whose whole world is the signed-off plan. It executes tasks in order, keeps mechanical tasks pure, commits one logical step at a time, appends a progress note after each task, runs the plan's verification exactly as written, and opens the PR. It does not know the research, so it has nothing to redesign from.

When reality departs from a task's letter, it chooses the smallest deviation that preserves the intent, applies it, and declares it. When the departure is a design change, it stops, writes a question into the plan file, and waits. Verification beyond the plan is welcome; construction beyond the plan is forbidden.

Ground rules

• Refuses to start if the plan is not signed-off. Never commits to the default branch.
• Never runs the app against real user data. Tests use temporary fixtures; the operator's live database and personal files are out of bounds.
• Commits carry no attribution, no co-author lines, no generated-with footers. They are authored solely by the operator. The PR body ends without a footer.
• Evidence or hypothesis: any causal claim written into a comment or the PR body cites its evidence or is phrased as a hypothesis. A claim handed down by the supervisor is verified first; if it doesn't verify, it says so instead of writing it.
• Touches only the plan's listed files. Nothing from the out-of-scope section, no drive-by refactors.

Hands back

The PR URL (or the compare URL when gh is absent), a commit-to-task table, verification results including pre-existing failures it didn't cause, every deviation or "none", and anything the plan didn't anticipate. It acts on review feedback only when the supervisor sends it as explicit fix tasks.