feat: rename skills/skiff to pouch and move ACK state under .pouch

Use ~/.pouch, the pouch CLI, and .pouch.yaml as the SSOT container.
Keep the inner skills/ packages, and store ACK project state in
.pouch/ack instead of docs/ack.
This commit is contained in:
2026-08-25 15:20:02 +08:00
parent ee31278947
commit f3cd56b78e
83 changed files with 1265 additions and 1192 deletions
+23 -23
View File
@@ -9,10 +9,10 @@
1. 目标项目根目录。
2. ACK Skill 已全局安装或安装到当前项目。
3. `skiff` 命令可用。
3. `pouch` 命令可用。
不要覆盖已有的 `docs/ack/project.md``docs/ack/tasks.yaml`
`docs/ack/knowledge.yaml``docs/ack/delivery.yaml``AGENTS.md` 或其它 Agent
不要覆盖已有的 `.pouch/ack/project.md``.pouch/ack/tasks.yaml`
`.pouch/ack/knowledge.yaml``.pouch/ack/delivery.yaml``AGENTS.md` 或其它 Agent
指令文件。ACK 不会自动
修改 `AGENTS.md``CLAUDE.md` 或其它 Agent 指令文件。不要把 token、`.env`
内容或其它私有配置写入 ACK 项目状态。
@@ -22,19 +22,19 @@
在目标项目执行:
```bash
skiff init ack
pouch init ack
```
或显式指定项目:
```bash
skiff init ack --project <project-root>
pouch init ack --project <project-root>
```
命令从 ACK Skill 自带的 `templates/` 生成:
```text
docs/ack/
.pouch/ack/
├── project.md
├── tasks.yaml
├── knowledge.yaml
@@ -47,24 +47,24 @@ docs/ack/
### 旧项目补充知识库
旧项目已经有 `project.md``tasks.yaml`、但没有 `knowledge.yaml` 时,不要重跑
`skiff init ack`。先检查现有文件并向用户报告缺失项;用户授权后,只从
`templates/knowledge.template.yaml` 生成 `docs/ack/knowledge.yaml`,替换项目名和
`pouch init ack`。先检查现有文件并向用户报告缺失项;用户授权后,只从
`templates/knowledge.template.yaml` 生成 `.pouch/ack/knowledge.yaml`,替换项目名和
当前时间,保留 `entries: []`。如果现有任务板缺少
`project.knowledgeFile`,同一次授权只补
`knowledgeFile: docs/ack/knowledge.yaml`,不改写其它项目状态。生成后运行任务板、
`knowledgeFile: .pouch/ack/knowledge.yaml`,不改写其它项目状态。生成后运行任务板、
知识库和跨文件引用校验。
### 旧项目补充交付配置
`delivery.yaml` 对旧项目是可选能力;缺少它不会影响三角色开发与验证闭环。只有用户
明确要求配置项目交付时,才从 `templates/delivery.template.yaml` 生成文件,同时在
任务板补 `project.deliveryFile: docs/ack/delivery.yaml` 与顶层
任务板补 `project.deliveryFile: .pouch/ack/delivery.yaml` 与顶层
`deliveryRuns: []`。首次生成保持 `enabled: false`,按 `delivery.md` 展示并确认
解析结果后才启用。不要重跑 `skiff init ack`,也不要改写已有任务或知识。
解析结果后才启用。不要重跑 `pouch init ack`,也不要改写已有任务或知识。
## 完善项目覆盖层
编辑 `docs/ack/project.md`,填入:
编辑 `.pouch/ack/project.md`,填入:
- 项目名、技术栈、运行命令和 Base URL。
- Coordinator、Developer、Test 的实际模型档位。
@@ -76,7 +76,7 @@ docs/ack/
## 完善任务板
编辑 `docs/ack/tasks.yaml`
编辑 `.pouch/ack/tasks.yaml`
- `ackVersion` 使用 ACK Skill 的合法 SemVer `VERSION`;从 `0.10.0`
`project.orchestration` 与顶层 `workerReceipts` 必须同时存在。
@@ -84,10 +84,10 @@ docs/ack/
自动补交付配置。
- `updatedAt` 使用当前带时区时间。
- `project.name` 使用真实值;`overlayFile``knowledgeFile` 使用项目内相对路径。
ACK 从命令行 `--project-root` 下固定的 `docs/ack/` 布局解析项目状态,不把
ACK 从命令行 `--project-root` 下固定的 `.pouch/ack/` 布局解析项目状态,不把
`repoPath``devWorktree` 绝对路径写入任务板。旧任务板中的这两个字段仅兼容读取,
不再参与路径绑定。
- 新项目的 `project.deliveryFile` 固定为 `docs/ack/delivery.yaml`,并保留顶层
- 新项目的 `project.deliveryFile` 固定为 `.pouch/ack/delivery.yaml`,并保留顶层
`deliveryRuns: []`。旧项目只有在采用交付能力时才补这两个字段。
- `allowedWorktrees` 已废弃(v0.19 起),新任务板不生成该字段;worker 默认在
`--project-root` 工作。模型 allowlist、profiles 和 defaults 使用项目实际允许值。
@@ -100,7 +100,7 @@ docs/ack/
## 初始化项目知识
新项目的 `docs/ack/knowledge.yaml` 保持 `verificationRegistry: {}`
新项目的 `.pouch/ack/knowledge.yaml` 保持 `verificationRegistry: {}`
`entries: []`。不要从聊天、README、issue 或单次失败中猜测并激活知识。
项目运行 ACK 后,Developer 和 Test 可以通过回报提名 `knowledgeCandidates`
@@ -116,7 +116,7 @@ candidate 留在任务证据中,不会被派发。只有 Test 独立验证且
## 初始化项目交付
新项目的 `docs/ack/delivery.yaml` 保持 `enabled: false`、空能力表、空 profile,以及
新项目的 `.pouch/ack/delivery.yaml` 保持 `enabled: false`、空能力表、空 profile,以及
`intents.testEnvironment: null``intents.release: null`
不要根据 README 或 CI 自动推断并启用发布/部署。用户用自然语言说明测试环境或发版
方式后,Coordinator 按 `delivery.md` 把两者都写入这一份契约:`intents` 指向对应
@@ -128,10 +128,10 @@ profile,工具 target 与仓库脚本分开引用。配置中不保存 shell
Agent 从当前 `SKILL.md` 解析 ACK Skill 目录后运行:
```bash
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
python3 <ack-skill-dir>/scripts/validate_delivery.py docs/ack/delivery.yaml \
--tasks docs/ack/tasks.yaml --project-root <project-root>
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>
```
同时确认:
@@ -139,8 +139,8 @@ python3 <ack-skill-dir>/scripts/validate_delivery.py docs/ack/delivery.yaml \
- `project.md``tasks.yaml``knowledge.yaml``delivery.yaml` 没有未替换的
`<...>` 占位符。
- `project.overlayFile` 指向真实文件。
- `project.knowledgeFile` 指向 `docs/ack/knowledge.yaml`
- 新项目的 `project.deliveryFile` 指向 `docs/ack/delivery.yaml`;交付默认关闭。
- `project.knowledgeFile` 指向 `.pouch/ack/knowledge.yaml`
- 新项目的 `project.deliveryFile` 指向 `.pouch/ack/delivery.yaml`;交付默认关闭。
- Developer 与 Test 的验证命令可执行。
- `project.orchestration` 的 profile/allowlist/defaults 通过校验,自动模式只允许
`read-only``workspace-write`;旧任务板未迁移时保持手动模式。