spec-steward

Spec Steward（仓库管家）

保证对 .spec/ 的任何改动都放对位置、格式合规、索引与名册同步，并在开发完成后把“改了什么、为什么”沉淀回知识库。 本技能不复述业务规范；权威在 .spec/AGENTS.md、knowledge/README.md、rules/system.md 和对应 skill 正文。

何时使用

• 新增 / 修改 / 删除一个子 Agent、Skill、知识文档或规则时。
• 完成一处代码 / 设计改动后，要把它沉淀进 knowledge/ 时。
• 不确定某份内容该放哪（rules / standards / features / agents / skills / decisions）时。
• 需要清理 AI 文档冗余、降低误读、压缩长规则或做全量自查时。
• 用户问“规范有没有问题 / 规范的规范有没有问题 / 要不要更新规范”时，先定位对应规范责任，而不是默认进入全量整理。

前置条件

• 能随时查阅 .spec/AGENTS.md（调度核心、宿主差异）与 knowledge/README.md（知识导航）。
• 改动目标明确（知道要加 / 改 / 删什么）。

操作步骤

流程 A · 维护结构（新增 / 修改 / 删除能力）

1. 判类型——这份内容属于哪一类：
   • 禁止碰什么（护栏）→ rules/（硬规则在 rules/system.md，无 frontmatter）
   • 怎么做（流程 / 规范）→ knowledge/standards/（见 knowledge/README.md）
   • 某功能的设计 / 记录 → knowledge/features/<领域>/...（见 knowledge/README.md）
   • 一个职能角色 → agents/（先过 .spec/AGENTS.md 的准入口径，再照 reviewer 范例写）
   • 可复用方法 → skills/<name>/SKILL.md（目录名即 skill 名；description 只写触发条件，不概括流程）
   • 决策原因 → decisions/（ADR，只记录为什么）
2. 放对位置 + 命名：
   • agent 文件：<name>.agent.md
   • skill 目录：skills/<name>/SKILL.md
   • knowledge 文档：kebab-case，放在 standards/ 或 features/
3. 写 frontmatter：
   • agents：仅 name + description
   • skills：仅 name + description
   • knowledge：name + description + metadata（type / status）
   • rules / decisions：无 frontmatter
4. 同步登记：
   • 加 / 删子 Agent → 更新 .spec/AGENTS.md 子 Agent 名册与宿主差异表
   • 加 / 删知识文档 → 更新 knowledge/README.md
   • 加 / 删 ADR → 更新 decisions/README.md
   • 改动影响调度 → 更新 .spec/AGENTS.md 调度核心

流程 B · 沉淀知识（改动完成后）

1. 一句话总结：这次改了什么、为什么。
2. 判断文档归属：
   • 影响开发流程 / 规范 → 更新 knowledge/standards/ 对应文件。
   • 影响功能设计 → 找 knowledge/features/ 对应文档；有就更新，没有就从 _TEMPLATE.md 新建。
   • 决策 → decisions/ 新增 ADR。
   • 复发问题 / 踩坑经验 → 追加进 knowledge/lessons.md。
3. 更新正文：只保留当前有效内容，交付历史不入库（git 提交即历史）。
4. frontmatter status 只能取枚举：设计中 / 实施中 / 已交付 / 历史归档；description 保持一句话。
5. knowledge/README.md 导航行来源于 frontmatter description，同一句话口径。
6. 待执行事项走任务卡，不堆进知识库。