@rpamis/comet 0.3.9 → 0.4.0-beta.2

package/assets/skills/comet-any/reference/subagents/workflow-entry-author.md

@@ -0,0 +1,100 @@
+# Workflow Entry Author Subagent
+
+This file is a portable lane brief, not a platform-native custom agent. If you need a Claude Code custom agent, generate a separate platform agent resource with frontmatter.
+
+## Responsibilities
+
+Write the generated Skill's entry `SKILL.md`. The entry owns the entry point, recovery, main router explanation, and user pause points; it must not turn the Node route table into an execution checklist that immediately triggers multiple Skills.
+
+Must cover:
+
+- entry Skill
+- Entry guidance for workflow-state / workflow-guard / workflow-handoff
+- `workflow-entry` claim
+
+## Authored Zone (what you write)
+
+The generator composes the entry SKILL.md from a deterministic **Auto zone** (frontmatter, Workflow Nodes route table, Skill Bindings, Guardrails And Evidence, Runtime And Recovery) plus an **Authored zone** (`## Decision Core`) that YOU write. You do NOT write the whole file — only the Decision Core body. The main session records your output via `comet creator authoring-record <name> --lane workflow-entry --file <out.json>`; the artifact `content` for `SKILL.md` is the Decision Core body.
+
+Quality bar: the `comet/SKILL.md` Decision Core (see `reference/authored-zone-example.md` for a full entry Decision Core example at the expected level). Author agent-readable decision rules — the Auto zone already handles mechanical routing via `workflow-state.mjs next`, so focus on judgment:
+
+- **Semantic current-Node detection** — how to determine which Node the user is in, beyond just running the script. Model comet's Step 0 (detect intent from user message, check Node order, handle "belongs to earlier/later Node" conflicts) + Step 1 (read state, trust files over stale state).
+- **Resume and drift rules** — what to do when context resumes (re-detect from scratch, never trust conversation history), when state says DONE but artifacts are missing, when the user's topic shifts mid-Node.
+- **Decision points** — explicit table of situations that MUST pause for user confirmation (first invocation scope, ambiguous Node, user approval required, guard failure).
+- **Red flags** — the "agent thought → actual risk" pattern that catches self-deception (e.g., "user mentioned the topic so research is confirmed" → mentioning ≠ confirming).
+
+A Decision Core without these four sections is a stub, not a Decision Core. The entry is the most-loaded file — it is what makes the Skill feel intelligent or mechanical.
+
+The Node route table in the Auto zone is reference only — do not duplicate it as an execution checklist, and do not issue multiple immediate Skill loads.
+
+## Inputs
+
+Read the common input from the main session, especially:
+
+- The user-confirmed goal, language, and Node labels.
+- Node order, Required Skill Calls, and recovery paths from
+  `reference/workflow-protocol.json`.
+- The script author's `status`, `init`, `next`, `NEXT:`, `SKILL:`, and guard contracts.
+- The open / design / build / verify / archive boundary that must be preserved when users customize existing Comet Skills.
+
+Use file handoff: the main session provides paths instead of pasting large bodies of text. Do not inherit main-session history; use only this brief, common input, script contracts, and reference evidence.
+
+## Dispatch Template
+
+Use the current platform's subagent mechanism. The shape should include:
+
+```text
+description: "Write the workflow entry for <bundle-name>"
+model: <must explicitly specify model>
+prompt:
+  You are the workflow entry author subagent.
+  First read this brief, the common input path, script contract path, workflow protocol path, and report file path.
+  Start by asking questions: if startup routing, recovery paths, current-Node detection, or user pause points are unclear, return NEEDS_CONTEXT.
+  Do not guess or fill in missing flow details.
+  Only write the entry SKILL.md draft; do not write internal Node Skills, Bundle state, or execute candidate scripts.
+  The Decision Core MUST include four subsections: ### Automatic Node Detection (Step 0 intent detection + Step 1 state read + resume rules), ### Decision Points (explicit pause table), ### Red Flags (agent thought → actual risk table). A Decision Core without these is a stub.
+  Write the full entry draft to the report file path and return only a status summary of 15 lines or fewer.
+```
+
+## Output Requirements
+
+The entry draft must show:
+
+- On entry, first read workflow state instead of directly loading a Node Skill.
+- If not started, initialize state before querying `next`.
+- Only after scripts output `NEXT: auto` and `SKILL: <node-skill>` should the agent load that single Node Skill.
+- The Node route table is reference only; it must not use "immediately execute" or "must load" execution directives.
+- When users customize existing Comet Skills, the entry must list Required Skill Calls as Node-local obligations,
+  not as an immediate execution checklist.
+- User pause points, recovery paths, and reference files are visible.
+- When users customize existing Comet Skills, preserve the open / design / build / verify / archive main path and Guardrails.
+
+Forbidden:
+
+- Multiple `**Immediate:**` or `**Execute now:**` generated Node Skill loads in entry `SKILL.md`.
+- Copying full source Skill bodies.
+- Provider prefixes.
+- Leaking audit reports, source hashes, or internal metadata into user-visible `SKILL.md`.
+
+## Self-Check
+
+Before returning, check:
+
+- The Decision Core has all four required subsections: Automatic Node Detection, Decision Points, Red Flags, and either Error Handling or Resume Rules.
+- The entry has exactly one main router startup protocol.
+- The entry has no immediate-load checklist for Node Skills.
+- The Node route is reference, not execution steps.
+- Automatic advancement references script outputs `NEXT:` and `SKILL:`.
+- User-visible English prose is consistent and does not mix in Chinese process sentences.
+
+## Required Claim
+
+- `workflow-entry`
+
+Missing this claim must block Skill review.
+
+## Status Return
+
+Status must be one of `DONE`, `DONE_WITH_CONCERNS`, `NEEDS_CONTEXT`, or `BLOCKED`.
+
+Write the full report to the report file path. The summary returned to the main session must be 15 lines or fewer and include status, report path, claims, unresolved concerns, and recommended rework. If status is `BLOCKED` or `NEEDS_CONTEXT`, state exactly what context is missing, what was tried, and what the main session should do.

package/assets/skills/comet-archive/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: comet-archive
-description: "Comet Phase 5: Archive. Invoke with /comet-archive. Merge delta specs into main specs with OpenSpec semantics, archive change."
+description: "Use when a Comet change has passed verification and needs archive confirmation, delta spec merge, or archive-phase recovery."
 ---
 
 # Comet Phase 5: Archive (Archive)
@@ -15,27 +15,21 @@ description: "Comet Phase 5: Archive. Invoke with /comet-archive. Merge delta sp
 
 ### 0. Output Language Constraint
 
-Archive summaries and lifecycle closure notes must use the language of the user request that triggered this workflow.
+Archive summaries and lifecycle closure notes must use the configured Comet artifact language from `"$COMET_BASH" "$COMET_STATE" get <name> language`.
 
 ### 0. Entry State Verification (Entry Check)
 
-Execute entry verification:
+Locate scripts via `comet/reference/scripts.md`, then run entry verification. When resuming from any entry point, first run the recovery check in `comet/reference/context-recovery.md`:
 
 ```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
+node "$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.
+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 `node "$COMET_ARCHIVE" "<change-name>"` before user confirmation.
 
 Before confirmation, show the user a brief summary:
 - Change name
@@ -45,7 +39,7 @@ Before confirmation, show the user a brief summary:
 
 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`
+- "Needs adjustment or re-verification" — do not archive; run `node "$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.
@@ -55,7 +49,7 @@ Only after the user selects "Confirm archive" may Step 2 continue. After the use
 Run the archive script to automatically complete all steps:
 
 ```bash
-"$COMET_BASH" "$COMET_ARCHIVE" "<change-name>"
+node "$COMET_ARCHIVE" "<change-name>"
 ```
 
 The script automatically executes:
@@ -64,7 +58,7 @@ The script automatically executes:
 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`
+6. Update archived state in the actual OpenSpec archive directory and reconcile pending recovery metadata
 
 If script returns non-zero exit code, report error and stop.
 If script returns zero exit code, archive is complete.
@@ -81,6 +75,22 @@ Spec lifecycle completes here:
 brainstorming → delta spec → implementation → verification → main spec merge → design doc annotation → archive
 ```
 
+### 4. Commit the Archive Changes
+
+The archive script only moves files and merges the spec; it does not commit. After archiving, the worktree holds these uncommitted changes:
+- The change directory moved from `openspec/changes/<name>/` to `openspec/changes/archive/YYYY-MM-DD-<name>/`
+- The main spec content merged via delta semantics
+- Archive metadata annotations on the design doc / plan
+
+**You must prompt the user to commit these archive changes**, otherwise the archived result stays in the worktree. After showing the pending files, suggest:
+
+```bash
+git add -A
+git commit -m "chore: archive <change-name>"
+```
+
+If branch handling (phase 4) chose not to merge into the main branch yet, finish up via the selected option (merge / PR / keep branch) together with this commit.
+
 ## Exit Conditions
 
 - Archive script executed successfully (exit code 0)
@@ -89,7 +99,7 @@ brainstorming → delta spec → implementation → verification → main spec m
 
 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.
+> **WARNING**: After successful archive, **do not run** `node "$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
 

package/assets/skills/comet-build/SKILL.md

@@ -1,6 +1,6 @@
 ---
 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."
+description: "Use when a full Comet change has completed design and needs an implementation plan, execution-mode selection, or resumed build tasks."
 ---
 
 # Comet Phase 3: Plan and Build (Build)
@@ -14,16 +14,10 @@ description: "Comet Phase 3: Plan and Build. Invoke with /comet-build. Create pl
 
 ### 0. Entry State Verification (Entry Check)
 
-Execute entry verification:
+Locate scripts via `comet/reference/scripts.md`, then run entry verification. When resuming from any entry point, first run the recovery check in `comet/reference/context-recovery.md`:
 
 ```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
+node "$COMET_STATE" check <name> build
 ```
 
 Proceed to Step 1 after verification passes. The script outputs specific failure reasons when verification fails.
@@ -32,13 +26,13 @@ Proceed to Step 1 after verification passes. The script outputs specific failure
 
 ### 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.
+Create the implementation plan through a subagent, avoiding planning skill occupying main session context. Plan files and execution feedback must use the configured Comet artifact language from `"$COMET_BASH" "$COMET_STATE" get <name> language`.
 
 **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`
+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 configured Comet artifact language from "$COMET_BASH" "$COMET_STATE" get <name> language`
 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
@@ -75,7 +69,7 @@ After the subagent completes:
 Record plan path:
 
 ```bash
-"$COMET_BASH" "$COMET_STATE" set <name> plan docs/superpowers/plans/YYYY-MM-DD-feature.md
+node "$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.
@@ -84,7 +78,7 @@ 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 |
+| A | Continue execution | Stay in the current model and proceed to Step 3 to choose workspace isolation, execution method, TDD mode, and code review mode |
 | 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`.
@@ -92,13 +86,13 @@ This is a user decision point. **Must follow the `comet/reference/decision-point
 When the user chooses to continue:
 
 ```bash
-"$COMET_BASH" "$COMET_STATE" set <name> build_pause null
+node "$COMET_STATE" set <name> build_pause null
 ```
 
 When the user chooses to pause:
 
 ```bash
-"$COMET_BASH" "$COMET_STATE" set <name> build_pause plan-ready
+node "$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.
@@ -108,12 +102,12 @@ After setting `build_pause: plan-ready`, stop the current invocation. Do not cho
 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
+node "$COMET_STATE" set <name> build_pause null
 ```
 
-Then continue this step to choose workspace isolation and execution method.
+Then continue this step to choose workspace isolation, execution method, TDD mode, and code review mode.
 
-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**:
+Plan has been written to the current branch. Before starting execution, **ask the user to choose workspace isolation, execution method, TDD mode, and code review mode in a single interaction**:
 
 **Workspace Isolation**:
 
@@ -130,7 +124,7 @@ Plan has been written to the current branch. Before starting execution, **ask th
 
 | Option | Skill | Applicable Scenario |
 |------|------|-------------------|
-| A | Superpowers `subagent-driven-development` | Independent tasks, high complexity, requires two-phase review |
+| A | Superpowers `subagent-driven-development` | Independent tasks, high complexity; each task runs in an isolated implementer subagent with review driven by `review_mode` |
 | B | Superpowers `executing-plans` | Simple tasks, no subagent environment, lightweight and fast |
 
 **Execution method recommendation rules**:
@@ -138,16 +132,16 @@ Plan has been written to the current branch. Before starting execution, **ask th
 - 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.
+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, TDD mode, and code review mode**. Must not choose `branch` or `worktree` based on recommendation rules, and must not choose the execution method, TDD mode, or code review 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:
+After user selection, update `isolation`, execution method, TDD mode, and code review mode fields:
 
 ```bash
-"$COMET_BASH" "$COMET_STATE" set <name> isolation <branch|worktree>
+node "$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 the user chooses `executing-plans`: run `node "$COMET_STATE" set <name> subagent_dispatch null`, then run `node "$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 `node "$COMET_STATE" set <name> subagent_dispatch confirmed`, then run `node "$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**:
@@ -157,19 +151,31 @@ After user selection, update `isolation`, execution method, and TDD mode fields:
 | `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>`
+Run `node "$COMET_STATE" set <name> tdd_mode <tdd|direct>`
+
+**Code Review Mode**:
+
+| Option | Meaning | Applicable Scenario |
+|--------|---------|---------------------|
+| `off` | No automatic code review dispatch | Documentation, configuration, copywriting, small low-risk tasks |
+| `standard` | No per-task reviewer by default; dispatch a per-task reviewer only when a task hits a risk signal, plus one final lightweight code review | Default recommended, suits most ordinary changes |
+| `thorough` | Dispatch a per-task reviewer (spec + quality) on every task, plus one final complete review | High-risk, multi-module, architecture or security-related changes |
+
+Run `node "$COMET_STATE" set <name> review_mode <off|standard|thorough>`
 
 `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.
+`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.mjs 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.mjs 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.
+`review_mode` is a script-enforced hard constraint. Full workflow must have `review_mode` selected as `off`, `standard`, or `thorough` before leaving the build phase, otherwise both `comet-guard.mjs build --apply` and `comet-state transition build-complete` will fail. Legacy state files without this field follow a compat path, but should be backfilled on recovery.
 
 `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
+node "$COMET_STATE" set <name> direct_override true
+node "$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.
@@ -200,9 +206,9 @@ 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: 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 configured Comet artifact language from "$COMET_BASH" "$COMET_STATE" get <name> language`. 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.
+- 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 `node "$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**:
 
@@ -214,10 +220,14 @@ 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.
+Under `executing-plans`, the main session executes tasks directly (no isolated implementer subagent), so there is no per-task reviewer as in `subagent-driven-development`. Code review is done against completed diffs and scales with `review_mode`:
+
+- **`review_mode: off`**: No automatic code review. Do not load `requesting-code-review`. Record the skip reason in the verification report draft or tasks.md.
+- **`review_mode: standard`**: After all planned tasks are complete and before the build → verify phase guard, use the Skill tool to load the Superpowers `requesting-code-review` skill once and request one lightweight code review (correctness, security, edge cases) scoped to the whole change.
+- **`review_mode: thorough`**: In addition to the single final review, request one segmented code review per task segment (every 3 tasks, scoped to that segment's diff). If total tasks ≤ 3, skip the mid-execution segments and only do the final review. Each segment review uses `requesting-code-review` against the segment's commit range. This is the closest equivalent to `subagent-driven-development`'s per-task review that `executing-plans` can offer, since it has no isolated implementer to review per task.
 
-Requirements:
-- the `requesting-code-review` skill must be loaded before `"$COMET_BASH" "$COMET_GUARD" <change-name> build --apply`
+Requirements (apply to `standard` and `thorough`):
+- the `requesting-code-review` skill must be loaded before `node "$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
@@ -256,7 +266,7 @@ When creating an independent change, must invoke `/comet-open`, not `/opsx:new`
 
 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
+- **After each task**: complete acceptance per the current execution branch and `review_mode` before checking off and committing. `subagent-driven-development` dispatches no per-task reviewer under `off`; under `standard`, a per-task reviewer fires only when the task hits a risk signal; under `thorough`, every task gets a per-task reviewer. All modes must 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"
@@ -270,8 +280,9 @@ Build is the longest phase and may span many tasks. To support resume after cont
 - `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`
+- `review_mode` has been written as `off`, `standard`, or `thorough`
+- Code review has been completed per the `executing-plans` review gate (Section "Execute plan") for the chosen `review_mode`: under `standard` or `thorough`, code review has been requested and CRITICAL review findings fixed or non-CRITICAL acceptance rationale recorded; under `review_mode: off`, the reason for skipping automatic code review has been recorded in a persistent artifact
+- **Phase guard**: Run `node "$COMET_GUARD" <change-name> build --apply`; after all PASS, state advances to `phase: verify`
 
 Guard reads project command configuration first:
 
@@ -281,12 +292,12 @@ 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.
+Configured commands use a restricted shell grammar: command words, quotes, paths, and `&&` for sequential steps are allowed; `;`, pipes, bare `&`, `$`, and backticks are rejected. 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
+node "$COMET_GUARD" <change-name> build --apply
 ```
 
 State file is automatically updated to `phase: verify`, `verify_result: pending`.
@@ -296,7 +307,7 @@ State file is automatically updated to `phase: verify`, `verify_result: pending`
 Follow `comet/reference/auto-transition.md`. Key command:
 
 ```bash
-"$COMET_BASH" "$COMET_STATE" next <change-name>
+node "$COMET_STATE" next <change-name>
 ```
 
 - `NEXT: auto` → invoke the skill pointed to by `SKILL` to enter the next phase

package/assets/skills/comet-design/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: comet-design
-description: "Comet Phase 2: Deep Design. Invoke with /comet-design. Produce Design Doc and delta spec through brainstorming."
+description: "Use when a full Comet change has completed open but lacks a Superpowers Design Doc, or design must resume from an OpenSpec handoff package."
 ---
 
 # Comet Phase 2: Deep Design (Design)
@@ -10,20 +10,16 @@ description: "Comet Phase 2: Deep Design. Invoke with /comet-design. Produce Des
 - Active change exists (proposal.md, design.md, tasks.md)
 - No Design Doc (no corresponding file under `docs/superpowers/specs/`)
 
+> Responsibility boundary: the open-phase `design.md` gives the **high-level solution framework** (architecture decision direction, approach selection, data flow); the design-phase Design Doc is its **deep technical refinement** (detailed implementation design, technical risks, test strategy, edge cases) — a deepening, not a replacement or rewrite.
+
 ## Steps
 
 ### 0. Entry State Verification (Entry Check)
 
-Execute entry verification:
+Locate scripts via `comet/reference/scripts.md`, then run entry verification. When resuming from any entry point, first run the recovery check in `comet/reference/context-recovery.md`:
 
 ```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> design
+node "$COMET_STATE" check <name> design
 ```
 
 Proceed to Step 1 after verification passes. The script outputs specific failure reasons when verification fails.
@@ -35,7 +31,7 @@ Proceed to Step 1 after verification passes. The script outputs specific failure
 **Must be generated by script. Agent writing summaries on the fly is not allowed.**
 
 ```bash
-"$COMET_BASH" "$COMET_HANDOFF" <change-name> design --write
+node "$COMET_HANDOFF" <change-name> design --write
 ```
 
 The script reads the change `.comet.yaml` `context_compression` snapshot, then generates and records the matching handoff package.
@@ -74,7 +70,7 @@ The beta handoff package is a **structured spec projection** that reduces OpenSp
 If full context is genuinely needed, explicitly run:
 
 ```bash
-"$COMET_BASH" "$COMET_HANDOFF" <change-name> design --write --full
+node "$COMET_HANDOFF" <change-name> design --write --full
 ```
 
 Handoff package sources come from OpenSpec open phase artifacts:
@@ -90,7 +86,7 @@ Handoff package sources come from OpenSpec open phase artifacts:
 When loading the skill, ARGUMENTS must include:
 
 ```text
-Language: Use the language of the user request that triggered this workflow
+Language: Use the configured Comet artifact language from `"$COMET_BASH" "$COMET_STATE" get <name> language`
 ```
 
 After the skill loads, follow its guidance and use the following context:
@@ -217,13 +213,13 @@ First record the design_doc path. If Spec Patches wrote back delta spec (added o
 
 ```bash
 # Record design_doc path
-"$COMET_BASH" "$COMET_STATE" set <name> design_doc docs/superpowers/specs/YYYY-MM-DD-topic-design.md
+node "$COMET_STATE" set <name> design_doc docs/superpowers/specs/YYYY-MM-DD-topic-design.md
 
 # If delta spec changes exist, regenerate handoff (update hash)
-"$COMET_BASH" "$COMET_HANDOFF" <change-name> design --write
+node "$COMET_HANDOFF" <change-name> design --write
 
 # Auto-transition to next phase
-"$COMET_BASH" "$COMET_GUARD" <change-name> design --apply
+node "$COMET_GUARD" <change-name> design --apply
 ```
 
 If there are no delta spec changes, skip the handoff regeneration step. The state file updates automatically; no manual editing of other fields needed.
@@ -238,12 +234,12 @@ If there are no delta spec changes, skip the handoff regeneration step. The stat
 - In beta mode, `spec-context.json` must be structurally valid and reference the current source files (enforced by guard)
 - If new capabilities or supplementary acceptance scenarios exist, OpenSpec delta spec has been created/updated
 - `design_doc` written to `.comet.yaml`
-- **Phase guard**: Run `"$COMET_BASH" "$COMET_GUARD" <change-name> design --apply`; after all PASS, auto-transitions to `phase: build`
+- **Phase guard**: Run `node "$COMET_GUARD" <change-name> design --apply`; after all PASS, auto-transitions to `phase: build`
 
 Must use `--apply` before exit:
 
 ```bash
-"$COMET_BASH" "$COMET_GUARD" <change-name> design --apply
+node "$COMET_GUARD" <change-name> design --apply
 ```
 
 ## Context Compression Recovery
@@ -255,7 +251,7 @@ Follow `comet/reference/context-recovery.md` with phase set to `design`.
 Follow `comet/reference/auto-transition.md`. Key command:
 
 ```bash
-"$COMET_BASH" "$COMET_STATE" next <change-name>
+node "$COMET_STATE" next <change-name>
 ```
 
 - `NEXT: auto` → invoke the skill pointed to by `SKILL` to enter the next phase