spec-init

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 等阶段动作

目标

在当前工作目录创建一套可持续演进的规范文档骨架。

• 只初始化目录结构和最小说明文件
• 不生成具体业务规格文档
• 不生成任务拆解
• 不迁移历史文档
• 不覆盖任何已有目录或文件

执行规则

按下面顺序执行，不要跳步：

1. 将当前工作目录视为仓库根目录。
2. 计算目标根目录名：
   • 优先使用 docs/
   • 若 docs/ 已存在，则依次检查 docs_v2/、docs_v3/、docs_v4/
   • 选择第一个不存在的目录名
3. 将任意已存在的候选目录视为“已占用”，即使它只是部分残缺结构，也不要复用或覆盖。
4. 先创建完整目录树，再写入所有 README.md。
5. 若任一步骤失败，立即停止，避免留下半初始化状态。
6. 完成后明确告知用户最终创建的根目录名称。
7. 如果仓库已经存在与 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 内容是否与目录职责一致
• 是否没有覆盖任何已有内容

输出

向用户返回简洁结果，至少包含：

• 最终创建的根目录名
• 已创建的核心目录
• 是否通过基础校验