@givolt/i3-composer-agent 2.3.7 → 3.1.0

package/docs/upstream-repository/CONTRIBUTING.md

@@ -0,0 +1,137 @@
+# Contributing to Agent Skills
+
+Thanks for your interest in contributing! This project is a collection of production-grade engineering skills for AI coding agents.
+
+New here? [docs/developer-onboarding.md](docs/developer-onboarding.md) is a guided tour of how the repo fits together (the five layers, the verification loop, and the contribution paths) and tells you when to read this document, [skill-anatomy.md](docs/skill-anatomy.md), and [evals/README.md](evals/README.md). This file is the authoritative rulebook; the onboarding guide is the map.
+
+## Adding a New Skill
+
+### Before proposing a new skill
+
+This pack already covers most of the development lifecycle, and many proposals overlap with an existing skill or another open PR. Before opening one, do these checks so reviewers aren't triaging duplicates:
+
+1. **Search the catalog.** Browse [the skill list in the README](README.md) and skim `skills/` for an existing skill that covers your idea, whole or in part.
+2. **Check open PRs.** Run `gh pr list --state open` (or browse the PRs tab) and look for proposals on the same topic. Clusters of near-duplicate skills already exist; don't add to them.
+3. **Check rejected proposals.** Search the [skill-change rejection ledger](evals/skill-impact.md) for earlier proposals that overlap with your idea and review their eval evidence before repeating the work.
+4. **Read the anatomy.** Confirm your idea fits the format in [docs/skill-anatomy.md](docs/skill-anatomy.md), an actionable workflow with verification, not vague advice.
+5. **Justify the gap in your PR description.** State explicitly why this isn't covered by an existing skill, open PR, or previously rejected proposal. If it overlaps, propose extending the existing skill instead of adding a new one.
+6. **Strip model-specific workarounds.** If a step can't be justified without naming a model, a model version, or one agent's private tool name, it doesn't belong in a skill — describe the capability instead (see [Write the Procedure, Not the Workaround](docs/skill-anatomy.md#write-the-procedure-not-the-workaround)).
+
+If your idea is a refinement of an existing skill, prefer a focused edit to that skill over a new directory.
+
+### Creating the skill
+
+1. Create a directory under `skills/` with a kebab-case name
+2. Add a `SKILL.md` following the format in [docs/skill-anatomy.md](docs/skill-anatomy.md)
+3. Include YAML frontmatter with `name` and `description` fields, and no vendor or runtime keys at the top level (those go under `metadata` or in a per-agent adapter file; see [docs/advanced-per-agent-configuration.md](docs/advanced-per-agent-configuration.md))
+4. Ensure the `description` starts with what the skill does (third person), then includes one or more `Use when` trigger conditions
+
+### Skill Quality Bar
+
+Skills should be:
+
+- **Specific** — Actionable steps, not vague advice
+- **Verifiable** — Clear exit criteria with evidence requirements
+- **Battle-tested** — Based on real engineering workflows, not theoretical ideals
+- **Minimal** — Only the content needed to guide the agent correctly
+
+### Structure
+
+Every new skill must have:
+
+- `SKILL.md` in the skill directory
+- YAML frontmatter with valid `name` and `description`
+- An eval case file at `evals/cases/<skill-name>.json` — at least 3 positive triggers, 2 negative triggers (with `owner` where possible), and 1 behavioral eval. Execution evals must be backed by real files under `evals/fixtures/`; conversation-shaped skills may use a reviewer-gated `kind: "dialogue"` eval instead (see [evals/README.md](evals/README.md)). CI enforces these requirements.
+
+New skills should generally follow the standard anatomy:
+
+- **Overview** — What this skill does and why it matters
+- **When to Use** — Triggering conditions
+- **Process** — Step-by-step workflow
+- **Common Rationalizations** — Excuses agents use to skip steps, with rebuttals
+- **Red Flags** — Warning signs that the skill is being applied incorrectly
+- **Verification** — How to confirm the skill was applied correctly
+
+The frontmatter fields above are required. The section anatomy is a recommended pattern: equivalent headings such as `How It Works`, `Workflow`, or `Core Process` are fine when they preserve the same intent and keep the skill easy to follow.
+
+### What Not to Do
+
+- Don't duplicate content between skills — reference other skills instead
+- Don't add skills that are vague advice instead of actionable processes
+- Don't create supporting files unless content exceeds 100 lines
+- Don't create an empty `scripts/` directory just to match another skill — add `scripts/` only when the skill includes runnable helpers
+- Don't put reference material inside skill directories — use `references/` instead
+
+## Modifying Existing Skills
+
+Before proposing a change, search the [skill-change rejection ledger](evals/skill-impact.md) for previous attempts affecting the same skill and review their eval evidence.
+
+- Keep changes focused and minimal
+- Preserve the existing structure and tone
+- Test that YAML frontmatter remains valid after edits
+
+If a skill or description change is rejected based on eval results, add one row to the ledger with the date, affected skill, concise attempted change, before-to-after rank-1 score, and rejected PR link and outcome. Land that ledger-only update separately on the default branch; do not leave it only on the rejected proposal branch, where closing or force-pushing the proposal could discard the record.
+
+## Adding a Host Guide
+
+The README install section lists only hosts a maintainer has installed and run the current release on. Every other host gets one line in [docs/other-hosts.md](docs/other-hosts.md): the host name and its install command. No dedicated setup page, vendor links, logos, emoji, or screenshots.
+
+- If you work for the company behind the host, say so in the PR.
+- A host moves into the README once a maintainer has run it and is willing to keep its entry current.
+- Host guides are reviewed in the order they were opened.
+
+## Repo-scoped files
+
+`AGENTS.md` and `CLAUDE.md` at the repo root configure agents working on the [`addyosmani/agent-skills`](https://github.com/addyosmani/agent-skills) repository itself. When writing setup guides or docs, do not instruct users to copy these files into their own projects or into a global agent configuration; the reusable assets are the skills in `skills/`.
+
+## Translations
+
+We don't accept translations of the documentation (README, `docs/`) or of skills and their content. Translated copies drift out of sync as skills and docs evolve, and we have no way to maintain them long-term without leaning on agent translations plus community corrections, which adds maintenance cost for limited value. Keep all skills, docs, and contributions in English.
+
+## Testing Hooks
+
+The session-start script (`hooks/session-start.sh`) injects the `using-agent-skills` meta-skill when wired into a host's `SessionStart` hook. The Claude Code plugin does not register it — Claude Code routes skills natively, and always-on injection would create two routers for the same task (see [docs/getting-started.md](docs/getting-started.md)); the script remains for hosts without native skill routing. A regression test at `hooks/session-start-test.sh` validates the script's JSON payload — both when `jq` is available and when it isn't.
+
+Run it before opening any PR that touches:
+
+- `hooks/session-start.sh`
+- `skills/using-agent-skills/SKILL.md` (the meta-skill content embedded by the hook)
+
+```bash
+bash hooks/session-start-test.sh
+```
+
+Expected output: `session-start JSON payload OK`. The script exits non-zero on any assertion failure.
+
+### Reproducing the no-jq fallback
+
+The hook still emits the same `hookSpecificOutput` envelope when `jq` isn't on `PATH`, with `additionalContext` explaining that `jq` is required. To exercise that branch locally, strip `jq`'s directory from `PATH` for the test invocation:
+
+```bash
+JQ_DIR=$(dirname "$(command -v jq)")
+PATH=$(echo "$PATH" | tr ':' '\n' | grep -v "^${JQ_DIR}$" | tr '\n' ':' | sed 's/:$//') \
+  bash hooks/session-start-test.sh
+```
+
+This works cleanly when `jq` lives in its own directory (e.g. `/opt/homebrew/bin` from Homebrew, `/usr/local/bin` from a manual install). If your `jq` shares a system bin with other tools the test depends on (such as `mktemp` in `/usr/bin`), the simpler approach is to install `jq` via a separate package manager so it has its own bin directory, then re-run.
+
+The hook's `command -v jq` check fails under the stripped `PATH`, the jq-missing fallback runs, and the test asserts the `jq is required` guidance in `additionalContext` instead of the meta-skill body.
+
+## Reporting Issues
+
+Open an issue if you find:
+
+- A skill that gives incorrect or outdated guidance
+- Missing coverage for a common engineering workflow
+- Inconsistencies between skills
+
+If a skill's guidance was wrong, outdated, or did not apply in your project
+(for example, it assumed `npm test` in a Maven or Gradle repo), use the
+[Skill gap](https://github.com/addyosmani/agent-skills/issues/new?template=skill-gap.yml)
+issue form. It asks for the affected skill, the relevant excerpt, your project
+context, and what you did instead — enough for maintainers to triage without a
+freeform write-up.
+
+## License
+
+By contributing, you agree that your contributions will be licensed under the MIT License.

package/docs/upstream-repository/README.md

@@ -0,0 +1,8 @@
+# 上游原版仓库资料
+
+来源：addyosmani/agent-skills，固定提交 aeac41d4d005999432bb7312f7ff06383a91d59d。
+
+本目录保留原版仓库规则、贡献资料和配置的完整原文字节，供阅读和恢复；不会注册为业务项目或宿主的活动规则。
+文件对应关系、原始路径、Git 模式和摘要见 manifest.json。gitignore.txt、gitattributes.txt 使用可随包交付的文件名。
+opencode-skills.link 保存原链接目标 ../skills/，manifest.json 保留其 120000 模式；这是可恢复的链接表示，实际技能发现继续使用所选宿主的登记。
+此处的命令、路径和文档链接保留上游语境，需结合完整上游仓库阅读；不把它们当成本项目的执行指令。

package/docs/upstream-repository/gitattributes.txt

@@ -0,0 +1 @@
+* text=auto eol=lf

package/docs/upstream-repository/gitignore.txt

@@ -0,0 +1,10 @@
+.DS_Store
+node_modules/
+.env
+.env.*
+*.log
+.claude/.simplify-ignore-cache/
+.claude/sdd-cache/
+evals/results/
+evals/plugin/results/
+__pycache__/

package/docs/upstream-repository/manifest.json

@@ -0,0 +1,71 @@
+{
+  "schemaVersion": 1,
+  "upstreamCommit": "aeac41d4d005999432bb7312f7ff06383a91d59d",
+  "files": [
+    {
+      "path": "AGENTS.md",
+      "preservedPath": "docs/upstream-repository/AGENTS.md",
+      "mode": "100644",
+      "blob": "e97670ed868e90b73753fafbe305cdabc7f55ad3",
+      "sha256": "a12bac68c447f8043a75c2259175b36a57a37617a5ab92900ab1e3e9afa381be"
+    },
+    {
+      "path": "CLAUDE.md",
+      "preservedPath": "docs/upstream-repository/CLAUDE.md",
+      "mode": "100644",
+      "blob": "97674d0b173c7c25764e11dc816a298a63119594",
+      "sha256": "f03b7aaf2c08ab93e70a020442634a09f518286ff1beb7b8353dde92533ff9b0"
+    },
+    {
+      "path": "CONTRIBUTING.md",
+      "preservedPath": "docs/upstream-repository/CONTRIBUTING.md",
+      "mode": "100644",
+      "blob": "3c3a015be673a04efd8647c201acfbb2fad7189a",
+      "sha256": "fe5d17011565e9cfeb8a02510c81a243f3e4d829b800e2eab239039fcac214e7"
+    },
+    {
+      "path": ".gitattributes",
+      "preservedPath": "docs/upstream-repository/gitattributes.txt",
+      "mode": "100644",
+      "blob": "6313b56c57848efce05faa7aa7e901ccfc2886ea",
+      "sha256": "d60f352d0db1404c70afb4bb8b2ca3fd1c610572aa40720e8a0b7baa7885418c"
+    },
+    {
+      "path": ".gitignore",
+      "preservedPath": "docs/upstream-repository/gitignore.txt",
+      "mode": "100644",
+      "blob": "167e5ad35e10c75795667a7b71c950eda641cdd8",
+      "sha256": "09bc8ca679551d8d723abeaadf303f3dcdaf93b94d0ad211873942a47c8559a2"
+    },
+    {
+      "path": ".claude/rules/skills-contributing.md",
+      "preservedPath": "docs/upstream-repository/skills-contributing.md",
+      "mode": "100644",
+      "blob": "8553dc3b0d4aba42f014605b488097b6e06e9060",
+      "sha256": "6f8ff659388c3b957322ac46f788ff16d996e5c751f71a6c1e59e4761c437bbd"
+    },
+    {
+      "path": ".github/ISSUE_TEMPLATE/skill-gap.yml",
+      "preservedPath": "docs/upstream-repository/skill-gap.yml",
+      "mode": "100644",
+      "blob": "dac6216a5ace3cd1f34bb2b9a753c6f133592892",
+      "sha256": "f6a7748bfe8a1a43c42c7a5e7317c66689b66afd514ee091eb6f8ce07e46d5a4"
+    },
+    {
+      "path": ".github/workflows/test-plugin-install.yml",
+      "preservedPath": "docs/upstream-repository/test-plugin-install.yml",
+      "mode": "100644",
+      "blob": "b25ba319a8d371c6c1924f8b75173bb319313ab2",
+      "sha256": "fe1437efbdd99bd9ea1fa2bf79aa921f8bdd68a067802e4b41af531a3aa39597"
+    },
+    {
+      "path": ".opencode/skills",
+      "preservedPath": "docs/upstream-repository/opencode-skills.link",
+      "mode": "120000",
+      "blob": "7fc7d9f7be858ee62e454c529b3f8deddd83e1d2",
+      "sha256": "9d36d6a253d6844eb107d26dc0dcd8252808449433b251eceb14cee3517a185a",
+      "target": "../skills/",
+      "representation": "serialized-symlink"
+    }
+  ]
+}

package/docs/upstream-repository/opencode-skills.link

@@ -0,0 +1 @@
+../skills/

package/docs/upstream-repository/skill-gap.yml

@@ -0,0 +1,80 @@
+name: Skill gap
+description: Report when a skill's guidance was wrong, outdated, or did not apply in your project.
+title: "[skill-gap]: "
+labels: ["enhancement"]
+body:
+  - type: markdown
+    attributes:
+      value: |
+        Use this form when a skill gave incorrect, outdated, or ecosystem-mismatched guidance.
+        Keep answers short — enough context for maintainers to triage, not a full write-up.
+
+  - type: dropdown
+    id: skill
+    attributes:
+      label: Affected skill
+      description: Which skill did not work as expected?
+      options:
+        - api-and-interface-design
+        - browser-testing-with-devtools
+        - ci-cd-and-automation
+        - code-review-and-quality
+        - code-simplification
+        - context-engineering
+        - debugging-and-error-recovery
+        - deprecation-and-migration
+        - documentation-and-adrs
+        - doubt-driven-development
+        - frontend-ui-engineering
+        - git-workflow-and-versioning
+        - idea-refine
+        - incremental-implementation
+        - interview-me
+        - observability-and-instrumentation
+        - performance-optimization
+        - planning-and-task-breakdown
+        - security-and-hardening
+        - shipping-and-launch
+        - source-driven-development
+        - spec-driven-development
+        - test-driven-development
+        - using-agent-skills
+        - other / not sure
+    validations:
+      required: true
+
+  - type: textarea
+    id: excerpt
+    attributes:
+      label: Relevant instruction or excerpt
+      description: Paste the line or short passage from SKILL.md (or a linked reference) that misled the agent or did not apply.
+      placeholder: e.g. the verification checklist said to run `npm test`
+    validations:
+      required: true
+
+  - type: textarea
+    id: context
+    attributes:
+      label: Project context
+      description: Language, build tool, test runner, or other conventions that matter here.
+      placeholder: e.g. Java 21, Maven, JUnit 5
+    validations:
+      required: true
+
+  - type: textarea
+    id: what-failed
+    attributes:
+      label: What did not work or did not apply
+      description: What happened when the agent followed the skill? What was wrong or irrelevant?
+      placeholder: e.g. agent insisted on npm scripts in a Maven repo; no package.json exists
+    validations:
+      required: true
+
+  - type: textarea
+    id: workaround
+    attributes:
+      label: What you did instead
+      description: How did you (or the agent) get unblocked? Optional but very helpful.
+      placeholder: e.g. pointed the agent at `./mvnw test` and ignored the npm checklist
+    validations:
+      required: false

package/docs/upstream-repository/skills-contributing.md

@@ -0,0 +1,15 @@
+---
+description: Anti-duplication guardrail for adding or changing skills
+paths:
+  - "skills/**"
+---
+
+# Adding or changing a skill
+
+This repo already covers most of the development lifecycle, so most new-skill ideas overlap an existing skill or an open PR. Before creating a new `skills/<name>/` directory or significantly reworking an existing one:
+
+- Run the pre-flight checks in [CONTRIBUTING.md](../../CONTRIBUTING.md#before-proposing-a-new-skill): search the catalog, check open PRs (`gh pr list --state open`), and justify the gap.
+- Prefer extending an existing skill over adding a near-duplicate. If the idea overlaps an existing skill, edit that skill instead of adding a new directory.
+- Keep the `SKILL.md` within [docs/skill-anatomy.md](../../docs/skill-anatomy.md), and never duplicate content between skills, reference the other skill instead.
+
+CONTRIBUTING.md is the single source of truth for the full workflow; this rule points to it rather than restating its checklist.

package/docs/upstream-repository/test-plugin-install.yml

@@ -0,0 +1,167 @@
+name: Test Plugin Installation
+
+on:
+  push:
+  pull_request:
+  workflow_dispatch:
+
+jobs:
+  validate-skills:
+    name: Validate skill content
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v6
+        with:
+          fetch-depth: 0
+
+      - name: Set up Node.js
+        uses: actions/setup-node@v6
+        with:
+          node-version: '24'
+
+      - name: Validate all skills
+        run: node scripts/validate-skills.js
+
+      - name: Test skill lint rules
+        run: node --test scripts/lib/skill-lint-test.js
+
+      - name: Validate manifest versions
+        run: node scripts/validate-versions.js
+
+      - name: Test manifest version validator
+        run: node --test scripts/validate-versions-test.js
+
+      - name: Test skill eval runner
+        run: node --test scripts/run-evals-test.js
+
+      - name: Run skill evals (trigger + routing)
+        run: node scripts/run-evals.js --min-rank1 95
+
+      - name: Validate references/ links in skills
+        run: node scripts/validate-reference-links.js
+
+      - name: Test reference-link validator
+        run: node --test scripts/validate-reference-links-test.js
+
+      - name: Test floor-guard reference
+        run: node --test scripts/floor-guard-reference-test.js
+
+      - name: Test session-start hook payload
+        run: bash hooks/session-start-test.sh
+
+  validate-commands:
+    name: Validate command parity and description sync
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v6
+
+      - name: Set up Node.js
+        uses: actions/setup-node@v6
+        with:
+          node-version: '24'
+
+      - name: Validate commands across all tool directories
+        run: node scripts/validate-commands.js
+
+      - name: Test command validator
+        run: node --test scripts/validate-commands-test.js
+
+      - name: Validate spec/plan/todo artifact paths
+        run: node scripts/validate-artifact-paths.js
+
+      - name: Test artifact-path validator
+        run: node --test scripts/validate-artifact-paths-test.js
+
+  # Ubuntu coverage stays in the existing jobs above, preserving their check names.
+  validate-platforms:
+    name: Validate tooling (${{ matrix.os }})
+    runs-on: ${{ matrix.os }}
+    strategy:
+      fail-fast: false
+      matrix:
+        os: [macos-latest, windows-latest]
+    steps:
+      - uses: actions/checkout@v6
+        with:
+          fetch-depth: 0
+
+      - name: Set up Node.js
+        uses: actions/setup-node@v6
+        with:
+          node-version: '24'
+
+      - name: Test validators and eval runner
+        run: >-
+          node --test
+          scripts/lib/skill-lint-test.js
+          scripts/validate-versions-test.js
+          scripts/run-evals-test.js
+          scripts/validate-reference-links-test.js
+          scripts/validate-commands-test.js
+          scripts/validate-artifact-paths-test.js
+          scripts/floor-guard-reference-test.js
+
+      - name: Validate all skills
+        run: node scripts/validate-skills.js
+
+      - name: Validate manifest versions
+        run: node scripts/validate-versions.js
+
+      - name: Validate references/ links in skills
+        run: node scripts/validate-reference-links.js
+
+      - name: Validate commands across all tool directories
+        run: node scripts/validate-commands.js
+
+      - name: Validate spec/plan/todo artifact paths
+        run: node scripts/validate-artifact-paths.js
+
+      - name: Run skill evals (trigger + routing)
+        run: node scripts/run-evals.js --min-rank1 95
+
+  test-hooks:
+    name: Hook regression tests
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v6
+
+      - name: Test sdd-cache hooks (stubbed curl, no network)
+        run: bash hooks/sdd-cache-test.sh
+
+      - name: Test simplify-ignore hook
+        run: bash hooks/simplify-ignore-test.sh
+
+  validate:
+    name: Validate plugin structure
+    needs: [validate-skills, validate-commands, validate-platforms]
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v6
+
+      - name: Install Claude Code
+        run: npm install -g @anthropic-ai/claude-code
+
+      - name: Validate marketplace and plugin manifests
+        run: claude plugin validate .
+
+  test-install:
+    name: Test plugin installation
+    runs-on: ubuntu-latest
+    needs: validate
+    steps:
+      - uses: actions/checkout@v6
+
+      - name: Install Claude Code
+        run: npm install -g @anthropic-ai/claude-code
+
+      - name: Configure git to use HTTPS
+        run: git config --global url."https://github.com/".insteadOf "git@github.com:"
+
+      - name: Add marketplace
+        run: claude plugin marketplace add ./
+
+      - name: List marketplaces
+        run: claude plugin marketplace list
+
+      - name: Install plugin
+        run: claude plugin install agent-skills@addy-agent-skills --scope user

package/docs/workbuddy-setup.md

@@ -10,8 +10,8 @@ npx @givolt/i3-composer-agent --agents codebuddy,workbuddy --scope global --yes
 
 向导中 WorkBuddy 位于第 2 项，预选后仍可多选。全局目录：
 
-- `~/.workbuddy/skills/`：26 个 `i3-` 技能，选择说明和默认回复中文。
-- `~/.workbuddy/commands/`：10 个 `/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@2.3.7 --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.1.0 --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

@@ -0,0 +1,64 @@
+{
+  "skill_name": "i3-enterprise-sop",
+  "trigger": {
+    "positive": [
+      {
+        "prompt": "Explicitly use i3-enterprise-sop to record this explicitly selected PRD path without editing business documents",
+        "top_k": 3
+      },
+      {
+        "prompt": "Use i3-enterprise-sop for this named PBC PRD and AD reference handoff",
+        "top_k": 3
+      },
+      {
+        "prompt": "Explicitly use i3-enterprise-sop in manual handoff mode without creating JSON",
+        "top_k": 3
+      },
+      {
+        "prompt": "Explicitly use i3-enterprise-sop to draft this named PBC AD through native Spec, then stop for review",
+        "top_k": 3
+      },
+      {
+        "prompt": "Explicitly use i3-enterprise-sop plan for this selected topic, reuse native planning and stop for review",
+        "top_k": 3
+      }
+    ],
+    "negative": [
+      {
+        "prompt": "Write the standard SPEC.md with objectives, behavior and explicit boundaries",
+        "owner": "i3-spec-driven-development"
+      },
+      {
+        "prompt": "Break the approved spec into ordered implementation tasks",
+        "owner": "i3-planning-and-task-breakdown"
+      }
+    ]
+  },
+  "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",
+      "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"
+      ]
+    }
+  ]
+}