| name | spec-init |
| description | 在仓库根目录初始化项目规范文档骨架并生成最小 README 模板。用于用户要求创建 `docs/` 规范目录、搭建 `rules`/`knowledge`/`changes`/`archives` 工作区、初始化 spec 文档承载结构，或在已有 `docs/` 存在时按 `docs_v2`、`docs_v3` 等安全回退命名创建新文档骨架时。 |
spec-init
协同技能
在执行本 skill 时，同时遵守 ../../references/full-sdd-lifecycle.md 中 spec-init 阶段的协同规则。
- 用本插件
skills/documentation-and-adrs/SKILL.md 的心智约束目录职责与长期文档边界
- 用本插件
skills/context-engineering/SKILL.md 控制初始化阶段只读取最少上下文
- 本 skill 只负责搭建文档骨架，不替代后续
spec-propose、spec-apply 等阶段动作
目标
在当前工作目录创建一套可持续演进的规范文档骨架。
- 只初始化目录结构和最小说明文件
- 不生成具体业务规格文档
- 不生成任务拆解
- 不迁移历史文档
- 不覆盖任何已有目录或文件
执行规则
按下面顺序执行，不要跳步：
- 将当前工作目录视为仓库根目录。
- 计算目标根目录名：
- 优先使用
docs/
- 若
docs/ 已存在，则依次检查 docs_v2/、docs_v3/、docs_v4/
- 选择第一个不存在的目录名
- 将任意已存在的候选目录视为“已占用”，即使它只是部分残缺结构，也不要复用或覆盖。
- 先创建完整目录树，再写入所有
README.md。
- 若任一步骤失败，立即停止，避免留下半初始化状态。
- 完成后明确告知用户最终创建的根目录名称。
- 如果仓库已经存在与
docs/ 等价的规范体系，先说明差异，再决定是复用还是新建版本化目录。
目录结构
始终创建完整结构：
<root>/
├── rules/
│ └── README.md
├── knowledge/
│ └── README.md
├── changes/
│ ├── templates/
│ │ └── README.md
│ ├── log/
│ │ └── README.md
│ └── README.md
└── archives/
└── README.md
其中 <root> 是 docs/ 或冲突回退后的 docs_vN/。
README 编写要求
为每个目录写简洁、稳定、可复用的说明文件。
- 先写一句话说明目录用途
- 再写最小必要的内容分类或使用建议
- 不写与目录职责无关的流程描述
- 不列出尚未创建的详细索引
- 保持中文说明，目录和文件名保持英文小写
使用以下模板内容。
rules/README.md
# 总览
本目录用于沉淀仓库级代码约束、架构边界和质量要求，避免实现偏离项目设计。
## 文件概述
- 当前目录下的每个规则文件都应是默认生效的长期约束
## 执行原则
- 代码实现必须满足本目录规则，否则视为未完成交付
knowledge/README.md
# 总览
本目录用于沉淀项目领域知识、背景上下文和术语说明，供实现时按需参考。
## 内容建议
- 业务概念
- 外部系统背景
- 数据模型背景
- 常见术语解释
changes/README.md
# 总览
本目录用于管理活跃变更，包括模板、任务拆解和变更日志。
## 子目录说明
- `templates/`: 放置可复用模板
- `log/`: 记录需求、设计与实现过程中的关键变更
changes/templates/README.md
# 总览
本目录用于存放可重复使用的文档模板，供后续规格、任务和记录文件复用。
## 内容建议
- 规格模板
- 任务拆解模板
- 记录模板
changes/log/README.md
# 总览
本目录用于记录需求、设计、实现和验收过程中的关键变更，确保决策可追溯。
## 记录建议
- 需求调整
- 设计取舍
- 实现偏差
- 验收结论
archives/README.md
# 总览
本目录用于归档已完成、已废弃或已替代的历史文档，避免干扰当前活跃工作区。
## 使用建议
- 仅归档不再活跃维护的内容
- 归档前应确保活跃目录已有最新版本
约束
始终满足以下要求：
- 默认目标目录名必须是
docs/
- 发生冲突时必须按
docs_v2/、docs_v3/、docs_v4/ 顺序递增
- 不允许只创建部分目录
- 不覆盖用户已有文件或目录
- 不推断业务模型
- 不自动补写
AGENTS.md
- 不自动创建
spec-*.md
验证
创建完成后至少检查以下内容：
- 最终根目录名是否符合冲突回退规则
rules/、knowledge/、changes/、archives/ 是否全部存在changes/templates/ 与 changes/log/ 是否存在- 所有要求的
README.md 是否存在
- README 内容是否与目录职责一致
- 是否没有覆盖任何已有内容
输出
向用户返回简洁结果，至少包含：
- 最终创建的根目录名
- 已创建的核心目录
- 是否通过基础校验
