@givolt/i3-composer-agent 3.0.0 → 3.2.1

package/docs/developer-onboarding.md

@@ -0,0 +1,143 @@
+# Developer Onboarding
+
+<!-- i3:zh-guide:start -->
+## 中文使用说明
+
+按下文完整工程步骤、检查项与验证条件执行。根据任务选择适用步骤，保留证据、风险和退出条件；正文示例中的英文标签在面向用户输出时译为中文。
+
+默认使用简体中文解释、追问及生成报告；用户明确要求其他语言时可切换。原方法正文、引用、阈值和审批条件完整保留。代码标识、路径、命令、工具参数、JSON 键/枚举与原文引用保持原样。
+<!-- i3:zh-guide:end -->
+
+This guide is for people working **on** the i3-composer-agent repository itself: contributing skills, fixing docs, improving the eval harness. If you want to *use* the skills in your own projects, you're looking for [getting-started.md](getting-started.md) instead.
+
+It's a guided tour, not a rulebook. The rules live in [CONTRIBUTING.md](upstream-repository/CONTRIBUTING.md) (contribution workflow), [skill-anatomy.md](skill-anatomy.md) (skill format), and [evals/README.md](../evals/README.md) (eval framework); this document tells you when to read each one and how the pieces fit.
+
+---
+
+## 1. The mental model
+
+The repo has five composable layers. Understanding what each one is *for* prevents the most common contribution mistakes (putting reference material in a skill, building a persona that routes to other personas, duplicating content across skills).
+
+| Layer | Location | Job | In one word |
+|---|---|---|---|
+| **Skills** | `skills/<name>/SKILL.md` | Step-by-step workflows with verification gates | *How* |
+| **Personas** | `agents/<role>.md` | Roles with a perspective and output format | *Who* |
+| **Commands** | `.claude/commands/`, `.gemini/commands/`, `commands/` | User-facing entry points; the orchestration layer | *When* |
+| **References** | `references/*.md` | Checklists skills pull in on demand | *What to check* |
+| **Evals** | `evals/cases/<name>.json` | Proof that skills trigger and behave correctly | *Does it work* |
+
+Two structural rules worth internalizing early:
+
+- **The user (or a slash command) is the orchestrator.** Personas never invoke other personas; the only endorsed multi-persona pattern is parallel fan-out with a merge step (see [references/orchestration-patterns.md](../references/orchestration-patterns.md)).
+- **Don't duplicate, reference.** Skills link to other skills and to `references/` instead of restating content. The same rule applies to docs, including this one.
+
+One scope caveat that trips people up: `AGENTS.md` and `CLAUDE.md` at the repo root configure agents working on *this repo*. They are not reusable assets and setup guides must never tell users to copy them into their own projects; the reusable assets are the skills.
+
+Note that commands exist in three parallel directories (Claude Code, Gemini CLI, Antigravity). Touch one and CI checks parity across all of them, see §3.
+
+## 2. Local setup
+
+```bash
+npx @givolt/i3-composer-agent --extract --dir ./i3-composer-agent
+cd i3-composer-agent
+```
+
+There's no build step and no `package.json`; validators are plain Node scripts. You need:
+
+- **Node 24** (the version CI pins) for the `scripts/` validators
+- **bash** (+ `jq` recommended) for the hook regression tests
+- **`gh` CLI** for the duplicate-PR check before proposing a skill
+- **Claude Code** only if you want to run Tier 3 behavioral evals locally
+
+To try the pack live against a local checkout:
+
+```bash
+claude --plugin-dir /path/to/i3-composer-agent
+```
+
+## 3. The verification loop
+
+The repo eats its own cooking: verification is non-negotiable for skills, and it's non-negotiable for contributions to the repo too. Everything CI runs without the Claude Code CLI, you can run locally in seconds. This is that set, grouped by what each check covers (the workflow spreads them across several jobs):
+
+```bash
+# Tier 1, structural: frontmatter, naming, required sections, layout and line budget
+node scripts/validate-skills.js
+
+# Links from skills to references/ resolve, including #anchor fragments
+node scripts/validate-reference-links.js
+
+# Every plugin manifest carries the same version
+node scripts/validate-versions.js
+
+# Command parity and description sync across the three command directories
+node scripts/validate-commands.js
+
+# Spec/plan/todo artifact paths agree across every command surface and the docs
+node scripts/validate-artifact-paths.js
+
+# Unit tests for the validators and the eval runner
+# (on PowerShell, list the files instead of using the globs)
+node --test scripts/*-test.js scripts/lib/*-test.js
+
+# Tier 2, trigger & routing: positive prompts rank top-k, negatives don't collide.
+# CI enforces the rank-1 floor, so run it the way CI does.
+node scripts/run-evals.js --min-rank1 95
+
+# Tier 3, behavioral (on demand, spends tokens; --dry-run prints the plan)
+node scripts/run-evals.js --behavioral <skill-name> --dry-run
+
+# Hook regression tests, required if you touch anything under hooks/ or
+# skills/i3-using-agent-skills/SKILL.md (the session-start script embeds that file)
+bash hooks/session-start-test.sh
+bash hooks/sdd-cache-test.sh
+bash hooks/simplify-ignore-test.sh
+```
+
+CI runs this set on Ubuntu, then runs the validators and unit tests again on macOS and Windows, so path handling and line endings get exercised too. Two further jobs need the Claude Code CLI and are not in the block: `claude plugin validate .` checks the marketplace and plugin manifests, and a marketplace install (`claude plugin marketplace add ./`, then `claude plugin install i3-composer-agent@i3-composer-agent --scope user`) proves the plugin installs from a checkout. Run those if you touch `plugin.json`, the `.claude-plugin/` manifests, or anything the install path reads. When the workflow gains a step, this block should gain the same line; if they ever disagree, [the workflow file](upstream-repository/test-plugin-install.yml) is the source of truth.
+
+The three eval tiers are worth understanding even if you never touch the harness, because a red Tier 2 usually means *fix your skill's description*, not the eval: Tier 2 is a lexical approximation of routing (stemmed TF-IDF over descriptions), and its two target failure modes are a description missing the vocabulary users actually say, and an over-broad description that outranks the right skill. The full design, schema, and trust-level rules are in [evals/README.md](../evals/README.md).
+
+Run the relevant subset before every PR. A PR that arrives green through Tier 1 + Tier 2 + command parity is reviewable; one that doesn't will bounce on mechanics before anyone reads the content.
+
+## 4. Contribution paths
+
+### Path 1: Fixing or improving an existing skill (most common, best first PR)
+
+1. Keep changes focused and minimal; preserve the skill's structure and tone.
+2. If you changed the frontmatter `description`, expect Tier 2 effects; run `node scripts/run-evals.js` and check the skill's trigger prompts still rank.
+3. Run Tier 1 to confirm frontmatter is still valid.
+
+### Path 2: Proposing a new skill (higher bar, do the pre-flight)
+
+The catalog already covers most of the lifecycle, so the burden of proof is on the gap. Before writing anything, run the pre-flight checks in [CONTRIBUTING.md](upstream-repository/CONTRIBUTING.md#before-proposing-a-new-skill): search the catalog, check open PRs (`gh pr list --state open`; near-duplicate clusters already exist), confirm the idea fits [skill-anatomy.md](skill-anatomy.md), and justify the gap explicitly in your PR description. If it overlaps an existing skill, a focused edit to that skill beats a new directory.
+
+A new skill ships as a set, not a single file: the `skills/<kebab-case-name>/SKILL.md`, a matching `evals/cases/<name>.json`, and a `scripts/` directory only when it ships runnable helpers (reference material goes in `references/`, never inside the skill). The exact frontmatter rules, the section anatomy, and the eval-case minimums live in [CONTRIBUTING.md](upstream-repository/CONTRIBUTING.md#structure) and [skill-anatomy.md](skill-anatomy.md); take them from there rather than this tour, so the two can't drift.
+
+One point worth internalizing rather than looking up: when writing trigger prompts, paraphrase how users actually talk; copying the description into the prompts games the eval and tells you nothing.
+
+### Path 3: Docs, references, harness
+
+- Docs and skills are **English only**; translations aren't accepted because they drift ([CONTRIBUTING.md](upstream-repository/CONTRIBUTING.md#translations) has the rationale).
+- Changes to `scripts/run-evals.js` or the eval schema should stay compatible with skill-creator's `evals.json` schema (adopted verbatim for the behavioral tier; that compatibility is a feature, not an accident).
+- Anything touching `hooks/` or `skills/i3-using-agent-skills/SKILL.md` (which the session-start script embeds) requires the three hook regression tests (§3). Anything touching `scripts/` requires its unit tests.
+
+## 5. Pre-PR checklist
+
+- [ ] Tier 1 green: `node scripts/validate-skills.js`, plus `node scripts/validate-reference-links.js` if you touched a skill that links to `references/`
+- [ ] Tier 2 green the way CI runs it: `node scripts/run-evals.js --min-rank1 95`
+- [ ] Command parity and artifact paths green if you touched any command directory: `node scripts/validate-commands.js` and `node scripts/validate-artifact-paths.js`
+- [ ] Unit tests green if you touched `scripts/`: `node --test scripts/*-test.js scripts/lib/*-test.js`
+- [ ] Hook tests green if you touched `hooks/` or `i3-using-agent-skills`: `bash hooks/session-start-test.sh`, `bash hooks/sdd-cache-test.sh`, `bash hooks/simplify-ignore-test.sh`
+- [ ] New skill → eval case file present with the minimum trigger/behavioral counts
+- [ ] New skill → gap justified in the PR description; catalog and open PRs checked
+- [ ] No duplicated content; cross-references used instead
+- [ ] Change is small and focused (the repo's own `i3-code-review-and-quality` change-sizing guidance applies to contributions here too)
+
+## 6. Suggested reading order
+
+1. [README.md](../README.md): the catalog and the lifecycle diagram (10 min)
+2. `skills/i3-using-agent-skills/SKILL.md`: how routing works from the agent's side
+3. One well-established skill end to end (e.g. `i3-test-driven-development`): internalize the anatomy by example
+4. [skill-anatomy.md](skill-anatomy.md): the format spec, now with context
+5. [evals/README.md](../evals/README.md): the three tiers and the case format
+6. [CONTRIBUTING.md](upstream-repository/CONTRIBUTING.md) + [AGENTS.md](upstream-repository/AGENTS.md): the rules and the repo-scoped agent config

package/docs/opencode-setup.md

@@ -141,7 +141,7 @@ For every request:
 
 Save this as `AGENTS.md` in your project root. OpenCode will load it automatically.
 
-> **Note:** The root `AGENTS.md` inside the `i3-composer-agent` repository is intended for contributors working on this repository and should not be copied into other projects. See [CONTRIBUTING.md](../CONTRIBUTING.md#repo-scoped-files).
+> **Note:** The root `AGENTS.md` inside the `i3-composer-agent` repository is intended for contributors working on this repository and should not be copied into other projects. See [CONTRIBUTING.md](upstream-repository/CONTRIBUTING.md#repo-scoped-files).
 
 ## How It Works
 

package/docs/other-hosts.md

@@ -2,11 +2,11 @@
 
 这些宿主尚未完成当前版本的真实宿主与模型执行验证。安装文件、宿主发现技能和模型正确执行是三项独立检查；请在测试项目中验证后再用于正式工作。
 
-技能包包含 27 个技能及共享资源。接入时应保留完整的技能、引用与配套工具，不能只复制 `SKILL.md`。
+技能包包含 28 个技能及共享资源。接入时应保留完整的技能、引用与配套工具，不能只复制 `SKILL.md`。
 
 ## 使用本地分发目录
 
-以下命令使用完整分发包解压目录里的 CLI，适用于本地测试和离线接入。`/absolute/path/to/package` 均替换为实际解压目录；已发布版本也可使用 `npx @givolt/i3-composer-agent@3.0.0` 的对应入口。
+以下命令使用完整分发包解压目录里的 CLI，适用于本地测试和离线接入。`/absolute/path/to/package` 均替换为实际解压目录；已发布版本也可使用 `npx @givolt/i3-composer-agent@3.2.1` 的对应入口。
 
 ### fx
 

package/docs/skill-anatomy.md

@@ -0,0 +1,211 @@
+# Skill Anatomy
+
+<!-- i3:zh-guide:start -->
+## 中文使用说明
+
+按下文完整工程步骤、检查项与验证条件执行。根据任务选择适用步骤，保留证据、风险和退出条件；正文示例中的英文标签在面向用户输出时译为中文。
+
+默认使用简体中文解释、追问及生成报告；用户明确要求其他语言时可切换。原方法正文、引用、阈值和审批条件完整保留。代码标识、路径、命令、工具参数、JSON 键/枚举与原文引用保持原样。
+<!-- i3:zh-guide:end -->
+
+This document describes the structure and format of i3-composer-agent skill files. Use this as a guide when contributing new skills or understanding existing ones.
+
+## File Location
+
+Every skill lives in its own directory under `skills/`:
+
+```
+skills/
+  skill-name/
+    SKILL.md           # Required: The skill definition
+    scripts/           # Optional: Runnable helpers used by the skill workflow
+    references/        # Optional: Skill-specific reference documentation
+    supporting-file.md # Optional: Reference material loaded on demand
+```
+
+`SKILL.md` is the only required file. Add `scripts/` or `references/` only when the skill actually needs them, and omit them entirely for simpler skills.
+
+## SKILL.md Format
+
+### Frontmatter (Required)
+
+```yaml
+---
+name: skill-name-with-hyphens
+description: Guides agents through [task/workflow]. Use when [specific trigger conditions].
+---
+```
+
+**Rules:**
+- `name`: Lowercase, hyphen-separated. Must match the directory name.
+- `description`: Start with what the skill does in third person, then include one or more clear "Use when" trigger conditions. Include both *what* and *when*. Maximum 1024 characters.
+- Top-level keys are limited to the [Agent Skills specification](https://agentskills.io) fields: `name`, `description`, `license`, `compatibility`, `metadata`, and `allowed-tools`. Vendor or runtime controls such as `model`, `tools`, `max_turns`, or `context` go under `metadata` or in a per-agent adapter file; see [docs/advanced-per-agent-configuration.md](advanced-per-agent-configuration.md). The validator rejects any other top-level key.
+
+Published names are compatibility identifiers. In particular,
+`i3-browser-testing-with-devtools` is the stable upstream name because other
+skills refer to it directly. A downstream catalog may rename it, but that
+catalog owns the alias or migration mapping; downstream-only aliases are not
+maintained in this repository.
+
+**Why this matters:** Agents discover skills by reading descriptions. The description is injected into the system prompt, so it must tell the agent both what the skill provides and when to activate it. Do not summarize the workflow — if the description contains process steps, the agent may follow the summary instead of reading the full skill.
+
+### Standard Sections (Recommended Pattern)
+
+The frontmatter contract above is required. The section layout below is a recommended pattern, not a rigid template: equivalent headings are acceptable when they serve the same purpose clearly.
+
+```markdown
+# Skill Title
+
+## Overview
+One-two sentences explaining what this skill does and why it matters.
+
+## When to Use
+- Bullet list of triggering conditions (symptoms, task types)
+- When NOT to use (exclusions)
+
+## [Core Process / The Workflow / Steps]
+The main workflow, broken into numbered steps or phases.
+Include code examples where they help.
+Use flowcharts (ASCII) where decision points exist.
+
+## [Specific Techniques / Patterns]
+Detailed guidance for specific scenarios.
+Code examples, templates, configuration.
+
+## Common Rationalizations
+| Rationalization | Reality |
+|---|---|
+| Excuse agents use to skip steps | Why the excuse is wrong |
+
+## Red Flags
+- Behavioral patterns indicating the skill is being violated
+- Things to watch for during review
+
+## Verification
+After completing the skill's process, confirm:
+- [ ] Checklist of exit criteria
+- [ ] Evidence requirements
+```
+
+## Section Purposes
+
+### Overview
+The "elevator pitch" for the skill. Should answer: What does this skill do, and why should an agent follow it?
+
+### When to Use
+Helps agents and humans decide if this skill applies to the current task. Include both positive triggers ("Use when X") and negative exclusions ("NOT for Y").
+
+### Core Process
+The heart of the skill. This is the step-by-step workflow the agent follows. Must be specific and actionable — not vague advice.
+
+**Good:** "Run `npm test` and verify all tests pass"
+**Bad:** "Make sure the tests work"
+
+### Common Rationalizations
+The most distinctive feature of well-crafted skills. These are excuses agents use to skip important steps, paired with rebuttals. They prevent the agent from rationalizing its way out of following the process.
+
+Think of every time an agent has said "I'll add tests later" or "This is simple enough to skip the spec" — those go here with a factual counter-argument.
+
+### Red Flags
+Observable signs that the skill is being violated. Useful during code review and self-monitoring.
+
+### Verification
+The exit criteria. A checklist the agent uses to confirm the skill's process is complete. Every checkbox should be verifiable with evidence (test output, build result, screenshot, etc.).
+
+## Supporting Files
+
+Create supporting files only when:
+- Reference material exceeds 100 lines (keep the main SKILL.md focused)
+- Code tools or scripts are needed
+- Checklists are long enough to justify separate files
+
+Keep patterns and principles inline when under 50 lines.
+
+If a skill does not need runnable helpers, do not create an empty `scripts/` directory just to mirror other skills. Empty directories add noise without changing how the skill works.
+
+## Shared References
+
+Checklists used by more than one skill — testing, security, performance, accessibility, definition-of-done — live in `references/` at the repository root, deliberately *not* inside any skill directory.
+
+This is a pack-level design choice. The Agent Skills spec describes a skill as a self-contained directory, but several skills here point at the same checklists. Colocating those would force one of two options: copy the checklist into every skill that uses it, or pick one skill to "own" it and have the others reach into that directory. Both drift over time. A single repo-root copy stays the source of truth.
+
+The tradeoff is portability: a whole-repo install (such as the Claude Code marketplace plugin) carries `references/` along, but a per-skill install that copies only `skills/<name>/` leaves the repo-root sibling behind, and those links resolve to nothing. That gap is tracked in [upstream agent-skills #361](https://github.com/addyosmani/agent-skills/issues/361).
+
+Current convention: material used by exactly one skill is a supporting file inside that skill's directory; material shared across skills goes in `references/`.
+
+## Context Efficiency
+
+Skills load on demand: only the skill name and description sit in context at startup. The full `SKILL.md` loads only when an agent decides the skill is relevant. To keep that load cheap:
+
+- **Keep `SKILL.md` under 500 lines.** Move detailed reference material into supporting files.
+- **Write specific descriptions.** A precise description helps the agent activate the skill at the right moment and skip it otherwise.
+- **Use progressive disclosure.** Reference supporting files that are read only when the workflow reaches them.
+- **Prefer scripts over inline code.** Executing a script consumes no context; only its output does. Inline code blocks are paid for on every load.
+- **Keep file references one level deep.** Link directly from `SKILL.md` to supporting files rather than chaining through intermediate documents.
+
+## Script Requirements
+
+When a skill ships runnable helpers under `scripts/`, each script follows these conventions:
+
+- Use a `#!/bin/bash` shebang.
+- Use `set -e` for fail-fast behavior.
+- Write status messages to stderr: `echo "Message" >&2`.
+- Write machine-readable output (JSON) to stdout.
+- Include a cleanup trap for temporary files.
+- Reference the script path as `skills/<skill-name>/scripts/<script>.sh` (repo-relative).
+
+## Writing Principles
+
+1. **Process over knowledge.** Skills are workflows, not reference docs. Steps, not facts.
+2. **Specific over general.** "Run `npm test`" beats "verify the tests".
+3. **Evidence over assumption.** Every verification checkbox requires proof.
+4. **Anti-rationalization.** Every skip-worthy step needs a counter-argument in the rationalizations table.
+5. **Progressive disclosure.** Main SKILL.md is the entry point. Supporting files are loaded only when needed.
+6. **Token-conscious.** Every section must justify its inclusion. If removing it wouldn't change agent behavior, remove it.
+7. **Model-neutral.** Write the procedure, not the workaround. See [Write the Procedure, Not the Workaround](#write-the-procedure-not-the-workaround).
+
+## Write the Procedure, Not the Workaround
+
+Skills in this pack run on many agents and model generations. A step that exists because one model gets a specific call wrong is a liability on every other model: it constrains agents that would have solved the task directly, and it spends turns that stronger models need for the actual work. Cross-model transfer measurements ([WikiSkill, arXiv:2608.27454](https://arxiv.org/abs/2608.27454)) show skills authored against one model's execution failures can leave a stronger model performing *worse than with no skill at all*.
+
+**The rule:** if a step cannot be justified without naming a model, a model version, or one agent's private tool name, it belongs in an issue, not in a skill. Describe the capability ("run the focused test command", "write the file"), not the mechanism one runtime happens to expose (`run_command`, `write_to_file`).
+
+Two smells to check for before proposing skill content:
+
+- **Over-specified mechanics.** Prescribing an exact command form or serialization detail where stating the goal alone would do. If the justification is "model X gets this wrong otherwise", it's a workaround, not a procedure.
+- **Fragmented diagnostics.** A multi-step inspection sequence where one step would confirm the same thing. Every extra step spends turns, and turn budget is finite.
+
+This is about skill *content*; the portability of `references/` *paths* is a separate concern (see [Shared References](#shared-references)).
+
+## Naming Conventions
+
+- Skill directories: `lowercase-hyphen-separated`
+- Skill files: `SKILL.md` (always uppercase)
+- Supporting files: `lowercase-hyphen-separated.md`
+- Shared references: stored in the root `references/` directory, not inside skill directories (see [Shared References](#shared-references) for why).
+- Skill-specific references: a single supporting doc can stay as a loose file in the skill directory (the `Supporting files` entry above); when several related docs travel with the skill, the emerging convention for self-contained, distributable skills is to group them in a `references/` directory inside the skill directory, so the skill carries its own supporting docs.
+
+## Cross-Skill References
+
+Reference other skills by name:
+
+```markdown
+Follow the `i3-test-driven-development` skill for writing tests.
+If the build breaks, use the `i3-debugging-and-error-recovery` skill.
+```
+
+Don't duplicate content between skills — reference and link instead.
+
+## Required vs Recommended
+
+Required:
+
+- A `skills/<skill-name>/SKILL.md` file
+- Valid YAML frontmatter with `name` and `description`
+- A description that includes both what the skill does and when to use it
+
+Recommended:
+
+- The standard section flow shown above
+- Equivalent headings such as `How It Works`, `Core Process`, or `Workflow` when they read more naturally for the skill
+- Supporting files only when they keep the main `SKILL.md` focused

package/docs/workbuddy-setup.md

@@ -10,8 +10,8 @@ npx @givolt/i3-composer-agent --agents codebuddy,workbuddy --scope global --yes
 
 向导中 WorkBuddy 位于第 2 项，预选后仍可多选。全局目录：
 
-- `~/.workbuddy/skills/`：27 个 `i3-` 技能，选择说明和默认回复中文。
-- `~/.workbuddy/commands/`：11 个 `/i3-*` 短命令。
+- `~/.workbuddy/skills/`：28 个 `i3-` 技能，选择说明和默认回复中文。
+- `~/.workbuddy/commands/`：12 个 `/i3-*` 短命令。
 - `~/.workbuddy/agents/`：4 个专业角色。
 - `~/.workbuddy/i3-composer-agent/references/`：共享参考。
 - `~/.workbuddy/i3-composer-agent/docs/agents.md`：角色说明。
@@ -27,7 +27,7 @@ WorkBuddy 的目录选择使用自己的配置，不借用 `CODEBUDDY_CONFIG_DIR
 
 运行 `node ~/.workbuddy/i3-composer-agent/scripts/run-evals.js --min-rank1 95`，检查实际安装技能的中英文触发，
 不会调用模型。进入 `~/.workbuddy/i3-composer-agent/` 运行 `npm test` 可检查完整内容、两种语言及全部脚本回归；原 `.js` 入口保留。项目安装将 `~/.workbuddy/` 换成 `.codebuddy/`。五项校验、行为评测用例、样例和
-脚本用法见 [评测说明](../evals/README.md)。原型审计 Hooks 默认注册，其他原版 Hook 文件保留但不新增注册；实际回调和补调仍需本机验收。
+脚本用法见 [评测说明](../evals/README.md)。原型审计 Hooks 已移除；新安装不注册，升级只清理精确归属的旧注册，保留其他设置和历史。
 
 ## 发现和调用
 
@@ -85,22 +85,19 @@ npx @givolt/i3-composer-agent --workbuddy --scope global --yes --force
 
 ## 可选原型工具
 
-原型辅助工具位于本宿主基址的 `tools/i3-prototype/`，支持项目和全局范围；旧项目 `.prototype-tools` 继续读取兼容。推荐使用 `npx @givolt/i3-composer-agent@3.0.0 --workbuddy --scope global --yes --prototype-skills uiux,antdv`；项目安装将 scope 改为 project。可选依赖默认 none，后续也可使用已安装 Skill 的 prototype-dependencies.cjs 单独检测／补装。完整用法见原型 Skill 的 references/optional-skills.md。
+原型辅助工具位于本宿主基址的 `tools/i3-prototype/`，支持项目和全局范围；旧项目 `.prototype-tools` 继续读取兼容。推荐使用 `npx @givolt/i3-composer-agent@3.2.1 --workbuddy --scope global --yes --prototype-skills uiux,antdv`；项目安装将 scope 改为 project。可选依赖默认 none，后续也可使用已安装 Skill 的 prototype-dependencies.cjs 单独检测／补装。完整用法见原型 Skill 的 references/optional-skills.md。
 
 原型共享资料统一在项目 prototypes/：新索引 prototypes/index.json，准备范围 prototypes/.preparation/<id>/scope.json。新原生 scope.moduleIds 自动生成 appliesTo；旧索引、输入和实例保持兼容，安装升级不自动迁移。工具及运行缓存使用所选宿主基址；全局浏览器缓存按业务项目身份隔离。详细规则和只读查询／显式迁移命令见 i3-ui-prototype/references/project-layout.md。
 
 
-## 原型 Hooks 与本地 antDv
+## 原型审计退役与本地 antDv
 
-项目安装注册到 .codebuddy/settings.json，全局注册到 WORKBUDDY_CONFIG_DIR 或 ~/.workbuddy/settings.json。与 CodeBuddy 共用项目目录时，每事件只有一个原型入口；各宿主允许范围、明确禁用和运行状态分别记录。重载 WorkBuddy 后验证，不因文件存在宣称生效。
+WorkBuddy 新安装不注册原型审计 Hook。项目升级清理 `.codebuddy/settings.json` 中本包拥有的旧注册；全局清理 WORKBUDDY_CONFIG_DIR 或 ~/.workbuddy/settings.json 中对应注册。共享项目的旧 Buddy 注册一并退役，其他 Hook、权限、原型和审计历史保留。被手改或未知归属先停止并报告；清理后重载 WorkBuddy。
 
 ```bash
 node ~/.workbuddy/i3-composer-agent/hooks/manage.cjs check --host workbuddy --scope global --project "/业务项目"
-node ~/.workbuddy/i3-composer-agent/hooks/manage.cjs enable --host workbuddy --scope global --project "/业务项目" --groups prototype
 node ~/.workbuddy/i3-composer-agent/hooks/manage.cjs disable --host workbuddy --scope global --project "/业务项目" --groups prototype
 node ~/.workbuddy/skills/i3-ui-prototype/scripts/prototype-dependencies.cjs query --host workbuddy --scope global --project "/业务项目" --kind info --component Table --version 1.5.2
 ```
 
-项目范围将入口改为 .codebuddy 并使用 --scope project。只读 query 解析本宿主 Node／CLI 入口，不要求全局 antdv 命令；它不代替实际 antDv Skill 调用。新实例使用 --host workbuddy --execution-policy buddy-ab-v2，按 Skill 合同先加载前端／适用专业技能，再实施。
-
-当前适配依据官方插件 Hooks 文档及 WorkBuddy 5.8.3 随包 CLI 源代码核对。六组宿主／范围的文件级集成测试使用合成日志，实际宿主执行状态仍 pending-user。手测须看到漏调拒绝、当前主会话真实成功加载和重试成功；持续失败到预算上限后如实报告阻塞，不能用只读文件或自述代替调用证据。
+项目范围将入口改为 .codebuddy 并使用 --scope project。check 只读，enable prototype 已拒绝。query 使用本宿主的本地入口，不代替 antDv Skill 调用。按 Skill 合同先实际加载前端／适用专业技能，再实施；固定业务断言、构建和浏览器证据校验保持。正常流程不要求 Hook 会话绑定，自动调用审计显示未验证。

package/evals/cases/i3-enterprise-sop.json

@@ -3,61 +3,99 @@
   "trigger": {
     "positive": [
       {
-        "prompt": "Explicitly use i3-enterprise-sop to record this explicitly selected PRD path without editing business documents",
-        "top_k": 3
+        "prompt": "Explicitly use i3-enterprise-sop to prepare enterprise BRD, PRD, AD and TestCase documents using its bundled templates",
+        "top_k": 1
       },
       {
-        "prompt": "Use i3-enterprise-sop for this named PBC PRD and AD reference handoff",
-        "top_k": 3
+        "prompt": "Use i3-enterprise-sop spec to build an engineering SPEC from the selected topic and registered BRD PRD AD sources",
+        "top_k": 1
       },
       {
-        "prompt": "Explicitly use i3-enterprise-sop in manual handoff mode without creating JSON",
-        "top_k": 3
+        "prompt": "Use i3-enterprise-sop plan for the approved engineering SPEC while reusing original planning and its human review stop",
+        "top_k": 1
       },
       {
-        "prompt": "Explicitly use i3-enterprise-sop to draft this named PBC AD through native Spec, then stop for review",
-        "top_k": 3
+        "prompt": "Use i3-enterprise-sop for read-only analysis of these document inputs; do not generate or register files",
+        "top_k": 1
       },
       {
-        "prompt": "Explicitly use i3-enterprise-sop plan for this selected topic, reuse native planning and stop for review",
-        "top_k": 3
+        "prompt": "Use i3-enterprise-sop to record an explicitly chosen AD path",
+        "top_k": 1
       }
     ],
     "negative": [
       {
-        "prompt": "Write the standard SPEC.md with objectives, behavior and explicit boundaries",
+        "prompt": "Write a standard SPEC.md with objectives and boundaries",
         "owner": "i3-spec-driven-development"
       },
       {
-        "prompt": "Break the approved spec into ordered implementation tasks",
+        "prompt": "Break an approved specification into ordered implementation tasks",
         "owner": "i3-planning-and-task-breakdown"
+      },
+      {
+        "prompt": "Create a i3-ui-demo using the enterprise admin template and antdv-next",
+        "owner": "i3-ui-demo"
       }
     ]
   },
   "evals": [
     {
       "id": 1,
-      "prompt": "Read brief.md. Explicitly use i3-enterprise-sop for the requested path handoff only.",
-      "files": [
-        "i3-enterprise-sop"
-      ],
-      "expected_output": "A handoff of explicitly selected document paths using schemaVersion, scope and selected only, or a read-only manual summary when requested",
+      "kind": "dialogue",
+      "prompt": "Explicitly use i3-enterprise-sop to prepare a PRD from my external BRD. The supplied BRD does not specify who can approve a request. Explain how you will obtain the bundled PRD template, invoke the original method and handle that critical gap before writing. Do not edit the supplied BRD.",
+      "expected_output": "A bounded T1 preparation and real clarification stop using the current template and original Spec method",
+      "expectations": [
+        "Uses the current project-selected template first, otherwise its own bundled PRD template; does not require user-supplied internal paths",
+        "Explicitly loads original Spec through the supported host mechanism and obtains its complete method body before substantive work; naming a method or reading a summary is insufficient",
+        "Checks the actual BRD and prior real answers before asking; does not invent approver permissions or treat a default recommendation as a human decision",
+        "Preserves supplied business files and waits for a genuine answer to a critical unresolved choice"
+      ]
+    },
+    {
+      "id": 2,
+      "kind": "dialogue",
+      "prompt": "Explicitly use i3-enterprise-sop spec. The selected handoff has readable BRD and PRD paths but no matching AD. Tell me the next step without creating an engineering SPEC.",
+      "expected_output": "T2 identifies the missing matching AD and stops for the user to generate or provide it",
+      "expectations": [
+        "Reads the selected work and topic rather than choosing the largest version in the directory",
+        "Requires readable and consistently paired BRD PRD AD for T2; optional TestCase and prototype do not become universal prerequisites",
+        "Names the missing AD and corresponding T1 ad operation, then stops without an engineering SPEC or plan",
+        "Does not mutate handoff during this T2 check or silently substitute a different topic"
+      ]
+    },
+    {
+      "id": 3,
+      "kind": "dialogue",
+      "prompt": "Explicitly use i3-enterprise-sop plan for this approved engineering SPEC. My existing tasks/todo.md contains unfinished work from another effort. Explain how you will reuse the original planning method without overwriting it or starting Build.",
+      "expected_output": "T3 explicitly uses original planning, protects the unfinished plan and retains its review gate",
+      "expectations": [
+        "Actually invokes the original planning Skill through the host's supported mechanism and obtains its full method rather than imitating a planner",
+        "Reads the selected engineering SPEC and necessary referenced evidence, not every topic in the project",
+        "Keeps original unfinished-plan protection, tasks/plan.md and a single task target; asks before replacing conflicting unfinished work",
+        "Maps requirements and design constraints into tasks and verification, then stops for human review without Build"
+      ]
+    },
+    {
+      "id": 4,
+      "kind": "dialogue",
+      "prompt": "Explicitly use i3-enterprise-sop for a saved document self-check. A tool failed while writing a long section, and no complete file result is yet proven. I have authorized only the target document and its handoff entry, not temporary scripts. Explain recovery and reporting; do not claim the document passed.",
+      "expected_output": "Evidence-based recovery at the actual persisted boundary, no extra self-check script files or false approval",
+      "expectations": [
+        "Inspects actual file state and distinguishes no write, partial write and failed receipt after write; resumes only missing or affected parts",
+        "Uses existing read-only tools or in-memory commands for routine self-checks, without writing temporary scripts or enlarging the authorized scope",
+        "Verifies persisted completeness and segment seams without making a full output reread universally mandatory",
+        "Separates structural checks, content self-check, real tool evidence, registration and human approval; retains original failure and stops when the safe boundary cannot be determined"
+      ]
+    },
+    {
+      "id": 5,
+      "kind": "dialogue",
+      "prompt": "Use i3-enterprise-sop only to analyze a request. I have not authorized drafting, directory creation, installation or handoff registration. Give a read-only explanation of T1, T2 and T3.",
+      "expected_output": "Read-only explanation without state changes or autonomous next-stage execution",
       "expectations": [
-        "Paths resolve against the confirmed project root and actual documents are read",
-        "A newly generated draft is only reported by path; selected changes only for an explicit user choice and business text is unchanged",
-        "Manual handoff does not create a JSON file or project directories",
-        "Original skills, commands, plans and task state are unchanged",
-        "No business approval, next-stage execution or publication is inferred",
-        "Drafting BRD, PRD, AD or TestCase loads original Spec successfully and preserves its save-and-stop gate",
-        "New business documents default to spec/ per capability; existing adopted paths are retained",
-        "Only the selected topic and necessary shared dependencies become original Plan inputs; original Build auto gates are retained",
-        "Short brd, prd, ad, testcase and plan actions ask only missing facts and do not write while awaiting an answer",
-        "Explicit plan successfully loads original planning Skill and preserves original command obligations and outputs, without JSON writes or Build",
-        "Manual and JSON Plan complete the same indexed shared reads and original command before native planning; scripts do not count as model reads; actual relevant dependency/build configuration is read rather than inferred from AD commands",
-        "AD capability/topic identity or direct-upstream path/PRD-version conflicts stop before native planning and any plan/todo or candidate-plan writes; suspected header typos are not self-resolved",
-        "PRD and AD independent version numbers may differ when the AD references the exact selected PRD version; optional TestCase/prototype do not become universal blockers",
-        "SOP preparation uses Read/Glob/Grep for file discovery instead of probing shell permission with ls/find/mkdir",
-        "The native plan retains full actual source paths and document versions for PRD, AD, adopted norms, contracts and engineering adoption; aliases in the plan or paths only in the conversation report are insufficient"
+        "Keeps T1 enterprise documents, T2 engineering SPEC and T3 original planning as distinct user-started stages",
+        "Does not create spec directories, handoff JSON, business drafts, plans or install tools during read-only analysis",
+        "Preserves human-review stops and does not call approval or a successful registration equivalent to permission for the next stage"
       ]
     }
   ]