paceaitian/paceflow/pace-workflow

PACE 协议工作流程

artifact 由 artifact-writer agent 创建和维护。主 session 负责分析、执行代码、验证和向用户确认；artifact 写入动作统一派 agent。

本 skill 的定位：PACEflow 已启用后的流程引导（P-A-C-E-V-R）。要不要启用 PACE 不由本 skill 判断，而是 hook 在 SessionStart 确定性处理：强信号（有 changes/ artifact / .pace-enabled / artifact-root 配置）→ 自动门控；软信号（detectSoftSignal：3+ 代码文件 / manifest 文件 / dated-plan）→ 注入指示让 AI 在响应用户前用 AskUserQuestion 问用户是否启用。本 skill 被加载时，PACE 通常已启用或正在启用流程中——下面直接讲流程，不再判断「要不要用」。

适用范围

启用后遵循 P-A-C-E-V-R。artifact 写入统一派 artifact-writer agent，主 session 通过 agent 完成创建/更新。

在已触发 PACEflow 信号的项目中，代码修改任务即使只涉及 1-2 个文件，也先按本 skill 判断流程；收到代码任务立即按流程判断，在第一次 Edit 前进入 PACE。一旦启用，写代码文件由写码门强制走 CHG，无豁免（详见下方「disable 是用户退出权」）。

Artifact 根目录以 hook 注入或 PreToolUse 提示为准。artifact_dir 仅用于 PaceFlow artifacts：spec.md / task.md / walkthrough.md / findings.md / corrections.md / changes/**。

Project Root 是 PACEflow 管理边界；local artifact root 表示 Project Root 本地目录，不是当前子目录。Current CWD 位于父级 Project Root 内时，沿用父项目 artifact、owner、Stop 和 .pace 运行态。若当前子目录确实是独立项目，先运行 hook 提示的 set-project-root helper（--mode independent），再选择 artifact root。

继续、恢复或收口已有 CHG 前，先 Read 对应 changes/<id>.md，确认 ## 任务清单、实施详情和 ## 工作记录；SessionStart 摘要只用于定位，不替代 CHG 详情。

spec.md 是 artifact root 内的项目事实文件，用于记录技术栈、依赖、配置、目录结构和编码约定等长期事实。它由主 session 按需要直接 Edit 维护，不派 artifact-writer，也不参与 CHG/HOTFIX 的批准、验证或归档流程。

若用户已经明确选择 Obsidian vault、本地项目目录或自定义 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 的子目录走宿主项目共享位置。helper 接受自身文档列出的参数；reserve 命令默认带 `--cwd <项目 cwd>` 锚定——Claude 主 session 的 Bash cwd 会在命令间漂移，不带 --cwd 时 reservation 可能写错 runtime（后续 artifact-writer 误报「无效或已过期」）；其余 artifact/root/project 路径由 helper 自行解析。

Helper 命令来源按以下顺序执行：

1. 如果 SessionStart / PreToolUse 已给出完整 node ".../hooks/*.js" 命令，直接复制那条命令。
2. 如果当前项目还没有 PACEflow 信号，但本 skill 已加载，使用 Claude Code 加载本 skill 时提供的 skill 根目录（本 SKILL.md 所在目录）作为 <skill-root>。按当前动作选择下面一条模板运行；这不是顺序执行清单：

node "<skill-root>/../../hooks/set-project-root.js" --mode independent
node "<skill-root>/../../hooks/set-artifact-root.js" --choice local
node "<skill-root>/../../hooks/set-artifact-root.js" --choice vault
node "<skill-root>/../../hooks/reserve-artifact-id.js" --operation create-chg --cwd <项目 cwd>

1. 如果当前上下文没有完整 hook 命令，也没有可用的 skill 根目录元数据，先触发/等待 hook 给出 helper 命令。helper 路径以 hook 命令或 skill 根目录为准，不扫描 ~/.claude/plugins/cache 猜版本。

disable 是用户退出权，非 AI 绕过手段

PACEflow 一旦启用（hook 检测到信号 / 有 artifact），写代码文件就由写码门强制走 CHG，没有豁免——唯一合法的停用是下面两个用户命令，不是 AI 绕过单次 deny。

被 PACE deny 拦住时，正确做法是走 PACE 流程（建 CHG / approve-and-start），不是 disable 绕过。/paceflow:disable（即 set-activation --disable）停用整个项目的 PACEflow，只在用户明确表达「不想用 PACE 管理本项目」时执行；AI 不得为绕过单次 deny 自主 disable。若判断用户可能想停用但用户未明说，先用 AskUserQuestion 确认，不自作主张。用户主动运行 /paceflow:disable 时直接执行，不再额外确认。

/paceflow:pause（即 set-activation --pause）是 session 级对应物：仅本 session 暂停流程门、artifact 完整性门保留、session 结束自动失效。防滥用约束同上且更严——AI 不得为绕过单次 deny 自行 pause，仅用户明确表达「本 session 不想要 PACEflow 约束」时执行；恢复用 /paceflow:resume。

参考：Superpowers/native plan 桥接细节见 references/superpowers-integration.md。

P (Plan)

默认先用 Superpowers / native plan 完成方案探索；无可用规划工具时，主 session 自行完成需求拆解、风险识别和执行方案。

P 阶段产物：

• 用户需求与验收标准清楚。
• 影响范围、技术决策、任务拆分足够拆成一个或多个 CHG。
• 如有 plan 文件，后续由 pace-bridge 转成 CHG。

CHG 粒度原则

CHG 不是大计划容器，而是连续执行、可独立验证、可独立回滚、可关闭的最小闭环单元——单个 CHG 自身就是一个能独立验证和回滚的完整变更，也能独立交给一个 worktree/session 执行。

• 一个 CHG 应该能在当前执行流中连续完成、运行验证、并用 close-chg 收尾。
• 一个 CHG 内可以有多个 T-NNN，但这些任务必须服务于同一个闭环，限定在单个独立功能/模块内。
• 大计划应拆成多个可独立完成和验证的 CHG。比如数据结构/迁移、后端接口、前端调用、文档配置通常应是不同 CHG。
• 按闭环边界拆分，不按 plan 层级合并：N 个独立可闭环功能就是 N 个 CHG，而不是把整个 plan 塞进一个大 CHG。
• 如果某个任务预计要暂停、等待用户、跨 session 继续、或在不同 worktree 并发推进，优先拆出独立 CHG。
• Artifact 是流程恢复和审计机制，按闭环里程碑派 agent 更新任务状态即可，无需为每个小步骤逐一更新。

A (Artifact)

有 plan 文件

调用 paceflow:pace-bridge。bridge 的职责是读取 plan，按上方 CHG 粒度原则拆成 N 个可闭环 CHG。拆出多个时优先一次性批量落地：reserve --operation create-chg --cwd <项目 cwd> --count N 取 N 个连号，再用一次 batch create（共享 change-set / change-set-total 头部 + N 个 --- CHG i/N --- 块）派 artifact-writer（详见 pace-bridge skill「批量创建」），避免「执行完一个才建下一个」把后续阶段规划只留在 session 上下文。生成：

• changes/chg-yyyymmdd-nn.md
• task.md wikilink 索引（唯一 CHG 索引）

Superpowers/native plan 中用户已参与设计且确认开始时，bridge 只对当前准备连续执行的 CHG继续派 update-chg action=approve-and-start，并带 approval-confirmed/source/evidence/task-id，形成 auto-APPROVED + 首个任务开始。后续 CHG 保持 planned，等真正开始时再批准/开始。

无 plan 文件

主 session 先预留编号，再组织字段派 artifact writer。优先使用 SessionStart / PreToolUse 提示中的 reserve helper 完整命令；如果上下文没有完整命令，按上方 helper 命令来源从当前 skill 根目录拼出同版本绝对路径。

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 默认复用尚未消费的 create-chg reservation。若已经预留过普通 CHG，现在要创建 HOTFIX，或确实需要第二个新编号，重新运行 helper 时加 --new：

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

将 helper 输出的 artifact_dir / operation / execution-context / reserved-id / reserved-file-prefix 原样放在 Agent prompt 顶部，再追加：

title: <变更标题>
tasks:
  - T-001: <任务标题与验收>
  - T-002: <任务标题与验收>
background: <Why>
scope: <What>
technical-decision: <How>

A 阶段完成标志：task.md 有活跃 [[chg-*]] / [[hotfix-*]] 索引，且 changes/<id>.md 存在。

若没有先运行 helper，create-chg 首次派遣会被 hook 阻止并返回 reserved-id / reserved-file-prefix；把这些字段原样加入 Agent prompt 后重派，编号一律来自 helper 预留。

Codex CLI 宿主（MVP）

PACEflow 也运行在 OpenAI Codex CLI 上（同一插件目录，经 .codex-plugin/plugin.json 安装；SessionStart 注入会带「=== 宿主: Codex CLI ===」提示）。P-A-C-E-V-R 流程与本 skill 完全一致，差异只在「artifact 怎么写」：

• 不派 `artifact-writer` 子代理——Codex 子代理的 prompt 对 hook 不可读、子代理内 hooks 不触发，改用插件自带的 MCP server paceflow。本 skill 里每一处「派 artifact-writer operation=X」在 Codex 上都对应一次 MCP 工具调用，字段同名（连字符改下划线）：

• 每次 MCP 调用先经 PreToolUse 派遣门（与 Claude 侧 artifact-writer 派遣门同一套校验，deny 文案相同），server 内每个文件写入再以 artifact-writer 身份过写入门；产物形态与 artifact-writer 逐段同构。
• MVP 未覆盖：update-finding / record-correction / update-index 与 batch create（change-set-total>1）——server 返回 not-implemented，请逐条调用或改到 Claude Code 宿主完成。
• 无 SendMessage resume 编排、无 Workflow；需要用户确认时用 Codex 自身的提问方式，批准证据仍写进 approval_evidence。
• 写码门覆盖 apply_patch（Codex 唯一文件写入工具）与 Bash；Codex 子代理内的写入不受门约束（宿主限制），不要把写代码委托给子代理。

Legacy v5 与 Worktree

检测到 v5 时代 artifact 布局（task.md 含活跃详情、无 changes/）时只会收到一句布局提示：新变更直接按当前合同走 create-chg（首次创建即建出 changes/），v5 存量内容保持原样、不迁移；如需保留历史，可建议用户手动归档到 <!-- ARCHIVE --> 下方。

Git worktree 中的 artifact root 与运行态 .pace/ 归一到宿主项目。普通子目录默认继承最近父级 Project Root。主 session 修改普通项目文件仍以当前 cwd/worktree 为准；只有 PaceFlow artifacts 与 .pace 运行态走 Project Root 共享位置。.pace/artifact-root 只由 set-artifact-root helper 写入；git worktree 与继承父 Project Root 的子目录走宿主项目共享位置。独立子项目先用 set-project-root --mode independent 声明边界。

C (Check)

改代码前先获批准：<!-- APPROVED --> 已写入 changes/<id>.md 且对应任务为 [/]。

需要用户确认时，先停止执行并询问是否批准当前 CHG。用户批准且准备开始时派 update-chg action=approve-and-start，必带 task-id、approval-confirmed: true、approval-source（user-directive | ask-user-question | accepted-plan | prior-approved-plan）、approval-evidence（用户原话或已确认方案摘要）；完整字段模板见 Skill(paceflow:artifact-management)「最小字段模板」。

若只是先批准、暂不执行，则派 update-chg action=approve，同样必须带 approval-confirmed: true、approval-source、approval-evidence。C 阶段批准标记只写入 changes/<id>.md；task.md 只保留索引，不承载批准标记。

如果用户已经直接要求“开始做/按方案执行/继续实现”，或已通过 plan/AskUserQuestion 明确批准，可以把这句话或确认摘要作为 approval-evidence；仍先派 approve-and-start 再写代码，让 C 阶段先行完成。

需要 AskUserQuestion 确认批准时，提供 2-3 个互斥选项，例如“批准并开始”与“暂不执行”。

PreToolUse 放行条件：活跃 CHG 在 task.md 存在，详情文件存在，已 APPROVED，且状态/checkbox 已进入可执行状态。APPROVED 标志 C 阶段完成；[ ] planned + APPROVED 属 ready/deferred，写项目文件前先 approve-and-start 或恢复为 [/] 进入 in-progress。

[!] 是 blocked/deferred：

• PreToolUse 仍会阻止继续写项目文件。
• Stop 允许结束当前 turn，但会显示人可见提醒，恢复前不能继续写。

E (Execute)

按 CHG 的 ## 任务清单 连续执行代码修改。默认路径是：批准并开始 → 写代码/测试 → 运行并读取验证 → close-chg complete-open-tasks:true 一次收口。同一个连续 CHG 的多个 T-NNN 由这一次 close-chg 统一收口；update-status 仅在暂停/阻塞/跳过/跨 session 时单独调用。

update-status [!] 仅表示暂停/阻塞，保持任务待恢复，其他 worktree 仍需显式接手。恢复前先确认用户意图，再把任务重新标为 [/] 继续，或按用户决策标 [-] / 取消。

update-status [x] 是跨 session/非连续任务记录的例外路径；连续执行的默认路径是 close-chg。最后一个任务代码写完后，先运行验证并读取结果，验证通过后用 close-chg complete-open-tasks=true 一次收口（由它收尾最后任务，无需先派 update-status）。若暂时不准备验证或必须把进度留给后续 session，才用 update-status [x] 把进度停在 completed 待验证状态。

方案根本性错误时：将当前任务标 [!]，停止写代码，重新说明偏差并回到 A/C；更新方案和重新批准也必须通过 artifact writer。

resume-per-CHG 编排（可选降本，显式低风险白名单）

连续执行同一个 CHG 时，可复用同一个 artifact-writer 省掉 fresh spawn 的规范重载。白名单是显式枚举的低风险 op，不是"无副作用"——update-status 会真实改变任务 checkbox / frontmatter status / 根索引，这些状态被写码门与 Stop 消费；将其留在白名单是已接受的 LLM-soft 权衡（改错可逆、无伪造 V/R 标记路径），扩大白名单前必须重新评估,不得以"只写记录"为由：