accelint-qrspi-apply

Accelint QRSPI Apply

通过智能并行化实现 OpenSpec 变更。此技能根据 OpenSpec 任务文件中的依赖分析编排并行子 Agent 执行，验证实现，并管理完整的 apply 工作流。

此技能的功能

自动化：规范驱动开发的实现阶段，支持并行执行 范围：任务实现 → 验证 → 归档就绪 输出：完全实现的变更，可供归档

不包含：创建计划、修改规范或自动归档（准备就绪时建议归档）

前置条件

• 已安装并初始化 OpenSpec CLI
• 已通过 accelint-qrspi 技能创建 OpenSpec 变更（tasks.md 中包含 "Parallelization Strategy"）
• 支持子 Agent（用于并行执行）
• 已启用扩展的 OpenSpec 工作流（explore、new、continue）

重要：此技能专为 QRSPI 规划的变更而设计。没有并行化策略的标准 OpenSpec 变更应直接使用常规的 openspec-apply-change 技能。

工作流概览

┌─────────────────────────────────────────────────────────────────┐
│  Stage          Action                        Output            │
├─────────────────────────────────────────────────────────────────┤
│  Preflight      Select and validate change    Ready to proceed  │
│  Start Time     Record started_at timestamp   Telemetry marker  │
│  Parse          Extract parallelization       Dependency graph  │
│  Dependencies   Identify blocking tasks       Execution plan    │
│  Load Context   Read config.yaml context      Project context   │
│  Execute        Run slices (parallel/serial)  Implemented code  │
│  Update Docs    Sync living documents         Updated docs      │
│  Complete Time  Record completed_at timestamp Telemetry marker  │
│  Verify         Run opsx:verify               Verification rpt  │
└─────────────────────────────────────────────────────────────────┘

实现步骤

预检与变更选择

1. 如果技能参数中提供了变更名称，则使用它
2. 否则，尝试从对话上下文中推断（最近提到的变更名称）
3. 如果有歧义或缺失：

   openspec list --json
   

   解析 JSON，并使用 AskUserQuestion 让用户选择变更
4. 声明："Applying change: <name>" 以及如何覆盖（例如，使用不同的名称重新调用）
5. 检查 tasks.md 是否存在：

   openspec status --change "<name>" --json
   

   如果 state: "blocked"（缺少 tasks），则以以下内容退出："Tasks artifact is missing. Run openspec-continue-change to generate tasks before applying."

记录实现开始时间

目标：标记实现开始的时间，用于遥测跟踪。

6. 从 openspec/changes/<change-name>/design.md 读取 design.md 文件，检查 frontmatter 中是否存在 started_at 时间戳

7. 如果 frontmatter 中未出现 started_at（首次应用此变更）：

   • 使用带 Z 后缀的 ISO 8601 格式，将 started_at 时间戳添加到 frontmatter
   • 关键：使用此命令确定性地生成时间戳：

     python3 -c "from datetime import datetime, timezone; print(datetime.now(timezone.utc).isoformat(timespec='seconds').replace('+00:00', 'Z'))"
     

   • 将 started_at 紧接在 created_at 字段之后插入，使所有时间戳归组在一起
   • 按原始顺序保留所有其他 frontmatter 字段（change、created_at、specs_touched、decisions）
   • 告知用户："Recording implementation start time..."

8. 如果 started_at 已出现（在上下文清除或暂停后恢复）：

   • 不要修改时间戳 — 保留原始开始时间
   • 告知用户："Resuming implementation (started at [timestamp])..."

添加 started_at 后的 frontmatter 示例：

---
change: <change-name>
created_at: "2026-08-17T15:00:00.000Z"
started_at: "2026-08-17T16:30:00.000Z"
specs_touched: [<capability-a>, <capability-b>]
decisions:
  - id: D1
    choice: <decision>
    rationale: <why>
    alternatives: [<option>]
---

输出：将时间戳写入 design.md 的 frontmatter（如果这是首次应用），或确认恢复

解析任务与并行化策略

目标：提取任务结构，识别可并行执行与必须串行执行的机会。检测工作是否已经开始，并从正确的层级恢复执行。

9. 从 openspec/changes/<change-name>/tasks.md 读取 tasks.md 文件

10. 验证清单格式（对进度跟踪至关重要）：

• 检查任务是否使用 markdown 清单格式：- [ ] task 或 - [x] task
• 如果任务使用编号列表（1. 2. 3.）或普通项目符号（- 不带 [ ]）：

  ❌ Invalid tasks.md format
  
  This skill requires tasks in markdown checklist format (`- [ ] task`) for
  progress tracking and resumption detection.
  
  Found format: [numbered lists / plain bullets / other]
  
  Please regenerate tasks.md using the accelint-qrspi-propose skill or convert
  manually to checklist format before applying.
  

• 如果格式无效则退出——不要以无效的任务格式继续执行

11. 检查部分完成情况（恢复检测）：

• 统计已完成任务（标记为 - [x]）与任务总数
• 解析哪些切片的所有任务都已标记为完成
• 如果有任何切片已完成，则宣布："检测到部分完成。从 Slice N 恢复执行。"
• 调整执行计划以跳过已完成的切片

12. 查找 "Parallelization Strategy" 部分（通常位于文件末尾）

13. 解析该策略以构建依赖图：

策略示例：

## Parallelization Strategy

- **Slice 1** must complete first (establishes infrastructure)
- **Slice 2** and **Slice 3** can run in parallel after Slice 1
- **Slice 2** (implementation cleanup) is independent of **Slice 3** (docs/verification)
- Final integration: merge both slices, run full pre-commit checklist

解析后的依赖图：

Level 0 (must run first):
  - Slice 1

Level 1 (can run in parallel after Level 0):
  - Slice 2
  - Slice 3

Level 2 (after all previous):
  - Final integration

14. 如果不存在 "Parallelization Strategy" 部分：

• 假设所有任务必须串行执行（安全的默认值）
• 告知用户："未找到并行化策略。将按串行方式执行任务。"

15. 构建执行计划，展示：

• 哪些切片以何种顺序执行
• 哪些切片可以并行执行（以及哪些已经完成）
• 并行化带来的总预计加速
• 起始点（Level 0 或从 Level N 恢复）

输出：依赖图、执行计划，以及适用时的恢复点

加载项目上下文

目标：从 openspec/config.yaml 加载项目上下文，以便注入到子 Agent 的提示词中。这弥补了 OpenSpec CLI 的限制——apply 技能不会自动加载项目上下文（与创建产物的技能不同）。

背景：OpenSpec 的 openspec instructions apply 技能不会注入 config.yaml 中的 context 字段（已通过代码审查和测试确认）。这意味着实现任务的子 Agent 不会收到本应指导实现的 Stack Facts、编码模式、测试约定或反模式。我们通过手动加载并注入上下文来绕过这一限制。

16. 检查 openspec/config.yaml 是否存在：

test -f openspec/config.yaml && echo "exists" || echo "missing"

17. 如果该文件存在，则读取它：

cat openspec/config.yaml

18. 解析并提取 context 部分（context: | 下的 YAML 块）：

• 上下文从 context: | 这一行之后开始
• 上下文一直延续到下一个顶层 YAML 键（例如 rules:、schema:）
• 上下文块中的行带有缩进（通常为 2 个空格）
• 保留上下文块中的所有空白和换行
• 你必须告知用户你已找到并加载了配置。

19. 存储提取出的上下文，以便在后续步骤中注入到子 Agent 的提示词中

20. 如果不存在 context 字段或文件缺失：

• 将上下文设置为空字符串
• 在无上下文注入的情况下继续执行（子 Agent 将依赖 OpenSpec 的默认行为）
• 你必须告知用户你未能找到并加载配置。

config.yaml 结构示例：

schema: spec-driven

context: |
  # STACK FACTS
  ## Project Identity
  auditkit-cli: TypeScript-based code quality audit CLI

  ## Dependencies
  - @fission-ai/openspec: ^1.2.0
  - vitest: ^2.1.8

  # CODING PATTERNS
  - Use Result<T,E> for fallible operations (never throw)
  - Data-last parameter ordering for currying
  - No `any` types — use `unknown` with type guards

  # TESTING CONVENTIONS
  - AAA pattern (Arrange/Act/Assert)
  - One assertion per test
  - Use descriptive test names

rules:
  proposal: [...]
  design: [...]

输出：提取出的项目上下文字符串（如果不存在则为空）

执行任务（串行 + 并行）

目标：按照依赖图实现任务，尽可能使用 Agent 工具启动并行子 Agent。

串行执行（当任务存在依赖关系时）：

对于依赖图中的每一层（从 level 0 开始）： 21. 如果该层级只有一个切片：

• 使用 Agent 工具生成一个带有此提示词的单一子 Agent（注入在步骤 16 中加载的项目上下文）：

  <project_context>
  
  {INJECTED_CONFIG_CONTEXT}
  </project_context>
  
  Invoke the openspec-apply-change skill.
  
  <change-name>
  
  CRITICAL: You MUST use the openspec-apply-change skill to implement tasks.
  DO NOT implement tasks directly yourself. The openspec-apply-change workflow will
  load context and guide implementation.
  
  IMPORTANT: This is Slice N of a parallelized QRSPI implementation.
  
  Context: This slice must complete before other slices can proceed.
  Other slices will start after you finish.
  
  Instructions:
  - Work ONLY on tasks in Slice N: [list slice N tasks/sections]
  - Do NOT implement tasks from other slices (Slices X, Y, Z will be handled separately)
  - Before you add or change code, apply this simplicity ladder and stop at the first rung that holds:
    1. Does this need to exist at all? Speculative need = skip it, say so in one line. (YAGNI)
    2. Already in this codebase? A helper, util, type, or pattern that already lives here → reuse it. Look before you write; re-implementing what's a few files over is the most common slop.
    3. Stdlib does it? Use it.
    4. Non-UI code: does a native platform or language feature cover it? Use it before a library.
    5. UI code: if this codebase already has a design-system or UI-library primitive for it, use that before raw native elements or hand-rolled UI behavior.
    6. Already-installed dependency solves it outside the above cases? Use it. Never add a new one for what a few lines can do.
    7. Can it be one line? One line.
    8. Only then: the minimum code that works.
  - Never simplify away trust-boundary input validation, error handling that prevents data loss, security checks, accessibility basics, or other explicit project constraints — the minimalism heuristics above never override this.
  - Apply the code patterns, conventions, and constraints from <project_context>
  - Follow the normal OpenSpec apply workflow:
    * OpenSpec will load context files (proposal, design, specs, tasks)
    * Implement the tasks assigned to Slice N
    * Mark tasks complete as you go: `- [ ]` → `- [x]`
    * Test your changes if tests are specified in the tasks
  - Report completion with summary of changes made
  - The <project_context> provides Stack Facts, coding patterns, testing conventions,
    and anti-patterns to avoid. These are constraints for YOU, not content to include in files.
  
  Focus exclusively on Slice N. Leave other slice tasks unchecked.
  

  注意：如果之前未加载项目上下文，请完全省略 <project_context> 块

22. 等待完成后再进入下一个层级

并行执行（当多个切片相互独立时）：

对于每个包含多个独立切片的层级：

23. 使用 Agent 工具在单个回合中并行生成所有子 Agent（每个切片一个，注入之前步骤中的项目上下文）：

<project_context>

{INJECTED_CONFIG_CONTEXT}
</project_context>

Invoke the openspec-apply-change skill.

<change-name>

CRITICAL: You MUST use the openspec-apply-change skill to implement tasks.
DO NOT implement tasks directly yourself. The openspec-apply-change workflow will
load context and guide implementation.

IMPORTANT: This is Slice N of a parallelized QRSPI implementation.

Context: This slice is independent and runs in parallel with Slices X, Y.
Other agents are working on those slices simultaneously.

Instructions:
- Work ONLY on tasks in Slice N: [list slice N tasks/sections]
- Do NOT implement tasks from other slices - they are being handled in parallel
- Before you add or change code, apply this simplicity ladder and stop at the first rung that holds:
  1. Does this need to exist at all? Speculative need = skip it, say so in one line. (YAGNI)
  2. Already in this codebase? A helper, util, type, or pattern that already lives here → reuse it. Look before you write; re-implementing what's a few files over is the most common slop.
  3. Stdlib does it? Use it.
  4. Non-UI code: does a native platform or language feature cover it? Use it before a library.
  5. UI code: if this codebase already has a design-system or UI-library primitive for it, use that before raw native elements or hand-rolled UI behavior.
  6. Already-installed dependency solves it outside the above cases? Use it. Never add a new one for what a few lines can do.
  7. Can it be one line? One line.
  8. Only then: the minimum code that works.
- Never simplify away trust-boundary input validation, error handling that prevents data loss, security checks, accessibility basics, or other explicit project constraints — the minimalism heuristics above never override this.
- Apply the code patterns, conventions, and constraints from <project_context>
- Follow the normal OpenSpec apply workflow:
    * OpenSpec will load context files (proposal, design, specs, tasks)
    * Implement the tasks assigned to Slice N
    * Mark tasks complete as you go: `- [ ]` → `- [x]`
    * Test your changes if tests are specified in the tasks
- Report completion with summary of changes made
- The <project_context> provides Stack Facts, coding patterns, testing conventions,
  and anti-patterns to avoid. These are constraints for YOU, not content to include in files.

Focus exclusively on Slice N. Leave other slice tasks unchecked.
Your work is independent and should not block or depend on other slices.

注意：如果之前未加载项目上下文，请完全省略 <project_context> 块

24. 在每个子 Agent 完成时跟踪其进度

25. 上下文管理决策点 - 当该层级中的所有切片都完成后，暂停并提供上下文管理选项：

✅ Level N complete

Completed slices:
- Slice X: <summary>
- Slice Y: <summary>

Next: Level N+1 has M slice(s) to run [list slices]

Options:
(a) Continue to next level
(b) Clear context and resume — I'll pick up from Level N+1
(c) Pause here — you can resume later with this skill

26. 如果用户选择 (b)，请指示他们：

Run `/clear` to reset context, then re-invoke this skill.
I'll detect that Level N is complete and resume from Level N+1.

27. 如果用户选择 (c)，退出并提醒他们如何恢复：

Paused at Level N+1. To resume, re-invoke this skill.
Progress is tracked in tasks.md checkboxes.

切片定位方式：OpenSpec 的 openspec-apply-change 技能没有原生的“切片定位”功能（没有 --slice N 标志）。此技能通过以下方式实现并行化：

1. 使用完整的 OpenSpec CLI 工作流：每个子 Agent 调用 openspec-apply-change <change-name>，它会：

   • 运行 openspec instructions apply --change "<name>" --json 获取上下文
   • 加载所有上下文文件（proposal、design、specs、tasks）
   • 根据当前状态提供动态指令
   • 处理任务进度跟踪和状态检查

2. 通过指令实现切片隔离：编排 skill：

   • 解析并行化策略，识别相互独立的切片
   • 启动子 Agent，并明确指示它们仅处理被分配的切片
   • 依赖 QRSPI 的垂直切片来确保切片真正独立
   • 每个子 Agent 仅将自己的切片中的任务标记为完成

3. 为什么这样做有效：QRSPI 的垂直切片方法确保每个切片：

   • 是一个完整的端到端功能增量
   • 相互独立，文件重叠最少
   • 可单独测试
   • 可安全地并行实现

切片边界在 tasks.md 中有清晰标注（例如 "## Slice 1: Remove CLI Surface"、"## Slice 2: Remove Implementation"），使子 Agent 能够直接识别自己的范围。

更新活文档

目标：在运行验证之前，更新项目文档以反映已实现的变更。

为什么这很重要：OpenSpec 变更代表着重要的架构决策和功能新增。活文档（ARCHITECTURE.md、AGENTS.md、openspec/config.yaml）为在代码库中工作的 Agent 提供上下文，而 README.md 则面向人类用户。保持它们同步可以防止文档漂移，并确保未来的 Agent 和开发者对系统当前状态拥有准确、最新的上下文。

重要：请在验证之前运行此步骤，以便验证步骤能够检查文档完整性。

28. 通过查找 .git/ 或 package.json，判断该变更是否位于仓库或包的根目录

29. 确定仓库/包的根目录（可能是当前目录或某个父目录）

30. 按以下顺序处理所有活文档（不要在处理完第一个后就停止）：

• OpenSpec 配置（openspec/config.yaml）
• ARCHITECTURE.md（如果存在）
• AGENTS.md（如果存在）
• README.md（如果存在）

此阶段的优先级规则：

• 如果已安装对应的 Accelint 文档 skill，则必须使用该 skill。不要自行手动编辑文档。
• 仅当对应的 skill 不可用时，才允许手动兜底。
• 如果调用的文档 skill 返回预览并在写入前要求确认，则该预览/确认环节是强制性的。将其呈现给人类，并等待明确批准。不要通过手动编辑文件来绕过该环节。
• “文档之间不要暂停”规则的含义是：一旦某个文档被完全处理完毕（跳过、通过其 skill 批准并写入，或因对应 skill 不可用而手动更新），立即继续处理下一个文档。它不会覆盖子 skill 所要求的预览/确认步骤。
• 绝不要仅仅因为手动兜底看起来更快，或因为子 skill 要求确认，就选择手动兜底。

对于上述列表中的每个文档，请遵循以下步骤：

步骤 3a：先检查是否需要更新

• 阅读变更产物以了解已实现的内容：
  • openspec/changes/<change-name>/proposal.md
  • openspec/changes/<change-name>/design.md
• 评估此变更是否引入会影响该文档的内容
• 如果变更无关紧要（拼写错误、注释），或者不涉及该文档的范围，则跳到下一个文档

步骤 3b：如果需要，更新文档 对于 OpenSpec 配置（<repo-root>/openspec/config.yaml）：

• 检查是否安装了 accelint-onboard-openspec 技能

• 如果技能可用：

  1. 该子技能负责本文档的发现、预览、确认和写入步骤。在此技能可用时，请勿手动编辑 openspec/config.yaml。
  2. 读取 openspec/changes/<change-name>/design.md 的 frontmatter，提取 decisions 字段
  3. 对于每个决策，将其改写为平实的事实性陈述（而非指令）
  4. 携带发现结果调用该技能：

  Invoke the accelint-onboard-openspec skill.
  
  We have just completed the change spec openspec/changes/<change-name>.
  
  findings:
  - [Decision 1 rephrased as fact, e.g., "config.yaml's Anti-Patterns section says to avoid polling, but this change chose polling for stated reasons"]
  - [Decision 2 rephrased as fact]
  ...
  

  该技能会将这些发现结果与其自身的代码库扫描合并，然后再呈现给人类。

• 如果技能不可用，则读取变更工件：

  • openspec/changes/<change-name>/proposal.md
  • openspec/changes/<change-name>/design.md

  然后读取 openspec/config.yaml 并手动更新，重点关注 项目 DNA（项目是什么）：

  • Tech Stack 部分：添加本次变更引入的新依赖、框架或库及其版本
  • Domain Concepts 部分：如果本次变更引入了新的实体或领域术语，则添加它们
  • Code Patterns 部分：如果本次变更确立了新模式（导出、错误处理、校验方式），则更新
  • Architecture Patterns 部分：如果引入了新的设计模式（工厂、仓储、观察者等），则添加
  • Patterns to Avoid 部分：添加本次变更废弃或明确指出的任何反模式
  • 按工件规则（rules: 部分）：如果本次变更影响 proposal/design/tasks/spec 的要求，则更新
  • 请勿添加 Agent 行为（提交约定、工作流步骤、工具偏好应放在 AGENTS.md 中）

对于 ARCHITECTURE.md（<repo-root>/ARCHITECTURE.md）——如果它存在：

• 检查是否安装了 accelint-architecture-doc 技能

• 如果技能可用：

  1. 该子技能负责本文档的发现、预览、确认和写入步骤。在此技能可用时，请勿手动编辑 ARCHITECTURE.md。
  2. 读取 openspec/changes/<change-name>/design.md 的 frontmatter，提取 decisions 字段
  3. 对于每个决策，将其改写为平实的事实性陈述（而非指令）
  4. 携带发现结果调用该技能：

  Invoke the accelint-architecture-doc skill.
  
  We have just completed the change spec openspec/changes/<change-name>.
  
  findings:
  - [Decision 1 rephrased as fact]
  - [Decision 2 rephrased as fact]
  ...
  

  该技能会将这些发现结果与其自身的代码库扫描合并，然后再呈现给人类。

• 如果技能不可用，则读取变更工件：

  • openspec/changes/<change-name>/proposal.md
  • openspec/changes/<change-name>/design.md 然后阅读 ARCHITECTURE.md，并手动更新，重点关注系统结构（各组件之间如何关联）：
  • 第 1 节（项目结构）：如果出现新的顶层目录或发生重大重组，更新目录树
  • 第 2 节（高层系统图）：如果组件关系发生变化或新增了服务，更新 ASCII 图
  • 第 3 节（核心组件）：添加本次变更引入的新组件、服务或包，并说明其架构角色
  • 第 4 节（数据存储）：如果引入了新数据库、缓存或数据存储，添加它们
  • 第 5 节（外部集成）：添加本次变更集成的新第三方服务或 API
  • 第 6 节（部署与基础设施）：如果部署模型发生变化或新增了基础设施，更新本节
  • 第 8 节（技术栈）：如果本次变更引入了新的运行时依赖或框架，更新本节
  • 不要添加编码模式、测试约定或 Agent 行为（这些属于 config.yaml 或 AGENTS.md）

对于 AGENTS.md（<repo-root>/AGENTS.md）—— 如果它存在：

• 检查是否安装了 accelint-onboard-agents skill

• 如果 skill 可用：

  1. 该子 skill 负责本文档的发现、预览、确认和写入步骤。在此 skill 可用时，不要手动编辑 AGENTS.md。
  2. 阅读 openspec/changes/<change-name>/design.md frontmatter，提取 decisions 字段
  3. 对每个决策，将其改写为平实的事实陈述（而非指令）
  4. 携带发现结果调用该 skill：

  Invoke the accelint-onboard-agents skill.
  
  We have just completed the change spec openspec/changes/<change-name>.
  
  findings:
  - [Decision 1 rephrased as fact]
  - [Decision 2 rephrased as fact]
  ...
  

  该 skill 会将这些发现结果与其自身的代码库扫描结果合并，然后再呈现给人类。

• 如果 skill 不可用，阅读变更产物：

  • openspec/changes/<change-name>/proposal.md
  • openspec/changes/<change-name>/design.md

  然后阅读 AGENTS.md，并手动更新，重点关注 Agent 行为（Agent 应如何行动）：

  • Workflow Procedures 部分：如果本次变更引入了新的工作流步骤（例如新的预提交检查、新的 PR 要求），更新本节
  • Decision Heuristics 部分：如果本次变更产生了需要 Agent 判断的情形，添加新的决策规则
  • Tool Preferences 部分：如果引入了新工具或工具使用方式发生变化（例如新的测试运行器、新的 linter），更新本节
  • Guardrails 部分：如果本次变更产生了新的风险领域，添加新的“绝不执行”或“必须先询问”规则
  • Pre-Commit Checklist：如果提交前需要新的验证命令，添加这些命令
  • Commit Messages 部分：如果提交约定发生变化，更新本节
  • 不要添加技术栈事实、领域概念或编码模式（这些属于 config.yaml）

对于 README.md（<repo-root>/README.md）—— 如果它存在：

• 检查是否安装了 accelint-readme-writer skill

• 如果 skill 可用：

  1. 该子 skill 负责本文档的发现、预览、确认和写入步骤。在此 skill 可用时，不要手动编辑 README.md。
  2. 阅读 openspec/changes/<change-name>/design.md frontmatter，提取 decisions 字段
  3. 对每个决策，将其改写为平实的事实陈述（而非指令）
  4. 携带发现结果调用该 skill：

  Invoke the accelint-readme-writer skill.
  
  We have just completed the change spec openspec/changes/<change-name>.
  
  findings:
  - [Decision 1 rephrased as fact]
  - [Decision 2 rephrased as fact]
  ...
  

  该 skill 会将这些发现结果与其自身的代码库扫描结果合并，然后再呈现给人类。

• 如果 skill 不可用，请阅读变更工件：

  • openspec/changes/<change-name>/proposal.md
  • openspec/changes/<change-name>/design.md

  然后阅读 README.md 并手动更新，重点关注面向用户的文档：

  • 安装部分：如果新增了依赖项或设置步骤，请更新命令
  • 功能部分：为此变更引入的新面向用户功能添加条目
  • 快速开始部分：如果基本使用模式发生变化，请更新
  • 用法 / API 参考部分：如果公共 API 签名发生变化或新增了导出，请更新代码示例
  • 配置部分：如果引入了新的配置选项，请添加
  • 示例部分：为新功能添加新的使用示例
  • 不要记录内部实现细节、架构决策或未导出的函数

Skill 可用性检测：要检查是否安装了某个 Accelint skill，请使用以下方法之一：

• 检查系统提醒中的可用 skills 列表中是否出现该 skill
• 尝试调用该 skill，并在其不存在时捕获错误
• 使用 Glob 在 .claude/skills/ 或 ~/.claude/skills/ 中搜索该 skill 名称

何时跳过特定文档的更新：

• 变更微不足道（拼写修正、注释更新），且不影响该文档的范围
• 文档不存在
• 变更内容没有引入任何需要更新该文档的内容

重要：按顺序依次处理全部 4 个文档，一个接一个，不要在第一个之后停止。不要在文档之间编造额外的停顿。此阶段唯一合理的等待是：(a) 子文档 skill 所需的预览/确认关卡，或 (b) 需要用户输入的错误。在某个文档被跳过、通过其 skill 批准并写入、或因其 skill 不可用而手动更新后，立即继续处理下一个文档。完成全部 4 个文档后，立即进入下一步（记录完成时间戳）。

31. 检查完全部 4 个文档后，运行 git status 以显示哪些文档被修改

32. 展示摘要（然后立即继续记录完成时间戳）：

• 如果无需更新：

  📝 已检查活文档 — 此变更无需更新
  
  已检查的文档：
  - openspec/config.yaml [无需更改]
  - ARCHITECTURE.md [无需更改]
  - AGENTS.md [无需更改]
  - README.md [无需更改]
  
  正在继续验证...
  

• 如果进行了更新：

  📝 已更新活文档
  
  已更新的文档：
  - openspec/config.yaml [通过 accelint-onboard-openspec / 因 skill 不可用而手动回退 / 已跳过]
  - ARCHITECTURE.md [通过 accelint-architecture-doc / 因 skill 不可用而手动回退 / 已跳过]
  - AGENTS.md [通过 accelint-onboard-agents / 因 skill 不可用而手动回退 / 已跳过]
  - README.md [通过 accelint-readme-writer / 因 skill 不可用而手动回退 / 已跳过]
  
  这些更改确保文档与实现保持同步。
  
  正在记录完成时间戳...
  

输出：已更新文档及其所用方法（skill 还是手动）的摘要，或无需更新的确认

记录实现完成

目标：标记实现完成的时间点（在验证之前），用于遥测跟踪。

重要：此步骤在活文档更新之后、验证之前立即运行。不要等待用户输入。

33. 从 openspec/changes/<change-name>/design.md 读取 design.md 文件

34. 使用带 Z 后缀的 ISO 8601 格式，将 completed_at 时间戳添加到 frontmatter：

• 关键：使用以下命令确定性地生成时间戳：

  python3 -c "from datetime import datetime, timezone; print(datetime.now(timezone.utc).isoformat(timespec='seconds').replace('+00:00', 'Z'))"
  

• 将 completed_at 紧接在 started_at 字段之后插入，以便将所有时间戳归组在一起
• 按原始顺序保留所有其他 frontmatter 字段（change、created_at、started_at、specs_touched、decisions）
• 这标记了实现完成的时刻，即验证开始之前

35. 通知用户："实现完成。正在运行验证……"

添加 completed_at 后的示例 frontmatter：

---
change: <change-name>
created_at: "2026-08-17T15:00:00.000Z"
started_at: "2026-08-17T16:30:00.000Z"
completed_at: "2026-08-17T17:45:00.000Z"
specs_touched: [<capability-a>, <capability-b>]
decisions:
  - id: D1
    choice: <decision>
    rationale: <why>
    alternatives: [<option>]
---

重要：记录完成时间戳后，立即进入验证（步骤 36）。不要暂停或等待用户输入。完成时间戳标记实现工作的结束，验证会自动跟进。

输出：时间戳写入 design.md frontmatter，然后强制自动过渡到验证，无需等待用户输入

验证实现

目标：验证实现是否与变更工件（规格、任务、设计）一致。

关键：这是最后一步。验证是强制性的，并生成一份全面的报告作为最终输出。不要在此步骤之后添加额外的报告。

36. 调用 verify skill：

Invoke the openspec-verify-change skill.

<change-name>

37. verify 命令将：

• 检查任务完成情况（所有复选框均已勾选）
• 验证规格覆盖（需求已实现）
• 验证设计遵循情况（决策已遵循）
• 检查活文档是否已适当更新
• 生成一份全面的验证报告，包含 CRITICAL/WARNING/SUGGESTION 问题
• 包含后续步骤（如果通过则归档，如果失败则修复问题）

38. 向用户呈现验证报告

39. 验证报告就是完成报告。它包括：

• 总体状态（通过/失败）
• 按严重程度划分的问题明细
• 已更改文件列表
• 基于状态的后续步骤
• 如已就绪，提供归档指导

40. 在呈现验证报告后退出 skill。报告已告知用户下一步该做什么。

输出：包含状态、问题、已更改文件和后续步骤的全面验证报告

关键原则

上下文管理与恢复

该 skill 支持在依赖层级边界处进行暂停/清除/恢复工作流：

• 暂停点：每个依赖层级完成后，该 skill 会提供继续或让用户清除上下文的选项（步骤 22）
• 恢复检测：再次调用时，该 skill 读取 tasks.md 复选框以检测已完成的切片，并从下一个未完成的层级恢复（步骤 8）
• 进度跟踪：任务完成情况通过复选框在 tasks.md 中跟踪，使进度在上下文清除后依然持久
• 理由：子 Agent 会累积大量上下文。在依赖层级之间，编排 Agent 可以清除上下文，同时通过任务复选框保留工作进度。

为什么这很重要：包含许多切片的长时间实现会使上下文膨胀。通过在各层级之间提供暂停点，用户既能保持清除上下文的灵活性（如同串行的 openspec-apply-change），又能受益于每个层级内的并行化。

智能并行化

该技能会从 tasks.md 的“并行化策略”部分自动检测并行化机会。当切片相互独立时，它会启动多个子 Agent 并行工作，从而显著缩短实现时间。

安全默认值

如果未找到并行化策略，该技能会按顺序运行任务。这确保了即使变更在规划时未考虑并行化，也能保持正确性。

归档前验证

该技能始终将 openspec-verify-change 作为最后一步运行。这会在用户归档之前捕获未完成的任务、失效的引用或 schema 违规。验证报告可作为完成摘要。

人在环路中

该技能会在以下情况下报告结果并请求指导：

• 验证失败
• 任务不明确或被阻塞
• 实现过程中出现任何错误

上下文管理

每个子 Agent 会收到：

• 完整的上下文文件（proposal、design、specs、tasks）
• 明确指示仅实现分配给自己的切片
• 知晓其他切片可能正在并行运行

这可以防止子 Agent 相互干扰彼此的工作，同时让它们看到全貌。

处理边界情况

循环依赖： 如果并行化策略包含循环依赖（切片 A 阻塞 B，B 阻塞 A），请检测并报告错误。要求用户修复 tasks.md 文件。

缺失切片： 如果并行化策略中引用了某个切片，但任务列表中不存在该切片，请报告错误并要求用户修复 tasks.md。

部分完成： 如果某些任务已被标记为完成（来自之前的会话），请从中断处继续。宣布：“N/M 个任务已完成。从切片 X 继续。”

子 Agent 失败： 如果子 Agent 失败或超时：

• 报告哪个切片失败以及原因
• 询问用户是希望重试该切片还是手动处理
• 在阻塞切片成功之前，不要继续处理依赖切片

不支持子 Agent： 如果环境不支持子 Agent（例如 Claude.ai）：

• 回退到顺序执行（自行实现所有任务）
• 告知用户：“子 Agent 不可用。正在按顺序运行任务。”

绝对不要这样做

绝对不要在活文档更新与验证之间停下来等待用户确认 — 一旦活文档更新（步骤 28-32）全部处理完毕，立即继续记录完成时间戳（步骤 33-35），然后进入验证（步骤 36）。这些步骤是一个连续的工作流。唯一合法的停止点是：(1) 需要用户输入才能解决的错误，(2) 预检失败（步骤 1-5），(3) 依赖层级之间由用户控制的上下文管理决策点（步骤 25），或 (4) 子文档技能自身强制的预览/确认关卡。该子技能关卡优先于此父规则。不要通过手动编辑文档来绕过它。一旦用户批准或拒绝预览，立即继续父工作流。

绝对不要直接实现任务 — 始终通过子 Agent 委托给 openspec-apply-change 技能。opsx:apply 工作流会加载上下文文件（proposal、design、specs、tasks），并基于 OpenSpec 的状态管理提供动态指令。如果你直接实现任务，就会绕过 OpenSpec 的进度跟踪和上下文加载。

绝对不要跳过验证 — 使用 openspec-verify-change 进行验证（步骤 36）是强制性的最后一步。验证会捕捉未完成的任务、未实现的需求和设计偏差。验证报告即完成总结。跳过验证会有归档不完整或不正确实现的风险。

绝对不要在任务格式无效的情况下继续 — 此技能依赖 markdown 清单格式（- [ ] task）来进行进度跟踪和恢复检测。如果 tasks.md 使用编号列表或普通项目符号，请尽早报错退出。不要试图绕过格式问题 — 用户必须先修复 tasks.md。

绝对不要跳过依赖层级 — 如果切片 A 阻塞切片 B，则切片 B 在切片 A 成功完成之前不能开始。不要在阻塞项完成之前启动依赖切片，即使这样能加快实现速度。必须遵守并行化策略中的依赖图。

绝对不要跳过活文档更新 — 活文档更新（步骤 28-32）使 ARCHITECTURE.md、AGENTS.md、README.md 和 config.yaml 与实现保持同步。这些步骤在完成时间戳和验证之前运行，以便验证步骤能够检查文档完整性。不要在没有先更新活文档的情况下跳到时间戳记录或验证。

当关联的 Accelint 技能已安装时，绝对不要手动编辑活文档 — 如果目标文档存在 accelint-onboard-openspec、accelint-architecture-doc、accelint-onboard-agents 或 accelint-readme-writer，你必须调用该技能并遵循其工作流，包括任何预览/确认关卡。仅在对应技能不可用时，手动编辑才作为后备方案。

配置要求

此技能假设：

1. OpenSpec 已安装并初始化
2. 变更存在且具有 tasks.md 文件
3. 子 Agent 支持可用（用于并行执行）
4. Git 已初始化（用于检查文件变更）

如果缺少任何一项，请报告问题并引导用户进行设置。

使用示例

场景 1：带并行化策略的变更

User: Apply the remove-security-ruleset change

Skill: Applying change: remove-security-ruleset

Parsing parallelization strategy...

Execution plan:
- Level 0 (sequential): Slice 1 (Remove CLI surface)
- Level 1 (parallel): Slice 2 (Remove implementation), Slice 3 (Docs/verification)

Starting Level 0: Slice 1
[spawns sub-agent]
✓ Slice 1 complete (4 tasks, ~8 minutes)

Starting Level 1: Slices 2 and 3 in parallel
[spawns 2 sub-agents simultaneously]
✓ Slice 2 complete (4 tasks, ~6 minutes)
✓ Slice 3 complete (4 tasks, ~7 minutes)

Updating living documents...
📝 Living documents updated
- README.md [via accelint-readme-writer]
- ARCHITECTURE.md [via accelint-architecture-doc]

Running verification...
✅ Verification passed

**Verification Report**

**Change:** remove-security-ruleset
**Tasks:** 12/12 complete
**Files changed:** 67

All requirements implemented. No critical issues found.

### Next Steps
1. Review the changes: `git diff`
2. Run tests: `pnpm test`
3. Archive this change: Invoke the `accelint-qrspi-archive` skill with `remove-security-ruleset`

Ready to archive!

场景 2：验证失败

User: Apply the auth-refactor change

Skill: Applying change: auth-refactor

[implementation proceeds...]

Updating living documents...
📝 Living documents updated
- ARCHITECTURE.md [via accelint-architecture-doc]

Running verification...
❌ Verification failed

**Verification Report**

**Change:** auth-refactor
**Critical Issues:**
- Task 3.2 in tasks.md is incomplete (checkbox not marked)
- Spec file specs/auth-service.md references non-existent file: src/old-auth.ts

**Next Steps:**
1. Fix critical issues
2. Re-run verification: Invoke the `openspec-verify-change` skill with `auth-refactor`
3. Or re-invoke this skill to retry

Not ready to archive until critical issues are resolved.

场景 3：无并行化（安全回退）

User: Apply the update-readme change

Skill: Applying change: update-readme

No parallelization strategy found. Running tasks sequentially.

Working on task 1/3: Update installation section
✓ Complete

Working on task 2/3: Add examples section
✓ Complete

Working on task 3/3: Update changelog
✓ Complete

Updating living documents...
📝 Living documents updated
- README.md [via accelint-readme-writer]

Running verification...
✅ Verification passed

**Verification Report**

**Change:** update-readme
All tasks complete. Ready to archive!

文件变更摘要

验证完成后，为用户生成结构化的 diff 摘要。此摘要提供所有代码级变更的可快速浏览的概览，不包含描述。

关键：此摘要必须在验证报告之后提供。不要跳过。

41. 运行 git diff 以捕获本次实现期间所做的所有变更

42. 从 openspec/archive/<change-name>/ 解析已归档的变更规范，以了解该变更的范围

43. 按照以下确切格式生成结构化的 token 级变更列表：

模板：

File Changes Made In This Change:
<token_type>   <file_name>:<line_number>   <symbol_name>   <[change_type]>

规则：

• Token 类型：function、constant、type、test、class、interface、enum 等。
• 变更类型：[added]、[modified]、[deleted]
• 行号：使用 "Ln " 前缀（例如，"Ln 234"）
• 仅限源目录：仅列出源目录中的条目（例如 src/、lib/）。排除配置文件、构建产物和生成的文件。
• 测试粒度：对于测试变更，仅列出 describe 块 token。不要列出单独的 it 或 test 用例——它们只会增加噪音而无价值。
• 不要合并：不要将多个变更总结或合并到一行。每个 token 各占一行。
• 排序：按变更类型排序（先 added，再 modified，然后 deleted）
• 对齐：列之间完美对齐，列间至少保留 3 个空格
• 无额外内容：仅提供上述模板——不要标题、不要摘要段落、不要说明

示例输出：

File Changes Made In This Change:
test       index.test.ts:Ln 234      ensureGrammar                [added]
test       index.test.ts:Ln 291      ensureGrammars               [added]
constant   language-constants.ts     EXTENSION_TO_LANGUAGE        [added]
constant   language-constants.ts     LANGUAGE_EXTENSIONS          [added]
function   index.ts:Ln 89            ensureGrammar                [added]
function   index.ts:Ln 112           ensureGrammars               [added]
function   scan.ts:Ln 45             detectLanguagesInFiles       [added]
type       errors.ts:Ln 12           AuditKitError                [modified]
function   errors.ts:Ln 65           formatError                  [modified]
function   index.test.ts:Ln 23       expectErrWithType            [modified]
constant   index.ts:Ln 15            LANGUAGE_MAP                 [modified]
constant   index.ts:Ln 28            SUPPORTED_EXTENSIONS         [modified]
function   index.ts:Ln 156           getWasmPath                  [modified]
function   scan.ts:Ln 632            executeScan                  [modified]
function   language-detection.ts     EXTENSION_TO_LANGUAGE        [deleted]

44. 在验证报告之后立即呈现文件变更摘要

输出：对齐、排序的 token 级变更列表，显示源代码中的所有新增、修改和删除