woostack-init

woostack-init

帮助用户创建或改进根目录 README 和项目指南，使其准确、贴合仓库、对决策有帮助、简洁且易于维护。先检查，再提问；先征求意见，再写入；保留有效内容，只应用请求授权的更改。重新运行可能不会产生任何更改。

命令和范围

/woostack-init [path]

默认意图是引导式文档编写，包括根目录 ARCHITECTURE.md。遵循仅限于一份文档、审查、规划或草稿的请求；仅涉及架构的请求不会编辑其他根目录文档。明确请求设置或修复本地支持（包括 Doctor 对缺失支持的引导）时，直接前往本地支持，无需先就文档进行沟通。同时请求这两类工作时，分别处理其授权和验证。

文档工作不需要 .woostack/、GitHub 政策验证、Doctor、GitHub 访问权限或依赖安装。缺少支持或无关的格式错误设置不得阻碍起草。仅在涉及相关支持工作时，才加载支持助手和契约。

引导式编写

1. 检查证据。 在不更改目标和请求范围的前提下，确认目标和请求范围。阅读相关对话中的决定、现有的根目录及作用域内 Agent 指令、README/贡献指南、产品/设计/架构文档及其规范来源、有代表性的源代码、入口点、清单、配置、脚本和 CI。 准备一份简短的开场摘要，说明目前的理解、需要创建、更新或保留哪些范围内的文档，以及哪些内容应保持不变。区分已观察到的实现、文档中表达的意图和拟议方向；发现矛盾时应明确指出，不要暗中择一。尊重现有指令的权威性和适用范围。 当验证指南与范围相关时，检查仓库实际使用的工具、命令、指令、CI、测试套件和可用的耗时证据，并区分已证实的瓶颈和未经测量的疑虑。若现有验证配置已足够，合理的做法可以是不作更改。
2. 起草前先咨询。 先以开场摘要开始讨论，然后结合仓库情况提问，并等待用户回复后再起草或编写任何文档，即使现有仓库看起来已很完善也不例外。一般性的初始化或更新文档请求，并不代表可以跳过这一步；常规编辑授权也不会自动免除咨询。对于一般任务，讨论与所请求文档相关的方面：意图（仓库为何存在、服务对象、应解决的问题、期望结果和非目标）、总体结构（主要应用、软件包、模块和文档的预期组织方式及职责；哪些现有安排是刻意为之且值得保留）、方向（近期优先事项、长期目标、产品和设计原则、约束与权衡）以及架构（预期边界、依赖关系、重要交互和数据流，以及仅凭源代码无法确定的理由）。这些是讨论主题，不是固定的问题清单：从仓库中读取事实细节，而不是要求用户盘点；应询问这些事实背后的意图和理由。范围受限的更新只咨询相关决定，不要把它变成与任务无关的全仓库访谈。 当 AGENTS.md 属于任务范围时，确认项目阶段和实际使用者、兼容性承诺（确认没有承诺时也要明确说明“无”），以及哪些数据/环境必须在变更后保留，或明确可丢弃。这些是彼此独立的决定：仅凭“尚未发布”的标签或 0.x 版本，既不能确认没有使用者，也不能认定数据可丢弃。除非用户明确要求更改，否则保留现有承诺；未解决的问题继续标记为未解决。使用 AGENTS.md 指南，将已确认的决定转化为可执行指令。 先提出一组适量的初始问题，然后等待回复。根据每次回复修正理解，并选择针对先前回答的后续问题，包括与从现有代码推断出的假设相矛盾的回答；应澄清影响、矛盾和有实际意义的未决选项，而非机械地按固定清单推进。重复利用用户已经提供的答案：如果先前的回答已确定相关事项，应陈述由此得出的理解，并询问还有哪些内容需要更改，而不是重新访谈。适当时提供建议和权衡；对实质性决定应明确标记为暂缓，不要臆断结论。绝不要在提出尚未得到回答的访谈问题的同一轮创建或修改文档。尊重用户明确要求不提问、直接推进的指示；Agent 自身有把握并不构成例外。若用户未回答，只能依据已观察到的证据起草，并将剩余决定标记为未解决，不得编造缺失事实。 提出验证建议时，遵循 测试原则：优先消除冗余工作并配置原生能力，而不是新增或替换工具。仅在确有必要时，依据当前权威生态来源调查选项；保留已确定且可行的选择，并比较兼容性、正确性、执行成本、迁移工作量和维护成本。明确区分当前配置、已同意的方向和尚未实施的建议；应说明权衡并进行验证，不要宣称未经测量的提速效果。
3. 起草聚焦的指南。 根据已达成一致的理解起草，明确区分当前实现、已同意的未来方向和暂缓决定，绝不要把提议或暂缓的架构表述为已经实现。产品 → 设计 → Agent 指令是有用的起草顺序，但并非强制。使用文档职责和适用的文档架构规范。补充缺失的指南，用有证据支持的内容替换空白或占位内容，或进行针对性修订，同时保留有价值的项目专属内容。 标明需要移除的过时、矛盾和重复内容，不要再叠加一层自动生成的内容。应链接到规范规格、架构决策、设计系统和贡献指南的权威来源，而非复制内容；替换既有文档前应先提出整合方案。绝不编造命令、指标、架构理由或已确定的决定。仓库清单和 CI 配置是已采用工具的权威依据。根据文档架构规范，记录已核实的命令是否存在、工作目录和执行条件；明确区分当前命令与拟议命令。保留作用域内的指令。
4. 审查有实质意义的变更并执行已授权的编辑。 展示拟议结果，并指出涉及产品方向、设计或架构约束以及 Agent 权限的变更。沿用已有授权；不要为单个标题或段落增设审批流程。仅供审查、仅起草或仅规划的请求不得写入任何内容。未经批准的范围扩展只能作为提议。 工具和验证建议依据边界仅供参考。 保留无关的现有工作、文件所有权以及既有文件/符号链接关系：编辑链接目标前，先核实其身份及授权；绝不要替换链接，也不要通过不安全或含义不明的路径写入。即使写入受阻，仍可展示草稿。
5. 在范围内验证。 检查适用的架构规范、受影响文档间的一致性、引用路径/链接，以及技术说法是否符合当前仓库证据。添加格式版本标记前，先验证格式；报告适用性限制和未解决的转换问题。按照请求和项目规则，执行相关且安全的检查；区分已检查的命令和实际执行的命令。 不要为了验证文字内容而运行无关的设置操作、网络操作或有副作用的命令。
6. 报告结果。 说明创建、更新、有意保留或因故未能处理的内容，提供验证证据，并列出未解决的决定。将尚未实施的建议、权衡和验证方案与当前配置及已同意的方向分开报告。对已有良好指南，不要为了追求文风新颖而重写。

文档职责

请使用当前适用的文档格式，不要采用详尽的模板，也不要为每个项目使用相同的问卷。省略不相关的章节。保留 DESIGN.md 已确立的、以架构为重点的含义；视觉规范不会取代它。

文档	目的	有用内容
README.md	这是一个什么项目？如何开始使用？	README 约定：有证据支撑的项目定位、经过验证的最简上手路径、具有代表性的用法，以及指向规范文档和政策的导航。
PRODUCT.md	我们要为谁构建什么？为什么？	产品记录：用户、目的、运行环境、功能、限制和已确认的原则。区分当前范围与未来方向。
DESIGN.md	产品应如何运作、呈现何种体验？	在适用时采用视觉格式：已观察到或达成共识的标识、设计令牌、组件和用法。若文档已负责记录规范的系统设计决策，则应予以保留。
ARCHITECTURE.md	变更应放在哪里，各部分如何交互，以及必须保留哪些边界？	技术概览：主要职责和路径、重要关系和流程、限制，以及有依据的决策链接。
AGENTS.md	Agent 应如何在此代码库中高效工作？	非版本化的操作性 Markdown：实际命令和工作目录、按条件执行的验证、边界、注意事项，以及指向更深入文档的链接。

保持 AGENTS.md 专注于操作：不要复制产品规范、罗列详尽的文件清单、提供通用编码建议，也不要重复 Woostack 工作流。当 AGENTS.md 也在授权范围内时，在适用处添加或完善指向 PRODUCT.md、DESIGN.md 和 ARCHITECTURE.md 的简短条件式指引。说明何时应查阅架构指南，例如在更改组件边界或跨组件流程之前；应使用链接，而不是复制内容，也不要假定这些文档会自动加载。在采用 Woostack 的过程中创建或更新 AGENTS.md 时，请在本地依据以下措辞编写一段简洁的可用性说明，并替换无条件要求使用或安装 Woostack 的表述：

Use woostack skills when available. At the start of work, `using-woostack` may load
project rules and route `/woostack-*` requests to the matching installed skill when it
is installed; it is an optional navigation aid, not a conduit. Each installed skill
carries its own activation, authority, approval, and completion behavior, so a missing
router or sibling skill must not block ordinary repository work. If woostack skills
are unavailable, follow this file and continue ordinary work with the host's available
capabilities; installation is not required. For an explicit `/woostack-*` command whose
skill is unavailable, name the missing skill and ask whether to install it or proceed
without it before continuing.

Follow this file first when it conflicts with generic agent defaults.

采用后的输出不得要求使用其他技能、访问源代码检出目录或依赖共享运行时。不要复制工作流目录，也不要将分范围的说明合并。

本地支持

仅在明确要求初始化/修复支持时使用此备用路径。此流程仅在本地运行，不依赖提供商，也不需要作出产品/设计决策或编辑文档。

1. 确定规范目标仓库，且不对其进行更改。核实仓库根目录、分支、工作状态、现有 .woostack/ 文件，以及冲突/符号链接/路径安全性。

2. 使用 scripts/config/resolve-config.sh 确定生效的本地策略。该脚本会合并受版本控制的 .woostack/config.json 与可选的主检出 .woostack/config.local.json，验证可选的规范 github 对象，并保留与之无关的用户自有设置。工件约定规定了配置字段、优先级、验证方式，以及对保留的旧版设置的保护。

3. 仅在所选支持范围内创建缺失的支持路径：

   • 根据 templates/config.json 创建 .woostack/config.json；
   • 为 Doctor、审计和 QA 创建本地诊断报告根目录；以及
   • 创建工作树约定声明的工作树/恢复支持文件。

   对现有支持内容提出的修复仅限于授权变更集内；不得覆盖用户自有设置。委派使用主机提供的 Agent；Init 绝不创建、验证或修复项目 Agent 定义。随附的 OMP 主机说明规定了可选的清理指导，适用于由旧版生成且未更改的定义。

4. 创建或修复支持内容后，使用 --check <target> 运行随附的非变更型支持检查器。这是本地流程，不是 Doctor 工作流。还要验证此次运行创建或修复路径的权限、报告根目录和交叉链接。若路径不安全、权限不符、存在冲突、规范配置格式错误、检查未完成，或受影响支持操作的恢复证据不完整，则必须安全失败；不得因此阻止无关的文档起草。

5. 准确报告已创建、已修复、已保留、已跳过和受阻的支持路径，并提供精确的验证结果。绝不推断 GitHub 所有者、Project、Status 字段、议题或发布目标；不联系提供商，也不选择远程持久化方式。

现有的 .woostack/tmp/runs/、旧版草稿、清单、锁、报告和远程记录均为历史用户数据。不得从中导入、重写、删除或重新创建包装器。工件约定规定了这些保护措施和可选的只读历史读取器；对于未知或不完整的结果，应在最后一个独立读取的边界处停止。

边界

Init 编写经授权的项目指导和明确要求的本地支持内容，不处理应用程序源代码或脚手架。工具建议仅供参考：Init 不安装软件包，不写入或更新任何软件包清单、锁文件或 CI 工作流，也不安排实现交接；实施这些建议仍需另行授权。Init 不创建议题、Project、分支、提交或拉取请求，也不创建生命周期状态；绝不推送、合并、读取/写入凭据、迁移保留数据或执行破坏性清理。Init 绝不创建用于会话命名的主机扩展或 .omp/。用户自有文件、旧版设置、保留记录、未提交更改的工作树和报告均保持不变。