@menghuan1918/dsh-apollo 0.0.0-stage → 0.3.0

package/skills/diagnosing-bugs/SKILL.md

@@ -0,0 +1,132 @@
+---
+name: diagnosing-bugs
+description: Diagnosis loop for hard bugs and performance regressions. Use when the user says "diagnose"/"debug this", or reports something broken/throwing/failing/slow.
+---
+
+# Diagnosing Bugs
+
+A discipline for hard bugs. Skip phases only when explicitly justified.
+
+## Phase 1 — Build a feedback loop
+
+**This is the skill.** Everything else is mechanical. If you have a **tight** pass/fail signal for the bug — one that goes red on _this_ bug — you will find the cause; bisection, hypothesis-testing, and instrumentation all just consume it. If you don't have one, no amount of staring at code will save you.
+
+Spend disproportionate effort here. **Be aggressive. Be creative. Refuse to give up.**
+
+### Ways to construct one — try them in roughly this order
+
+1. **Failing test** at whatever seam reaches the bug — unit, integration, e2e.
+2. **Curl / HTTP script** against a running dev server.
+3. **CLI invocation** with a fixture input, diffing stdout against a known-good snapshot.
+4. **Headless browser script** (Playwright / Puppeteer) — drives the UI, asserts on DOM/console/network.
+5. **Replay a captured trace.** Save a real network request / payload / event log to disk; replay it through the code path in isolation.
+6. **Throwaway harness.** Spin up a minimal subset of the system (one service, mocked deps) that exercises the bug code path with a single function call.
+7. **Property / fuzz loop.** If the bug is "sometimes wrong output", run 1000 random inputs and look for the failure mode.
+8. **Bisection harness.** If the bug appeared between two known states (commit, dataset, version), automate "boot at state X, check, repeat" so you can `git bisect run` it.
+9. **Differential loop.** Run the same input through old-version vs new-version (or two configs) and diff outputs.
+10. **HITL bash script.** Last resort. If a human must click, drive _them_ with `scripts/hitl-loop.template.sh` so the loop is still structured. Captured output feeds back to you.
+
+Build the right feedback loop, and the bug is 90% fixed.
+
+### Tighten the loop
+
+Treat the loop as a product. Once you have _a_ loop, **tighten** it:
+
+- Can I make it faster? (Cache setup, skip unrelated init, narrow the test scope.)
+- Can I make the signal sharper? (Assert on the specific symptom, not "didn't crash".)
+- Can I make it more deterministic? (Pin time, seed RNG, isolate filesystem, freeze network.)
+
+A 30-second flaky loop is barely better than no loop; a 2-second deterministic one is tight — a debugging superpower.
+
+### Non-deterministic bugs
+
+The goal is not a clean repro but a **higher reproduction rate**. Loop the trigger 100×, parallelise, add stress, narrow timing windows, inject sleeps. A 50%-flake bug is debuggable; 1% is not — keep raising the rate until it's debuggable.
+
+### When you genuinely cannot build a loop
+
+Stop and say so explicitly. List what you tried. Ask the user for: (a) access to whatever environment reproduces it, (b) a captured artifact (HAR file, log dump, core dump, screen recording with timestamps), or (c) permission to add temporary production instrumentation. Do **not** proceed to hypothesise without a loop.
+
+### Completion criterion — a tight loop that goes red
+
+Phase 1 is done when the loop is **tight** and **red-capable**: you can name **one command** — a script path, a test invocation, a curl — that you have **already run at least once** (paste the invocation and its output), and that is:
+
+- [ ] **Red-capable** — it drives the actual bug code path and asserts the **user's exact symptom**, so it can go red on this bug and green once fixed. Not "runs without erroring" — it must be able to _catch this specific bug_.
+- [ ] **Deterministic** — same verdict every run (flaky bugs: a pinned, high reproduction rate, per above).
+- [ ] **Fast** — seconds, not minutes.
+- [ ] **Agent-runnable** — you can run it unattended; a human in the loop only via `scripts/hitl-loop.template.sh`.
+
+If you catch yourself reading code to build a theory before this command exists, **stop — jumping straight to a hypothesis is the exact failure this skill prevents.** No red-capable command, no Phase 2.
+
+## Phase 2 — Reproduce + minimise
+
+Run the loop. Watch it go red — the bug appears.
+
+Confirm:
+
+- [ ] The loop produces the failure mode the **user** described — not a different failure that happens to be nearby. Wrong bug = wrong fix.
+- [ ] The failure is reproducible across multiple runs (or, for non-deterministic bugs, reproducible at a high enough rate to debug against).
+- [ ] You have captured the exact symptom (error message, wrong output, slow timing) so later phases can verify the fix actually addresses it.
+
+### Minimise
+
+Once it's red, shrink the repro to the **smallest scenario that still goes red**. Cut inputs, callers, config, data, and steps **one at a time**, re-running the loop after each cut — keep only what is load-bearing for the failure.
+
+Why bother: a minimal repro shrinks the hypothesis space in Phase 3 (fewer moving parts left to suspect) and becomes the clean regression test in Phase 5.
+
+Done when **every remaining element is load-bearing** — removing any one of them makes the loop go green.
+
+Do not proceed until you have reproduced **and** minimised.
+
+## Phase 3 — Hypothesise
+
+Generate **3–5 ranked hypotheses** before testing any of them. Single-hypothesis generation anchors on the first plausible idea.
+
+Each hypothesis must be **falsifiable**: state the prediction it makes.
+
+> Format: "If <X> is the cause, then <changing Y> will make the bug disappear / <changing Z> will make it worse."
+
+If you cannot state the prediction, the hypothesis is a vibe — discard or sharpen it.
+
+**Show the ranked list to the user before testing.** They often have domain knowledge that re-ranks instantly ("we just deployed a change to #3"), or know hypotheses they've already ruled out. Cheap checkpoint, big time saver. Don't block on it — proceed with your ranking if the user is AFK.
+
+## Phase 4 — Instrument
+
+Each probe must map to a specific prediction from Phase 3. **Change one variable at a time.**
+
+Tool preference:
+
+1. **Debugger / REPL inspection** if the env supports it. One breakpoint beats ten logs.
+2. **Targeted logs** at the boundaries that distinguish hypotheses.
+3. Never "log everything and grep".
+
+**Tag every debug log** with a unique prefix, e.g. `[DEBUG-a4f2]`. Cleanup at the end becomes a single grep. Untagged logs survive; tagged logs die.
+
+**Perf branch.** For performance regressions, logs are usually wrong. Instead: establish a baseline measurement (timing harness, `performance.now()`, profiler, query plan), then bisect. Measure first, fix second.
+
+## Phase 5 — Fix + regression test
+
+Write the regression test **before the fix** — but only if there is a **correct seam** for it.
+
+A correct seam is one where the test exercises the **real bug pattern** as it occurs at the call site. If the only available seam is too shallow (single-caller test when the bug needs multiple callers, unit test that can't replicate the chain that triggered the bug), a regression test there gives false confidence.
+
+**If no correct seam exists, that itself is the finding.** Note it. The codebase architecture is preventing the bug from being locked down. Flag this in the post-mortem.
+
+If a correct seam exists:
+
+1. Turn the minimised repro into a failing test at that seam.
+2. Watch it fail.
+3. Apply the fix.
+4. Watch it pass.
+5. Re-run the Phase 1 feedback loop against the original (un-minimised) scenario.
+
+## Phase 6 — Cleanup + post-mortem
+
+Required before declaring done:
+
+- [ ] Original repro no longer reproduces (re-run the Phase 1 loop)
+- [ ] Regression test passes (or absence of seam is documented)
+- [ ] All `[DEBUG-...]` instrumentation removed (`grep` the prefix)
+- [ ] Throwaway prototypes deleted (or moved to a clearly-marked debug location)
+- [ ] The hypothesis that turned out correct is stated in the commit / PR message — so the next debugger learns
+
+**Then ask: what would have prevented this bug?** If the answer involves architectural change (no good test seam, tangled callers, hidden coupling), flag it for the user as an architecture improvement opportunity. Make the recommendation **after** the fix is in, not before — you have more information now than when you started.

package/skills/diagnosing-bugs/scripts/hitl-loop.template.sh

@@ -0,0 +1,55 @@
+#!/usr/bin/env bash
+# HITL (Human-In-The-Loop) debugging script template.
+# Used when a human must interact to reproduce a bug.
+# Drives the human through structured steps and captures output.
+
+set -euo pipefail
+
+LOG_DIR="${DEBUG_LOG_DIR:-/tmp/debug-hitl}"
+mkdir -p "$LOG_DIR"
+
+TIMESTAMP=$(date +%Y%m%d-%H%M%S)
+LOG_FILE="$LOG_DIR/hitl-$TIMESTAMP.log"
+
+echo "[HITL] Starting debug session. Output: $LOG_FILE"
+echo "[HITL] Timestamp: $TIMESTAMP"
+echo ""
+
+step() {
+    local n=$1; shift
+    echo "" | tee -a "$LOG_FILE"
+    echo "=== Step $n: $* ===" | tee -a "$LOG_FILE"
+    echo "[HITL] Press Enter when ready..." | tee -a "$LOG_FILE"
+    read -r
+}
+
+capture() {
+    local label=$1; shift
+    echo "[HITL] Capturing: $label" | tee -a "$LOG_FILE"
+    echo "--- $label ---" >> "$LOG_FILE"
+    "$@" 2>&1 | tee -a "$LOG_FILE"
+    echo "--- end $label ---" >> "$LOG_FILE"
+}
+
+# --- Steps go here ---
+
+step 1 "Reproduce the issue"
+echo "Follow these steps to reproduce:" | tee -a "$LOG_FILE"
+echo "  1. <describe step>" | tee -a "$LOG_FILE"
+echo "  2. <describe step>" | tee -a "$LOG_FILE"
+echo "  3. Observe: <expected vs actual>" | tee -a "$LOG_FILE"
+echo ""
+echo "[HITL] Paste the output or error message, then press Enter:" | tee -a "$LOG_FILE"
+read -r user_output
+echo "User observed: $user_output" >> "$LOG_FILE"
+
+step 2 "Collect diagnostics"
+capture "git-status" git status --short
+capture "git-diff" git diff --stat
+capture "recent-logs" tail -50 /var/log/app.log 2>/dev/null || echo "(no log file)"
+
+step 3 "Check environment"
+capture "env" env | grep -v -i -E 'secret|password|token|key' || true
+
+echo "" | tee -a "$LOG_FILE"
+echo "[HITL] Session complete. Log: $LOG_FILE" | tee -a "$LOG_FILE"

package/skills/exec/SKILL.md

@@ -0,0 +1,91 @@
+---
+name: exec
+description: "当用户调用 /exec 并提供已批准的主 Spec 时使用。负责编排逐 Spec worktree、波次 workflow 执行、合并、验证和最终代码审查。"
+---
+
+# 执行多 Spec 任务
+
+在目标仓库的 `.worktrees/` 隔离 worktree 中执行已批准的子 Spec。主工作区始终是合入目标；编排状态只保存在当前会话上下文中。
+
+## 前置条件
+
+- 主 Spec 索引至少两个子 Spec。
+- 确认唯一目标仓库；主工作区位于命名分支且工作树干净。
+- `.worktrees/` 已被目标仓库 `.gitignore` 覆盖；没有就先提示用户加入。
+
+## 执行
+
+1. 读取主 Spec 和全部子 Spec，确认共享契约、依赖 DAG、验证命令。
+2. 按依赖波次创建任务列表。
+3. 每波：从主工作区 HEAD 建分支，在 `<repo>/.worktrees/exec-<任务>/<子任务>` 建 worktree，再派遣整波节点。前置波全部合入后才创建下一波 worktree。
+
+## 波次执行：workflow 驱动
+
+每波恰好一次 `workflow` 工具调用：脚本只做波内扇出与 CR 循环——worktree 创建、合并、清理全在主线程（workflow 引擎无文件系统，脚本碰不了 git）。节点契约（prompt 要素、schema、失败语义）见 `dev` skill。本波 specs 经 workflow 的 `args` 传入，每个元素带具体值：`{ id, specPath, worktree, contracts, verify }`（`worktree` 为绝对路径）。
+
+```js
+const specs = args.specs
+// 质量档 = 本会话可用的最强模型。留空即不覆盖路由：子代理继承父会话的
+// provider/model，任何环境都能跑。有固定质量档时只改这一处，例如：
+// const quality = { provider: '<provider>', model: '<model>' }
+const quality = {}
+const implSchema = { type: 'object', required: ['status', 'commit', 'verification', 'summary'], properties: { status: { type: 'string', enum: ['complete', 'blocked'] }, commit: { type: 'string' }, verification: { type: 'string' }, summary: { type: 'string' }, blocker: { type: 'string' } }, additionalProperties: false }
+const verdictSchema = { type: 'object', required: ['status', 'findings'], properties: { status: { type: 'string', enum: ['APPROVED', 'APPROVED_WITH_NOTES', 'CHANGES_REQUIRED', 'BLOCKED'] }, findings: { type: 'array', items: { type: 'string' } } }, additionalProperties: false }
+const implPrompt = (s) => `你在隔离 worktree ${s.worktree} 中工作：bash 一律 workdir=${s.worktree}，文件工具用绝对路径。以预建 worktree 模式遵循 main-agent-driven-development skill（跳过其内部 CR 步骤，CR 由本编排循环承担，节点不自行派 reviewer）。只实现 ${s.specPath} 的子 Spec，遵守共享契约：${s.contracts}。运行验证：${s.verify}。提交后按 schema 报告。不得合入或删除 worktree；阻塞时 status=blocked 并填 blocker。`
+const reviewPrompt = (s, impl) => `只读审查 worktree ${s.worktree} 相对基线的完整 diff（bash 一律 workdir=${s.worktree}）。Spec：${s.specPath}。实现摘要：${impl.summary}。已跑验证：${impl.verification}。按严重度列出问题，每条附文件与行号；按 schema 四态判定。不得编辑、提交、合并。`
+const fixPrompt = (s, impl, verdict) => `你在隔离 worktree ${s.worktree} 中继续前人的实现（bash 一律 workdir=${s.worktree}，文件工具用绝对路径）。此前摘要：${impl.summary}（commit ${impl.commit}）。reviewer 发现：${verdict.findings.join('；')}。逐条修复真实问题，对误报在 summary 中给出理由；重跑验证：${s.verify}；提交后按 schema 报告。不得合入。`
+log(`wave: dispatching ${specs.length} spec(s)`)
+return await parallel(specs.map((s) => async () => {
+  let impl = await agent(implPrompt(s), { label: `${s.id}-impl`, schema: implSchema, ...quality })
+  if (!impl || impl.status !== 'complete') return { spec: s.id, status: 'node-failed', impl }
+  let verdict = await agent(reviewPrompt(s, impl), { label: `${s.id}-cr-1`, schema: verdictSchema, ...quality })
+  let round = 1
+  while (verdict && verdict.status === 'CHANGES_REQUIRED' && round < 5) {
+    impl = await agent(fixPrompt(s, impl, verdict), { label: `${s.id}-fix-${round}`, schema: implSchema, ...quality })
+    if (!impl || impl.status !== 'complete') return { spec: s.id, status: 'fix-failed', round }
+    round += 1
+    verdict = await agent(reviewPrompt(s, impl), { label: `${s.id}-cr-${round}`, schema: verdictSchema, ...quality })
+  }
+  return { spec: s.id, status: verdict ? verdict.status : 'review-failed', rounds: round, impl, verdict }
+}))
+```
+
+要点：
+
+- CR 循环是代码不是纪律：每轮全新 reviewer（`agent()` 一次一代理）、schema 校验判定、5 轮熔断。
+- 子代理失败 resolve `null` → 该 Spec 记 `node-failed`，`parallel` 等整波，单个失败不拖垮其他 Spec。
+- 质量档（本会话最强模型）在脚本顶部一处定义，impl / review / fix 节点全部使用；留空则由子代理继承父会话路由。
+- 调用前台阻塞至整波结束，波内无人工交互；节点的疑问一律按 blocked 上报，由主线程处置。
+- 返回值是结构化波次报告：只有 `status` 为 `APPROVED` / `APPROVED_WITH_NOTES` 的 Spec 进入合并。
+
+## 合并
+
+对每个完成节点：确认已提交且验证通过 → 检查变更文件排除越界 → 合入主工作区 → 合并后验证 → 删除 worktree 和子分支。
+
+小而明确的冲突由主代理直接解决。复杂冲突用 `.worktrees/` 下新的修复 worktree 和开发节点。不得合并失败或阻塞的节点。
+
+## 最终审查
+
+所有子 Spec 合入后，运行完整集成验证，然后派遣一个全新只读 reviewer 子代理（质量档 = 本会话最强模型）审查全量集成结果：
+
+```
+subagent(
+  prompt="只读审查 <workspace> 的 <base>..HEAD diff（bash 一律 workdir=<workspace>）。
+         主 Spec: <path> | 全部子 Spec | 共享契约 | 变更文件 | 实现摘要 | 验证结果。
+         按严重度列出问题，每条附文件与行号。
+         返回 APPROVED / APPROVED_WITH_NOTES / CHANGES_REQUIRED / BLOCKED。不得编辑、提交、合并。"
+)
+```
+
+用 `wait_subagent` 等待。`CHANGES_REQUIRED` 时不需要询问用户——主代理直接分类并修复所有真实 bug，对误报和既有行为在上下文中简述理由；修复后重新验证，再派全新 reviewer 复审。软熔断 3 轮后仍存在严重或阻塞问题则停止修复循环，如实向用户报告剩余问题。
+
+## 收尾
+
+运行完整验证，核对 Spec，报告分支、提交、验证结果和遗留问题，询问用户下一步。未经用户选择不得创建 PR 或删除分支。
+
+## KISS
+
+- 一个子 Spec、一个 worktree、一个开发节点。
+- 主线程只持仓库拓扑（分支/worktree/合并/清理）；波内扇出交给一次 workflow 调用。
+- 状态只保存在会话上下文；不增加集成分支、调度脚本或状态文件。
+- 等待靠完成通知自动送达，需要结果才继续时再等待。不得用 `sleep` 轮询。

package/skills/handoff/SKILL.md

@@ -0,0 +1,23 @@
+---
+name: handoff
+description: 把当前对话压缩成一份交接文档，供下一个全新 agent 接续。
+argument-hint: "下一个会话将用来做什么？"
+disable-model-invocation: true
+---
+
+把当前对话压缩成一份交接文档，让全新 agent 无需重读父会话即可接续工作。
+
+## 存放与复用
+
+- **已有则复写**：若会话上下文中已存在交接文档（本会话早前写过，或会话开启时注入了一份），整篇重写该文件，不新建。
+- **否则新建**：工作区有 `.workspace-docs/` 时写 `.workspace-docs/notes/<仓库或主题>/`，交接本质上就是一篇 note；否则写目标仓库现有的文档目录。文件名带日期前缀，沿用目录内现有命名风格。
+- 写入 `.workspace-docs/` 时新建文件带 OKF 头（`type: Note` 及 `title`/`description`/`tags`/`status`/`repos`），不登记 `index.md`；提交/推送遵循该仓库既有纪律。目标仓库无此约定时用其现有文档格式。
+- 两个位置都不存在时，回退写 OS 临时目录。
+
+## 内容要求
+
+- 含「建议技能」一节，提示接手 agent 应调用的技能。
+- 不复述已落盘物（spec、plan、ADR、issue、commit、diff）的内容，只给路径或 URL。
+- 只写客观事实与验证证据，不写自我免责叙事。
+- 脱敏 API key、密码、个人身份信息等敏感内容。
+- 用户带参数调用时，参数即下一会话焦点，据此裁剪文档。

package/skills/main-agent-driven-development/SKILL.md

@@ -0,0 +1,64 @@
+---
+name: main-agent-driven-development
+description: "仅当用户或编排技能显式调用 /main-agent-driven-development 来完成一个边界明确的实现任务时使用。"
+---
+
+# 主代理驱动开发
+
+由当前 Agent 会话直接实现一个边界明确的 Spec。外层 `/exec` 编排器负责 worktree 和合入生命周期。
+
+## Worktree 模式
+
+只选一种：
+
+- **预建模式** — 调用方已提供隔离 worktree 并声明负责生命周期时，直接使用；不得创建、合并或删除 worktree。
+- **独立模式** — 否则识别目标仓库，要求基线位于命名分支，记录起始 SHA，在仓库 `.worktrees/` 下创建 worktree。
+
+所有操作必须在选定 worktree 内完成。隔离后不得编辑原始 checkout。
+
+## 流程
+
+1. 读取分配的 Spec 及相关仓库指令。
+2. 确认任务边界、依赖、验收标准和必要验证。只有缺失决策真正阻塞实现时才提问。
+3. 根据 Spec 初始化任务列表。
+4. 项目初始化 + 基线验证。基线失败时先报告；仅当失败明确无关且已记录时才继续。
+5. 直接实现，限定在 Spec 范围。遵循 `tdd` skill（本包已捆绑）：先写失败测试，再写最小实现。
+6. 每个逻辑步骤后运行聚焦验证、自审 diff，内容完整时提交。验证标准：本轮运行命令并确认输出，不得以"应该通过"代替实际运行。
+7. 实现完成后运行全部必要验证。
+8. 验证失败或 CR 发现 bug 时，遵循 `diagnosing-bugs` skill（本包已捆绑）：先建反馈循环找根因，再修复。
+9. 执行内部 CR 循环（见下文）。例外：作为 `/exec` dev 后端 workflow 波次中的实现节点时，**跳过本步**——CR 循环由编排脚本承担，节点只实现、验证、提交、报告。
+10. 提交全部已批准修复，向调用方报告。
+
+保持 KISS。优先复用既有模式，小而完整的修改，只做 Spec 必需的针对性重构。
+
+## 内部 CR 循环
+
+完整验证后，派遣恰好一个全新只读 reviewer 子代理（质量档 = 本会话最强模型）：
+
+```
+subagent(
+  prompt="Review <worktree-abs-path> from <base_sha> to HEAD.
+         Spec: <path>
+         Implementation summary: <brief>
+         Changed files: <list>
+         Verification already run: <commands and results>"
+)
+```
+
+要求附文件和行号，返回一种状态：`APPROVED` / `APPROVED_WITH_NOTES` / `CHANGES_REQUIRED` / `BLOCKED`。
+
+用 `wait_subagent` 等待审查完成。收到结果后直接修复所有必要的正确性错误、Spec 缺口、安全问题、集成风险和验证缺口——不需要询问用户。验证并提交修复后，再用 `subagent` 派遣全新 reviewer。重复直到 `APPROVED` 或仅含非阻塞建议。
+
+不得自我批准，不得复用旧 reviewer。
+
+## 完成契约
+
+报告完成前必须满足：
+
+- 所有分配的验收标准已实现
+- 必要验证已在本轮运行并通过（有命令输出为证）
+- 没有未提交的实现修改
+- 内部 CR 已通过且无必要修复项
+- 可提供最终 commit SHA
+
+如实报告阻塞。不得自行合入；调用方负责集成和清理。

package/skills/tdd/SKILL.md

@@ -0,0 +1,34 @@
+---
+name: tdd
+description: Test-driven development. Use when the user wants to build features or fix bugs test-first, mentions "red-green-refactor", or wants integration tests.
+---
+
+# Test-Driven Development
+
+TDD is the red → green loop. This skill is the reference that makes that loop produce tests worth keeping: what a good test is, where tests go, the anti-patterns, and the rules of the loop. Every section applies on every cycle — consult them before and during the loop, not after.
+
+## What a good test is
+
+Tests verify behavior through public interfaces, not implementation details. Code can change entirely; tests shouldn't. A good test reads like a specification — "user can checkout with valid cart" tells you exactly what capability exists — and survives refactors because it doesn't care about internal structure.
+
+See [tests.md](tests.md) for examples and [mocking.md](mocking.md) for mocking guidelines.
+
+## Seams — where tests go
+
+A **seam** is the public boundary you test at: the interface where you observe behavior without reaching inside. Tests live at seams, never against internals.
+
+**Test only at pre-agreed seams.** Before writing any test, write down the seams under test and confirm them with the user. No test is written at an unconfirmed seam. You can't test everything — agreeing the seams up front is how testing effort lands on the critical paths and complex logic instead of every edge case.
+
+Ask: "What's the public interface, and which seams should we test?"
+
+## Anti-patterns
+
+- **Implementation-coupled** — mocks internal collaborators, tests private methods, or verifies through a side channel (querying the database instead of using the interface). The tell: the test breaks when you refactor but behavior hasn't changed.
+- **Tautological** — the assertion recomputes the expected value the way the code does (`expect(add(a, b)).toBe(a + b)`, a snapshot derived by hand the same way, a constant asserted equal to itself), so it passes by construction and can never disagree with the code. Expected values must come from an independent source of truth — a known-good literal, a worked example, the spec.
+- **Horizontal slicing** — writing all tests first, then all implementation. Bulk tests verify _imagined_ behavior: you test the _shape_ of things rather than user-facing behavior, the tests go insensitive to real changes, and you commit to test structure before understanding the implementation. Work in **vertical slices** instead — one test → one implementation → repeat, each test a **tracer bullet** that responds to what the last cycle taught you.
+
+## Rules of the loop
+
+- **Red before green.** Write the failing test first, then only enough code to pass it. Don't anticipate future tests or add speculative features.
+- **One slice at a time.** One seam, one test, one minimal implementation per cycle.
+- **Refactoring is not part of the loop.** It belongs to the review stage (see the `code-review` skill), not the red → green implementation cycle.

package/skills/tdd/mocking.md

@@ -0,0 +1,59 @@
+# When to Mock
+
+Mock at **system boundaries** only:
+
+- External APIs (payment, email, etc.)
+- Databases (sometimes - prefer test DB)
+- Time/randomness
+- File system (sometimes)
+
+Don't mock:
+
+- Your own classes/modules
+- Internal collaborators
+- Anything you control
+
+## Designing for Mockability
+
+At system boundaries, design interfaces that are easy to mock:
+
+**1. Use dependency injection**
+
+Pass external dependencies in rather than creating them internally:
+
+```typescript
+// Easy to mock
+function processPayment(order, paymentClient) {
+  return paymentClient.charge(order.total);
+}
+
+// Hard to mock
+function processPayment(order) {
+  const client = new StripeClient(process.env.STRIPE_KEY);
+  return client.charge(order.total);
+}
+```
+
+**2. Prefer SDK-style interfaces over generic fetchers**
+
+Create specific functions for each external operation instead of one generic function with conditional logic:
+
+```typescript
+// GOOD: Each function is independently mockable
+const api = {
+  getUser: (id) => fetch(`/users/${id}`),
+  getOrders: (userId) => fetch(`/users/${userId}/orders`),
+  createOrder: (data) => fetch('/orders', { method: 'POST', body: data }),
+};
+
+// BAD: Mocking requires conditional logic inside the mock
+const api = {
+  fetch: (endpoint, options) => fetch(endpoint, options),
+};
+```
+
+The SDK approach means:
+- Each mock returns one specific shape
+- No conditional logic in test setup
+- Easier to see which endpoints a test exercises
+- Type safety per endpoint

package/skills/tdd/tests.md

@@ -0,0 +1,77 @@
+# Good and Bad Tests
+
+## Good Tests
+
+**Integration-style**: Test through real interfaces, not mocks of internal parts.
+
+```typescript
+// GOOD: Tests observable behavior
+test("user can checkout with valid cart", async () => {
+  const cart = createCart();
+  cart.add(product);
+  const result = await checkout(cart, paymentMethod);
+  expect(result.status).toBe("confirmed");
+});
+```
+
+Characteristics:
+
+- Tests behavior users/callers care about
+- Uses public API only
+- Survives internal refactors
+- Describes WHAT, not HOW
+- One logical assertion per test
+
+## Bad Tests
+
+**Implementation-detail tests**: Coupled to internal structure.
+
+```typescript
+// BAD: Tests implementation details
+test("checkout calls paymentService.process", async () => {
+  const mockPayment = jest.mock(paymentService);
+  await checkout(cart, payment);
+  expect(mockPayment.process).toHaveBeenCalledWith(cart.total);
+});
+```
+
+Red flags:
+
+- Mocking internal collaborators
+- Testing private methods
+- Asserting on call counts/order
+- Test breaks when refactoring without behavior change
+- Test name describes HOW not WHAT
+- Verifying through external means instead of interface
+
+```typescript
+// BAD: Bypasses interface to verify
+test("createUser saves to database", async () => {
+  await createUser({ name: "Alice" });
+  const row = await db.query("SELECT * FROM users WHERE name = ?", ["Alice"]);
+  expect(row).toBeDefined();
+});
+
+// GOOD: Verifies through interface
+test("createUser makes user retrievable", async () => {
+  const user = await createUser({ name: "Alice" });
+  const retrieved = await getUser(user.id);
+  expect(retrieved.name).toBe("Alice");
+});
+```
+
+**Tautological tests**: Expected value restates the implementation, so the test passes by construction.
+
+```typescript
+// BAD: Expected value is recomputed the way the code computes it
+test("calculateTotal sums line items", () => {
+  const items = [{ price: 10 }, { price: 5 }];
+  const expected = items.reduce((sum, i) => sum + i.price, 0);
+  expect(calculateTotal(items)).toBe(expected);
+});
+
+// GOOD: Expected value is an independent, known literal
+test("calculateTotal sums line items", () => {
+  expect(calculateTotal([{ price: 10 }, { price: 5 }])).toBe(15);
+});
+```