incu-way-init

仓库初始化流程

一种由关卡驱动的工作流，用于将仓库接入 incu-way。它会为其他技能所依赖的内容打好基础：填写完整的 CLAUDE.md、PRD.md、docs/ 目录树、develop/main 分支模型以及 .ways/ 目录。对于现有应用（棕地项目——最常见的情况），它还会推动完成架构和功能文档，让人类和 incu-way 工作流真正了解仓库中的内容。

这是一个引导流程，而不是工作项流程。它不会创建 .ways/state.json（该模型用于 feature / bug / security 工作——请参阅 ways/v1alpha1 状态契约，该契约作为始终启用的 state-contract 规则提供）。相反，此技能会创建 .ways/ 目录，供后续工作项流程填充。

---

仓库资格检查（其他操作之前）

在 Phase 0 之前，检查 ~/.ways/config.yaml 的 blacklist（格式遵循始终启用的 incu-base global-config 规则），确认当前仓库是否在其中。如果匹配，告知用户该仓库已被 incu-way 列入黑名单，并询问是仍要继续（一次性例外）还是停止——在用户回答之前不要运行任何阶段。文件不存在或未匹配：正常继续。

---

Phase 0 — 熟悉情况并检测模式

目标： 判断这是绿地还是棕地仓库，以及 incu-way 是否已（部分）完成设置。此时不要写入任何内容。

检测清单

对仓库根目录进行只读检查：

git -C . rev-parse --is-inside-work-tree 2>/dev/null   # is this a git repo at all?
git log --oneline -1 2>/dev/null                        # any commits yet?
git branch -a                                           # does develop/main exist?
ls -A                                                    # what is at the root?

然后检查以下信号。

1. 是否存在应用代码？ 包含真实、非样板代码的源代码目录（src/、app/、lib/、pkg/ 等）。
2. 依赖/构建清单？ package.json、pnpm-lock.yaml、pom.xml、build.gradle、go.mod、requirements.txt/pyproject.toml、Cargo.toml、*.csproj、Gemfile 等。
3. Git 历史？ 零次提交/空树，还是有实际历史记录。
4. 是否已存在 incu-way？ 引用了 incu-way 工作流的 CLAUDE.md、.ways/ 目录或 docs/architecture/。
5. 分支模型？ main 和 develop 是否已存在。

仓库分类

• 绿地项目 — 空仓库或近乎空仓库（尚无应用代码；可能只有 README 或许可证）。工作是记录意图：产品愿景和团队计划构建的架构。
• 棕地项目 — 包含代码且有历史记录的现有应用（默认假定为此类）。工作是逆向梳理并建立认知：记录架构，并在适当时记录现有功能行为。
• 已初始化 — 已存在 incu-way 结构。切换到刷新模式：补齐缺失内容、更新过时章节，并在棕地项目中重新执行文档梳理。

Phase 0 完成标准

进入 Gate 1 之前，Claude 应能说明：

• 仓库属于绿地、棕地还是已初始化
• 检测到的技术栈（语言、框架、包管理器、测试运行器、构建工具）——对于棕地项目，应根据清单文件和目录布局得出，而非凭空假定
• main 和 develop 是否存在（以及是否已初始化 git）
• 哪些 incu-way 部分已经存在，哪些仍缺失
• 拟定的初始化计划（要创建的文件、分支策略、文档深度）

不要猜测技术栈或产品用途。如果清单文件含义不明确，或仓库意图不清楚，将其记为 Gate 1 的待解决问题，而不是自行编造。

---

Gate 1 — 确认模式和范围

展示检测结果和拟定计划，然后向用户确认。

显示简短摘要：

## Initialization plan

- **Mode:** greenfield | brownfield | refresh
- **Detected stack:** {languages / frameworks / package manager / test runner}
- **Branch model:** {exists: main, develop} | {will create: main, develop}
- **Will create / update:**
  - CLAUDE.md (from template, filled with the detected stack)
  - PRD.md (root) — {product vision (greenfield) | reverse-engineered overview (brownfield)}
  - docs/ tree: prds/, bugs/, security/, architecture/
  - .ways/ (work-item state.json lives here later)
- **Documentation depth (brownfield):** {structural only | architecture | architecture + functional}
- **Open questions:** {anything ambiguous about stack or product intent}

• 询问：“这是初始化计划。请在我创建任何内容之前，确认模式和文档深度。”
• 停止。用户确认模式和范围之前不要继续。

不要将仓库检测本身视为获得搭建许可。Gate 1 用于确定模式和文档深度。

---

隔离设置（紧接 Gate 1 之后）

在写入任何文件之前，确定分支模型，并询问用户希望如何隔离初始化工作：

你希望我在当前检出中创建新分支，还是创建单独的 git worktree？

严格按照用户的回答执行。 提问后立即停止；在用户选择之前，不要创建分支或 worktree。

如果当前检出存在未提交的更改，在切换分支或创建 worktree 之前停止并询问。

全新项目，尚未使用 git

除非用户明确要求在 git 初始化后使用单独的 worktree，否则在当前检出中使用分支。此仓库尚无提交，因此没有提交就无法存在 main/develop——请先询问：“此仓库尚无提交。可以创建一个空的初始提交来建立 main 吗？” 仅在用户确认后：

git init
git checkout -b main
git commit --allow-empty -m "chore: initial commit"
git checkout -b develop
git checkout -b chore/incu-way-init

已有项目（已存在 git）

如果缺少 develop，则需要从 main 创建它（这是整个仓库范围的决定——如果此前尚未确认，请在 Gate 1 确认），并推送，使其存在于远程仓库。请先询问：“develop 目前不存在。可以从 main 创建它并推送吗？” 仅在用户确认后：

git checkout main && git checkout -b develop && git push -u origin develop   # only if develop is missing

选项 A — 在当前检出中创建分支

# Run from the repo root
git switch develop
git pull --ff-only
git switch -c chore/incu-way-init

所有后续工作——CLAUDE.md、文档、.ways/ 脚手架、提交——都在当前检出中的此分支上进行。切勿直接写入 develop 或 main。

选项 B — 单独的 worktree

仅在 .worktrees/ 下创建 worktree。不要询问用户要使用什么路径。

# Run from the repo root
git fetch origin develop
mkdir -p .worktrees
git worktree add .worktrees/incu-way-init -b chore/incu-way-init origin/develop

所有后续工作——CLAUDE.md、文档、.ways/ 脚手架、提交——都只能在此 worktree 内进行。切勿直接写入 develop 或 main。

---

阶段 2 — 搭建 incu-way 结构

目标： 创建 incu-way 工作流所依赖的文件和目录，并填入真实的检测结果（如果仓库中已有答案，就不要使用占位内容）。

2.1 — CLAUDE.md

将此技能附带的 claude.template.md（它与此 SKILL.md 位于同一目录，因此会随技能一起通过 ways add 移动）复制到仓库根目录，命名为 CLAUDE.md，并根据阶段 0 检测到的信息填写所有 [TODO: ...]：

• 关于项目 — 对于已有项目，根据 README、清单文件和代码提炼；对于全新项目，根据 Gate 1 记录的用户愿景填写。
• 技术栈 — 语言、框架、数据库、测试、包管理器（根据检测结果填写）。
• 文件夹结构 — 列出实际的顶层布局，并为每项写明一行用途。
• 代码规范 — 对于已有项目，根据现有配置（.eslintrc、.editorconfig、tsconfig.json、代码检查工具、格式化工具）推断；对于全新项目，使用模板默认值。
• 常用命令 — 从清单文件的脚本中读取（package.json 的 scripts、Makefile、pom.xml 等）。不要编造不存在的命令。
• 必须严格按照模板定义保留 Security、Worktree、Development workflow 和 Bug workflow 部分。

任何无法推导的信息，都应保留为明确的 [TODO: ...]，并在 Gate 2 列出——不要捏造。

2.2 — PRD.md（根目录）

incu-way 工作流会在阶段 0 中首先读取 PRD.md。请创建此文件：

• 全新项目： 记录 Gate 1 确定的产品愿景——问题、目标用户、目标、非目标及预期的高层架构。
• 已有项目： 编写一份逆向梳理的产品概览——应用目前的功能、目标用户及主要能力，且内容应能追溯到代码。如果 incu-way-docs 在范围内（见阶段 3），此处可以简要指向 docs/architecture/ 和功能文档，并有意保持精简。

2.3 — docs/ 树和 .ways/

创建各流程写入内容的目录结构：

docs/
  prds/          # incu-way-development writes here
  bugs/          # incu-way-bugs writes here
  security/      # snyk-remediation writes here
  architecture/  # incu-way-docs writes here (brownfield)
.ways/       # work-item state.json lands here later (add a .gitkeep)

在空目录中添加 .gitkeep，以便将它们提交到版本库。此处不要创建 .ways/state.json——它属于工作项流程。

.ways/ 是 way 状态（ways/v1alpha1）的规范根目录。如果项目也使用 ways CLI，该工具会在 .ways/cache/ 下保留一个缓存——请参阅下文的版本库清理规范。

2.4 — 版本库清理规范

始终确保 .gitignore 包含以下条目（追加缺失的条目；不要重复已有条目）：

.claude/
.agents/

.claude/ 和 .agents/ 存放 skills.sh/hooks.sh 的放置输出（以及 .claude/ 中 Claude Code 自己的本地设置）——其中所有内容都由 ways install 根据 ways.lock / skills-lock.json / steering-lock.json 重新生成，因此和 node_modules 一样可以随时丢弃：绝不要提交，也绝不要在忽略它们之前征求确认。

仅在与此项目相关时：

• 如果 .worktrees/ 位于版本库中且尚未被忽略，则将它添加到 .gitignore。
• .ways/ 忽略规则。 .ways/state.json 必须保持受版本控制（按分支恢复 和看板都依赖它通过 incu-way-prepare-pr 提交）。如果正在使用 ways CLI，只忽略它的缓存——将 .ways/cache/（而非整个 .ways/）添加到 .gitignore。绝不要一概忽略 .ways/。
• 如果项目使用流程中提到的 SonarQube 扫描，请注明 run-sonar.sh 的位置，或说明它仍为 TODO——不要编造脚本。

告知用户脚手架已就绪，并建议调用 incu-way-prepare-pr 提交它——不要自行提交：

Suggested message: chore(incu-way-init): scaffold CLAUDE.md, docs/ tree and .ways/

---

Phase 3 — 应用文档

目标： 编写架构文档（以及在必要时编写功能文档），帮助人们和 incu-way 流程理解应用。

棕地项目 — 调用 incu-way-docs

如果在 Gate 1 商定的文档深度为架构或架构 + 功能，则交由 incu-way-docs 技能处理，并指示它写入当前初始化分支/工作树（无需单独的 PR——其输出会随此初始化 PR 一并交付）。 incu-way-docs 会根据应用规模生成：

• docs/architecture/——概览、组件、数据模型、集成、部署/运维
• 功能/领域文档和术语表（当应用面向用户或领域内容较多时）
• Mermaid 图表（已验证）

如果商定的深度仅为结构层面，则跳过深入梳理——目前 CLAUDE.md 中的文件夹结构和 PRD.md 概览已足够。在 PRD.md 中注明深入文档工作暂缓，之后可以通过 incu-way-docs 生成。

绿地项目 — 记录预期架构

没有代码可供反向工程。应改为在 docs/architecture/overview.md 中记录意图：计划采用的架构、主要组件、关键技术选型及其理由（ADR 风格）。保持轻量；随着代码通过 incu-way-development 编写，这些内容也会不断演进。

---

Gate 2 — 检查初始化结果

完成脚手架搭建（以及适用时的文档编写）后：

• 总结创建/更新的内容，并列出 CLAUDE.md 中所有剩余的 [TODO: ...] 和任何未解决的问题。
• 说："初始化已在 chore/incu-way-init 上完成。CLAUDE.md、PRD.md、docs/ 树和 .ways/ 均已就绪{，另含架构/功能文档}。请先审阅，然后我再创建 PR。"
• 停止。未经用户批准，不要创建 PR。

---

Phase 4 — 通过 Pull Request 合并

目标： 通过经过审查的 PR 将初始化内容合并到 develop（然后合并到 main）。 绝不要直接合并。

PR

通过 Gate 2 审批后，建议调用 incu-way-prepare-pr，推送 chore/incu-way-init（如果仓库尚无远程仓库或历史记录，还需首次推送 main/develop），并创建 PR。不要自行推送或运行 gh pr create。

建议 incu-way-prepare-pr 使用的 PR 标题/正文：

Title: chore: initialize incu-way

PR 正文必须包含：

• 模式： greenfield / brownfield / refresh。
• 已创建/更新： CLAUDE.md、PRD.md、docs/ 树、.ways/，以及（如有）带链接的架构/功能文档。
• 待处理事项： 剩余的 [TODO: ...] 和团队尚待讨论的问题。

PR 创建后，将 PR URL 告知用户。停止。未经用户批准，不要合并。

如果团队也要求通过 main 的门禁，则在第一个 PR 合并后，按照开发流程创建后续 PR develop → main。

---

快速参考 — 门禁

门禁	触发条件	应说的话	暂停，直到
1	检测到模式和计划	“这是初始化计划。请确认模式和文档深度。”	用户确认
2	脚手架（及文档）已就绪	“已在 chore/incu-way-init 上完成初始化。请在我创建 PR 前进行审核。”	用户批准
3	已审核	建议使用 incu-way-prepare-pr 创建 PR chore/incu-way-init → develop；用户运行后分享 URL	用户批准 PR

---

不要做的事

以上阶段级规则具有最高权威；唯一未在其他地方说明的一点是：

• greenfield/brownfield 引导命令是唯一不适用禁止自动提交规则的例外，而且执行前仍须先征求同意——其他操作（脚手架提交、PR）都只能通过 incu-way-prepare-pr 完成。