@alanwang-merit/meritdata-platform-skill-package 1.0.9 → 1.0.10

package/skills/generate-developer-testcase/references//345/274/200/345/217/221/350/200/205/346/265/213/350/257/225/347/224/250/344/276/213/346/250/241/346/235/277.md

@@ -0,0 +1,157 @@
+# 开发者测试用例 — [项目名] V1.0
+
+**项目名称**：[项目名称]
+**需求名称**：[需求名称]
+**需求编号**：[REQ-XXXX]
+**测试范围**：[单元测试 / 集成测试 / 端到端测试 / ...]
+**测试目的**：[本次测试的目标]
+
+**测试环境**：
+- 数据库：[MySQL X.X / Oracle X.X / ...]
+- 应用服务器：[Tomcat X.X / ...]
+- 操作系统：[Linux / Windows]
+- JDK版本：[JDK X]
+
+**测试工具**：
+- 单元测试框架：[JUnit 5 / TestNG / pytest / ...]
+- Mock 框架：[Mockito / MockMvc / ...]
+- 覆盖率工具：[JaCoCo / Coverage.py / ...]
+- 其他工具：[Postman / JMeter / ...]
+
+**前提条件**：
+- [ ] 前提条件1
+- [ ] 前提条件2
+- [ ] 前提条件3
+
+**用例适用程序版本/分支**：[v1.0.0 / branch: feature/xxx]
+**编写人**：[XXX]
+**编写日期**：YYYY-MM-DD
+
+---
+
+## 一、测试用例
+
+| 用例编号 | 功能模块名称 | 接口名称 | 测试方法名 | 操作步骤 | 测试内容 | 期望的输出/响应 | 执行人 | 测试结果 | 测试未通过说明 |
+|---------|------------|---------|-----------|----------|----------|----------------|--------|----------|----------------|
+| TC-001 | 用户管理 | /api/v1/user/login | testLoginSuccess | 1. 调用 login 接口 2. 传入正确的用户名和密码 | 验证正常登录场景 | HTTP 200，返回用户信息 + token | XXX | 通过/失败 | XXX |
+| TC-002 | 用户管理 | /api/v1/user/login | testLoginWithWrongPassword | 1. 调用 login 接口 2. 传入正确的用户名和错误的密码 | 验证错误密码场景 | HTTP 200，业务错误码 1001（密码错误） | XXX | 通过/失败 | XXX |
+| TC-003 | 用户管理 | /api/v1/user/login | testLoginWithEmptyUsername | 1. 调用 login 接口 2. 传入空用户名 | 验证参数校验场景 | HTTP 400，参数错误提示 | XXX | 通过/失败 | XXX |
+| TC-004 | 用户管理 | /api/v1/user/{id} | testGetUserById | 1. 调用查询用户接口 2. 传入有效的用户ID | 验证正常查询场景 | HTTP 200，返回用户信息 | XXX | 通过/失败 | XXX |
+| TC-005 | 用户管理 | /api/v1/user/{id} | testGetUserByIdNotFound | 1. 调用查询用户接口 2. 传入不存在的用户ID | 验证不存在场景 | HTTP 200，业务错误码 1004（用户不存在） | XXX | 通过/失败 | XXX |
+| TC-006 | 订单管理 | /api/v1/order/create | testCreateOrderSuccess | 1. 创建订单接口 2. 传入合法订单参数 | 验证正常创建场景 | HTTP 200，返回订单ID | XXX | 通过/失败 | XXX |
+| TC-007 | 订单管理 | /api/v1/order/create | testCreateOrderInsufficientStock | 1. 创建订单接口 2. 传入库存不足的商品 | 验证库存不足场景 | HTTP 200，业务错误码 2003（库存不足） | XXX | 通过/失败 | XXX |
+| ... | ... | ... | ... | ... | ... | ... | ... | ... | ... |
+
+---
+
+## 二、测试结果统计
+
+| 统计项 | 数量 |
+|--------|------|
+| 测试用例总数 | __ |
+| 测试通过用例数 | __ |
+| 测试不通过用例数 | __ |
+| 测试阻塞用例数 | __ |
+| **通过率** | **__%** |
+
+**计算公式**：通过率 = (通过数 / 总数) × 100%
+
+---
+
+## 三、测试未通过用例详情
+
+| 用例编号 | 问题描述 | 失败原因 | 处理状态 | 处理人 | 解决日期 |
+|---------|---------|---------|---------|--------|----------|
+| TC-XXX | xxx | xxx | 待修复/已修复/已跳过 | XXX | YYYY-MM-DD |
+| TC-XXX | xxx | xxx | 待修复/已修复/已跳过 | XXX | YYYY-MM-DD |
+
+---
+
+## 四、覆盖率统计
+
+| 维度 | 覆盖率 | 目标 | 是否达标 |
+|------|--------|------|----------|
+| 行覆盖率 | __% | ≥ 80% | 是/否 |
+| 分支覆盖率 | __% | ≥ 70% | 是/否 |
+| 方法覆盖率 | __% | ≥ 90% | 是/否 |
+| 类覆盖率 | __% | ≥ 90% | 是/否 |
+
+---
+
+## 五、关键回归用例
+
+针对软删除、唯一性约束等关键业务的回归测试：
+
+| 用例编号 | 测试场景 | 业务约束 | 期望结果 |
+|---------|---------|---------|----------|
+| TC-XXX | 编号生成器跳过软删除编号 | 附录 D 业务-1 | 跳过被软删除的编号 |
+| TC-XXX | 唯一性校验拒软删除编号 | 附录 D 业务-1 | 提示编号已存在 |
+| TC-XXX | 软删除历史可查询 | 附录 D 业务-3 | 通过 is_deleted 字段过滤 |
+
+---
+
+## 六、迭代记录
+
+### 6.1 迭代概览
+
+| 轮次 | 日期 | 新增用例 | 修改用例 | 删除用例 | 通过率 | 状态 |
+|------|------|---------|---------|---------|--------|------|
+| V1 | YYYY-MM-DD | __ | __ | __ | __% | 完成/进行中 |
+| V2 | YYYY-MM-DD | __ | __ | __ | __% | 完成/进行中 |
+| V3 | YYYY-MM-DD | __ | __ | __ | __% | 完成/进行中 |
+
+### 6.2 V1 迭代详情
+
+**迭代时间**：YYYY-MM-DD
+**迭代内容**：
+- 新增用例：xxx 条
+- 修改用例：xxx 条
+- 删除用例：xxx 条
+- 主要变更原因：xxx
+
+### 6.3 V2 迭代详情
+
+**迭代时间**：YYYY-MM-DD
+**迭代内容**：
+- 新增用例：xxx 条
+- 修改用例：xxx 条
+- 删除用例：xxx 条
+- 主要变更原因：xxx
+
+### 6.4 关键变更记录
+
+| 日期 | 轮次 | 变更类型 | 变更内容 | 变更原因 |
+|------|------|---------|---------|----------|
+| YYYY-MM-DD | V1 | 新增 | xxx | xxx |
+| YYYY-MM-DD | V2 | 修改 | xxx | xxx |
+
+---
+
+## 七、测试结论
+
+| 项目 | 内容 |
+|------|------|
+| 测试用例总数 | __ |
+| 测试通过率 | __% |
+| 代码覆盖率 | 行 __% / 分支 __% |
+| 阻塞问题数 | __ |
+| 测试结论 | **通过 / 不通过 / 有条件通过** |
+
+**测试结论依据**：
+- 通过条件1
+- 通过条件2
+
+---
+
+## 八、遗留问题与风险
+
+| 序号 | 问题描述 | 影响范围 | 处理方式 | 责任人 |
+|------|---------|---------|---------|--------|
+| 1 | xxx | xxx | 待修复/已忽略/后续版本 | XXX |
+| 2 | xxx | xxx | xxx | XXX |
+
+---
+
+**编写人**：XXX
+**编写日期**：YYYY-MM-DD
+**最后更新**：YYYY-MM-DD

package/skills/git-guardrails-claude-code/SKILL.md

@@ -0,0 +1,95 @@
+---
+name: git-guardrails-claude-code
+description: Set up Claude Code hooks to block dangerous git commands (push, reset --hard, clean, branch -D, etc.) before they execute. Use when user wants to prevent destructive git operations, add git safety hooks, or block git push/reset in Claude Code.
+---
+
+# Setup Git Guardrails
+
+Sets up a PreToolUse hook that intercepts and blocks dangerous git commands before Claude executes them.
+
+## What Gets Blocked
+
+- `git push` (all variants including `--force`)
+- `git reset --hard`
+- `git clean -f` / `git clean -fd`
+- `git branch -D`
+- `git checkout .` / `git restore .`
+
+When blocked, Claude sees a message telling it that it does not have authority to access these commands.
+
+## Steps
+
+### 1. Ask scope
+
+Ask the user: install for **this project only** (`.claude/settings.json`) or **all projects** (`~/.claude/settings.json`)?
+
+### 2. Copy the hook script
+
+The bundled script is at: [scripts/block-dangerous-git.sh](scripts/block-dangerous-git.sh)
+
+Copy it to the target location based on scope:
+
+- **Project**: `.claude/hooks/block-dangerous-git.sh`
+- **Global**: `~/.claude/hooks/block-dangerous-git.sh`
+
+Make it executable with `chmod +x`.
+
+### 3. Add hook to settings
+
+Add to the appropriate settings file:
+
+**Project** (`.claude/settings.json`):
+
+```json
+{
+  "hooks": {
+    "PreToolUse": [
+      {
+        "matcher": "Bash",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "\"$CLAUDE_PROJECT_DIR\"/.claude/hooks/block-dangerous-git.sh"
+          }
+        ]
+      }
+    ]
+  }
+}
+```
+
+**Global** (`~/.claude/settings.json`):
+
+```json
+{
+  "hooks": {
+    "PreToolUse": [
+      {
+        "matcher": "Bash",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "~/.claude/hooks/block-dangerous-git.sh"
+          }
+        ]
+      }
+    ]
+  }
+}
+```
+
+If the settings file already exists, merge the hook into existing `hooks.PreToolUse` array — don't overwrite other settings.
+
+### 4. Ask about customization
+
+Ask if user wants to add or remove any patterns from the blocked list. Edit the copied script accordingly.
+
+### 5. Verify
+
+Run a quick test:
+
+```bash
+echo '{"tool_input":{"command":"git push origin main"}}' | <path-to-script>
+```
+
+Should exit with code 2 and print a BLOCKED message to stderr.

package/skills/git-guardrails-claude-code/agents/openai.yaml

@@ -0,0 +1,3 @@
+interface:
+  display_name: "Git Guardrails for Claude Code"
+  short_description: "Block dangerous git commands"

package/skills/git-guardrails-claude-code/scripts/block-dangerous-git.sh

@@ -0,0 +1,25 @@
+#!/bin/bash
+
+INPUT=$(cat)
+COMMAND=$(echo "$INPUT" | jq -r '.tool_input.command')
+
+DANGEROUS_PATTERNS=(
+  "git push"
+  "git reset --hard"
+  "git clean -fd"
+  "git clean -f"
+  "git branch -D"
+  "git checkout \."
+  "git restore \."
+  "push --force"
+  "reset --hard"
+)
+
+for pattern in "${DANGEROUS_PATTERNS[@]}"; do
+  if echo "$COMMAND" | grep -qE "$pattern"; then
+    echo "BLOCKED: '$COMMAND' matches dangerous pattern '$pattern'. The user has prevented you from doing this." >&2
+    exit 2
+  fi
+done
+
+exit 0

package/skills/grill-me/SKILL.md

@@ -0,0 +1,7 @@
+---
+name: grill-me
+description: A relentless interview to sharpen a plan or design.
+disable-model-invocation: true
+---
+
+Run a `/grilling` session.

package/skills/grill-me/agents/openai.yaml

@@ -0,0 +1,5 @@
+interface:
+  display_name: "Grill Me"
+  short_description: "Sharpen a plan through interview"
+policy:
+  allow_implicit_invocation: false

package/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/skills/grill-with-docs/agents/openai.yaml

@@ -0,0 +1,5 @@
+interface:
+  display_name: "Grill with Docs"
+  short_description: "Grill a design and write its docs"
+policy:
+  allow_implicit_invocation: false

package/skills/grilling/SKILL.md

@@ -0,0 +1,12 @@
+---
+name: grilling
+description: Grill the user relentlessly about a plan, decision, or idea. Use when the user wants to stress-test their thinking, or uses any 'grill' trigger phrases.
+---
+
+Interview me relentlessly about every aspect of this until we reach a shared understanding. Walk down each branch of the decision tree, resolving dependencies between decisions one-by-one. For each question, provide your recommended answer.
+
+Ask the questions one at a time, waiting for feedback on each question before continuing. Asking multiple questions at once is bewildering.
+
+If a *fact* can be found by exploring the environment (filesystem, tools, etc.), look it up rather than asking me. The *decisions*, though, are mine — put each one to me and wait for my answer.
+
+Do not act on it until I confirm we have reached a shared understanding.

package/skills/grilling/agents/openai.yaml

@@ -0,0 +1,3 @@
+interface:
+  display_name: "Grilling"
+  short_description: "Stress-test thinking one question at a time"

package/skills/handoff/SKILL.md

@@ -0,0 +1,16 @@
+---
+name: handoff
+description: Compact the current conversation into a handoff document for another agent to pick up.
+argument-hint: "What will the next session be used for?"
+disable-model-invocation: true
+---
+
+Write a handoff document summarising the current conversation so a fresh agent can continue the work. Save to the temporary directory of the user's OS - not the current workspace.
+
+Include a "suggested skills" section in the document, which suggests skills that the agent should invoke.
+
+Do not duplicate content already captured in other artifacts (specs, plans, ADRs, issues, commits, diffs). Reference them by path or URL instead.
+
+Redact any sensitive information, such as API keys, passwords, or personally identifiable information.
+
+If the user passed arguments, treat them as a description of what the next session will focus on and tailor the doc accordingly.

package/skills/handoff/agents/openai.yaml

@@ -0,0 +1,5 @@
+interface:
+  display_name: "Handoff"
+  short_description: "Compact a conversation into a handoff"
+policy:
+  allow_implicit_invocation: false

package/skills/implement/SKILL.md

@@ -0,0 +1,15 @@
+---
+name: implement
+description: "Implement a piece of work based on a spec or set of tickets."
+disable-model-invocation: true
+---
+
+Implement the work described by the user in the spec or tickets.
+
+Use /tdd where possible, at pre-agreed seams.
+
+Run typechecking regularly, single test files regularly, and the full test suite once at the end.
+
+Once done, use /code-review to review the work.
+
+Commit your work to the current branch.

package/skills/implement/agents/openai.yaml

@@ -0,0 +1,5 @@
+interface:
+  display_name: "Implement"
+  short_description: "Build work from a spec or tickets"
+policy:
+  allow_implicit_invocation: false

package/skills/improve-codebase-architecture/HTML-REPORT.md

@@ -0,0 +1,123 @@
+# HTML Report Format
+
+The architectural review is rendered as a single self-contained HTML file in the OS temp directory. Tailwind and Mermaid both come from CDNs. Mermaid handles graph-shaped diagrams reliably; hand-built divs and inline SVG handle the more editorial visuals (mass diagrams, cross-sections). Mix the two — don't lean on Mermaid for everything, it'll start to look generic.
+
+## Scaffold
+
+```html
+<!doctype html>
+<html lang="en">
+  <head>
+    <meta charset="utf-8" />
+    <title>Architecture review — {{repo name}}</title>
+    <script src="https://cdn.tailwindcss.com"></script>
+    <script type="module">
+      import mermaid from "https://cdn.jsdelivr.net/npm/mermaid@11/dist/mermaid.esm.min.mjs";
+      mermaid.initialize({ startOnLoad: true, theme: "neutral", securityLevel: "loose" });
+    </script>
+    <style>
+      /* small custom layer for things Tailwind doesn't cover cleanly:
+         dashed seam lines, hand-drawn-feeling arrow heads, etc. */
+      .seam { stroke-dasharray: 4 4; }
+      .leak { stroke: #dc2626; }
+      .deep { background: linear-gradient(135deg, #0f172a, #1e293b); }
+    </style>
+  </head>
+  <body class="bg-stone-50 text-slate-900 font-sans">
+    <main class="max-w-5xl mx-auto px-6 py-12 space-y-12">
+      <header>...</header>
+      <section id="candidates" class="space-y-10">...</section>
+      <section id="top-recommendation">...</section>
+    </main>
+  </body>
+</html>
+```
+
+## Header
+
+Repo name, date, and a compact legend: solid box = module, dashed line = seam, red arrow = leakage, thick dark box = deep module. No introduction paragraph — straight into the candidates.
+
+## Candidate card
+
+The diagrams carry the weight. Prose is sparse, plain, and uses the glossary terms (from the `/codebase-design` skill) without ceremony.
+
+Each candidate is one `<article>`:
+
+- **Title** — short, names the deepening (e.g. "Collapse the Order intake pipeline").
+- **Badge row** — recommendation strength (`Strong` = emerald, `Worth exploring` = amber, `Speculative` = slate), plus a tag for the dependency category (`in-process`, `local-substitutable`, `ports & adapters`, `mock`).
+- **Files** — monospaced list, `font-mono text-sm`.
+- **Before / After diagram** — the centrepiece. Two columns, side by side. See patterns below.
+- **Problem** — one sentence. What hurts.
+- **Solution** — one sentence. What changes.
+- **Wins** — bullets, ≤6 words each. e.g. "Tests hit one interface", "Pricing logic stops leaking", "Delete 4 shallow wrappers".
+- **ADR callout** (if applicable) — one line in an amber-tinted box.
+
+No paragraphs of explanation. If the diagram needs a paragraph to be understood, redraw the diagram.
+
+## Diagram patterns
+
+Pick the pattern that fits the candidate. Mix them. Don't make every diagram look the same — variety is part of the point.
+
+### Mermaid graph (the workhorse for dependencies / call flow)
+
+Use a Mermaid `flowchart` or `graph` when the point is "X calls Y calls Z, and look at the mess." Wrap it in a Tailwind-styled card so it doesn't feel parachuted in. Style with classDef to colour leakage edges red and the deep module dark. Sequence diagrams work well for "before: 6 round-trips; after: 1."
+
+```html
+<div class="rounded-lg border border-slate-200 bg-white p-4">
+  <pre class="mermaid">
+    flowchart LR
+      A[OrderHandler] --> B[OrderValidator]
+      B --> C[OrderRepo]
+      C -.leak.-> D[PricingClient]
+      classDef leak stroke:#dc2626,stroke-width:2px;
+      class C,D leak
+  </pre>
+</div>
+```
+
+### Hand-built boxes-and-arrows (when Mermaid's layout fights you)
+
+Modules as `<div>`s with borders and labels. Arrows as inline SVG `<line>` or `<path>` elements positioned absolutely over a relative container. Reach for this when you want the "after" diagram to feel like one thick-bordered deep module with greyed-out internals — Mermaid won't render that with the right weight.
+
+### Cross-section (good for layered shallowness)
+
+Stack horizontal bands (`h-12 border-l-4`) to show layers a call passes through. Before: 6 thin layers each doing nothing. After: 1 thick band labelled with the consolidated responsibility.
+
+### Mass diagram (good for "interface as wide as implementation")
+
+Two rectangles per module — one for interface surface area, one for implementation. Before: interface rectangle is nearly as tall as the implementation rectangle (shallow). After: interface rectangle is short, implementation rectangle is tall (deep).
+
+### Call-graph collapse
+
+Before: a tree of function calls rendered as nested boxes. After: the same tree collapsed into one box, with the now-internal calls shown faded inside it.
+
+## Style guidance
+
+- Lean editorial, not corporate-dashboard. Generous whitespace. Serif optional for headings (`font-serif` works well with stone/slate).
+- Colour sparingly: one accent (emerald or indigo) plus red for leakage and amber for warnings.
+- Keep diagrams ~320px tall so before/after sits comfortably side by side without scrolling.
+- Use `text-xs uppercase tracking-wider` for module labels inside diagrams — they should read as schematic, not as UI.
+- The only scripts are the Tailwind CDN and the Mermaid ESM import. The report is otherwise static — no app code, no interactivity beyond Mermaid's own rendering.
+
+## Top recommendation section
+
+One larger card. Candidate name, one sentence on why, anchor link to its card. That's it.
+
+## Tone
+
+Plain English, concise — but the architectural nouns and verbs come straight from the `/codebase-design` skill. Concision is not an excuse to drift.
+
+**Use exactly:** module, interface, implementation, depth, deep, shallow, seam, adapter, leverage, locality.
+
+**Never substitute:** component, service, unit (for module) · API, signature (for interface) · boundary (for seam) · layer, wrapper (for module, when you mean module).
+
+**Phrasings that fit the style:**
+
+- "Order intake module is shallow — interface nearly matches the implementation."
+- "Pricing leaks across the seam."
+- "Deepen: one interface, one place to test."
+- "Two adapters justify the seam: HTTP in prod, in-memory in tests."
+
+**Wins bullets** name the gain in glossary terms: *"locality: bugs concentrate in one module"*, *"leverage: one interface, N call sites"*, *"interface shrinks; implementation absorbs the wrappers"*. Don't write *"easier to maintain"* or *"cleaner code"* — those terms aren't in the glossary and don't earn their place.
+
+No hedging, no throat-clearing, no "it's worth noting that…". If a sentence could be a bullet, make it a bullet. If a bullet could be cut, cut it. If a term isn't in the `/codebase-design` glossary, reach for one that is before inventing a new one.

package/skills/improve-codebase-architecture/SKILL.md

@@ -0,0 +1,71 @@
+---
+name: improve-codebase-architecture
+description: Scan a codebase for deepening opportunities, present them as a visual HTML report, then grill through whichever one you pick.
+disable-model-invocation: true
+---
+
+# Improve Codebase Architecture
+
+Surface architectural friction and propose **deepening opportunities** — refactors that turn shallow modules into deep ones. The aim is testability and AI-navigability.
+
+This command is _informed_ by the project's domain model and built on a shared design vocabulary:
+
+- Run the `/codebase-design` skill for the architecture vocabulary (**module**, **interface**, **depth**, **seam**, **adapter**, **leverage**, **locality**) and its principles (the deletion test, "the interface is the test surface", "one adapter = hypothetical seam, two = real"). Use these terms exactly in every suggestion — don't drift into "component," "service," "API," or "boundary."
+- The domain language in `CONTEXT.md` gives names to good seams; ADRs in `docs/adr/` record decisions this command should not re-litigate.
+
+## Process
+
+### 1. Explore
+
+**Scope before you scan — YAGNI.** Deepening a module pays off by making future changes to it easier, so put extra weight on the parts of the codebase that have recently changed. Decide *where* to look before you look:
+
+- If the user named a direction — a module, a subsystem, a pain point — take it, and skip the inference below.
+- Otherwise, walk back a good stretch of the commit history (`git log --oneline`) to find the codebase's hot spots — the files and areas that keep coming up — and let those paths pull your attention first. If the changes are scattered with no clear hot spot, widen the net.
+
+Read the project's domain glossary (`CONTEXT.md`) and any ADRs in the area you're touching first.
+
+Then use the Agent tool with `subagent_type=Explore` to walk the codebase. Don't follow rigid heuristics — explore organically and note where you experience friction:
+
+- Where does understanding one concept require bouncing between many small modules?
+- Where are modules **shallow** — interface nearly as complex as the implementation?
+- Where have pure functions been extracted just for testability, but the real bugs hide in how they're called (no **locality**)?
+- Where do tightly-coupled modules leak across their seams?
+- Which parts of the codebase are untested, or hard to test through their current interface?
+
+Apply the **deletion test** to anything you suspect is shallow: would deleting it concentrate complexity, or just move it? A "yes, concentrates" is the signal you want.
+
+### 2. Present candidates as an HTML report
+
+Write a self-contained HTML file to the OS temp directory so nothing lands in the repo. Resolve the temp dir from `$TMPDIR`, falling back to `/tmp` (or `%TEMP%` on Windows), and write to `<tmpdir>/architecture-review-<timestamp>.html` so each run gets a fresh file. Open it for the user — `xdg-open <path>` on Linux, `open <path>` on macOS, `start <path>` on Windows — and tell them the absolute path.
+
+The report uses **Tailwind via CDN** for layout and styling, and **Mermaid via CDN** for diagrams where a graph/flow/sequence reliably communicates the structure. Mix Mermaid with hand-crafted CSS/SVG visuals — use Mermaid when relationships are graph-shaped (call graphs, dependencies, sequences), and hand-built divs/SVG when you want something more editorial (mass diagrams, cross-sections, collapse animations). Each candidate gets a **before/after visualisation**. Be visual.
+
+For each candidate, render a card with:
+
+- **Files** — which files/modules are involved
+- **Problem** — why the current architecture is causing friction
+- **Solution** — plain English description of what would change
+- **Benefits** — explained in terms of locality and leverage, and how tests would improve
+- **Before / After diagram** — side-by-side, custom-drawn, illustrating the shallowness and the deepening
+- **Recommendation strength** — one of `Strong`, `Worth exploring`, `Speculative`, rendered as a badge
+
+End the report with a **Top recommendation** section: which candidate you'd tackle first and why.
+
+**Use CONTEXT.md vocabulary for the domain, and the `/codebase-design` vocabulary for the architecture.** If `CONTEXT.md` defines "Order," talk about "the Order intake module" — not "the FooBarHandler," and not "the Order service."
+
+**ADR conflicts**: if a candidate contradicts an existing ADR, only surface it when the friction is real enough to warrant revisiting the ADR. Mark it clearly in the card (e.g. a warning callout: _"contradicts ADR-0007 — but worth reopening because…"_). Don't list every theoretical refactor an ADR forbids.
+
+See [HTML-REPORT.md](HTML-REPORT.md) for the full HTML scaffold, diagram patterns, and styling guidance.
+
+Do NOT propose interfaces yet. After the file is written, ask the user: "Which of these would you like to explore?"
+
+### 3. Grilling loop
+
+Once the user picks a candidate, run the `/grilling` skill to walk the decision tree with them — constraints, dependencies, the shape of the deepened module, what sits behind the seam, what tests survive.
+
+Side effects happen inline as decisions crystallize — run the `/domain-modeling` skill to keep the domain model current as you go:
+
+- **Naming a deepened module after a concept not in `CONTEXT.md`?** Add the term to `CONTEXT.md`. Create the file lazily if it doesn't exist.
+- **Sharpening a fuzzy term during the conversation?** Update `CONTEXT.md` right there.
+- **User rejects the candidate with a load-bearing reason?** Offer an ADR, framed as: _"Want me to record this as an ADR so future architecture reviews don't re-suggest it?"_ Only offer when the reason would actually be needed by a future explorer to avoid re-suggesting the same thing — skip ephemeral reasons ("not worth it right now") and self-evident ones.
+- **Want to explore alternative interfaces for the deepened module?** Run the `/codebase-design` skill and use its design-it-twice parallel sub-agent pattern.

package/skills/improve-codebase-architecture/agents/openai.yaml

@@ -0,0 +1,5 @@
+interface:
+  display_name: "Improve Codebase Architecture"
+  short_description: "Find and grill architecture improvements"
+policy:
+  allow_implicit_invocation: false