init-workspace

初始化工作区

将空仓库或现有仓库改造成适用于 Agent 工作流的仓库： 复制通用脚手架，然后根据此项目进行调整，而不是保留原始占位内容。

回合约定——结束前核对

✓ The adapted scaffold and repository-state ledger are written (or the merge/abort decision was asked) and remaining placeholders are listed
✓ Nothing was installed or overwritten without an explicit yes
✓ Artifact language: explicit user instruction > the project's declared docs language > English. The CONVERSATION language never decides — a Spanish prompt still produces English PRs/issues/commits/SPECs unless one of the first two says otherwise
✓ The closing `→ Next:` block is printed as the ABSOLUTE last output

准备结束回合时，是否还有未勾选的方框？如果有，回合就尚未完成——请先完成缺少的事项（弱模型容易遗漏文档末尾的任务；因此特意将此列表放在最前面）。

适用场景

• 设置仓库以使用这些技能，并希望根据项目调整文档基础结构（AGENTS.md + docs/ 地图 + 模板），而不只是复制过来。
• 如果希望通过访谈补全检查命令、架构和文档领域，请优先使用此方式，而不是静态运行 npx degit gtrabanco/agentic-workflow/template。

步骤 0 — 发现项目（始终首先执行）

在进行任何操作之前，检查目标目录（[target-dir]，默认为当前工作目录）：

• 是否已有Agent 指南（AGENTS.md 或旧版 CLAUDE.md）、docs/ 或 .github/？如果有，不要覆盖——先检查它是否为 agentic-workflow 脚手架（标记：存在 Agent 指南，且有 docs/features/ROADMAP.md 或 docs/workflow/ 目录）。如果两个标记都存在，默认提供升级选项，同时提供合并／就地调整／中止选项——参见下文的升级模式。如果存在 Agent 指南或 docs/，但没有这些标记（属于其他脚手架），则继续使用引导流程，并像之前一样询问合并／就地调整／中止。
• 根据清单文件（package.json、pyproject.toml、go.mod、Cargo.toml、Gemfile 等）检测技术栈，以便提出检查命令和命名约定。
• 记录 Git 状态（是否为仓库、默认分支是什么，以及远程 URL → 代码托管平台：github.com → GitHub/gh，gitlab → GitLab/glab，否则询问）。

渐进式加载——只能选择引导或升级，不能同时进行

参考资料的允许列表仅限于以下五个链接路径。绝不臆造或读取其他 references/ 路径。步骤 0 必须且只能选择一条路线：

**针对现有 Claude Code、Cursor、Copilot 或 OpenCode 脚手架的硬性规定：**仅加载 references/UPGRADE.md。缺少已提交的安全适配器属于升级工作，而不是缺少供应商原语。除非运行时平台完全没有对应的命名适配器，否则不要加载引导或可移植性资料。

• 空仓库／其他脚手架：阅读 引导发现，完成访谈，然后阅读引导写入。 发现和写入两条路线都要加载 SERENA 语言服务器，用于检测技术栈。
• 现有 agentic-workflow 脚手架：仅阅读升级。其仅允许增量添加的规则是绝对要求；不要重走引导流程。 升级路线会加载 SERENA 语言服务器，用于增量配置步骤。
• 检测到的运行时平台没有对应的命名适配器：仅在这种兜底情况下添加 可移植性。Claude Code、Cursor、Copilot 和 OpenCode 均为已命名的受支持适配器；适配器文件缺失时应通过升级修复，不应触发可移植性流程。

所有资源都与此文件处于同一层级。现有文件、钩子授权、安装授权和遗留项报告均为固定约定。缺少模板／迁移依据时，由所选路线报告，绝不可猜测补全。现有 OpenCode 脚手架如果仅缺少安全适配器，应严格只加载升级资料，跳过引导和可移植性流程。

防护原则

• 未经明确同意，绝不覆盖现有的 Agent 指南（AGENTS.md 或旧版 CLAUDE.md）或 docs/。
• 一份指南，一个名称。 AGENTS.md 是指南；旧版 CLAUDE.md 仅在升级模式下、经明确同意后才会停用，并且必须先将其中独有的内容合并到 AGENTS.md。使用的 Claude Code 版本早于 AGENTS.md 支持的用户可以保留它——这会作为遗留项报告，绝不会被视为需要修复的偏差。
• 仅允许增补，绝不覆盖（升级模式）。 升级模式只会添加项目缺少的区块，并填充原始占位符——绝不重写或删除项目已经定制的区块，即使当前模板也修改了该区块。真正的重新定制属于另行明确请求的就地调整引导流程，绝不会由升级模式自行执行。紧急程度标签的创建也遵循仅增补原则： 创建缺少的 urgent/fix-next 标签，绝不改动已有标签（包括项目已定制的名称、颜色或描述）。
• Serena 约定。 提交 .serena/project.yml；project.local.yml 和 cache 保留在本地。未经同意，绝不写入 .serena/ 配置。LSP 绝不验证文档——当某种文件类型的服务器未列出时会出现误报（markdown/yaml/json 永远不会自动检测）；列出的服务器若无法启动，则必须移除（项目中任一服务器失败都会禁用所有服务器）。文档验证应由脚本负责。
• 检索索引脚手架和 git 钩子须经同意后才能安装（AC22）。 索引组件——已提交的 .agentic-workflow/index.json 配置，以及三个保持索引最新的钩子（post-merge、post-checkout、post-rewrite，均将 index-sync.sh 安装到 .git/hooks/）——只有在明确回答“是否安装文档检索索引脚手架及其 git 钩子？”之后才会安装。未经同意：不安装任何内容，将其记录为遗留项（入口仍会在首次查询时运行并构建索引——钩子仅是快速更新途径），且后续访问时若未重新明确同意，绝不写入 .git/hooks/ 或配置。根据约定，钩子尽力执行（doc --sync --quiet，始终以 0 退出——快速更新途径绝不能破坏 git）。
• 绝不在此处重新定义紧急程度标签的词汇。 skills/triage-issue /SKILL.md 是 urgent/fix-next 名称、颜色和应用规则的唯一维护方——此技能只会在仓库中创建这两个标签；绝不引入第三个标签，也不改变这两个标签的含义。
• 仅搭建文档脚手架；不编写应用代码，不擅自安装依赖。
• 与架构无关：记录项目采用的模式，不强行指定模式。
• 对占位符如实说明，不虚构具体内容；标明仍需补充的部分。
• 存在项目的 工作流约定 后，遵守这些约定；对于现有仓库，不要在其默认分支上工作，也绝不在未获请求时提交或推送。

单元文档约定（自适应通道）

自适应通道（功能 61）以单元文档模型取代固定流水线。每个新单元都会在 docs/features/<NN>-<slug>/ 下生成一个 SPEC.md，包含 13 个章节：目标、原因、用户成果、 验收标准、非目标、未来成本、适用测试、已知的既存问题、任务、证据、进度日志、下一步、参考资料。

写入项目 AGENTS.md 的约定：

• 分诊：通道协调器（/unit-lane / workflow-status）返回确定性排序的步骤列表（研究、设计、规划、实施、 测试、证据、审查、文档、发布）。
• 防护措施：scripts/diff-guard.mjs 会在各个边界测量 git diff --stat；超出限制 → 必须重新分诊。防止钻空子：“绝不要通过删除 注释、空行、文档或测试来缩小差异。”
• 证据条目：每个 AC 一条 — 运行了什么、退出状态/摘要、输出（≤2 行）、 验证者。必须经过验证，而非仅声称完成。
• 进度日志：按每个已执行步骤记录带日期的条目（YYYY-MM-DD HH:MM）。
• 提交格式：type(scope): description（约定式提交）。
• 路线图状态：idea → defined → planned → in-progress → done。

这些内容由引导模式（新建）和升级模式（仅对尚未采用通道的安装进行增量添加）写入。尚未采用通道的项目只会获得：AGENTS.md 中的通道约定章节、docs/features/_TEMPLATE/ 下的单元文档模板，以及单元文档对应的 docs-map 行。

规范化的仓库状态

根据模板创建 docs/workflow/REPOSITORY_STATE.md。说明发现阶段会在规划前冻结证据，并且只有解析器会更新事实。

架构不变量

提供 docs/architecture/ARCHITECTURAL_INVARIANTS.md，作为可选的项目契约，用于记录长期架构规则。其条目必须注明稳定 ID、仓库证据，以及有权更改规则的主体。不要根据实现或功能 SPEC 推断规则。没有此文档的项目仍然兼容；在后续工作流产物中记录 n/a: no project invariants declared，而不是悄悄创建该文档。

可移植性

该脚手架不依赖特定厂商；只有钩子激活方式有所不同。如果检测到的 Agent 没有对应的适配器，请遵循 可移植性，并将其明确列为遗留项。受支持的 Claude Code、Cursor、Copilot 或 OpenCode 适配器不会加载此回退方案。

与其他技能的关系

• npx degit gtrabanco/agentic-workflow/template — 此技能适配的静态副本。想要原始脚手架并自行填充时，请使用它。
• docs/workflow/PORTABLE_PROMPT.md — 为项目重新生成经过适配的技能（行为）。此技能适配的是基础材料（文档）。二者相辅相成。
• 初始化后：discover-repository-state → workflow-status（查看哪些内容可以开始）→ /unit-lane（通道协调器）；运行 audit-docs 确认脚手架内容一致。

完成条件

• 目标项目中已存在量身定制的 AGENTS.md、docs/ 脚手架和 .github/ 模板；未使用的文件夹已清理，遗留占位符已标记，平台配套的审查技能已记录（并已提供），urgent/ fix-next 标签已创建（脚手架模式）或以增量方式完成协调（升级模式）；所有已接受的安全适配器均已激活并通过夹具测试 — 如果钩子 API/依赖不可用，则将其明确列为遗留项。 自适应通道约定（单元文档、分诊、目录步骤、防护措施、证据、提交格式）已写入 AGENTS.md。

• Serena 项目配置已完成初始化（或已说明未完成的原因并列为遗留项，且已运行健康检查）。

• 已打印结尾的 → Next: 块（并附上安装技能的提议）：

  → Next: /discover-repository-state — freeze repository evidence before planning
    · raw idea → /workflow-status → /unit-lane (the lane conductor)
    · next roadmap entry → /unit-lane (tridirection decides catalog steps)
    · confirm the scaffold is coherent → /audit-docs