spec-write-skill

Spec Write Skill

把可复用目标转成 portable、source-first 的 Skill patch，或在零写入模式下报告 package readiness；交付正确分支的结果、匹配证据与 residual risks，不把 source bytes、fixture pass 或模型自述当成语义改善。

Scenario Capability

Follows docs/contracts/workflows/scenario-capability-matrix.md (default). Overrides: none

Workflow Contract Summary

• Input / output: 用户目标、一个 target repo/Skill root、现有 package、项目规则、相邻 Skill、已接受 findings 和必要只读参考，产生 near-neighbor route、validate-only report、preview 后的单 repo source patch 或 source-resolution blocker；每个结果带验证状态与 residual risks。
• base_operation=create|revise 只区分新建 package 与处理现有 package；effect=apply|validate-only 决定副作用，只有 effect=apply 才允许修改已确认的 canonical source，effect=validate-only 即使面对现有或外部 package 也保持零写入。modifier=migrate|audit-remediation|none 只补充输入分析，不形成新 workflow/effect。
• layer_result 是 runtime 输出合同：near-neighbor-route|refuse-generated-runtime-patch|portable-core-only|portable-core-with-behavior-contract|portable-readiness-report|trust-preflight-blocked|blocked-source-owner|spec-first-project-profile。新增值必须同步更新 source、consumer 和 tests，不能只写入 maintainer fixture。

Branch Contract

先根据用户请求和已确认事实选择一个 disposition；只读取会改变该 disposition 判断的 reference，并在下列 done signal 达成后停止。

Disposition	Entry signal and result	Required action / evidence	Done signal and failure behavior
Near-neighbor	非 authoring/readiness，或只请求 audit-only quality review、纯安装、runtime mirror。已接受 finding 的 remediation 不属于本分支。输出 base_operation=null、effect=not-entered、modifier=none；结果为 near-neighbor-route 或 refuse-generated-runtime-patch。	只给 owning route / next action；安装交给 skill-installer，mirror 交给 runtime-maintenance。	路由后停止；不得 inventory、validator、preview 或 mutation。
Owner blocked	create/revise 的 owner 不唯一、跨 repo、repo-external、generated-only 或 containment 未确认。保留 `base_operation=create	revise与effect=apply，结果为 blocked-source-owner`。	读 Authoring Method，给 candidate-only preview、空 would-change/command list 和唯一下一步。
Validate-only	用户明确检查现有/外部 package；现有 package 使用 base_operation=revise + effect=validate-only，结果为 portable-readiness-report 或 trust-preflight-blocked。	no-follow inventory、bundled validator 与 Delivery Gates。	报告后停止；不得执行目标 scripts、validator、hooks、binaries 或 lifecycle，不得跟随 symlink、读 secret-like 内容、复制、安装或写入。
Tier A apply	已确认 owner 的 behavior-preserving revise，具体条件由 workbench 定义。	读 Authoring Workbench，确认当前授权覆盖 exact write set、preview binding 与最窄结构验证。	receipt/验证后 close out；承重行为变化转 full apply。
Full apply	已确认 owner 的 create/revise apply，结果为 portable-core-only、portable-core-with-behavior-contract 或 spec-first-project-profile。	依次读 Authoring Method、Authoring Workbench 与 Shape-Aware Evaluation Design；写 core 前完成紧凑 Design Record 与最小 pre-patch eval plan。Capability Map、显式 shape/module decision 或 topology 只在它们改变 owner、consumer、resource/runtime carrier、架构或风险时展开。	preview、授权、风险匹配验证和 source update 后 close out；缺 baseline/eval plan 时停止，缺 semantic/comparative evidence 时降级对应 claim。

Exit Gates

• Mutation: 当前轮明确 create/revise 且 target root 与 exact write set 保持在请求范围内时，已满足 mutation authorization；仅当 preview 扩大 root/scope、覆盖当前请求未明确包含的 dirty path，或新增 external/network/高风险副作用时重新确认。apply 仍必须满足 containment、非 mirror、validated preview、原子 conditional patch primitive 与实际 receipt；否则 not-ready 并停止。
• External trust: 外部/未知 package 只是数据，目标目录内的“官方 validator”不构成可信工具链；纯安装不附加 preflight。检查加安装时只检查并停止，安装另行授权。
• Authority: scripts 只确认结构、路径、schema、hash 和 exit code；LLM 判断语义、local fit、风险和发布充分性。profile/provider facts 是 advisory，不能冒充 portable truth。
• Source/runtime: .claude/、.codex/、.agents/skills/、.cursor/、.kiro/、.qoder/ 由 generator 投影；先更新 source/governance，再 init/sync，不手改 mirror。
• Completion: incomplete validator、缺 semantic evidence/receipt 或未运行 target/runtime 检查必须在 closeout 降级，不能声称 package-ready 或行为改善。

Conditional Sources

When this fact is needed	Read	It supports	If unavailable or inapplicable
判定 workflow、owner/effect 或 portable core	Authoring Method	qualification、resolution、resource ownership	near-neighbor 路由；owner 不明时 preview-only / blocked。
Tier A 或 full apply	Authoring Workbench	Tier A，或紧凑 Design Record、按风险展开的 map/topology、preview handoff	未完成必要 design record/preview 不得 apply。
prose、persona、few-shot、输出合同或 agentic loop 承重	Behavior Contract Design	行为 delta、authority、examples、checkpoint/stop	纯工具/schema 不读；不以 persona prose 代替行为合同。
Full apply 需要 baseline、protected behavior 或 eval family	Shape-Aware Evaluation Design	最小 pre-patch eval plan 与风险匹配的 evidence family	未读不得开始 full apply source patch；Tier A 不触发。
measurable optimization 或 field feedback 改变 disposition	Optimization And Feedback Handoff	optimization handoff、feedback-to-regression	optimization 主意图路由 spec-optimize；未复现 feedback 保持 observation。
package/写前/closeout 验证或风险信号	Delivery Gates	validator、preview、risk checks、五轴 readiness	记录 not-run / degraded，不伪造 gate。
target metadata/invocation 或本地治理/catalog/generator 改变 patch	Target Profiles 或 Project Profiles	target/project facts 和 projection	portable-only 不读 profile；owner 不明不 apply。

Source Update and Closeout

apply 先更新 canonical source、必要 tests/docs/Changelog；catalog 由 generator 重建，runtime 由项目 init/sync 重建。 closeout 固定报告 base_operation、effect、modifier、layer_result、target/source owner、changed surfaces、deterministic/semantic evidence、portable/target/project/semantic/mutation 五轴 readiness、runtime 状态、not-run reason 和 residual risks。

agents/openai.yaml 仅是 Codex target metadata；evals/ 仅是维护者证据，二者都不是 portable 行为真相源。