@chinhae/atw-cli 0.3.6 → 0.4.0

package/dist/templates/atw/workflow-general.md

@@ -0,0 +1,554 @@
+# General Workflow
+
+For work that is not code: writing, research, organizing material, planning.
+
+---
+
+## Core Principles
+
+1. **The user talks, you run the process** — they say what they want in their own words. Creating a task, moving it along, archiving it and writing the journal are yours to do. Never ask the user to type a command to move the work forward.
+2. **Agree before doing** — for anything beyond a small request, write down what will be done, what will not be done, and what counts as done, and let the user confirm it before you start.
+3. **Check against what was agreed** — when the work is finished, go through what counts as done item by item, with evidence. The user decides whether to accept it.
+4. **Two decisions are the user's, and only two** — whether what you wrote down is right, and whether the result is accepted. Everything in between is yours to advance without asking.
+5. **Write it to files** — tasks, conventions and the journal outlast the conversation; what was only said in chat is gone in the next session.
+
+---
+
+## ATW System
+
+### Developer Identity
+
+On first use, initialize your identity:
+
+```bash
+python3 ./.atw/scripts/init_developer.py <your-name>
+```
+
+Creates `.atw/.developer` (gitignored) + `.atw/workspace/<your-name>/`.
+
+### Noob Mode
+
+For a user who is not an engineer. While it is on, every reply in every stage is in plain language: terms explained where they appear, each action explained before it happens (what, why, how risky, what approving or declining leads to), errors and results retold with what they affect and what comes next. The full rules are `/atw-noob-mode`.
+
+```bash
+python3 ./.atw/scripts/noob_mode.py on|off|status
+```
+
+The user switches it by saying "开启小白模式" / "关闭小白模式" or running `/atw-noob-mode`; the skill runs the script. Their choice — on or off — is one line in that user's own `.atw/.developer`, so it is personal and never committed. A user who has never chosen gets the project mode's default: on when `.atw/config.yaml` says `mode: general`, off when it says `mode: dev` or has no `mode` entry. Switching off is recorded as a choice, so neither the default nor a change of project mode turns it back on; `status` says which of the two is in effect. It changes how the AI talks to the user — not the stages, the stops, or what goes into task files.
+
+### Conventions
+
+`.atw/spec/conventions.md` is the one place this project keeps what the user asked for more than once: how they want things written, named, laid out or checked, and what they do not want. Its content is handed to you at the start of every session inside `<conventions>`. Follow it in every reply. You also add to it yourself — see "Keeping Conventions" below.
+
+### Task System
+
+Work that is more than a small request gets a task: a directory under `.atw/tasks/`.
+
+```
+.atw/tasks/MM-DD-<slug>/
+├── task.json   task record (status and metadata)
+├── prd.md      what was agreed: what will be done, what will not, what counts as done
+└── research/   notes from looking things up, one file per topic
+```
+
+`task.json.status` moves through five stages in this workflow:
+
+```
+discover → specify → implement → accept → completed
+```
+
+A sixth status, `slice`, belongs to the `dev` workflow. A task only carries it here when the project was switched over from `dev`; step 1.4 says how to continue one.
+
+```bash
+python3 ./.atw/scripts/task.py create "<title>" --description "<one line>" --slug <name>
+python3 ./.atw/scripts/task.py set-status <task> <status>            # move between stages
+python3 ./.atw/scripts/task.py start <task>                          # make it this session's current task; discover / specify / slice → implement
+python3 ./.atw/scripts/task.py resume <task>                         # make it this session's current task; its status stays as it is
+python3 ./.atw/scripts/task.py current --source                      # this session's current task
+python3 ./.atw/scripts/task.py list --mine                           # open tasks and their status
+python3 ./.atw/scripts/task.py archive <task> --skip-branch-validation   # → completed, moved to archive/{year-month}/
+```
+
+**Current task**: each session has its own. `task.py create` makes the new task this session's current task; `task.py start` and `task.py resume` do the same for an existing one — `start` also moves a task still at `discover`, `specify` or `slice` on to `implement`, `resume` changes nothing else. `task.py set-status` changes the stage and leaves the current task alone. A new session starts with none. The reminder you get on every turn is chosen by the current task's status.
+
+### Workspace System
+
+A journal of sessions, kept per person under `.atw/workspace/<developer>/`, so a later session can see what was done.
+
+```bash
+python3 ./.atw/scripts/add_session.py --title "<title>" --summary "<what was done>"
+```
+
+### Context Script
+
+```bash
+python3 ./.atw/scripts/get_context.py                            # who you are working with, current task, open tasks, conventions
+python3 ./.atw/scripts/get_context.py --mode phase               # the Phase Index below
+python3 ./.atw/scripts/get_context.py --mode phase --step <X.Y>  # one step in full
+```
+
+---
+
+<!--
+  WORKFLOW-STATE BLOCK CONTRACT (read this before editing the tag blocks below)
+
+  The [workflow-state:STATUS] blocks inside the ## Phase Index section are the
+  only source of the per-turn `<workflow-state>` reminder: the per-turn hook of
+  every platform looks a block up by the current task's status and injects its
+  body. The scripts hold no fallback text. When a block is missing the reminder
+  degrades to "Refer to workflow.md for current step."
+
+  STATUS is matched against `task.json.status` verbatim, so the six stage tags
+  must stay spelled `discover` / `specify` / `slice` / `implement` / `accept` /
+  `completed`.
+
+    [workflow-state:no_task]    → the session has no current task
+    [workflow-state:task_error] → the current task's record cannot be read
+    [workflow-state:noob_mode]  → appended to every reminder while this user has noob mode on; not a status
+    [workflow-state:discover]   → step 1.1 (the status `task.py create` writes)
+    [workflow-state:specify]    → steps 1.2–1.3
+    [workflow-state:slice]      → step 1.4; only a task brought over from `dev` carries it
+    [workflow-state:implement]  → Phase 2 (`task.py start` sets it)
+    [workflow-state:accept]     → Phase 3, up to the archive
+    [workflow-state:completed]  → the archive was interrupted; task still under .atw/tasks/
+
+  The reminder is the only thing the AI hears on every turn. Anything it must
+  do at a status has to be said in that status's block, not only in the step.
+
+  Keep comments out of the Phase Index section itself: platforms without a
+  session-start hook print that section as it is.
+
+  The heading `## Phase Index`, the heading `## Phase 1: Plan` and the step
+  headings `#### X.Y` are compared literally by the scripts.
+  `packages/cli/test/scripts/workflow-structure.test.ts` guards them.
+
+  A step ends at the next line that starts with `#### ` or `## `, or that is
+  `---`. Keep such lines out of a step's body, code examples included, or the
+  step comes back cut short.
+-->
+
+## Phase Index
+
+```
+Phase 1: Plan   → talk it through, write down what was agreed, the user confirms it
+Phase 2: Do     → do the work that was agreed
+Phase 3: Finish → check the result against what was agreed, the user accepts it, then archive and journal
+```
+
+### Small Request or Task
+
+You decide this yourself. Do not ask the user whether to create a task.
+
+| The request | What you do |
+|---|---|
+| Small — you can finish it in this reply and the user can judge the result at a glance: a question, a lookup, a quick fix to a sentence, a rename | Just do it. No task, no record. |
+| Anything larger — several steps, more than one sitting, a result the user will keep or pass on (a document, a plan, a report, a reorganized folder), or "done" is not obvious | Create a task yourself, right away, and say so in one sentence. Then Phase 1. |
+
+When unsure, create the task. The cost is a few lines for the user to confirm; the cost of skipping it is work that drifts with nothing written down to check it against.
+
+### The Two Stops
+
+Outside these two, you advance on your own. Do not stop to ask "shall I go on?", and do not ask the user to run anything.
+
+| # | Where | Whose call |
+|---|---|---|
+| ① | After you have written down what was agreed | Is it right — the user's |
+| ② | After you have checked the finished work against it | Is it accepted — the user's |
+
+### What To Do At Each Status
+
+| Current task | What you do | Step |
+|---|---|---|
+| none | Small request: do it. Larger: create a task. Earlier unfinished work the user wants to go on with: pick it up (below). | 1.0 |
+| `discover` | Ask until what the user wants is clear, then move to `specify`. | 1.1 |
+| `specify` | Write `prd.md`; stop ①. Once confirmed, start the work. | 1.2, 1.3 |
+| `slice` | A task brought over from `dev`. Cut no tickets; carry on from its `prd.md`. | 1.4 |
+| `implement` | Do the work, then move to `accept`. | 2.1 |
+| `accept` | Check item by item; stop ②. Once accepted, tick what was met, archive and write the journal. | 3.1, 3.2 |
+| `completed`, still under `.atw/tasks/` | The archive was interrupted. Run it again. | 3.2 |
+
+### Picking Up Unfinished Work
+
+A new session starts with no current task, even when earlier work is unfinished — the session context says how many tasks are still open. When the user says "continue" / "接着做", or what they ask for clearly belongs to an open task, pick that task up instead of creating a new one:
+
+```bash
+python3 ./.atw/scripts/task.py list --mine      # open tasks and their status
+python3 ./.atw/scripts/task.py resume <task>    # make it this session's current task
+```
+
+Use `resume`, not `start`: `resume` leaves the task at the status it had, while `start` would move a task still at `discover`, `specify` or `slice` on to `implement` — the work would read as started before it was agreed. Then read its `prd.md`, tell the user in a sentence or two where things stand, and continue from the table above. With several open tasks and no way to tell which one is meant, ask which.
+
+### Keeping Conventions
+
+When the user corrects you, or states a preference for the second time — how to write, name, lay out or check things, or what they do not want — write the lasting rule behind it into `.atw/spec/conventions.md` in the same turn: one short line under `## 说定的事 / What we agreed`. Do not ask first; tell them in one sentence that you noted it, so they never have to say it again.
+
+A correction that only concerns the piece of work in hand (a wrong date, a missing section) is not a convention: fix the work. If it changes what was agreed, that goes through step 2.2 first.
+
+### Looking Things Up
+
+Look things up yourself, in this conversation. `atw-research` is written to hand the reading to a background agent; in this workflow you do that agent's job yourself — primary sources, each claim with its source, the notes saved in `{TASK_DIR}/research/`. A small lookup with no task has no notes to keep: the answer and where it comes from go in the reply. With `atw-research` too, do not hand the looking-up to a background agent or any other helper.
+
+A helper works out of sight and may not be allowed the tools it needs; the user waits a turn and gets nothing. Looking yourself, you know in the same reply whether it worked.
+
+If it comes back with nothing — the tool is blocked, or no source you can trust says it — tell the user in the same reply and offer other ways to go on. Do not leave them waiting for a result that is not coming. For a blocked tool, see "When A Tool Is Blocked".
+
+### When A Tool Is Blocked
+
+The platform may refuse a tool you want: going online, running a program, writing a file. When a tool you want is blocked, tell the user what you cannot do and why, offer ways to go on that do not need that tool, and wait for them to choose.
+
+Do not ask them to type a slash command, or anything else meant for the platform: in this workflow the user never types a command to move the work forward. And do not edit, or offer to edit, the platform's permission or settings files — not even when they ask you to sort it out. Access is not yours to give yourself: say so, and offer again the ways that do not need the tool.
+
+This is not a third stop. It is a question you cannot go on without, like the ones in step 1.1, and it only comes up when a tool is blocked. Before the work is agreed, the user's answer settles it. Once the work is agreed, their answer is not yet a confirmation. Going on another way changes what was agreed: what they choose goes through step 2.2 like any other change, before you act on it.
+
+### Before You Delete Or Overwrite A File
+
+Before you delete any file in the user's folder, or overwrite a file you did not create in this piece of work, tell the user which file, why, and whether it can be got back afterwards, and wait for them to agree. This holds whether noob mode is on or off.
+
+Their agreement has to be to the deleting or the overwriting itself. "Replace it with the new version" or "tidy this up" is not agreement to delete or overwrite: they agreed to a result, and may not know that a file goes with it. If a file is to go or be written over, say so in those words and name the file. What they have clearly agreed to, do not ask again.
+
+Updating a file you made in this piece of work, to what was agreed, needs no asking; deleting it does. A draft you wrote sits in the user's folder like any other file, and they may still want it. Files under `.atw/` that this workflow manages are outside this: task records, conventions, the journal.
+
+Asking this is not a third stop. Like a blocked tool, it is a question you cannot go on without, and it only comes up when a file would be deleted or overwritten. Everything else in the work you still advance on your own.
+
+### Skills
+
+Six skills come with this workflow. Use the first four yourself when the situation calls for one; the last two start only when the user types them.
+
+- `atw-interview` — ask until what the user wants is clear. Yours to use in `discover`, without being told.
+- `atw-research` — look up outside facts from sources that can be trusted; keep the notes in `{TASK_DIR}/research/`. You do the looking-up yourself (see "Looking Things Up").
+- `atw-session-insight` — find what was said or decided in earlier conversations.
+- `atw-noob-mode` — the plain-language rules; also when the user says "开启小白模式" / "关闭小白模式".
+- `/atw-askme` — the user asking to be questioned about a plan. It leads to the same questioning as `atw-interview`.
+- `/atw-handoff` — the user asking for a handoff document for another session.
+
+[workflow-state:no_task]
+No current task. Decide from the request itself; do not ask the user whether to create a task.
+Small — you can finish it in this reply and the user can judge the result at a glance: just do it. No task, no record.
+Anything larger — several steps, more than one sitting, a result the user will keep, or "done" is not obvious: run `task.py create "<title>" --description "<one line>" --slug <name>` yourself now, tell the user in one sentence that you are keeping a record of this, and continue in discover. When unsure, create it.
+The user wants to go on with earlier unfinished work ("continue" / "接着做", or the request belongs to an open task): run `task.py list --mine`, then `task.py resume <task>` — not `start`, which would move a task that is still being discussed on to `implement`. The task stays at the status it had; continue from there. Do not create a second task for the same work.
+Look things up yourself, in this conversation. With `atw-research` too, do not hand the looking-up to a background agent or any other helper: do the reading yourself. If it comes back with nothing, tell the user in the same reply and offer other ways to go on.
+When a tool you want is blocked, tell the user what you cannot do and why, offer ways to go on that do not need that tool, and wait for them to choose. Do not ask them to type a slash command, and do not edit, or offer to edit, the platform's permission or settings files — not even when they ask you to sort it out.
+Before you delete any file in the user's folder, or overwrite a file you did not create in this piece of work, tell the user which file, why, and whether it can be got back afterwards, and wait for them to agree. "Replace it with the new version" or "tidy this up" is not agreement to delete or overwrite. What they have clearly agreed to, do not ask again. Updating a file you made in this piece of work, to what was agreed, needs no asking; deleting it does. Files under `.atw/` that this workflow manages are outside this.
+[/workflow-state:no_task]
+
+[workflow-state:task_error]
+The current task's record could not be read. Do not create or start another task.
+Inspect the task directory named above and repair its task.json. It must be a valid JSON object with a non-empty status.
+Preserve existing task fields and files. If the correct status cannot be determined safely, ask the user before reconstructing the record.
+[/workflow-state:task_error]
+
+[workflow-state:noob_mode]
+Noob mode is ON — this user is not an engineer. The full rules are `/atw-noob-mode`: if their text is not in front of you in this conversation, load it before you reply. The lines below are only its core; hold to them in every reply, in every stage:
+- Plain words in the user's language. Explain any unavoidable term, command, path or flag in the same sentence it appears in.
+- Another skill's question list, table or report keeps its shape, but every word in it that reaches the user follows these rules. The project's own glossary words are jargon to this user too.
+- Before anything they must approve or that is hard to undo: what will happen, why, how risky it is, and what approving or declining leads to.
+- Say who did what, what you actually ran versus what you only expect, and every decision you made for them.
+- Retell command output, research results and errors the same way: what happened, what it affects, what comes next.
+This workflow adds two rules; where a skill says otherwise, these come first:
+- Per round, ask the user for at most three answers, one per question: no second ask in it or its suggested answer. Count ones without ❓ and each to ask someone else. Reported decisions do not, unless one changes the result with no safe default: ask. Rest later despite `atw-interview`.
+- Keep the task folder and file paths out of your replies: say what you did and show the content, even where `/atw-noob-mode` says to point to the file. Give a path only for a file the user has to open themselves, and say in the same sentence what that file is.
+Only the user turns it off ("关闭小白模式" / "turn off noob mode"): run `python3 ./.atw/scripts/noob_mode.py off`.
+[/workflow-state:noob_mode]
+
+### Phase 1: Plan
+
+- 1.0 Create the task `[larger requests · once]` (your call; no stop)
+- 1.1 Talk it through `[required · repeatable]` (status `discover`)
+- 1.2 Write it down `[required · once]` (status `specify`; `prd.md`, then stop ①)
+- 1.3 Start the work `[required · once]` (`task.py start`; status → `implement`)
+- 1.4 Continue a task brought over from `dev` `[only for status slice]`
+
+[workflow-state:discover]
+Do not start the work yet. First make sure you know what the user wants: the goal, who or what it is for, how far it goes, and how they will tell it is done.
+If any of that is unclear, ask — use the `atw-interview` skill yourself. Never tell the user to run a command in order to be asked. If everything is already clear from what they said, do not question them for form's sake.
+Use `atw-research` for outside facts you need before the work can be agreed, and `atw-session-insight` when the user refers to something from an earlier conversation.
+Look things up yourself, in this conversation. With `atw-research` too, do not hand the looking-up to a background agent or any other helper: do the reading yourself. If it comes back with nothing, tell the user in the same reply and offer other ways to go on.
+When a tool you want is blocked, tell the user what you cannot do and why, offer ways to go on that do not need that tool, and wait for them to choose. Do not ask them to type a slash command, and do not edit, or offer to edit, the platform's permission or settings files — not even when they ask you to sort it out.
+Before you delete any file in the user's folder, or overwrite a file you did not create in this piece of work, tell the user which file, why, and whether it can be got back afterwards, and wait for them to agree. "Replace it with the new version" or "tidy this up" is not agreement to delete or overwrite. What they have clearly agreed to, do not ask again. Updating a file you made in this piece of work, to what was agreed, needs no asking; deleting it does. Files under `.atw/` that this workflow manages are outside this.
+Gate out of discover: not one question you raised may still be unanswered. If one is open, ask it now instead of advancing.
+When clear, run `task.py set-status <task> specify` yourself — this is not a stop.
+[/workflow-state:discover]
+
+[workflow-state:specify]
+Write `{TASK_DIR}/prd.md` yourself, now, in the user's language and in plain words. Three parts: what will be done, what will not be done, and what counts as done — a short list of checks the user could verify themselves. Replace the placeholder text the file was created with.
+Stop ①: show the user what you wrote — the content, not just the file name — and wait for them to confirm it. Do not start on your own judgement that it looks right. If they change anything, update `prd.md` and show it again. If they agree to part of it and say nothing about the rest, only that part is confirmed: ask about the rest before you start.
+Once they confirm, run `task.py start <task>` yourself and begin the work in the same turn. Do not ask them to start anything.
+Look things up yourself, in this conversation. With `atw-research` too, do not hand the looking-up to a background agent or any other helper: do the reading yourself. If it comes back with nothing, tell the user in the same reply and offer other ways to go on.
+When a tool you want is blocked, tell the user what you cannot do and why, offer ways to go on that do not need that tool, and wait for them to choose. Do not ask them to type a slash command, and do not edit, or offer to edit, the platform's permission or settings files — not even when they ask you to sort it out.
+Before you delete any file in the user's folder, or overwrite a file you did not create in this piece of work, tell the user which file, why, and whether it can be got back afterwards, and wait for them to agree. "Replace it with the new version" or "tidy this up" is not agreement to delete or overwrite. What they have clearly agreed to, do not ask again. Updating a file you made in this piece of work, to what was agreed, needs no asking; deleting it does. Files under `.atw/` that this workflow manages are outside this.
+[/workflow-state:specify]
+
+[workflow-state:slice]
+This task was brought over from a `dev` project. `slice` is the `dev` stage where a confirmed `prd.md` is cut into tickets; this workflow has no such stage. Do not cut tickets and do not ask the user to run anything.
+Read `{TASK_DIR}/prd.md`, and read any tickets already in `{TASK_DIR}/issues/` as a plain list of the parts of the work. Tell the user in a sentence or two what this task is and where it stands.
+If `prd.md` says what will be done, what will not, and what counts as done: the user confirmed it before the task got here, so run `task.py start <task>` and continue in implement.
+If it does not: run `task.py set-status <task> specify` and write that down first, for the user to confirm.
+Before you delete any file in the user's folder, or overwrite a file you did not create in this piece of work, tell the user which file, why, and whether it can be got back afterwards, and wait for them to agree. "Replace it with the new version" or "tidy this up" is not agreement to delete or overwrite. What they have clearly agreed to, do not ask again. Updating a file you made in this piece of work, to what was agreed, needs no asking; deleting it does. Files under `.atw/` that this workflow manages are outside this.
+[/workflow-state:slice]
+
+### Phase 2: Do
+
+- 2.1 Do the work `[required]` (status `implement`; no stop)
+- 2.2 Go back when what was agreed has to change `[on demand]`
+
+[workflow-state:implement]
+The user has confirmed `{TASK_DIR}/prd.md`. Do the work now, yourself. There is no stop here and nothing for the user to run.
+Stay inside what was agreed. Any change to it is confirmed before you act on it: a change the user asks for, and equally one you propose yourself because something cannot be done as written (another format, another source, a part left out). Go back: run `task.py set-status <task> specify`, update `prd.md`, show the user each change, and wait for them to confirm — this is stop ① again. Do not carry on with the work in the same turn.
+If the user agreed to some of the changes, only those are confirmed. Anything else you changed is still open: point it out and ask about it before you start again. Telling the user afterwards is not confirmation.
+Look things up yourself, in this conversation. With `atw-research` too, do not hand the looking-up to a background agent or any other helper: do the reading yourself. If it comes back with nothing, tell the user in the same reply and offer other ways to go on.
+When a tool you want is blocked, tell the user what you cannot do and why, offer ways to go on that do not need that tool, and wait for them to choose. Do not ask them to type a slash command, and do not edit, or offer to edit, the platform's permission or settings files — not even when they ask you to sort it out. Going on another way changes what was agreed: what they choose is confirmed like any other change, as above.
+Before you delete any file in the user's folder, or overwrite a file you did not create in this piece of work, tell the user which file, why, and whether it can be got back afterwards, and wait for them to agree. "Replace it with the new version" or "tidy this up" is not agreement to delete or overwrite. What they have clearly agreed to, do not ask again. Updating a file you made in this piece of work, to what was agreed, needs no asking; deleting it does. Files under `.atw/` that this workflow manages are outside this.
+A task brought over from a `dev` project may have tickets in `{TASK_DIR}/issues/`: read them as a list of the parts of the work. Do not claim them and do not ask the user to run anything for them.
+When everything in `prd.md` is done, run `task.py set-status <task> accept` yourself and go straight on to the check.
+[/workflow-state:implement]
+
+### Phase 3: Finish
+
+- 3.1 Check against what was agreed `[required · once]` (status `accept`; then stop ②)
+- 3.2 Archive and write the journal `[required · once]` (after the user accepts; no stop)
+
+[workflow-state:accept]
+Go through "what counts as done" in `{TASK_DIR}/prd.md` one item at a time. For each item say whether it is met and give the evidence: where the user can see it for themselves — the file, the section, the figure, the source.
+Report what you actually checked, not what you expect. If an item is not met and you can finish it within what was agreed, run `task.py set-status <task> implement`, finish it, and come back to this check.
+Look things up yourself, in this conversation. With `atw-research` too, do not hand the looking-up to a background agent or any other helper: do the reading yourself. If it comes back with nothing, tell the user in the same reply and offer other ways to go on.
+When a tool you want is blocked, tell the user what you cannot do and why, offer ways to go on that do not need that tool, and wait for them to choose. Do not ask them to type a slash command, and do not edit, or offer to edit, the platform's permission or settings files — not even when they ask you to sort it out.
+Before you delete any file in the user's folder, or overwrite a file you did not create in this piece of work, tell the user which file, why, and whether it can be got back afterwards, and wait for them to agree. "Replace it with the new version" or "tidy this up" is not agreement to delete or overwrite. What they have clearly agreed to, do not ask again. Updating a file you made in this piece of work, to what was agreed, needs no asking; deleting it does. Files under `.atw/` that this workflow manages are outside this.
+Stop ②: present the item-by-item result and wait. Whether the work is done is the user's judgement, not yours. If they want changes, run `task.py set-status <task> implement`, make them, then check again.
+Once they accept, do the rest yourself, without asking, in this order. First record the result in `{TASK_DIR}/prd.md`: under "what counts as done", tick each item your check found met (`- [x]`). An item you found not met, or could not verify in full, stays unticked, with the reason on a line under it. Tick by what the check found, not because the user accepted, and change no other wording. If the item-by-item result is not in front of you in this conversation — the user accepts in a later session — go through the items again before you tick.
+Then `task.py archive <task> --skip-branch-validation`, then `add_session.py --title "<title>" --summary "<what was done>"`. Tell them in one sentence that it is filed.
+[/workflow-state:accept]
+
+[workflow-state:completed]
+The archive was interrupted. `task.py archive` writes `completed` to `task.json` first and moves the directory last, and it does not roll back — so a task still under `.atw/tasks/` with this status means the move never happened.
+Re-run `task.py archive <task> --skip-branch-validation` to finish it; the steps before the move are safe to repeat. Then write the journal entry with `add_session.py` if this task does not have one yet.
+Do not open new work on this task, do not create another task for it, and do not move the directory by hand. If the re-run fails, tell the user what happened instead of working around it.
+[/workflow-state:completed]
+
+### Rules
+
+1. Find the current task's status, then do what the table above says for it
+2. Stops ① and ② are the user's calls. Never pass one by inferring the answer
+3. Everything else you advance yourself: no "shall I go on?", and nothing for the user to type
+4. A status can go back (the work shows that what was agreed is wrong → `set-status specify`, fix `prd.md`, confirm again)
+5. A task without `prd.md` content the user confirmed is not ready to be worked on
+
+### Loading Step Detail
+
+At each step, run this to read it in full:
+
+```bash
+python3 ./.atw/scripts/get_context.py --mode phase --step <step>
+# e.g. python3 ./.atw/scripts/get_context.py --mode phase --step 1.2
+```
+
+---
+
+## Phase 1: Plan
+
+Goal: know what the user wants, and have it written down and confirmed.
+
+#### 1.0 Create the task `[larger requests · once]`
+
+Create a task as soon as you see the request is more than a small one (see "Small Request or Task"). This is your call — do not ask the user first. Tell them in one sentence that you are keeping a record of this piece of work.
+
+```bash
+python3 ./.atw/scripts/task.py create "<task title>" --description "<one-line description>" --slug <name>
+```
+
+`--slug` is a short readable name only. Do not include the `MM-DD-` date prefix; `task.py create` adds it.
+
+The command sets the status to `discover`, writes `task.json`, creates a placeholder `prd.md`, and makes the new task this session's current task. From the next turn the reminder is the one for `discover`.
+
+Run only `create` here. `start` moves the status straight to `implement`, which skips agreeing on the work; it belongs to step 1.3.
+
+Skip this step when `python3 ./.atw/scripts/task.py current --source` already points to a task, and when the user is going on with earlier work — pick that task up instead (see "Picking Up Unfinished Work").
+
+#### 1.1 Talk it through `[required · repeatable]`
+
+Goal: remove the unknowns before anything is written down as agreed.
+
+You need to know four things: what the result is, who or what it is for, how far it goes (and where it stops), and how the user will tell it is done. If any of them is unclear, ask.
+
+- Use the `atw-interview` skill yourself to do the asking. The user does not have to type anything to be asked, and you do not tell them to.
+- Use `atw-research` when the open question is about outside facts — what a source says, what the options are — rather than about what the user wants. Keep the notes in `{TASK_DIR}/research/`, one file per topic. You do the looking-up yourself (see "Looking Things Up").
+- Use `atw-session-insight` when the user refers to something said or decided in an earlier conversation.
+
+When the request is already clear, do not question the user for form's sake. Go straight on.
+
+**Gate out of discover**: not one question you raised may still be unanswered. An unanswered question becomes a guess, and a guess becomes something the user rejects at the end. When the gate is clear:
+
+```bash
+python3 ./.atw/scripts/task.py set-status <task> specify
+```
+
+This is not a stop — advance on your own judgement.
+
+#### 1.2 Write it down `[required · once]`
+
+Write `{TASK_DIR}/prd.md` yourself, replacing the placeholder the task was created with. Use the user's language and plain words — this is the page they confirm, so they must be able to read it without help.
+
+Give it three sections, each under its own heading, in this order:
+
+- **What will be done** — the result, concretely: which document, which list, which decision.
+- **What will not be done** — what someone could reasonably expect but is left out. This is where misunderstandings get caught cheaply.
+- **What counts as done** — a short checklist the user could verify themselves. Phase 3 goes through exactly this list, so each item has to be something you can show evidence for.
+
+**Stop ①**: show the user what you wrote — the content itself, not just the file name — and wait for them to confirm it. This is the last cheap place to be wrong. Do not advance on your own judgement that it looks right. If they change anything, update `prd.md` and show it again. If they agree to part of it and say nothing about the rest, only that part is confirmed: ask about the rest before you start.
+
+Come back to this step whenever what was agreed changes, including from Phase 2 (step 2.2).
+
+#### 1.3 Start the work `[required · once]`
+
+As soon as the user has confirmed `prd.md` (stop ①), start — in the same turn, without asking them to do anything:
+
+```bash
+python3 ./.atw/scripts/task.py start <task>
+```
+
+This makes the task this session's current task and moves its status to `implement`.
+
+If `task.py start` says the session identity is not available, it has still moved the status; carry on from the conversation.
+
+#### 1.4 Continue a task brought over from `dev` `[only for status slice]`
+
+A task at `slice` was created while this project was in `dev` mode. There, `slice` is the stage where a confirmed `prd.md` is cut into tickets under `{TASK_DIR}/issues/`. This workflow has no such stage: do not cut tickets, and do not ask the user to run anything.
+
+1. Read `{TASK_DIR}/prd.md`. If there are tickets in `{TASK_DIR}/issues/`, read them as a plain list of the parts of the work — some may already be finished.
+2. Tell the user in a sentence or two what this task is and where it stands.
+3. If `prd.md` says what will be done, what will not, and what counts as done, the user confirmed it before the task reached this status. Start the work:
+
+   ```bash
+   python3 ./.atw/scripts/task.py start <task>
+   ```
+
+4. If it does not — it is missing, still a placeholder, or gives no way to tell when the work is done — go back and write that down first (step 1.2), for the user to confirm:
+
+   ```bash
+   python3 ./.atw/scripts/task.py set-status <task> specify
+   ```
+
+The same reading applies to a task that arrives at `implement` with tickets in `issues/`: they are a list of the parts of the work, nothing to claim or close.
+
+---
+
+## Phase 2: Do
+
+Goal: produce what was agreed.
+
+#### 2.1 Do the work `[required]`
+
+The user has confirmed `prd.md`. Do the work yourself, now. There is no stop in this phase and nothing for the user to run.
+
+- Work from `prd.md`: what will be done is the scope, what will not be done is the fence.
+- Follow `.atw/spec/conventions.md`, and add to it when the user corrects you or repeats a preference (see "Keeping Conventions").
+- When you need outside facts, look them up (`atw-research`) rather than writing from memory, and keep what you found in `{TASK_DIR}/research/`. You do the looking-up yourself (see "Looking Things Up").
+- When a tool you want is blocked, see "When A Tool Is Blocked". Going on another way is step 2.2.
+- Before you delete or overwrite a file, see "Before You Delete Or Overwrite A File".
+- If the work takes more than one session, the task stays open at `implement`; a later session picks it up (see "Picking Up Unfinished Work").
+
+When everything in `prd.md` is done, move on yourself and go straight to the check (step 3.1):
+
+```bash
+python3 ./.atw/scripts/task.py set-status <task> accept
+```
+
+#### 2.2 Go back when what was agreed has to change `[on demand]`
+
+Any change to what was agreed is confirmed before you act on it. Where the change comes from makes no difference:
+
+- the user asks for something that changes it;
+- the work shows it cannot be met as written;
+- one you propose yourself — a tool is not available, a source cannot be reached, another format would read better. However reasonable your alternative looks, it is a change like any other. For a tool the platform blocked, the user chooses the way on first (see "When A Tool Is Blocked").
+
+Do not quietly do something else. Go back to step 1.2: update `prd.md`, show the user each change, and wait for them to confirm (stop ①). Do not carry on with the work in the same turn:
+
+```bash
+python3 ./.atw/scripts/task.py set-status <task> specify
+```
+
+If the user agreed to some of the changes, only those are confirmed — picking one of the options you offered agrees to what that option said, nothing more. Anything else in the updated `prd.md` is still open: point it out and ask about it before you start again.
+
+Telling the user afterwards is not confirmation. A change that reaches them as "a decision I made for you", once the work is done, was never agreed.
+
+Once every change is confirmed, start again as in step 1.3. A small clarification that changes nothing in `prd.md` does not need this.
+
+---
+
+## Phase 3: Finish
+
+Goal: the user agrees the work is done, and it is filed.
+
+#### 3.1 Check against what was agreed `[required · once]`
+
+Go through "what counts as done" in `prd.md` one item at a time. For each item, say whether it is met and give the evidence: where the user can see it for themselves — the file, the section, the figure, the source. Also confirm nothing listed under "what will not be done" was done anyway.
+
+Report what you actually checked, not what you expect to be true. You are checking your own work, so the user's acceptance is the real gate — make it easy for them to verify.
+
+If an item is not met and you can finish it within what was agreed, finish it before presenting:
+
+```bash
+python3 ./.atw/scripts/task.py set-status <task> implement
+```
+
+Then come back to this check. If it cannot be met, say so plainly in the report.
+
+**Stop ②**: present the item-by-item result and wait. Whether the work is done is the user's judgement, not yours — you can report that every item is met, but you cannot accept on their behalf. If they want changes, set the status back to `implement` as above, make them, and check again.
+
+#### 3.2 Archive and write the journal `[required · once]`
+
+Once the user accepts, do the rest yourself, in this order, without asking and without telling them to run anything.
+
+First record the result of the check in `prd.md`, while the task is still in place — the archive moves its directory. Under "what counts as done":
+
+- tick each item your check found met (`- [x]`);
+- an item you found not met, or could not verify in full, stays unticked, with the reason on a line under it. A caveat you gave about part of an item counts: that item is not verified in full.
+
+Tick by what the check in step 3.1 found, not because the user accepted: they can accept the work with an item still open, and whoever opens the archived task later should read the same result you reported. Change no other wording — this records the outcome, it does not change what was agreed.
+
+If the item-by-item result is not in front of you in this conversation — the user accepts in a later session — go through the items again before you tick, as in step 3.1.
+
+Then archive and write the journal:
+
+```bash
+python3 ./.atw/scripts/task.py archive <task> --skip-branch-validation
+python3 ./.atw/scripts/add_session.py --title "<title>" --summary "<what was done>"
+```
+
+`archive` writes `status=completed`, moves the directory to `archive/{year-month}/`, and clears the session's current task. `--skip-branch-validation` is needed because a task in this workflow is not tied to a branch or a pull request, which is what that check is about.
+
+`add_session.py` adds an entry to your journal under `.atw/workspace/`, so the next session can see what was done. In a folder that is not a git repository both commands say so and carry on; that is not an error.
+
+Then tell the user in one sentence that the work is filed.
+
+If a task is found at `completed` but still under `.atw/tasks/`, the archive was interrupted: run the `archive` command again, then write the journal entry if the task does not have one yet.
+
+---
+
+## Customizing ATW (for forks)
+
+This is the built-in workflow of `general` mode. `atw workflow --template native` in a general project restores it, and `atw update` keeps it current as long as the file has not been edited. All customization is done by editing this file; the scripts only parse it.
+
+### What must stay true
+
+- With no current task, a small request is just done and a larger one gets a task without the user being asked.
+- Stops ① and ② stay reachable and stay the user's call. There is no third stop.
+- Nothing here tells the user to type a command in order to move the work forward.
+- Only skills that `general` mode installs are named.
+
+Structure is guarded by `packages/cli/test/scripts/workflow-structure.test.ts`, which runs with `pnpm test`.
+
+### Changing the per-turn reminder text
+
+Edit the body of the matching `[workflow-state:STATUS]` block in the `## Phase Index` section. When you change a block, check the matching step for sync: the block is what the AI hears on every turn, the step is what it reads on demand.
+
+| Scope | Block |
+|---|---|
+| No current task | `[workflow-state:no_task]` |
+| Current task's record unreadable | `[workflow-state:task_error]` |
+| Step 1.1 | `[workflow-state:discover]` |
+| Steps 1.2–1.3 | `[workflow-state:specify]` |
+| Step 1.4 — a task brought over from `dev` | `[workflow-state:slice]` |
+| Phase 2 | `[workflow-state:implement]` |
+| Phase 3 up to the archive | `[workflow-state:accept]` |
+| Archive interrupted; task still under `.atw/tasks/` | `[workflow-state:completed]` |
+| Any of the above, while the user has noob mode on (appended, not a status) | `[workflow-state:noob_mode]` |

package/dist/templates/atw/workflow.md

@@ -32,7 +32,7 @@ For a user who is not an engineer. While it is on, every reply in every stage is
 python3 ./.atw/scripts/noob_mode.py on|off|status
 ```
 
-The user switches it by saying "开启小白模式" / "关闭小白模式" or running `/atw-noob-mode`; the skill runs the script. The switch is one line in that user's own `.atw/.developer`, so it is personal and never committed. It changes how the AI talks to the user — not the stages, the stops, or what goes into task files.
+The user switches it by saying "开启小白模式" / "关闭小白模式" or running `/atw-noob-mode`; the skill runs the script. Their choice — on or off — is one line in that user's own `.atw/.developer`, so it is personal and never committed. A user who has never chosen gets the project mode's default: on when `.atw/config.yaml` says `mode: general`, off when it says `mode: dev` or has no `mode` entry. Switching off is recorded as a choice, so neither the default nor a change of project mode turns it back on; `status` says which of the two is in effect. It changes how the AI talks to the user — not the stages, the stops, or what goes into task files.
 
 ### Spec System