@chinhae/atw-cli 0.1.0

package/dist/templates/common/bundled-skills/atw-meta/references/platform-files/skills-and-commands.md

@@ -0,0 +1,86 @@
+# Skills, Commands, Prompts, And Workflows
+
+Skills and commands are textual entry points for user interaction with ATW. Different platforms use different names, but their core purpose is the same: tell the AI how to enter the ATW flow when the user expresses a certain intent.
+
+## Conceptual Differences
+
+| Type | Trigger mode | Best for |
+| --- | --- | --- |
+| skill | AI auto-match or explicit user mention | Long-term capabilities, workflow rules, modification guides. |
+| command | Explicit user invocation | Clear operation entry points such as continue and finish-work. |
+| prompt | Explicit user invocation or platform selection | Similar to command, but in a platform prompt format. |
+| workflow | Explicit user selection or platform auto-match | Guides the main session when no sub-agent/hook exists. |
+
+ATW workflow skills usually share one semantic set: brainstorm, before-dev, update-spec. Multi-file built-in skills such as `atw-meta` use layered references.
+
+## Common Paths
+
+| Platform | Common entries |
+| --- | --- |
+| Claude Code | `.claude/skills/`, `.claude/commands/` |
+| Cursor | `.cursor/skills/`, `.cursor/commands/` |
+| OpenCode | `.opencode/skills/`, `.opencode/commands/` |
+| Codex | `.agents/skills/`, `.codex/skills/` |
+| Kilo | `.kilocode/skills/`, `.kilocode/workflows/` |
+| Kiro | `.kiro/skills/` |
+| Gemini CLI | `.agents/skills/`, `.gemini/commands/` |
+| Antigravity | `.agent/skills/`, `.agent/workflows/` |
+| Devin | `.devin/skills/`, `.devin/workflows/` |
+| Qoder | `.qoder/skills/`, `.qoder/commands/` |
+| CodeBuddy | `.codebuddy/skills/`, `.codebuddy/commands/` |
+| GitHub Copilot | `.github/skills/`, `.github/prompts/` |
+| Factory Droid | `.factory/skills/`, `.factory/commands/` |
+| Pi Agent | `.agents/skills/` |
+| Reasonix | `.reasonix/skills/` |
+| ZCode | `.zcode/skills/`, `.zcode/commands/` |
+| Kimi Code | `.agents/skills/`, `.kimi-code/skills/` (commands delivered as `/skill:atw-*` skills) |
+
+In a user project, use the files actually generated by init as authoritative.
+
+## Skill Structure
+
+A common skill is a directory:
+
+```text
+atw-meta/
+├── SKILL.md
+└── references/
+```
+
+`SKILL.md` should tell the AI:
+
+- When to use this skill.
+- Which reference to read first for the current task.
+- What not to do.
+
+References hold longer explanations so the entry file does not contain everything.
+
+## Command/Prompt/Workflow Structure
+
+Commands, prompts, and workflows are usually single files. Their content should include:
+
+- When to use it.
+- Which `.atw/` files to read.
+- Which scripts to run.
+- How to report after completion.
+
+They should not store task state; task state belongs in `.atw/tasks/` and `.atw/.runtime/`.
+
+## Local Change Scenarios
+
+| User need | Edit location |
+| --- | --- |
+| Change AI auto-trigger rules | The corresponding skill's frontmatter description. |
+| Change user command behavior | The corresponding command/prompt/workflow file. |
+| Add a project-local skill | Platform skill directory, or shared `.agents/skills/`. |
+| Let multiple platforms share one capability | Write equivalent skills in each platform skill directory, or use the `.agents/skills/` shared layer on platforms that support it. |
+| Change finish/continue entry points | Platform commands/prompts/workflows. |
+
+## Modification Principles
+
+1. **Keep entry files short; references carry long content**. This matters especially for multi-file skills like `atw-meta`.
+2. **Make trigger descriptions specific**. A description that is too broad can mis-trigger; one that is too narrow may not trigger.
+3. **Keep the same semantics consistent across platforms**. File formats can differ, but behavior descriptions should match.
+4. **Put project-specific capabilities in local skills**. Do not put team-private flows into public `atw-meta`.
+
+If the user only wants local AI to know one more project rule, usually create a project-local skill or update `.atw/spec/` instead of changing an ATW built-in workflow skill.

package/dist/templates/common/bundled-skills/atw-prototype/LOGIC.md

@@ -0,0 +1,67 @@
+# Logic Prototype
+
+A single, self-contained HTML file — a **shareable demo** — that lets anyone drive a state model by clicking buttons. Use this when the question is about **business logic, state transitions, or data shape** — the kind of thing that looks reasonable on paper but only feels wrong once you push it through real cases.
+
+Because it's one file with nothing to install, you can hand it to a non-developer — a designer, a PM, a domain expert — and let them feel the model for themselves. So it speaks their language, not the code's.
+
+## When this is the right shape
+
+- "I'm not sure if this state machine handles the edge case where X then Y."
+- "Does this data model actually let me represent the case where..."
+- "I want to feel out what the API should look like before writing it."
+- Anything where someone wants to **press buttons and watch state change**.
+
+If the question is "what should this look like" — wrong branch. Use [UI.md](UI.md).
+
+## Process
+
+### 1. State the question
+
+Before writing code, write down what state model and what question you're prototyping. One paragraph, at the top of the demo (in a visible intro, not just a comment). A logic prototype that answers the wrong question is pure waste — make the question explicit so it can be checked later, whether the user is watching now or returning to it AFK.
+
+### 2. Isolate the logic in a portable module
+
+Put the actual logic — the bit that's answering the question — in a single `<script>` block written as a small, pure module that could be lifted out and dropped into the real codebase later. The page around it is throwaway; this module isn't.
+
+The right shape depends on the question:
+
+- **A pure reducer** — `(state, action) => state`. Good when actions are discrete events and state is a single value.
+- **A state machine** — explicit states and transitions. Good when "which actions are even legal right now" is part of the question.
+- **A small set of pure functions** over a plain data type. Good when there's no implicit current state — just transformations.
+- **A class or module with a clear method surface** when the logic genuinely owns ongoing internal state.
+
+Pick whichever shape best fits the question being asked, *not* whichever is easiest to wire to a page. Keep it pure: no DOM, no `document`, no button handlers reaching inside it. The page calls into it; nothing flows the other direction. This is what makes the prototype useful past its own lifetime: once the question's answered, the validated reducer / machine / function set lifts into the real module on its own.
+
+### 3. Build the shareable HTML file
+
+One file, plain HTML/CSS/JS — no framework, no bundler, no server, everything inline so it opens by double-click and survives being emailed around. Anyone should be able to run it by opening it.
+
+Write it for a non-developer. Every label is in **domain language**, not code — buttons and state read like the business, not the reducer. Explain in plain words what's happening.
+
+Lay it out with a clean hierarchy, top to bottom:
+
+1. **Title and one-line explanation** of what this demo lets you explore (the question from step 1).
+2. **Current state** — the full relevant state, rendered as a readable panel (labelled fields, not a raw JSON dump), re-rendered after every click so the change is visible. Where it helps a non-developer follow, call out what just changed.
+3. **Free-play buttons** — one button per action, always available, so anyone can poke at the model in any order. Each click dispatches its action and re-renders the state.
+4. **Guided walkthroughs** — a set of **scenarios**, one per tab. Each tab holds a short plain-language description of the scenario — the situation it sets up and what to watch for — and underneath it, the ordered **buttons to press** for that scenario. Each step is a real button: clicking it performs that action and moves to the next step. Starting a walkthrough resets to a known initial state so the scenario runs the same way every time.
+
+Choose scenarios that demonstrate the awkward cases — the happy path, a tricky edge case, an attempt at something that should be illegal — the ones hard to reason about on paper.
+
+Keep it beautiful but restrained: clean typography, generous spacing, one accent colour. No animations, no gimmicks — nothing that competes with the state and the buttons.
+
+### 4. Hand it over
+
+Send them the file, or open it for them. They'll click through the walkthroughs and free-play whenever they get to it; the interesting moments are when they say "wait, that shouldn't be possible" or "huh, I assumed X would be different" — those are the bugs in the _idea_, which is the whole point. If they want new actions or a new scenario, add them. Prototypes evolve.
+
+### 5. Capture the answer and the prototype
+
+Once the prototype has answered its question, capture the answer, then capture the prototype the way the [SKILL](SKILL.md) describes. The logic-specific mapping: the validated reducer / machine / function set lifts into the real module (the decision, absorbed); the HTML shell rides along to the throwaway branch that keeps the prototype as a primary source — and being one self-contained file, it stays trivially re-runnable there.
+
+## Anti-patterns
+
+- **Don't add tests.** A prototype that needs tests is no longer a prototype.
+- **Don't wire it to the real database.** Use in-memory state unless the question is specifically about persistence.
+- **Don't generalise.** No "what if we wanted to support X later." The prototype answers one question.
+- **Don't blur the logic and the page together.** If the pure module references the DOM, `document`, or button handlers, it's no longer liftable. Keep the page as a thin shell over a pure module.
+- **Don't reach for a framework, bundler, or server.** One file the recipient double-clicks; a React app or a dev server defeats "shareable".
+- **Don't ship the HTML shell into production.** The page is optimised for being clicked through by hand. The logic module behind it is the bit worth keeping.

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

@@ -0,0 +1,26 @@
+---
+name: atw-prototype
+description: "构建一个一次性原型来解答设计问题。当用户希望验证状态模型或逻辑是否合理，或者探索用户界面应呈现何种样貌时，可采用此方法。"
+---
+
+# Prototype
+
+A prototype is **throwaway code that answers a question**. The question decides the shape.
+
+## Pick a branch
+
+Identify which question is being answered — from the user's prompt, the surrounding code, or by asking if the user is around:
+
+- **"Does this logic / state model feel right?"** → [LOGIC.md](LOGIC.md). Build a single shareable HTML file — free-play buttons plus tabbed guided walkthroughs — that pushes the state machine through cases that are hard to reason about on paper, and that a non-developer can drive.
+- **"What should this look like?"** → [UI.md](UI.md). Generate several radically different UI variations on a single route, switchable via a URL search param and a floating bottom bar.
+
+The two branches produce very different artifacts — getting this wrong wastes the whole prototype. If the question is genuinely ambiguous and the user isn't reachable, default to whichever branch better matches the surrounding code (a backend module → logic; a page or component → UI) and state the assumption at the top of the prototype.
+
+## Rules that apply to both
+
+1. **Throwaway from day one, and clearly marked as such.** Locate the prototype code close to where it will actually be used (next to the module or page it's prototyping for) so context is obvious — but name it so a casual reader can see it's a prototype, not production. For throwaway UI routes, obey whatever routing convention the project already uses; don't invent a new top-level structure.
+2. **Trivial to run.** A UI prototype starts from one command in the project's task runner — `pnpm <name>`, `python <path>`, `bun <path>`, etc. A logic demo is a single HTML file the user double-clicks. Either way, no thinking required to start it.
+3. **No persistence by default.** State lives in memory. Persistence is the thing the prototype is _checking_, not something it should depend on. If the question explicitly involves a database, hit a scratch DB or a local file with a clear "PROTOTYPE — wipe me" name.
+4. **Skip the polish.** No tests, no error handling beyond what makes the prototype _runnable_, no abstractions. The point is to learn something fast.
+5. **Surface the state.** After every action (logic) or on every variant switch (UI), print or render the full relevant state so the user can see what changed.
+6. **Capture it when done.** Fold any validated decision into the real code, then capture the prototype itself as a **primary source**: commit it to a throwaway branch, out of main, and leave a context pointer to that branch on the implementation issue. Capture the answer too — the verdict and the question it settled — in the issue or a commit. The main branch keeps only the validated decision.

package/dist/templates/common/bundled-skills/atw-prototype/UI.md

@@ -0,0 +1,112 @@
+# UI Prototype
+
+Generate **several radically different UI variations** on a single route, switchable from a floating bottom bar. The user flips between variants in the browser, picks one (or steals bits from each), then throws the rest away.
+
+If the question is about logic/state rather than what something looks like — wrong branch. Use [LOGIC.md](LOGIC.md).
+
+## When this is the right shape
+
+- "What should this page look like?"
+- "I want to see a few options for this dashboard before committing."
+- "Try a different layout for the settings screen."
+- Any time the user would otherwise spend a day picking between three vague mockups in their head.
+
+## Two sub-shapes — strongly prefer sub-shape A
+
+A UI prototype is much easier to judge when it's **butting up against the rest of the app** — real header, real sidebar, real data, real density. A throwaway route on its own is a vacuum: every variant looks fine in isolation. Default to sub-shape A whenever there's a plausible existing page to host the variants. Only reach for sub-shape B if the prototype genuinely has no nearby home.
+
+### Sub-shape A — adjustment to an existing page (preferred)
+
+The route already exists. Variants are rendered **on the same route**, gated by a `?variant=` URL search param. The existing data fetching, params, and auth all stay — only the rendering swaps. This is the default; pick it unless there's a specific reason not to.
+
+If the prototype is for something that doesn't yet have a page but *would naturally live inside one* (a new section of the dashboard, a new card on the settings screen, a new step in an existing flow) — that's still sub-shape A. Mount the variants inside the host page.
+
+### Sub-shape B — a new page (last resort)
+
+Only use this when the thing being prototyped genuinely has no existing page to live inside — e.g. an entirely new top-level surface, or a flow that can't be embedded anywhere sensible.
+
+Create a **throwaway route** following whatever routing convention the project already uses — don't invent a new top-level structure. Name it so it's obviously a prototype (e.g. include the word `prototype` in the path or filename). Same `?variant=` pattern.
+
+Before committing to sub-shape B, sanity-check: is there really no existing page this could be embedded in? An empty route hides design problems that a populated one would expose.
+
+In both sub-shapes the floating bottom bar is identical.
+
+## Process
+
+### 1. State the question and pick N
+
+Default to **3 variants**. More than 5 stops being radically different and starts being noise — cap there.
+
+Write down the plan in one line, in the prototype's location or a top-of-file comment:
+
+> "Three variants of the settings page, switchable via `?variant=`, on the existing `/settings` route."
+
+This works whether the user is here to push back or not.
+
+### 2. Generate radically different variants
+
+Draft each variant. Hold each one to:
+
+- The page's purpose and the data it has access to.
+- The project's component library / styling system (TailwindCSS, shadcn, MUI, plain CSS, whatever).
+- A clear exported component name, e.g. `VariantA`, `VariantB`, `VariantC`.
+
+Variants must be **structurally different** — different layout, different information hierarchy, different primary affordance, not just different colours. Three slightly-tweaked card grids isn't a UI prototype, it's wallpaper. If two drafts come out too similar, redo one with explicit "do not use a card grid" guidance.
+
+### 3. Wire them together
+
+Create a single switcher component on the route:
+
+```tsx
+// pseudo-code — adapt to the project's framework
+const variant = searchParams.get('variant') ?? 'A';
+return (
+  <>
+    {variant === 'A' && <VariantA {...data} />}
+    {variant === 'B' && <VariantB {...data} />}
+    {variant === 'C' && <VariantC {...data} />}
+    <PrototypeSwitcher variants={['A','B','C']} current={variant} />
+  </>
+);
+```
+
+For sub-shape A (existing page): keep all the existing data fetching above the switcher; only the rendered subtree changes per variant.
+
+For sub-shape B (new page): the throwaway route under `/prototype/<name>` mounts the same switcher.
+
+### 4. Build the floating switcher
+
+A small fixed-position bar at the bottom-centre of the screen with three pieces:
+
+- **Left arrow** — cycles to the previous variant (wraps around).
+- **Variant label** — shows the current variant key and, if the variant exports a name, that name too. e.g. `B — Sidebar layout`.
+- **Right arrow** — cycles forward (wraps around).
+
+Behaviour:
+
+- Clicking an arrow updates the URL search param (use the framework's router — `router.replace` on Next, `navigate` on React Router, etc) so the variant is shareable and reload-stable.
+- Keyboard: `←` and `→` arrow keys also cycle. Don't intercept arrow keys when an `<input>`, `<textarea>`, or `[contenteditable]` is focused.
+- Visually distinct from the page (e.g. high-contrast pill, subtle shadow) so it's obviously not part of the design being evaluated.
+- Hidden in production builds — gate on `process.env.NODE_ENV !== 'production'` or an equivalent check, so a stray prototype merge can't ship the bar to users.
+
+Put the switcher in a single shared component so both sub-shapes can reuse it. Locate it wherever shared UI lives in the project.
+
+### 5. Hand it over
+
+Surface the URL (and the `?variant=` keys). The user will flip through whenever they get to it. The interesting feedback is usually **"I want the header from B with the sidebar from C"** — that's the actual design they want.
+
+### 6. Capture the answer and clean up
+
+Once a variant has won, capture the answer — which variant and why — then capture the prototype the way the [SKILL](SKILL.md) describes. Fold the winner into the real code and move the rest onto the throwaway branch, not into main:
+
+- **Sub-shape A** — fold the winner into the existing page; drop the losing variants and the switcher from main.
+- **Sub-shape B** — promote the winning variant to a real route; drop the throwaway route and the switcher from main.
+
+The full set of variants is the primary source, so it lands on the throwaway branch, not the bin — variant components and the switcher left in the main branch rot fast and confuse the next reader.
+
+## Anti-patterns
+
+- **Variants that differ only in colour or copy.** That's a tweak, not a prototype. Real variants disagree about structure.
+- **Sharing too much code between variants.** A shared `<Header>` is fine; a shared `<Layout>` defeats the point. Each variant should be free to throw out the layout.
+- **Wiring variants to real mutations.** Read-only prototypes are fine. If a variant needs to mutate, point it at a stub — the question is "what should this look like", not "does the backend work".
+- **Promoting the prototype directly to production.** The variant code was written under prototype constraints (no tests, minimal error handling). Rewrite it properly when you fold it in.

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

@@ -0,0 +1,3 @@
+interface:
+  display_name: "Oxyteam Prototype"
+  short_description: "用于解答设计问题的原型"

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

@@ -0,0 +1,14 @@
+---
+name: atw-research
+description: "根据可信度高的原始资料对某个问题进行调查，并将调查结果以 Markdown 文件的形式保存到代码库中。当用户希望对某个主题进行研究、收集文档或 API 信息，或者将阅读和资料搜集工作委托给后台代理时，可使用此功能。"
+---
+
+Before spawning, settle **where the findings file goes** and put that path in the spawn prompt — a background agent may not inherit the session context that would otherwise tell it. In order: a path the caller gave you; the location `docs/agents/issue-tracker.md` names for research notes; the convention the repo already follows. Only if all three come up empty does the agent choose, and then it must say where.
+
+Then spin up a **background agent** to do the research, so you keep working while it reads.
+
+Its job:
+
+1. Investigate the question against **primary sources** — official docs, source code, specs, first-party APIs — not a secondary write-up of them. Follow every claim back to the source that owns it.
+2. Write the findings to a single Markdown file, citing each claim's source.
+3. Save it to the path it was given.

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

@@ -0,0 +1,3 @@
+interface:
+  display_name: "Oxyteam Research"
+  short_description: "来自高可信度来源的研究"

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

@@ -0,0 +1,81 @@
+---
+name: atw-session-insight
+description: "Reach into past AI conversation history through the `atw mem` CLI. Use whenever the user asks 'how did we solve X last time', 'have we discussed this before', 'what was the decision on X', 'remind me what we did in this task', '上次怎么解的', '之前讨论过吗', '想起一段对话', or when starting a brainstorm that overlaps prior work, debugging a familiar bug, continuing a task across sessions, or doing a finish-work review. Returns raw past dialogue; decide for the moment whether to update spec, append to task notes, quote inline in the answer, or just internalize."
+---
+
+# ATW Session Insight
+
+This skill teaches an AI **how to call `atw mem`** — the project's cross-session memory feedstock — and **when reaching for it is the right move**.
+
+It is intentionally a **capability skill, not a workflow**. There is no fixed output file, no required write-back step, no "always run after finish-work" rule. What to do with what `mem` returns is a judgement call made in the moment of the conversation. The skill exists so the AI knows the capability is there and can decide.
+
+## What `atw mem` is
+
+A local CLI that indexes the user's past Claude Code, Codex, Pi Agent, and ZCode conversation logs and lets you list, search, slice by ATW task boundaries, and dump cleaned dialogue from them. Claude and Codex use `~/.claude/projects/` and `~/.codex/sessions/`. Pi uses its default or environment-configured session root, global `~/.pi/agent/settings.json`, and the scoped project's `.pi/settings.json`; relative `sessionDir` values resolve from the settings file directory. Project-local Pi settings require project-scoped lookup through the current cwd or `--cwd`. ZCode uses `~/.zcode/cli/db/db.sqlite`. OpenCode logs are not yet indexable (provider adapter pending) — when an OpenCode session is the obvious target, surface that limitation rather than guessing.
+
+Nothing in `mem` is uploaded. All reads are local.
+
+## When to reach for it
+
+The bar is "would a senior teammate ask 'didn't we already talk about this?'" — those are the moments. Some concrete patterns:
+
+- **Brainstorm rerun risk.** Starting a new task that touches an area the user has been in before, and you want to check whether a decision was already made — before re-asking the user.
+- **Familiar-bug debugging.** The current bug pattern feels like one the user reported / fixed before. Pulling the relevant past session can save a full debugging loop.
+- **Cross-session continuation.** The user resumes work after a gap and says "where were we" / "继续上次的" without being specific.
+- **Decision retrieval.** The user references "the decision we made about X" but the decision lives in an old brainstorm, not in any `prd.md` / `spec/`.
+- **Finish-work retrospective.** When the user explicitly asks for a wrap-up of what was decided / what hurt / what surprised them in this task — not as a forced step on every finish-work.
+- **Pattern-spotting across past work.** The user asks "do I keep making the same mistake on X" / "我每次都踩这个坑吗" — search across sessions answers that.
+
+If none of these apply, don't call `mem`. It is a tool, not a ceremony.
+
+## When NOT to reach for it
+
+- The relevant context is already in the current turn, `prd.md`, recent `git log`, or the open files. `mem` is for stuff that has fallen out of immediate reach.
+- The user is asking about a fact in the code, not a fact from a past conversation. `git log -p` / `grep` / reading the file directly is faster and more authoritative.
+- You are in a sub-agent (`atw-implement-agent` / `atw-review`) whose dispatch prompt already includes the curated `implement.jsonl` / `check.jsonl` context. Adding `mem` on top usually just clutters.
+- The user has explicitly said "don't dig through history, just answer what I asked".
+
+## What to do with what `mem` returns
+
+Treat the output as **raw material**, not a deliverable. Once you have it, decide based on the live conversation:
+
+- **Quote inline in your reply** if a specific past exchange answers the user's current question — and cite the session-id / phase so the user can verify.
+- **Update `<task>/prd.md`** if `mem` surfaced a load-bearing decision that should have been written down but wasn't. Surface the proposed edit to the user first.
+- **Append to a task-local notes file** (e.g. `<task>/notes.md` or extending an existing one) if the finding belongs to the current task's record but doesn't fit the PRD.
+- **Update `.atw/spec/`** if the finding is a project-wide convention or gotcha that would help future tasks. Run the `atw-update-spec` skill for that — `session-insight` ends at the discovery.
+- **Just absorb it** for the next few turns and answer better, without writing anything. This is often the right move for one-off recall.
+
+ATW does not prescribe a single destination. Forcing every recall into a fixed file makes the file grow into noise. Let the situation decide.
+
+## How to call it
+
+Full CLI reference is in `references/cli-quick-reference.md`. The 80% case is one of:
+
+```bash
+# Find sessions whose contents mention a keyword (project-scope is default;
+# add --global to search every project on this machine).
+atw mem search "<keyword>"
+
+# Dump dialogue from one session, optionally filtered by phase or keyword.
+atw mem extract <session-id> --phase brainstorm
+atw mem extract <session-id> --grep "<keyword>"
+
+# Drill into a session: top-N hit turns + surrounding context.
+atw mem context <session-id> --turns 3 --around 2
+
+# When you do not know the session id yet, start with list + filter.
+atw mem list --cwd <project-path>
+atw mem projects   # → list active project cwds, then narrow
+```
+
+Phase slicing (`--phase brainstorm|implement|all`) cuts the session at `task.py create` and `task.py start` boundaries. For a finish-work review of the current task, `--phase brainstorm` recovers the planning discussion and `--phase implement` recovers the execution loop. Default is `all`.
+
+## Triggering patterns
+
+`references/triggering-patterns.md` lists more verbatim user phrasings (English + Chinese) that should make you think "reach for `mem`" — keep that handy when training instinct.
+
+## Out of scope
+
+- `mem` does not edit code or update files. Any write-back is your decision in the moment.
+- `mem` is read-only on the platform JSONL stores. It does not push or sync to remote.
+- This skill does not replace `atw-update-spec` (which is the right tool for promoting a finding into project-wide guidance) or the platform-native task / spec workflow.

package/dist/templates/common/bundled-skills/atw-session-insight/references/cli-quick-reference.md

@@ -0,0 +1,65 @@
+# `atw mem` CLI Reference
+
+Full flag reference for the five subcommands. Pin this as the authoritative source — `atw mem help` prints the same content at runtime, so anything here that drifts is a bug.
+
+## Subcommands
+
+| Command                | Purpose                                                                                                                |
+| ---------------------- | ---------------------------------------------------------------------------------------------------------------------- |
+| `list`                 | List sessions. Default subcommand when none is given.                                                                  |
+| `search <keyword>`     | Find sessions whose contents match a keyword.                                                                          |
+| `context <session-id>` | Drill into one session: top-N hit turns + surrounding context. Pair with `--grep` for keyword anchoring.               |
+| `extract <session-id>` | Dump cleaned dialogue. Combine with `--phase` / `--grep` to slice.                                                     |
+| `projects`             | List active project `cwd` values with session counts. Use this to discover which `--cwd` to pass to other subcommands. |
+
+## Flags (apply where meaningful)
+
+| Flag                                          | Subcommands       | Meaning                                                                                                                                                    |
+| --------------------------------------------- | ----------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `--platform claude\|codex\|opencode\|pi\|all` | all               | Default `all`. OpenCode sessions are read, but `--phase` does not apply to them — see "Caveats" below.                                                      |
+| `--since YYYY-MM-DD`                          | list / search     | Inclusive lower date bound.                                                                                                                                |
+| `--until YYYY-MM-DD`                          | list / search     | Inclusive upper date bound.                                                                                                                                |
+| `--global`                                    | list / search     | Include sessions from every project on this machine. Default is the current project `cwd`.                                                                 |
+| `--cwd <path>`                                | list / search     | Force a specific project cwd instead of inferring from where you are.                                                                                      |
+| `--limit N`                                   | list / search     | Cap output rows. Default `50`.                                                                                                                             |
+| `--grep KW`                                   | extract / context | Filter turns by keyword. Multi-token AND when whitespace-separated.                                                                                        |
+| `--phase brainstorm\|implement\|all`          | extract           | Slice session by ATW task boundaries. `brainstorm` = `[task.py create, task.py start)`. `implement` = turns outside brainstorm windows. Default `all`. |
+| `--turns N`                                   | context           | Number of hit turns to return. Default `3`.                                                                                                                |
+| `--around N`                                  | context           | Surrounding turns to include per hit. Default `1`.                                                                                                         |
+| `--max-chars N`                               | context           | Total character budget. Default `6000` (~1500 tokens).                                                                                                     |
+| `--include-children`                          | search / context  | Merge OpenCode sub-agent sessions into their parent session.                                                                                               |
+| `--json`                                      | all               | Emit machine-parseable JSON instead of human-readable output.                                                                                              |
+
+## Common one-liners
+
+```bash
+# What past sessions discussed "deadlock" anywhere on this machine?
+atw mem search "deadlock" --global --limit 20
+
+# Inside a specific session, surface the top 5 turns that mention "lock contention"
+# plus 2 turns of surrounding context.
+atw mem context 5842592d --grep "lock contention" --turns 5 --around 2
+
+# Recover the brainstorm window for a session — useful when continuing a task
+# the user started a week ago.
+atw mem extract 5842592d --phase brainstorm
+
+# List every project this machine has ATW sessions for, with counts.
+atw mem projects
+```
+
+## Output shapes
+
+- **Default human output** (no `--json`): wrapped to a terminal, with session ids highlighted and turn markers visible. Suitable to read inline but messy to paste into a markdown file.
+- **`--json`**: stable schema, safe to parse and process. When piping `mem` output into a follow-up step (e.g. summarizing for a Lessons section), prefer `--json`.
+
+## Caveats
+
+- **OpenCode does not support `--phase` slicing.** `list`, `search`, and `context` all read OpenCode sessions from its SQLite session store, but the adapter has no native phase-boundary detection. A `--phase brainstorm` or `--phase implement` request against OpenCode returns the *full* dialogue plus an `opencode-phase-unsupported` warning, so report those results as "full session" rather than as brainstorm or implement turns.
+- **`--phase` slicing depends on `task.py create` / `task.py start` invocations appearing in the recorded bash calls of the session.** Sessions where the user ran `task.py` from a different terminal — outside the recorded AI loop — will not have phase boundaries. `--phase all` is the safe fallback.
+- **`mem` indexes platform JSONL files directly.** If the user has cleared their Claude / Codex / Pi session storage, `mem` cannot recover what is no longer on disk.
+- **`mem` is read-only.** No remote sync, no edits to platform JSONL. Any write you do based on `mem` findings is your own follow-up call into the editing tools available to you.
+
+## When you need more than this reference
+
+Run `atw mem help` in the user's shell. The runtime help is authoritative and will be ahead of this reference during fast-moving beta releases.

package/dist/templates/common/bundled-skills/atw-session-insight/references/triggering-patterns.md

@@ -0,0 +1,93 @@
+# Triggering Patterns
+
+Verbatim user phrasings that should make an AI reach for `atw mem`. Calibrate instinct against these — if a user message hits one of these patterns and you do not reach for `mem`, you probably missed an obvious recall.
+
+Patterns are grouped by the *intent* behind the phrasing, not the surface words. The same intent shows up in different languages and registers.
+
+## Past-solution recall
+
+The user is asking "how did we (or I) solve this before". Past dialogue holds the answer; the codebase shows the result but not the reasoning.
+
+- "How did we solve this last time?"
+- "What did we end up doing about X?"
+- "We dealt with this once already, didn't we?"
+- "上次怎么解的?"
+- "之前是怎么搞定 X 的?"
+- "我记得以前修过类似的"
+
+Reach: `atw mem search "<symptom keyword>" --global --limit 10`, then `context` into the hit that looks closest.
+
+## Decision retrieval
+
+The user is referencing a decision that lives in old dialogue, not in any committed file. Look in brainstorm windows.
+
+- "What was the decision on X?"
+- "Did we decide to use Postgres or SQLite?"
+- "The rationale for choosing X over Y was…?"
+- "我们当时为啥选了 X 而不是 Y?"
+- "关于 X 我们之前是怎么定的?"
+- "之前讨论过 X 的方案吗?"
+
+Reach: `atw mem search "<decision keyword>"` to find the session, then `extract <id> --phase brainstorm` to recover the discussion.
+
+## Cross-session continuation
+
+The user resumed work after a gap and the context is implicit.
+
+- "Where were we?"
+- "Continue from last time."
+- "Pick up where we left off."
+- "继续上次的"
+- "我们上次做到哪了"
+- "接着昨天那个任务"
+
+Reach: `atw mem list --task <current-task-dir>` to find the most recent sessions tied to the active task, then `extract` the last one.
+
+## Familiar-bug debugging
+
+The current bug feels like one already seen. Past sessions probably hold the resolution path.
+
+- "I feel like I've hit this before."
+- "Doesn't this look like that bug from last month?"
+- "Same kind of timeout I had in X."
+- "这个错好像之前见过"
+- "这个 bug 是不是上次那个?"
+- "怎么又是这个 error?"
+
+Reach: `atw mem search "<error message fragment>" --global`. Anchor on a short, distinctive token from the actual error string.
+
+## Self-pattern spotting
+
+The user is asking whether they keep repeating the same kind of mistake or decision.
+
+- "Do I always make this mistake?"
+- "How often have I run into X?"
+- "Is this a recurring thing for me?"
+- "我每次都踩这个坑吗?"
+- "我老犯这个错?"
+- "这类问题之前出现过几次?"
+
+Reach: `atw mem search "<topic>" --global --limit 50` and scan the dates / projects in the listing. Optionally `extract` two or three for comparison.
+
+## Finish-work retrospective (on demand)
+
+The user explicitly wants to look back at this task — not as a forced step, only when they ask.
+
+- "Summarize what we did in this task."
+- "What were the key decisions / surprises?"
+- "Write up the lessons from this round."
+- "总结一下这次的经验"
+- "记一下这次踩的坑"
+- "复盘下这个任务"
+
+Reach: identify the current task's session id (from `.atw/.runtime/sessions/*.json` or `mem list --task <task-dir>`), then `extract <id> --phase brainstorm` and `--phase implement`. Present a summary — surface concrete file:line citations where possible. Whether to also write the summary somewhere (PRD, spec, notes file) is the user's call; offer, don't auto-write.
+
+## Anti-patterns: do NOT reach for `mem` here
+
+- "What does this function do?" → read the file.
+- "Why is this test failing?" → read the test output and the file.
+- "What's the right pattern for X in our codebase?" → grep / read spec files.
+- "What's the latest npm version of Y?" → call `npm view`.
+- "Fix this bug." → debug. Reach for `mem` only if you suspect prior context exists; otherwise it is noise.
+
+The bar stays: would a senior teammate ask "didn't we already talk about this?" before answering? If yes, reach for `mem`. If no, don't.