@chinhae/atw-cli 0.1.0

package/dist/templates/common/bundled-skills/atw-channel/references/workers.md

@@ -0,0 +1,274 @@
+# Workers And Agent Cards
+
+Use workers when a peer agent should execute independently and report back
+through the channel event log. A worker is a registered child process (claude
+or codex) attached to a channel; the supervisor forwards inbox messages to it
+and translates its output back into channel events.
+
+## Spawn
+
+```bash
+atw channel create impl-task --by dispatcher --cwd /path/to/repo
+atw channel spawn impl-task --provider codex --as codex-impl --timeout 30m
+
+echo "Implement the schema for table X per .atw/.../prd.md" \
+  | atw channel send impl-task --as dispatcher --to codex-impl --stdin
+
+atw channel wait impl-task --as dispatcher --from codex-impl --kind done --timeout 30m
+```
+
+`spawn` forks a `channel __supervisor` worker that emits `spawned`, streams
+`progress`, and should end with `done`, `error`, or `killed`. Workers stay
+inbox-idle until a `send --to <worker>` (or a broadcast when
+`--inbox-policy broadcastAndExplicit` is set) wakes them.
+
+Key `spawn` flags:
+
+- `--agent <name>` — load `.atw/agents/<name>.md` (provider/model/as/system prompt defaults).
+- `--provider <claude|codex>` — overrides the agent card; validated against the adapter registry.
+- `--as <name>` — channel worker handle; defaults to the agent name.
+- `--cwd <path>` — worker working directory (also the jail root for `--file`/`--jsonl`).
+- `--model <id>` — model override.
+- `--resume <id>` — resume an existing claude session / codex thread.
+- `--timeout <duration>` — auto-kill after `30s` / `2m` / `1h`.
+- `--warn-before <duration>` — supervisor_warning lead time (default `5m`; `0ms` disables).
+- `--file <path>` (repeatable, glob-supported) — inject file content into the system prompt.
+- `--jsonl <path>` (repeatable) — ATW jsonl manifest (`{file, reason}` per line).
+- `--by <agent>` — author of the `spawned` event (defaults to `$ATW_CHANNEL_AS` or `main`).
+- `--inbox-policy <explicitOnly|broadcastAndExplicit>` — default `explicitOnly`.
+- `--idle-timeout <duration>` — OOM guard idle TTL (default `5m`; `0` disables).
+- `--max-live-workers <n>` — spawn-time live-worker budget (default `6`; `0` disables).
+
+The success event `spawned` records `pid`, `provider`, `agent`, the injected
+`files`, and the resolved `manifests` so later spectators can audit context.
+
+## Agent Cards
+
+`--agent <name>` resolves to `.atw/agents/<name>.md`. The card name must
+match `[A-Za-z0-9._-]+`. The default ATW install ships two cards:
+
+- `.atw/agents/review.md` — code-quality reviewer.
+- `.atw/agents/implement-agent.md` — coding worker for implementation runs.
+
+```yaml
+---
+name: review
+description: Code quality check expert.
+provider: claude
+---
+```
+
+Frontmatter fields populate `spawn` defaults (provider, model, `as`); the
+markdown body becomes the worker's system-prompt role. Cards do **not**
+auto-attach task files — context must be injected explicitly per spawn (see
+below).
+
+Always inspect project cards before spawning a named agent:
+
+```bash
+ls .atw/agents
+sed -n '1,100p' .atw/agents/review.md
+```
+
+## Context Injection
+
+Two flags inject content into the worker's system prompt under a
+`# CONTEXT FILES` block, assembled by `context-loader`:
+
+- `--file <path>` — repeatable, glob-supported (`*`, `**`). Each match is
+  read and concatenated.
+- `--jsonl <path>` — repeatable ATW manifest where every line is
+  `{"file":"<path>","reason":"<why>"}`. The reason is preserved as a header
+  comment above each file's content.
+
+Limits enforced by the loader:
+
+- 1 MB hard cap per file (oversize → error).
+- 200 KB per-file warning to stderr.
+- 500 KB total assembled-context warning to stderr.
+- Path-traversal jail: all resolved paths must stay under `--cwd`.
+
+Example spawning a review agent against a task directory:
+
+```bash
+TASK=.atw/tasks/05-13-example
+atw channel spawn cr-example --agent review --provider codex --as review-cx \
+  --file "$TASK/prd.md" \
+  --jsonl "$TASK/check.jsonl" \
+  --cwd "$PWD" --timeout 30m
+```
+
+The `spawned` event records both the literal `files` array and any `manifests`
+expanded from `--jsonl`, so the audit trail captures whatever the worker was
+actually shown.
+
+## Names And Routing
+
+`--as` has two meanings:
+
+- `send` / `wait` / `interrupt`: speaker identity (author of the resulting event).
+- `spawn`: the worker handle that other agents address with `--to`.
+
+Use explicit names when multiple workers or providers participate in one
+channel:
+
+```bash
+atw channel spawn cr-feature --agent review --as review-claude
+atw channel spawn cr-feature --agent review --provider codex --as review-cx
+
+atw channel wait cr-feature --as main \
+  --from review-claude,review-cx --kind done --all --timeout 15m
+```
+
+`--all` requires `--from` and blocks until every listed worker has produced a
+matching event; timeout exits with code **124** and prints
+`timeout: still waiting on ...` to stderr.
+
+## Soft Interrupt — `interrupt`
+
+`channel interrupt` is the cooperative redirect: it appends an `interrupt`
+event (reason `"user"`) and, where the adapter supports it, issues a
+provider-level turn interrupt with a replacement instruction. Use it when the
+worker should drop its current turn and act on new input immediately, without
+losing its session.
+
+```bash
+echo "Stop refactoring the parser — switch to fixing the failing test in src/foo.ts" \
+  | atw channel interrupt impl-task --as dispatcher --to codex-impl --stdin
+```
+
+Flags:
+
+- `--as <agent>` **(required)** — caller identity.
+- `--to <agent>` **(required)** — target worker.
+- `--scope <project|global>` — channel scope.
+- `--stdin` / `--text-file <path>` / `[text]` — replacement instruction body.
+
+The appended event has `kind: "interrupt"` — downstream `wait` / `messages`
+filters can subscribe with `--kind interrupt` to react to redirections (e.g.
+to log the rerouting, or to gate other workers behind a coordinator's
+correction).
+
+For low-priority hints that should wait for the worker's next turn, send a
+plain tagged message instead:
+
+```bash
+echo "Check this when you reach the next turn." \
+  | atw channel send impl-task --as dispatcher --to codex-impl \
+      --stdin --tag question
+```
+
+## Hard Interrupt — `kill` + `--resume`
+
+Use `kill` when the worker must stop **now** (e.g. runaway loop, bad
+instructions already in flight, or `interrupt` is not honored by the
+adapter). The supervisor escalates SIGTERM → 8 s grace → SIGKILL; the CLI
+writes a `killed` event when SIGKILL is needed so the event log stays
+truthful.
+
+```bash
+atw channel kill impl-task --as codex-impl
+atw channel spawn impl-task --as codex-impl --provider codex \
+  --resume "$(cat ~/.atw/channels/<bucket>/impl-task/worker.session-id)"
+
+echo "STOP — new instructions: ..." \
+  | atw channel send impl-task --as dispatcher --to codex-impl --stdin
+```
+
+`kill` flags:
+
+- `--as <agent>` **(required)** — names the worker (positional `<name>` is the channel).
+- `--scope <project|global>`.
+- `--force` — SIGKILL immediately (also kills the inner worker pid).
+
+Side effects: cleans `pid`, `worker-pid`, `config`, `spawnlock` sidecar
+files; keeps `log`, `session-id`, `thread-id` for forensics and resume.
+
+When `interrupt` will not converge, kill + `--resume` is the guaranteed
+redirection path.
+
+## Worker OOM Guard
+
+The OOM guard prevents orphaned/idle workers from accumulating and exhausting
+host resources. It runs at every `spawn` and enforces two policies per
+project bucket:
+
+- **Idle TTL** — sweep workers whose last activity is older than the
+  configured threshold (default `5m`; `0` disables).
+- **Live-worker budget** — refuse the new spawn if more than N workers are
+  already alive in the same project bucket (default `6`; `0` disables).
+
+Precedence (highest first):
+
+1. CLI flags: `--idle-timeout`, `--max-live-workers` on `spawn`.
+2. Environment variables: `ATW_CHANNEL_WORKER_IDLE_TIMEOUT`,
+   `ATW_CHANNEL_MAX_LIVE_WORKERS`.
+3. `.atw/config.yaml` under `channel.worker_guard`.
+4. Built-in defaults (`5m`, `6`).
+
+Cleanup notices are written to stderr at spawn time so operators can see which
+idle workers were swept and why a new spawn was rejected. The guard does not
+touch ephemeral / `channel run` workers any differently — they are subject to
+the same idle TTL and budget.
+
+To audit current state, list workers via `channel list` (the `WORKERS`
+column) and inspect per-channel `pid` / `worker-pid` sidecar files under
+`~/.atw/channels/<bucket>/<channel>/`.
+
+## Worker Inbox APIs
+
+The inbox is the channel surface workers wake on. Routing is controlled by
+two knobs:
+
+- **Inbox policy** (`spawn --inbox-policy`):
+  - `explicitOnly` (default) — worker only wakes on `send --to <worker>` or
+    `interrupt --to <worker>`.
+  - `broadcastAndExplicit` — also wakes on broadcasts (`send` with no `--to`).
+- **Delivery mode** (`send --delivery-mode`):
+  - `appendOnly` — append the event regardless of worker state.
+  - `requireKnownWorker` — fail if no worker named in `--to` was ever spawned.
+  - `requireRunningWorker` — fail if the named worker is not currently alive.
+
+Stricter delivery modes prevent silent message loss when callers expect a
+running peer.
+
+Inbox-relevant subcommands:
+
+- `send <channel> [text]` — append a `message` event.
+  - `--as <agent>` **(required)** — author.
+  - `--to <agents>` — CSV; one → string, many → array; broadcast if omitted.
+  - `--stdin` / `--text-file <path>` / `[text]` — body source.
+  - `--delivery-mode <appendOnly|requireKnownWorker|requireRunningWorker>`.
+- `interrupt <channel> [text]` — soft-interrupt redirect (see above).
+- `wait <channel>` — block until matching events arrive.
+  - `--as <agent>` **(required)** — `self` for filter context.
+  - `--from <agents>` — CSV authors.
+  - `--kind <kind[,kind...]>` — CSV (OR semantics); supports `interrupt`,
+    `done`, `progress`, etc.
+  - `--to <target>` — defaults to own agent (broadcast + explicit-to-me).
+  - `--include-progress` — also wake on progress events.
+  - `--all` — require every `--from` agent to match (timeout → exit **124**).
+  - `--timeout <duration>` — `30s` / `2m` / `1h` / `1000ms`.
+- `messages <channel>` — view / filter / follow the event stream.
+  - `--follow` to tail, `--kind` / `--from` / `--to` to filter, `--raw` for
+    JSON-per-line, `--no-progress` to hide progress noise.
+
+A typical dispatcher loop:
+
+```bash
+# 1. Wake the worker.
+echo "Run the failing test and report." \
+  | atw channel send impl-task --as dispatcher --to codex-impl --stdin \
+      --delivery-mode requireRunningWorker
+
+# 2. Block until it finishes.
+atw channel wait impl-task --as dispatcher \
+  --from codex-impl --kind done,error --timeout 30m
+
+# 3. Read the final answer.
+atw channel messages impl-task --from codex-impl --last 1 --raw
+```
+
+All event-emitting subcommands (`send`, `interrupt`, `post`, `context add` /
+`delete`, `title set` / `clear`, `thread rename`) print the appended event as
+a single JSON line on stdout, making the inbox layer easy to script against.

package/dist/templates/common/bundled-skills/atw-channel/references/workflows.md

@@ -0,0 +1,125 @@
+# Workflows
+
+Use these patterns by intent. Prefer durable channels for multi-round work and
+`channel run` for one-shot questions.
+
+## Pattern A: Multi-round Brainstorm
+
+Use when the user says "和 codex/claude 讨论一下", "brainstorm", or "拉一个 agent
+进来一起看".
+
+```bash
+atw channel create brainstorm-storage-layer --by main \
+  --task .atw/tasks/05-XX-storage-adapter
+
+atw channel spawn brainstorm-storage-layer \
+  --agent architect --provider codex \
+  --file .atw/tasks/05-XX-storage-adapter/prd.md \
+  --as cx-arch --timeout 30m
+
+atw channel send brainstorm-storage-layer \
+  --as main --to cx-arch --text-file /tmp/brainstorm-r1.md
+
+atw channel wait brainstorm-storage-layer \
+  --as main --kind done --from cx-arch --timeout 10m
+```
+
+Do not stop after one answer. Read the answer, identify vague areas, send a
+new probe, and repeat until the result is executable.
+
+Minimum round structure:
+
+1. Direction split: should this live in an existing mechanism or a new one?
+2. MVP boundary: v1, v2, and what would force v2 back into v1.
+3. Data contract: events, schema, metadata, state source of truth, compatibility.
+4. CLI / UX contract: command names, flags, errors, defaults, ambiguity.
+5. Cross-layer risk and tests: shared helpers, drift points, release-blocking tests.
+
+Optional rounds:
+
+- Operations: logs, debugging, stuck workers, kill/restart, recovery.
+- Migration/release: breaking status, manifest, changelog, docs-site.
+- Opposition review: ask the peer agent to argue against the current plan.
+
+Every probe should request concrete file paths, commands, schema, rejected
+alternatives, and release-blocking issues. Reject hedging when a decision is
+needed.
+
+## Pattern B: Implement / Review Agent
+
+Use when the user asks to dispatch implementation or review work.
+
+```bash
+TASK=.atw/tasks/05-12-foo
+atw channel create cr-foo --task "$TASK" --by main
+
+atw channel spawn cr-foo \
+  --agent review \
+  --jsonl "$TASK/check.jsonl" \
+  --file "$TASK/prd.md" \
+  --cwd "$PWD" --timeout 15m
+
+atw channel send cr-foo --as main --to review --text-file /tmp/cr-brief.md
+atw channel wait cr-foo --as main --kind done --from review --timeout 15m
+atw channel messages cr-foo --kind message --from review --tag final_answer
+```
+
+For implement work, use `--agent implement-agent` and send an implementation
+brief. For review work, include the exact diff scope, relevant specs, and
+validation already run.
+
+## Pattern C: Parallel Reviewers
+
+Use one channel and distinct worker names.
+
+```bash
+atw channel create cr-feature --by main --ephemeral
+
+atw channel spawn cr-feature --agent review \
+  --jsonl "$TASK/check.jsonl" --file "$TASK/prd.md" \
+  --timeout 15m
+
+atw channel spawn cr-feature --agent review --provider codex --as review-cx \
+  --jsonl "$TASK/check.jsonl" --file "$TASK/prd.md" \
+  --timeout 15m
+
+atw channel send cr-feature --as main --to review --text-file /tmp/cr-brief.md
+atw channel send cr-feature --as main --to review-cx --text-file /tmp/cr-brief.md
+atw channel wait cr-feature --as main --kind done --from review,review-cx --all --timeout 15m
+```
+
+`--all` means every listed worker must emit a matching event.
+
+## Pattern D: One-shot Worker
+
+```bash
+atw channel run --provider codex --message "say hi in 3 words" --timeout 1m
+atw channel run --agent plan --message-file /tmp/plan-question.md --timeout 10m
+```
+
+On success, `run` removes the ephemeral channel. On error/timeout/killed, it
+keeps the channel and prints the path for inspection.
+
+## Pattern E: Forum Channel
+
+Use for issue forums, topic-style feedback, release todos, agent findings, and
+internal changelogs. Read `forum.md` for the full model.
+
+## Pattern F: Take Over Existing Thread
+
+If the user gives a forum/thread name, restore context yourself:
+
+```bash
+atw channel forum <board> --scope global
+atw channel thread <board> <thread> --scope global --raw
+atw channel context list <board> --scope global --thread <thread>
+atw channel messages <board> --scope global --raw --thread <thread>
+```
+
+Output a constraint summary, not a transcript dump:
+
+- user-level problem
+- context files that affect this repo
+- current-version versus future-version requirements
+- whether current code/design satisfies it
+- next action or comment to append

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

@@ -0,0 +1,113 @@
+---
+name: atw-code-review
+description: "沿两个维度审查自某个固定点（提交、分支、标签或合并基点）以来的变更——标准（代码是否遵循了该仓库的文档化编码标准？）和规格（代码是否符合原始问题/规格的要求?）。在并行子代理中同时运行这两项审查，并将结果并排显示。当用户希望审查某个分支、拉取请求、进行中的更改，或要求“审查自 X 以来”的变更时，请使用此功能。"
+---
+
+Two-axis review of the diff between `HEAD` and a fixed point the user supplies:
+
+- **Standards** — does the code conform to this repo's documented coding standards?
+- **Spec** — does the code faithfully implement the originating issue / spec?
+
+Both axes run as **parallel sub-agents** so they don't pollute each other's context, then this skill aggregates their findings.
+
+**This skill only reports — it edits nothing.** Neither this skill nor either sub-agent writes to a source file: not to fix a finding, not to tidy something noticed in passing. They read the frozen patch and produce findings. Hand every finding back to whoever called the review — the user, or `/atw-implement` — and let the caller decide what changes. A reviewer that fixes what it found leaves no independent record of what was wrong, and the next review reads its own edits as the baseline.
+
+The issue tracker should have been provided to you. If `docs/agents/issue-tracker.md` is missing, tell the user to call the Skill tool for `atw-init-repo`, which asks which tracker this repo uses and writes that file.
+
+## Process
+
+### 1. Pin the fixed point
+
+Whatever the user said is the fixed point — a commit SHA, branch name, tag, `main`, `HEAD~5`, etc. If they didn't specify one, ask for it. Confirm it resolves (`git rev-parse <fixed-point>`) before going further — a bad ref should fail here, not inside two parallel sub-agents.
+
+Then **freeze one patch** covering everything under review, and hand that same patch to both sub-agents.
+
+Do **not** use `git diff <fixed-point>...HEAD`. Three-dot syntax compares two *commits*, so the working tree takes no part in it — and this skill is normally called from `atw-implement` **before** the commit. The failure is silent, not loud: when the fixed point has earlier commits behind it, the diff is non-empty (it holds the *previous* ticket's already-reviewed code), the non-empty check passes, and the review reports "passed" without a single line of the new implementation ever being read.
+
+```bash
+base=$(git merge-base "$fixed_point" HEAD)
+patch=$(mktemp)   # bare mktemp — `mktemp -t review-patch` errors on GNU coreutils
+
+# ① committed changes + the current state of every tracked file
+git diff --binary "$base" -- > "$patch"
+
+# ② every untracked, non-ignored file — one at a time, NUL-safe
+git ls-files --others --exclude-standard -z |
+  while IFS= read -r -d '' f; do
+    git diff --no-index --binary -- /dev/null "$f" >> "$patch" || true
+  done
+```
+
+- `git ls-files --others` lists **files**, so no directory expansion is needed. (`git status --porcelain` reports a new directory as a single `?? newdir/` entry — that is why it isn't used here.)
+- `git diff --no-index` **exits 1 when it finds a difference**. That is the normal result, not a failure — hence the `|| true`.
+- Nothing writes to the index, so review stays read-only and never contends for `index.lock`.
+- Cap the size of any single untracked file you inline. `--binary` base64-encodes content, so one image or build artifact can swamp the patch and both sub-agents' context. Over the cap, record the path and skip the body, and leave a line in the patch saying so.
+
+Check that `$patch` is non-empty — this replaces the old "diff is non-empty" check. Also note the commit list via `git log <fixed-point>..HEAD --oneline`. If the patch is large, check its total size before spawning: both sub-agents receive it, so the token cost is doubled.
+
+### 2. Identify the spec source
+
+Look for the originating spec, in this order:
+
+1. A path the user passed as an argument.
+2. Wherever `docs/agents/issue-tracker.md` says specs live — its "When a skill says publish to the issue tracker" section names the location for this repo. Some trackers scope it to the current unit of work rather than a fixed directory; follow whatever resolution step it gives.
+3. Issue references in the commit messages (`#123`, `Closes #45`, GitLab `!67`, etc.) — fetch via the workflow in `docs/agents/issue-tracker.md`.
+4. A spec file under `docs/`, `specs/`, or `.scratch/` matching the branch name or feature.
+5. If nothing is found, ask the user where the spec is. If they say there isn't one, the **Spec** sub-agent will skip and report "no spec available".
+
+### 3. Identify the standards sources
+
+Anything in the repo that documents how code should be written, such as `CODING_STANDARDS.md` or `CONTRIBUTING.md`.
+
+On top of whatever the repo documents, the Standards axis always carries the **smell baseline** below — a fixed set of Fowler code smells (_Refactoring_, ch.3) that applies even when a repo documents nothing. Two rules bind it:
+
+- **The repo overrides.** A documented repo standard always wins; where it endorses something the baseline would flag, suppress the smell.
+- **Always a judgement call.** Each smell is a labelled heuristic ("possible Feature Envy"), never a hard violation — and, like any standard here, skip anything tooling already enforces.
+
+Each smell reads *what it is* → *how to fix*; match it against the diff:
+
+- **Mysterious Name** — a function, variable, or type whose name doesn't reveal what it does or holds. → rename it; if no honest name comes, the design's murky.
+- **Duplicated Code** — the same logic shape appears in more than one hunk or file in the change. → extract the shared shape, call it from both.
+- **Feature Envy** — a method that reaches into another object's data more than its own. → move the method onto the data it envies.
+- **Data Clumps** — the same few fields or params keep travelling together (a type wanting to be born). → bundle them into one type, pass that.
+- **Primitive Obsession** — a primitive or string standing in for a domain concept that deserves its own type. → give the concept its own small type.
+- **Repeated Switches** — the same `switch`/`if`-cascade on the same type recurs across the change. → replace with polymorphism, or one map both sites share.
+- **Shotgun Surgery** — one logical change forces scattered edits across many files in the diff. → gather what changes together into one module.
+- **Divergent Change** — one file or module is edited for several unrelated reasons. → split so each module changes for one reason.
+- **Speculative Generality** — abstraction, parameters, or hooks added for needs the spec doesn't have. → delete it; inline back until a real need shows.
+- **Message Chains** — long `a.b().c().d()` navigation the caller shouldn't depend on. → hide the walk behind one method on the first object.
+- **Middle Man** — a class or function that mostly just delegates onward. → cut it, call the real target direct.
+- **Refused Bequest** — a subclass or implementer that ignores or overrides most of what it inherits. → drop the inheritance, use composition.
+
+### 4. Spawn both sub-agents in parallel
+
+Both sub-agents read the **frozen patch from step 1** and run **no git commands of their own** — same input, no chance of one axis seeing a file the other missed, and no re-deriving the untracked list from memory.
+
+**Standards sub-agent prompt** — include:
+
+- The path to the frozen patch, and the commit list. State plainly: this patch is the complete change under review, including uncommitted and untracked files; do not run git.
+- The list of standards-source files you found in step 3, **plus the smell baseline from step 3** pasted in full — the sub-agent has no other access to it.
+- The brief: "Report — per file/hunk where relevant — (a) every place the diff violates a documented standard: cite the standard (file + the rule); and (b) any baseline smell you spot: name it and quote the hunk. Distinguish hard violations from judgement calls — documented-standard breaches can be hard, but baseline smells are always judgement calls, and a documented repo standard overrides the baseline. Skip anything tooling enforces. Under 400 words."
+
+**Spec sub-agent prompt** — include:
+
+- The path to the frozen patch, and the commit list. Same instruction: the patch is complete; do not run git.
+- The path or fetched contents of the spec.
+- The brief: "Report: (a) requirements the spec asked for that are missing or partial; (b) behaviour in the diff that wasn't asked for (scope creep); (c) requirements that look implemented but where the implementation looks wrong. Quote the spec line for each finding. Under 400 words."
+
+If the spec is missing, skip the Spec sub-agent and note this in the final report.
+
+### 5. Aggregate
+
+Present the two reports under `## Standards` and `## Spec` headings, verbatim or lightly cleaned. Do **not** merge or rerank findings — the two axes are deliberately separate (see _Why two axes_).
+
+End with a one-line summary: total findings per axis, and the worst issue _within each axis_ (if any). Don't pick a single winner across axes — that's the reranking the separation exists to prevent.
+
+## Why two axes
+
+A change can pass one axis and fail the other:
+
+- Code that follows every standard but implements the wrong thing → **Standards pass, Spec fail.**
+- Code that does exactly what the issue asked but breaks the project's conventions → **Spec pass, Standards fail.**
+
+Reporting them separately stops one axis from masking the other.

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

@@ -0,0 +1,3 @@
+interface:
+  display_name: "Oxyteam Code Review"
+  short_description: "审查标准和规范的差异"

package/dist/templates/common/bundled-skills/atw-codebase-design/DEEPENING.md

@@ -0,0 +1,37 @@
+# Deepening
+
+How to deepen a cluster of shallow modules safely, given its dependencies. Assumes the vocabulary in [SKILL.md](SKILL.md) — **module**, **interface**, **seam**, **adapter**.
+
+## Dependency categories
+
+When assessing a candidate for deepening, classify its dependencies. The category determines how the deepened module is tested across its seam.
+
+### 1. In-process
+
+Pure computation, in-memory state, no I/O. Always deepenable — merge the modules and test through the new interface directly. No adapter needed.
+
+### 2. Local-substitutable
+
+Dependencies that have local test stand-ins (PGLite for Postgres, in-memory filesystem). Deepenable if the stand-in exists. The deepened module is tested with the stand-in running in the test suite. The seam is internal; no port at the module's external interface.
+
+### 3. Remote but owned (Ports & Adapters)
+
+Your own services across a network boundary (microservices, internal APIs). Define a **port** (interface) at the seam. The deep module owns the logic; the transport is injected as an **adapter**. Tests use an in-memory adapter. Production uses an HTTP/gRPC/queue adapter.
+
+Recommendation shape: *"Define a port at the seam, implement an HTTP adapter for production and an in-memory adapter for testing, so the logic sits in one deep module even though it's deployed across a network."*
+
+### 4. True external (Mock)
+
+Third-party services (Stripe, Twilio, etc.) you don't control. The deepened module takes the external dependency as an injected port; tests provide a mock adapter.
+
+## Seam discipline
+
+- **One adapter means a hypothetical seam. Two adapters means a real one.** Don't introduce a port unless at least two adapters are justified (typically production + test). A single-adapter seam is just indirection.
+- **Internal seams vs external seams.** A deep module can have internal seams (private to its implementation, used by its own tests) as well as the external seam at its interface. Don't expose internal seams through the interface just because tests use them.
+
+## Testing strategy: replace, don't layer
+
+- Old unit tests on shallow modules become waste once tests at the deepened module's interface exist — delete them.
+- Write new tests at the deepened module's interface. The **interface is the test surface**.
+- Tests assert on observable outcomes through the interface, not internal state.
+- Tests should survive internal refactors — they describe behaviour, not implementation. If a test has to change when the implementation changes, it's testing past the interface.

package/dist/templates/common/bundled-skills/atw-codebase-design/DESIGN-IT-TWICE.md

@@ -0,0 +1,44 @@
+# Design It Twice
+
+When the user wants to explore alternative interfaces for a chosen deepening candidate, use this parallel sub-agent pattern. Based on "Design It Twice" (Ousterhout) — your first idea is unlikely to be the best.
+
+Uses the vocabulary in [SKILL.md](SKILL.md) — **module**, **interface**, **seam**, **adapter**, **leverage**.
+
+## Process
+
+### 1. Frame the problem space
+
+Before spawning sub-agents, write a user-facing explanation of the problem space for the chosen candidate:
+
+- The constraints any new interface would need to satisfy
+- The dependencies it would rely on, and which category they fall into (see [DEEPENING.md](DEEPENING.md))
+- A rough illustrative code sketch to ground the constraints — not a proposal, just a way to make the constraints concrete
+
+Show this to the user, then immediately proceed to Step 2. The user reads and thinks while the sub-agents work in parallel.
+
+### 2. Spawn sub-agents
+
+Spawn 3+ sub-agents in parallel. Each must produce a **radically different** interface for the deepened module.
+
+Prompt each sub-agent with a separate technical brief (file paths, coupling details, dependency category from [DEEPENING.md](DEEPENING.md), what sits behind the seam). The brief is independent of the user-facing problem-space explanation in Step 1. Give each agent a different design constraint:
+
+- Agent 1: "Minimize the interface — aim for 1–3 entry points max. Maximise leverage per entry point."
+- Agent 2: "Maximise flexibility — support many use cases and extension."
+- Agent 3: "Optimise for the most common caller — make the default case trivial."
+- Agent 4 (if applicable): "Design around ports & adapters for cross-seam dependencies."
+
+Include both [SKILL.md](SKILL.md) vocabulary and CONTEXT.md vocabulary in the brief so each sub-agent names things consistently with the architecture language and the project's domain language.
+
+Each sub-agent outputs:
+
+1. Interface (types, methods, params — plus invariants, ordering, error modes)
+2. Usage example showing how callers use it
+3. What the implementation hides behind the seam
+4. Dependency strategy and adapters (see [DEEPENING.md](DEEPENING.md))
+5. Trade-offs — where leverage is high, where it's thin
+
+### 3. Present and compare
+
+Present designs sequentially so the user can absorb each one, then compare them in prose. Contrast by **depth** (leverage at the interface), **locality** (where change concentrates), and **seam placement**.
+
+After comparing, give your own recommendation: which design you think is strongest and why. If elements from different designs would combine well, propose a hybrid. Be opinionated — the user wants a strong read, not a menu.