@chinhae/atw-cli 0.1.0

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

@@ -0,0 +1,45 @@
+# Issue tracker: GitHub
+
+Issues and specs for this repo live as GitHub issues. Use the `gh` CLI for all operations.
+
+## Conventions
+
+- **Create an issue**: `gh issue create --title "..." --body "..."`. Use a heredoc for multi-line bodies.
+- **Read an issue**: `gh issue view <number> --comments`, filtering comments by `jq` and also fetching labels.
+- **List issues**: `gh issue list --state open --json number,title,body,labels,comments --jq '[.[] | {number, title, body, labels: [.labels[].name], comments: [.comments[].body]}]'` with appropriate `--label` and `--state` filters.
+- **Comment on an issue**: `gh issue comment <number> --body "..."`
+- **Apply / remove labels**: `gh issue edit <number> --add-label "..."` / `--remove-label "..."`
+- **Close**: `gh issue close <number> --comment "..."`
+
+Infer the repo from `git remote -v` — `gh` does this automatically when run inside a clone.
+
+## Pull requests as a triage surface
+
+**PRs as a request surface: no.** _(Set to `yes` if this repo treats external PRs as feature requests; `atw-triage` reads this flag.)_
+
+When set to `yes`, PRs run through the same labels and states as issues, using the `gh pr` equivalents:
+
+- **Read a PR**: `gh pr view <number> --comments` and `gh pr diff <number>` for the diff.
+- **List external PRs for triage**: `gh pr list --state open --json number,title,body,labels,author,authorAssociation,comments` then keep only `authorAssociation` of `CONTRIBUTOR`, `FIRST_TIME_CONTRIBUTOR`, or `NONE` (drop `OWNER`/`MEMBER`/`COLLABORATOR`).
+- **Comment / label / close**: `gh pr comment`, `gh pr edit --add-label`/`--remove-label`, `gh pr close`.
+
+GitHub shares one number space across issues and PRs, so a bare `#42` may be either — resolve with `gh pr view 42` and fall back to `gh issue view 42`.
+
+## When a skill says "publish to the issue tracker"
+
+Create a GitHub issue.
+
+## When a skill says "fetch the relevant ticket"
+
+Run `gh issue view <number> --comments`.
+
+## Wayfinding operations
+
+Used by `atw-map`. The **map** is a single issue with **child** issues as tickets.
+
+- **Map**: a single issue labelled `atw-map:map`, holding the Notes / Decisions-so-far / Fog body. `gh issue create --label atw-map:map`.
+- **Child ticket**: an issue linked to the map as a GitHub sub-issue (`gh api` on the sub-issues endpoint). Where sub-issues aren't enabled, add the child to a task list in the map body and put `Part of #<map>` at the top of the child body. Labels: `atw-map:<type>` (`research`/`prototype`/`interview`/`task`). Once claimed, the ticket is assigned to the driving dev.
+- **Blocking**: GitHub's **native issue dependencies** — the canonical, UI-visible representation. Add an edge with `gh api --method POST repos/<owner>/<repo>/issues/<child>/dependencies/blocked_by -F issue_id=<blocker-db-id>`, where `<blocker-db-id>` is the blocker's numeric **database id** (`gh api repos/<owner>/<repo>/issues/<n> --jq .id`, _not_ the `#number` or `node_id`). GitHub reports `issue_dependencies_summary.blocked_by` (open blockers only — the live gate). Where dependencies aren't available, fall back to a `Blocked by: #<n>, #<n>` line at the top of the child body. A ticket is unblocked when every blocker is closed.
+- **Frontier query**: list the map's open children (`gh issue list --state open`, scoped to the map's sub-issues / task list), drop any with an open blocker (`issue_dependencies_summary.blocked_by > 0`, or an open issue in the `Blocked by` line) or an assignee; first in map order wins.
+- **Claim**: `gh issue edit <n> --add-assignee @me` — the session's first write.
+- **Resolve**: `gh issue comment <n> --body "<answer>"`, then `gh issue close <n>`, then append a context pointer (gist + link) to the map's Decisions-so-far.

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

@@ -0,0 +1,46 @@
+# Issue tracker: GitLab
+
+Issues and specs for this repo live as GitLab issues. Use the [`glab`](https://gitlab.com/gitlab-org/cli) CLI for all operations.
+
+## Conventions
+
+- **Create an issue**: `glab issue create --title "..." --description "..."`. Use a heredoc for multi-line descriptions. Pass `--description -` to open an editor.
+- **Read an issue**: `glab issue view <number> --comments`. Use `-F json` for machine-readable output.
+- **List issues**: `glab issue list -F json` with appropriate `--label` filters.
+- **Comment on an issue**: `glab issue note <number> --message "..."`. GitLab calls comments "notes".
+- **Apply / remove labels**: `glab issue update <number> --label "..."` / `--unlabel "..."`. Multiple labels can be comma-separated or by repeating the flag.
+- **Close**: `glab issue close <number>`. `glab issue close` does not accept a closing comment, so post the explanation first with `glab issue note <number> --message "..."`, then close.
+- **Merge requests**: GitLab calls PRs "merge requests". Use `glab mr create`, `glab mr view`, `glab mr note`, etc. — the same shape as `gh pr ...` with `mr` in place of `pr` and `note`/`--message` in place of `comment`/`--body`.
+
+Infer the repo from `git remote -v` — `glab` does this automatically when run inside a clone.
+
+## Merge requests as a triage surface
+
+**MRs as a request surface: no.** _(Set to `yes` if this repo treats external merge requests as feature requests; `atw-triage` reads this flag.)_
+
+When set to `yes`, MRs run through the same labels and states as issues, using the `glab mr` equivalents:
+
+- **Read an MR**: `glab mr view <number> --comments` and `glab mr diff <number>` for the diff.
+- **List external MRs for triage**: `glab mr list -F json`, then keep only MRs whose author is not a project member/owner (a contributor's MR, not a maintainer's in-flight work).
+- **Comment / label / close**: `glab mr note`, `glab mr update --label`/`--unlabel`, `glab mr close`.
+
+Unlike GitHub, GitLab numbers issues and MRs separately, so `#42` is unambiguous once you know which surface the maintainer means.
+
+## When a skill says "publish to the issue tracker"
+
+Create a GitLab issue.
+
+## When a skill says "fetch the relevant ticket"
+
+Run `glab issue view <number> --comments`.
+
+## Wayfinding operations
+
+Used by `atw-map`. The **map** is a single issue with **child** issues as tickets.
+
+- **Map**: a single issue labelled `atw-map:map`, holding the Notes / Decisions-so-far / Fog body. `glab issue create --label atw-map:map`. (On GitLab tiers with native epics, an epic may hold the map instead; a labelled issue works everywhere.)
+- **Child ticket**: an issue carrying `Part of #<map>` at the top of its description and labels `atw-map:<type>` (`research`/`prototype`/`interview`/`task`). Once claimed, the ticket is assigned to the driving dev.
+- **Blocking**: GitLab's **native blocking link** — the canonical, UI-visible representation. Add it with the `/blocked_by #<n>` quick action, posted as a note (`glab issue note <child> --message "/blocked_by #<blocker>"`). Native blocking links are a Premium/Ultimate feature; on the free tier (or where unavailable) fall back to a `Blocked by: #<n>, #<n>` line at the top of the description. A ticket is unblocked when every blocker is closed.
+- **Frontier query**: `glab issue list -F json` scoped to the map's children, drop any with an open blocker — a native `blocked_by` link to an open issue (`glab api projects/:id/issues/:iid/links`), or an open issue in the `Blocked by` line — or an assignee; first in map order wins.
+- **Claim**: `glab issue update <n> --assignee @me` — the session's first write.
+- **Resolve**: `glab issue note <n> --message "<answer>"`, then `glab issue close <n>`, then append a context pointer (gist + link) to the map's Decisions-so-far.

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

@@ -0,0 +1,30 @@
+# Issue tracker: Local Markdown
+
+Issues and specs for this repo live as markdown files in `.scratch/`.
+
+## Conventions
+
+- One feature per directory: `.scratch/<feature-slug>/`
+- The spec is `.scratch/<feature-slug>/spec.md`
+- Implementation issues are one file per ticket at `.scratch/<feature-slug>/issues/<NN>-<slug>.md`, numbered from `01` — never a single combined tickets file
+- Triage state is recorded as a `Status:` line near the top of each issue file (see `triage-labels.md` for the role strings)
+- Comments and conversation history append to the bottom of the file under a `## Comments` heading
+
+## When a skill says "publish to the issue tracker"
+
+Create a new file under `.scratch/<feature-slug>/` (creating the directory if needed).
+
+## When a skill says "fetch the relevant ticket"
+
+Read the file at the referenced path. The user will normally pass the path or the issue number directly.
+
+## Wayfinding operations
+
+Used by `atw-map`. The **map** is a file with one **child** file per ticket.
+
+- **Map**: `.scratch/<effort>/map.md` — the Notes / Decisions-so-far / Fog body.
+- **Child ticket**: `.scratch/<effort>/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 `.scratch/<effort>/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 (gist + link) to the map's Decisions-so-far in `map.md`.

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

@@ -0,0 +1,15 @@
+# Triage Labels
+
+The skills speak in terms of five canonical triage roles. This file maps those roles to the actual label strings used in this repo's issue tracker.
+
+| Canonical role             | Label in our tracker | Meaning                                  |
+| -------------------------- | -------------------- | ---------------------------------------- |
+| `needs-triage`             | `needs-triage`       | Maintainer needs to evaluate this issue  |
+| `needs-info`               | `needs-info`         | Waiting on reporter for more information |
+| `ready-for-agent`          | `ready-for-agent`    | Fully specified, ready for an AFK agent  |
+| `ready-for-human`          | `ready-for-human`    | Requires human implementation            |
+| `wontfix`                  | `wontfix`            | Will not be actioned                     |
+
+When a skill mentions a role (e.g. "apply the AFK-ready triage label"), use the corresponding label string from this table.
+
+Edit the right-hand column to match whatever vocabulary you actually use.

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

@@ -0,0 +1,22 @@
+---
+name: atw-interview
+description: "就某项计划、决策或想法对用户进行无休止的追问。当用户希望对自己的思路进行压力测试，或使用了任何“追问”类触发短语时，可使用此功能。"
+---
+
+Interview the user relentlessly until you reach a shared understanding. Map this as a **design tree**: every decision branches into the decisions that hang off it.
+
+Work the tree in **rounds**. The **frontier** is every decision whose prerequisites are already settled — the questions you can ask _now_ without guessing at answers you haven't heard yet. Ask the whole frontier in one round: number each question and give your recommended answer. Then wait for the user's answers before the next round.
+
+Each question should be formatted like so:
+
+```
+❓ **Q1** - **<question title>**: <question body, might be multiple paragraphs, including multiple choices>
+
+➡️ <your recommended answer>
+```
+
+Each round the user answers reshapes the tree — settled decisions push the frontier outward and unblock questions that depended on them. Recompute the frontier and ask the next round. A question whose answer depends on another question still open in this round belongs to a _later_ round, not this one.
+
+Finding _facts_ is your job, never the user's. When a frontier question needs a fact from the environment (filesystem, tools, etc.), dispatch a sub-agent to find it — don't ask the user for anything you could look up yourself. Don't block on it: a running exploration is an unsettled prerequisite, so only the questions downstream of it wait for the sub-agent to report — ask the rest of the frontier now. The _decisions_ are the user's — put each to them and wait.
+
+The session is done when the frontier is empty: every branch of the design tree visited, nothing left silently assumed. Do not act on it until the user confirms you have reached a shared understanding.

package/dist/templates/common/bundled-skills/atw-interview/agents/openai.yaml

@@ -0,0 +1,3 @@
+interface:
+  display_name: "Oxyteam Interview"
+  short_description: "通过决策树逐轮澄清计划、方案和关键决策"

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

@@ -0,0 +1,128 @@
+---
+name: atw-map
+description: "将一大批工作（超过一个代理会话所能处理的范围）规划为问题跟踪系统中决策工单的共享地图，并逐一解决这些工单，直到通往目标的道路畅通无阻。"
+disable-model-invocation: true
+---
+
+A loose idea has arrived — too big for one agent session, and wrapped in fog: the way from here to the **destination** isn't visible yet. Wayfinding is about finding that way, not charging at the destination. This skill charts the way as a **shared map** on the repo's issue tracker, then works its **decision tickets** — questions whose resolution is a decision, not slices of a build to execute — one at a time until the route is clear.
+
+The destination varies per effort, and naming it is the first act of charting — it shapes every ticket. It might be a spec to hand off and iterate on, a decision to lock before planning starts, or a change made in place like a data-structure migration. The map is domain-agnostic — engineering work, course content, whatever fits the shape.
+
+## Plan, don't do
+
+atw-map is **planning** by default: each ticket resolves a decision, and the map is done when the way is clear — nothing left to decide before someone goes and does the thing. The pull to just do the work is usually the signal you've reached the edge of the map and it's time to hand off. An effort can override this in its **Notes** — carrying execution into the map itself — but absent that, produce decisions, not deliverables.
+
+## Refer by name
+
+Every map and ticket is an issue, so it has a **name** — its title. In everything the human reads — narration, the map's Decisions-so-far — refer to it by that name, never by a bare id, number, or slug. A wall of `#42, #43, #44` is illegible; names read at a glance. The id and URL don't vanish — a name wraps its link — but they ride _inside_ the name, never stand in for it.
+
+## The Map
+
+The map is a single issue on this repo's issue tracker, labelled `atw-map:map` — the canonical artifact. Its tickets are child issues of the map.
+
+The map is an **index**, not a store. It lists the decisions made and points at the tickets that hold their detail; a decision lives in exactly one place — its ticket — so the map never restates it, only gists it and links.
+
+**Where the map, its child tickets, blocking, and frontier queries physically live is tracker-specific.** The issue tracker should have been provided to you. If not, tell the user to call the Skill tool for `atw-init-repo`, which asks which tracker this repo uses and writes that file. Consult the tracker doc's "Wayfinding operations" section for how _this_ repo expresses them. If no tracker has been provided, default to the local-markdown tracker.
+
+### The map body
+
+The whole map at low resolution, loaded once per session. Open tickets are **not** listed — they are open child issues, found by query.
+
+```markdown
+## Destination
+
+<what reaching the end of this map looks like — the spec, decision, or change this effort is finding its way to. One or two lines; every session orients to it before choosing a ticket.>
+
+## Notes
+
+<domain; skills every session should consult; standing preferences for this effort>
+
+## Decisions so far
+
+<!-- the index — one line per closed ticket: enough to judge relevance, then zoom the link for the detail the ticket holds -->
+
+- [<closed ticket title>](link) — <one-line gist of the answer>
+
+## Not yet specified
+
+<!-- see "Fog of war": in-scope fog you can't ticket yet; graduates as the frontier advances -->
+
+## Out of scope
+
+<!-- see "Out of scope": work ruled beyond the destination; closed, never graduates -->
+```
+
+### Tickets
+
+Each ticket is a **child issue** of the map; the tracker's issue id is its identity. Its body is the question, sized to one 100K token agent session:
+
+```markdown
+## Question
+
+<the decision or investigation this ticket resolves>
+```
+
+Each ticket carries a `atw-map:<type>` label — one of `research`, `prototype`, `interview`, `task` (see [Ticket Types](#ticket-types)).
+
+A session **claims** a ticket by assigning it to the dev driving the map, **first**, before any work, so concurrent sessions skip it. That assignee _is_ the claim: an open, unassigned ticket is unclaimed.
+
+Blocking uses the tracker's **native** dependency relationship — essential because it renders the frontier _visually_ in the tracker's own UI, so the human sees what's takeable without opening the map. Only a tracker that lacks native blocking falls back to a body convention. A ticket is **unblocked** when every ticket blocking it is closed; the **frontier** is the open, unblocked, unclaimed children — the edge of the known.
+
+The answer isn't part of the body — it's recorded on resolution (see [Work through the map](#work-through-the-map)). Assets created while resolving a ticket are linked from the issue, not pasted in.
+
+## Ticket Types
+
+Every ticket is either **HITL** — human in the loop, worked _with_ a human who speaks for themselves — or **AFK**, driven by the agent alone. A HITL ticket only resolves through that live exchange; the agent never stands in for the human's side of it (an interview agent that answers its own questions has broken this).
+
+- **Research** (AFK): Reading documentation, third-party APIs, or local resources like knowledge bases to surface a fact a decision waits on. Resolved by a subagent that calls the Skill tool with "atw-research". Use when knowledge outside the current working directory is required.
+- **Prototype** (HITL): Raise the fidelity of the discussion by making a cheap, rough, concrete artifact to react to — an outline, a rough take, a stub, or UI/logic code, by calling the Skill tool with "atw-prototype". Links the prototype as an asset. Use when "how should it look" or "how should it behave" is the key question.
+- **Interview** (HITL): Conversation. The default case. Always call the Skill tool twice, for "atw-interview" and "atw-domain-modeling".
+- **Task** (HITL or AFK): Manual work that must happen before a _decision_ can be made — nothing to decide, prototype, or research, but the discussion is blocked until it's done. Signing up for a service so its API can be judged, provisioning access, moving data so its shape can be seen. This is the one type that _does_ rather than decides — and it earns its place by unblocking a decision, not by delivering the destination. The agent drives it alone where it can (AFK); otherwise it hands the human a precise checklist (HITL). Resolved when the work is done; the answer records what was done and any resulting facts (credentials location, new URLs, row counts) later tickets depend on.
+
+## Fog of war
+
+The map is _deliberately_ incomplete: don't chart what you can't yet see. Beyond the live tickets lies the **fog of war** — the dim view of decisions and investigations you can tell are coming but can't yet pin down, because they hang on questions still open. Resolving a ticket clears the fog ahead of it, graduating whatever's now specifiable into fresh tickets — one at a time, until the way to the destination is clear and no tickets remain.
+
+The map's **Not yet specified** section is where that dim view is written down: the suspected question, the area to revisit later. It's the undiscovered frontier _toward_ the destination — everything here is in scope, just not sharp enough to ticket. Write as loosely or as fully as the view allows; it doubles as a signpost for collaborators reading where the effort is headed.
+
+**Fog or ticket?** The test is whether you can state the question precisely now — _not_ whether you can answer it now.
+
+- **Ticket when** the question is already sharp — even if it's blocked and you can't act on it yet.
+- **Not yet specified when** you can't yet phrase it that sharply. Don't pre-slice the fog into ticket-sized pieces: it's coarser than a ticket, and one patch may graduate into several tickets, or none, once the frontier reaches it.
+
+**Not yet specified** excludes what's already decided (Decisions so far), what's already a live ticket, and what's out of scope (the next section).
+
+## Out of scope
+
+Fog only ever gathers _toward_ the destination. The destination fixes the scope, so work beyond it is **out of scope** — it isn't fog, and it doesn't belong in **Not yet specified**. It gets its own **Out of scope** section on the map: work you've consciously ruled out of _this_ effort. Scope, not sharpness, lands it here.
+
+Out-of-scope work never graduates — the frontier stops at the destination — so it returns only if the destination is redrawn, and then as a fresh effort, not a resumption.
+
+Ruling something out of scope is a scoping act, not a step on the route. When a ticket that already exists turns out to sit past the destination — mis-scoped in while charting, or exposed by a resolution — **close it** (a closed ticket is unambiguously off the frontier) and leave one line in the **Out of scope** section: the gist plus why it's out of scope, linking the closed ticket. It stays out of **Decisions so far**, which records the route actually walked — a scope boundary isn't a step on it.
+
+## Invocation
+
+Two modes. Either way, **never resolve more than one ticket per session** — with the exception of research tickets.
+
+### Chart the map
+
+User invokes with a loose idea.
+
+1. **Name the destination.** Call the Skill tool twice, for "atw-interview" and "atw-domain-modeling", to pin down what this map is finding its way to — the spec, decision, or change. The destination fixes the scope, so it's settled first.
+2. **Map the frontier.** Interview again, **breadth-first** this time: fan out across the whole space rather than deep on any one thread, surfacing the open decisions and the first steps takeable now. **If this surfaces no fog** — the way to the destination is already clear, the whole journey small enough for one session — you don't need a map. Stop and ask the user how they'd like to proceed.
+3. **Create the map** (label `atw-map:map`): Destination and Notes filled in, Decisions-so-far empty, the fog sketched into **Not yet specified**.
+4. **Create the tickets you can specify now** as child issues of the map — then wire blocking edges in a **second pass** (issues need ids before they can reference each other). Wiring sorts them into the frontier and the blocked; everything you can't yet specify stays in the fog — the **Not yet specified** section.
+5. **Fire the research subagents.** For each `research` ticket you just created, spin up a subagent that calls the Skill tool with "atw-research" to resolve it in parallel, capturing its findings on a throwaway `research/<name>` branch with a context pointer from the ticket.
+6. Stop — charting is one session's work; it hand-resolves nothing.
+
+### Work through the map
+
+User invokes with a map (URL or number). A ticket is **optional** — without one, you pick the next decision, not the user.
+
+1. Load the **map** — the low-res view, not every ticket body.
+2. Choose the ticket. If the user named one, use it. Otherwise take the first frontier ticket in order. **Claim it**: assign it to yourself before any work.
+3. Resolve it — **zoom as needed**: fetch the full body of any related or closed ticket on demand; call the Skill tool for whichever skills the `## Notes` block names. If in doubt, call the Skill tool twice, for "atw-interview" and "atw-domain-modeling".
+4. Record the resolution: post the answer as a **resolution comment**, **close** the issue, and **append a context pointer** to the map's Decisions-so-far.
+5. Add newly-surfaced tickets (create-then-wire); graduate any fog the answer has made specifiable, clearing each graduated patch from **Not yet specified** so it lives only as its new ticket. If the answer reveals a ticket — this one or another — sits beyond the destination, **rule it out of scope** rather than resolving it on the route. If the decision invalidates other parts of the map, update or delete those tickets.
+
+The user may run unblocked tickets in parallel, so expect other sessions to be editing the tracker concurrently.

package/dist/templates/common/bundled-skills/atw-map/agents/openai.yaml

@@ -0,0 +1,5 @@
+interface:
+  display_name: "Oxyteam Map"
+  short_description: "将大型工作任务映射为决策工单"
+policy:
+  allow_implicit_invocation: false

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

@@ -0,0 +1,14 @@
+---
+name: atw-merge
+description: "当您需要解决正在进行的git合并/变基冲突时使用。"
+---
+
+1. **See the current state** of the merge/rebase. Check git history, and the conflicting files.
+
+2. **Find the primary sources** for each conflict. Understand deeply why each change was made, and what the original intent was. Read the commit messages, check the PRs, check original issues/tickets.
+
+3. **Resolve each hunk.** Preserve both intents where possible. Where incompatible, pick the one matching the merge's stated goal and note the trade-off. Do **not** invent new behaviour. Always resolve; never `--abort`.
+
+4. Discover the project's **automated checks** and run them — typically typecheck, then tests, then format. Fix anything the merge broke.
+
+5. **Finish the merge/rebase.** Stage everything and commit. If rebasing, continue the rebase process until all commits are rebased.

package/dist/templates/common/bundled-skills/atw-merge/agents/openai.yaml

@@ -0,0 +1,3 @@
+interface:
+  display_name: "Oxyteam Merge"
+  short_description: "解决合并与变基冲突"

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

@@ -0,0 +1,85 @@
+---
+name: atw-meta
+description: "Understand and customize the local ATW architecture inside a user project. Use when modifying .atw plus platform hooks, settings, agents, skills, commands, prompts, workflows, the channel runtime (atw channel), bundled runtime agents under .atw/agents/, selectable workflow templates, registry-backed spec refresh, cross-session memory (atw mem) generated by atw init, or AI-facing bundled skills (atw-channel, atw-session-insight, atw-spec-bootstrap) and bundled-skill auto-dispatch flow."
+---
+
+# ATW Meta
+
+This skill is for local ATW users who have already run `atw init` in a project. After reading it, an AI should understand the ATW architecture, operating model, and customization entry points inside that user project, then modify the generated `.atw/` and platform directory files according to the user's request.
+
+Beyond the workflow / persistence / platform model, ATW has three further architectural surfaces. First, a multi-agent collaboration runtime: `atw channel` coordinates multiple AI worker processes through project-scoped JSONL event logs at `~/.atw/channels/<project>/<channel>/events.jsonl`, with worker OOM guard, forum/thread channels, durable idempotency keys, and bundled `.atw/agents/{review,implement-agent}.md` runtime definitions. Second, cross-session memory: `atw mem list | search | context | extract | projects` reads raw Claude Code, Codex, and Pi Agent JSONL already on disk, slices by `--phase brainstorm|implement|all`, and never uploads anything. Third, a dual-package npm release: `@chinhae/atw-cli` (CLI) and `@chinhae/atw-core` (SDK with `/channel`, `/task`, `/mem`, `/testing` subpaths) ship in lockstep on one version. Treat these as first-class customization surfaces alongside the per-platform integration files.
+
+The default operating scope is local files in the user project:
+
+- `.atw/`: workflow, config, tasks, spec, workspace, scripts, bundled runtime agents, and runtime state.
+- Platform directories: `.claude/`, `.codex/`, `.cursor/`, `.opencode/`, `.kiro/`, `.gemini/`, `.qoder/`, `.codebuddy/`, `.github/`, `.factory/`, `.pi/`, `.reasonix/`, `.kilocode/`, `.agent/`, `.devin/`, `.kimi-code/`, and similar directories. Pi additionally exposes a native `atw_subagent` tool with `single` / `parallel` / `chain` dispatch modes, throttled progress cards, and `isAtwAgent()` validation on top of the file layout. Reasonix stores both workflow skills and subagent skills as `.reasonix/skills/<name>/SKILL.md`; subagent skills carry `runAs: subagent` frontmatter. Kimi Code keeps workflow skills in the shared `.agents/skills/` layer, delivers commands plus agent prompts as `.kimi-code/skills/<name>/SKILL.md`, and installs the same agent prompts as custom sub-agents under `.kimi-code/agents/<name>.md`.
+- Shared skill layer: `.agents/skills/`.
+- User-owned channel store outside the project tree: `~/.atw/channels/<project>/<channel>/events.jsonl`.
+- Raw platform conversation logs queryable via `atw mem`: `~/.claude/projects/`, `~/.codex/sessions/`, and `~/.pi/agent/sessions/`, plus OpenCode's SQLite session store under its XDG data directory.
+
+Do not assume the user has the ATW source repository. Do not default to modifying the global npm install directory or `node_modules` — both `@chinhae/atw-cli` and `@chinhae/atw-core` ship as published packages sharing one version and one git tag per release.
+
+## How To Use
+
+1. Read `references/local-architecture/overview.md` first to establish the local ATW system model.
+2. If the request involves a specific AI tool, read `references/platform-files/platform-map.md` and the relevant platform file notes.
+3. If the request involves multi-agent dispatch or channel workers, read `references/local-architecture/multi-agent-channel.md` and the bundled `.atw/agents/` files.
+4. If the user wants to change behavior, read `references/customize-local/overview.md`, then open the specific customization topic.
+5. Before editing, read the actual files in the user project and treat local content as authoritative.
+
+## References
+
+### Local Architecture
+
+- `references/local-architecture/overview.md`: The layered local ATW architecture (workflow / persistence / platform / channel runtime) and customization principles.
+- `references/local-architecture/generated-files.md`: Files generated by `atw init` and their customization boundaries, including `.atw/agents/`.
+- `references/local-architecture/workflow.md`: Phases, routing, workflow-state blocks, and selectable workflow templates (`native`, `tdd`, `channel-driven-subagent-dispatch`, marketplace) in `.atw/workflow.md`.
+- `references/local-architecture/task-system.md`: Task directories, active task, JSONL context, parent/child task trees, and task runtime.
+- `references/local-architecture/spec-system.md`: How `.atw/spec/` is organized, injected, and refreshed from a `registry.spec` source.
+- `references/local-architecture/workspace-memory.md`: `.atw/workspace/` journals plus `atw mem` cross-session recall and the `@chinhae/atw-core/mem` SDK.
+- `references/local-architecture/context-injection.md`: Hooks, sub-agent preludes, and channel-runtime worker inbox routing.
+- `references/local-architecture/multi-agent-channel.md`: `atw channel` subcommands, project-scoped event store, forum/thread channels, worker OOM guard, durable idempotency, and bundled `.atw/agents/` runtime agents.
+- `references/local-architecture/bundled-skills.md`: Auto-dispatched bundled skills (`atw-meta`, `atw-spec-bootstrap`, `atw-session-insight`) and how `getBundledSkillTemplates()` ships them to every platform skill root.
+
+### Platform Files
+
+- `references/platform-files/overview.md`: How shared `.atw/` files relate to platform directories and the four platform integration modes (hook-driven, agent prelude, main-session workflow, channel runtime).
+- `references/platform-files/platform-map.md`: Platform directories and paths for skills, agents, hooks, and extensions across all supported platforms including Reasonix and Pi's native `atw_subagent` extension.
+- `references/platform-files/hooks-and-settings.md`: How settings/config files, hooks, plugins, and extensions connect to ATW; covers `channel.worker_guard.*` and `codex.dispatch_mode`.
+- `references/platform-files/agents.md`: Per-platform `atw-review` / `atw-implement-agent` sub-agent files plus bundled `.atw/agents/{review,implement-agent}.md` for the channel runtime.
+- `references/platform-files/skills-and-commands.md`: Differences between skills, commands, prompts, and workflows, plus how to change them.
+
+### Local Customization
+
+- `references/customize-local/overview.md`: Choose the right local customization entry point for the user's request.
+- `references/customize-local/change-workflow.md`: Change phases, routing, next actions, workflow-state, and the selected workflow template.
+- `references/customize-local/change-task-lifecycle.md`: Change task creation, status, archive behavior, parent/child links, archive slug collision handling, and lifecycle hooks.
+- `references/customize-local/change-context-loading.md`: Change how tasks, specs, journals, hook context, channel inbox messages, and `atw mem` recall are loaded.
+- `references/customize-local/change-hooks.md`: Change platform hooks, settings, task lifecycle hooks (`hooks.after_*`), and shell session bridges.
+- `references/customize-local/change-agents.md`: Change review and implement agent behavior across platform sub-agents, bundled channel runtime agents, and the Codex `dispatch_mode` toggle.
+- `references/customize-local/change-skills-or-commands.md`: Add or modify local skills, commands, prompts, and workflows; covers upstream bundled-skill auto-dispatch.
+- `references/customize-local/change-spec-structure.md`: Adjust the project spec structure under `.atw/spec/`, including registry-backed sources.
+- `references/customize-local/add-project-local-conventions.md`: Put team rules into project-local specs or local skills.
+
+## Current Rules
+
+- `.atw/workflow.md` is the local workflow source of truth; its initial content was selected from a workflow template (built-in `native`, `tdd`, `channel-driven-subagent-dispatch`, or a marketplace template) at `atw init` time and can be re-selected via `atw workflow --template <id>`. Missing `.atw/agents/<name>.md` files referenced by the active template trigger a non-blocking stderr warning pointing at `atw update`.
+- `.atw/config.yaml` is the project-level ATW configuration entry point. It hosts task lifecycle hooks (`hooks.after_create` / `after_start` / `after_finish` / `after_archive`), journal shape (`session_commit_message` / `max_journal_lines` / `session_auto_commit`), channel worker guard (`channel.worker_guard.idle_timeout` / `max_live_workers`), Codex dispatch mode (`codex.dispatch_mode: inline | sub-agent`), and the spec registry block (`registry.spec.source` + `registry.spec.template`).
+- `.atw/spec/` stores the user's project-specific coding conventions and design constraints. When `registry.spec` is set, files are refreshed by `atw update`; local edits surface as "modified by user" conflicts in `.atw/.template-hashes.json`.
+- `.atw/tasks/` stores task PRDs, research files, and JSONL context. Tasks form parent/child trees: `task.py create --parent <slug>`, `task.py add-subtask <parent> <child>`, `task.py remove-subtask <parent> <child>`, and `task.py list-context <task>`. `task.py create` rejects a slug already present in `.atw/tasks/archive/**`.
+- `.atw/workspace/` stores **deliberately written** developer journals. Raw cross-session dialogue is **not** stored here — it lives on disk under `~/.claude/projects/`, `~/.codex/sessions/`, and `~/.pi/agent/sessions/` and is recovered via `atw mem search|extract|context`. The bundled `atw-session-insight` skill teaches when to reach for `mem`.
+- `.atw/agents/{review,implement-agent}.md` are bundled, platform-agnostic channel runtime agent definitions loaded by `atw channel spawn --agent <name>`. Editable; `atw update` backfills missing ones. Editing the per-platform `atw-implement-agent.md` / `atw-review.md` does **not** change channel-runtime worker behavior.
+- `~/.atw/channels/<project>/<channel>/events.jsonl` is the channel runtime event log per project per channel. User-owned, file-locked sequence numbering, durable `idempotencyKey` support; never under `.atw/`.
+- Bundled multi-file skills (`atw-meta`, `atw-spec-bootstrap`, `atw-session-insight`, `atw-channel`) are auto-dispatched to every platform skill root by `getBundledSkillTemplates()` in `packages/cli/src/templates/common/index.ts`. Dropping a new directory under `packages/cli/src/templates/common/bundled-skills/` (upstream) ships it to every platform on the next `atw update`.
+- Platform settings/config files decide which hooks, agents, skills, commands, prompts, and workflows actually run. Reasonix has no settings file — behavior is encoded inside skill frontmatter.
+- `.atw/.template-hashes.json` and `.atw/.runtime/` are management/runtime state files. Confirm necessity before editing them.
+
+## Do Not
+
+- Do not treat ATW upstream source code as the default target for local customization.
+- Do not modify the global npm install directory or `node_modules/@chinhae/atw-cli` or `node_modules/@chinhae/atw-core` to implement project needs; both packages ship in lockstep.
+- Do not overwrite user-modified local files with default templates; check `.atw/.template-hashes.json` first and prefer `.new` sidecar files over destructive overwrites.
+- Do not put team-private project rules into any public bundled skill (`atw-meta`, `atw-spec-bootstrap`, `atw-session-insight`, `atw-channel`); put project rules in `.atw/spec/`, a project-local skill, the current task, or the workspace journal — `atw update` will overwrite anything inside a bundled skill directory.
+- Do not hand-edit `~/.atw/channels/<project>/<channel>/events.jsonl`; sequence numbers are assigned under a file lock and replay-safe writes go through the `atw channel` CLI or the `@chinhae/atw-core/channel` SDK.
+- Do not edit `.claude/agents/atw-implement-agent.md` (or any other per-platform sub-agent file) when the goal is to change channel runtime worker behavior — edit `.atw/agents/<name>.md` instead.
+- Do not describe removed or never-shipped mechanisms as current ATW behavior; cross-check against the local `.atw/config.yaml` and the installed CLI's `atw --help` before claiming a knob exists.

package/dist/templates/common/bundled-skills/atw-meta/references/customize-local/add-project-local-conventions.md

@@ -0,0 +1,83 @@
+# Add Project-Local Conventions
+
+Often the user does not need to change ATW mechanics; they need local AI to understand their team's conventions. In that case, prefer `.atw/spec/` or a project-local skill instead of editing `atw-meta`.
+
+## Where To Put Things
+
+| Content type | Location |
+| --- | --- |
+| Rules code must follow | `.atw/spec/<layer>/` |
+| Cross-layer thinking methods | `.atw/spec/guides/` |
+| AI capability for a project-specific flow | Platform-local skill |
+| One-off task material | `.atw/tasks/<task>/` |
+| Session summary | `.atw/workspace/<developer>/journal-N.md` |
+
+## Create A Project-Local Skill
+
+If the user wants AI to know "how this project customizes ATW," create a local skill:
+
+```text
+.claude/skills/atw-local/
+└── SKILL.md
+```
+
+Example:
+
+```md
+---
+name: atw-local
+description: "Project-local ATW customizations for this repository. Use when changing this project's ATW workflow, hooks, local agents, or team-specific conventions."
+---
+
+# ATW Local
+
+## Local Scope
+
+This skill documents this repository's ATW customizations only.
+
+## Custom Workflow Rules
+
+- ...
+
+## Local Hook Changes
+
+- ...
+
+## Local Agent Changes
+
+- ...
+```
+
+For multi-platform projects, place equivalent versions in other platform skill directories, or use `.agents/skills/` for platforms that support the shared layer.
+
+## Write To `.atw/spec/`
+
+If the content is a coding convention, write it to spec. Examples:
+
+```text
+.atw/spec/backend/error-handling.md
+.atw/spec/frontend/components.md
+.atw/spec/guides/cross-platform-thinking-guide.md
+```
+
+After writing it, update the corresponding `index.md` so AI can find the new rule from the entry point.
+
+## Make The Current Task Use New Conventions
+
+After writing a spec, add it to the current task context:
+
+```bash
+python3 ./.atw/scripts/task.py add-context <task> implement ".atw/spec/backend/error-handling.md" "Error handling conventions"
+python3 ./.atw/scripts/task.py add-context <task> check ".atw/spec/backend/error-handling.md" "Review error handling"
+```
+
+## Do Not Store Project-Private Rules In `atw-meta`
+
+`atw-meta` is a public skill for understanding ATW architecture and local customization entry points. Put project-private content in:
+
+- `.atw/spec/`
+- a project-local skill
+- the current task
+- workspace journal
+
+This prevents future updates to ATW's built-in `atw-meta` from overwriting the team's own conventions.

package/dist/templates/common/bundled-skills/atw-meta/references/customize-local/change-agents.md

@@ -0,0 +1,55 @@
+# Change Local Agents
+
+When the user wants to change `atw-review` or `atw-implement-agent` behavior, edit platform agent files in the user project.
+
+## Read These Files First
+
+1. Target platform agent directory
+2. `.atw/workflow.md` Phase 2 / agent routing
+3. Current task `prd.md`
+4. Current task `implement.jsonl` / `check.jsonl`
+5. Relevant hook or agent prelude
+
+## Common Paths
+
+| Platform | Path |
+| --- | --- |
+| Claude Code | `.claude/agents/atw-*.md` |
+| Cursor | `.cursor/agents/atw-*.md` |
+| OpenCode | `.opencode/agents/atw-*.md` |
+| Codex | `.codex/agents/atw-*.toml` |
+| Kiro | `.kiro/agents/atw-*.json` |
+| Gemini CLI | `.gemini/agents/atw-*.md` |
+| Qoder | `.qoder/agents/atw-*.md` |
+| CodeBuddy | `.codebuddy/agents/atw-*.md` |
+| Factory Droid | `.factory/droids/atw-*.md` |
+| Pi Agent | `.pi/agents/atw-*.md` |
+| Reasonix | `.reasonix/skills/atw-*/SKILL.md` (subagent frontmatter) |
+| ZCode | `.zcode/agents/atw-*.md` |
+
+Use the actual paths in the user project as authoritative.
+
+## Common Needs
+
+| Need | Which agent to edit |
+| --- | --- |
+| Certain local specs must be read before implementation | `atw-implement-agent` + `implement.jsonl` configuration rules |
+| Specific commands must run during review | `atw-review` |
+| Agent must not modify certain directories | The corresponding agent's write boundary instructions |
+| Agent output format must be fixed | The corresponding agent's final/reporting instructions |
+
+## Modification Principles
+
+1. **Preserve role boundaries**: implement writes implementation; review checks changes against project standards and the task spec, then fixes what it finds.
+2. **Do not hard-code project specs into agents**: long-term specs belong in `.atw/spec/`; agents are responsible for reading them.
+3. **Make read order explicit**: active task -> PRD -> info -> JSONL -> spec/research.
+4. **Make write boundaries explicit**: which directories may be written and which may not.
+5. **Synchronize across platforms**: when the user configured multiple platforms, decide whether to change only the current platform or all platform agents.
+
+## Agent Pull Platforms
+
+If an agent file contains a prelude for "read task/context after startup," do not remove those steps when editing. Otherwise the agent will work only from chat context and bypass ATW's core mechanism.
+
+## Hook Push Platforms
+
+If context is injected by a hook, the agent file should still retain responsibility boundaries. Do not remove PRD/spec requirements from the agent just because a hook injects context.