@givolt/i3-composer-agent 2.2.2 → 2.3.0

package/bin/native-migration.cjs

@@ -5,6 +5,12 @@ const path = require('node:path');
 const { fingerprint } = require('./asset-fingerprint.cjs');
 const inventory = require('./legacy-native-files.json').files;
 const name = 'i3-composer-agent';
+const publishedFiles = new Set(inventory);
+
+function ownsAsset(previous, relative) {
+  return previous.assets.some(file => file === relative
+    || (!(previous.layoutVersion >= 2) && publishedFiles.has(relative) && relative.startsWith(file + '/')));
+}
 
 function allowed(relative) {
   return typeof relative === 'string' && !relative.includes('\0') && !relative.includes(':') && !relative.includes('\\')
@@ -41,7 +47,7 @@ function migrationAssets(target, previous, current) {
     const file = fileAt(base, relative);
     if (!file) continue;
     if (fs.statSync(file).isFile()) oldFiles.add(relative);
-    else if (previous.layoutVersion !== 2) {
+    else if (!(previous.layoutVersion >= 2)) {
       // Old manifests registered directories, not their contents. Expand only
       // paths in the published inventory, never the current filesystem tree.
       for (const known of inventory) if (known.startsWith(relative + '/')) oldFiles.add(known);
@@ -51,8 +57,8 @@ function migrationAssets(target, previous, current) {
 
   // Evaluation output is user data, not an installed package asset. Move it
   // transactionally, including plugin and locale-specific result folders.
-  if (previous.assets.some(file => typeof file === 'string' && file.startsWith(`${name}/`))) {
-    const oldEvals = path.join(base, name, 'evals');
+  if (previous.layoutVersion === 2) {
+    const oldEvals = path.join(base, 'evals', name);
     function visit(directory, relative = '') {
       if (!fs.existsSync(directory)) return;
       for (const entry of fs.readdirSync(directory, { withFileTypes: true })) {
@@ -61,7 +67,7 @@ function migrationAssets(target, previous, current) {
         if (entry.isSymbolicLink()) continue;
         if (entry.isDirectory()) visit(source, subpath);
         else if (entry.isFile() && subpath.split('/').includes('results')) {
-          const destinationRelative = `evals/${name}/${subpath}`;
+          const destinationRelative = `${name}/evals/${subpath}`;
           const destination = path.join(base, destinationRelative);
           let reusable = false;
           if (fs.existsSync(destination)) {
@@ -70,11 +76,11 @@ function migrationAssets(target, previous, current) {
           }
           assets.push({ base, source, destination, relative: destinationRelative, kind: 'result', reusable,
             expectedFingerprint: fingerprint(source) });
-          retire(`${name}/evals/${subpath}`);
+          retire(`evals/${name}/${subpath}`);
         }
       }
     }
-    if (fileAt(base, `${name}/evals`)) visit(oldEvals);
+    if (fileAt(base, `evals/${name}`)) visit(oldEvals);
   }
   return assets;
 }
@@ -90,4 +96,4 @@ function pruneRetiredDirectories(assets) {
   }
 }
 
-module.exports = { migrationAssets, pruneRetiredDirectories };
+module.exports = { migrationAssets, pruneRetiredDirectories, ownsAsset };

package/bin/native-runtime.cjs

@@ -1,6 +1,6 @@
 'use strict';
 
-// Installed as scripts/i3-composer-agent/lib/installation.cjs. Resolve from
+// Installed as i3-composer-agent/scripts/lib/installation.js. Resolve from
 // this file, never the caller's working directory or the host's package.json.
 const fs = require('node:fs');
 const path = require('node:path');
@@ -27,7 +27,7 @@ function loadInstallation() {
   let manifest;
   try { manifest = JSON.parse(fs.readFileSync(manifestPath, 'utf8')); }
   catch (error) { throw new Error(`无法读取安装清单 ${manifestPath}：${error.message}`); }
-  if (manifest.name !== 'i3-composer-agent' || manifest.layoutVersion !== 2
+  if (manifest.name !== 'i3-composer-agent' || manifest.layoutVersion !== 3
       || manifest.version !== EXPECTED_VERSION || !Array.isArray(manifest.assets) || !manifest.assets.length) {
     throw new Error(`安装清单的名称、布局或版本不匹配：${manifestPath}`);
   }
@@ -44,14 +44,19 @@ function loadInstallation() {
   }
   for (const relative of assets) resolveOwned(relative);
   const resources = {};
-  for (const category of ['references', 'evals', 'hooks', 'scripts', 'docs']) {
-    const relative = `${category}/i3-composer-agent`;
+  for (const category of ['references', 'evals', 'hooks', 'scripts', 'docs', 'adapters']) {
+    const relative = 'i3-composer-agent/' + category;
     if (manifest.resources?.[category] !== relative || ![...assets].some(file => file.startsWith(relative + '/'))) {
       throw new Error(`安装清单缺少资源：${category}`);
     }
     resources[category] = path.join(root, relative);
   }
-  return { root, manifest, catalog: manifest.catalog, resources, skillsDirectory: path.join(root, 'skills') };
+  const toolkitRoot = path.join(root, 'i3-composer-agent');
+  const pkg = JSON.parse(fs.readFileSync(path.join(toolkitRoot, 'package.json'), 'utf8'));
+  if (pkg.name !== '@givolt/i3-composer-agent' || pkg.type !== 'commonjs' || pkg.version !== EXPECTED_VERSION) {
+    throw new Error('配套 package.json 的名称、模块格式或版本与安装不一致');
+  }
+  return { root, toolkitRoot, manifest, catalog: manifest.catalog, resources, skillsDirectory: path.join(root, 'skills') };
 }
 
 module.exports = { loadInstallation };

package/commands/i3-prototype.toml

@@ -0,0 +1,23 @@
+description = "选择模板并生成、评审和迭代交互原型，维护已确认的 UI 基线。"
+# i3-description-source: "description = \"Create, review and iterate interactive UI prototypes with template selection and approved baselines\""
+
+prompt = """
+<!-- i3:zh-CN:start -->
+## 中文交互与输出
+
+默认使用简体中文回复，包括追问、选项说明、阶段进度、分析、规格、计划、验收、代码审查与发布报告。只有用户明确要求其他语言时才切换；输入中出现英文术语、代码或引用不构成切换语言的要求。
+下文的工程步骤、审批要求、退出条件和工具约束完整有效。英文示例中的人类可读标题、说明和占位内容在实际输出时应译为中文；保留原有信息与验证标准，不删减方法。
+Skill/Command/Agent 标识、文件路径、命令参数、代码/API 名称、工具调用参数、JSON 键/类型/枚举、机器状态、测试期望字面量及引用原文保持原样。生成文档正文用中文，SPEC.md、tasks/plan.md、tasks/todo.md、CONSTRAINTS.md 等约定路径不改名。
+严重程度按原规则判断，面向用户可写“严重（Critical）”“必须修复（Required）”“小问题（Nit）”“可选（Optional）”“建议考虑（Consider）”“仅供参考（FYI）”；High/Medium/Low、APPROVE/REQUEST CHANGES 和 GO/NO-GO 保留其原始语义与机器值。不得因翻译降低门槛，角色不能互相委派。
+
+适用说明：选择模板并生成、评审和迭代交互原型，维护已确认的 UI 基线。
+<!-- i3:zh-CN:end -->
+
+Invoke the i3-ui-prototype skill.
+
+$ARGUMENTS
+
+With no arguments, use create. Supported operations: create, revise, inspect, confirm-baseline.
+Default to professional enhancement mode. Detect UI/UX Pro Max in the current host; if unavailable, offer installation or explicit template mode. Never silently downgrade.
+Use the skill workflow for template selection, business mapping, professional advice, real browser verification and version-specific human confirmation. Preserve approved snapshots during iteration.
+"""

package/commands/i3-review.toml

@@ -23,6 +23,6 @@ Review the current changes (staged or recent commits) across all five axes:
 4. **Security** — Input validated? Secrets safe? Auth checked? (Use i3-security-and-hardening skill)
 5. **Performance** — No N+1 queries? No unbounded ops? (Use i3-performance-optimization skill)
 
-Categorize findings as Critical, Important, or Suggestion.
+Categorize findings as Critical, Required, Optional, or Nit.
 Output a structured review with specific file:line references and fix recommendations.
 """

package/commands/i3-ship.toml

@@ -40,7 +40,7 @@ Constraints (from CLI's subagent model):
 
 Once all three reports are back, the main agent (not a sub-persona) synthesizes them:
 
-1. **Code Quality** — Aggregate Critical/Important findings from `code-reviewer` and any failing tests, lint, or build output. Resolve duplicates between reviewers.
+1. **Code Quality** — Aggregate Critical/Required findings from `code-reviewer` and any failing tests, lint, or build output. Resolve duplicates between reviewers.
 2. **Security** — Promote any Critical/High `security-auditor` findings to launch blockers. Cross-reference with `code-reviewer`'s security axis.
 3. **Performance** — Pull from `code-reviewer`'s performance axis; cross-check Core Web Vitals if applicable.
 4. **Accessibility** — Verify keyboard nav, screen reader support, contrast (not covered by the three personas — handle directly here, or invoke the accessibility checklist).

package/docs/advanced-per-agent-configuration.md

@@ -0,0 +1,78 @@
+# Advanced per-agent configuration
+
+<!-- i3:zh-guide:start -->
+## 中文使用说明
+
+按下文完整工程步骤、检查项与验证条件执行。根据任务选择适用步骤，保留证据、风险和退出条件；正文示例中的英文标签在面向用户输出时译为中文。
+
+默认使用简体中文解释、追问及生成报告；用户明确要求其他语言时可切换。原方法正文、引用、阈值和审批条件完整保留。代码标识、路径、命令、工具参数、JSON 键/枚举与原文引用保持原样。
+<!-- i3:zh-guide:end -->
+
+Skills in this repository are intentionally portable. Every `SKILL.md` keeps its frontmatter limited to the fields the [Agent Skills specification](https://agentskills.io) defines, so the same file works across Claude Code, Cursor, Gemini CLI, Antigravity, and any other spec-conformant client.
+
+Several agents also support extra runtime controls: model routing, tool restrictions, turn limits, execution isolation. These controls are valuable, but they are vendor-specific and do not belong in the shared, portable frontmatter. This document explains which controls each agent supports, where they belong, and how to apply them as an opt-in without breaking portability.
+
+This is the canonical reference for per-agent configuration, and it supersedes the earlier approach of adding vendor fields to top-level `SKILL.md` frontmatter. Fields such as `kind`, `model`, `temperature`, `max_turns`, `tools`, and `context` must not appear at the top level of a skill. They belong under `metadata` or in a separate per-agent adapter file, as described below.
+
+## Principles
+
+1. **Keep `SKILL.md` portable.** The Agent Skills specification reserves top-level frontmatter for `name`, `description`, `license`, `compatibility`, `metadata`, and the experimental `allowed-tools`. Vendor or client-specific properties belong under `metadata`, not at the top level.
+2. **Unknown top-level fields are not guaranteed to be ignored.** Many parsers only read `name` and `description` and silently drop the rest, but a strict spec-conformant validator or client may flag or reject unrecognized top-level keys. Putting vendor fields under `metadata` keeps the file conformant everywhere.
+3. **Opt-in, not global.** Runtime controls should be something a user adds for their own agent and workflow, not a default baked into every skill in the repository.
+4. **Prefer generation over hand-editing.** Where a configuration is repetitive and mechanical, generate it from a single source of truth instead of maintaining copies by hand. See [Automating with scripts](#automating-with-scripts).
+
+## Where vendor fields belong
+
+| Field type | Example | Correct home |
+|---|---|---|
+| Spec fields | `name`, `description`, `license`, `compatibility` | Top-level frontmatter in `SKILL.md` |
+| Vendor metadata | model hints, routing tags | Under the `metadata` key in `SKILL.md` |
+| Runtime orchestration | subagent definitions, turn limits, tool allowlists | A separate per-agent adapter file (see each agent below) |
+
+## Claude Code
+
+Claude Code reads `name` and `description` for discovery. Custom commands and skills share the same frontmatter, so the `context` and `allowed-tools` fields below work in both `.claude/commands/*.md` and `.claude/skills/*/SKILL.md`.
+
+- **`context: fork`** runs a command or skill in an isolated subagent context instead of the active conversation. This gives context isolation, repeatable execution from a clean state, execution tokens spent in the fork rather than the main session, and a cleaner handoff where only the result surfaces back. An optional **`agent`** field selects which subagent type runs the fork (for example `agent: Plan`); it defaults to `general-purpose`.
+- **`allowed-tools`** pre-approves tools; it does not restrict them. Listed tools run without a permission prompt for the turn that invokes the command or skill, and the grant clears on your next message. Nothing is removed from the tool pool.
+- **`disallowed-tools`** is the field that actually restricts: it removes the listed tools from the available pool while the skill is active, which is what least-privilege needs for passive stages such as review or audit. The restriction also clears on your next message. Note it is a Claude Code field and not one of the specification's six, so it belongs in a local copy or an adapter file; in a published `SKILL.md` it fails packaging with an unexpected-key error.
+
+These are Claude Code conventions. Keep the shared, published `SKILL.md` limited to spec fields; apply these runtime controls in your own local command or skill copies instead.
+
+## Gemini CLI and Antigravity
+
+Gemini CLI and Antigravity discover skills the same way: they match `name` and `description`, then load the full skill on demand. Runtime orchestration lives in a separate resource, not in the skill frontmatter.
+
+- **Subagent definitions** live in `.gemini/agents/*.md`, which are distinct from skills. Their schema is `kind` (`local` or `remote`), `model`, `temperature`, `max_turns`, and `tools`. Note that this is a subagent schema, not a skill schema: the two should not be merged into one `SKILL.md`.
+- **Model routing** can send lighter tasks (formatting, documentation, git operations) to a faster model and reserve a stronger model for cognitively demanding work (debugging, security auditing, interface design).
+- **Tool restrictions** enforce least-privilege per subagent, which also trims unused tool schemas from the prompt.
+- **Turn limits** (`max_turns`) cap execution to avoid runaway correction loops.
+
+### Model guidance
+
+Google recommends omitting `temperature` for Gemini 3.x models and using `thinking_level` instead. Do not hardcode `temperature` on skills or subagents routed to 3.x models; prefer `thinking_level` and revisit this guidance as the models evolve.
+
+```yaml
+# .gemini/agents/security-auditor.md
+---
+kind: local
+model: gemini-3-pro
+thinking_level: high   # not: temperature: 0.1
+tools: [read_file, grep]
+max_turns: 10
+---
+```
+
+## Automating with scripts
+
+Maintaining per-agent metadata by hand across every skill is repetitive, drifts out of sync, and is easy to get wrong. A better approach is to keep a single source of truth and generate the agent-specific output:
+
+- A generator reads a per-skill configuration map (which model, tool allowlist, turn limit, and isolation each skill should use for a given agent).
+- For metadata-style fields, it injects them under the `metadata` key of each `SKILL.md`, keeping the file spec-conformant.
+- For orchestration-style fields, it emits the separate adapter files an agent expects, for example `.gemini/agents/*.md` subagent definitions, leaving `SKILL.md` untouched.
+
+Generation also lets the tooling validate **semantics, not just shape**: confirm that a model name is a known model, that a tool name is a real tool, that `max_turns` is a positive integer, and that `temperature` (where still applicable) is a valid number in range. Shape-only checks let invalid values such as `parseInt("1.5")` or `parseFloat("0.2oops")` slip through.
+
+## Status
+
+It is the single reference for per-agent configuration: it keeps the shared skills portable while documenting the advanced controls each agent offers as an opt-in. The script-based automation described above is a proposal pending agreement before any implementation.

package/docs/agents.md

@@ -42,10 +42,10 @@ Pick this when you want one perspective on the current change and the user is in
 ### Slash command (single persona behind it)
 Pick this when there's a repeatable workflow you'd otherwise re-explain every time.
 
-- `/i3-review` → wraps `code-reviewer` with the project's review skill
-- `/i3-test` → wraps `test-engineer` with TDD skill
 - `/i3-webperf` → wraps `web-performance-auditor` for performance-focused audits on web apps
 
+`/i3-review` and `/i3-test` are not persona wrappers. They run the `i3-code-review-and-quality` and `i3-test-driven-development` skills in the main session, where the conversation's context is. To get `code-reviewer` or `test-engineer` in a fresh context, invoke the persona directly or run `/i3-ship`.
+
 ### Slash command (orchestrator — fan-out)
 Pick this only when **independent** investigations can run in parallel and produce reports that a single agent then merges.
 

package/docs/codebuddy-setup.md

@@ -9,9 +9,9 @@ npx @givolt/i3-composer-agent --codebuddy
 ```
 
 向导预选 CodeBuddy，可增加其他工具，再选择项目或全局范围。
-项目安装提供 `.codebuddy/skills/`（25 个技能）、`references/`、
-`commands/`（9 个命令）和 `agents/`（4 个角色）。
-同级 `evals/`、`hooks/`、`scripts/`、`docs/`、`references/` 各自通过 `i3-composer-agent/` 分组资料，
+项目安装提供 `.codebuddy/skills/`（26 个技能）、`references/`、
+`commands/`（10 个命令）和 `agents/`（4 个角色）。
+同级 `i3-composer-agent/` 是配套工具根，集中提供 `package.json`、`evals/`、`hooks/`、`scripts/`、`docs/`、`references/` 和校验输入 `adapters/`，
 只有一份实际技能、命令和角色，评测与宿主共用。
 全局使用 `~/.codebuddy/` 的相同结构。默认中文说明和回复；技能/命令标识不改名。
 安装成功清理旧内容，失败恢复；设置与自定义命令保留。
@@ -41,8 +41,8 @@ CodeBuddy 与 WorkBuddy 项目共用 `.codebuddy/`；同版本追加客户端会
 
 ## 配套检查
 
-在业务项目运行 `node .codebuddy/scripts/i3-composer-agent/run-evals.cjs --min-rank1 95`，
-可检查中英文触发，不调用模型；全局安装使用脚本的全局绝对路径。五项校验、行为评测和样例用法见
+在业务项目运行 `node .codebuddy/i3-composer-agent/scripts/run-evals.js --min-rank1 95`，
+可检查中英文触发，不调用模型；进入 `.codebuddy/i3-composer-agent/` 可运行 `npm test` 和 `node scripts/run-evals.js --locale zh-CN --min-rank1 95`。全局安装使用脚本的全局绝对路径。五项校验、行为评测和样例用法见
 [评测说明](../evals/README.md)。Hook 文件已安装，需要按宿主协议单独启用。
 
 ## 通过 CodeBuddy Code 插件管理器安装

package/docs/codex-setup.md

@@ -6,11 +6,11 @@
 npx @givolt/i3-composer-agent --codex
 ```
 
-项目范围写入 `.agents/skills/`，全局写入 `~/.agents/skills/`，并安装同级 `references/i3-composer-agent/`。
-提供全部 25 个 `i3-` 技能，中文选择说明与默认中文回复在每个入口独立生效。
+项目范围写入 `.agents/skills/`，全局写入 `~/.agents/skills/`，并安装同级 `i3-composer-agent/references/`。
+提供全部 26 个 `i3-` 技能，中文选择说明与默认中文回复在每个入口独立生效。
 同级 `evals/`、`hooks/`、`scripts/`、`docs/` 各自以 `i3-composer-agent/` 分组资料。
 命令与角色文件也会提供，供按需阅读，其自动发现由宿主决定。
-从项目目录执行 `node .agents/scripts/i3-composer-agent/run-evals.cjs --min-rank1 95`
+从项目目录执行 `node .agents/i3-composer-agent/scripts/run-evals.js --min-rank1 95`
 检查实际安装技能的中英文触发，不调用模型；五项结构校验详见
 [评测说明](../evals/README.md)。原生调用使用技能 ID，Hook 文件需按宿主能力单独启用。
 

package/docs/copilot-setup.md

@@ -12,6 +12,8 @@ This guide covers Copilot in VS Code. For the standalone `copilot` command-line
 
 **What an install actually gives you:** the skills. Each installed skill becomes a slash command named after its frontmatter `name` — `/i3-spec-driven-development`, `/i3-test-driven-development`, and so on. `npx skills add /path/to/i3-composer-agent` and the manual copy below both install skills only. Neither of those two routes copies this repo's short lifecycle wrappers (`/i3-spec`, `/i3-plan`, `/i3-build`, `/i3-test`, `/i3-review`, `/i3-ship`) — those are Claude Code commands living in `.claude/commands/`. Use the full skill names, or add your own aliases — see [Lifecycle workflows](#lifecycle-workflows).
 
+> **`/i3-spec`, `/i3-plan`, `/i3-build`, `/i3-test`, `/i3-review`, `/i3-code-simplify`, `/i3-webperf` and `/i3-ship` never appear in Copilot.** They are Claude Code commands, and Copilot does not read `.claude/commands/`. Not seeing them after an install is expected, not a missing step. Invoke the skill by its own name instead — `/i3-spec-driven-development` for `/i3-spec`, `/i3-planning-and-task-breakdown` for `/i3-plan`, and so on; the full mapping is in [Lifecycle Workflows](#lifecycle-workflows). On VS Code you can add [short aliases](#optional-short-spec-style-aliases) yourself if you want the short forms.
+
 ## Setup
 
 ### Copilot Instructions
@@ -153,6 +155,8 @@ Write the body yourself, or take it from this table, rather than copying `.claud
 
 ### If the skill slash commands don't appear
 
+First rule out the expected case: if the only commands you miss are the short lifecycle wrappers (`/i3-spec`, `/i3-plan`, `/i3-build`, `/i3-test`, `/i3-review`, `/i3-ship`), nothing is wrong — those are Claude Code commands and never surface in Copilot (see the note at the top). The steps below are for when the skills' own names, such as `/i3-spec-driven-development`, are missing too.
+
 Work through these in order — `/i3-spec-driven-development` missing and `/i3-spec` missing have different causes:
 
 1. **Check where the skills landed.** Each one needs its own directory containing a `SKILL.md`. The project-level paths this guide uses are `.github/skills/`, `.claude/skills/` and `.agents/skills/` — but an installer run with a global/user flag writes outside the workspace instead (`~/.agents/skills/` and equivalents), so a skill that isn't in any of the three may simply be installed personally. Confirm the actual path against the [VS Code agent skills docs](https://code.visualstudio.com/docs/agent-customization/agent-skills), then re-install into the project if you wanted it project-scoped.

package/docs/cursor-setup.md

@@ -10,6 +10,8 @@
 
 How to wire [i3-composer-agent](../README.md) into **Cursor** using current, supported project context — not legacy monolith files or Kaizen-specific layouts.
 
+Every `.cursor/` path in this guide lives in **your** project (or under `~/.cursor/` for user scope). This repository does not ship a `.cursor/` directory: you create it and sync the skills into it, which is what [step 1](#1-install-skills-into-cursorskills) does.
+
 ---
 
 ## What Cursor supports today
@@ -213,6 +215,7 @@ Files under `i3-composer-agent/agents/` (e.g. code reviewer persona) are **not**
 | Stale workflow | Re-`rsync` from `i3-composer-agent/skills/` |
 | Duplicate instructions | Remove skill content from rules; keep one source |
 | Wrong skill picked | Narrow `description` in custom skills; nudge in chat |
+| "An unexpected error occurred on our servers" right after attaching a skill with `/`, and every later message in that chat fails too | Known Cursor-side issue, tracked in [upstream agent-skills #494](https://github.com/addyosmani/agent-skills/issues/494): Cursor pulls the attached `SKILL.md` into the request and the failure happens on its side, not in the skill. Start a new chat and reference the skill by name in plain text ("Use the i3-test-driven-development skill to …") instead of attaching it. |
 
 ---
 

package/docs/other-hosts.md

@@ -1,15 +1,50 @@
-# Other hosts
+# 其他宿主
 
-<!-- i3:zh-guide:start -->
-## 中文使用说明
+这些宿主尚未完成当前版本的真实宿主与模型执行验证。安装文件、宿主发现技能和模型正确执行是三项独立检查；请在测试项目中验证后再用于正式工作。
 
-按下文完整工程步骤、检查项与验证条件执行。根据任务选择适用步骤，保留证据、风险和退出条件；正文示例中的英文标签在面向用户输出时译为中文。
+技能包包含 26 个技能及共享资源。接入时应保留完整的技能、引用与配套工具，不能只复制 `SKILL.md`。
 
-默认使用简体中文解释、追问及生成报告；用户明确要求其他语言时可切换。原方法正文、引用、阈值和审批条件完整保留。代码标识、路径、命令、工具参数、JSON 键/枚举与原文引用保持原样。
-<!-- i3:zh-guide:end -->
+## 使用本地分发目录
 
-These hosts install the pack but are not in the README's install section, because no maintainer has run the current release on them. Each entry is one line: the host and its install command. To add one, see [Adding a Host Guide](../CONTRIBUTING.md#adding-a-host-guide).
+以下命令使用完整分发包解压目录里的 CLI，适用于本地测试和离线接入。`/absolute/path/to/package` 均替换为实际解压目录；已发布版本也可使用 `npx @givolt/i3-composer-agent@2.3.0` 的对应入口。
 
-Skills are plain `SKILL.md` folders, so any agent that reads the i3 Composer Agent layout can load them. See [getting-started.md](getting-started.md).
+### fx
 
-- **Oh My Pi**: `omp plugin marketplace add /path/to/i3-composer-agent`, then `omp plugin install i3-composer-agent@i3-composer-agent`
+在业务项目目录执行：
+
+```bash
+node /absolute/path/to/package/bin/i3-composer-agent.cjs --agents fx --scope project --yes
+```
+
+原生目标使用 `.fx/skills/`；全局安装可将 `--scope project` 改成 `--scope global`。上游记录要求 fx 0.0.5 或更新版本；当前版本的宿主发现与调用仍需人工验证。
+
+### Pi
+
+在业务项目目录执行：
+
+```bash
+node /absolute/path/to/package/bin/i3-composer-agent.cjs --agents pi --scope project --yes
+```
+
+原生目标使用 `.agents/skills/`；全局安装可将 `--scope project` 改成 `--scope global`。当前版本的宿主发现与调用仍需人工验证。
+
+### Dojo Workspace
+
+上游接入方式使用标准 `.agents/skills/` 布局。i3 CLI 目前没有专用 Dojo 目标；应先核对实际宿主的本地技能接入协议、共享资源路径和技能发现行为，再确定安装方式。不要将其他宿主目标的安装成功视为 Dojo 已验证。
+
+### Oh My Pi
+
+先将本地分发包导出为完整插件目录：
+
+```bash
+node /absolute/path/to/package/bin/i3-composer-agent.cjs --extract --dir ./i3-composer-agent
+```
+
+然后使用实际导出目录的绝对路径注册：
+
+```text
+omp plugin marketplace add /absolute/path/to/i3-composer-agent
+omp plugin install i3-composer-agent@i3-composer-agent
+```
+
+这是待人工验证的插件接入路径，i3 CLI 目前没有专用 Oh My Pi 原生目标。注册后需另行检查技能、命令和角色是否被宿主发现，以及模型能否正确调用；Hook 需要按宿主协议单独启用。

package/docs/workbuddy-setup.md

@@ -10,14 +10,14 @@ npx @givolt/i3-composer-agent --agents codebuddy,workbuddy --scope global --yes
 
 向导中 WorkBuddy 位于第 2 项，预选后仍可多选。全局目录：
 
-- `~/.workbuddy/skills/`：25 个 `i3-` 技能，选择说明和默认回复中文。
-- `~/.workbuddy/commands/`：9 个 `/i3-*` 短命令。
+- `~/.workbuddy/skills/`：26 个 `i3-` 技能，选择说明和默认回复中文。
+- `~/.workbuddy/commands/`：10 个 `/i3-*` 短命令。
 - `~/.workbuddy/agents/`：4 个专业角色。
-- `~/.workbuddy/references/i3-composer-agent/`：共享参考。
-- `~/.workbuddy/docs/i3-composer-agent/agents.md`：角色说明。
-- `~/.workbuddy/evals/i3-composer-agent/`：中英文用例、样例与评测结果。
-- `~/.workbuddy/hooks/i3-composer-agent/`：Hook 文件与说明。
-- `~/.workbuddy/scripts/i3-composer-agent/`：评测、校验与依赖库。
+- `~/.workbuddy/i3-composer-agent/references/`：共享参考。
+- `~/.workbuddy/i3-composer-agent/docs/agents.md`：角色说明。
+- `~/.workbuddy/i3-composer-agent/evals/`：中英文用例、样例与评测结果。
+- `~/.workbuddy/i3-composer-agent/hooks/`：Hook 文件与说明。
+- `~/.workbuddy/i3-composer-agent/scripts/`：评测、校验与依赖库。
 - `~/.workbuddy/.i3-composer-agent.json`：安装内容所有权及客户端清单。
 
 自定义 profile 可设置 `WORKBUDDY_CONFIG_DIR`，安装后打开对应 profile。
@@ -25,8 +25,8 @@ WorkBuddy 的目录选择使用自己的配置，不借用 `CODEBUDDY_CONFIG_DIR
 
 ## 配套检查
 
-运行 `node ~/.workbuddy/scripts/i3-composer-agent/run-evals.cjs --min-rank1 95`，检查实际安装技能的中英文触发，
-不会调用模型。项目安装将 `~/.workbuddy/` 换成 `.codebuddy/`。五项校验、行为评测用例、样例和
+运行 `node ~/.workbuddy/i3-composer-agent/scripts/run-evals.js --min-rank1 95`，检查实际安装技能的中英文触发，
+不会调用模型。进入 `~/.workbuddy/i3-composer-agent/` 运行 `npm test` 可检查完整内容、两种语言及全部脚本回归；原 `.js` 入口保留。项目安装将 `~/.workbuddy/` 换成 `.codebuddy/`。五项校验、行为评测用例、样例和
 脚本用法见 [评测说明](../evals/README.md)。Hook 文件默认提供，启用需适配宿主事件协议。
 
 ## 发现和调用

package/evals/README.md

@@ -6,22 +6,31 @@
 
 ## 运行位置
 
-原生安装的技能位于宿主基址的 `skills/`；评测资料位于 `evals/i3-composer-agent/`，
-脚本位于 `scripts/i3-composer-agent/`。安装清单记录预期技能和文件，评测只读取这份实际安装内容。
+原生安装的技能位于宿主基址的 `skills/`；评测资料位于 `i3-composer-agent/evals/`，
+脚本位于 `i3-composer-agent/scripts/`。安装清单记录预期技能和文件，评测只读取这份实际安装内容。
 例如 CodeBuddy 项目基址是 `.codebuddy/`，WorkBuddy 全局基址是 `~/.workbuddy/`。
 下面原生示例从业务项目根目录运行；从其他位置运行时，将脚本路径换成绝对路径即可。
-Node.js 20 或以上，无需额外 npm 依赖；`.cjs` 入口兼容业务项目的 ESM/CommonJS 设置。
+Node.js 20 或以上，无需额外 npm 依赖；配套根的独立 CommonJS 配置使 `.js` 入口兼容业务项目的 ESM/CommonJS 设置。
 
 ## 不调用模型的检查
 
+进入 `.codebuddy/i3-composer-agent/`（全局安装进入对应宿主的配套根）即可沿用：
+
+```bash
+npm test
+node scripts/run-evals.js --locale zh-CN --min-rank1 95
+```
+
+第一条执行五项校验、中英文评测与全部脚本回归；第二条只运行中文评测。以下项目路径入口也可用。
+
 ```bash
-node .codebuddy/scripts/i3-composer-agent/validate-skills.cjs
-node .codebuddy/scripts/i3-composer-agent/validate-versions.cjs
-node .codebuddy/scripts/i3-composer-agent/validate-commands.cjs
-node .codebuddy/scripts/i3-composer-agent/validate-reference-links.cjs
-node .codebuddy/scripts/i3-composer-agent/validate-artifact-paths.cjs
-node .codebuddy/scripts/i3-composer-agent/run-evals.cjs --locale zh-CN --min-rank1 95
-node .codebuddy/scripts/i3-composer-agent/run-evals.cjs --locale en --min-rank1 95
+node .codebuddy/i3-composer-agent/scripts/validate-skills.js
+node .codebuddy/i3-composer-agent/scripts/validate-versions.js
+node .codebuddy/i3-composer-agent/scripts/validate-commands.js
+node .codebuddy/i3-composer-agent/scripts/validate-reference-links.js
+node .codebuddy/i3-composer-agent/scripts/validate-artifact-paths.js
+node .codebuddy/i3-composer-agent/scripts/run-evals.js --locale zh-CN --min-rank1 95
+node .codebuddy/i3-composer-agent/scripts/run-evals.js --locale en --min-rank1 95
 ```
 
 五项校验分别检查技能格式、安装版本及登记文件、实际命令和角色格式、引用锚点、规格/计划产物路径。
@@ -37,8 +46,9 @@ npm run validate
 node scripts/run-evals.js --locale zh-CN --min-rank1 95
 ```
 
-独立插件的校验还会检查插件清单和三种命令格式的一致性。原生安装不复制这些注册清单，
-不需要在业务项目或宿主基址执行 `npm test`。
+原生配套与独立插件均保留全部原版脚本及回归测试。原生校验读取真实宿主命令，
+并与 `adapters/` 中另外两种格式比较；同时检查五份插件清单、配套包及安装版本。
+这些 adapter 输入不自动注册插件。在配套根运行 `npm test`，不修改业务项目配置。
 
 触发评测使用词法评分检查正例、负例、描述冲突、用例结构及样例是否齐全。
 中英文各自满足指定门槛；这不能证明模型在实际宿主中一定选择正确技能。
@@ -49,13 +59,13 @@ node scripts/run-evals.js --locale zh-CN --min-rank1 95
 先预览，不调用模型、不生成评测结果：
 
 ```bash
-node .codebuddy/scripts/i3-composer-agent/run-evals.cjs --behavioral i3-test-driven-development --locale zh-CN --dry-run
+node .codebuddy/i3-composer-agent/scripts/run-evals.js --behavioral i3-test-driven-development --locale zh-CN --dry-run
 ```
 
 确认需要后，移除 `--dry-run` 才会调用已登录的 Claude Code，并消耗该账户的模型额度：
 
 ```bash
-node .codebuddy/scripts/i3-composer-agent/run-evals.cjs --behavioral i3-test-driven-development --locale zh-CN
+node .codebuddy/i3-composer-agent/scripts/run-evals.js --behavioral i3-test-driven-development --locale zh-CN
 ```
 
 执行型用例需要 Git，并在临时 Git 项目中复制 `fixtures/` 的真实输入；
@@ -63,10 +73,12 @@ node .codebuddy/scripts/i3-composer-agent/run-evals.cjs --behavioral i3-test-dri
 可能编辑文件、运行命令、访问网络；各样例还可能需要自身的语言运行环境。
 评分依据执行轨迹或对话与 `expectations`，不会把“声称完成”当成实际执行证据。
 模型输出按不可信数据评分，执行和评分均有限时。临时项目完成后清理。
+每项评分必须提供非空白的 `evidence`；缺失或空白证据会使该次评分无效，原始输出保留为
+`.grading.raw.txt`，不能视为行为验收通过。
 
 `--locale en` 运行英文用例，省略该参数运行两种语言。可通过 `I3_EVAL_MODEL`
 和 `I3_EVAL_GRADER_MODEL` 指定执行/评分模型；报告同时记录宿主和模型信息。
-原生结果写入 `evals/i3-composer-agent/results/`；独立插件写入 `evals/results/`。
+原生结果写入 `i3-composer-agent/evals/results/`；独立插件写入 `evals/results/`。
 结果不会进入发行包和文件替换清单，升级保留；旧配套目录的结果会迁入新位置，同名异内容时停止迁移。
 
 ## 插件级评测
@@ -86,7 +98,7 @@ claude plugin eval . --no-publish
 
 ## Hooks
 
-原生的 `hooks/i3-composer-agent/`（独立插件为 `hooks/`）默认交付会话注入、文档缓存、代码块保护脚本及说明。
+原生的 `i3-composer-agent/hooks/`（独立插件为 `hooks/`）默认交付会话注入、文档缓存、代码块保护脚本及说明。
 安装文件不会自动注册事件。中文回复与普通技能调用不依赖启用 Hook。
 会话注入仅适用于缺少原生技能路由的宿主；已有路由时不要重复注入。
 缓存及保护的当前配置示例针对 Claude Code，详见

package/evals/cases/i3-documentation-and-adrs.json

@@ -39,6 +39,24 @@
         "Trade-offs and rejected options are recorded, not just the winning choice",
         "The ADR records a status from the skill's lifecycle (Proposed, Accepted, Superseded or Deprecated) and a date"
       ]
+    },
+    {
+      "id": 4,
+      "kind": "execution",
+      "prompt": "Review README.md for operators onboarding to this batch queue. Make the prose clearer, check it against queue.js, and keep the operational details and caveats accurate. Do not change the implementation.",
+      "expected_output": "A concise operational README grounded in the inspected implementation, with unsupported assurances removed or flagged, limits and caveats preserved, and the unverified command identified",
+      "files": [
+        "i3-documentation-and-adrs/prose-review"
+      ],
+      "expectations": [
+        "The final README identifies queuectl submit jobs.json --max-batch-size 50 as an unverified documented example because the fixture contains neither the CLI nor jobs.json; it does not invent, silently certify, or replace that interface",
+        "The final README preserves the 50-job batch limit, 72-hour retention period, and at most three retries, distinguishing those units correctly",
+        "The final README preserves the operational caveat that failed jobs require operator review and queue state is not durable across a process restart",
+        "The unsupported claims of guaranteed zero job loss and no need for monitoring are removed or explicitly marked as unsubstantiated rather than restated as facts",
+        "The promotional opening is replaced with a concrete description of the queue without invented users, benchmarks, certifications, or capabilities",
+        "The execution trace shows the agent inspecting queue.js and comparing the README with its batch, retention, retry, and in-memory-state implementation before editing",
+        "queue.js remains unchanged, and the agent does not install a tool or send the fixture to a hosted service"
+      ]
     }
   ]
 }

package/evals/cases/i3-test-driven-development.json

@@ -13,6 +13,14 @@
       {
         "prompt": "What tests should cover this new parsing logic before I write it?",
         "top_k": 3
+      },
+      {
+        "prompt": "Add unit tests for this function. There are none yet.",
+        "top_k": 3
+      },
+      {
+        "prompt": "Fix this bug: splitCents(100, 3) returns [33, 33, 33] and a cent goes missing. Here is the function.",
+        "top_k": 3
       }
     ],
     "negative": [

package/evals/cases/i3-ui-prototype.json

@@ -0,0 +1,49 @@
+{
+  "skill_name": "i3-ui-prototype",
+  "trigger": {
+    "positive": [
+      {
+        "prompt": "Choose a UI prototype template and generate an interactive approval prototype for review",
+        "top_k": 1
+      },
+      {
+        "prompt": "Generate a reviewable interactive UI prototype from business requirements",
+        "top_k": 1
+      },
+      {
+        "prompt": "Inspect prototype fidelity against its approved prototype baseline",
+        "top_k": 1
+      },
+      {
+        "prompt": "Iterate the interactive prototype using review feedback and preserve the approved baseline",
+        "top_k": 1
+      }
+    ],
+    "negative": [
+      {
+        "prompt": "Build an accessible modal component with keyboard support",
+        "owner": "i3-frontend-ui-engineering"
+      },
+      {
+        "prompt": "Optimize slow database indexes",
+        "owner": "i3-performance-optimization"
+      }
+    ]
+  },
+  "evals": [
+    {
+      "id": 1,
+      "prompt": "Create an interactive application approval prototype from the supplied business brief. Use template mode explicitly, compare the templates and generate a review candidate. Do not approve it yourself.",
+      "expected_output": "A runnable business-specific prototype with traceability and pending-review status",
+      "files": [
+        "i3-ui-prototype"
+      ],
+      "expectations": [
+        "Selected template and template mode are recorded without claiming UI/UX Pro Max was used",
+        "Business fields, role visibility, status transitions and review scenarios follow the supplied brief",
+        "A runnable prototype and verification evidence are produced; absent browser evidence is marked pending",
+        "The prototype remains pending human review and no approved baseline is invented"
+      ]
+    }
+  ]
+}

package/evals/fixtures/i3-documentation-and-adrs/prose-review/README.md

@@ -0,0 +1,19 @@
+# Batch Queue
+
+Batch Queue is an innovative, enterprise-grade solution that seamlessly unlocks
+the power of batch processing. In today's fast-paced landscape, it is important
+to note that this robust queue empowers operators to take work to the next level.
+
+## Submit a batch
+
+```sh
+queuectl submit jobs.json --max-batch-size 50
+```
+
+A batch contains at most 50 jobs. Queue entries expire after 72 hours. Failed
+jobs are retried at most three times.
+
+Operators review jobs that still fail after retries. Queue state is held in
+memory and is not durable across a process restart.
+
+This guarantees zero job loss and means operators never need to monitor the queue.