在新项目初始化 ACK

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

前提与边界

开始前确认：

目标项目根目录。
ACK Skill 已全局安装或安装到当前项目。
skiff 命令可用。

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

初始化

在目标项目执行：

skiff init ack

或显式指定项目：

skiff init ack --project <project-root>

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

docs/ack/
├── project.md
├── tasks.yaml
└── knowledge.yaml

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

旧项目补充知识库

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

完善项目覆盖层

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

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

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

完善任务板

编辑 docs/ack/tasks.yaml：

ackVersion 使用 ACK Skill 的合法 SemVer VERSION；从 0.10.0 起 project.orchestration 与顶层 workerReceipts 必须同时存在。
updatedAt 使用当前带时区时间。
project.name、repoPath、devWorktree、overlayFile 和 knowledgeFile 使用真实值。
project.orchestration.allowedWorktrees 使用已核对的绝对 worktree；模型 allowlist、profiles 和 defaults 使用项目实际允许值。不要把完整启动命令、 extraArgs、env 或任意 executable 写进任务板。
非服务项目的 baseUrl 写为 n/a。
没有真实任务时使用 tasks: []，不要保留或虚构示例任务。

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

初始化项目知识

新项目的 docs/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 或正式规范。

校验

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

python3 <ack-skill-dir>/scripts/validate_tasks.py docs/ack/tasks.yaml
python3 <ack-skill-dir>/scripts/validate_knowledge.py docs/ack/knowledge.yaml --tasks docs/ack/tasks.yaml

同时确认：

project.md、tasks.yaml 和 knowledge.yaml 没有未替换的 <...> 占位符。
project.overlayFile 指向真实文件。
project.knowledgeFile 指向 docs/ack/knowledge.yaml。
Developer 与 Test 的验证命令可执行。
project.orchestration 的 profile/allowlist/defaults 通过校验，自动模式只允许 read-only 或 workspace-write；旧任务板未迁移时保持手动模式。
顶层 workerReceipts 和 dispatch.developer/test 的 task/role/profile/attempt 引用一致；receiptId 与 attemptId 同时为空或同时填写。持久 receipt 只作审计， v0.10 不自动复用旧终端。
网站或 API 项目写清服务启动、重启和 Base URL。
任务中的固定 revision knowledgeRefs 都能解析，非 active 条目没有被派发。

初始化报告

完成后报告：

创建或确认的三个项目文件。
检测到的技术栈和验证命令。
任务板和项目知识校验结果。
仍需用户补充的值。

只有结构校验通过且必填项目事实完整时才称“初始化完成”；否则称“部分完成”，并列出具体阻塞项。除非用户明确要求，不提交、不推送。

5.3 KiB Raw Blame History Unescape Escape