Repo Init

---
name: repo-init
description: 读取 project-arch（或 project-lite）产出和项目现状，目标还不是 Git 仓库时执行 Git 初始化，规范仓库目录职责与文件归属，创建或更新 AGENTS.md（含合并策略），并按需适配其他 Agent 的规则入口。用于 Git 与仓库初始化、结构规范化、按个人偏好更新规则或多 Agent 兼容；不用于安装依赖或开发业务功能。
---

# 规范仓库结构并生成仓库指南

读取项目规划和实际文件，确定各类文件应该放在哪里，然后创建或更新 `AGENTS.md`，写成简洁、具体、可执行的目录约定和贡献指南。本 Skill 不依赖任何 Agent 的内置 `/init`，也不修改它。

## 规则与模板

- 优先级按 [开发流程契约](../shared/workflow-contract.md) 的“规则来源”执行。
- 每次生成前读取 [基础模板](references/init-template.md)。模板中的标题、语言、篇幅、章节都只是默认值，用户的偏好和项目规则可以覆盖它们。
- 个人偏好用于指导生成，不整段复制进项目文件，也不修改全局设置。读不到偏好时默认使用简体中文，标题为“仓库指南”；只有用户明确要求英文时才用 `Repository Guidelines`。中文篇幅以与英文 200–400 词相近的阅读量为准。

## 输入

- 接入完整流程时，读取 project-arch 交接的内容：目标路径、`CONTEXT.md`、需求文档、架构文档、调研记录、目标 Agent。来自 project-lite 时，读取 `docs/brief.md`。
- 也可以单独使用：以已有的 README、源码和配置为依据，区分“已确认的约定”和“本次的建议”，不为缺失的文档创建占位副本，也不另行开展访谈或调研。
- 读取已有的 `AGENTS.md`、README、清单、脚本、目录结构，必要时查看 Git 历史。目标项目可能只是上层仓库的一个子目录，查询和改动都限定在目标范围内。项目不一定是应用程序，也可能是 Skill、文档或配置仓库。
- 没有源码的新项目要如实说明当前状态：已规划但还没落地的目录、依赖和命令标为“计划”，不写成已经存在的事实。

## Git 初始化

- 用 `git -C <目标> rev-parse --show-toplevel` 判断。已在仓库中（包括目标是上层仓库的子目录）时跳过，不嵌套初始化，也不改已有的分支、远端和配置。
- 不在仓库中时执行 `git init -b main`；Git 版本不支持 `-b` 时，先 `git init`，再 `git symbolic-ref HEAD refs/heads/main`。
- 按已确定的技术栈写基础 `.gitignore`：依赖目录、构建产物、缓存、日志、本地环境与密钥文件（如 `.env`）。只写确定会产生的条目，已有文件只补缺。
- 用户提供了远端地址时 `git remote add origin <地址>`；新建远端仓库（如 `gh repo create`）需要单独授权。
- 不修改全局 Git 配置；缺少 `user.name` 或 `user.email` 时报告缺口，留给用户设置。
- 首次提交由最外层的 task-closeout 完成，本 Skill 不提交。初始化前已落盘的项目文件列入交接，随首次提交纳入，不当作无关文件遗漏：前一阶段的 `CONTEXT.md`、需求文档，以及已安装的项目级技能目录（如 `.claude/skills/`、`.agents/skills/`，技能随项目版本管理）。

## 目录职责

- 按 [仓库结构规范](references/repository-structure.md) 确定适用的目录职责。优先沿用有效的架构和工具约束；已有结构合理时保留，只补充新增文件该放在哪里的规则。
- 在指南的“项目结构”一节写出实际路径、用途和代表性文件，标明哪些是已有、哪些是计划。详细的模块设计链接到架构文档，必要时同步架构中的目录说明，避免两套说法互相冲突。
- 默认只制定规范，不搬迁现有文件。用户明确要求迁移时，先列出“旧路径 → 新路径 → 理由 → 受影响的引用”，再在授权范围内执行并验证。工具要求固定位置的文件保持不动，不创建空目录或脚手架。

## 指南内容

按实际情况保留、合并或省略以下章节：
- **项目结构**：目录归属、新增文件的放置规则、文档入口及读取时机（`CONTEXT.md`、需求文档或 brief、架构、计划或 Issues）。只链接这些文档，不复制正文。
- **构建、测试与开发命令**：只写已经确认的命令；尚未配置时如实说明，不编造。
- **代码风格与命名**：现有的风格和格式化工具；建议与已配置的规则分开写。
- **测试指南**：实际使用的框架、命名和运行方式；没有自动化测试时，给出相称的验证方式。
- **提交与合并**：从 Git 历史总结提交惯例，并写入合并策略：
  ```
  合并策略: auto   # auto：验收通过后自动合并 main | confirm：推送分支后等确认再合并 | pr：走 PR
  ```
  已有的取值保留不动；新建时默认写 `auto`，除非用户另有指定。
- **可选章节**：只在项目确实需要时添加，例如配置说明、架构概览、Agent 专属说明。

同一层级只维护一个 `AGENTS.md`。单个模块的专属规则不要提升为全项目规则。

## Agent 兼容入口

- 根目录 `AGENTS.md` 是项目规则的权威来源，但并非所有 Agent 都会自动加载它。只为用户指定的、或项目中已有集成的 Agent 建立兼容入口，不批量创建。
- 兼容入口（例如 `CLAUDE.md`、`GEMINI.md`）写成薄入口：只包含“读取并遵循 AGENTS.md”的指令，加上确有必要的产品专属内容。使用导入语法前，先按官方文档确认该产品支持；普通 Markdown 链接不能证明会被自动加载。
- 已有入口里有独特规则时，先把这些规则合并到正确的作用域，再改为引用，不直接覆盖。入口之间有实质冲突时，先完成没有冲突的部分，再就具体冲突询问用户。
- 需要共享的参考资料时，优先放在已有目录，没有合适目录时可以用 `.agents/`，并在 `AGENTS.md` 中写明路径。不创建空目录，不再默认创建 `.codex/`。

## 验证与交付

- 核对：路径和命令都有来源，章节适用于本项目，语言符合偏好，与其他规则没有冲突；兼容入口的引用目标存在，且没有循环引用。
- 用项目中的代表性文件检验归属规则是否明确，例如“新增的接口文档、模块测试、开发脚本分别放在哪里”。
- 分开说明“文件检查已完成”和“目标 Agent 的实际加载已验证或未验证”。
- 由 project-arch 调用时，只把新增或修改的路径和缺口交回调用方；单独执行时，最后执行 [task-closeout](../task-closeout/SKILL.md)。交接或答复中说明 Git 初始化结果：已初始化、已存在或跳过，以及远端是否配置。