software-lifecycle

软件生命周期包 — 如何在此工作

此项目包含工程团队或 OSS 项目的文档生命周期。流程为 提案 → 决策 → 规范 → 事后复盘，而 指南 用于存放操作说明。本技能承载工作流，让模板和文件夹说明保持简洁。

本技能提供软件包指导。平台 /open-knowledge 技能（读取／写入／预览／链接／依据规则）仍管理每项 Markdown 操作；本技能在此基础上叠加生命周期约定。

流程

proposals/    in-flight RFC-shape design proposals
   ↓ accepted
decisions/    frozen ADRs (the record of what was decided)
   ↓ derived
specs/        implementation specs for accepted proposals
   ↓ when things break
postmortems/  blameless incident write-ups
guides/       how-to / onboarding / runbooks (referenced throughout)

各文件夹规则 + Agent 行为

proposals/ — 每个提案一个文件（0001-feature-name.md）。状态流转为 draft → fcp → accepted/rejected。已接受的提案会晋升为 decisions/ 中的记录。结构：动机 / 设计 / 缺点 / 替代方案 / 未解决问题。Agent：当提案处于 status: draft 超过 14 天时，提醒作者推进、搁置或关闭提案。

decisions/ — 架构决策记录（MADR / Nygard 格式）。接受后即冻结。每个决策一个文件（NNNN-title.md）；状态为 proposed/accepted/deprecated/superseded。取代旧决策的新决策会通过 Supersedes: 链接回旧决策。Agent：新增决策时，扫描涉及同一子系统的现有记录，并在提交前提醒可能需要填写 Supersedes: 的候选记录。

specs/ — 根据已接受提案编写的实现规范。优先采用 github/spec-kit 格式：每个规范一个文件夹（specs/NNN-name/），包含 spec.md + plan.md + tasks.md（此软件包提供全部三个模板）。引用上级提案。Agent：当规范状态变为 status: shipped 时，如果负责人报告该规范所属子系统发生了事故，则建议使用事后复盘模板。

postmortems/ — 无责备的事故复盘，每起事故一个文件（YYYY-MM-DD-name.md）：摘要 / 时间线 / 根本原因 / 进展顺利之处 / 行动项（Google SRE 格式）。Agent：添加一个 Related: 区块，关联涉及相同子系统的既往事后复盘。

guides/ — 操作指南、入门文档和服务相关的运行手册（Diátaxis 操作说明）。提供 guide、onboarding-guide 和 runbook 模板。包含 last_verified 字段，以便在定期审核中发现过时指南。Agent：发布事后复盘时，扫描其行动项，查找适合编写成指南的后续事项，并创建指南草稿，预填症状和时间线摘录。

五种工作流

本项目中的文档编写遵循流程，而非惯例。每种工作流都以独立技能提供，因此仅在需要时加载 — 请使用与任务匹配的技能，而不是从头开始向文件夹中写入内容。

工作流	同级技能	适用时机
构思提案	/frame-a-proposal	某项变更需要先经过设计和论证，再开始构建。
编写规范	/write-a-spec	需要将已接受的提案细化为可实施的规范。
记录决策	/record-a-decision	已作出决策，需要保留其背景和影响。
编写事后复盘	/write-a-postmortem	发生事故，团队需要撰写无责备的复盘。
评审设计	/review-a-design	需要对现有提案、规范或决策进行严格审视，以检验其合理性。

模板

使用 write({ document: { path, template: "<name>" } }) 创建文档。模板仅包含结构（标题 + frontmatter 框架）；各部分的用途已在上文说明，不会在文档正文中重复。