@rpamis/comet 0.3.9 → 0.4.0-beta.10

package/eval/local/skills/benchmarks/039-release/comet-classic-039/reference/subagent-dispatch.md

@@ -0,0 +1,113 @@
+# Comet Extensions for Subagent-Driven Development
+
+Canonical path: `comet/reference/subagent-dispatch.md`
+
+This document provides Comet-specific extensions applied **on top of** the Superpowers `subagent-driven-development` skill. The skill handles the core dispatch loop (fresh implementer per task → spec compliance review → code quality review → next task) and enforces continuous execution. This document adds Comet-specific real background dispatch, task tracking, state verification, and context recovery. If the Superpowers skill conflicts with this document, the more specific Comet constraints here take precedence.
+
+> **⚠️ CRITICAL — No Pause Between Tasks**
+>
+> After a task passes both reviews and is checked off, **immediately dispatch the next task** without stopping, summarizing, or asking the user whether to continue. The user expects all tasks to execute in sequence without manual intervention. Pausing between tasks breaks the workflow and requires the user to manually resume each time.
+>
+> Only stop and wait for user input when:
+> - A task is **BLOCKED** (3 review-fix rounds exhausted)
+> - There is irreducible ambiguity that cannot be resolved from the repository, plan, or existing context
+> - The platform lacks real background agent dispatch capability and the user must choose `executing-plans`
+> - The user **explicitly** asks to pause
+>
+> This rule applies to the ENTIRE dispatch loop, not just individual tasks.
+
+## Before Starting
+
+1. Read the plan once, extracting the full text of all unchecked tasks in order.
+2. Save a unique identifier for each task: the full task text after the checkbox in the plan, and the full OpenSpec task text it maps to (if any). If the text is not unique, stop and fix the plan first; never rely on "first match."
+3. Respect dependencies; do not dispatch a task whose dependencies are not yet complete.
+
+## Per-Task Comet Extensions
+
+Apply these on every task, in addition to the Superpowers skill's dispatch loop:
+
+### 0. Dispatch Enforcement (Critical)
+
+The main session is the **coordinator only** and must NOT execute tasks directly or modify source code. The coordinator may modify only the plan, OpenSpec task, and subagent progress checkpoint for durable tracking. Never bundle multiple tasks into one agent. Dispatch a fresh background implementer agent for every task; spec reviewers, code quality reviewers, fix agents, and the final reviewer must also each use a fresh background agent:
+
+- **Claude Code**: Use the `Agent` tool with `run_in_background: true` for each implementer, spec reviewer, code quality reviewer, fix agent, and final reviewer. Never execute tasks inline and do not accidentally enter team mode, which requires a pre-created team.
+- **Other platforms**: Use the platform's equivalent background agent / Task / multi-agent dispatch mechanism.
+- **Never** reuse implementers, reviewers, or fix agents across tasks or roles. Each agent gets a fresh, isolated context containing only the single task and role-specific context it needs.
+- If the platform has no real background dispatch capability, do not proceed; pause and wait for the user to choose `build_mode: executing-plans`.
+
+### 1. Dispatch Prompt and Return Contract
+
+Every implementer or fix-agent prompt must include:
+
+- The full text of the single current task, architecture background, and dependency context
+- `Language: Use the language of the user request that triggered this workflow`
+- The allowed file scope and prohibited modification scope
+- The required test commands and commit requirements
+- For a fix agent, the corresponding reviewer's complete feedback
+
+The agent return status must be `DONE | DONE_WITH_CONCERNS | BLOCKED | NEEDS_CONTEXT` and include implementation details, test results, commit hash, changed files, and concerns. Before review, the coordinator must verify that the commit and changed files are visible in the current worktree; on isolated-copy platforms, pull or merge the changes first.
+
+Every reviewer prompt must include the full task, the implementation commit or diff and the RED/GREEN evidence (when `tdd_mode: tdd`). A reviewer must not review from the implementer's summary alone.
+
+### 2. Implementer Scope Restriction
+
+The implementer is only responsible for implementation, testing, and committing code. **The implementer must not check off plan or OpenSpec tasks**, nor update only the built-in Todo or in-chat checklists.
+
+### 3. TDD Hard Constraint
+
+If `tdd_mode: tdd`, every implementer and fix agent must first use the Skill tool to load the Superpowers `test-driven-development` skill, and its prompt must also inject:
+
+```text
+You MUST follow TDD: write a failing test first, watch it fail, then write minimal code to pass. No production code without a failing test first.
+```
+
+The implementer or fix-agent return must provide **RED failure command and failure summary**, **GREEN pass command and pass summary**; missing either piece of evidence blocks entry into review. Both spec compliance reviewer and code quality reviewer must verify RED/GREEN evidence and test coverage.
+
+### 4. Durable Progress Checkpoint
+
+The coordinator must maintain `openspec/changes/<name>/.comet/subagent-progress.md` and update it immediately after every dispatch, agent return, review result, review-fix round change, and task checkoff. The checkpoint must record at least:
+
+- The unique current plan task text and mapped OpenSpec task text
+- Current stage: `implementing | spec-review | quality-review | checkoff | done | blocked | final-review | final-fix`
+- Implementation commit hash, changed files, and RED/GREEN evidence
+- Review stages already passed and unresolved reviewer feedback
+- The current task or final-review review-fix round (maximum 3)
+
+This file stores only coordinator recovery state and does not replace plan or OpenSpec checkboxes. Retain the final record when a task completes, then replace it with the next task's record when that task begins.
+
+### 5. Review-Fix Round Limit
+
+Each task allows at most 3 review-fix rounds. When either reviewer finds an issue, dispatch a fresh background fix agent and restart from the corresponding review. If the task still does not pass after 3 rounds, mark it **BLOCKED**, pause, and hand the accumulated feedback to the user.
+
+### 6. Task Checkoff and Verification
+
+**After both reviews pass**, the main session:
+
+1. Changes the saved unique task text from `- [ ]` to `- [x]` in the plan
+2. If a mapping exists, also checks off the OpenSpec task
+3. Commits this progress update
+4. Runs targeted verification:
+
+```bash
+"$COMET_BASH" "$COMET_STATE" task-checkoff "$PLAN_FILE" "$PLAN_TASK_TEXT"
+"$COMET_BASH" "$COMET_STATE" task-checkoff "openspec/changes/<name>/tasks.md" "$OPENSPEC_TASK_TEXT"
+```
+
+Run the second command only when the corresponding mapping exists. The script requires the task text to appear exactly once and be checked; verification failure blocks moving to the next task.
+
+## Wrap-up
+
+- **AUTO-CONTINUE**: After both reviews pass and the task is checked off, immediately dispatch the next unchecked task. Do NOT summarize, do NOT ask the user whether to continue, do NOT wait for user input between tasks. This is non-negotiable — the Superpowers skill enforces continuous execution, and the CRITICAL warning at the top of this document reinforces it.
+- After all tasks complete, switch the checkpoint to `final-review`, then dispatch a fresh background final code quality reviewer. For CRITICAL issues, switch the checkpoint to `final-fix`, record feedback and the round, dispatch a fresh background fix agent, and re-review. Final review also has a maximum of 3 rounds; when exhausted, mark the checkpoint `blocked` and pause. Non-CRITICAL findings may be accepted with rationale recorded in tasks.md.
+- After final review passes, only the subagent dispatch loop is complete, not the Comet workflow. The coordinator must not load `finishing-a-development-branch` or pause to ask what comes next; it must return control to `comet-build` for exit checks, the phase guard, and phase handoff.
+
+## Context Recovery
+
+Reload the Superpowers `subagent-driven-development` skill and re-read this document. Read `openspec/changes/<name>/.comet/subagent-progress.md`, then compare it with the first unchecked task and the current worktree:
+
+- When the checkpoint matches the unchecked task, resume from its exact recorded stage while preserving the implementation commit, RED/GREEN evidence, review stages already passed, unresolved feedback, and current review-fix round. Never reset the round or repeat an already passed stage.
+- When the checkpoint is missing or does not match the unchecked task, create a new checkpoint for the first unchecked task and begin with implementer dispatch.
+- When a recorded commit or file is not visible in the current worktree, pull, merge, or recover the corresponding changes before proceeding; never assume the implementation exists.
+- When all tasks are checked and the checkpoint stage is `final-review` or `final-fix`, resume the exact final-review stage while preserving final feedback and its review-fix round; never re-enter completed tasks.
+
+Tasks committed without dual-review approval remain unchecked and re-enter the review or fix loop according to the checkpoint.

package/eval/local/skills/benchmarks/039-release/comet-classic-039/rules/comet-phase-guard.md

@@ -0,0 +1,125 @@
+# Comet 阶段感知（防漂移规则）
+
+> 此规则每轮注入，防止长上下文时遗忘 Comet 流程状态。
+> Hook 平台额外执行 `comet-hook-guard.sh` 进行硬性拦截；
+> 此 Rule 是所有平台通用的软性防线。
+
+## 全局规则
+
+### 阶段感知（最高优先级）
+
+有活跃 comet change 时（`openspec/changes/<name>/.comet.yaml` 存在），**每次开始执行操作前**必须读取 `phase` 字段确认当前阶段。
+
+**阶段与允许操作：**
+
+| 阶段 | 允许 | 禁止 |
+|------|------|------|
+| `open` | 创建 proposal/design/tasks, 运行 guard | 写源代码 |
+| `design` | brainstorming, 创建 Design Doc, 运行 guard | 写源代码 |
+| `build` | 写源代码、测试、执行计划 | 跳过用户确认点 |
+| `verify` | 验证、branch handling | 跳过失败处理 |
+| `archive` | 确认归档、运行归档脚本 | 写源代码 |
+
+### 阶段进入自洽性校验（写源代码前必查）
+
+仅看 `phase` 字段不够——还必须确认"是如何到达这个阶段的"。每次准备写源代码前，先用下表自检 `.comet.yaml` 是否处于**非法空跳**状态（绕过了前置阶段）。命中任一行，立即停止写源代码，按动作回到对应阶段补齐产物，不得信任 `phase` 字段直接续跑。
+
+| 检测到 | 判定 | 动作 |
+|--------|------|------|
+| `phase: build` + `workflow: full` + `design_doc` 为空/null | 绕过 design 空跳 | 停止写源代码，运行 `/comet-design` 补 Design Doc 并过 guard |
+| `phase: build/verify` + proposal/design/tasks 任一缺失或为空 | 绕过 open 空跳 | 回 `/comet-open` 补齐三件套 |
+| `phase: archive` + `verify_result` ≠ `pass` | 绕过 verify 空跳 | 回 `/comet-verify` 完成验证 |
+
+预设例外：`workflow: hotfix/tweak` 本就跳过 design，`design_doc` 为空属正常，不算非法。
+
+### Skill 调用（不可用普通对话替代）
+
+以下操作必须通过 Skill 工具加载，Skill 不可用时应停止流程并提示安装：
+
+- **brainstorming** — design 阶段、build 阶段中等规模 spec 变更
+- **writing-plans** — build 阶段创建实现计划
+- **executing-plans** / **subagent-driven-development** — build 阶段执行
+- **test-driven-development** — `executing-plans` 由主会话在第一个 task 前加载；`subagent-driven-development` 由每个后台 implementer 和修复 agent 加载
+- **systematic-debugging** — 遇到崩溃/测试失败/构建失败时
+- **verification-before-completion** — verify 阶段
+- **using-git-worktrees** — build 阶段选择 worktree 隔离时
+
+### 脚本执行（不可跳过）
+
+- **阶段退出**: `comet-guard <name> <phase> --apply`（必须看到 ALL CHECKS PASSED）
+- **压缩恢复**: `comet-state check <name> <phase> --recover`
+- **状态更新**: 关键操作后通过 `comet-state set` 更新字段，禁止手工编辑 .comet.yaml
+- **阶段推进只能经 guard/transition**: 禁止用 `comet-state set <name> phase <值>` 手动跳阶段（会绕过证据校验，脚本已硬拦截）；确需修复畸形状态时才用 `COMET_FORCE_PHASE=1` 逃生阀
+- **handoff 生成**: `comet-handoff <name> design --write`（禁止手写摘要）
+
+### 用户确认（不可自动跳过）
+
+以下决策点必须暂停等待用户明确选择，不得根据推荐规则自动填写：
+
+- **open**: 需求澄清完成确认、artifact 评审确认
+- **design**: brainstorming 方案确认（确认前不得创建 Design Doc）
+- **build**: plan-ready 暂停、isolation/build_mode/tdd_mode 选择、spec 大规模变更确认
+- **verify**: 验证失败处理策略、branch handling 选择
+- **archive**: 归档前最终确认
+
+## Design 阶段专项
+
+1. 第一个脚本操作 = `comet-handoff <name> design --write`（未生成 handoff 禁止加载 brainstorming）
+2. brainstorming in progress: incrementally update brainstorm-summary.md（每轮澄清或方案迭代后增量更新恢复检查点，未确认内容标注为待确认/候选）
+3. brainstorming 完成后下一步 = brainstorm-summary.md 定稿 → Design Doc → guard
+4. active compaction gate: brainstorm-summary.md 定稿后、创建 Design Doc 前，优先触发宿主平台原生上下文压缩；无法程序化触发时暂停提示用户手动压缩或确认继续
+5. **绝对不能直接开始写实现代码** — 必须先创建 Design Doc 并通过 guard
+
+## Build 阶段专项
+
+1. plan 创建后必须询问用户选择继续或暂停（`build_pause` 机制）
+2. 每个 task 验收后必须: tasks.md 打勾 → git commit（不得积攒）。`subagent-driven-development` 必须等 spec compliance 与 code quality 两个审查都通过，再由协调者按任务唯一文本定向勾选和验证；不得用未完成任务总表代替当前任务验证
+3. 遇到失败必须加载 **systematic-debugging** skill，根因未定位前不得提出源码修复
+4. spec 变更分级: 小改直接编辑 | 中改加载 brainstorming | 大改暂停等用户确认拆分
+
+## Verify 阶段专项
+
+1. 第一步运行 `comet-state scale <name>` 确定验证级别
+2. 验证失败后列出失败项等用户选择，CRITICAL 必须修
+3. 连续 3 次失败后必须让用户选择接受偏差或继续修
+
+## 上下文压缩恢复
+
+如果怀疑发生上下文压缩（之前对话被摘要、找不到之前讨论的内容），立即运行：
+
+```bash
+"$COMET_BASH" "$COMET_STATE" check <name> <phase> --recover
+```
+
+按脚本输出的 **Recovery action** 决定下一步。
+
+恢复后必须先用「阶段进入自洽性校验」表复查一遍：若发现 `phase` 与产物不自洽（design_doc/三件套/verify_result 任一不匹配），按非法空跳处理，回对应阶段补齐，不得信任 `phase` 字段直接续跑。
+
+**特别注意 `build_mode`**：若恢复脚本输出 `build_mode: subagent-driven-development`，你是协调者，不是执行者。必须：
+1. 使用 Skill 工具重新加载 Superpowers `subagent-driven-development` 技能 (Use the Skill tool to reload the Superpowers `subagent-driven-development` skill)
+2. 读取 `comet/reference/subagent-dispatch.md` 获取 Comet 专属扩展 (re-read `comet/reference/subagent-dispatch.md` for Comet-specific extensions)
+3. 读取 `openspec/changes/<name>/.comet/subagent-progress.md` 恢复精确阶段、证据和审查-修复轮次 (Read `openspec/changes/<name>/.comet/subagent-progress.md` to recover the exact stage, evidence, and review-fix round)
+4. 禁止在主会话中直接执行 task (Do not execute the pending task directly in the main window)
+5. 按检查点恢复；缺失或不匹配时才从第一个未勾选 task 开始
+6. 已提交但未通过双审查的 task 保持未勾选，继续审查/修复循环
+7. task 通过双审查和定向勾选验证后立即继续下一个 task，不得总结或询问是否继续
+
+## 阶段退出后自动过渡
+
+guard `--apply` 成功后，不得在本规则中硬编码下一阶段 skill。必须先运行：
+
+```bash
+comet-state next <change-name>
+```
+
+若已通过 `comet-env.sh` 定位脚本，等价运行：
+
+```bash
+"$COMET_BASH" "$COMET_STATE" next <change-name>
+```
+
+按脚本输出决定下一步：
+
+- `NEXT: auto` → 使用 Skill 工具加载 `SKILL` 指向的 skill
+- `NEXT: manual` → 不加载下一 skill，按 `HINT` 提示用户手动继续
+- `NEXT: done` → 流程已完成，无需继续

package/eval/local/skills/benchmarks/039-release/comet-classic-039-archive/SKILL.md

@@ -0,0 +1,100 @@
+---
+name: comet-archive
+description: "Comet Phase 5: Archive. Invoke with /comet-archive. Merge delta specs into main specs with OpenSpec semantics, archive change."
+---
+
+# Comet Phase 5: Archive (Archive)
+
+## Prerequisites
+
+- Verification passed (Phase 4 complete)
+- Branch handled
+- `verify_result: pass` in `openspec/changes/<name>/.comet.yaml`
+
+## Steps
+
+### 0. Output Language Constraint
+
+Archive summaries and lifecycle closure notes must use the language of the user request that triggered this workflow.
+
+### 0. Entry State Verification (Entry Check)
+
+Execute entry verification:
+
+```bash
+COMET_ENV="${COMET_ENV:-$(find . "$HOME"/.*/skills "$HOME/.config" "$HOME/.gemini" -path '*/comet/scripts/comet-env.sh' -type f -print -quit 2>/dev/null)}"
+if [ -z "$COMET_ENV" ]; then
+  echo "ERROR: comet-env.sh not found. Ensure the comet skill is installed." >&2
+  return 1
+fi
+. "$COMET_ENV"
+"$COMET_BASH" "$COMET_STATE" check <name> archive
+```
+
+Proceed to Step 1 after verification passes. The script outputs specific failure reasons when verification fails.
+
+### 1. Final Archive Confirmation (Blocking Point)
+
+After entry verification passes, **must follow the `comet/reference/decision-point.md` protocol to pause and wait for the user to confirm whether to archive immediately**. Must not run `"$COMET_BASH" "$COMET_ARCHIVE" "<change-name>"` before user confirmation.
+
+Before confirmation, show the user a brief summary:
+- Change name
+- Verification report path and result
+- Branch handling status
+- Irreversible actions this archive will perform: merge main specs with OpenSpec delta semantics, annotate design doc / plan, and move the change to the archive directory
+
+The user confirmation question must be presented as a single-select question with these options:
+- "Confirm archive" — immediately run the archive script to complete spec merge and change movement
+- "Needs adjustment or re-verification" — do not archive; run `"$COMET_BASH" "$COMET_STATE" transition <change-name> archive-reopen` to return to `phase: verify`, then invoke `/comet-verify`. If verification confirms fixes are needed, follow `/comet-verify`'s verification-failure decision flow back to `/comet-build`
+- "Do not archive yet" — do not archive; keep the current `phase: archive` state and wait for the user to invoke `/comet-archive` again later
+
+Only after the user selects "Confirm archive" may Step 2 continue. After the user selects "Needs adjustment or re-verification", must first run the `archive-reopen` state transition; do not edit `.comet.yaml` manually.
+
+### 2. Execute Archive
+
+Run the archive script to automatically complete all steps:
+
+```bash
+"$COMET_BASH" "$COMET_ARCHIVE" "<change-name>"
+```
+
+The script automatically executes:
+1. Entry state validation (phase=archive, verify_result=pass, archived=false)
+2. Design doc frontmatter annotation (archived-with, status)
+3. Plan frontmatter annotation (archived-with)
+4. OpenSpec archive for delta-merge semantics and moving the change to the archive directory
+5. Main spec guard against leaked delta-only section headings
+6. Update `archived: true` through `comet-state transition <archive-name> archived`
+
+If script returns non-zero exit code, report error and stop.
+If script returns zero exit code, archive is complete.
+The summary `X/Y steps succeeded` counts real executed steps and does not double-count delta spec sync or document annotation.
+
+The script calls OpenSpec archive to merge `ADDED/MODIFIED/REMOVED/RENAMED` delta semantics into main specs, then verifies main specs do not contain delta-only section headings.
+
+Use `--dry-run` flag to preview without executing.
+
+### 3. Lifecycle Closed Loop
+
+Spec lifecycle completes here:
+```
+brainstorming → delta spec → implementation → verification → main spec merge → design doc annotation → archive
+```
+
+## Exit Conditions
+
+- Archive script executed successfully (exit code 0)
+- Archive directory `openspec/changes/archive/YYYY-MM-DD-<change-name>/` exists
+- Archived `.comet.yaml` contains `archived: true`
+
+The archive script moves `openspec/changes/<name>/` to `openspec/changes/archive/YYYY-MM-DD-<name>/`.
+
+> **WARNING**: After successful archive, **do not run** `"$COMET_BASH" "$COMET_GUARD" <change-name> archive` against the old active change name; the active directory no longer exists. Doing so will cause the guard to error with "change directory not found". Archive completeness is determined by script exit code and archived directory state.
+
+## Complete
+
+Comet workflow complete. To start new work, invoke `/comet` or `/comet-open`.
+
+## Context Compression Recovery
+
+Follow `comet/reference/context-recovery.md` with phase set to `archive`. If `archived: true` and archive directory exists, archival is complete — do not re-execute archive operations.

package/eval/local/skills/benchmarks/039-release/comet-classic-039-build/SKILL.md

@@ -0,0 +1,304 @@
+---
+name: comet-build
+description: "Comet Phase 3: Plan and Build. Invoke with /comet-build. Create plans and select execution method (subagent or direct) for implementation."
+---
+
+# Comet Phase 3: Plan and Build (Build)
+
+## Prerequisites
+
+- Design Doc has been created (Phase 2 complete)
+- Active change exists
+
+## Steps
+
+### 0. Entry State Verification (Entry Check)
+
+Execute entry verification:
+
+```bash
+COMET_ENV="${COMET_ENV:-$(find . "$HOME"/.*/skills "$HOME/.config" "$HOME/.gemini" -path '*/comet/scripts/comet-env.sh' -type f -print -quit 2>/dev/null)}"
+if [ -z "$COMET_ENV" ]; then
+  echo "ERROR: comet-env.sh not found. Ensure the comet skill is installed." >&2
+  return 1
+fi
+. "$COMET_ENV"
+"$COMET_BASH" "$COMET_STATE" check <name> build
+```
+
+Proceed to Step 1 after verification passes. The script outputs specific failure reasons when verification fails.
+
+**Idempotency**: All build phase operations can be safely re-executed. Read `.comet.yaml` `phase` field to confirm still in build, read plan header `base-ref`, then use `grep -n '\- \[ \]' tasks.md | head -1` to find the first unchecked task. Already-committed tasks must not be re-committed.
+
+### 1. Create Plan (Subagent Offload)
+
+Create the implementation plan through a subagent, avoiding planning skill occupying main session context. Plan files and execution feedback must use the language of the user request that triggered this workflow.
+
+**Subagent instructions**:
+
+You are an implementation planning expert. Create an implementation plan based on the following inputs:
+
+1. **Immediately execute:** Use the Skill tool to load the Superpowers `writing-plans` skill. Skipping this step is prohibited. After the skill loads, ARGUMENTS must include: `Language: Use the language of the user request that triggered this workflow`
+2. Read the Design Doc (technical design document under `docs/superpowers/specs/`)
+3. Read `openspec/changes/<name>/tasks.md` (task boundaries)
+4. Follow the skill's guidance to create the plan
+
+Plan requirements:
+- Save to `docs/superpowers/plans/YYYY-MM-DD-<feature>.md`
+- Reference design document, break down into executable tasks
+- **Plan file header must contain associated metadata**:
+
+```yaml
+---
+change: <openspec-change-name>
+design-doc: docs/superpowers/specs/YYYY-MM-DD-<topic>-design.md
+base-ref: <git rev-parse HEAD before implementation>
+---
+```
+
+`base-ref` is used during verification to measure committed changes across the full implementation range. Record the current commit when creating the plan:
+
+```bash
+git rev-parse HEAD
+```
+
+Write the plan to file, then return the file path.
+
+**Execute subagent**: Use the current platform's subagent dispatch mechanism to send the above task.
+
+After the subagent completes:
+- If a valid file path is returned and the file exists, record it as the plan
+- If the subagent fails or returns an invalid path, fall back to loading the Superpowers `writing-plans` skill inline in the main session (degraded fallback)
+
+### 2. Update Plan Status and Provide Plan-Ready Pause Point
+
+Record plan path:
+
+```bash
+"$COMET_BASH" "$COMET_STATE" set <name> plan docs/superpowers/plans/YYYY-MM-DD-feature.md
+```
+
+No manual phase update needed — guard auto-transitions when exit conditions are met.
+
+After the plan is recorded, immediately provide a new user decision point:
+
+| Option | Behavior | Description |
+|--------|----------|-------------|
+| A | Continue execution | Stay in the current model and proceed to Step 3 to choose workspace isolation and execution method |
+| B | Pause to switch model | Record `build_pause: plan-ready`, stop this `/comet-build` invocation, and allow the user to resume later from `/comet` or `/comet-build` |
+
+This is a user decision point. **Must follow the `comet/reference/decision-point.md` protocol to pause and wait for the user to explicitly choose**. Must not auto-continue and must not write the pause into `build_mode`.
+
+When the user chooses to continue:
+
+```bash
+"$COMET_BASH" "$COMET_STATE" set <name> build_pause null
+```
+
+When the user chooses to pause:
+
+```bash
+"$COMET_BASH" "$COMET_STATE" set <name> build_pause plan-ready
+```
+
+After setting `build_pause: plan-ready`, stop the current invocation. Do not choose `isolation` or `build_mode`, and do not load an execution skill.
+
+### 3. Select Workflow Configuration
+
+If resuming with `build_pause: plan-ready` and the `plan` file exists, do not rerun `writing-plans`. First tell the user the workflow is stopped at the plan-ready pause point; after the user confirms continuing, set:
+
+```bash
+"$COMET_BASH" "$COMET_STATE" set <name> build_pause null
+```
+
+Then continue this step to choose workspace isolation and execution method.
+
+Plan has been written to the current branch. Before starting execution, **ask the user to choose both workspace isolation and execution method in a single interaction**:
+
+**Workspace Isolation**:
+
+| Option | Method | Description |
+|--------|--------|-------------|
+| A | Create branch | Create a new branch in the current repo, simple and fast |
+| B | Create Worktree | Isolated workspace, fully independent, suitable for parallel development |
+
+**Recommendation rules**:
+- Change involves ≤ 3 files → Recommend A
+- Need parallel development, current branch has uncommitted work → Recommend B
+
+**Execution Method**:
+
+| Option | Skill | Applicable Scenario |
+|------|------|-------------------|
+| A | Superpowers `subagent-driven-development` | Independent tasks, high complexity, requires two-phase review |
+| B | Superpowers `executing-plans` | Simple tasks, no subagent environment, lightweight and fast |
+
+**Execution method recommendation rules**:
+- Task count ≥ 3 → Recommend A
+- Task count ≤ 2 and no cross-module dependencies → Recommend B
+- From hotfix path → Recommend B
+
+This is a user decision point. **Must follow the `comet/reference/decision-point.md` protocol to pause and wait for the user to explicitly choose isolation method, execution method, and TDD mode**. Must not choose `branch` or `worktree` based on recommendation rules, and must not choose the execution method or TDD mode based on recommendation rules. Recommendation rules are for suggestion only, not a substitute for user confirmation.
+
+After user selection, update `isolation`, execution method, and TDD mode fields:
+
+```bash
+"$COMET_BASH" "$COMET_STATE" set <name> isolation <branch|worktree>
+```
+
+- If the user chooses `executing-plans`: run `"$COMET_BASH" "$COMET_STATE" set <name> subagent_dispatch null`, then run `"$COMET_BASH" "$COMET_STATE" set <name> build_mode executing-plans`
+- If the user chooses `subagent-driven-development`: first confirm the current platform has real background subagent / Task / multi-agent dispatch capability; after confirming, run `"$COMET_BASH" "$COMET_STATE" set <name> subagent_dispatch confirmed`, then run `"$COMET_BASH" "$COMET_STATE" set <name> build_mode subagent-driven-development`
+- If real background dispatch capability cannot be confirmed, must not write `build_mode: subagent-driven-development`; must pause and wait for the user to choose `executing-plans` instead
+
+**TDD Mode**:
+
+| Option | Meaning | Applicable Scenario |
+|--------|---------|---------------------|
+| `tdd` | Write a failing test first for each task, then implement | Recommended. Changes involving business logic, new features, APIs |
+| `direct` | Implement directly, no enforced TDD flow | Changes that don't need test coverage, or user chooses to skip tests and write code directly. hotfix/tweak presets default to `direct` |
+
+Run `"$COMET_BASH" "$COMET_STATE" set <name> tdd_mode <tdd|direct>`
+
+`isolation` is a script-enforced hard constraint. Full workflow init may temporarily leave it as `null`, but only before this step. If it remains `null`, both the `build → verify` guard and `comet-state transition build-complete` will fail.
+
+`subagent_dispatch` is a script-enforced hard constraint. `build_mode: subagent-driven-development` requires `subagent_dispatch: confirmed` before leaving the build phase, otherwise both `comet-guard.sh build --apply` and `comet-state transition build-complete` will fail.
+
+`tdd_mode` is a script-enforced hard constraint. Full workflow must have `tdd_mode` selected as `tdd` or `direct` before leaving the build phase, otherwise both `comet-guard.sh build --apply` and `comet-state transition build-complete` will fail.
+
+`build_mode` defaults to `direct` only for hotfix/tweak presets. Full workflow must not default to `direct`. Use it only when the user explicitly asks to bypass the plan execution skills and you record an explicit override:
+
+```bash
+"$COMET_BASH" "$COMET_STATE" set <name> direct_override true
+"$COMET_BASH" "$COMET_STATE" set <name> build_mode direct
+```
+
+Without `direct_override: true`, `build_mode=direct` in full workflow is blocked by both guard and state transition.
+
+**Execute isolation**:
+
+- **branch**: Recommend a branch name based on the workflow type and current date, then let the user confirm or input a custom name. This is a user decision point — **must use the current platform's available user input/confirmation mechanism to pause and wait for the user to explicitly confirm or override the branch name**. Must not skip this step and create the branch directly.
+
+  Branch naming convention:
+  - Read the `workflow` field from `.comet.yaml` to determine the prefix
+  - `workflow: full` → recommend `feature/YYYYMMDD/<change-name>`
+  - `workflow: hotfix` → recommend `hotfix/YYYYMMDD/<change-name>`
+  - `workflow: tweak` → recommend `tweak/YYYYMMDD/<change-name>`
+  - Date is derived from `date +%Y%m%d` at runtime
+
+  Example: if change name is `fix-login-bug` and today is 2026-06-09, recommend `feature/20260609/fix-login-bug`
+
+  After the user confirms or provides a custom branch name, run `git checkout -b <branch-name>`, subsequent work on the new branch.
+
+- **worktree**: Must use the Skill tool to load the Superpowers `using-git-worktrees` skill to create isolated workspace. Do not bypass this skill with plain shell commands or native tools; if the skill is unavailable, stop the process and prompt to install or enable Superpowers skills.
+
+After creating isolation, confirm plan file is accessible (naturally accessible with branch method; for worktree method, confirm plan has been committed). If the plan file has not been committed under worktree mode, commit it first before creating the worktree:
+
+```bash
+git add docs/superpowers/plans/YYYY-MM-DD-feature.md
+git commit -m "chore: add implementation plan"
+```
+
+**Execute plan**: Must handle execution according to the actual runtime of `build_mode`.
+
+- `build_mode: executing-plans`: **Immediately execute:** Use the Skill tool to load the Superpowers `executing-plans` skill. Skipping this step is prohibited. If the skill is unavailable, stop the process and prompt to install or enable the corresponding skill; do not substitute with normal conversation. After the skill loads, ARGUMENTS must include the same Language constraint as Step 1: `Language: Use the language of the user request that triggered this workflow`. Execute according to plan.
+- `build_mode: subagent-driven-development`: The main session only coordinates and must not write implementation code directly. **Immediately execute:** Use the Skill tool to load the Superpowers `subagent-driven-development` skill. After the skill loads, read `comet/reference/subagent-dispatch.md` for Comet-specific extensions (real background dispatch, task isolation, checkoff verification, TDD constraints, continuous execution, context recovery) and apply them alongside the skill's workflow. If they conflict, the more specific Comet extensions take precedence.
+- If the current platform has no real background agent dispatch capability, must pause and wait for the user to choose main window execution instead. After the user chooses, must run `"$COMET_BASH" "$COMET_STATE" set <name> build_mode executing-plans`, then follow the `build_mode: executing-plans` branch to load the Superpowers `executing-plans` skill. Must not continue executing tasks before the user explicitly chooses.
+
+**TDD Mode Execution Constraints**:
+
+If `tdd_mode: tdd`:
+- `build_mode: executing-plans`: After loading the execution skill and before executing the first task, **Immediately execute:** Use the Skill tool to load the Superpowers `test-driven-development` skill once. Skipping this step is prohibited. After the skill loads, start from the first unchecked task and follow the loaded TDD Red-Green-Refactor cycle for each task. Must not skip the failing test verification phase. Do not reload this skill for subsequent tasks; follow the already-loaded flow. If resuming after context compaction, re-run this step to load the TDD skill once, then continue from the first unchecked task.
+- `build_mode: subagent-driven-development`: The main session does not load the TDD skill. TDD constraints and evidence thresholds are defined in `comet/reference/subagent-dispatch.md`; every background implementer and fix agent must use the Skill tool to load the Superpowers `test-driven-development` skill and follow the Comet-injected TDD hard constraint.
+
+If `tdd_mode: direct`: Follow normal flow, no enforced TDD.
+
+**`executing-plans` review gate**:
+
+When `build_mode` is `executing-plans`, after all planned tasks are complete and before running the build → verify phase guard, must use the Skill tool to load the Superpowers `requesting-code-review` skill and request code review at least once.
+
+Requirements:
+- the `requesting-code-review` skill must be loaded before `"$COMET_BASH" "$COMET_GUARD" <change-name> build --apply`
+- if `requesting-code-review` skill is unavailable, skip the review gate but must record `<!-- review skipped: skill unavailable -->` in tasks.md, then continue guard transition
+- CRITICAL review findings (security vulnerabilities, data loss risk, build/test failures) must be fixed first and must not be carried into verify
+- if non-CRITICAL review findings are accepted, record the acceptance reason and impact scope in tasks.md, the commit body, a verification report draft, or another durable artifact
+
+### 3b. In-Execution Debugging (Debug Gate)
+
+During task execution, whenever a crash, unexpected behavior, test failure, or build failure appears while running the program, tests, build, or manual verification, must use the Skill tool to load the Superpowers `systematic-debugging` skill. Before root-cause investigation is complete, must not propose or implement source-code fixes.
+
+For specific investigation, minimal failing test, fix verification, and keeping the current change verification loop, follow `comet/reference/debug-gate.md`.
+
+### 4. Spec Incremental Updates
+
+When the initial spec is found incomplete during implementation, handle by scale:
+
+| Scale | Trigger Conditions | Approach |
+|------|-------------------|----------|
+| Small | Missing acceptance scenarios, edge cases | Directly edit delta spec + design.md, append tasks.md tasks |
+| Medium | Interface changes, new components, data flow changes | **Must use the current platform's available user input/confirmation mechanism to pause and wait for the user to explicitly confirm**, then must use Skill tool to load the Superpowers `brainstorming` skill to update Design Doc + delta spec |
+| Large | Brand-new capability requirements | **Must use the current platform's available user input/confirmation mechanism to pause and wait for the user to explicitly confirm the split**; after user confirms, create independent change through `/comet-open` |
+
+**50% Threshold Determination**: Using initial task count in tasks.md as baseline, if new tasks exceed half of that total, it's considered outside original plan scope, **must follow the `comet/reference/decision-point.md` protocol to pause and wait for the user to decide whether to split into a new change**.
+
+When creating an independent change, must invoke `/comet-open`, not `/opsx:new` directly. `/comet-open` creates both OpenSpec artifacts and `.comet.yaml`, preventing the new change from leaving the Comet state machine.
+
+**User choices must include**:
+- "Split into new change" — create independent change via `/comet-open`
+- "Continue in current change" — record scope-expansion decision, update tasks.md and delta spec, then continue
+
+**Principles**:
+- Delta spec is a living document, can be modified at any time during this phase
+- Each update should be committed with commit message explaining the change reason
+- Do not sync to main spec in advance, sync uniformly during archiving
+- For small-scale incremental direct delta spec edits, note in commit message to facilitate design doc drift assessment during archiving
+
+### 5. Context Management
+
+Build is the longest phase and may span many tasks. To support resume after context compaction:
+
+- **After each task**: complete acceptance per the current execution branch before checking off and committing. `subagent-driven-development` must wait for both reviews to pass and perform targeted verification by unique task text. Use `grep -c '\- \[ \]' tasks.md` to check remaining unchecked count; no need to re-read the entire file
+- **Context compression recovery**: Follow `comet/reference/context-recovery.md` with phase set to `build`.
+- **User manual-change resume**: handle uncommitted changes through `comet/reference/dirty-worktree.md`. That protocol defines checks, attribution, and prohibitions. Build-specific handling:
+  1. After attribution, if the diff implies plan or spec changes, handle it through Step 4 "Spec Incremental Updates"
+- **Long task split**: if a single task exceeds 200 lines of code changes, consider splitting it into multiple subtasks and commits
+
+## Exit Conditions
+
+- All tasks.md checked
+- Code committed
+- Project-specific build/tests explicitly run and pass; do not rely only on guard auto-detection
+- `isolation` has been written as `branch` or `worktree`
+- `build_mode` has been written as `subagent-driven-development`, `executing-plans`, or `direct` with explicit override; if `subagent-driven-development`, `subagent_dispatch` must be `confirmed`
+- `tdd_mode` has been written as `tdd` or `direct`
+- If `build_mode` is `executing-plans`, the Skill tool has been used to load the Superpowers `requesting-code-review` skill and request code review at least once, and CRITICAL review findings have been fixed or acceptance rationale for non-CRITICAL review findings has been recorded
+- **Phase guard**: Run `"$COMET_BASH" "$COMET_GUARD" <change-name> build --apply`; after all PASS, state advances to `phase: verify`
+
+Guard reads project command configuration first:
+
+```yaml
+build_command: <build command>
+verify_command: <verify command>
+```
+
+Configuration can live in the change `.comet.yaml`, or in repo-root `.comet.yaml` / `comet.yaml` / `.comet.yml` / `comet.yml`.
+Only when no command is configured does guard fall back to `npm run build`, Maven, or Cargo auto-detection. When a command fails, guard prints the command output as evidence for debugging.
+
+Before exit, run guard to auto-transition:
+
+```bash
+"$COMET_BASH" "$COMET_GUARD" <change-name> build --apply
+```
+
+State file is automatically updated to `phase: verify`, `verify_result: pending`.
+
+## Automatic Handoff to Next Phase
+
+Follow `comet/reference/auto-transition.md`. Key command:
+
+```bash
+"$COMET_BASH" "$COMET_STATE" next <change-name>
+```
+
+- `NEXT: auto` → invoke the skill pointed to by `SKILL` to enter the next phase
+- `NEXT: manual` → do not invoke the next skill; prompt user to run `/<SKILL>` manually
+- `NEXT: done` → workflow is complete, no further action needed