507-setup

name	507-setup
description	为一个或多个代码项目做工作流初始化或全量规范巡检：核对 AGENTS、README、CHANGELOG、doc、术语、决策和代码目录现实，先报告再路由。Use when user says 项目初始化, 项目规范巡检, 工作流初始化, 校准 AGENTS, project setup, project bootstrap, scaffold. 不用于代码体检或架构 review；专项地图维护使用 507-map。

项目初始化与巡检（setup）

给具体代码项目建立或校准工作规范。它读取文档、代码结构、测试和配置来判断项目规范是否反映现实，先给巡检报告，再把专项修改路由给职责明确的 skill（技能）。

巡检标准以本技能的 references/project-standard.md 为权威来源；执行前先完整读取该文件。

核心对象

• 项目根 AGENTS.md、README.md、CHANGELOG.md；
• doc/README.md、术语表、决策档案和经验笔记；
• doc/ 的产品、架构、能力参考、路线图、实施方案和归档边界；
• 含代码目录的分层 README.md；
• 项目入口、测试/构建命令、配置与目录现实；
• 已反复口述但尚未沉淀的稳定约束。

什么时候使用

• 新项目需要接入完整工作流；
• 老项目需要全量规范巡检；
• AGENTS.md、项目入口、文档地图、术语和决策可能整体失真；
• 多个项目需要统一比较规范完备度。

只维护某个目录的 README、doc 组织或项目地图时，不跑全量巡检，使用 507-map。

修改边界

默认只读并输出报告，不直接修改文件。用户确认落地后：

• 可修改项目规范和基础文件；
• 地图文档的创建、移动或校准交给 507-map；
• 术语定义先由 507-grill 对齐；
• 架构摩擦转 507-inspect；
• 业务代码 bug 转 507-fix，行为不变内部简化转 507-simplify。

本 skill 不修改业务代码，不把全面巡检伪装成顺手重构，也不写宿主专属配置。

输入范围

用户可提供一个或多个项目根目录。若给的是 workspace（工作区），先识别其中的仓库并等待选定目标；不把 workspace 当单个项目，也不自动批量修改全部仓库。

巡检流程

0. 读取项目标准

完整读取 references/project-standard.md，再读目标项目。目标项目有明确历史例外时，记录差异、影响和推荐，不凭样例覆盖现状。

1. 扫描项目现实

读取根目录文件、入口、项目清单、测试/构建配置、doc/ 结构，以及代码目录 README。记录项目类型、当前入口、验证方式和明显缺口。

2. 核对项目规范

逐项检查：

• AGENTS.md 是否包含项目定位、阅读顺序、边界、验证和特有禁忌；
• 根 README.md 是否回答是什么、给谁用、怎么运行、目录与入口；
• 主动维护项目是否有 Keep a Changelog（维护变更日志）格式的 CHANGELOG.md 与 Unreleased；
• doc/README.md 是否说明阅读顺序、当前权威和归档边界；
• 路线图、实施方案、能力参考与归档是否职责清楚；
• 稳定项目语言是否进入术语表；
• 只有符合三项门槛的决定是否进入决策档案并维护索引；
• 含代码目录的 README 是否缺失或与代码现实冲突；
• 文档声明的入口、命令和职责是否能由代码与配置验证。

3. 输出巡检报告

# 项目初始化与巡检报告

## 总览
| 项目 | AGENTS | README | CHANGELOG | doc 地图 | 术语 | 决策 | 分层 README | 验证入口 | 主要缺口 |

## 项目详情
### <project>
- 当前现实：...
- 规范缺口：...
- 文档与代码冲突：...
- 历史例外：...
- 推荐动作：...

## 建议执行顺序
1. ...

每项建议说明依据、影响和对应落地 skill。没有实际内容时不建议创建空目录、空术语表、空决策档案或空经验笔记。

4. 经确认后路由落地

• 项目地图、README、doc 导航 → 507-map；
• 术语或真实取舍未对齐 → 507-grill；
• 架构摩擦 → 507-inspect；
• 需求规格/工单 → 507-prd / 507-issue；
• bug、测试或内部简化 → 507-fix / 507-test / 507-simplify。

一次只处理已确认的项目和范围，不跨项目批量改写。

验证

巡检报告必须能把每个结论定位到文件、代码结构或可运行配置。落地后按修改类型检查 Markdown（标记语言）链接、项目命令、差异范围和文档/代码一致性；无法验证时写明缺口。

红线

• 不未经确认重写项目规范；
• 不修改业务代码；
• 不生成任何宿主专属配置；
• 不为形式完整创建空文件；
• 不把归档当当前权威；
• 不把术语表写成实现细节；
• 不自动跨多个项目批量修改。

完成与接力

• 完成信号：初始化或巡检范围已覆盖项目规则、文档地图、变更记录、代码目录和验证入口，每项结论都有证据与状态。
• 产物：初始化产物或全量巡检报告；按授权边界先报告再落地，不修改业务代码。
• 候选出口：地图缺口进入 507-map；代码/测试问题进入 507-fix 或 507-test；需求或治理项进入 507-prd / 507-issue；落地后进入 507-review，用户明确要求提交时再进入 507-commit。
• 回退条件：项目规则互相冲突或需要用户选择治理方向时进入 507-grill，不自行重写权威规范。