@aipper/aiws-spec 0.0.51 → 0.0.53

package/docs/pi-plugins-manifest.json

@@ -14,13 +14,13 @@
   ],
   "recommended_a": [
     {
-      "id": "pi-extension-settings",
-      "package": "pi-extension-settings",
+      "id": "@juanibiapina/pi-extension-settings",
+      "package": "@juanibiapina/pi-extension-settings",
       "tier": "recommended_a"
     },
     {
-      "id": "pi-powerbar",
-      "package": "pi-powerbar",
+      "id": "@juanibiapina/pi-powerbar",
+      "package": "@juanibiapina/pi-powerbar",
       "tier": "recommended_a"
     },
     {
@@ -39,8 +39,8 @@
       "tier": "recommended_a"
     },
     {
-      "id": "rpiv-ask-user-question",
-      "package": "rpiv-ask-user-question",
+      "id": "@juicesharp/rpiv-ask-user-question",
+      "package": "@juicesharp/rpiv-ask-user-question",
       "tier": "recommended_a"
     },
     {
@@ -63,7 +63,8 @@
     {
       "id": "pi-mcp-adapter",
       "package": "pi-mcp-adapter",
-      "tier": "recommended_b"
+      "tier": "recommended_b",
+      "reason": "MCP adapter; heavy deps \u2014 sequential install with timeout; may need manual retry"
     },
     {
       "id": "pi-fff",
@@ -76,8 +77,8 @@
       "tier": "recommended_b"
     },
     {
-      "id": "plan-mode",
-      "package": "plan-mode",
+      "id": "pi-plan-mode",
+      "package": "pi-plan-mode",
       "tier": "recommended_b"
     },
     {

package/docs/pi-plugins-manifest.md

@@ -54,12 +54,12 @@ Low conflict with AIWS governance; useful quality-of-life.
 
 | package | notes |
 |---------|--------|
-| `pi-extension-settings` | settings UX |
-| `pi-powerbar` | status bar |
+| `@juanibiapina/pi-extension-settings` | settings UX |
+| `@juanibiapina/pi-powerbar` | status bar |
 | `pi-lsp` | LSP |
 | `pi-hashline-edit-pro` | edit helper (watch tool names vs force deny) |
 | `rpiv-todo` | todos |
-| `rpiv-ask-user-question` | structured questions |
+| `@juicesharp/rpiv-ask-user-question` | structured questions |
 | `pi-btw` | asides |
 | `pi-caffeinate` | keep awake |
 | `pi-workspace-history` | history |
@@ -68,10 +68,10 @@ Low conflict with AIWS governance; useful quality-of-life.
 
 | package | notes |
 |---------|--------|
-| `pi-mcp-adapter` | MCP |
+| `pi-mcp-adapter` | MCP (heavy deps; install may hang — retry alone or skip) |
 | `pi-fff` | file finder |
 | `pi-slopchop` | slop cleanup |
-| `plan-mode` | plan UX (AIWS keeps plan truth) |
+| `pi-plan-mode` | plan UX (AIWS keeps plan truth) |
 | `pi-cache-optimizer` | cache (truncation caution) |
 | `pi-rtk-optimizer` | RTK |
 | `pi-agent-browser-native` | browser |
@@ -102,7 +102,7 @@ Low conflict with AIWS governance; useful quality-of-life.
 - Missing **required** → exit code ≠ 0  
 - Conflicts / forbidden installed → warn (exit ≠ 0 if any required missing or any conflict)  
 - `init --pi` / `update` (when `.pi/` exists or `--pi`): print same report as **warn**; do not fail init/update by default  
-- Optional `--install-pi-plugins`: install **required only** (user scope); recommended stay print-only
+- Optional `--install-pi-plugins`: install **all declared installable** plugins (required + recommended A/B, user scope); never forbidden; default without flag remains detect+prompt only
 
 ## Related
 

package/docs/skill-manifest.json

@@ -0,0 +1,18 @@
+{
+  "version": 1,
+  "description": "Default skills installed by `aiws skill add`",
+  "sources": [
+    {
+      "source": "https://gitea.aipper.de/github/taste-skill",
+      "description": "67K-star collection: anti-slop frontend design rules (Impeccable Design, Zero Emoji, Phosphor Icons, layout diversification, etc.)"
+    },
+    {
+      "source": "https://gitea.aipper.de/github/skills",
+      "description": "Engineering workflow pipeline: grill-with-docs → to-spec → to-tickets → implement → code-review + tdd, domain-modeling, handoff, research, prototype, grill-me"
+    }
+  ],
+  "notes": [
+    "Add more sources here as curated defaults.",
+    "aiws-built-in skills (grill-me, ws-*, p-aiws-*) are shipped via templates and do not need listing here."
+  ]
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@aipper/aiws-spec",
-  "version": "0.0.51",
+  "version": "0.0.53",
   "description": "AIWS spec and templates (single source of truth).",
   "type": "module",
   "files": [

package/templates/workspace/.opencode/README.md

@@ -0,0 +1,49 @@
+# OpenCode Skills — Two-Layer Architecture
+
+This workspace uses a layered skill architecture:
+
+## Layer 1: Engineering Pipeline (mattpocock/skills)
+
+Default entry for daily engineering work. Skills auto-load by intent.
+
+```
+/grill-with-docs  →  Design discussion with domain modeling + ADR
+/to-spec          →  Synthesize conversation into a spec
+/to-tickets       →  Break spec into executable tickets
+/implement        →  Implement from spec/tickets (with TDD)
+/code-review      →  Review against standards + spec
+/handoff          →  Compact session for handoff to another agent
+```
+
+Also available: `/tdd`, `/research`, `/prototype`, `/domain-modeling`, `/grill-me`, `/diagnosing-bugs`, `/resolving-merge-conflicts`, etc.
+
+## Layer 2: aiws Governance (ws-*)
+
+Supplemental skills for process, audit, and compliance. Use when the work needs:
+- Traceable goal/change/contract tracking
+- Completion gates and evidence
+- Spec/quality review process
+
+```
+/ws-goal                     →  Set auditable goal with dependency check
+/ws-plan                     →  Bind change with requirements contract
+/ws-dev / ws-dev-lite        →  Develop under AIWS constraints
+/ws-frontend-design          →  Apply frontend design rules
+/ws-finish                   →  Merge change + archive evidence
+/ws-spec-review              →  Process completeness audit
+/ws-quality-review           →  Implementation quality + test coverage
+/ws-verify-before-complete   →  Pre-finish validation gate
+```
+
+## When to Use Which
+
+| You want to... | Use |
+|---|---|
+| Explore and refine an idea | `/grill-with-docs` |
+| Create a spec from discussion | `/to-spec` |
+| Implement a well-defined feature | `/implement` (or `/ws-dev` if aiws governance needed) |
+| Fix a small bug quickly | `/ws-dev-lite` |
+| Review a branch | `/code-review` |
+| Audit process compliance | `/ws-spec-review` + `/ws-quality-review` |
+| Merge and archive | `/ws-finish` |
+| Design UI | `/ws-frontend-design` |

package/templates/workspace/.opencode/command/ws-frontend-design.md

@@ -0,0 +1,17 @@
+---
+description: 前端设计：视觉优先的 UI/UX 实现，先信息层级与构图，再组件细节
+---
+<!-- AIWS_MANAGED_BEGIN:opencode:ws-frontend-design -->
+# ws frontend design
+
+用中文输出（命令/路径/代码标识符保持原样不翻译）。
+
+目标：在 AIWS 约束下交付可运行、可验证、视觉方向明确的前端界面。先信息层级与构图，再组件细节。品牌页重视觉锚点，产品页重可操作性。
+
+前置：
+1) 运行 `$ws-preflight` 读取真值文件。
+2) 判断任务类型：`landing`（品牌/营销）| `app-ui`（dashboard/工具）| `polish-only`（仅视觉提质）。
+3) medium/complex 任务先用 `$ws-plan` 落盘计划。
+
+详细设计指令见对应的 SKILL.md 文件：`skill(name="ws-frontend-design")`
+<!-- AIWS_MANAGED_END:opencode:ws-frontend-design -->

package/templates/workspace/.opencode/commands/using-aiws.md

@@ -15,13 +15,24 @@ description: 默认 workflow router：先判定阶段，再进入具体 ws-* 入
    - 若未检测到：输出 `OpenCode mode: standard-opencode`
 2) 若缺失任一真值文件：先 `/ws-preflight`，必要时运行 `aiws init .`，不要继续实现。
 3) 若任务意图、归因或验证入口不明确：先提 1-3 个关键澄清问题并停止。
-4) 路由规则：
-   - 需求/验收/合同变更：`/ws-req-review`
-   - 中大型实现或需要 change/worktree：`/ws-plan`
-   - 小步明确实现：`/ws-dev`（若是 simple/local 单点修复，可显式进入 `/ws-dev-lite`）
-   - 评审/审计：`/ws-review`
-   - finish / merge / push / cleanup：`/ws-finish`
-   - handoff / archive summary：`/ws-handoff`
+  4) 两层架构：默认走 mattpocock/skills 工程流水线，需要 aiws 治理时叠加 ws-*。
+     - 工程入口（mattpocock）：
+       - 需求澄清/设计探讨：`/grill-with-docs`（→ `/grilling` + `/domain-modeling`）
+       - 输出 spec：`/to-spec`
+       - 拆 tickets：`/to-tickets`
+       - 实现（含 TDD）：`/implement`
+       - 代码审查：`/code-review`
+       - 交接：`/handoff`
+     - 治理叠加（aiws ws-*）：
+       - 设定可审计目标：`/ws-goal`
+       - 绑定 change + contract：`/ws-plan`
+       - 小步实现（simple/local 单点修复）：`/ws-dev-lite`
+       - 完整开发（AIWS 约束下）：`/ws-dev`
+       - 前端设计规则：`/ws-frontend-design`
+       - aiws 规范/质量双审查：`/ws-spec-review` + `/ws-quality-review`
+       - 完成前验证：`/ws-verify-before-complete`
+       - 合并/推送/清理：`/ws-finish`
+       - 需求/验收/合同变更：`/ws-req-review`
 5) 输出 `OpenCode mode:` / `Task intent:` / `Binding:` / `Route:` / `Why:` / `Next:`。
 6) 若 `Route: ws-dev` 且任务属于 simple/local 单点修复：`Next` 可显式建议 `/ws-dev-lite`。
 7) 除非用户只要路由判断，否则给出 route 后继续遵循对应入口的契约。

package/templates/workspace/.opencode/plugins/memory-autoload.js

@@ -0,0 +1,185 @@
+/**
+ * Memory Autoload Plugin
+ *
+ * Injects AIWS memory context at session start so each session
+ * has continuity without needing the nocturne_memory MCP server.
+ *
+ * What it does:
+ *   1. On the first user message of a new session, reads:
+ *      - Active goal(s) from .aiws/goals/*.state.json
+ *      - Recent decisions from .aiws/memory-bank/decision/ (last 3)
+ *      - Project overview from .aiws/memory-bank/project/
+ *   2. Injects a <memory-context> block into the assistant's first response.
+ *   3. Deduplicates per session — injects once only.
+ *
+ * Disable: export MEMORY_AUTOLOAD_DISABLE=1
+ *
+ * @module memory-autoload
+ */
+
+import { readFileSync, existsSync, readdirSync } from "node:fs";
+import { join } from "node:path";
+
+const MEMORY_BANK = ".aiws/memory-bank";
+const GOALS_DIR = ".aiws/goals";
+
+export const MemoryAutoloadPlugin = async ({ project, client, directory }) => {
+  const processed = new Set();
+
+  return {
+    "chat.message": async (input, output) => {
+      const sid = input?.sessionID;
+      if (!sid || processed.has(sid)) return;
+      if (process.env.MEMORY_AUTOLOAD_DISABLE === "1") {
+        processed.add(sid);
+        return;
+      }
+
+      const root = directory || process.cwd();
+      const bankDir = join(root, MEMORY_BANK);
+      if (!existsSync(bankDir)) {
+        processed.add(sid);
+        return;
+      }
+
+      const blocks = [];
+
+      // ── 1. Active/paused goals (ADVISORY ONLY — not FSM authority) ─
+      // TOOLING-003D: authoritative goal-context + next_action come from
+      // session-start → buildSessionContext → getActiveGoal(s).
+      // memory-autoload must NOT become authority over goal state.
+      try {
+        const goalsDir = join(root, GOALS_DIR);
+        if (existsSync(goalsDir)) {
+          const files = readdirSync(goalsDir).filter((f) =>
+            f.endsWith(".state.json"),
+          );
+          const advisory = [];
+          for (const file of files.sort()) {
+            try {
+              const state = JSON.parse(
+                readFileSync(join(goalsDir, file), "utf-8"),
+              );
+              const st = state.status;
+              if (st === "active" || st === "paused") {
+                const phase = state.current_phase ?? "?";
+                const iter = state.iteration ?? "?";
+                advisory.push(
+                  `- [${st}] ${state.goal_id || file} — phase=${phase}, iteration=${iter}`,
+                );
+              }
+            } catch {
+              /* skip malformed state file */
+            }
+          }
+          if (advisory.length) {
+            blocks.push(
+              "[Goals — advisory memory only; use session <goal-context> for next_action]",
+            );
+            blocks.push(...advisory);
+          }
+        }
+      } catch {
+        /* goals dir missing */
+      }
+
+      // ── 2. Recent decisions (last 3, sorted by filename) ──────────
+      try {
+        const decDir = join(bankDir, "decision");
+        if (existsSync(decDir)) {
+          const files = readdirSync(decDir)
+            .filter((f) => f.endsWith(".md") && f !== "handoff-evidence.md")
+            .sort()
+            .reverse()
+            .slice(0, 3);
+          for (const file of files) {
+            try {
+              const content = readFileSync(join(decDir, file), "utf-8");
+              const title =
+                content
+                  .split("\n")
+                  .find((l) => l.startsWith("#"))
+                  ?.replace(/^#+\s*/, "") || file.replace(".md", "");
+              const summary = content
+                .split("\n")
+                .slice(1, 8)
+                .filter((l) => l.trim())
+                .join("\n")
+                .trim();
+              blocks.push(`\n[Decision] ${title}\n${summary}`);
+            } catch {
+              /* skip unreadable file */
+            }
+          }
+        }
+      } catch {
+        /* decision dir missing */
+      }
+
+      // ── 3. Project overview ────────────────────────────────────────
+      try {
+        const projDir = join(bankDir, "project");
+        if (existsSync(projDir)) {
+          const files = readdirSync(projDir).filter((f) => f.endsWith(".md"));
+          for (const file of files.slice(0, 2)) {
+            try {
+              const content = readFileSync(join(projDir, file), "utf-8");
+              const title =
+                content
+                  .split("\n")
+                  .find((l) => l.startsWith("#"))
+                  ?.replace(/^#+\s*/, "") || file.replace(".md", "");
+              const excerpt = content
+                .split("\n")
+                .slice(1, 12)
+                .filter((l) => l.trim())
+                .join("\n")
+                .trim();
+              blocks.push(`\n[Project: ${title}]\n${excerpt}`);
+            } catch {
+              /* skip */
+            }
+          }
+        }
+      } catch {
+        /* project dir missing */
+      }
+
+      // ── 4. If aiws memory boot produces anything, append it ────────
+      // (skipped — avoids shell dependency; use --disclosure boot on
+      //  `aiws memory write` and the injected goal/decision blocks
+      //  above already provide sufficient context)
+
+      if (blocks.length === 0) {
+        processed.add(sid);
+        return;
+      }
+
+      const context = `<memory-context>\n${blocks.join("\n")}\n</memory-context>`;
+
+      const parts = output?.parts || [];
+      const textIdx = parts.findIndex(
+        (p) => p.type === "text" && p.text !== undefined,
+      );
+      if (textIdx !== -1) {
+        parts[textIdx].text = `${context}\n\n${parts[textIdx].text}`;
+      } else {
+        parts.unshift({ type: "text", text: context });
+      }
+
+      try {
+        await client.app.log({
+          body: {
+            service: "memory-autoload",
+            level: "info",
+            message: `Injected ${blocks.length} memory blocks for session ${sid.slice(0, 12)}`,
+          },
+        });
+      } catch {
+        /* logging optional */
+      }
+
+      processed.add(sid);
+    },
+  };
+};

package/templates/workspace/.opencode/skills/codebase-design/SKILL.md

@@ -0,0 +1,114 @@
+---
+name: codebase-design
+description: Shared vocabulary for designing deep modules. Use when the user wants to design or improve a module's interface, find deepening opportunities, decide where a seam goes, make code more testable or AI-navigable, or when another skill needs the deep-module vocabulary.
+---
+
+# Codebase Design
+
+Design **deep modules**: a lot of behaviour behind a small interface, placed at a clean seam, testable through that interface. Use this language and these principles wherever code is being designed or restructured. The aim is leverage for callers, locality for maintainers, and testability for everyone.
+
+## Glossary
+
+Use these terms exactly — don't substitute "component," "service," "API," or "boundary." Consistent language is the whole point.
+
+**Module** — anything with an interface and an implementation. Deliberately scale-agnostic: a function, class, package, or tier-spanning slice. _Avoid_: unit, component, service.
+
+**Interface** — everything a caller must know to use the module correctly: the type signature, but also invariants, ordering constraints, error modes, required configuration, and performance characteristics. _Avoid_: API, signature (too narrow — they refer only to the type-level surface).
+
+**Implementation** — what's inside a module, its body of code. Distinct from **Adapter**: a thing can be a small adapter with a large implementation (a Postgres repo) or a large adapter with a small implementation (an in-memory fake). Reach for "adapter" when the seam is the topic; "implementation" otherwise.
+
+**Depth** — leverage at the interface: the amount of behaviour a caller (or test) can exercise per unit of interface they have to learn. A module is **deep** when a large amount of behaviour sits behind a small interface, **shallow** when the interface is nearly as complex as the implementation.
+
+**Seam** _(Michael Feathers)_ — a place where you can alter behaviour without editing in that place; the *location* at which a module's interface lives. Where to put the seam is its own design decision, distinct from what goes behind it. _Avoid_: boundary (overloaded with DDD's bounded context).
+
+**Adapter** — a concrete thing that satisfies an interface at a seam. Describes *role* (what slot it fills), not substance (what's inside).
+
+**Leverage** — what callers get from depth: more capability per unit of interface they learn. One implementation pays back across N call sites and M tests.
+
+**Locality** — what maintainers get from depth: change, bugs, knowledge, and verification concentrate in one place rather than spreading across callers. Fix once, fixed everywhere.
+
+## Deep vs shallow
+
+**Deep module** = small interface + lots of implementation:
+
+```
+┌─────────────────────┐
+│   Small Interface   │  ← Few methods, simple params
+├─────────────────────┤
+│                     │
+│  Deep Implementation│  ← Complex logic hidden
+│                     │
+└─────────────────────┘
+```
+
+**Shallow module** = large interface + little implementation (avoid):
+
+```
+┌─────────────────────────────────┐
+│       Large Interface           │  ← Many methods, complex params
+├─────────────────────────────────┤
+│  Thin Implementation            │  ← Just passes through
+└─────────────────────────────────┘
+```
+
+When designing an interface, ask:
+
+- Can I reduce the number of methods?
+- Can I simplify the parameters?
+- Can I hide more complexity inside?
+
+## Principles
+
+- **Depth is a property of the interface, not the implementation.** A deep module can be internally composed of small, mockable, swappable parts — they just aren't part of the interface. A module can have **internal seams** (private to its implementation, used by its own tests) as well as the **external seam** at its interface.
+- **The deletion test.** Imagine deleting the module. If complexity vanishes, it was a pass-through. If complexity reappears across N callers, it was earning its keep.
+- **The interface is the test surface.** Callers and tests cross the same seam. If you want to test *past* the interface, the module is probably the wrong shape.
+- **One adapter means a hypothetical seam. Two adapters means a real one.** Don't introduce a seam unless something actually varies across it.
+
+## Designing for testability
+
+Good interfaces make testing natural:
+
+1. **Accept dependencies, don't create them.**
+
+   ```typescript
+   // Testable
+   function processOrder(order, paymentGateway) {}
+
+   // Hard to test
+   function processOrder(order) {
+     const gateway = new StripeGateway();
+   }
+   ```
+
+2. **Return results, don't produce side effects.**
+
+   ```typescript
+   // Testable
+   function calculateDiscount(cart): Discount {}
+
+   // Hard to test
+   function applyDiscount(cart): void {
+     cart.total -= discount;
+   }
+   ```
+
+3. **Small surface area.** Fewer methods = fewer tests needed. Fewer params = simpler test setup.
+
+## Relationships
+
+- A **Module** has exactly one **Interface** (the surface it presents to callers and tests).
+- **Depth** is a property of a **Module**, measured against its **Interface**.
+- A **Seam** is where a **Module**'s **Interface** lives.
+- An **Adapter** sits at a **Seam** and satisfies the **Interface**.
+- **Depth** produces **Leverage** for callers and **Locality** for maintainers.
+
+## Rejected framings
+
+- **Depth as ratio of implementation-lines to interface-lines** (Ousterhout): rewards padding the implementation. We use depth-as-leverage instead.
+- **"Interface" as the TypeScript `interface` keyword or a class's public methods**: too narrow — interface here includes every fact a caller must know.
+- **"Boundary"**: overloaded with DDD's bounded context. Say **seam** or **interface**.
+
+## Going deeper
+
+- **Deepening a cluster given its dependencies** — see [DEEPENING.md](DEEPENING.md): dependency categories, seam discipline, and replace-don't-layer testing.
+- **Exploring alternative interfaces** — see [DESIGN-IT-TWICE.md](DESIGN-IT-TWICE.md): spin up parallel sub-agents to design the interface several radically different ways, then compare on depth, locality, and seam placement.

package/templates/workspace/.opencode/skills/domain-modeling/SKILL.md

@@ -0,0 +1,74 @@
+---
+name: domain-modeling
+description: Build and sharpen a project's domain model. Use when the user wants to pin down domain terminology or a ubiquitous language, record an architectural decision, or when another skill needs to maintain the domain model.
+---
+
+# Domain Modeling
+
+Actively build and sharpen the project's domain model as you design. This is the *active* discipline — challenging terms, inventing edge-case scenarios, and writing the glossary and decisions down the moment they crystallise. (Merely *reading* `CONTEXT.md` for vocabulary is not this skill — that's a one-line habit any skill can do. This skill is for when you're changing the model, not just consuming it.)
+
+## File structure
+
+Most repos have a single context:
+
+```
+/
+├── CONTEXT.md
+├── docs/
+│   └── adr/
+│       ├── 0001-event-sourced-orders.md
+│       └── 0002-postgres-for-write-model.md
+└── src/
+```
+
+If a `CONTEXT-MAP.md` exists at the root, the repo has multiple contexts. The map points to where each one lives:
+
+```
+/
+├── CONTEXT-MAP.md
+├── docs/
+│   └── adr/                          ← system-wide decisions
+├── src/
+│   ├── ordering/
+│   │   ├── CONTEXT.md
+│   │   └── docs/adr/                 ← context-specific decisions
+│   └── billing/
+│       ├── CONTEXT.md
+│       └── docs/adr/
+```
+
+Create files lazily — only when you have something to write. If no `CONTEXT.md` exists, create one when the first term is resolved. If no `docs/adr/` exists, create it when the first ADR is needed.
+
+## During the session
+
+### Challenge against the glossary
+
+When the user uses a term that conflicts with the existing language in `CONTEXT.md`, call it out immediately. "Your glossary defines 'cancellation' as X, but you seem to mean Y — which is it?"
+
+### Sharpen fuzzy language
+
+When the user uses vague or overloaded terms, propose a precise canonical term. "You're saying 'account' — do you mean the Customer or the User? Those are different things."
+
+### Discuss concrete scenarios
+
+When domain relationships are being discussed, stress-test them with specific scenarios. Invent scenarios that probe edge cases and force the user to be precise about the boundaries between concepts.
+
+### Cross-reference with code
+
+When the user states how something works, check whether the code agrees. If you find a contradiction, surface it: "Your code cancels entire Orders, but you just said partial cancellation is possible — which is right?"
+
+### Update CONTEXT.md inline
+
+When a term is resolved, update `CONTEXT.md` right there. Don't batch these up — capture them as they happen. Use the format in [CONTEXT-FORMAT.md](./CONTEXT-FORMAT.md).
+
+`CONTEXT.md` should be totally devoid of implementation details. Do not treat `CONTEXT.md` as a spec, a scratch pad, or a repository for implementation decisions. It is a glossary and nothing else.
+
+### Offer ADRs sparingly
+
+Only offer to create an ADR when all three are true:
+
+1. **Hard to reverse** — the cost of changing your mind later is meaningful
+2. **Surprising without context** — a future reader will wonder "why did they do it this way?"
+3. **The result of a real trade-off** — there were genuine alternatives and you picked one for specific reasons
+
+If any of the three is missing, skip the ADR. Use the format in [ADR-FORMAT.md](./ADR-FORMAT.md).

package/templates/workspace/.opencode/skills/grill-with-docs/SKILL.md

@@ -0,0 +1,7 @@
+---
+name: grill-with-docs
+description: A relentless interview to sharpen a plan or design, which also creates docs (ADR's and glossary) as we go.
+disable-model-invocation: true
+---
+
+Run a `/grilling` session, using the `/domain-modeling` skill.

package/templates/workspace/.opencode/skills/tdd/SKILL.md

@@ -0,0 +1,36 @@
+---
+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.
+
+When exploring the codebase, read `CONTEXT.md` (if it exists) so test names and interface vocabulary match the project's domain language, and respect ADRs in the area you're touching.
+
+## 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/templates/workspace/.opencode/skills/using-aiws/SKILL.md

@@ -68,7 +68,7 @@ description: 使用时机：新会话开始、不确定下一步做什么时。
 
 只问 1-3 个关键问题（意图、Req_ID/Problem_ID、verify、change），然后停止。
 
-### 4. Continuation Routing（新 session 恢复）
+### 4. Continuation Routing / 续跑决策表（新 session 恢复）
 
 change 相位 + goal 叠加；goal 优先于冷启动 plan/dev 跳过：
 
@@ -98,3 +98,4 @@ Root: / Found: / OpenCode mode: / Task intent: / Binding: / Route: / Why: / Next
 - subagent 不可用：单 agent，维护等价工件；不用 L4 程序化 skill invoke（agent 读规则后进入 skill）
 
 > 运行时行为约束：`packages/spec/docs/run-behavior-guidelines.md`
+> Subagent-first 规范：`packages/spec/docs/opencode-subagent-first.md`