@chinhae/atw-cli 0.1.0

package/dist/templates/common/bundled-skills/atw-improve-codebase-architecture/HTML-REPORT.md

@@ -0,0 +1,123 @@
+# HTML Report Format
+
+The architectural review is rendered as a single self-contained HTML file in the OS temp directory. Tailwind and Mermaid both come from CDNs. Mermaid handles graph-shaped diagrams reliably; hand-built divs and inline SVG handle the more editorial visuals (mass diagrams, cross-sections). Mix the two — don't lean on Mermaid for everything, it'll start to look generic.
+
+## Scaffold
+
+```html
+<!doctype html>
+<html lang="en">
+  <head>
+    <meta charset="utf-8" />
+    <title>Architecture review — {{repo name}}</title>
+    <script src="https://cdn.tailwindcss.com"></script>
+    <script type="module">
+      import mermaid from "https://cdn.jsdelivr.net/npm/mermaid@11/dist/mermaid.esm.min.mjs";
+      mermaid.initialize({ startOnLoad: true, theme: "neutral", securityLevel: "loose" });
+    </script>
+    <style>
+      /* small custom layer for things Tailwind doesn't cover cleanly:
+         dashed seam lines, hand-drawn-feeling arrow heads, etc. */
+      .seam { stroke-dasharray: 4 4; }
+      .leak { stroke: #dc2626; }
+      .deep { background: linear-gradient(135deg, #0f172a, #1e293b); }
+    </style>
+  </head>
+  <body class="bg-stone-50 text-slate-900 font-sans">
+    <main class="max-w-5xl mx-auto px-6 py-12 space-y-12">
+      <header>...</header>
+      <section id="candidates" class="space-y-10">...</section>
+      <section id="top-recommendation">...</section>
+    </main>
+  </body>
+</html>
+```
+
+## Header
+
+Repo name, date, and a compact legend: solid box = module, dashed line = seam, red arrow = leakage, thick dark box = deep module. No introduction paragraph — straight into the candidates.
+
+## Candidate card
+
+The diagrams carry the weight. Prose is sparse, plain, and uses the glossary terms (from the `/atw-codebase-design` skill) without ceremony.
+
+Each candidate is one `<article>`:
+
+- **Title** — short, names the deepening (e.g. "Collapse the Order intake pipeline").
+- **Badge row** — recommendation strength (`Strong` = emerald, `Worth exploring` = amber, `Speculative` = slate), plus a tag for the dependency category (`in-process`, `local-substitutable`, `ports & adapters`, `mock`).
+- **Files** — monospaced list, `font-mono text-sm`.
+- **Before / After diagram** — the centrepiece. Two columns, side by side. See patterns below.
+- **Problem** — one sentence. What hurts.
+- **Solution** — one sentence. What changes.
+- **Wins** — bullets, ≤6 words each. e.g. "Tests hit one interface", "Pricing logic stops leaking", "Delete 4 shallow wrappers".
+- **ADR callout** (if applicable) — one line in an amber-tinted box.
+
+No paragraphs of explanation. If the diagram needs a paragraph to be understood, redraw the diagram.
+
+## Diagram patterns
+
+Pick the pattern that fits the candidate. Mix them. Don't make every diagram look the same — variety is part of the point.
+
+### Mermaid graph (the workhorse for dependencies / call flow)
+
+Use a Mermaid `flowchart` or `graph` when the point is "X calls Y calls Z, and look at the mess." Wrap it in a Tailwind-styled card so it doesn't feel parachuted in. Style with classDef to colour leakage edges red and the deep module dark. Sequence diagrams work well for "before: 6 round-trips; after: 1."
+
+```html
+<div class="rounded-lg border border-slate-200 bg-white p-4">
+  <pre class="mermaid">
+    flowchart LR
+      A[OrderHandler] --> B[OrderValidator]
+      B --> C[OrderRepo]
+      C -.leak.-> D[PricingClient]
+      classDef leak stroke:#dc2626,stroke-width:2px;
+      class C,D leak
+  </pre>
+</div>
+```
+
+### Hand-built boxes-and-arrows (when Mermaid's layout fights you)
+
+Modules as `<div>`s with borders and labels. Arrows as inline SVG `<line>` or `<path>` elements positioned absolutely over a relative container. Reach for this when you want the "after" diagram to feel like one thick-bordered deep module with greyed-out internals — Mermaid won't render that with the right weight.
+
+### Cross-section (good for layered shallowness)
+
+Stack horizontal bands (`h-12 border-l-4`) to show layers a call passes through. Before: 6 thin layers each doing nothing. After: 1 thick band labelled with the consolidated responsibility.
+
+### Mass diagram (good for "interface as wide as implementation")
+
+Two rectangles per module — one for interface surface area, one for implementation. Before: interface rectangle is nearly as tall as the implementation rectangle (shallow). After: interface rectangle is short, implementation rectangle is tall (deep).
+
+### Call-graph collapse
+
+Before: a tree of function calls rendered as nested boxes. After: the same tree collapsed into one box, with the now-internal calls shown faded inside it.
+
+## Style guidance
+
+- Lean editorial, not corporate-dashboard. Generous whitespace. Serif optional for headings (`font-serif` works well with stone/slate).
+- Colour sparingly: one accent (emerald or indigo) plus red for leakage and amber for warnings.
+- Keep diagrams ~320px tall so before/after sits comfortably side by side without scrolling.
+- Use `text-xs uppercase tracking-wider` for module labels inside diagrams — they should read as schematic, not as UI.
+- The only scripts are the Tailwind CDN and the Mermaid ESM import. The report is otherwise static — no app code, no interactivity beyond Mermaid's own rendering.
+
+## Top recommendation section
+
+One larger card. Candidate name, one sentence on why, anchor link to its card. That's it.
+
+## Tone
+
+Plain English, concise — but the architectural nouns and verbs come straight from the `/atw-codebase-design` skill. Concision is not an excuse to drift.
+
+**Use exactly:** module, interface, implementation, depth, deep, shallow, seam, adapter, leverage, locality.
+
+**Never substitute:** component, service, unit (for module) · API, signature (for interface) · boundary (for seam) · layer, wrapper (for module, when you mean module).
+
+**Phrasings that fit the style:**
+
+- "Order intake module is shallow — interface nearly matches the implementation."
+- "Pricing leaks across the seam."
+- "Deepen: one interface, one place to test."
+- "Two adapters justify the seam: HTTP in prod, in-memory in tests."
+
+**Wins bullets** name the gain in glossary terms: *"locality: bugs concentrate in one module"*, *"leverage: one interface, N call sites"*, *"interface shrinks; implementation absorbs the wrappers"*. Don't write *"easier to maintain"* or *"cleaner code"* — those terms aren't in the glossary and don't earn their place.
+
+No hedging, no throat-clearing, no "it's worth noting that…". If a sentence could be a bullet, make it a bullet. If a bullet could be cut, cut it. If a term isn't in the `/atw-codebase-design` glossary, reach for one that is before inventing a new one.

package/dist/templates/common/bundled-skills/atw-improve-codebase-architecture/SKILL.md

@@ -0,0 +1,71 @@
+---
+name: atw-improve-codebase-architecture
+description: "扫描代码库以发现可深入挖掘的机会，将其以可视化的 HTML 报告形式呈现，然后针对您选择的任何一个机会进行深入探讨。"
+disable-model-invocation: true
+---
+
+# Oxyteam Improve Codebase Architecture
+
+Surface architectural friction and propose **deepening opportunities** — refactors that turn shallow modules into deep ones. The aim is testability and AI-navigability.
+
+This command is _informed_ by the project's domain model and built on a shared design vocabulary:
+
+- Call the Skill tool with "atw-codebase-design" for the architecture vocabulary (**module**, **interface**, **depth**, **seam**, **adapter**, **leverage**, **locality**) and its principles (the deletion test, "the interface is the test surface", "one adapter = hypothetical seam, two = real"). Use these terms exactly in every suggestion — don't drift into "component," "service," "API," or "boundary."
+- The domain language in `CONTEXT.md` gives names to good seams; ADRs in `docs/adr/` record decisions this command should not re-litigate.
+
+## Process
+
+### 1. Explore
+
+**Scope before you scan — YAGNI.** Deepening a module pays off by making future changes to it easier, so put extra weight on the parts of the codebase that have recently changed. Decide *where* to look before you look:
+
+- If the user named a direction — a module, a subsystem, a pain point — take it, and skip the inference below.
+- Otherwise, walk back a good stretch of the commit history (`git log --oneline`) to find the codebase's hot spots — the files and areas that keep coming up — and let those paths pull your attention first. If the changes are scattered with no clear hot spot, widen the net.
+
+Read the project's domain glossary (`CONTEXT.md`) and any ADRs in the area you're touching first.
+
+Then spawn a sub-agent to walk the codebase. Don't follow rigid heuristics — explore organically and note where you experience friction:
+
+- Where does understanding one concept require bouncing between many small modules?
+- Where are modules **shallow** — interface nearly as complex as the implementation?
+- Where have pure functions been extracted just for testability, but the real bugs hide in how they're called (no **locality**)?
+- Where do tightly-coupled modules leak across their seams?
+- Which parts of the codebase are untested, or hard to test through their current interface?
+
+Apply the **deletion test** to anything you suspect is shallow: would deleting it concentrate complexity, or just move it? A "yes, concentrates" is the signal you want.
+
+### 2. Present candidates as an HTML report
+
+Write a self-contained HTML file to the OS temp directory so nothing lands in the repo. Resolve the temp dir from `$TMPDIR`, falling back to `/tmp` (or `%TEMP%` on Windows), and write to `<tmpdir>/architecture-review-<timestamp>.html` so each run gets a fresh file. Open it for the user — `xdg-open <path>` on Linux, `open <path>` on macOS, `start <path>` on Windows — and tell them the absolute path.
+
+The report uses **Tailwind via CDN** for layout and styling, and **Mermaid via CDN** for diagrams where a graph/flow/sequence reliably communicates the structure. Mix Mermaid with hand-crafted CSS/SVG visuals — use Mermaid when relationships are graph-shaped (call graphs, dependencies, sequences), and hand-built divs/SVG when you want something more editorial (mass diagrams, cross-sections, collapse animations). Each candidate gets a **before/after visualisation**. Be visual.
+
+For each candidate, render a card with:
+
+- **Files** — which files/modules are involved
+- **Problem** — why the current architecture is causing friction
+- **Solution** — plain English description of what would change
+- **Benefits** — explained in terms of locality and leverage, and how tests would improve
+- **Before / After diagram** — side-by-side, custom-drawn, illustrating the shallowness and the deepening
+- **Recommendation strength** — one of `Strong`, `Worth exploring`, `Speculative`, rendered as a badge
+
+End the report with a **Top recommendation** section: which candidate you'd tackle first and why.
+
+**Use CONTEXT.md vocabulary for the domain, and the `/atw-codebase-design` vocabulary for the architecture.** If `CONTEXT.md` defines "Order," talk about "the Order intake module" — not "the FooBarHandler," and not "the Order service."
+
+**ADR conflicts**: if a candidate contradicts an existing ADR, only surface it when the friction is real enough to warrant revisiting the ADR. Mark it clearly in the card (e.g. a warning callout: _"contradicts ADR-0007 — but worth reopening because…"_). Don't list every theoretical refactor an ADR forbids.
+
+See [HTML-REPORT.md](HTML-REPORT.md) for the full HTML scaffold, diagram patterns, and styling guidance.
+
+Do NOT propose interfaces yet. After the file is written, ask the user: "Which of these would you like to explore?"
+
+### 3. Interview loop
+
+Once the user picks a candidate, call the Skill tool with "atw-interview" to walk the decision tree with them — constraints, dependencies, the shape of the deepened module, what sits behind the seam, what tests survive.
+
+Side effects happen inline as decisions crystallize — call the Skill tool with "atw-domain-modeling" to keep the domain model current as you go:
+
+- **Naming a deepened module after a concept not in `CONTEXT.md`?** Add the term to `CONTEXT.md`. Create the file lazily if it doesn't exist.
+- **Sharpening a fuzzy term during the conversation?** Update `CONTEXT.md` right there.
+- **User rejects the candidate with a load-bearing reason?** Offer an ADR, framed as: _"Want me to record this as an ADR so future architecture reviews don't re-suggest it?"_ Only offer when the reason would actually be needed by a future explorer to avoid re-suggesting the same thing — skip ephemeral reasons ("not worth it right now") and self-evident ones.
+- **Want to explore alternative interfaces for the deepened module?** Call the Skill tool with "atw-codebase-design" and use its design-it-twice parallel sub-agent pattern.

package/dist/templates/common/bundled-skills/atw-improve-codebase-architecture/agents/openai.yaml

@@ -0,0 +1,5 @@
+interface:
+  display_name: "Oxyteam Improve Codebase Architecture"
+  short_description: "发现并深入访谈架构改进机会"
+policy:
+  allow_implicit_invocation: false

package/dist/templates/common/bundled-skills/atw-init-repo/SKILL.md

@@ -0,0 +1,130 @@
+---
+name: atw-init-repo
+description: "为当前代码库配置工程技能所依赖的三样东西：问题跟踪器、分诊标签词汇、领域文档布局，写入 docs/agents/。首次使用 atw-spec / atw-tickets / atw-triage / atw-map / atw-code-review 之前跑一次。"
+disable-model-invocation: true
+---
+
+# Init repo
+
+Scaffold the per-repo configuration the engineering skills assume:
+
+- **Issue tracker** — where issues live for this repo
+- **Triage labels** — the strings used for the five canonical triage roles
+- **Domain docs** — where `CONTEXT.md` and ADRs live, and the rules for reading them
+
+The output is three files under `docs/agents/`, plus an `## Agent skills` block in the repo's agent instructions file. Five skills read them: `atw-spec`, `atw-tickets`, `atw-triage`, `atw-map`, `atw-code-review`. `atw-research` reads the tracker doc for where findings go.
+
+This is a prompt-driven skill, not a deterministic script. Explore, present what you found, confirm with the user, then write.
+
+## Process
+
+### 1. Explore
+
+Look at the current repo to understand its starting state. Read whatever exists; don't assume:
+
+- `git remote -v` — is this a GitHub repo? GitLab? No remote at all?
+- `CLAUDE.md` and `AGENTS.md` at the repo root — does either exist? Is there already an `## Agent skills` section in either?
+- `CONTEXT.md` and `CONTEXT-MAP.md` at the repo root
+- `docs/adr/` and any `src/*/docs/adr/` directories
+- `docs/agents/` — does this skill's prior output already exist?
+- `.scratch/` — sign that a local-markdown issue tracker convention is already in use
+- `.atw/scripts/tickets.py` — the ATW ticket parser. Its presence means this repo can use its own task directory as the tracker, which is usually the right answer
+- Monorepo signals — a `pnpm-workspace.yaml`, a `workspaces` field in `package.json`, or a populated `packages/*` with its own `src/`. Present only in a genuinely large multi-package repo; their absence means single-context, which is almost every repo.
+
+### 2. Present findings and ask
+
+Summarise what's present and what's missing. Then take the sections in order — one section, one answer, then the next.
+
+Lead each section with the recommended answer so the user can accept it in a word. Give a one-line explainer only when the choice genuinely branches; skip Section C entirely when there's no monorepo.
+
+**Section A — Issue tracker.**
+
+> Explainer: The "issue tracker" is where issues live for this repo. Skills like `atw-tickets`, `atw-triage`, and `atw-spec` read from and write to it — they need to know whether to call `gh issue create`, write a markdown file under the task directory, or follow some other workflow you describe. Pick the place you actually track work for this repo.
+
+Default posture: if `.atw/scripts/tickets.py` is present, propose the ATW task directory. **Which of the two ATW variants you propose is decided by `git remote get-url origin`**: a GitHub remote → the mirrored variant; no remote, or a non-GitHub one → **ATW task directory (local only)**. Don't propose the mirror to a repo that has nothing to mirror to — `github_sync.py` would sit there printing "本仓库没有 GitHub 远程，跳过 Issue 创建" on every task, and would silently start filing real issues the day someone adds a remote. Otherwise, if a `git remote` points at GitHub, propose that; if it points at GitLab (`gitlab.com` or a self-hosted host), propose GitLab. Offer:
+
+- **ATW task directory + GitHub** — the spec and tickets for the current task live in `.atw/tasks/<task>/` and sync one-way out to GitHub Issues; issues other people raise stay in GitHub Issues
+- **ATW task directory (local only)** — same task directory, **no remote mirror at all**: nothing is synced, and no GitHub Issue is created. Propose this one when the repo has no `git remote` (also valid for a solo/private repo, or a team that deliberately keeps planning artifacts out of the issue tracker)
+- **GitHub** — issues live in the repo's GitHub Issues (uses the `gh` CLI)
+- **GitLab** — issues live in the repo's GitLab Issues (uses the [`glab`](https://gitlab.com/gitlab-org/cli) CLI)
+- **Local markdown** — issues live as files under `.scratch/<feature>/` in this repo (good for repos that don't run the ATW task system)
+- **Other** (Jira, Linear, etc.) — ask the user to describe the workflow in one paragraph; the skill will record it as freeform prose
+
+Record the choice in `docs/agents/issue-tracker.md`. The GitHub and GitLab templates carry a "PRs as a request surface" flag, defaulted **off** — leave it off and don't raise it; a user who wants external PRs in the triage queue can flip the flag in the file later.
+
+**Section B — Triage label vocabulary.** `atw-triage` ships with every ATW install, so this section always runs. Ask exactly one question:
+
+> Do you want to keep the default triage labels? (recommended: **yes**)
+
+The defaults are the five canonical roles, each label string equal to its name: `needs-triage`, `needs-info`, `ready-for-agent`, `ready-for-human`, `wontfix`. On **yes**, write them as-is. Only if the user says no — usually because their tracker already uses other names (e.g. `bug:triage` for `needs-triage`) — collect the overrides so `atw-triage` applies existing labels instead of creating duplicates.
+
+**Section C — Domain docs.** Default to **single-context** — one `CONTEXT.md` + `docs/adr/` at the repo root. This fits almost every repo; write it without asking.
+
+Offer **multi-context** — a root `CONTEXT-MAP.md` pointing to per-context `CONTEXT.md` files — only when exploration found monorepo signals. Then confirm which layout they want.
+
+### 3. Confirm and edit
+
+Show the user a draft of:
+
+- The `## Agent skills` block to add to whichever of `CLAUDE.md` / `AGENTS.md` is being edited (see step 4 for selection rules)
+- The contents of `docs/agents/issue-tracker.md`, `docs/agents/domain.md`, and `docs/agents/triage-labels.md`
+
+Let them edit before writing.
+
+### 4. Write
+
+**Pick the file to edit:**
+
+- If `CLAUDE.md` exists, edit it.
+- Else if `AGENTS.md` exists, edit it.
+- If neither exists, ask the user which one to create — don't pick for them.
+
+Never create `AGENTS.md` when `CLAUDE.md` already exists (or vice versa) — always edit the one that's already there.
+
+If an `## Agent skills` block already exists in the chosen file, update its contents in-place rather than appending a duplicate. Don't overwrite user edits to the surrounding sections.
+
+The block:
+
+```markdown
+## Agent skills
+
+### Issue tracker
+
+[one-line summary of where issues are tracked]. See `docs/agents/issue-tracker.md`.
+
+### Triage labels
+
+[one-line summary of the label vocabulary]. See `docs/agents/triage-labels.md`.
+
+### Domain docs
+
+[one-line summary of layout — "single-context" or "multi-context"]. See `docs/agents/domain.md`.
+```
+
+Then write the docs files using the seed templates in this skill's `references/` directory as a starting point:
+
+- [issue-tracker-atw.md](./references/issue-tracker-atw.md) — ATW task directory + GitHub mirror
+- [issue-tracker-atw-local.md](./references/issue-tracker-atw-local.md) — ATW task directory, no mirror. Also carries a `## Re-enabling the GitHub mirror` section, so picking it is reversible
+- [issue-tracker-github.md](./references/issue-tracker-github.md) — GitHub issue tracker
+- [issue-tracker-gitlab.md](./references/issue-tracker-gitlab.md) — GitLab issue tracker
+- [issue-tracker-local.md](./references/issue-tracker-local.md) — local-markdown issue tracker
+- [triage-labels.md](./references/triage-labels.md) — label mapping
+- [domain.md](./references/domain.md) — domain doc consumer rules + layout
+
+For "other" issue trackers, write `docs/agents/issue-tracker.md` from scratch using the user's description. It still needs the two lookup headings below, or the skills that read it will find nothing.
+
+**Keep every `##` heading verbatim from the template — do not translate them.** The prose under a heading may be written in whatever language the user works in, but the headings themselves are lookup keys that other skills match on literally:
+
+| Skill | Heading it looks for |
+|---|---|
+| `atw-map` | `## Wayfinding operations` |
+| `atw-tickets` | `## When a skill says "publish to the issue tracker"` |
+| `atw-code-review` | `## When a skill says "publish to the issue tracker"` |
+
+A translated heading fails **silently**: `atw-map` says "if no tracker has been provided, default to the local-markdown tracker", so it quietly falls back to writing under `.scratch/` instead of reporting an error. This has been observed in practice in a Chinese-language session, where all eight headings were translated.
+
+The same rule covers everything else other tooling matches literally: `[workflow-state:*]` tag names, task status values, file names, command names, and skill names all stay in English.
+
+### 5. Done
+
+Tell the user the setup is complete and which engineering skills will now read from these files. Mention they can edit `docs/agents/*.md` directly later — re-running this skill is only necessary if they want to switch issue trackers or restart from scratch.

package/dist/templates/common/bundled-skills/atw-init-repo/references/domain.md

@@ -0,0 +1,51 @@
+# Domain Docs
+
+How the engineering skills should consume this repo's domain documentation when exploring the codebase.
+
+## Before exploring, read these
+
+- **`CONTEXT.md`** at the repo root, or
+- **`CONTEXT-MAP.md`** at the repo root if it exists — it points at one `CONTEXT.md` per context. Read each one relevant to the topic.
+- **`docs/adr/`** — read ADRs that touch the area you're about to work in. In multi-context repos, also check `src/<context>/docs/adr/` for context-scoped decisions.
+
+If any of these files don't exist, **proceed silently**. Don't flag their absence; don't suggest creating them upfront. The `atw-domain-modeling` skill (reached via `atw-askme-with-docs` and `atw-improve-codebase-architecture`) creates them lazily when terms or decisions actually get resolved.
+
+## File structure
+
+Single-context repo (most repos):
+
+```
+/
+├── CONTEXT.md
+├── docs/adr/
+│   ├── 0001-event-sourced-orders.md
+│   └── 0002-postgres-for-write-model.md
+└── src/
+```
+
+Multi-context repo (presence of `CONTEXT-MAP.md` at the root):
+
+```
+/
+├── CONTEXT-MAP.md
+├── docs/adr/                          ← system-wide decisions
+└── src/
+    ├── ordering/
+    │   ├── CONTEXT.md
+    │   └── docs/adr/                  ← context-specific decisions
+    └── billing/
+        ├── CONTEXT.md
+        └── docs/adr/
+```
+
+## Use the glossary's vocabulary
+
+When your output names a domain concept (in an issue title, a refactor proposal, a hypothesis, a test name), use the term as defined in `CONTEXT.md`. Don't drift to synonyms the glossary explicitly avoids.
+
+If the concept you need isn't in the glossary yet, that's a signal — either you're inventing language the project doesn't use (reconsider) or there's a real gap (note it for `atw-domain-modeling`).
+
+## Flag ADR conflicts
+
+If your output contradicts an existing ADR, surface it explicitly rather than silently overriding:
+
+> _Contradicts ADR-0007 (event-sourced orders) — but worth reopening because…_

package/dist/templates/common/bundled-skills/atw-init-repo/references/issue-tracker-atw-local.md

@@ -0,0 +1,133 @@
+# Issue tracker: ATW task directory (local only)
+
+This repo tracks work in the ATW task system. All issues — the spec and the implementation tickets for the task you are working on — live as markdown files in the current ATW task directory. There is no remote mirror: the task directory is the **sole authority**, and nothing is synced anywhere.
+
+## Resolving the current task directory
+
+Every path below is relative to the active task. Resolve it first:
+
+```bash
+TASK=$(python3 .atw/scripts/task.py current)
+```
+
+Bare `current` prints the repo-relative task directory. It **exits non-zero when there is no active task** — when that happens, stop and ask the user to create or start one. Do not fall back to `.scratch/`.
+
+## Conventions
+
+- **Spec**: `$TASK/prd.md`. Write the whole file; the skeleton `task.py create` wrote is meant to be overwritten. ATW treats the file as opaque text and parses nothing inside it.
+- **Implementation tickets**: one file per ticket at `$TASK/issues/<NN>-<slug>.md`, numbered from `01` in dependency order.
+- **Research notes**: `$TASK/research/<topic>.md`, one file per topic.
+- **Triage state**: not used on tickets in the task directory — see the `Status:` note below.
+- Comments and conversation history append to the bottom of the ticket file under a `## Comments` heading.
+
+## Ticket file fields
+
+On top of the standard ticket template, tickets here carry one extra line:
+
+```markdown
+# 01 — Ticket title
+
+**What to build:** the end-to-end behaviour this ticket makes work.
+
+**Blocked by:** None
+**Status:** ready-for-agent
+**Impl:** ready
+```
+
+| Field | Vocabulary | Who writes it |
+|---|---|---|
+| `Status:` | triage roles (see `triage-labels.md`) | Fixed at `ready-for-agent`. These tickets are ones you sliced yourself, so they never need triage — the field is a placeholder kept for vocabulary compatibility. |
+| `Impl:` | `ready` / `doing` / `done` | `tickets.py`. This is the field the workflow actually routes on, and the only field the parser requires. |
+
+The ticket template `tickets.py` writes also carries an empty `**Issue:**` line. It is meaningless in this variant — nothing fills it in — and `tickets.py` never reads it. Leave it or delete it; neither breaks anything.
+
+`Status:` and `Impl:` are deliberately separate. `Status:` answers "is this ticket clear enough, and who should pick it up"; `Impl:` answers "how far along is it". Folding implementation progress into `Status:` puts three unrelated vocabularies in one slot.
+
+## When a skill says "publish to the issue tracker"
+
+| Artifact | Destination |
+|---|---|
+| A spec | `$TASK/prd.md` |
+| Implementation tickets | `$TASK/issues/<NN>-<slug>.md` |
+
+The files **are** the tracker — there is no sync step and no remote to publish to.
+
+Do not apply a triage label when publishing here; these artifacts don't enter the triage queue.
+
+## When a skill says "fetch the relevant ticket"
+
+- A number like `01` or a filename → read `$TASK/issues/<NN>-*.md`.
+- No reference given → `python3 .atw/scripts/tickets.py frontier` and take the ticket currently at `Impl: doing`, or the first frontier ticket if none is claimed.
+
+## Ticket operations
+
+```bash
+python3 .atw/scripts/tickets.py list        # all tickets + Impl state
+python3 .atw/scripts/tickets.py frontier    # Impl: ready with all blockers done
+python3 .atw/scripts/tickets.py claim <NN>  # → Impl: doing
+python3 .atw/scripts/tickets.py done <NN>   # → Impl: done
+```
+
+`claim` refuses tickets that aren't on the frontier, and the parser rejects blocker references that don't exist or form a cycle. `claim` also records `implementation_base_sha` and writes the ticket's path into `$TASK/check.jsonl`, which is what review sub-agents read to know which ticket is live; `done` withdraws that line.
+
+**Tickets run one at a time by default.** `claim` hard-rejects a second ticket while another is at `Impl: doing`, but that check is read-then-write — it is serial execution, not an atomic exclusive claim. Don't run two implementers against one task directory.
+
+## Wayfinding operations
+
+Used by `atw-map`. A map is a **discover-phase** artifact and lives in the task directory alongside everything else.
+
+- **Map**: `$TASK/map.md` — the Notes / Decisions-so-far / Fog body.
+- **Child ticket**: `$TASK/map-issues/NN-<slug>.md`, numbered from `01`, with the question in the body. A `Type:` line records the ticket type (`research`/`prototype`/`interview`/`task`); a `Status:` line records `claimed`/`resolved`.
+- **Blocking**: a `Blocked by: NN, NN` line near the top. A ticket is unblocked when every file it lists is `resolved`.
+- **Frontier**: scan `$TASK/map-issues/` for files that are open, unblocked, and unclaimed; first by number wins.
+- **Claim**: set `Status: claimed` and save before any work.
+- **Resolve**: append the answer under an `## Answer` heading, set `Status: resolved`, then append a context pointer to Decisions-so-far in `map.md`.
+
+Decision tickets live in `map-issues/`, **not** `issues/`. They are questions whose resolution is a decision; `issues/` holds slices of a build to execute. They use different state vocabularies (`claimed`/`resolved` vs `Impl:`), and `tickets.py` only reads `issues/`. Mixing them makes the frontier calculation wrong in both directions.
+
+## What is *not* tracked here
+
+These stay at the repo root, unchanged:
+
+```text
+docs/adr/          architecture decisions          atw-domain-modeling
+CONTEXT.md         domain glossary                 atw-domain-modeling
+.out-of-scope/     rejected-concept records        atw-triage
+.atw/spec/         layered coding standards        ATW's own spec flow
+```
+
+They outlive any single task, so they don't belong in a directory that gets archived.
+
+## Re-enabling the GitHub mirror
+
+The mirror machinery ships with ATW, switched off. `.atw/scripts/github_sync.py` works; nothing calls it. Turning the mirror on means wiring it yourself in two places — there is no commented-out block to uncomment, so check your work against the commands given here.
+
+1. **`.atw/config.yaml`** — add a `hooks:` block. The file ships with a commented example that shows the shape but no sync wiring:
+
+   ```yaml
+   hooks:
+     after_create:
+       - "python3 .atw/scripts/github_sync.py create"
+     after_archive:
+       - "python3 .atw/scripts/github_sync.py archive"
+   ```
+
+   `task.py` sets `TASK_JSON_PATH` for you on the hook path, so these two need no environment prefix. Verify with `grep -n -A 6 "^hooks:" .atw/config.yaml` — you should see your two entries with no leading `#`.
+
+2. **`.atw/workflow.md`** — add the sync steps as phase completion conditions: `github_sync.py sync-spec` when the spec is written, `github_sync.py sync-tickets` when the tickets are sliced. Both are explicit commands, not hooks — ATW fires lifecycle hooks only on task create / start / finish / archive, and **there is no event for "a file was written"**. They take the `TASK_JSON_PATH=$TASK/task.json` prefix, because nothing sets it for you outside the hook path.
+
+3. **Replace this file** with the "ATW task directory + GitHub" variant, which documents the sync steps and the `**Issue:**` ticket field the sync fills in. The seed template ships inside the `atw-init-repo` skill folder as `references/issue-tracker-atw.md`; locate it with:
+
+   ```bash
+   find -L . -name "issue-tracker-atw.md" -not -path "./.git/*"
+   ```
+
+   The `-L` matters: skill folders are often symlinked between `.claude/skills/` and `.agents/skills/`, and a bare `find` walks past symlinked directories without descending into them, so it reports only one of the two paths.
+
+Historic tasks need no back-fill — from then on, `create` assigns each new task a fresh remote issue.
+
+## Why this variant exists
+
+Choosing the ATW task directory as the tracker does not have to mean choosing GitHub. This file covers the case where the task directory is all there is: a repo with no remote, a private/solo project, or a team that keeps planning artifacts out of the issue tracker on purpose.
+
+Nothing here is a degraded version of the mirrored variant — the task directory was already the authority in that one too. The only thing removed is the outbound copy.

package/dist/templates/common/bundled-skills/atw-init-repo/references/issue-tracker-atw.md

@@ -0,0 +1,109 @@
+# Issue tracker: ATW task directory + GitHub
+
+This repo tracks work in the ATW task system. Work is split across two places, and which one you use depends on **who raised the item**:
+
+| What | Where | Who triages it |
+|---|---|---|
+| Issues and PRs other people raised | GitHub Issues (`gh` CLI) | `atw-triage` runs here |
+| The spec and implementation tickets for the task you are working on now | The current ATW task directory | Nobody — these are agent-ready by construction |
+
+The task directory is the **authority**. Its contents are synced one-way out to GitHub as a mirror; never edit the mirror and expect it to come back.
+
+## Resolving the current task directory
+
+Every path below is relative to the active task. Resolve it first:
+
+```bash
+TASK=$(python3 .atw/scripts/task.py current)
+```
+
+Bare `current` prints the repo-relative task directory. It **exits non-zero when there is no active task** — when that happens, stop and ask the user to create or start one. Do not fall back to `.scratch/`.
+
+## Conventions
+
+- **Spec**: `$TASK/prd.md`. Write the whole file; the skeleton `task.py create` wrote is meant to be overwritten. ATW treats the file as opaque text and parses nothing inside it.
+- **Implementation tickets**: one file per ticket at `$TASK/issues/<NN>-<slug>.md`, numbered from `01` in dependency order.
+- **Research notes**: `$TASK/research/<topic>.md`, one file per topic.
+- **Triage state**: not used on tickets in the task directory — see the `Status:` note below.
+- Comments and conversation history live on the mirrored GitHub issue, not in the file.
+
+## Ticket file fields
+
+On top of the standard ticket template, tickets here carry two extra lines:
+
+```markdown
+# 01 — Ticket title
+
+**What to build:** the end-to-end behaviour this ticket makes work.
+
+**Blocked by:** None
+**Status:** ready-for-agent
+**Impl:** ready
+**Issue:**
+```
+
+| Field | Vocabulary | Who writes it |
+|---|---|---|
+| `Status:` | triage roles (see `triage-labels.md`) | Fixed at `ready-for-agent`. These tickets are ones you sliced yourself, so they never need triage — the field is a placeholder kept for vocabulary compatibility. |
+| `Impl:` | `ready` / `doing` / `done` | `tickets.py`. This is the field the workflow actually routes on, and the only field the parser requires. |
+| `Issue:` | `#58`, or empty | Filled in by `github_sync.py sync-tickets`; it is also the only ticket ↔ remote-issue mapping, so there is no separate mapping table. |
+
+`Status:` and `Impl:` are deliberately separate. `Status:` answers "is this ticket clear enough, and who should pick it up"; `Impl:` answers "how far along is it". Folding implementation progress into `Status:` puts three unrelated vocabularies in one slot.
+
+## When a skill says "publish to the issue tracker"
+
+| Artifact | Destination | Then |
+|---|---|---|
+| A spec | `$TASK/prd.md` | `TASK_JSON_PATH=$TASK/task.json python3 .atw/scripts/github_sync.py sync-spec` |
+| Implementation tickets | `$TASK/issues/<NN>-<slug>.md` | `TASK_JSON_PATH=$TASK/task.json python3 .atw/scripts/github_sync.py sync-tickets` |
+
+ATW fires lifecycle hooks only on task create / start / finish / archive — **there is no event for "a file was written"**, so the sync step above is something you run, not something that happens for you. It exits non-zero when it can't sync, because you asked for it explicitly; the `create` / `archive` hook path warns and exits 0 instead, so a sync failure never blocks creating or archiving a task.
+
+Do not apply a triage label when publishing here; these artifacts don't enter the triage queue.
+
+## When a skill says "fetch the relevant ticket"
+
+- A number like `01` or a filename → read `$TASK/issues/<NN>-*.md`.
+- A `#NN` GitHub reference → `gh issue view <NN>`. If it mirrors a local ticket, prefer the local file — that's the authority.
+- No reference given → `python3 .atw/scripts/tickets.py frontier` and take the ticket currently at `Impl: doing`, or the first frontier ticket if none is claimed.
+
+## Ticket operations
+
+```bash
+python3 .atw/scripts/tickets.py list        # all tickets + Impl state
+python3 .atw/scripts/tickets.py frontier    # Impl: ready with all blockers done
+python3 .atw/scripts/tickets.py claim <NN>  # → Impl: doing
+python3 .atw/scripts/tickets.py done <NN>   # → Impl: done
+```
+
+`claim` refuses tickets that aren't on the frontier, and the parser rejects blocker references that don't exist or form a cycle. `claim` also records `implementation_base_sha` and writes the ticket's path into `$TASK/check.jsonl`, which is what review sub-agents read to know which ticket is live; `done` withdraws that line.
+
+**Tickets run one at a time by default.** `claim` hard-rejects a second ticket while another is at `Impl: doing`, but that check is read-then-write — it is serial execution, not an atomic exclusive claim. Don't run two implementers against one task directory.
+
+## Wayfinding operations
+
+Used by `atw-map`. A map is a **discover-phase** artifact and lives in the task directory alongside everything else.
+
+- **Map**: `$TASK/map.md` — the Notes / Decisions-so-far / Fog body.
+- **Child ticket**: `$TASK/map-issues/NN-<slug>.md`, numbered from `01`, with the question in the body. A `Type:` line records the ticket type (`research`/`prototype`/`interview`/`task`); a `Status:` line records `claimed`/`resolved`.
+- **Blocking**: a `Blocked by: NN, NN` line near the top. A ticket is unblocked when every file it lists is `resolved`.
+- **Frontier**: scan `$TASK/map-issues/` for files that are open, unblocked, and unclaimed; first by number wins.
+- **Claim**: set `Status: claimed` and save before any work.
+- **Resolve**: append the answer under an `## Answer` heading, set `Status: resolved`, then append a context pointer to Decisions-so-far in `map.md`.
+
+Decision tickets live in `map-issues/`, **not** `issues/`. They are questions whose resolution is a decision; `issues/` holds slices of a build to execute. They use different state vocabularies (`claimed`/`resolved` vs `Impl:`), and `tickets.py` only reads `issues/`. Mixing them makes the frontier calculation wrong in both directions.
+
+Map child tickets are not synced to GitHub — they are working notes for one effort's discover phase, and they resolve fast.
+
+## What is *not* tracked here
+
+These stay at the repo root, unchanged:
+
+```text
+docs/adr/          architecture decisions          atw-domain-modeling
+CONTEXT.md         domain glossary                 atw-domain-modeling
+.out-of-scope/     rejected-concept records        atw-triage
+.atw/spec/         layered coding standards        ATW's own spec flow
+```
+
+They outlive any single task, so they don't belong in a directory that gets archived.