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

在新项目初始化 ACK

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

前提与边界

开始前确认：

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

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

初始化

在目标项目执行：

skiff init ack

或显式指定项目：

skiff init ack --project <project-root>

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

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

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

完善项目覆盖层

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

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

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

完善任务板

编辑 docs/ack/tasks.yaml：

• ackVersion 使用 ACK Skill 的 VERSION。
• updatedAt 使用当前带时区时间。
• project.name、repoPath、devWorktree 和 overlayFile 使用真实值。
• 非服务项目的 baseUrl 写为 n/a。
• 没有真实任务时使用 tasks: []，不要保留或虚构示例任务。

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

校验

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

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

同时确认：

• project.md 和 tasks.yaml 没有未替换的 <...> 占位符。
• project.overlayFile 指向真实文件。
• Developer 与 Test 的验证命令可执行。
• 网站或 API 项目写清服务启动、重启和 Base URL。

初始化报告

完成后报告：

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

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