.pouch/skills/ack/references/init-new-project.md

在新项目初始化 ACK

本文件说明如何把 ACK 的项目状态初始化到目标项目。ACK Skill 自身已经通过 Agent 的 Skill 机制安装；项目不复制、不链接 Skill 内容。

前提与边界

开始前确认：

1. 目标项目根目录。
2. ACK Skill 已全局安装或安装到当前项目。
3. pouch 命令可用。

不要覆盖已有的 .pouch/ack/project.md、.pouch/ack/tasks.yaml、 .pouch/ack/knowledge.yaml、.pouch/ack/delivery.yaml、.pouch/ack/regression.yaml、 AGENTS.md 或其它 Agent 指令文件。ACK 不会自动 修改 AGENTS.md、CLAUDE.md 或其它 Agent 指令文件。不要把 token、.env 内容或其它私有配置写入 ACK 项目状态。

初始化

在目标项目执行：

pouch init ack

或显式指定项目：

pouch init ack --project <project-root>

命令从 ACK Skill 自带的 templates/ 生成：

.pouch/ack/
├── project.md
├── tasks.yaml
├── knowledge.yaml
├── delivery.yaml       # 默认 enabled: false
└── regression.yaml     # 默认 cases: []

如果任一目标文件已经存在，命令会拒绝覆盖。初始化过程不会创建 kit、 framework 或其它指向 Skill 的软链接。

旧项目补充知识库

旧项目已经有 project.md 和 tasks.yaml、但没有 knowledge.yaml 时，不要重跑 pouch init ack。先检查现有文件并向用户报告缺失项；用户授权后，只从 templates/knowledge.template.yaml 生成 .pouch/ack/knowledge.yaml，替换项目名和 当前时间，保留 entries: []。如果现有任务板缺少 project.knowledgeFile，同一次授权只补 knowledgeFile: .pouch/ack/knowledge.yaml，不改写其它项目状态。生成后运行任务板、 知识库和跨文件引用校验。

旧项目补充交付配置

delivery.yaml 对旧项目是可选能力；缺少它不会影响三角色开发与验证闭环。只有用户 明确要求配置项目交付时，才从 templates/delivery.template.yaml 生成文件，同时在 任务板补 project.deliveryFile: .pouch/ack/delivery.yaml 与顶层 deliveryRuns: []。首次生成保持 enabled: false，按 delivery.md 展示并确认 解析结果后才启用。不要重跑 pouch init ack，也不要改写已有任务或知识。

旧项目补充回归目录

regression.yaml 对旧项目是可选能力。用户明确要求回归或授权补齐时，从 templates/regression.template.yaml 生成 .pouch/ack/regression.yaml，并只补 project.regressionFile: .pouch/ack/regression.yaml 与顶层 regressionRuns: []。 保持 cases: []，不要从聊天虚构用例。

完善项目覆盖层

编辑 .pouch/ack/project.md，填入：

• 项目名、技术栈、运行命令和 Base URL。
• Coordinator、Developer、Test 的实际模型档位。
• 规格、集成测试、源码、单元测试和私有配置的路径权限。
• Developer 白盒验证命令。
• Test 黑盒复测命令。

无法从项目证据确定的值写为 n/a，不要猜测。

完善任务板

编辑 .pouch/ack/tasks.yaml：

• ackVersion 使用 ACK Skill 的合法 SemVer VERSION；从 0.10.0 起 project.orchestration 与顶层 workerReceipts 必须同时存在。
• 从 0.11.0 起的新项目初始化包含默认关闭的交付契约；旧项目不要求为了版本号升级 自动补交付配置。
• updatedAt 使用当前带时区时间。
• project.name 使用真实值；overlayFile 和 knowledgeFile 使用项目内相对路径。 ACK 从命令行 --project-root 下固定的 .pouch/ack/ 布局解析项目状态，不把 repoPath 或 devWorktree 绝对路径写入任务板。旧任务板中的这两个字段仅兼容读取， 不再参与路径绑定。
• 新项目的 project.deliveryFile 固定为 .pouch/ack/delivery.yaml，并保留顶层 deliveryRuns: []。旧项目只有在采用交付能力时才补这两个字段。
• 新项目的 project.regressionFile 固定为 .pouch/ack/regression.yaml，并保留顶层 regressionRuns: []。旧项目只有在采用回归能力时才补这两个字段。
• allowedWorktrees 已废弃（v0.19 起），新任务板不生成该字段；worker 默认在 --project-root 工作。模型 allowlist、profiles 和 defaults 使用项目实际允许值。 不要把完整启动命令、extraArgs、env 或任意 executable 写进任务板。
• 非服务项目的 baseUrl 写为 n/a。
• 没有真实任务时使用 tasks: []，不要保留或虚构示例任务。

每个真实任务的验收必须是可观测信号，例如可见文本、API 状态和字段，或明确的交互 结果；不要只写“功能正常”。

初始化项目知识

新项目的 .pouch/ack/knowledge.yaml 保持 verificationRegistry: {} 与 entries: []。不要从聊天、README、issue 或单次失败中猜测并激活知识。

项目运行 ACK 后，Developer 和 Test 可以通过回报提名 knowledgeCandidates； candidate 留在任务证据中，不会被派发。只有 Test 独立验证且 Coordinator gate 通过后，Coordinator 才能把它写成 active 条目。全项目范围的强制或权限类规则 还需要 User / Decision Owner 确认。

知识条目只引用项目已审查的 verification.ref。对应入口保存在 knowledge.yaml.verificationRegistry，只允许仓库内相对 path 和结构化 args， 不保存或自动执行自由 shell 命令。需要执行时只把 registry ID 交给 <ack-skill-dir>/scripts/run_verification.py，不直接运行 path/args。关键约束应 最终下沉为测试、lint、CI 或正式规范。

初始化项目交付

新项目的 .pouch/ack/delivery.yaml 保持 enabled: false、空能力表、空 profile，以及 intents.testEnvironment: null 与 intents.release: null。 不要根据 README 或 CI 自动推断并启用发布/部署。用户说明测试环境后，Coordinator 把 intents.testEnvironment 写成 {via: deployer, env: <env>}，若 .pouch/deployer/<env> 尚未就绪则加载 deployer skill 的「初始化」；发版仍指向 profile。ACK 初始化不自动跑 deployer 初始化。 配置中不保存 shell、环境变量值或凭据正文；稳定发布和生产部署必须有显式 approval 步骤。

初始化回归目录

新项目的 .pouch/ack/regression.yaml 保持 cases: []。不要从 README 或聊天猜测 用例。任务 verified 后按 regression.md 收获。

校验

Agent 从当前 SKILL.md 解析 ACK Skill 目录后运行：

python3 <ack-skill-dir>/scripts/validate_tasks.py .pouch/ack/tasks.yaml
python3 <ack-skill-dir>/scripts/validate_knowledge.py .pouch/ack/knowledge.yaml --tasks .pouch/ack/tasks.yaml
python3 <ack-skill-dir>/scripts/validate_delivery.py .pouch/ack/delivery.yaml \
  --tasks .pouch/ack/tasks.yaml --project-root <project-root>
python3 <ack-skill-dir>/scripts/validate_regression.py .pouch/ack/regression.yaml \
  --tasks .pouch/ack/tasks.yaml

同时确认：

• project.md、tasks.yaml、knowledge.yaml、delivery.yaml 和 regression.yaml 没有未替换的 <...> 占位符。
• project.overlayFile 指向真实文件。
• project.knowledgeFile 指向 .pouch/ack/knowledge.yaml。
• 新项目的 project.deliveryFile 指向 .pouch/ack/delivery.yaml；交付默认关闭。
• Developer 与 Test 的验证命令可执行。
• project.orchestration 的 profile/allowlist/defaults 通过校验，自动模式只允许 read-only 或 workspace-write；旧任务板未迁移时保持手动模式。
• 顶层 workerReceipts 和 dispatch.developer/test 的 task/role/profile/attempt 引用一致；receiptId 与 attemptId 同时为空或同时填写。持久 receipt 只作审计， 不能单独授权复用旧终端；复用还需要空闲状态、身份匹配和可信历史清理证明。
• 网站或 API 项目写清服务启动、重启和 Base URL。
• 任务中的固定 revision knowledgeRefs 都能解析，非 active 条目没有被派发。

初始化报告

按 SKILL.md「初始化」最后一步的格式报告（## ack 初始化：完成 | 部分完成 | 阻塞）， 列出已具备项、待配置项（路径 + 字段 + 示例）、工具链和下一步。

只有结构校验通过且必填项目事实完整时才称「完成」；否则称「部分完成」或「阻塞」。 除非用户明确要求，不提交、不推送。