@givolt/i3-composer-agent 3.1.0 → 3.2.1

package/skills/i3-enterprise-sop/references/{testcase/templates → templates}/testcase.md

@@ -8,15 +8,19 @@
 默认使用简体中文解释、追问及生成报告；用户明确要求其他语言时可切换。原方法正文、引用、阈值和审批条件完整保留。代码标识、路径、命令、工具参数、JSON 键/枚举与原文引用保持原样。
 <!-- i3:zh-guide:end -->
 
-原型只在本次实际适用且已采用时作为输入，不因缺少原型一律停止测试设计；依赖未定交互的用例明确待确认，其他场景可以继续。最终技术判据仍需核对选定 PRD 和有效 AD，起草不等于已经执行测试。
+模板版本：v0.1.7。模板版本与业务文档版本分别维护。
 
-**审查只标注，使用者决定处理。**文档审查者只读标注问题、准确位置、来源、影响和修改建议，不直接修改候选。使用者可以人工修改、明确委托模型修订、有依据地不采纳建议，或将业务问题保持待确认；审查意见不自动触发改写。保留旧稿、人工修改、原报告和逐项处理依据，按项目既有约束进行必要复查；缺少真实答复不为清零而补造规则，人工编辑也不自动等于审查通过或业务批准。
+## 使用说明（不复制为业务正文）
 
-模板版本：v0.0.4。日期：2026-10-18。状态：自有资源候选；模板可供明确采用，业务内容与认可另行记录。
+- **输入：**准确选定的 PRD／配套 AD，或外部 TestCase及产品与技术依据；适用测试规范、环境和数据条件。
+- **来源选择：**完整取得所选 PRD、配套 AD及本次必要真实答复；从 AD 采用表或项目已选引用定位规约、契约与目录规范，项目自有资料优先。本次用技术规约／契约条款制定测试预期或质量判据时，直接读取实际采用原件的完整正文，不以 AD 转述代替。测试目录、命令沿用 AD 已落实的映射；直接检查目录规范条款、映射不足或有冲突时，再读实际采用的目录规范，不将其设为所有 TestCase 的统一必读。可读资料未读完先补读，不作为业务 Q 跳过；确实无法取得时说明受限范围，不声称依据齐备。
+- **输出：**对应所选主题／AD的测试设计；默认保存到业务项目的本PBC目录，路径为`spec/{PBC名称}/{PBC名称}-{主题名称}-TestCase_v{业务版本}.md`，实际运行另存TestReport。已有明确采用位置或外部原件保留实际路径，不自动迁移。
+- **阶段职责：**产品预期直接核 PRD，技术判据核 AD和正式契约，不只由 AD 反推需求。完整交接绑定所选直接上游；关键依据缺失先澄清或标明受限范围，不伪造预期。TestCase不是所有 Plan 的统一前置；已有适用版本应引用，测试策略仍须充分。
+- **写作：**主会话按本 Skill 显式使用原 Spec；来源、假设、真实答复与 Q 分开。新建、外部稿整理与授权修订均保护业务原件、人工编辑和历史，不预填批准或运行结果。
+- **交付：**按下文完整填写适用内容，不以标题或数量代替语义覆盖；新增规范性要求逐条回查来源、权限与状态跨处一致、表格逐行核列义。生成或修订稿保存后检查落盘完整性，分段写入或报错时核对相关内容，保留内容自查；检查完成后按本Skill自动登记本次文档路径，再交人工审阅并停轮。登记不表示批准，只读审查只标注问题，不改稿或登记。
+- **工程衔接：**T1形成企业文档并交审；T2显式使用原 Spec，结合选定依据落实六项、形成工程 SPEC并交审；T3读取选定工程 SPEC调用原规划。每阶段保留人工审阅停点，不自动推进。工程事实缺失如实说明，不编造命令、代码或技术选型。用户另行明确选择原生等效规格方式时，沿原方法处理。
 
-采用[模板与交接合同](../../template-contracts.md)。实例文件名为 `{PBC}-{需求主题}-TestCase_v0.0.1.md`，其中包含多条用例与回归/评估安排。直接读取选定的 PRD、AD 和适用原型，不只从 AD 反推需求；设计遗漏也应被覆盖检查发现。所需条件、判据和报告合同先明确，真实执行结果另写一份或多份 TestReport，不预填通过结论。
-
-本模板承接原 SPEC 的测试策略：明确框架、测试目录、测试层级和适用覆盖要求，并固定引用 AD 的完整测试命令及运行条件。测试代码、实际报告、CONSTRAINTS 与其他辅助产物继续按原方法保留；本模板不替代原 TDD、浏览器或其他 Skill 的工具、步骤、停点和验证要求，也不强制复制 SPEC。
+未知项写明 Q及具体影响，不适用项说明依据；缺少工程条件只限制依赖它的范围。
 
 ---
 
@@ -26,19 +30,23 @@
 
 | 项目 | 本次实际值 |
 | --- | --- |
-| 能力/需求主题 | `{PBC capabilityId/名称；稳定prdId/主题；适用EBC引用}` |
-| 文档身份/版本/位置 | `{documentId；实际版本；可回读路径/固定内容及摘要}` |
-| 直接 PRD 依据 | `{选定主题、PRD版本、具体条目、固定内容与摘要}` |
-| 直接 AD 依据 | `{选定AD版本/固定内容/摘要；其产品引用与本PRD是否一致}` |
-| 原型、契约与质量规则 | `{适用原型版本/认可范围；接口、数据、项目规范固定引用；不适用或缺项说明}` |
+| 所属 EBC | `{ebcId；ebcName；已确认或候选边界}` |
+| 所属 PBC | `{pbcId；pbcName；已确认或候选边界}` |
+| 产品需求主题 | `{稳定prdId；主题名称；改名不换身份}` |
+| 文档身份/版本/位置 | `{documentId；类型TestCase；实际业务版本；可回读路径/固定内容及摘要}` |
+| 直接 PRD 依据 | `{选定PRD的documentId、实际路径、文内版本、需求／AC具体条目及固定内容；摘要可选}` |
+| 直接 AD 依据 | `{选定AD的documentId、实际路径、文内版本、设计条款及固定内容；其直接PRD身份／路径／版本与本PRD一致；摘要可选}` |
+| 原型、契约与质量规则 | `{引用ID、来源身份、实际路径或URL、版本或固定提交、条款／页面及本次采用范围；不适用或缺项说明}` |
 | 当前范围/比较基准 | `{全部有效目标、变化和保留；前次用例/真实实现及历史运行，不混为当前通过证明}` |
 | 模板/责任/状态 | `{固定模板；设计、复核、执行与业务验收责任；未指定如实写}` |
 
 ### 0.1 输入与确认核对
 
-| 输入 ID | 身份/版本/具体条目 | 固定内容/摘要与已读范围 | 用途与权威定义 | 认可/真实可用性/缺口 |
+| 引用 ID／类型 | 来源身份／实际路径或URL／文内版本或固定提交／具体条目 | 固定内容（摘要可选）与已读范围 | 本次用途／采用范围／判据落实位置与权威定义 | 认可/真实可用性/缺口 |
 | --- | --- | --- | --- | --- |
-| `{别名}` | `{PRD/AD/原型/外部规范/真实答复}` | `{可回读引用}` | `{产品预期/技术约束/交互等}` | `{分别记录，不由文件存在推定}` |
+| `{IN别名；直接PRD／直接AD／原型／契约／外部规范／真实答复}` | `{documentId或资料标识及适用ebcId／pbcId／prdId；准确位置、版本和条款}` | `{可回读的固定内容及实际已读部分}` | `{产品预期／技术约束／交互等及用例／章节位置}` | `{实际采用、仅参考、未取得分别记录，不由文件存在推定}` |
+
+本稿与直接PRD／AD使用一致的EBC／PBC编号名称和prdId，各文档独立版本，名称变化不换编号。跨PBC契约、关联主题与外部资料明确来源身份、准确版本及采用范围，不能替代本主题产品或设计依据。沿PRD／AD的固定引用读取必要原型、契约和适用规范，将判据落实到用例；这些资料不再依靠handoff.json扩展字段传递，也不另建平行清单。必要引用失效或版本冲突时列明缺项和影响，不从目录猜最新。
 
 本 TestCase 对应本次选定的一个 AD 版本；后续方法改进可形成新 TestCase 版本而不强制改变 AD 或 PRD 版本。同一能力其他主题可以有自己的用例集，组合交付时显式选择配套集合及集成范围，不自动合并目录中全部最新文件。
 
@@ -49,12 +57,12 @@
 | 方法／产物 | 职责与输入 | 输出及权限边界 |
 | --- | --- | --- |
 | 企业TestCase | 按PRD产品预期、AD技术判据及采用规范设计用例 | 测试设计与报告合同，不编写测试代码、不运行测试、不预填结果 |
-| 原Plan | 按当前范围的需求、设计、验证要求及真实工程拆任务 | 原tasks/plan.md和唯一任务目标；TestCase为可选输入，已有则引用，没有则安排补齐设计，不统一阻断规划 |
+| T3／原Plan | 按选定工程SPEC、必要来源、验证要求及真实工程拆任务 | 原tasks/plan.md和唯一任务目标；TestCase为可选输入，已有则引用，没有则安排补齐设计，不统一阻断规划 |
 | 原Build／test | 按获准任务及相关来源执行原TDD、缺陷复现、回归与适用浏览器验证 | 业务与测试代码、实际运行及构建证据；不是只读文档作业，不更改原方法或质量门槛 |
 | 企业文档review／recheck | 独立上下文核来源、语义、覆盖和报告约定 | 零项目写入，只在会话标注；有据人工处理或明确委托修订 |
 | 原代码review | 对真实代码与测试差异作原五维审查及验证 | 保留原检查和结论标准；其中临时变异检查后恢复源码涉及写入，不能整体套作零写入的文档审查 |
 
-原test是开发／修复中的TDD入口，Build也复用它；不要求每次Build之后重复执行同一无变化测试。文档审查通过不替代代码审查、测试或人类认可，保留人工修改空间不降低原合并和发布要求。原命令不天然发现企业TestCase或JSON，实际交接需明确任务或已采用指引；本资源不实现JSON登记接点、自动跨阶段执行或宿主路由。
+原test是开发／修复中的TDD入口，Build也复用它；不要求每次Build之后重复执行同一无变化测试。文档审查通过不替代代码审查、测试或人类认可，保留人工修改空间不降低原合并和发布要求。原命令不天然发现企业TestCase或JSON，实际交接需明确任务或已采用指引；交稿路径登记由本Skill处理，本模板不负责自动跨阶段执行或宿主路由。
 
 ## 1. 验证目标、范围与排除
 
@@ -115,6 +123,8 @@
 
 ## 4. 详细用例（逐用例填写）
 
+**EARS 使用：**将来源中行为的条件和状态写入前置条件，将事件写入操作或输入，将响应和副作用写成可判断的预期与检查方法；关联相应需求编号、AC和 AD条款，覆盖适用的正常、拒绝和异常场景。来源未采用 EARS句式时，按原意设计用例。
+
 ### {TC ID} · {用例名称}
 
 1. **来源**：`{PRD需求/AC/子项、AD技术条款及其他适用规范的身份、版本和准确位置}`。
@@ -159,7 +169,7 @@
 
 | 组合ID／作用范围 | 本主题PRD／AD／TestCase实际路径和各自版本 | 提供／消费方主题及配套引用 | 公共规范条款／契约与数据权威 | 实现／制品／环境事实 | 设计判断、执行状态与缺口 |
 | --- | --- | --- | --- | --- | --- |
-| `{独立主题或本次集成组合}` | `{以正文及真实采用为准，不强制同号}` | `{仅相关范围；缺关联TestCase如实记，不造未来文件路径}` | `{准确位置／版本；实际共享定义不在用例中复制另一权威}` | `{已有／拟建／未知；代码或服务不存在不填已部署}` | `{相容／冲突／待核实与依据；不预填运行通过}` |
+| `{独立主题或本次集成组合}` | `{各自documentId、准确路径及文内版本，以正文及真实采用为准，不强制同号}` | `{提供／消费方ebcId／pbcId／prdId及配套引用；仅相关范围，缺关联TestCase如实记，不造未来文件路径}` | `{来源引用ID、准确位置／版本／条款；实际共享定义不在用例中复制另一权威}` | `{已有／拟建／未知；代码或服务不存在不填已部署}` | `{相容／冲突／待核实与依据；不预填运行通过}` |
 
 一个主题TestCase仍对应本主题选定PRD和一个直接AD版本，关联引用用于组合场景；不用总用例文档包办全部主题，不要求双方版本数值一致。文档、契约、代码、服务各自版本属于不同对象，不能跨对象比较大小或据同号／SemVer／Schema校验宣布语义兼容。默认值、枚举、权限、错误、副作用及严格消费者均应核对。
 
@@ -193,9 +203,9 @@
 
 `{明确当前范围预期、方法、覆盖、所需条件、未决影响及报告约定是否足够，分别列可交接与仍缺定义范围。此结论不表示代码存在、环境可用或测试已运行。}`
 
-**TestCase是Plan的可选输入，不是统一前置文件。**当前范围的需求、技术约束和测试策略／验收预期可从PRD、AD及已采用规范充分回读时，可先按原Plan拆任务；没有独立TestCase不要求先补一份才能规划。已有且适用的TestCase应读取准确版本并落实到任务验收和验证步骤；缺少或待补的用例设计可作为计划任务，相关验证定义在依赖它的实现、测试或验收之前明确。核心行为或技术判据尚不明确时，只限制相应依赖任务，不把计划先行等同编码、测试或发布许可。
+**TestCase是工程SPEC和Plan的可选输入，不是统一前置文件。**T2可从PRD、AD及已采用规范形成含充分测试策略／验收预期的工程SPEC并交审，T3再按选定工程SPEC调用原Plan；没有独立TestCase不要求先补一份才能规划。已有且适用的TestCase应读取准确版本，经工程SPEC衔接并落实到任务验收和验证步骤；缺少或待补的用例设计可作为计划任务，相关验证定义在依赖它的实现、测试或验收之前明确。核心行为或技术判据尚不明确时，只限制相应依赖任务，不把计划先行等同编码、测试或发布许可。
 
-测试策略可在AD或现有测试规范中承载原SPEC六项的相应要求，不能因TestCase可选而跳过六项核对。企业SOP仍保留本主题TestCase设计交付，允许其与规划按依赖衔接，不取消正式交付所要求的验证定义。用例与任务、脚本可以多对多；只有真实脚本和任务形成后才登记实际路径，人工用例明确执行方式，不伪造全部自动化。
+AD或现有测试规范可提供测试策略依据，由T2落实到工程SPEC六项中的相应内容；不能因TestCase可选而跳过六项核对。企业SOP仍保留本主题TestCase设计交付，允许其与T2／T3按依赖衔接，不取消正式交付所要求的验证定义。用例与任务、脚本可以多对多；只有真实脚本和任务形成后才登记实际路径，人工用例明确执行方式，不伪造全部自动化。
 
 ### 7.2 执行可准入（候选形成后另存核实记录）
 
@@ -206,7 +216,7 @@
 | 任务和操作授权 | `{Plan范围/执行模式及适用高风险动作授权}` | `{可信来源；沿用有效授权，不自填批准}` |
 | 内容新鲜度与安全边界 | `{版本未变、影响已复核、清理/恢复可执行}` | `{失效范围、阻断用例或独立可执行部分}` |
 
-准入结论由实际核实产生并保存到独立记录，不回填本章为永久通过。设计可用于形成 Plan，不要求先有获批 Plan 才能编写计划；真正运行才核实计划认可和实际执行条件。缺必需条件的用例不准入、不算通过。
+准入结论由实际核实产生并保存到独立记录，不回填本章为永久通过。设计经T2落实到工程SPEC，供T3原Plan使用；不要求先有获批Plan才能编写计划，真正运行才核实计划认可和实际执行条件。缺必需条件的用例不准入、不算通过。
 
 ### 7.3 适用通过判据、缺陷处理与重测
 
@@ -225,7 +235,7 @@
 | 报告字段 | 执行后记录要求 |
 | --- | --- |
 | 报告身份与运行 | `{报告ID/版本、runId、实际起止时间、执行主体、实际工具/运行方式}` |
-| 本次选择 | `{capabilityId/prdId；PRD/AD/TestCase准确版本、固定内容及摘要；多主题组合逐项登记}` |
+| 本次选择 | `{ebcId／ebcName、pbcId／pbcName、prdId；PRD/AD/TestCase的documentId、准确路径、文内版本及固定内容，摘要按需；多主题组合逐项登记}` |
 | 本次组合 | `{§6.1组合ID；提供／消费方文档、契约、数据、代码／服务及环境各自版本；设计配套与真实兼容分开}` |
 | 实际候选 | `{源提交、构建/镜像制品、摘要；实际启动/部署对象，未部署不能写已部署}` |
 | 实际环境 | `{配置、依赖、身份/权限、数据版本及来源、真实/模拟边界；不泄露密钥}` |
@@ -262,8 +272,8 @@
 - 规格可交接、执行可准入、实际运行、业务认可分别记录，无循环开工条件。
 - 报告字段和1:N运行关系明确，未执行不预填通过；旧证据和失败记录保留。
 - §0.2、§3.3、§6.1—§6.4中的准确组合、唯一权威、失败恢复、传递影响和无关主题保护有实际来源。
-- §7.1不把完整TestCase设为所有Plan的前置；原test／Build仍执行TDD，原代码review与零写入文档审查职责分开。
+- §7.1不把完整TestCase设为T2工程SPEC或T3原Plan的统一前置；原test／Build仍执行TDD，原代码review与零写入文档审查职责分开。
 
-交接结论：`{本次可供Plan采用的验证要求、尚不能确定的判据和影响；实际执行须另行准入。当前版本及真实认可范围如实记录。}`
+交接结论：`{本次供T2工程SPEC及后续T3任务采用的验证要求、尚不能确定的判据和影响；实际执行须另行准入。当前版本及真实认可范围如实记录。}`
 
 版本变化：`{变化来源、修改用例/子项、受影响需求/AD/执行任务及报告适用性；保留旧版本与重新采用依据。}`

package/docs/upstream-repository/AGENTS.md

@@ -1,92 +0,0 @@
-# AGENTS.md
-
-This file provides guidance to AI coding agents (Claude Code, Cursor, Copilot, Antigravity, etc.) when working with code in this repository.
-
-> **Scope:** This file configures agents working on the [`addyosmani/agent-skills`](https://github.com/addyosmani/agent-skills) repository itself. It is not meant to be copied into other projects or into a global agent configuration; the reusable assets are the skills in `skills/`, not this file.
-
-## Repository Overview
-
-A collection of skills for Claude.ai and Claude Code for senior software engineers. Skills are packaged instructions and scripts that extend Claude and your coding agents capabilities.
-
-## OpenCode Integration
-
-OpenCode uses a **skill-driven execution model** powered by the `skill` tool and this repository's `/skills` directory.
-
-### Core Rules
-
-- If a task matches a skill, you MUST invoke it
-- Skills are located in `skills/<skill-name>/SKILL.md`
-- Never implement directly if a skill applies
-- Always follow the skill instructions exactly (do not partially apply them)
-
-### Intent → Skill Mapping
-
-The agent should automatically map user intent to skills:
-
-- Feature / new functionality → `spec-driven-development`, then `incremental-implementation`, `test-driven-development`
-- Planning / breakdown → `planning-and-task-breakdown`
-- Bug / failure / unexpected behavior → `debugging-and-error-recovery`
-- Code review → `code-review-and-quality`
-- Refactoring / simplification → `code-simplification`
-- API or interface design → `api-and-interface-design`
-- UI work → `frontend-ui-engineering`
-
-### Lifecycle Mapping (Implicit Commands)
-
-OpenCode does not support slash commands like `/spec` or `/plan`.
-
-Instead, the agent must internally follow this lifecycle:
-
-- DEFINE → `spec-driven-development`
-- PLAN → `planning-and-task-breakdown`
-- BUILD → `incremental-implementation` + `test-driven-development`
-- VERIFY → `debugging-and-error-recovery`
-- REVIEW → `code-review-and-quality`
-- SHIP → `shipping-and-launch`
-
-### Execution Model
-
-For every request:
-
-1. Determine if any skill applies (even 1% chance)
-2. Invoke the appropriate skill using the `skill` tool
-3. Follow the skill workflow strictly
-4. Only proceed to implementation after required steps (spec, plan, etc.) are complete
-
-### Anti-Rationalization
-
-The following thoughts are incorrect and must be ignored:
-
-- "This is too small for a skill"
-- "I can just quickly implement this"
-- "I’ll gather context first"
-
-Correct behavior:
-
-- Always check for and use skills first
-
-This ensures OpenCode behaves similarly to Claude Code with full workflow enforcement.
-
-## Orchestration: Personas, Skills, and Commands
-
-This repo has three composable layers. They have different jobs and should not be confused:
-
-- **Skills** (`skills/<name>/SKILL.md`) — workflows with steps and exit criteria. The *how*. Mandatory hops when an intent matches.
-- **Personas** (`agents/<role>.md`) — roles with a perspective and an output format. The *who*.
-- **Slash commands** (`.claude/commands/*.md`) — user-facing entry points. The *when*. The orchestration layer.
-
-Composition rule: **the user (or a slash command) is the orchestrator. Personas do not invoke other personas.** A persona may invoke skills.
-
-The only multi-persona orchestration pattern this repo endorses is **parallel fan-out with a merge step** — used by `/ship` to run `code-reviewer`, `security-auditor`, and `test-engineer` concurrently and synthesize their reports. Do not build a "router" persona that decides which other persona to call; that's the job of slash commands and intent mapping.
-
-See [docs/agents.md](docs/agents.md) for the decision matrix and [references/orchestration-patterns.md](references/orchestration-patterns.md) for the full pattern catalog.
-
-**Claude Code interop:** the personas in `agents/` work as Claude Code subagents (auto-discovered from this plugin's `agents/` directory) and as Agent Teams teammates (referenced by name when spawning). Two platform constraints align with our rules: subagents cannot spawn other subagents, and teams cannot nest. Plugin agents silently ignore the `hooks`, `mcpServers`, and `permissionMode` frontmatter fields.
-
-## Creating a New Skill
-
-> **Before you start:** 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`), confirm the idea fits [docs/skill-anatomy.md](docs/skill-anatomy.md), and justify the gap in your PR description. Most new-skill ideas overlap an existing skill or an open PR; prefer extending an existing skill over adding a near-duplicate. CONTRIBUTING.md is the single source of truth for this workflow.
-
-Skills in this repo are markdown-first: each lives at `skills/<kebab-case-name>/SKILL.md` with YAML frontmatter (`name`, `description`) and follows the section anatomy (Overview, When to Use, Process, Common Rationalizations, Red Flags, Verification). Add a `scripts/` directory only when the skill ships runnable helpers; most skills are markdown only, and there are no per-skill zip packages.
-
-For the full format, naming conventions, frontmatter rules, supporting-file thresholds, and writing principles, see [docs/skill-anatomy.md](docs/skill-anatomy.md), the single source of truth for skill structure. Do not restate that guidance here, link to it.

package/docs/upstream-repository/CLAUDE.md

@@ -1,60 +0,0 @@
-# agent-skills
-
-This is the agent-skills project — a collection of production-grade engineering skills for AI coding agents.
-
-> **Scope:** This file configures agents working on the [`addyosmani/agent-skills`](https://github.com/addyosmani/agent-skills) repository itself, not other projects. Don't copy it into another project or a global agent configuration; the reusable assets are the skills in `skills/`.
-
-## Project Structure
-
-```
-skills/       → Core skills (SKILL.md per directory)
-agents/       → Reusable agent personas (code-reviewer, test-engineer, security-auditor, web-performance-auditor)
-hooks/        → Session lifecycle hooks
-.claude/commands/ → Slash commands (/spec, /plan, /build, /test, /review, /code-simplify, /ship; plus /webperf specialist audit)
-references/   → Supplementary checklists (testing, performance, security, accessibility, observability)
-evals/        → Skill eval cases + framework (see evals/README.md)
-docs/         → Setup guides for different tools
-```
-
-## Skills by Phase
-
-**Define:** interview-me, idea-refine, spec-driven-development
-**Plan:** planning-and-task-breakdown
-**Build:** incremental-implementation, test-driven-development, context-engineering, source-driven-development, doubt-driven-development, frontend-ui-engineering, api-and-interface-design
-**Verify:** browser-testing-with-devtools, debugging-and-error-recovery
-**Review:** code-review-and-quality, code-simplification, security-and-hardening, performance-optimization
-**Ship:** git-workflow-and-versioning, ci-cd-and-automation, deprecation-and-migration, documentation-and-adrs, observability-and-instrumentation, shipping-and-launch
-
-## Conventions
-
-- Every skill lives in `skills/<name>/SKILL.md`
-- YAML frontmatter with `name` and `description` fields
-- Description starts with what the skill does (third person), followed by trigger conditions ("Use when...")
-- Every skill has: Overview, When to Use, Process, Common Rationalizations, Red Flags, Verification
-- Shared references are in the root `references/` directory; the emerging convention for self-contained, distributable skills keeps a skill's own references inside `skills/<name>/references/`
-- Supporting files only created when content exceeds 100 lines
-
-## Contributing
-
-Before adding a new skill 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, confirm the idea fits [docs/skill-anatomy.md](docs/skill-anatomy.md), and justify the gap. Prefer extending an existing skill over adding a near-duplicate. CONTRIBUTING.md is the single source of truth for this workflow; do not restate its checklist here or elsewhere, link to it.
-
-## Commands
-
-- `npm test` — Not applicable (this is a documentation project)
-- Validate: Check that all SKILL.md files have valid YAML frontmatter with name and description
-- Evals: `node scripts/run-evals.js` — trigger/routing evals for every skill (CI); `--behavioral <skill>` for graded runs
-
-## Pull Requests
-
-PRs target the upstream repository's default branch. In a typical fork setup the upstream remote is `upstream` and your fork is `origin`, but the exact remote names are not what matters here.
-
-- Before opening a PR, search the upstream repository's open PRs and issues for work that touches the same files or rules. If any overlaps, coordinate (build on it, align your rules with it, or rebase after it merges) instead of opening a conflicting PR.
-- Prefer small, focused PRs over large refactors of widely shared files (for example, files under `scripts/`), which are more likely to collide with in-flight work.
-
-## Boundaries
-
-- Always: Run the CONTRIBUTING.md pre-flight checks before creating a new skill directory
-- Always: Follow the skill-anatomy.md format for new skills
-- Always: Check the upstream repo's open PRs and issues for overlap before opening a new PR
-- Never: Add skills that are vague advice instead of actionable processes
-- Never: Duplicate content between skills — reference other skills instead

package/docs/upstream-repository/CONTRIBUTING.md

@@ -1,137 +0,0 @@
-# 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

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

package/docs/upstream-repository/gitattributes.txt

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

package/docs/upstream-repository/gitignore.txt

@@ -1,10 +0,0 @@
-.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

@@ -1,71 +0,0 @@
-{
-  "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

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

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

@@ -1,80 +0,0 @@
-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

@@ -1,15 +0,0 @@
----
-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.