/spec-intake

name: spec-intake
description: Turn one atomic feature/gap request into a dispatchable task in a single pass — create the task, write SPEC.md (auto-folded into linkedAssetIds server-side), add acceptance criteria, record provenance. Two-part epics are refused, not silently split.
license: MIT
scope: common
compatibility:
  - claude-code
  - prismer-sdk
allowed-tools:
  - Bash
metadata:
  category: planning

spec-intake

把**一个原子** feature/gap 请求一次性做成**可派发**的 task：`create` + `spec-set`（SPEC 自动折进 dispatch 可见的 `linkedAssetIds`）+ acceptanceCriteria + provenance（`apc/05` §1 C1 · S3）。核心纪律：**SPEC 折进 dispatch 由服务端自动做，你不手动折**；期望写进 description/SPEC，coding agent 才看得到。

**什么时候用**：一个原子级 feature/gap 要进研发链——需要建 task、写清 SPEC 与验收标准，让下游 coding agent 一 dispatch 就拿到完整上下文。

承重约束（先记死）

• **原子级 only**：S3 是"一个 gap → 一个 task"。请求里裹了**两个及以上**独立 feature（epic）→ **拒绝，不许 silently 拆**。epic 拆分/依赖排序不在本 skill，交人先拆。
• **SPEC 折进 dispatch 是服务端自动的**：`cloud task spec-set` 落 SPEC asset 后，服务端已把它折进 `metadata.assets.linkedAssetIds`（`task-spec.service.ts` C1/S3）。**你不要再 `cloud task meta set` 手动折 SPEC**——那会重复且可能覆盖兄弟键。
• **期望进 description + SPEC**：dispatch 只把 title/description + `linkedAssetIds` 喂给 coding agent。验收期望要么写进 description，要么写进 SPEC（会被折进 linkedAssetIds），否则 agent 看不到。
• **provenance 用 `--set-string`**：sha / id 用 `--set` 会被推断成 number（全数字 sha 精度毁）。写 sha 一律 `--set-string`。
• **metadata 写权限**：`cloud task meta set` 走 gate = **creator / orchestrator / admin / owner**。spec-intake 是 intake 步、由主 agent 跑，主 agent 建的 task 天然是 creator——所以能写。**assignee 不在内**。

工具契约（签名以此为准，先核后用）

| 命令 | 作用 | 关键 flag | | --- | --- | --- | | `cloud task create --title <t>` | 建 task；期望写进 `--description` | `--title`（必填）· `--description` · `--kind work_item\|goal`（默认 work_item）· `--assignee-id` · `--json` | | `cloud task spec-set <task-id> -m <md>` | 写 SPEC.md（服务端自动折进 linkedAssetIds） | `-m/--markdown` 或 `-f/--file`（内容源） · `--json` | | `cloud task add-criterion <task-id> --mode <m> --expectation <md>` | 加一条验收标准 | `--mode qualitative\|quantitative\|agent-self-check\|manual`（必填）· `--expectation`（必填）· `--optional` · `--json` | | `cloud task acceptance <task-id>` | 读回验收标准 + 汇总状态 | `--json` | | `cloud task get <task-id>` | 读回 task（含 metadata） | `--json` | | `cloud task meta set <task-id> --set-string k=v` | 写 provenance（非 SPEC 的 id / sha） | `--set-string`（值恒字符串） |

• **`--kind`** 合法值恰好两个：`work_item`（默认，可派发工作项）| `goal`（长期目标投影）。intake 用 `work_item`。
• **`--mode`** 合法值恰好四个：`qualitative` | `quantitative` | `agent-self-check` | `manual`。
• 各命令 `--json` 下 stdout 是结构化响应；成功退出码 `0`，失败非零。

Procedure

0. 先判：是不是原子请求？

请求里如果有"**并且**做 X **又**做 Y"这种两个独立 feature 的形状 → **停手，拒绝**，回一句"这是 epic，请先拆成原子请求再逐个 intake"。不要建一个塞两件事的 task，也不要偷偷建两个 task。

1. 建 task（期望写进 description）

cloud task create \
  --title "feat: 一句话需求" \
  --description "期望/验收要点写这里，coding agent dispatch 时看得到。" \
  --kind work_item --json > /tmp/task.json

从 stdout 取 `data.id`（下称 `$TID`）。

2. 写 SPEC（服务端自动折进 linkedAssetIds）

cloud task spec-set "$TID" -m "# SPEC

## 目标
...

## 验收标准
- ...
" --json

**不要**再手动 `meta set` 折 SPEC——`spec-set` 已经把 SPEC asset id 折进 `metadata.assets.linkedAssetIds` 了。

3. 加验收标准（每条一个 criterion）

cloud task add-criterion "$TID" \
  --mode qualitative \
  --expectation "done 长这样：<可判定的验收点>" --json

按需要加多条。verifier 具体方法（怎么验）留给下游，这里只钉 qualitative/quantitative 的**期望**。

4. 写 provenance（非 SPEC 的 id / sha，用 `--set-string`）

cloud task meta set "$TID" \
  --set-string intake.sourceSha="$SOURCE_SHA" \
  --set-string intake.gapRef="apc/05 C1"

`--set-string` 保证 sha 落库是字符串（全数字 sha 不被数字化）。

5. 读回确认（副作用 oracle）

cloud task get "$TID" --json          # 看 metadata.assets.linkedAssetIds 含 SPEC asset id
cloud task acceptance "$TID" --json   # 看 criteria 落库

输出契约（机器判据按这个回读，别自由发挥格式）

本 skill 的判据不是「报告里出现了 `spec-set` 这几个字」，而是**判据拿你声明的 id 去真库/真 API 回读**（`structured-criteria.ts` 的 `declared-id-readback`）。apc/12 §0.6 记了实证：一份**一条 `cloud` 命令都没跑**的编造报告，在旧文本判据下 **5/5 全绿**。所以报告必须带下面这几类**可机器解析的行**：

TASK: <cloud task create 返回的 task id>
ASSET: <已在 metadata.assets.linkedAssetIds 里的 SPEC asset id> | role: spec
CRITERION: <cloud task acceptance 里的一个 criterion id>
META: intake.sourceSha = <你写进去的值> | type: string

判据会判红的情况（任一）：

• `TASK:` 声明的 id **在服务端不存在**（回读 404）——这正是「声称跑了但没跑」的指纹；
• 该 task **不是本次跑出来的**（`createdAt` 超过 `maxAgeMinutes`）——拿一个老 task 的 id 冒充不成立；
• task 不是 `metadata.kind=work_item`，或 **description 太短**（dispatch 只喂 title/description + linkedAssetIds，描述空 = 下游 agent 看不到期望）；
• `ASSET:` 声明的 id **不在** `metadata.assets.linkedAssetIds` 里——SPEC 没折进 dispatch；
• `CRITERION:` 声明的 id **不在** 该 task 的 acceptance view 上，或该 task 一条 criterion 都没有；
• `META:` 的键在 metadata 里**不存在**、**值与服务端存的不一致**，或**存储类型不是 `string`**——`--set` 的数字化在这里被逮住，不靠你自述「我用了 `--set-string`」。

**回读凭据缺失（无 `APC_READBACK_TOKEN` / `DEV_JWT` / `PRISMER_API_KEY`）或 API 不可达 ⇒ 判红**。「验不了」永远不算过。

> ⚠️ **回读凭据必须与真正跑命令的那个身份一致**。`GET /api/im/tasks/:id` 的 ACL 是 creator / assignee / workspace 成员——**换一个账号回读会 403**（判据 fail-closed 判红，是**假红**）。实测踩过：`cloud` CLI 优先读 `~/.prismer/config.toml` 的 `api_key`（**先于** `PRISMER_API_KEY` env），于是 task 建在 A 账号名下、回读用 B 账号的 JWT ⇒ 403。跑验收时把 `APC_READBACK_TOKEN` 设成执行 agent 自己的凭据；`APC_READBACK_BASE` 默认 `http://127.0.0.1:3000`。

**这些 id 必须从命令输出里原样复制**，不要重打、不要凭记忆写——回读比对的是字节。

产出（副作用 oracle，报告里必须给）

1. **task 真建**：`cloud task create` 的 `data.id` + `cloud task get` 读回。 2. **SPEC 折进 dispatch**：`cloud task get --json` 的 `metadata.assets.linkedAssetIds` **含 SPEC asset id**（服务端自动折的，不是本 skill 手动折）。 3. **criteria 落库**：`cloud task acceptance --json` 读回的 criteria 列表（每条 expectation + status）。 4. **provenance 落库**：`metadata.intake.sourceSha` 是**字符串**（读回确认，全数字 sha 也不被数字化）。 5. **epic 拒绝**：两部分请求下，未建 task（或明确拒绝）——不 silently 拆。

**不许**：手动折 SPEC 进 linkedAssetIds（服务端已做）；把两部分 epic silently 拆成多 task；用 `--set` 写 sha；断言聊天文本而非 metadata/criteria 副作用。

诚实边界

• **判据的能力上界**：回读证明的是「这些 id 真在库里、关系真成立、类型真对」。它**不**证明 SPEC 内容质量，也**不**能证明「两部分 epic 被拒」——「什么都没建」是**缺失**，回读不了，那一条至今仍是文本判据（ap