القائمة
Use for PACEflow artifact fields and formats: task indexes, CHG/HOTFIX lifecycle operations, artifact-writer prompts, approvals, verification, and archive.
التثبيت باستخدام Codex أو Claude انسخ هذا Prompt والصقه في Codex أو Claude أو مساعد آخر ليراجع صفحة Skill ويثبّتها لك.
استنادا إلى تصنيف SOC المهني
Use for PACEflow-managed coding work: create, approve, resume, verify, close, or archive CHG/HOTFIX before project file edits.
Use for PACEflow internal full audit: run five independent review agents, verify evidence from code/tests/logs, de-duplicate findings, and produce a severity-ranked report for release gates or comprehensive code review.
Use for PACEflow knowledge/thoughts notes, finding-to-knowledge extraction, correction knowledge links, and Obsidian frontmatter/L0-L2 note structure.
Use to bridge a confirmed Superpowers/native plan into PACEflow CHG/HOTFIX artifacts, create artifact-writer prompts, and mark the specific plan as synced.
| name | artifact-management |
| effort | medium |
| description | Use for PACEflow artifact fields and formats: task indexes, CHG/HOTFIX lifecycle operations, artifact-writer prompts, approvals, verification, and archive. |
PACEflow 是 agent-driven artifact workflow。主 session 不直接 Write/Edit artifact；需要创建、更新、批准、验证、归档、记录 finding/correction 时，派 artifact-writer 执行。
artifact_dir 必须指向 hook 解析出的 artifact 根目录，只用于 PaceFlow artifacts：spec.md / task.md / walkthrough.md / findings.md / corrections.md / changes/**。
Project Root 是 PACEflow 管理边界；local artifact root 表示 Project Root 本地目录，不是当前子目录。普通子目录默认继承最近父级 Project Root；独立子项目先运行 set-project-root --mode independent，再选择 artifact root。
继续、恢复或收口已有 CHG/HOTFIX 前，先 Read 对应 changes/<id>.md，确认 ## 任务清单、实施详情和 ## 工作记录；SessionStart 摘要只用于定位，不替代详情文件。
如果用户已明确选择 vault/local 或自定义 artifact 目录但 artifact-root 配置还不存在，正确做法是先运行 hook 提示的 set-artifact-root helper（--choice vault、--choice local，或 --choice <绝对路径或相对 Project Root 路径>），再从目标项目 cwd 运行 reserve helper。helper 会写入权威 runtime 配置位置。.pace/artifact-root 只由 set-artifact-root helper 写入；git worktree 与继承父 Project Root 的子目录走宿主项目共享位置。reserve helper 接受自身文档列出的参数；自动化用 --cwd 指定项目 cwd，其余 artifact/root/project 路径由 helper 自行解析。
Helper 命令来源顺序的权威定义见 Skill(paceflow:pace-workflow)「Helper 命令来源」（本节不再复制）。速记：优先复制 SessionStart / PreToolUse 给出的完整命令；无 hook 输出但本 skill 已加载时以 skill 根目录拼 fallback（从 references/ 阅读时仍以 skill 根目录为基准）；不扫描 ~/.claude/plugins/cache 猜版本。按当前动作选择下面一条模板运行；这不是顺序执行清单：
node "<skill-root>/../../hooks/set-artifact-root.js" --choice local|vault
node "<skill-root>/../../hooks/reserve-artifact-id.js" --operation create-chg --cwd <项目 cwd>
node "<skill-root>/../../hooks/reserve-artifact-id.js" --operation record-correction --cwd <项目 cwd>
权威规范：
${CLAUDE_PLUGIN_ROOT}/agents/artifact-writer.md${CLAUDE_PLUGIN_ROOT}/agent-references/artifact-writer-spec.md${CLAUDE_PLUGIN_ROOT}/agent-references/instructions/*.mdArtifact root 文件：
| 文件 | 用途 | 活跃区内容 |
|---|---|---|
spec.md | 项目元数据与技术栈 | 项目事实 |
task.md | CHG/HOTFIX 唯一索引 | [[chg-id]] / [[hotfix-id]] 行 |
walkthrough.md | 完成记录索引 | 日期表格行 |
findings.md | finding 摘要索引 | `[[finding-id |
corrections.md | correction 摘要索引 | [[correction-yyyy-mm-dd-nn-slug]] 行 |
详情文件：
changes/
├── chg-yyyymmdd-nn.md
├── hotfix-yyyymmdd-nn.md
├── findings/finding-yyyy-mm-dd-slug.md
└── corrections/correction-yyyy-mm-dd-nn-slug.md
task.md、walkthrough.md、findings.md、corrections.md 只保留索引。任务清单、实施详情、工作记录、finding 详情、correction 详情都写入 changes/**。
spec.md 是项目事实文件，不是 artifact-writer 管理对象。技术栈、依赖、配置、目录结构或编码约定变化时，由主 session 用 Edit 增量同步已有 spec.md。它不含 ARCHIVE / APPROVED / VERIFIED / REVIEWED 标记，也不被 close-chg 或 archive-chg 修改。
CHG/HOTFIX 是连续执行、可验证、可关闭的最小变更单元，不是大计划容器。
T-NNN，但这些任务应服务于同一个闭环，并默认在一次执行流中完成。close-chg complete-open-tasks:true，它会把仍 open 的 T-NNN 统一收口为 [x]、写 VERIFIED、归档索引并写 walkthrough。update-status 不是逐步看板更新；只在暂停、阻塞、跳过、跨 session、长任务进度或多 CHG/worktree 可见性需要时使用。[-]，该 CHG 表示取消，frontmatter 使用 status: cancelled；随后派 archive-chg 做取消归档，把根索引移到 ARCHIVE 下方 [-]，不验证、不改为 archived。| 目标 | 操作 |
|---|---|
| 创建 CHG/HOTFIX | 派 artifact-writer，operation=create-chg |
| 批量创建一个 change-set 的 N 个 CHG | 先 reserve --count N，再一次 operation=create-chg batch（共享 change-set / change-set-total + N 个 --- CHG i/N --- 块） |
| 仅批准 C 阶段，暂不开始 | operation=update-chg，target=CHG-...，action=approve，需要 approval-confirmed: true + approval-source + approval-evidence |
| 批准并开始首个任务 | operation=update-chg，target=CHG-...，action=approve-and-start，需要 approval-confirmed: true + approval-source + approval-evidence + task-id |
| 暂停/阻塞/跳过/跨 session 时更新任务状态 | operation=update-chg，target=CHG-...，section=tasks，action=update-status，task-id=T-NNN；new-status=[!] 必须带 status-reason；全任务 [-] 表示取消 |
| 追加工作记录/实施说明 | operation=update-chg，target=CHG-...，section=work-record / implementation，action=append |
| 只记录 V 阶段暂不归档 | operation=update-chg，target=CHG-...，action=verify |
| 只记录 R 阶段暂不归档 | operation=update-chg，target=CHG-...，action=review |
| 归档 CHG/HOTFIX | operation=archive-chg，target=CHG-...；已取消 CHG 也用此操作做取消归档 |
| 最后任务验证审计后完成并归档 | operation=close-chg，target=CHG-...，需要 verification-confirmed: true + complete-open-tasks: true + review-confirmed: true（附 review-source / review-findings）+ implementation-notes（per-task 实施说明） |
| 记录 finding | operation=record-finding |
| 记录 correction | 先运行 reserve helper --operation record-correction --cwd <项目 cwd>，再派 operation=record-correction 并带 reserved-file-prefix |
| 重排索引（findings.md/corrections.md 活跃区改日期降序新→旧） | operation=update-index，target=findings.md/corrections.md，action=reorder |
action=approve 只完成 C 阶段，CHG 仍是 ready/deferred，不能据此写项目文件；只有 approve-and-start 或将任务恢复为 [/] 后才进入 E 阶段。[!] 表示 blocked/deferred：允许 Stop，但 Stop 会显示人可见提醒，恢复前不能继续写项目文件。
v5 时代布局（task.md 含活跃详情、无 changes/）的项目直接按当前流程派 create-chg——首次创建即建出 changes/**，v5 存量保持原样不迁移。Git worktree 场景下 artifact root 与 .pace 运行态使用宿主项目共享位置；普通子目录默认继承最近父级 Project Root；普通项目文件仍写当前 worktree/cwd。
以下内容只由 artifact-writer 写入，主 session 通过派遣 agent 完成：
<!-- APPROVED --> / <!-- VERIFIED --> / <!-- REVIEWED --> 标记由 update-chg / close-chg 写入verified-date 由 close-chg（或 update-chg action=verify）设置reviewed-date 由 close-chg（或 update-chg action=review）设置changes/<id>.md，task.md 只留 wikilink 索引changes/findings/<id>.md，findings.md 只留摘要索引close-chg / archive-chg 移动索引行并更新 frontmatter 完成复制模板时保留字段名，CHG-ID 与 task-id 都用对应字段承载。
创建 CHG/HOTFIX：
artifact_dir: <hook 解析出的 artifact 目录>
operation: create-chg
execution-context: <reserve helper 输出>
reserved-id: <reserve helper 输出>
reserved-file-prefix: <reserve helper 输出（原样含 <slug>.md 占位，slug 由 artifact-writer 按 title 生成）>
title: <变更标题>
tasks:
- T-001: <任务标题与验收>
background: <Why>
scope: <What>
technical-decision: <How>
批量创建（batch create CHG，一个 change-set 的 N 个 CHG 一次落地）：
artifact_dir: <hook 解析出的 artifact 目录>
operation: create-chg
change-set: <变更集名>
change-set-total: <N，必须等于块数>
--- CHG 1/N ---
reserved-id: <reserve --count N 输出的第 1 个>
title: <第 1 个 CHG 标题>
tasks:
- T-001: <任务标题与验收>
--- CHG 2/N ---
reserved-id: <第 2 个 reserved-id>
title: <第 2 个 CHG 标题>
tasks:
- T-001: <任务标题与验收>
（每块一个 reserved-id；artifact-writer 逐块建 N 个 CHG 并各写 change-set / change-set-seq: i/N；hook 对块数 / 字段 / reserved-id 做确定性前置校验。）
仅批准，暂不开始：
artifact_dir: <hook 解析出的 artifact 目录>
operation: update-chg
target: CHG-YYYYMMDD-NN
action: approve
approval-confirmed: true
approval-source: user-directive | ask-user-question | accepted-plan | prior-approved-plan
approval-evidence: <用户原话或已确认方案摘要>
批准并开始：
artifact_dir: <hook 解析出的 artifact 目录>
operation: update-chg
target: CHG-YYYYMMDD-NN
action: approve-and-start
task-id: T-001
approval-confirmed: true
approval-source: user-directive | ask-user-question | accepted-plan | prior-approved-plan
approval-evidence: <用户原话或已确认方案摘要>
恢复暂停/阻塞任务：
artifact_dir: <hook 解析出的 artifact 目录>
operation: update-chg
target: CHG-YYYYMMDD-NN
section: tasks
action: update-status
task-id: T-001
new-status: [/]
status-reason: <用户要求恢复或当前阻塞已解除>
验证后收尾归档（close-chg 折叠 VERIFIED + REVIEWED + 归档；R 审计是主 session 在派 close-chg 前完成的编排步骤，详见 Skill(paceflow:pace-workflow) R 小节）：
artifact_dir: <hook 解析出的 artifact 目录>
operation: close-chg
target: CHG-YYYYMMDD-NN
verification-confirmed: true
complete-open-tasks: true
review-confirmed: true
review-source: manual | <所选 review agent 名>
review-findings: <P0/P1/P2/P3 计数 + 各自处置（HOTFIX / won't-fix finding / record-finding 的 wikilink）>
verify-summary: <已运行并读取的验证结果>
implementation-notes:
- T-NNN: <该任务实际改动——改了哪些文件、关键实现、对应 commit>
walkthrough-summary: <完成摘要>
implementation-notes 是 close-chg 必填字段（与 verify-summary 同款内容字段），agent 据此把各任务实际改动写入 ## 实施详情 段 ### T-NNN 标题下——缺失会被 hook 拒绝。
只记录验证，暂不归档（不强制 implementation-notes；该字段在最终 close-chg 收口时必填）：
artifact_dir: <hook 解析出的 artifact 目录>
operation: update-chg
target: CHG-YYYYMMDD-NN
action: verify
verify-summary: <已运行并读取的验证结果>
只记录审计，暂不归档（已 verified 的 CHG 跑完 R 审计、但还不收口时用；对标 action=verify）：
artifact_dir: <hook 解析出的 artifact 目录>
operation: update-chg
target: CHG-YYYYMMDD-NN
action: review
review-confirmed: true
review-source: manual | <所选 review agent 名>
review-findings: <P0/P1/P2/P3 计数 + 各自处置 wikilink>
只归档已验证 CHG：
artifact_dir: <hook 解析出的 artifact 目录>
operation: archive-chg
target: CHG-YYYYMMDD-NN
walkthrough-summary: <完成摘要>
记录 finding：
artifact_dir: <hook 解析出的 artifact 目录>
operation: record-finding
title: <finding 标题>
summary: <≤200 字摘要>
type: research | observation | comparison | bug-report
impact: P0 | P1 | P2 | P3
body: <完整 Markdown 正文>
多条一次 batch：要一次记 N 条 finding（如 R 阶段批量路由 P2/P3 backlog），用共享头
finding-batch-total: N+ N 个--- FINDING i/N ---块（每块一套完整字段，无需 reserve 编号），省去逐条派遣的重复上下文重载；各块 title 须互异（避免 date-slug 文件名碰撞）。详见agent-references/instructions/record-finding.md「Batch 模式」。
用户纠正类记录使用 record-correction；record-finding 的 type 限于 research | observation | comparison | bug-report。
判定不修的 finding 一落地即 won't-fix：传 status: rejected + rejection-reason（≥10 字符）直接落 [-]（已决定不修的追踪记录，不注入 SessionStart，避免技术债污染上下文）；finding [-] 语义区别于任务跳过 [-] 与 CHG 取消 [-]。已记录的 finding 改判不修则派 update-finding status: rejected。
记录 correction：
artifact_dir: <hook 解析出的 artifact 目录>
operation: record-correction
reserved-id: <reserve helper 输出>
reserved-file-prefix: <reserve helper 输出（原样含 <slug>.md 占位，不替换 slug——slug 由 artifact-writer 按 title 生成）>
trigger-quote: <用户纠正原话>
wrong-behavior: <错误行为，至少 20 字符>
correct-behavior: <正确行为，至少 20 字符>
trigger-scenario: <触发场景>
root-cause: <根因>
knowledge-link: [[note]] 或 project-scope: project-only
更新已存在 finding（状态流转 / 回链 / 追加正文，record-finding 的对称操作）：
artifact_dir: <hook 解析出的 artifact 目录>
operation: update-finding
target: finding-yyyy-mm-dd-slug
status: accepted （枚举 open | investigating | accepted | rejected | merged | blocked；至少给 status / change-link / append 之一）
change-link: [[chg-yyyymmdd-nn]] （可选，与 accepted 搭配表示由该变更处置；won't-fix 用 status: rejected + rejection-reason 不带 change-link）
append: <可选，原样追加到详情正文末尾的 Markdown>
重排 findings.md / corrections.md 活跃区索引（按 date 降序，新→旧）：
artifact_dir: <hook 解析出的 artifact 目录>
operation: update-index
target: findings.md | corrections.md
action: reorder
<!-- APPROVED -->、<!-- VERIFIED --> 与 <!-- REVIEWED --> 只允许在 changes/<id>.md 内出现，三者三行相邻、自上而下：
- [x] T-002 验证任务
<!-- APPROVED -->
<!-- VERIFIED -->
<!-- REVIEWED -->
## 实施详情
verified-date 是机器权威，<!-- VERIFIED --> 是人读/hook 信号。两者必须同时存在或同时不存在。
<!-- VERIFIED --> 必须紧邻 <!-- APPROVED --> 下一行，中间不留空行。
与 V 阶段 verify/VERIFIED 完全同构。R 阶段对抗审计跑过后，由 close-chg（主路径）或 update-chg action=review（暂不归档）写入。
| 维度 | 内容 |
|---|---|
| 机器权威（单源） | frontmatter reviewed-date: YYYY-MM-DDTHH:mm:ss+08:00 |
| 人读 / hook 信号 | <!-- REVIEWED -->，紧邻 <!-- VERIFIED --> 下一行（无空行间隔） |
| 一致性约束 | 两者同时存在 ↔ 同时不存在；不一致即 format-violation |
| 顺序约束 | 仅在 <!-- VERIFIED --> 已存在时出现（先验证再审计）；未 verified 即出现 REVIEWED 即 format-violation |
派 close-chg 或 update-chg action=review 时必填三字段：
review-confirmed: true——主 session 已编排对抗审计并路由 findings 后传入，agent 以此字段为唯一依据折叠 REVIEWED（仿 verification-confirmed / approval-confirmed gating）。缺失 → missing-fields，非 true → format-violation。review-source——manual（主 session 自己瞄一眼）或所选 review agent / 棱镜名。review-findings——P0/P1/P2/P3 计数 + 各自处置（HOTFIX / won't-fix finding / record-finding 的 wikilink），并对每条「已修」finding 标注主 session 修前复核方式（如「X：主 session 读 file:line 确认」，留「复核发生过」纸面证据），写入 ## 审查记录 段（位于 ## 工作记录 之后）：## 审查记录
| 日期 | 审计来源 | findings |
| --- | --- | --- |
| <YYYY-MM-DD> | <review-source> | <P0/P1/P2/P3 计数 + 各自处置 wikilink> |
流程证据语义，非质量裁决：
<!-- REVIEWED -->只证"对抗审计这步跑过并记录了 findings 处置"，与<!-- APPROVED -->证"批准了"、<!-- VERIFIED -->证"验证跑了"同理，都不证明对应对象正确。审计的派发、findings 路由（开 HOTFIX / record-finding）是主 session 编排活（见 Skill(paceflow:pace-workflow) R 小节）；agent 只落reviewed-date+<!-- REVIEWED -->+## 审查记录三项证据，不验证 findings 真伪、不要求"修完"。
状态→checkbox 完整映射（CHG 六维状态机 + finding 状态机）的权威定义见 ${CLAUDE_PLUGIN_ROOT}/agent-references/artifact-writer-spec.md §4（本节不再复制）。速记：CHG 级 planned [ ] → in-progress [/] → completed [x]（活跃区，V/R 证据在此阶段折叠）→ archived [x]（ARCHIVE 下方）；cancelled [-]（ARCHIVE 下方，不验证）。任务级 T-NNN：[ ] 未开始 / [/] 进行中 / [x] 完成 / [!] 暂停或阻塞 / [-] 跳过。
CHG-YYYYMMDD-NN / HOTFIX-YYYYMMDD-NN：由 hook 原子预留。主路径是在派 artifact-writer create-chg 前先运行 SessionStart / PreToolUse 提示中的 reserve helper 完整命令；如果上下文没有完整命令，按上方 helper 命令来源从当前 skill 根目录拼出同版本绝对路径。普通 CHG 用 --operation create-chg --cwd <项目 cwd>；HOTFIX 用 --operation create-chg --cwd <项目 cwd> --type hotfix；批量创建一个 change-set 的 N 个 CHG 用 --count N 一次预留 N 个连号（仅 create-chg 支持）。create-chg --type 只支持 change / hotfix；finding/research 沉淀走 record-finding。同一 session 默认复用尚未消费的 create-chg reservation，若已预留普通 CHG 后要改建 HOTFIX，或确实要第二个新编号，加 --new。再把 helper 输出的 reserved-id / reserved-file-prefix 原样写入 Agent prompt。T-NNN：由 artifact writer 为当前 CHG/HOTFIX 分配的局部编号，写入 changes/<id>.md 的 ## 任务清单；不同 CHG 可以重复 T-001，后续操作用 target + task-id 定位。FINDING-YYYY-MM-DD-slug：详情在 changes/findings/。CORRECTION-YYYY-MM-DD-NN：由 hook 在派 record-correction 前原子预留；frontmatter 稳定 ID；详情文件名和 wikilink 追加 slug，格式为 changes/corrections/correction-yyyy-mm-dd-nn-slug.md。先按 helper 命令来源运行 reserve-artifact-id.js --operation record-correction --cwd <项目 cwd>，再把 helper 输出的 reserved-file-prefix 原样写入 Agent prompt。编号一律来自 helper 预留；task.md 只保留索引，无内嵌详情区可供推导。
创建变更：
先预留编号：
node "<SessionStart/PreToolUse 输出的 reserve-artifact-id.js 绝对路径>" --operation create-chg --cwd <项目 cwd>
# 若没有 hook 输出但本 skill 已加载：
node "<skill-root>/../../hooks/reserve-artifact-id.js" --operation create-chg --cwd <项目 cwd>
HOTFIX 预留：
node "<SessionStart/PreToolUse 输出的 reserve-artifact-id.js 绝对路径>" --operation create-chg --cwd <项目 cwd> --type hotfix
# 若没有 hook 输出但本 skill 已加载：
node "<skill-root>/../../hooks/reserve-artifact-id.js" --operation create-chg --cwd <项目 cwd> --type hotfix
若同一 session 已有未消费的普通 CHG reservation，但现在要创建 HOTFIX，或确实要新编号：
node "<SessionStart/PreToolUse 输出的 reserve-artifact-id.js 绝对路径>" --operation create-chg --cwd <项目 cwd> --type hotfix --new
# 若没有 hook 输出但本 skill 已加载：
node "<skill-root>/../../hooks/reserve-artifact-id.js" --operation create-chg --cwd <项目 cwd> --type hotfix --new
Correction 预留：
node "<SessionStart/PreToolUse 输出的 reserve-artifact-id.js 绝对路径>" --operation record-correction --cwd <项目 cwd>
# 若没有 hook 输出但本 skill 已加载：
node "<skill-root>/../../hooks/reserve-artifact-id.js" --operation record-correction --cwd <项目 cwd>
把 helper 输出放在 prompt 顶部，派遣字段按上方「最小字段模板」段组织——create / 批量创建 / 批准 / 批准并开始 / 恢复 / close / verify / review / archive / record 系全量模板见该段，本节不再复制。
连续执行的 CHG 由收尾的 close-chg 统一收口多个 T-NNN。close-chg 折叠 VERIFIED + REVIEWED + 归档；R 审计本身是主 session 在派 close-chg 前编排的步骤（见 Skill(paceflow:pace-workflow) R 小节）。只要主 session 已运行并读取验证结果，close-chg complete-open-tasks:true 就是默认收口方式。
paceflow:pace-workflow：P-A-C-E-V-R 流程控制。paceflow:pace-knowledge：finding/correction 需要沉淀到 knowledge/ 时使用。