Why ATW?

| Capability | What it changes | | --- | --- | | A task record with six stages | Every task moves through discover → specify → slice → implement → accept → completed. The stage lives in task.json, and a per-turn hook injects that stage's rules into the session — so the AI knows where it is without being told again. | | Four stops, all yours | Everywhere else the AI advances on its own. At four points it must stop and wait for you: creating the task, confirming the spec, starting each ticket, and accepting the result. | | Auto-injected specs | Write conventions once in .atw/spec/, then let ATW inject the relevant context into each session instead of repeating yourself. | | One ticket at a time | Work is sliced into tickets with explicit dependencies. Exactly one is doing; two at once is a broken state, not a choice. | | Project memory | Journals in .atw/workspace/ preserve what happened last time, so each new session starts with real context. atw mem searches conversation history across hosts. | | Team-shared standards | Specs and tasks live in the repo. Workspace journals stay per-developer, so two people on the same repo don't collide. | | Multi-platform setup | Bring the same ATW structure to 22 AI coding platforms instead of rebuilding your workflow per tool. |

Prerequisites

• Node.js >= 18.17
• Python >= 3.9

Quick Start

# 1. Install ATW
npm install -g @chinhae/atw-cli@latest

# 2. Initialize in your repo
atw init -u your-name

# 3. Or initialize with the platforms you actually use
atw init --cursor --opencode --codex -u your-name

Set Up a Project

atw init writes the files. Two one-time steps make them useful. Order between them doesn't matter; the AI does most of the work in both.

1. Run /atw-init-repo. Records three things the engineering skills assume: where issues live, the triage label vocabulary, and where domain docs go. Output is three files under docs/agents/, read by atw-spec, atw-tickets, atw-triage, atw-map, atw-code-review and atw-research. Takes a few minutes. You must run it yourself — the AI cannot invoke this one.

2. Fill .atw/spec/. Init leaves the spec files as empty placeholders, so review sub-agents have no conventions to match and write generic code. Two ways in — pick one, they do the same job:

• python3 ./.atw/scripts/task.py start 00-bootstrap-guidelines, then tell the agent to start that task. Run the command from inside an AI session so the session identity reaches the script. Checklist-driven: it asks whether an existing CLAUDE.md, .cursorrules or CONTRIBUTING.md can be imported before it reads any source.
• /atw-spec-bootstrap — the same work as a skill. One agent analyses the codebase and writes the docs.

Close it out with task.py finish, then task.py archive 00-bootstrap-guidelines. After the archive, teammates who run atw init get a 00-join-<slug> onboarding task instead of the bootstrap one.

Then commit .atw/, docs/agents/, .gitattributes and AGENTS.md. Teammates should clone your conventions, not an empty scaffold.

Neither step is mandatory — triage, tasks and specs all work without them. What you give up is concrete: sub-agents matching your patterns, and skills knowing where issues and research notes belong.

How It Works

ATW runs three phases over a six-stage task record:

Phase 1: Plan     discover → specify → slice (optional)
Phase 2: Execute  implement — one ticket at a time
Phase 3: Finish   accept → completed

Phase 1 — Plan. /atw-askme works through open requirements one question at a time. When the work is large and the route is unclear, /atw-map scans the territory first and files decision tickets; /atw-research handles external unknowns and /atw-prototype handles design questions that need a throwaway build. /atw-spec turns the findings into prd.md — the requirements, constraints, and acceptance criteria everything downstream is checked against. When the work won't fit one session, /atw-tickets slices the confirmed spec into issues/NN-*.md.

Phase 2 — Execute. One ticket at a time, claimed from the ready frontier. Each ticket runs a closed chain that must not be broken up from the outside: implement → run tests → review → handle findings → write learnings back to spec → commit. Review is an atw-review sub-agent reading two axes, project standards and the task's own spec, and both of its reports reach you verbatim — including when the verdict is "nothing found".

Phase 3 — Finish. Read-only. The acceptance criteria in prd.md get walked one by one with evidence, and nothing new gets opened — things you notice become tickets or a follow-up task. After you accept, the task archives.

Not every request needs a task

| Path | Route | | --- | --- | | Simple | No task. Just do it, skip ATW for this session. | | Medium | Task → discover → specify → implement | | Complex | Task → map → specify → slice into tickets → implement each |

The threshold is deliberately not a file count — changing two files can be a typo fix or an auth rewrite. When unsure, go one path up: the cost of going up is one more prd.md, and the cost of going down is discovering mid-build that there is no record, no spec, and no review baseline.

The four stops

Outside these four, the AI advances stages on its own. It does not stop to ask "shall we move on?".

| Where | Whose call | | --- | --- | | Before a task is created | Does this work deserve a record | | After prd.md is written | Is the spec right | | Before each ticket starts | You run /atw-implement; the AI cannot invoke it | | Before archiving | "This is done" |

What lands in your repo

.atw/
├── spec/                    coding guidelines, by package and layer
├── tasks/MM-DD-<slug>/
│   ├── task.json            stage, branch, metadata
│   ├── prd.md               the spec
│   ├── map.md               territory map — complex path only
│   ├── issues/NN-*.md       implementation tickets (Impl / Blocked by)
│   ├── research/<topic>.md  research notes, one file per topic
│   └── check.jsonl          which specs the review sub-agents read
├── workspace/<you>/         per-developer session journals
├── workflow.md              the workflow the AI follows, in your repo
└── scripts/                 the Python that reads and writes all of it

workflow.md is a file in your project, not something baked into the CLI — atw workflow switches it between the built-in native template and anything published to the workflow marketplace, and editing it changes what the AI actually does.

Skills and sub-agents

26 skills install into every configured platform. The ones you reach for daily:

| Skill | For | | --- | --- | | /atw-askme | fuzzy requirements, one question at a time (/atw-askme-with-docs when the answer is in project docs) | | /atw-map | large scope, unclear route — scans breadth-first and stops itself if it finds no fog | | /atw-research | external or third-party unknowns | | /atw-spec | write or revise prd.md | | /atw-tickets | slice a confirmed spec into tickets | | /atw-implement | run one ticket's full chain — you invoke it, the AI can't | | /atw-diagnosing-bugs | the same bug got fixed more than once | | /atw-update-spec | promote a learning back into .atw/spec/ | | /atw-channel | multi-agent collaboration over a durable local event log |

Three commands sit alongside them: /atw-start loads session context on platforms that have no session-start hook, /atw-continue resumes the current task at the right step, and /atw-finish-work archives the task and writes the session journal. Nothing is committed there — the implement chain commits per ticket, long before a task reaches it.

/atw-implement writes the code in your main session; atw-review sub-agents review the diff so the review does not share the implementer's context.

CLI

atw init          # set up this repo, optionally per-platform
atw platforms     # show which platforms are configured here
atw update        # pull new template bodies into this repo
atw workflow      # list or switch the .atw/workflow.md template
atw upgrade       # upgrade the CLI itself
atw mem           # search conversation history across Claude Code, Codex, OpenCode, Pi
atw channel       # multi-agent collaboration runtime
atw ablate        # temporarily remove ATW; atw restore puts it back
atw uninstall     # permanent removal

FAQ

Those files are useful entry points, but they tend to become monolithic, and they say the same thing on every turn regardless of what you are doing. ATW adds a stage the work is actually in, specs scoped to the package and layer you are touching, a spec you confirmed before implementation started, and four points where the AI has to stop and ask you.

No. ATW is a project layer that works across multiple coding agents and IDEs. Run atw platforms to see what is configured in the current project.

A per-turn hook reads the task's stage and injects that stage's rules into the session. In discover those rules say not to write code and not to create tickets yet; in accept they say read-only. The rules come from the [workflow-state:*] blocks in your project's .atw/workflow.md, so they are editable — and when the hook can't find them, it says so visibly instead of failing quietly.

Both. Solo developers use it for memory and repeatable workflow. Teams get the larger benefit: shared standards, task boundaries, reviewable context, and platform portability.

No. Many teams start by letting AI draft specs from existing code and then tighten the important parts by hand. /atw-update-spec promotes learnings back as you go. ATW works best when you keep the high-signal rules explicit and versioned.

Yes. Personal workspace journals stay separate per developer, while shared specs and tasks stay in the repo where they can be reviewed and improved like any other project artifact.

Yes. atw ablate temporarily removes all supported project-owned ATW surfaces after creating a verified recovery transaction outside the project. Start a fresh agent session for the comparison, then run atw restore to recover the exact prior state. Use --dry-run to preview either operation. The private recovery transaction includes exact .atw task, spec, and workspace bytes, which may contain user-authored sensitive text, and is kept until restore verifies successfully.

This is different from atw uninstall (permanent removal) and ATW_HOOKS=0 (hooks only). Ablation does not launch agents, manage worktrees, hide Git changes, or remove the global CLI, channel logs, or host transcripts. If a managed path changes while ablated, restore refuses all writes until the conflict is resolved.