create-yss-spec 3.3.4 → 3.3.6

package/template/.codex/skills/yss-product-lifecycle/SKILL.md

@@ -7,6 +7,8 @@ description: 编排 YSS 产品或模块从机会调研到 Spec、原型、技术
 
 生命周期单一主控：识别请求、仓库身份和最近可信阶段，计算可执行 frontier，派发并验收工作单元；业务设计、实现和独立审查交给专项 skill。
 
+文档按 `document_writing` 条件调用 `i-have-adhd`，并传递 `docs/process/document-writing.md` 规范。
+
 ## 事实源与按需加载
 
 先读 `yss-project.yaml`、`CONTEXT.md`、相关 ADR、父 Ticket/checkpoint 和当前资产，按需加载合同子树：
@@ -25,7 +27,7 @@ description: 编排 YSS 产品或模块从机会调研到 Spec、原型、技术
 scripts/query-lifecycle-context --mode route --stage stage.plan --work-unit work-unit.plan-requirements --include execution_efficiency
 ```
 
-`--include` 接受编排合同的顶层键；非法模式、ID 或合同键必须失败。查询结果只是带摘要的权威事实投影，不成为新的事实源。解释性细节按需读取 `references/orchestration.md`、`references/state-model.md`、`references/artifact-dependencies.md`、`references/user-decisions.md` 和 `references/matt-yss-adapter.md`，达到最小充分证据后停止扩展上下文。
+`--include` 接受编排合同的顶层键；非法模式、ID 或合同键必须失败。结果为权威投影；细节按需读 `references/orchestration.md`、`references/state-model.md`、`references/artifact-dependencies.md`、`references/user-decisions.md` 和 `references/matt-yss-adapter.md`，证据充分即停止加载。
 
 按 `execution_efficiency` 合并查询、复用未变资料并验证当前资产；产品流转不重跑模板套件。词汇对账、恢复核验及门禁不变，执行细节见 `references/orchestration.md`。
 

package/template/.codex/skills/yss-product-lifecycle/references/orchestration-contract.yaml

@@ -1,4 +1,16 @@
 schema_version: 1
+document_writing:
+  supporting_skill: i-have-adhd
+  condition: lifecycle-document-output
+  scope: current-document-work-only
+  dispatch: pass-condition-and-reference-to-document-owner
+  reference: docs/process/document-writing.md
+  examples: docs/templates/examples/lifecycle-writing-examples.md
+  load_when: [lifecycle-document-draft, lifecycle-document-revision, progress-or-decision-presentation]
+  dispatch_input: include-reference-for-document-work
+  artifact_ownership: unchanged
+  gate_and_status_semantics: unchanged
+
 backend_architecture_identity_policy:
   source: docs/agents/yss-skill-registry.yaml#architecture_profiles
   schema: docs/process/schemas/backend-architecture-identity.schema.json

package/template/.codex/skills/yss-prototype-stage/SKILL.md

@@ -7,6 +7,12 @@ description: Use when a YSS feature has product-design impact on a primary flow,
 
 把产品设计影响收敛为跨 Agent 一致的原型交付物、证据和生命周期回流合同。它不替代 `yss-product-lifecycle` 的门禁裁决，也不把原型当作生产前端代码。
 
+文档输出时按 `lifecycle-document-output` 条件调用 `i-have-adhd`，读取 `docs/process/document-writing.md`；作用域仅限当前产物，派发时传递条件及引用。
+
+## 文档写作
+
+起草或修订交互说明、状态说明和设计结论前，读取 `docs/process/document-writing.md` 的共用写法及产品设计指引；原型视觉和行为仍消费当前设计合同。
+
 ## 进入条件与主入口
 
 - 先由 `yss-product-lifecycle` 判断产品设计影响；无行为变化的孤立视觉修复记录 `not-applicable`，不创建空资产。

package/template/.codex/skills/yss-research/SKILL.md

@@ -9,6 +9,12 @@ Investigate facts that a YSS decision depends on. Produce evidence and bounded c
 
 `research` is a deprecated compatibility alias. Use `yss-research` in new assets and routing.
 
+文档输出时按 `lifecycle-document-output` 条件调用 `i-have-adhd`，读取 `docs/process/document-writing.md`；作用域仅限当前产物，派发时传递条件及引用。
+
+## 文档写作
+
+撰写研究简报或结论前，读取 `docs/process/document-writing.md` 的共用写法和研究指引；既有证据结构、来源限定和校验器要求保持完整。
+
 ## Profiles
 
 - `technical-evidence`: standards, official documentation, source code, third-party APIs, framework behavior, protocols, or implementation constraints. Decision-bearing claims must trace to primary sources.

package/template/.codex/skills/yss-stage-decision/SKILL.md

@@ -7,6 +7,12 @@ description: 编排 Plan 到 Spec 入口的方案决策与业务边界、协作
 
 `yss-stage-decision` 是由生命周期主控调度的上游决策技能，负责把需求、产品、商务输入和业务边界与规则设计结果整理成可审查、可版本化、可被下游消费的方案决策包。它不替代生命周期主控，也不生成产品代码、原型、OpenAPI 或垂直切片 Ticket。
 
+文档输出时按 `lifecycle-document-output` 条件调用 `i-have-adhd`，读取 `docs/process/document-writing.md`；作用域仅限当前产物，派发时传递条件及引用。
+
+## 文档写作
+
+撰写方案决策包和业务边界说明前，读取 `docs/process/document-writing.md` 的共用写法及 Plan 指引；原业务规则、决定依据和未决项完整保留。
+
 ## 适用边界
 
 - 适用于 `project-instance` 的 Plan → Spec 入口。

package/template/.codex/skills/yss-technical-design/SKILL.md

@@ -7,6 +7,12 @@ description: 在 YSS 技术分析中统一承接需求与战略输入，按已
 
 由 `yss-product-lifecycle` 调度，负责 `work-unit.technical-analysis` 的技术设计，不另起生命周期、不生成生产代码。生命周期维护批准和状态；`yss-implementation-contract-compiler` 消费批准且当前的设计，起草实现合同。
 
+文档输出时按 `lifecycle-document-output` 条件调用 `i-have-adhd`，读取 `docs/process/document-writing.md`；作用域仅限当前产物，派发时传递条件及引用。
+
+## 文档写作
+
+起草或修订技术设计解释正文前，读取 `docs/process/document-writing.md` 的共用写法及工程契约指引，并在分支派发中传递该引用；结构化合同保持原 schema 和验证要求。
+
 ## 输入与架构选择
 
 先读根 `CONTEXT.md`、已批准且当前的 Spec、业务规则、关键场景、适用的 API 契约、ADR 和工程约束。没有 API 或其他专项影响时记录有依据的不适用，不生成占位设计。

package/template/.cursor/skills/code-review/SKILL.md

@@ -13,6 +13,12 @@ Standards and Spec run as **parallel sub-agents** so they don't pollute each oth
 
 If `docs/agents/issue-tracker.md` is missing, tell the user to run `/setup-matt-pocock-skills`; do not invoke another user-invoked skill yourself.
 
+文档输出时按 `lifecycle-document-output` 条件调用 `i-have-adhd`，读取 `docs/process/document-writing.md`；作用域仅限当前产物，派发时传递条件及引用。
+
+## 文档写作
+
+撰写审查报告时，读取 `docs/process/document-writing.md` 的共用写法及审查指引；保留各审查轴的 findings、严重性、定位、证据及原裁决，不因压缩表达合并或降级。
+
 ## Process
 
 ### 1. Pin the fixed point and candidate

package/template/.cursor/skills/i-have-adhd/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Ayoub Ghriss
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/template/.cursor/skills/i-have-adhd/SKILL.md

@@ -0,0 +1,26 @@
+---
+name: i-have-adhd
+description: 在研发文档起草、修订、审查报告和交接表达时，按 YSS 中文规范组织具体、完整、可执行的输出；仅作用于当前文档工作。
+license: MIT
+---
+
+# i-have-adhd · YSS 适配
+
+为当前产物应用 `docs/process/document-writing.md`；该文是中文写法的唯一权威来源。需要例子时读取 `docs/templates/examples/lifecycle-writing-examples.md`。本技能是原资产所有者的配套技能，不持有业务决定、批准或生命周期状态。
+
+## 触发与作用域
+
+调用者在当前工作包含研究结论、Plan、Spec、设计说明、契约解释正文、Ticket、审查、交接、发布或复盘时，设置条件 `lifecycle-document-output` 并加载本技能。进度与会签表达也属于文档输出；纯代码修改、命令执行和后续无关会话不激活此条件。
+
+每次调用只覆盖输入指定的文档或报告。工作结束即结束本次作用域；用户后续要求正常表达或不使用本技能时遵从当前要求，不继承先前启用状态。不假设读者具有任何诊断。
+
+## 执行
+
+1. 接收产物类型、读者、允许改动范围和可读权威输入；先读共用规范，再读取对应阶段指引。字段、版本或规则来源不明确时保留缺口并回交原所有者，不补造业务决定。
+2. 先写当前问题、结论或交付行为，再提供依据和必要细节；按顺序动作、规则比较和因果说明选择编号、表格或段落。删除无信息的修饰和重复，不设置字数或规则数量上限。
+3. 对照输入核查主体、条件、例外、量词、范围、数值、证据、未决项、责任、时点和依赖。保持原 API 标识、schema、冻结行为、状态及批准证据；发现冲突时交回所有者，不以润色名义修复事实。
+4. 返回调整后的正文及必要的缺口说明，由原工作单元执行现有验证。明确区分已验证结果、估算和未知原因；未执行测试不写通过，多项实质阻塞全部保留。已授权工作由原执行者继续，不把可完成的操作转交用户。
+
+研究仍使用原研究证据合同；代码审查保留原轴、严重性、定位和结论；契约保持机器结构。共用规范不可读时停止受影响的文档改写并报告缺失引用，不妨碍独立的已授权工作。
+
+来源、固定版本和适配差异见 [YSS 适配说明](references/yss-adaptation.md)。只安装项目技能，不安装上游全局插件、hook 或会话持久模式。

package/template/.cursor/skills/i-have-adhd/agents/openai.yaml

@@ -0,0 +1,6 @@
+interface:
+  display_name: "i-have-adhd · YSS 文档配套"
+  short_description: "按当前研发文档任务应用中文写作规范，保持规则与证据完整"
+  default_prompt: "使用 i-have-adhd 配套技能改善当前研发文档表达，保留所有业务规则、证据、未决项和原批准状态。"
+policy:
+  allow_implicit_invocation: true

package/template/.cursor/skills/i-have-adhd/references/yss-adaptation.md

@@ -0,0 +1,21 @@
+# i-have-adhd 的 YSS 适配
+
+上游：`ayghri/i-have-adhd`；固定 revision：`7b9069b39972e269e61bd95c2f66ebb90cac6a02`；许可证见技能目录 `LICENSE`。
+
+原始文件来自 [固定版本目录](https://github.com/ayghri/i-have-adhd/tree/7b9069b39972e269e61bd95c2f66ebb90cac6a02/skills/i-have-adhd)。未经改写的来源基线保存在模板维护证据中；`upstream-files.json` 记录逐文件 SHA-256，`skills-lock.json` 记录上游目录哈希和当前技能目录哈希。基线不进入实例默认加载面。
+
+| 上游行为 | YSS 适配 |
+|---|---|
+| 用户显式调用、会话持续 | 原技能名保留；文档工作按 `lifecycle-document-output` 条件调用，任务结束即失效 |
+| 对读者作 ADHD 假设 | 面向所有文档读者，不引入诊断假设 |
+| 行动前置、步骤编号、删除套话 | 消费中文写作规范，按产物类型决定信息顺序和格式 |
+| 展示进度、下一步和具体时间 | 报告实际变化和全部必要阻塞；时间有依据才估算，不把工作推给用户 |
+| 压缩可见列表 | 完整性优先，不设规则数量上限 |
+| 原因与修复直接陈述 | 区分已知现象、待验证原因和实际验证结果 |
+| 平台专属 agent 配置 | 不安装上游 Gemini 持久提示；项目 OpenAI 配置只描述当前文档配套用途 |
+
+生命周期仍拥有门禁、状态、批准和资产；本技能没有独立授权、审批或分支流程。正文规则只在 `docs/process/document-writing.md` 维护；本文件只解释来源差异。
+
+注册表将本技能声明为模型可调用、实例默认可发现的通用工作流 core 技能（仍只作为文档配套）；调用者以条件依赖加载。上游 `disable-model-invocation: true` 在适配版移除；作用域由本技能触发条件限定，不延续上游会话开关。
+
+验证只证明来源、路由、投影和合同符合预期。中文文档质量需通过真实生成评估，不以结构检查或作者自检代替盲评效果。

package/template/.cursor/skills/i-have-adhd/tests/verify-integration.mjs

@@ -0,0 +1,63 @@
+// Structural and real dependency-resolution checks; not a model-output quality evaluation.
+import assert from 'node:assert/strict';
+import fs from 'node:fs';
+import path from 'node:path';
+import {pathToFileURL} from 'node:url';
+
+const root=path.resolve(process.argv[2] || '.');
+const read=ref=>fs.readFileSync(path.join(root,ref),'utf8');
+const {parse}=await import(pathToFileURL(path.join(root,'scripts/vendor/yaml.mjs')));
+const registry=parse(read('docs/agents/yss-skill-registry.yaml'));
+const skill=registry.skills.find(x=>x.id==='i-have-adhd');
+assert.equal(skill.instance_default_discoverable,true);
+assert.equal(registry.invocation_contract.overrides['i-have-adhd'].invocation_mode,'model');
+assert.ok(registry.invocation_contract.overrides['i-have-adhd'].exclusion_conditions.includes('unrelated-conversation'));
+assert.ok(registry.invocation_contract.overrides['i-have-adhd'].exclusion_conditions.includes('user-disabled'));
+const entry=read('.agents/skills/i-have-adhd/SKILL.md');
+assert.ok(!entry.includes('disable-model-invocation: true'));
+assert.equal(parse(read('.agents/skills/i-have-adhd/agents/openai.yaml')).policy.allow_implicit_invocation,true);
+const lock=JSON.parse(read('skills-lock.json'));
+const locked=lock.skills.shared['i-have-adhd'];
+assert.equal(locked.source,'ayghri/i-have-adhd');
+assert.equal(locked.sourceRevision,'7b9069b39972e269e61bd95c2f66ebb90cac6a02');
+assert.notEqual(locked.upstreamHash,locked.effectiveHash);
+const {treeHash}=await import(pathToFileURL(path.join(root,'scripts/lib/skill-supply-chain.mjs')));
+assert.equal(treeHash(path.join(root,'.agents/skills/i-have-adhd')),locked.effectiveHash);
+for (const target of locked.targets) {
+  const skillPath=target.endsWith('/i-have-adhd')?target:path.join(target,'i-have-adhd');
+  assert.equal(treeHash(path.join(root,skillPath)),locked.effectiveHash,`projection ${target}`);
+}
+for(const ref of ['docs/process/document-writing.md','docs/templates/examples/lifecycle-writing-examples.md']) {
+  assert.ok(read(ref).length);
+  assert.ok(!read(ref).includes('.template-source/'));
+}
+const callers=Object.entries(registry.skill_dependencies).filter(([,deps])=>deps.some(d=>d.skill==='i-have-adhd'));
+assert.ok(callers.length>0);
+for(const [owner,deps] of callers) {
+  const edge=deps.find(d=>d.skill==='i-have-adhd');
+  assert.equal(edge.type,'context-conditional');
+  assert.equal(edge.when,'lifecycle-document-output');
+  assert.ok(read(`.agents/skills/${owner}/SKILL.md`).includes('`i-have-adhd`'));
+}
+const orchestrator=registry.skills.find(x=>['yss-product-lifecycle','yss-strategic-design','harness-orchestrator'].includes(x.id)).id;
+const contract=parse(read(`.agents/skills/${orchestrator}/references/orchestration-contract.yaml`));
+assert.equal(contract.document_writing.supporting_skill,'i-have-adhd');
+assert.equal(contract.document_writing.condition,'lifecycle-document-output');
+assert.equal(contract.document_writing.scope,'current-document-work-only');
+assert.equal(contract.document_writing.gate_and_status_semantics,'unchanged');
+
+// Compile using the actual repository resolver, with and without the condition and again without it.
+const compiler=path.join(root,'scripts/lib/implementation-contract-compiler.mjs');
+if(fs.existsSync(compiler)) {
+  const api=await import(pathToFileURL(compiler));
+  const capability=registry.capabilities.find(c=>c.id==='governance.implementation-contract');
+  assert.ok(capability);
+  const run=conditions=>api.compileImplementationContract({registry,compilerContract:api.loadCompilerContract(),requiredCapabilities:[capability.id],conditions,root});
+  const off=run([]),on=run(['lifecycle-document-output']),next=run([]);
+  assert.ok(!off.required_skills.includes('i-have-adhd'));
+  assert.ok(on.required_skills.includes('i-have-adhd'));
+  assert.ok(!next.required_skills.includes('i-have-adhd'));
+  assert.equal(on.status,'draft');
+  console.log('PASS: actual resolver excludes code-only, includes document output, does not persist condition or approve the contract.');
+} else console.log('N/A: this strategic-only template has no implementation compiler; conditional route verified in registry and orchestration contract.');
+console.log(`PASS: source, license metadata, ${locked.targets.length} projections, ${callers.length} callers, scope and readable writing inputs. Model output quality not measured.`);

package/template/.cursor/skills/prototype-review/SKILL.md

@@ -7,6 +7,8 @@ description: Use when independently reviewing low-fidelity UI, interaction specs
 
 Use this skill as the independent low-fidelity review in `yss-prototype-stage`. The review is fail-closed: if the design cannot drive calibrated requirements, API, frontend acceptance, and slices, send it back to product design. `yss-product-lifecycle` alone records the resulting `check.prototype-reviewed` decision.
 
+文档输出时按 `lifecycle-document-output` 条件调用 `i-have-adhd`，读取 `docs/process/document-writing.md`；作用域仅限当前产物，派发时传递条件及引用。
+
 ## Trigger Boundary
 
 Run this independent gate only when UI changes affect a primary user flow, navigation, permissions, exception/recovery states, state transitions, or OpenAPI implications. For copy edits, token/color/spacing adjustments, and isolated visual fixes with no behavior, state, permission, navigation, or API impact, record `not-applicable` with the impact assessment; do not create prototype-review artifacts.

package/template/.cursor/skills/yss-implementation-contract-compiler/SKILL.md

@@ -7,6 +7,12 @@ description: Use when a YSS vertical slice is entering implementation, spans mul
 
 阶段 7 的实现合同编译器。它把已批准的生命周期资产、垂直切片、capability 和窄 Recipe 编译为 `Slice Implementation Contract` v2 草案；不批准合同、不写业务代码、不设置 `ready-for-agent`。
 
+文档输出时按 `lifecycle-document-output` 条件调用 `i-have-adhd`，读取 `docs/process/document-writing.md`；作用域仅限当前产物，派发时传递条件及引用。
+
+## 文档写作
+
+撰写实现合同的解释正文和切片交接说明前，读取 `docs/process/document-writing.md` 的共用写法及工程契约 / Ticket 指引；不改变结构化合同、批准状态或就绪条件。
+
 ## 输入
 
 先读取 Spec、切片 Ticket、需求冻结、适用的原型确认、OpenAPI Freeze/no-impact、系统/数据架构、Design Review、Build Architecture Checklist、实现仓库和验证命令。输入缺失、未批准或 `stale` 时输出 `blocked`，交回 `yss-product-lifecycle`。

package/template/.cursor/skills/yss-implementation-contract-compiler/references/boundaries.md

@@ -18,6 +18,7 @@
 
 | Capability | Primary skill | Task modes |
 | --- | --- | --- |
+| `writing.lifecycle-document` | `i-have-adhd` | `guidance` |
 | `architecture.technical-design` | `yss-technical-design` | `guidance`, `integration`, `review-input` |
 | `architecture.mvc-design` | `yss-mvc-design` | `guidance`, `integration`, `review-input` |
 | `layer.mvc-service` | `yss-application` | `guidance`, `integration`, `slice-implementation`, `troubleshooting`, `review-input` |
@@ -105,8 +106,16 @@
 
 | Skill | Dependency | Type | Condition |
 | --- | --- | --- | --- |
+| `prototype-review` | `i-have-adhd` | `context-conditional` | `lifecycle-document-output` |
+| `yss-implementation-contract-compiler` | `i-have-adhd` | `context-conditional` | `lifecycle-document-output` |
+| `yss-openapi-governance` | `i-have-adhd` | `context-conditional` | `lifecycle-document-output` |
+| `yss-stage-decision` | `i-have-adhd` | `context-conditional` | `lifecycle-document-output` |
+| `yss-research` | `i-have-adhd` | `context-conditional` | `lifecycle-document-output` |
+| `yss-product-lifecycle` | `i-have-adhd` | `context-conditional` | `lifecycle-document-output` |
+| `code-review` | `i-have-adhd` | `context-conditional` | `lifecycle-document-output` |
 | `code-review` | `yss-repository` | `context-conditional` | `backend-persistence-impact` |
 | `code-review` | `yss-mybatis` | `context-conditional` | `backend-persistence-impact` |
+| `yss-prototype-stage` | `i-have-adhd` | `context-conditional` | `lifecycle-document-output` |
 | `yss-prototype-stage` | `prototype-review` | `review-only` | — |
 | `yss-prototype-stage` | `yss-design-system` | `coordination-only` | — |
 | `yss-prototype-stage` | `yss-antdv-next-design` | `context-conditional` | `h2-vue-antdv-next-default` |
@@ -118,6 +127,7 @@
 | `yss-domain` | `domain-modeling` | `coordination-only` | — |
 | `yss-domain` | `yss-tactical-design` | `context-conditional` | `tactical-domain` |
 | `yss-domain` | `lombok` | `context-conditional` | `pojo` |
+| `yss-technical-design` | `i-have-adhd` | `context-conditional` | `lifecycle-document-output` |
 | `yss-technical-design` | `yss-tactical-design` | `coordination-only` | `domain-driven` |
 | `yss-technical-design` | `yss-mvc-design` | `coordination-only` | `layered-mvc` |
 | `yss-mvc-design` | `yss-openapi-draft-review` | `review-only` | `api-impact` |

package/template/.cursor/skills/yss-openapi-governance/SKILL.md

@@ -15,6 +15,12 @@ Spec / 设计输入 → OpenAPI YAML Draft → 审查与 Freeze → JSON 派生
 
 YSS DTO 的可复用 HTTP/JSON 映射由 `.agents/skills/yss-dto/references/openapi-wire-profile.yaml` 单一维护。它描述公开 wire shape，不是 Java 字段或 getter 清单；本 skill 必须消费 profile，不能在治理文档、feature YAML 和 JSON 中各自发明 `SingleResult`、`PageResult` 或 `PageQuery` 字段表。
 
+文档输出时按 `lifecycle-document-output` 条件调用 `i-have-adhd`，读取 `docs/process/document-writing.md`；作用域仅限当前产物，派发时传递条件及引用。
+
+## 文档写作
+
+编写接口说明和契约评审交接正文前，读取 `docs/process/document-writing.md` 的共用写法及工程契约指引；协议标识、schema、冻结状态和验证记录按原合同保存。
+
 ## 边界与职责
 
 使用 `yss-openapi-governance`：

package/template/.cursor/skills/yss-product-lifecycle/SKILL.md

@@ -7,6 +7,8 @@ description: 编排 YSS 产品或模块从机会调研到 Spec、原型、技术
 
 生命周期单一主控：识别请求、仓库身份和最近可信阶段，计算可执行 frontier，派发并验收工作单元；业务设计、实现和独立审查交给专项 skill。
 
+文档按 `document_writing` 条件调用 `i-have-adhd`，并传递 `docs/process/document-writing.md` 规范。
+
 ## 事实源与按需加载
 
 先读 `yss-project.yaml`、`CONTEXT.md`、相关 ADR、父 Ticket/checkpoint 和当前资产，按需加载合同子树：
@@ -25,7 +27,7 @@ description: 编排 YSS 产品或模块从机会调研到 Spec、原型、技术
 scripts/query-lifecycle-context --mode route --stage stage.plan --work-unit work-unit.plan-requirements --include execution_efficiency
 ```
 
-`--include` 接受编排合同的顶层键；非法模式、ID 或合同键必须失败。查询结果只是带摘要的权威事实投影，不成为新的事实源。解释性细节按需读取 `references/orchestration.md`、`references/state-model.md`、`references/artifact-dependencies.md`、`references/user-decisions.md` 和 `references/matt-yss-adapter.md`，达到最小充分证据后停止扩展上下文。
+`--include` 接受编排合同的顶层键；非法模式、ID 或合同键必须失败。结果为权威投影；细节按需读 `references/orchestration.md`、`references/state-model.md`、`references/artifact-dependencies.md`、`references/user-decisions.md` 和 `references/matt-yss-adapter.md`，证据充分即停止加载。
 
 按 `execution_efficiency` 合并查询、复用未变资料并验证当前资产；产品流转不重跑模板套件。词汇对账、恢复核验及门禁不变，执行细节见 `references/orchestration.md`。
 

package/template/.cursor/skills/yss-product-lifecycle/references/orchestration-contract.yaml

@@ -1,4 +1,16 @@
 schema_version: 1
+document_writing:
+  supporting_skill: i-have-adhd
+  condition: lifecycle-document-output
+  scope: current-document-work-only
+  dispatch: pass-condition-and-reference-to-document-owner
+  reference: docs/process/document-writing.md
+  examples: docs/templates/examples/lifecycle-writing-examples.md
+  load_when: [lifecycle-document-draft, lifecycle-document-revision, progress-or-decision-presentation]
+  dispatch_input: include-reference-for-document-work
+  artifact_ownership: unchanged
+  gate_and_status_semantics: unchanged
+
 backend_architecture_identity_policy:
   source: docs/agents/yss-skill-registry.yaml#architecture_profiles
   schema: docs/process/schemas/backend-architecture-identity.schema.json

package/template/.cursor/skills/yss-prototype-stage/SKILL.md

@@ -7,6 +7,12 @@ description: Use when a YSS feature has product-design impact on a primary flow,
 
 把产品设计影响收敛为跨 Agent 一致的原型交付物、证据和生命周期回流合同。它不替代 `yss-product-lifecycle` 的门禁裁决，也不把原型当作生产前端代码。
 
+文档输出时按 `lifecycle-document-output` 条件调用 `i-have-adhd`，读取 `docs/process/document-writing.md`；作用域仅限当前产物，派发时传递条件及引用。
+
+## 文档写作
+
+起草或修订交互说明、状态说明和设计结论前，读取 `docs/process/document-writing.md` 的共用写法及产品设计指引；原型视觉和行为仍消费当前设计合同。
+
 ## 进入条件与主入口
 
 - 先由 `yss-product-lifecycle` 判断产品设计影响；无行为变化的孤立视觉修复记录 `not-applicable`，不创建空资产。

package/template/.cursor/skills/yss-research/SKILL.md

@@ -9,6 +9,12 @@ Investigate facts that a YSS decision depends on. Produce evidence and bounded c
 
 `research` is a deprecated compatibility alias. Use `yss-research` in new assets and routing.
 
+文档输出时按 `lifecycle-document-output` 条件调用 `i-have-adhd`，读取 `docs/process/document-writing.md`；作用域仅限当前产物，派发时传递条件及引用。
+
+## 文档写作
+
+撰写研究简报或结论前，读取 `docs/process/document-writing.md` 的共用写法和研究指引；既有证据结构、来源限定和校验器要求保持完整。
+
 ## Profiles
 
 - `technical-evidence`: standards, official documentation, source code, third-party APIs, framework behavior, protocols, or implementation constraints. Decision-bearing claims must trace to primary sources.

package/template/.cursor/skills/yss-stage-decision/SKILL.md

@@ -7,6 +7,12 @@ description: 编排 Plan 到 Spec 入口的方案决策与业务边界、协作
 
 `yss-stage-decision` 是由生命周期主控调度的上游决策技能，负责把需求、产品、商务输入和业务边界与规则设计结果整理成可审查、可版本化、可被下游消费的方案决策包。它不替代生命周期主控，也不生成产品代码、原型、OpenAPI 或垂直切片 Ticket。
 
+文档输出时按 `lifecycle-document-output` 条件调用 `i-have-adhd`，读取 `docs/process/document-writing.md`；作用域仅限当前产物，派发时传递条件及引用。
+
+## 文档写作
+
+撰写方案决策包和业务边界说明前，读取 `docs/process/document-writing.md` 的共用写法及 Plan 指引；原业务规则、决定依据和未决项完整保留。
+
 ## 适用边界
 
 - 适用于 `project-instance` 的 Plan → Spec 入口。

package/template/.cursor/skills/yss-technical-design/SKILL.md

@@ -7,6 +7,12 @@ description: 在 YSS 技术分析中统一承接需求与战略输入，按已
 
 由 `yss-product-lifecycle` 调度，负责 `work-unit.technical-analysis` 的技术设计，不另起生命周期、不生成生产代码。生命周期维护批准和状态；`yss-implementation-contract-compiler` 消费批准且当前的设计，起草实现合同。
 
+文档输出时按 `lifecycle-document-output` 条件调用 `i-have-adhd`，读取 `docs/process/document-writing.md`；作用域仅限当前产物，派发时传递条件及引用。
+
+## 文档写作
+
+起草或修订技术设计解释正文前，读取 `docs/process/document-writing.md` 的共用写法及工程契约指引，并在分支派发中传递该引用；结构化合同保持原 schema 和验证要求。
+
 ## 输入与架构选择
 
 先读根 `CONTEXT.md`、已批准且当前的 Spec、业务规则、关键场景、适用的 API 契约、ADR 和工程约束。没有 API 或其他专项影响时记录有依据的不适用，不生成占位设计。

package/template/.pi/skills/code-review/SKILL.md

@@ -13,6 +13,12 @@ Standards and Spec run as **parallel sub-agents** so they don't pollute each oth
 
 If `docs/agents/issue-tracker.md` is missing, tell the user to run `/setup-matt-pocock-skills`; do not invoke another user-invoked skill yourself.
 
+文档输出时按 `lifecycle-document-output` 条件调用 `i-have-adhd`，读取 `docs/process/document-writing.md`；作用域仅限当前产物，派发时传递条件及引用。
+
+## 文档写作
+
+撰写审查报告时，读取 `docs/process/document-writing.md` 的共用写法及审查指引；保留各审查轴的 findings、严重性、定位、证据及原裁决，不因压缩表达合并或降级。
+
 ## Process
 
 ### 1. Pin the fixed point and candidate

package/template/.pi/skills/i-have-adhd/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Ayoub Ghriss
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/template/.pi/skills/i-have-adhd/SKILL.md

@@ -0,0 +1,26 @@
+---
+name: i-have-adhd
+description: 在研发文档起草、修订、审查报告和交接表达时，按 YSS 中文规范组织具体、完整、可执行的输出；仅作用于当前文档工作。
+license: MIT
+---
+
+# i-have-adhd · YSS 适配
+
+为当前产物应用 `docs/process/document-writing.md`；该文是中文写法的唯一权威来源。需要例子时读取 `docs/templates/examples/lifecycle-writing-examples.md`。本技能是原资产所有者的配套技能，不持有业务决定、批准或生命周期状态。
+
+## 触发与作用域
+
+调用者在当前工作包含研究结论、Plan、Spec、设计说明、契约解释正文、Ticket、审查、交接、发布或复盘时，设置条件 `lifecycle-document-output` 并加载本技能。进度与会签表达也属于文档输出；纯代码修改、命令执行和后续无关会话不激活此条件。
+
+每次调用只覆盖输入指定的文档或报告。工作结束即结束本次作用域；用户后续要求正常表达或不使用本技能时遵从当前要求，不继承先前启用状态。不假设读者具有任何诊断。
+
+## 执行
+
+1. 接收产物类型、读者、允许改动范围和可读权威输入；先读共用规范，再读取对应阶段指引。字段、版本或规则来源不明确时保留缺口并回交原所有者，不补造业务决定。
+2. 先写当前问题、结论或交付行为，再提供依据和必要细节；按顺序动作、规则比较和因果说明选择编号、表格或段落。删除无信息的修饰和重复，不设置字数或规则数量上限。
+3. 对照输入核查主体、条件、例外、量词、范围、数值、证据、未决项、责任、时点和依赖。保持原 API 标识、schema、冻结行为、状态及批准证据；发现冲突时交回所有者，不以润色名义修复事实。
+4. 返回调整后的正文及必要的缺口说明，由原工作单元执行现有验证。明确区分已验证结果、估算和未知原因；未执行测试不写通过，多项实质阻塞全部保留。已授权工作由原执行者继续，不把可完成的操作转交用户。
+
+研究仍使用原研究证据合同；代码审查保留原轴、严重性、定位和结论；契约保持机器结构。共用规范不可读时停止受影响的文档改写并报告缺失引用，不妨碍独立的已授权工作。
+
+来源、固定版本和适配差异见 [YSS 适配说明](references/yss-adaptation.md)。只安装项目技能，不安装上游全局插件、hook 或会话持久模式。

package/template/.pi/skills/i-have-adhd/agents/openai.yaml

@@ -0,0 +1,6 @@
+interface:
+  display_name: "i-have-adhd · YSS 文档配套"
+  short_description: "按当前研发文档任务应用中文写作规范，保持规则与证据完整"
+  default_prompt: "使用 i-have-adhd 配套技能改善当前研发文档表达，保留所有业务规则、证据、未决项和原批准状态。"
+policy:
+  allow_implicit_invocation: true

package/template/.pi/skills/i-have-adhd/references/yss-adaptation.md

@@ -0,0 +1,21 @@
+# i-have-adhd 的 YSS 适配
+
+上游：`ayghri/i-have-adhd`；固定 revision：`7b9069b39972e269e61bd95c2f66ebb90cac6a02`；许可证见技能目录 `LICENSE`。
+
+原始文件来自 [固定版本目录](https://github.com/ayghri/i-have-adhd/tree/7b9069b39972e269e61bd95c2f66ebb90cac6a02/skills/i-have-adhd)。未经改写的来源基线保存在模板维护证据中；`upstream-files.json` 记录逐文件 SHA-256，`skills-lock.json` 记录上游目录哈希和当前技能目录哈希。基线不进入实例默认加载面。
+
+| 上游行为 | YSS 适配 |
+|---|---|
+| 用户显式调用、会话持续 | 原技能名保留；文档工作按 `lifecycle-document-output` 条件调用，任务结束即失效 |
+| 对读者作 ADHD 假设 | 面向所有文档读者，不引入诊断假设 |
+| 行动前置、步骤编号、删除套话 | 消费中文写作规范，按产物类型决定信息顺序和格式 |
+| 展示进度、下一步和具体时间 | 报告实际变化和全部必要阻塞；时间有依据才估算，不把工作推给用户 |
+| 压缩可见列表 | 完整性优先，不设规则数量上限 |
+| 原因与修复直接陈述 | 区分已知现象、待验证原因和实际验证结果 |
+| 平台专属 agent 配置 | 不安装上游 Gemini 持久提示；项目 OpenAI 配置只描述当前文档配套用途 |
+
+生命周期仍拥有门禁、状态、批准和资产；本技能没有独立授权、审批或分支流程。正文规则只在 `docs/process/document-writing.md` 维护；本文件只解释来源差异。
+
+注册表将本技能声明为模型可调用、实例默认可发现的通用工作流 core 技能（仍只作为文档配套）；调用者以条件依赖加载。上游 `disable-model-invocation: true` 在适配版移除；作用域由本技能触发条件限定，不延续上游会话开关。
+
+验证只证明来源、路由、投影和合同符合预期。中文文档质量需通过真实生成评估，不以结构检查或作者自检代替盲评效果。

package/template/.pi/skills/i-have-adhd/tests/verify-integration.mjs

@@ -0,0 +1,63 @@
+// Structural and real dependency-resolution checks; not a model-output quality evaluation.
+import assert from 'node:assert/strict';
+import fs from 'node:fs';
+import path from 'node:path';
+import {pathToFileURL} from 'node:url';
+
+const root=path.resolve(process.argv[2] || '.');
+const read=ref=>fs.readFileSync(path.join(root,ref),'utf8');
+const {parse}=await import(pathToFileURL(path.join(root,'scripts/vendor/yaml.mjs')));
+const registry=parse(read('docs/agents/yss-skill-registry.yaml'));
+const skill=registry.skills.find(x=>x.id==='i-have-adhd');
+assert.equal(skill.instance_default_discoverable,true);
+assert.equal(registry.invocation_contract.overrides['i-have-adhd'].invocation_mode,'model');
+assert.ok(registry.invocation_contract.overrides['i-have-adhd'].exclusion_conditions.includes('unrelated-conversation'));
+assert.ok(registry.invocation_contract.overrides['i-have-adhd'].exclusion_conditions.includes('user-disabled'));
+const entry=read('.agents/skills/i-have-adhd/SKILL.md');
+assert.ok(!entry.includes('disable-model-invocation: true'));
+assert.equal(parse(read('.agents/skills/i-have-adhd/agents/openai.yaml')).policy.allow_implicit_invocation,true);
+const lock=JSON.parse(read('skills-lock.json'));
+const locked=lock.skills.shared['i-have-adhd'];
+assert.equal(locked.source,'ayghri/i-have-adhd');
+assert.equal(locked.sourceRevision,'7b9069b39972e269e61bd95c2f66ebb90cac6a02');
+assert.notEqual(locked.upstreamHash,locked.effectiveHash);
+const {treeHash}=await import(pathToFileURL(path.join(root,'scripts/lib/skill-supply-chain.mjs')));
+assert.equal(treeHash(path.join(root,'.agents/skills/i-have-adhd')),locked.effectiveHash);
+for (const target of locked.targets) {
+  const skillPath=target.endsWith('/i-have-adhd')?target:path.join(target,'i-have-adhd');
+  assert.equal(treeHash(path.join(root,skillPath)),locked.effectiveHash,`projection ${target}`);
+}
+for(const ref of ['docs/process/document-writing.md','docs/templates/examples/lifecycle-writing-examples.md']) {
+  assert.ok(read(ref).length);
+  assert.ok(!read(ref).includes('.template-source/'));
+}
+const callers=Object.entries(registry.skill_dependencies).filter(([,deps])=>deps.some(d=>d.skill==='i-have-adhd'));
+assert.ok(callers.length>0);
+for(const [owner,deps] of callers) {
+  const edge=deps.find(d=>d.skill==='i-have-adhd');
+  assert.equal(edge.type,'context-conditional');
+  assert.equal(edge.when,'lifecycle-document-output');
+  assert.ok(read(`.agents/skills/${owner}/SKILL.md`).includes('`i-have-adhd`'));
+}
+const orchestrator=registry.skills.find(x=>['yss-product-lifecycle','yss-strategic-design','harness-orchestrator'].includes(x.id)).id;
+const contract=parse(read(`.agents/skills/${orchestrator}/references/orchestration-contract.yaml`));
+assert.equal(contract.document_writing.supporting_skill,'i-have-adhd');
+assert.equal(contract.document_writing.condition,'lifecycle-document-output');
+assert.equal(contract.document_writing.scope,'current-document-work-only');
+assert.equal(contract.document_writing.gate_and_status_semantics,'unchanged');
+
+// Compile using the actual repository resolver, with and without the condition and again without it.
+const compiler=path.join(root,'scripts/lib/implementation-contract-compiler.mjs');
+if(fs.existsSync(compiler)) {
+  const api=await import(pathToFileURL(compiler));
+  const capability=registry.capabilities.find(c=>c.id==='governance.implementation-contract');
+  assert.ok(capability);
+  const run=conditions=>api.compileImplementationContract({registry,compilerContract:api.loadCompilerContract(),requiredCapabilities:[capability.id],conditions,root});
+  const off=run([]),on=run(['lifecycle-document-output']),next=run([]);
+  assert.ok(!off.required_skills.includes('i-have-adhd'));
+  assert.ok(on.required_skills.includes('i-have-adhd'));
+  assert.ok(!next.required_skills.includes('i-have-adhd'));
+  assert.equal(on.status,'draft');
+  console.log('PASS: actual resolver excludes code-only, includes document output, does not persist condition or approve the contract.');
+} else console.log('N/A: this strategic-only template has no implementation compiler; conditional route verified in registry and orchestration contract.');
+console.log(`PASS: source, license metadata, ${locked.targets.length} projections, ${callers.length} callers, scope and readable writing inputs. Model output quality not measured.`);

package/template/.pi/skills/prototype-review/SKILL.md

@@ -7,6 +7,8 @@ description: Use when independently reviewing low-fidelity UI, interaction specs
 
 Use this skill as the independent low-fidelity review in `yss-prototype-stage`. The review is fail-closed: if the design cannot drive calibrated requirements, API, frontend acceptance, and slices, send it back to product design. `yss-product-lifecycle` alone records the resulting `check.prototype-reviewed` decision.
 
+文档输出时按 `lifecycle-document-output` 条件调用 `i-have-adhd`，读取 `docs/process/document-writing.md`；作用域仅限当前产物，派发时传递条件及引用。
+
 ## Trigger Boundary
 
 Run this independent gate only when UI changes affect a primary user flow, navigation, permissions, exception/recovery states, state transitions, or OpenAPI implications. For copy edits, token/color/spacing adjustments, and isolated visual fixes with no behavior, state, permission, navigation, or API impact, record `not-applicable` with the impact assessment; do not create prototype-review artifacts.

package/template/.pi/skills/yss-implementation-contract-compiler/SKILL.md

@@ -7,6 +7,12 @@ description: Use when a YSS vertical slice is entering implementation, spans mul
 
 阶段 7 的实现合同编译器。它把已批准的生命周期资产、垂直切片、capability 和窄 Recipe 编译为 `Slice Implementation Contract` v2 草案；不批准合同、不写业务代码、不设置 `ready-for-agent`。
 
+文档输出时按 `lifecycle-document-output` 条件调用 `i-have-adhd`，读取 `docs/process/document-writing.md`；作用域仅限当前产物，派发时传递条件及引用。
+
+## 文档写作
+
+撰写实现合同的解释正文和切片交接说明前，读取 `docs/process/document-writing.md` 的共用写法及工程契约 / Ticket 指引；不改变结构化合同、批准状态或就绪条件。
+
 ## 输入
 
 先读取 Spec、切片 Ticket、需求冻结、适用的原型确认、OpenAPI Freeze/no-impact、系统/数据架构、Design Review、Build Architecture Checklist、实现仓库和验证命令。输入缺失、未批准或 `stale` 时输出 `blocked`，交回 `yss-product-lifecycle`。