@rpamis/comet 0.1.6 → 0.1.7

package/README.md

@@ -153,6 +153,7 @@ Comet uses a decoupled state architecture with separate YAML files:
 - `design_doc`: Path to Superpowers Design Doc
 - `plan`: Path to implementation plan
 - `build_mode`: `subagent-driven-development`, `executing-plans`, or `direct`
+- `isolation`: `branch` or `worktree`, workspace isolation method
 - `verify_mode`: `light` or `full`
 - `verify_result`: `pending`, `pass`, or `fail`
 - `archived`: Boolean indicating if change is archived
@@ -170,8 +171,8 @@ Comet includes three-layer defense to ensure agent execution reliability:
    - Automatic retry mechanism (up to 2 attempts) on mismatch
 
 3. **Schema Validation** — `comet-yaml-validate.sh` ensures data integrity
-   - Validates required fields (9 fields)
-   - Validates enum values (6 enum types)
+   - Validates required fields (10 fields)
+   - Validates enum values (7 enum types)
    - Validates referenced file paths exist
    - Detects unknown/typos fields
 
@@ -208,7 +209,7 @@ your-project/
 
 ```bash
 # Clone
-git clone https://github.com/benym/comet.git
+git clone https://github.com/rpamis/comet
 cd comet
 
 # Install dependencies

package/assets/skills/comet/SKILL.md

@@ -161,7 +161,7 @@ If metadata conflicts with file state, use verifiable file state as source of tr
 
 ### Script Location
 
-Comet phase guard script `comet-guard.sh` is distributed with the skill package, located in `comet/scripts/` directory.
+Comet phase guard script `comet-guard.sh` and archive script `comet-archive.sh` are distributed with the skill package, located in `comet/scripts/` directory.
 **Do not hardcode platform paths**, self-locate at runtime with:
 
 ```bash
@@ -169,6 +169,19 @@ COMET_GUARD=$(find . -path '*/comet/scripts/comet-guard.sh' -type f -print -quit
 bash "$COMET_GUARD" <change-name> <phase>
 ```
 
+**Auto state update**: Guard supports `--apply` flag, automatically updating `.comet.yaml` state fields after checks pass:
+
+```bash
+bash "$COMET_GUARD" <change-name> <phase> --apply
+```
+
+**Archive script**: Complete all archive steps in one command:
+
+```bash
+COMET_ARCHIVE=$(find . -path '*/comet/scripts/comet-archive.sh' -type f -print -quit)
+bash "$COMET_ARCHIVE" <change-name>
+```
+
 In subsequent documentation, `bash $COMET_GUARD <change> <phase>` refers to this command. After loading comet, agents should cache `COMET_GUARD` path in shell environment to avoid repeated `find`.
 
 ### File Structure
@@ -185,7 +198,7 @@ openspec/                              # OpenSpec — WHAT
 │   │   ├── specs/<capability>/spec.md # Delta capability spec
 │   │   └── tasks.md                   # Task checklist
 │   └── archive/YYYY-MM-DD-<name>/     # Archived
-└── specs/<capability>/spec.md         # Main specs (sync from delta at archive)
+└── specs/<capability>/spec.md         # Main specs (overwritten from delta at archive)
 
 docs/superpowers/                      # Superpowers — HOW
 ├── specs/YYYY-MM-DD-<topic>-design.md # Design doc (technical RFC, mark status at archive)
@@ -202,5 +215,5 @@ docs/superpowers/                      # Superpowers — HOW
 6. **Classify incremental updates** — Small edits, medium brainstorming, large new changes
 7. **Plan must associate with change** — File header contains `change:` and `design-doc:` metadata
 8. **Archive closure** — design doc and plan must mark `archived-with` status
-9. **Incremental modification of existing features** — Create delta spec baseline based on main spec, not from scratch
+9. **Modifying existing features** — Just open a new change; brainstorming reads existing specs as context naturally
 10. **Preset has limits** — Switch to full workflow promptly when hotfix/tweak meet upgrade conditions

package/assets/skills/comet/scripts/comet-archive.sh

@@ -0,0 +1,252 @@
+#!/bin/bash
+# Comet Archive — automates the archive phase in one command
+# Usage: comet-archive.sh <change-name> [--dry-run]
+# Exit 0 = archive complete, exit 1 = fatal error
+
+set -euo pipefail
+
+red() { echo -e "\033[31m$1\033[0m" >&2; }
+green() { echo -e "\033[32m$1\033[0m" >&2; }
+yellow() { echo -e "\033[33m$1\033[0m" >&2; }
+
+DRY_RUN=0
+if [[ "${2:-}" == "--dry-run" ]]; then
+  DRY_RUN=1
+fi
+
+# Input validation
+validate_change_name() {
+  local name="$1"
+  if [ -z "$name" ]; then
+    red "FATAL: Change name cannot be empty"
+    exit 1
+  fi
+  if [[ ! "$name" =~ ^[a-zA-Z0-9_-]+$ ]]; then
+    red "FATAL: Invalid change name: '$name'"
+    red "Valid characters: a-z, A-Z, 0-9, -, _"
+    exit 1
+  fi
+  if [[ "$name" =~ \.\. ]]; then
+    red "FATAL: Change name cannot contain '..'"
+    exit 1
+  fi
+}
+
+CHANGE="$1"
+validate_change_name "$CHANGE"
+
+CHANGE_DIR="openspec/changes/$CHANGE"
+YAML="$CHANGE_DIR/.comet.yaml"
+TODAY=$(date +%Y-%m-%d)
+ARCHIVE_NAME="${TODAY}-${CHANGE}"
+ARCHIVE_DIR="openspec/changes/archive/${ARCHIVE_NAME}"
+
+STEPS_OK=0
+STEPS_TOTAL=0
+
+step_ok() {
+  green "  [OK] $1"
+  STEPS_OK=$((STEPS_OK + 1))
+  STEPS_TOTAL=$((STEPS_TOTAL + 1))
+}
+
+step_fail() {
+  red "  [FAIL] $1"
+  STEPS_TOTAL=$((STEPS_TOTAL + 1))
+}
+
+echo "=== Comet Archive: $CHANGE ===" >&2
+
+# --- Step 1: Read .comet.yaml, extract paths ---
+
+yaml_field() {
+  local field="$1"
+  if [ -f "$YAML" ]; then
+    grep "^${field}:" "$YAML" | sed "s/^${field}: *//" | tr -d '"' | tr -d "'"
+  fi
+}
+
+if [ ! -f "$YAML" ]; then
+  red "FATAL: .comet.yaml not found in $CHANGE_DIR/"
+  exit 1
+fi
+
+DESIGN_DOC=$(yaml_field "design_doc")
+PLAN_PATH=$(yaml_field "plan")
+
+# --- Step 2: Validate entry state ---
+
+PHASE_VAL=$(yaml_field "phase")
+VERIFY_VAL=$(yaml_field "verify_result")
+ARCHIVED_VAL=$(yaml_field "archived")
+
+if [ "$PHASE_VAL" != "archive" ]; then
+  red "FATAL: phase is '$PHASE_VAL', expected 'archive'"
+  exit 1
+fi
+
+if [ "$VERIFY_VAL" != "pass" ]; then
+  red "FATAL: verify_result is '$VERIFY_VAL', expected 'pass'. Run comet-verify first."
+  exit 1
+fi
+
+if [ "$ARCHIVED_VAL" = "true" ]; then
+  red "FATAL: change already archived"
+  exit 1
+fi
+
+step_ok "Entry state verified"
+
+# --- Step 3: Check archive target ---
+
+if [ -d "$ARCHIVE_DIR" ]; then
+  red "FATAL: archive target already exists: $ARCHIVE_DIR"
+  exit 1
+fi
+
+step_ok "Archive target available"
+
+# --- Step 4: Sync delta specs → main specs ---
+
+sync_delta_specs() {
+  local delta_root="$CHANGE_DIR/specs"
+  if [ ! -d "$delta_root" ]; then
+    return 0
+  fi
+
+  for delta_spec_dir in "$delta_root"/*/; do
+    [ -d "$delta_spec_dir" ] || continue
+    local capability
+    capability=$(basename "$delta_spec_dir")
+    local delta_spec="$delta_spec_dir/spec.md"
+    local main_spec="openspec/specs/$capability/spec.md"
+
+    if [ ! -f "$delta_spec" ]; then
+      continue
+    fi
+
+    STEPS_TOTAL=$((STEPS_TOTAL + 1))
+
+    if [ "$DRY_RUN" -eq 1 ]; then
+      yellow "  [DRY-RUN] Would sync: $capability → $main_spec"
+      STEPS_OK=$((STEPS_OK + 1))
+      continue
+    fi
+
+    if [ ! -f "$main_spec" ]; then
+      mkdir -p "openspec/specs/$capability"
+    fi
+    cp "$delta_spec" "$main_spec"
+
+    step_ok "Delta spec synced: $capability → openspec/specs/$capability/spec.md"
+  done
+}
+
+sync_delta_specs
+
+# --- Step 5: Annotate design doc frontmatter ---
+
+annotate_frontmatter() {
+  local file="$1"
+  local extra_fields="$2"
+
+  if [ ! -f "$file" ]; then
+    return 0
+  fi
+
+  STEPS_TOTAL=$((STEPS_TOTAL + 1))
+
+  if [ "$DRY_RUN" -eq 1 ]; then
+    yellow "  [DRY-RUN] Would annotate: $file"
+    STEPS_OK=$((STEPS_OK + 1))
+    return 0
+  fi
+
+  if head -1 "$file" | grep -q '^---'; then
+    local tmp_file
+    tmp_file=$(mktemp)
+    awk -v archive="$ARCHIVE_NAME" -v extra="$extra_fields" '
+      /^archived-with:/ { next }
+      NR==1 && /^---/ { print; next }
+      /^---/ && NR>1 {
+        print "archived-with: " archive
+        if (extra != "") print extra
+        print; next
+      }
+      { print }
+    ' "$file" > "$tmp_file"
+    mv "$tmp_file" "$file"
+  else
+    local tmp_file
+    tmp_file=$(mktemp)
+    {
+      echo "---"
+      echo "archived-with: $ARCHIVE_NAME"
+      if [ -n "$extra_fields" ]; then
+        echo "$extra_fields"
+      fi
+      echo "status: final"
+      echo "---"
+      cat "$file"
+    } > "$tmp_file"
+    mv "$tmp_file" "$file"
+  fi
+
+  step_ok "Annotated: $file"
+}
+
+if [ -n "$DESIGN_DOC" ] && [ "$DESIGN_DOC" != "null" ]; then
+  annotate_frontmatter "$DESIGN_DOC" "status: final"
+fi
+
+# --- Step 6: Annotate plan frontmatter ---
+
+if [ -n "$PLAN_PATH" ] && [ "$PLAN_PATH" != "null" ]; then
+  annotate_frontmatter "$PLAN_PATH" ""
+fi
+
+# --- Step 7: Move change to archive ---
+
+STEPS_TOTAL=$((STEPS_TOTAL + 1))
+
+if [ "$DRY_RUN" -eq 1 ]; then
+  yellow "  [DRY-RUN] Would move: $CHANGE_DIR → $ARCHIVE_DIR"
+  STEPS_OK=$((STEPS_OK + 1))
+else
+  mkdir -p "openspec/changes/archive"
+  mv "$CHANGE_DIR" "$ARCHIVE_DIR"
+  step_ok "Moved to: $ARCHIVE_DIR"
+fi
+
+# --- Step 8: Update archived: true in .comet.yaml ---
+
+STEPS_TOTAL=$((STEPS_TOTAL + 1))
+
+ARCHIVE_YAML="$ARCHIVE_DIR/.comet.yaml"
+
+if [ "$DRY_RUN" -eq 1 ]; then
+  yellow "  [DRY-RUN] Would set archived: true in $ARCHIVE_YAML"
+  STEPS_OK=$((STEPS_OK + 1))
+else
+  if [ -f "$ARCHIVE_YAML" ]; then
+    sed -i 's/^archived:.*/archived: true/' "$ARCHIVE_YAML"
+    step_ok "archived: true"
+  else
+    step_fail "archived: true (.comet.yaml not found after move)"
+  fi
+fi
+
+# --- Step 9: Print summary ---
+
+echo "" >&2
+if [ "$DRY_RUN" -eq 1 ]; then
+  yellow "Dry run complete. $STEPS_OK/$STEPS_TOTAL steps would succeed."
+else
+  green "Archive complete. $STEPS_OK/$STEPS_TOTAL steps succeeded."
+fi
+
+if [ "$STEPS_OK" -lt "$STEPS_TOTAL" ]; then
+  exit 1
+fi
+
+exit 0

package/assets/skills/comet/scripts/comet-guard.sh

@@ -1,6 +1,6 @@
 #!/bin/bash
 # Comet Phase Guard — validates exit conditions before phase transitions
-# Usage: comet-guard.sh <change-name> <from-phase>
+# Usage: comet-guard.sh <change-name> <current-phase> [--apply]
 # Phases: open, design, build, verify, archive
 # Exit 0 = all checks pass, exit 1 = blocked (reasons printed to stderr)
 
@@ -35,6 +35,10 @@ validate_change_name "$1"
 
 CHANGE="$1"
 PHASE="$2"
+APPLY=0
+if [[ "${3:-}" == "--apply" ]]; then
+  APPLY=1
+fi
 CHANGE_DIR="openspec/changes/$CHANGE"
 
 BLOCK=0
@@ -177,6 +181,33 @@ guard_archive() {
   check "tasks.md all tasks checked" tasks_all_done
 }
 
+apply_state_update() {
+  local yaml="$CHANGE_DIR/.comet.yaml"
+  local p="$1"
+
+  case "$p" in
+    open)
+      sed -i 's/^phase:.*/phase: design/' "$yaml"
+      ;;
+    design)
+      sed -i 's/^phase:.*/phase: build/' "$yaml"
+      ;;
+    build)
+      sed -i 's/^phase:.*/phase: verify/' "$yaml"
+      sed -i 's/^verify_result:.*/verify_result: pending/' "$yaml"
+      ;;
+    verify)
+      sed -i 's/^phase:.*/phase: archive/' "$yaml"
+      sed -i 's/^verify_result:.*/verify_result: pass/' "$yaml"
+      if ! grep -q '^verified_at:' "$yaml" 2>/dev/null; then
+        echo "verified_at: $(date +%Y-%m-%d)" >> "$yaml"
+      else
+        sed -i "s/^verified_at:.*/verified_at: $(date +%Y-%m-%d)/" "$yaml"
+      fi
+      ;;
+  esac
+}
+
 # --- Main ---
 
 case "$PHASE" in
@@ -199,5 +230,14 @@ if [ "$BLOCK" -eq 1 ]; then
 else
   echo "" >&2
   green "ALL CHECKS PASSED — ready for next phase"
+  if [ "$APPLY" -eq 1 ]; then
+    apply_state_update "$PHASE"
+    case "$PHASE" in
+      open)   green "  [APPLY] .comet.yaml updated: phase=design" ;;
+      design) green "  [APPLY] .comet.yaml updated: phase=build" ;;
+      build)  green "  [APPLY] .comet.yaml updated: phase=verify, verify_result=pending" ;;
+      verify) green "  [APPLY] .comet.yaml updated: phase=archive, verify_result=pass" ;;
+    esac
+  fi
   exit 0
 fi

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

@@ -39,113 +39,38 @@ Proceed to Step 1 only after verification passes.
 
 ### 1. Execute Archive
 
-Before archiving, if `verify_result` is not `pass`, stop archiving and return to `/comet-verify`.
-
-**Immediately execute:** Use the Skill tool to load the `openspec-archive-change` skill. Skipping this step is prohibited.
-
-After the skill loads, follow its guidance to archive. Automatic checks:
-1. Artifact completion status (proposal, design, specs, tasks)
-2. All tasks marked `[x]`
-3. Delta specs sync status
-
-### 1b. Move Comet State File
-
-`openspec-archive-change` is not aware of `.comet.yaml`, so Comet needs to move this file itself after OpenSpec archiving completes:
+Run the archive script to automatically complete all steps:
 
 ```bash
-mv openspec/changes/<name>/.comet.yaml openspec/changes/archive/YYYY-MM-DD-<name>/.comet.yaml
-```
-
-【Write verification】After move completion, must verify:
-  test -f openspec/changes/archive/YYYY-MM-DD-<name>/.comet.yaml
-  Confirm .comet.yaml exists in archive directory
-  If file is not at expected location, check if mv command executed successfully.
-
-### 2. Delta Spec Sync
-
-Sync delta specs to main specs during archiving:
-
-```
-openspec/changes/<name>/specs/<capability>/spec.md
-       ↓ sync
-openspec/specs/<capability>/spec.md  ← main spec (persistent)
+COMET_ARCHIVE=$(find . -path '*/comet/scripts/comet-archive.sh' -type f -print -quit)
+bash "$COMET_ARCHIVE" "<change-name>"
 ```
 
-### 3. Design Doc & Plan Handling
-
-Handle associated files under `docs/superpowers/` during archiving. If target file already has YAML frontmatter, merge archive fields into existing frontmatter; if no frontmatter, create new frontmatter.
-
-**3a. Design Doc Consistency Annotation**
+The script automatically executes:
+1. Entry state validation (phase=archive, verify_result=pass, archived=false)
+2. Delta spec sync to main spec (overwrite)
+3. Design doc frontmatter annotation (archived-with, status)
+4. Plan frontmatter annotation (archived-with)
+5. Move change to archive directory
+6. Update archived: true
 
-Find design documents associated with current change in `docs/superpowers/specs/`:
-- Compare delta spec final version with design doc content
-- If there are discrepancies (incremental spec modifications during implementation), set the following metadata in design doc's YAML frontmatter:
+If script returns non-zero exit code, report error and stop.
+If script returns zero exit code, archive is complete.
 
-```yaml
----
-archived-with: YYYY-MM-DD-<name>
-status: superseded-by-main-spec
-implementation-notes: |
-  <briefly describe key changes deviating from original design during implementation>
----
-```
+Use `--dry-run` flag to preview without executing.
 
-- If completely consistent, only set:
-
-```yaml
----
-archived-with: YYYY-MM-DD-<name>
-status: final
----
-```
-
-**3b. Plan Association Annotation**
-
-Find implementation plans associated with current change in `docs/superpowers/plans/`, set the same `archived-with` metadata in YAML frontmatter.
-
-### 4. Archive Directory
-
-Change moves to archive directory:
-
-```
-openspec/changes/archive/YYYY-MM-DD-<name>/
-├── .openspec.yaml
-├── .comet.yaml
-├── proposal.md
-├── design.md
-├── specs/<capability>/spec.md
-└── tasks.md
-```
-
-### 5. Lifecycle Closed Loop
+### 2. Lifecycle Closed Loop
 
 Spec lifecycle completes here:
 ```
-brainstorming → delta spec → implementation (incremental modifications) → verification → main spec sync → design doc annotation → archive
+brainstorming → delta spec → implementation → verification → main spec overwrite → design doc annotation → archive
 ```
 
 ## Exit Conditions
 
-- Change archived (removed from active list)
-- Main specs updated (delta → main sync complete)
-- Associated design doc annotated with archive status
-- Associated plan annotated with archive status
-- `.comet.yaml` `archived` recorded as `true`
+- Archive script executed successfully (exit code 0)
 - **Phase guard**: Run `bash $COMET_GUARD <change-name> archive`, confirm archive complete after all PASS
 
-After archiving completes, update `.comet.yaml` in archive directory:
-
-```yaml
-phase: archive
-archived: true
-```
-
-【Write verification】After update completion, must verify:
-  cat openspec/changes/archive/YYYY-MM-DD-<name>/.comet.yaml
-  Confirm phase line value is "archive"
-  Confirm archived line value is "true"
-  If any field does not match, retry write then verify again. Maximum 2 retries, report error and terminate if still fails.
-
 ## Complete
 
 Comet workflow complete. To start new work, invoke `/comet` or `/comet-open`.

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

@@ -56,17 +56,13 @@ design-doc: docs/superpowers/specs/YYYY-MM-DD-<topic>-design.md
 
 ### 2. Update Plan Status
 
-Merge and update the following fields in `openspec/changes/<name>/.comet.yaml` (keep other fields unchanged):
+Record plan path:
 
-```yaml
-phase: build
-plan: docs/superpowers/plans/YYYY-MM-DD-feature.md
+```bash
+sed -i 's|^plan:.*|plan: docs/superpowers/plans/YYYY-MM-DD-feature.md|' openspec/changes/<name>/.comet.yaml
 ```
 
-【Write verification】After update completion, must verify:
-  cat openspec/changes/<name>/.comet.yaml
-  Confirm plan line value is "docs/superpowers/plans/YYYY-MM-DD-feature.md"
-  If not matching, retry write then verify again. Maximum 2 retries, report error and terminate if still fails.
+No manual phase update needed — guard auto-transitions when exit conditions are met.
 
 ### 3. Workspace Isolation
 
@@ -81,28 +77,11 @@ Plan has been written to the current branch. Before starting execution, choose w
 - Change involves ≤ 3 files → Recommend A
 - Need parallel development, current branch has uncommitted work → Recommend B
 
-After user selection, merge and update `isolation` in `openspec/changes/<name>/.comet.yaml` (keep other fields unchanged). `isolation` only allows one of the following values:
+After user selection, update `isolation` in `openspec/changes/<name>/.comet.yaml`. `isolation` only allows one of the following values:
 
 - `branch`
 - `worktree`
 
-Few-shot examples:
-
-```yaml
-# User selects create branch / A
-isolation: branch
-```
-
-```yaml
-# User selects create worktree / B
-isolation: worktree
-```
-
-【Write verification】After update completion, must verify:
-  cat openspec/changes/<name>/.comet.yaml
-  Confirm isolation line value is "<branch or worktree>"
-  If not matching, retry write then verify again. Maximum 2 retries, report error and terminate if still fails.
-
 **Execute isolation**:
 
 - **branch**: Run `git checkout -b <change-name>`, subsequent work on the new branch
@@ -124,29 +103,12 @@ Present plan summary to user (task count, involved modules), then ask for execut
 - Task count ≤ 2 and no cross-module dependencies → Recommend B
 - From hotfix path → Recommend B
 
-After user selection, merge and update `build_mode` in `openspec/changes/<name>/.comet.yaml` (keep other fields unchanged). `build_mode` only allows one of the following values:
+After user selection, update `build_mode` in `openspec/changes/<name>/.comet.yaml`. `build_mode` only allows one of the following values:
 
 - `subagent-driven-development`
 - `executing-plans`
 - `direct` (only for hotfix preset use)
 
-Few-shot examples:
-
-```yaml
-# User selects robust mode / A
-build_mode: subagent-driven-development
-```
-
-```yaml
-# User selects fast mode / B
-build_mode: executing-plans
-```
-
-【Write verification】After update completion, must verify:
-  cat openspec/changes/<name>/.comet.yaml
-  Confirm build_mode line value is "<subagent-driven-development or executing-plans or direct>"
-  If not matching, retry write then verify again. Maximum 2 retries, report error and terminate if still fails.
-
 Then, **immediately execute:** Use the Skill tool to load the corresponding skill. Skipping this step is prohibited.
 
 If the selected Superpowers skill is unavailable, stop the process and prompt to install or enable the corresponding skill. Do not substitute this step with normal conversation.
@@ -183,18 +145,13 @@ When the initial spec is found incomplete during implementation, handle by scale
 - `.comet.yaml` `phase` updated to `verify`
 - **Phase guard**: Run `bash $COMET_GUARD <change-name> build`, allow transition only after all PASS
 
-Before exit, merge and update the following fields in `.comet.yaml` (keep other fields unchanged):
+Before exit, run guard to auto-transition:
 
-```yaml
-phase: verify
-verify_result: pending
+```bash
+bash $COMET_GUARD <change-name> build --apply
 ```
 
-【Write verification】After update completion, must verify:
-  cat openspec/changes/<name>/.comet.yaml
-  Confirm phase line value is "verify"
-  Confirm verify_result line value is "pending"
-  If any field does not match, retry write then verify again. Maximum 2 retries, report error and terminate if still fails.
+State file is automatically updated to `phase: verify`, `verify_result: pending`.
 
 ## Automatic Transition
 

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

@@ -66,18 +66,17 @@ After the skill loads, follow its guidance to produce:
 
 ### 2. Update Comet State
 
-Merge and update the following fields in `openspec/changes/<name>/.comet.yaml` (keep other fields unchanged):
+Record design_doc path, then run guard to auto-transition:
 
-```yaml
-phase: build
-design_doc: docs/superpowers/specs/YYYY-MM-DD-topic-design.md
+```bash
+# Record design_doc path
+sed -i 's|^design_doc:.*|design_doc: docs/superpowers/specs/YYYY-MM-DD-topic-design.md|' openspec/changes/<name>/.comet.yaml
+
+# Auto-transition to next phase
+bash $COMET_GUARD <change-name> design --apply
 ```
 
-【Write verification】After update completion, must verify:
-  cat openspec/changes/<name>/.comet.yaml
-  Confirm phase line value is "build"
-  Confirm design_doc line value is "docs/superpowers/specs/YYYY-MM-DD-topic-design.md"
-  If any field does not match, retry write then verify again. Maximum 2 retries, report error and terminate if still fails.
+State file is updated automatically. No manual editing of other fields required.
 
 ### 3. Dual Spec Division of Labor
 

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

@@ -57,24 +57,6 @@ openspec/changes/<name>/
 └── tasks.md          # Task checklist (checkboxes)
 ```
 
-### 2b. Incrementally Modify Existing Capability (Optional)
-
-**Trigger condition:** proposal.md mentions modifying an existing capability, or user explicitly requests incremental modification.
-
-**Applicable scenario:** Incremental modification to archived functionality (not a brand-new capability).
-
-When proposal.md goals involve modifying an existing capability:
-1. Check if `openspec/specs/<capability>/spec.md` main spec already exists
-2. If it exists, copy the main spec as a delta spec baseline:
-
-```bash
-mkdir -p openspec/changes/<name>/specs/<capability>/
-cp openspec/specs/<capability>/spec.md openspec/changes/<name>/specs/<capability>/spec.md
-```
-
-3. In the copied delta spec, organize changes in delta format (`## ADDED`, `## MODIFIED`, `## REMOVED`)
-4. Note in proposal.md: `based on existing capability: <capability-name>`
-
 ### 3. Initialize Comet State
 
 Create an independent `.comet.yaml` file under `openspec/changes/<name>/`:
@@ -91,19 +73,6 @@ verified_at: null
 archived: false
 ```
 
-【Write verification】After creation, must verify:
-  cat openspec/changes/<name>/.comet.yaml
-  Confirm workflow line value is "full"
-  Confirm phase line value is "design"
-  Confirm design_doc line value is "null"
-  Confirm plan line value is "null"
-  Confirm build_mode line value is "null"
-  Confirm verify_mode line value is "null"
-  Confirm verify_result line value is "pending"
-  Confirm verified_at line value is "null"
-  Confirm archived line value is "false"
-  If any field does not match, retry write then verify again. Maximum 2 retries, report error and terminate if still fails.
-
 ### 4. Content Completeness Check
 
 Confirm the three documents have complete content:

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

@@ -53,27 +53,6 @@ After determination, record actual verification mode in `openspec/changes/<name>
 - `light`
 - `full`
 
-Few-shot examples:
-
-```yaml
-# All metrics hit "small"
-phase: verify
-verify_mode: light
-verify_result: pending
-```
-
-```yaml
-# Any metric hits "large"
-phase: verify
-verify_mode: full
-verify_result: pending
-```
-
-【Write verification】After update completion, must verify:
-  cat openspec/changes/<name>/.comet.yaml
-  Confirm verify_mode line value is "<light or full>"
-  If not matching, retry write then verify again. Maximum 2 retries, report error and terminate if still fails.
-
 ### 2a. Lightweight Verification (Small Changes)
 
 When scale assessment result is "small", skip `openspec-verify-change`, directly execute the following checks:
@@ -142,20 +121,13 @@ After the skill loads, follow its guidance to complete. Branch handling options:
 - `.comet.yaml` `verify_result` recorded as `pass`
 - **Phase guard**: Run `bash $COMET_GUARD <change-name> verify`, allow transition only after all PASS
 
-Before exit, merge and update the following fields in `.comet.yaml` (keep other fields unchanged):
+Before exit, run guard to auto-transition:
 
-```yaml
-phase: archive
-verify_result: pass
-verified_at: YYYY-MM-DD
+```bash
+bash $COMET_GUARD <change-name> verify --apply
 ```
 
-【Write verification】After update completion, must verify:
-  cat openspec/changes/<name>/.comet.yaml
-  Confirm phase line value is "archive"
-  Confirm verify_result line value is "pass"
-  Confirm verified_at line value is non-empty (format YYYY-MM-DD)
-  If any field does not match, retry write then verify again. Maximum 2 retries, report error and terminate if still fails.
+State file is automatically updated to `phase: archive`, `verify_result: pass`, `verified_at: YYYY-MM-DD`.
 
 ## Automatic Transition
 

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

@@ -161,7 +161,7 @@ archived: false
 
 ### 脚本定位
 
-Comet 阶段守卫脚本 `comet-guard.sh` 随 skill 包分发，位于 `comet/scripts/` 目录。
+Comet 阶段守卫脚本 `comet-guard.sh` 和归档脚本 `comet-archive.sh` 随 skill 包分发，位于 `comet/scripts/` 目录。
 **不硬编码平台路径**，运行时通过以下命令自定位：
 
 ```bash
@@ -169,6 +169,19 @@ COMET_GUARD=$(find . -path '*/comet/scripts/comet-guard.sh' -type f -print -quit
 bash "$COMET_GUARD" <change-name> <phase>
 ```
 
+**自动状态更新**：guard 支持 `--apply` 参数，验证通过后自动更新 `.comet.yaml` 状态字段：
+
+```bash
+bash "$COMET_GUARD" <change-name> <phase> --apply
+```
+
+**归档脚本**：一键完成归档全部步骤：
+
+```bash
+COMET_ARCHIVE=$(find . -path '*/comet/scripts/comet-archive.sh' -type f -print -quit)
+bash "$COMET_ARCHIVE" <change-name>
+```
+
 后续文档中 `bash $COMET_GUARD <change> <phase>` 均指此命令。加载 comet 后，agent 应在 shell 环境中缓存 `COMET_GUARD` 路径，避免重复 `find`。
 
 ### 文件结构
@@ -185,7 +198,7 @@ openspec/                              # OpenSpec — WHAT
 │   │   ├── specs/<capability>/spec.md # Delta 能力规格
 │   │   └── tasks.md                   # 任务清单
 │   └── archive/YYYY-MM-DD-<name>/     # 已归档
-└── specs/<capability>/spec.md         # 主 specs（归档时从 delta 同步）
+└── specs/<capability>/spec.md         # 主 specs（归档时从 delta 覆盖）
 
 docs/superpowers/                      # Superpowers — HOW
 ├── specs/YYYY-MM-DD-<topic>-design.md # 设计文档（技术 RFC，归档时标注状态）
@@ -202,5 +215,5 @@ docs/superpowers/                      # Superpowers — HOW
 6. **增量更新分级** — 小编辑、中重 brainstorming、大新 change
 7. **Plan 必须关联 change** — 文件头包含 `change:` 和 `design-doc:` 元数据
 8. **归档闭环** — design doc 和 plan 必须标注 `archived-with` 状态
-9. **增量修改已有功能** — 基于 main spec 创建 delta spec 基线，不从零编写
+9. **增量修改已有功能** — 直接 open 新 change，brainstorming 会读取已有 main spec 作为上下文
 10. **Preset 有上限** — hotfix/tweak 满足升级条件时及时切换到完整流程

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

@@ -39,113 +39,38 @@ description: "Comet 阶段 5：归档。用 /comet-archive 调用。同步 delta
 
 ### 1. 执行归档
 
-归档前如 `verify_result` 不是 `pass`，停止归档并返回 `/comet-verify`。
-
-**立即执行：** 使用 Skill 工具加载 `openspec-archive-change` 技能。禁止跳过此步骤。
-
-技能加载后，按其指引归档。自动检查：
-1. artifact 完成状态（proposal、design、specs、tasks）
-2. 所有任务已标记 `[x]`
-3. delta specs 同步状态
-
-### 1b. 移动 Comet 状态文件
-
-`openspec-archive-change` 不感知 `.comet.yaml`，因此 Comet 需要在 OpenSpec 归档完成后自行移动该文件：
+运行归档脚本，自动完成以下全部步骤：
 
 ```bash
-mv openspec/changes/<name>/.comet.yaml openspec/changes/archive/YYYY-MM-DD-<name>/.comet.yaml
-```
-
-【写入验证】移动完成后必须验证：
-  test -f openspec/changes/archive/YYYY-MM-DD-<name>/.comet.yaml
-  确认归档目录中 .comet.yaml 存在
-  如文件不在预期位置，检查 mv 命令是否成功执行。
-
-### 2. Delta Spec 同步
-
-归档时将 delta specs 同步到主 specs：
-
-```
-openspec/changes/<name>/specs/<capability>/spec.md
-       ↓ 同步
-openspec/specs/<capability>/spec.md  ← 主 spec（持久化）
+COMET_ARCHIVE=$(find . -path '*/comet/scripts/comet-archive.sh' -type f -print -quit)
+bash "$COMET_ARCHIVE" "<change-name>"
 ```
 
-### 3. Design Doc & Plan 处理
-
-归档时同步处理 `docs/superpowers/` 下的关联文件。若目标文件已有 YAML frontmatter，将归档字段合并到现有 frontmatter；若没有 frontmatter，才新建一组 frontmatter。
-
-**3a. Design Doc 一致性标注**
+脚本自动执行：
+1. 入口状态验证（phase=archive, verify_result=pass, archived=false）
+2. Delta spec 同步到主 spec
+3. Design doc 前置元数据标注（archived-with, status）
+4. Plan 前置元数据标注（archived-with）
+5. 移动 change 到归档目录
+6. 更新 archived: true
 
-查找 `docs/superpowers/specs/` 中与当前 change 关联的设计文档：
-- 对比 delta spec 最终版与 design doc 内容
-- 如有偏差（实施过程中 spec 发生了增量修改），在 design doc 的 YAML frontmatter 中设置以下元数据：
+如脚本返回非零退出码，报告错误并停止。
+如脚本返回零退出码，归档完成。
 
-```yaml
----
-archived-with: YYYY-MM-DD-<name>
-status: superseded-by-main-spec
-implementation-notes: |
-  <简述实施过程中偏离原设计的关键变化>
----
-```
+如需预览而不实际执行，使用 `--dry-run` 参数。
 
-- 如完全一致，仅设置：
-
-```yaml
----
-archived-with: YYYY-MM-DD-<name>
-status: final
----
-```
-
-**3b. Plan 关联标注**
-
-查找 `docs/superpowers/plans/` 中与当前 change 关联的实施计划，在 YAML frontmatter 中设置相同的 `archived-with` 元数据。
-
-### 4. 归档目录
-
-change 移入归档目录：
-
-```
-openspec/changes/archive/YYYY-MM-DD-<name>/
-├── .openspec.yaml
-├── .comet.yaml
-├── proposal.md
-├── design.md
-├── specs/<capability>/spec.md
-└── tasks.md
-```
-
-### 5. 生命周期闭环
+### 2. 生命周期闭环
 
 Spec 生命周期在此完成：
 ```
-brainstorming → delta spec → 实施（增量修改）→ 验证 → 主 spec 同步 → design doc 标注 → 归档
+brainstorming → delta spec → 实施 → 验证 → 主 spec 覆盖 → design doc 标注 → 归档
 ```
 
 ## 退出条件
 
-- change 已归档（从活跃列表移除）
-- 主 specs 已更新（delta → main 同步完成）
-- 关联 design doc 已标注归档状态
-- 关联 plan 已标注归档状态
-- `.comet.yaml` 中 `archived` 已记录为 `true`
+- 归档脚本执行成功（退出码 0）
 - **阶段守卫**：运行 `bash $COMET_GUARD <change-name> archive`，全部 PASS 后确认归档完整
 
-归档完成后，在归档目录的 `.comet.yaml` 中更新：
-
-```yaml
-phase: archive
-archived: true
-```
-
-【写入验证】更新完成后必须验证：
-  cat openspec/changes/archive/YYYY-MM-DD-<name>/.comet.yaml
-  确认 phase 行的值为 "archive"
-  确认 archived 行的值为 "true"
-  如任一字段不匹配，重试写入后再次验证。最多重试 2 次，仍失败则报告错误并终止。
-
 ## 完成
 
 Comet 流程全部完成。如需开始新工作，调用 `/comet` 或 `/comet-open`。

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

@@ -56,17 +56,13 @@ design-doc: docs/superpowers/specs/YYYY-MM-DD-<topic>-design.md
 
 ### 2. 更新计划状态
 
-在 `openspec/changes/<name>/.comet.yaml` 中合并更新以下字段（保留其他字段不变）：
+先记录 plan 路径：
 
-```yaml
-phase: build
-plan: docs/superpowers/plans/YYYY-MM-DD-feature.md
+```bash
+sed -i 's|^plan:.*|plan: docs/superpowers/plans/YYYY-MM-DD-feature.md|' openspec/changes/<name>/.comet.yaml
 ```
 
-【写入验证】更新完成后必须验证：
-  cat openspec/changes/<name>/.comet.yaml
-  确认 plan 行的值为 "docs/superpowers/plans/YYYY-MM-DD-feature.md"
-  如不匹配，重试写入后再次验证。最多重试 2 次，仍失败则报告错误并终止。
+无需手动更新 phase，guard 会在退出条件满足后自动流转。
 
 ### 3. 工作区隔离
 
@@ -81,28 +77,11 @@ plan: docs/superpowers/plans/YYYY-MM-DD-feature.md
 - 变更涉及 ≤ 3 个文件 → 推荐 A
 - 需要并行开发、当前分支有未提交工作 → 推荐 B
 
-用户选择后，在 `openspec/changes/<name>/.comet.yaml` 中合并更新 `isolation`（保留其他字段不变）。`isolation` 只允许以下值之一：
+用户选择后，在 `openspec/changes/<name>/.comet.yaml` 中更新 `isolation`。`isolation` 只允许以下值之一：
 
 - `branch`
 - `worktree`
 
-Few-shot 示例：
-
-```yaml
-# 用户选择创建分支 / A
-isolation: branch
-```
-
-```yaml
-# 用户选择创建 worktree / B
-isolation: worktree
-```
-
-【写入验证】更新完成后必须验证：
-  cat openspec/changes/<name>/.comet.yaml
-  确认 isolation 行的值为 "<branch 或 worktree>"
-  如不匹配，重试写入后再次验证。最多重试 2 次，仍失败则报告错误并终止。
-
 **执行隔离**：
 
 - **branch**：执行 `git checkout -b <change-name>`，后续工作在新分支上进行
@@ -124,29 +103,12 @@ isolation: worktree
 - 任务数 ≤ 2 且无跨模块依赖 → 推荐 B
 - 来自 hotfix 路径 → 推荐 B
 
-用户选择后，在 `openspec/changes/<name>/.comet.yaml` 中合并更新 `build_mode`（保留其他字段不变）。`build_mode` 只允许以下值之一：
+用户选择后，在 `openspec/changes/<name>/.comet.yaml` 中更新 `build_mode`。`build_mode` 只允许以下值之一：
 
 - `subagent-driven-development`
 - `executing-plans`
 - `direct`（仅 hotfix preset 使用）
 
-Few-shot 示例：
-
-```yaml
-# 用户选择稳健模式 / A
-build_mode: subagent-driven-development
-```
-
-```yaml
-# 用户选择快速模式 / B
-build_mode: executing-plans
-```
-
-【写入验证】更新完成后必须验证：
-  cat openspec/changes/<name>/.comet.yaml
-  确认 build_mode 行的值为 "<subagent-driven-development 或 executing-plans 或 direct>"
-  如不匹配，重试写入后再次验证。最多重试 2 次，仍失败则报告错误并终止。
-
 然后，**立即执行：** 使用 Skill 工具加载对应技能。禁止跳过此步骤。
 
 如所选 Superpowers 技能不可用，停止流程并提示安装或启用对应技能，不要用普通对话替代该步骤。
@@ -183,18 +145,13 @@ build_mode: executing-plans
 - `.comet.yaml` 中 `phase` 已更新为 `verify`
 - **阶段守卫**：运行 `bash $COMET_GUARD <change-name> build`，全部 PASS 后才允许流转
 
-退出前在 `.comet.yaml` 中合并更新以下字段（保留其他字段不变）：
+退出前运行 guard 自动流转：
 
-```yaml
-phase: verify
-verify_result: pending
+```bash
+bash $COMET_GUARD <change-name> build --apply
 ```
 
-【写入验证】更新完成后必须验证：
-  cat openspec/changes/<name>/.comet.yaml
-  确认 phase 行的值为 "verify"
-  确认 verify_result 行的值为 "pending"
-  如任一字段不匹配，重试写入后再次验证。最多重试 2 次，仍失败则报告错误并终止。
+状态文件自动更新为 `phase: verify`、`verify_result: pending`。
 
 ## 自动流转
 

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

@@ -66,18 +66,17 @@ Design 摘要: <design.md 架构决策>
 
 ### 2. 更新 Comet 状态
 
-在 `openspec/changes/<name>/.comet.yaml` 中合并更新以下字段（保留其他字段不变）：
+先记录 design_doc 路径，再运行 guard 自动流转：
 
-```yaml
-phase: build
-design_doc: docs/superpowers/specs/YYYY-MM-DD-topic-design.md
+```bash
+# 记录 design_doc 路径
+sed -i 's|^design_doc:.*|design_doc: docs/superpowers/specs/YYYY-MM-DD-topic-design.md|' openspec/changes/<name>/.comet.yaml
+
+# 自动流转到下一阶段
+bash $COMET_GUARD <change-name> design --apply
 ```
 
-【写入验证】更新完成后必须验证：
-  cat openspec/changes/<name>/.comet.yaml
-  确认 phase 行的值为 "build"
-  确认 design_doc 行的值为 "docs/superpowers/specs/YYYY-MM-DD-topic-design.md"
-  如任一字段不匹配，重试写入后再次验证。最多重试 2 次，仍失败则报告错误并终止。
+状态文件自动更新，无需手动编辑其他字段。
 
 ### 3. 双 Spec 分工
 

package/assets/skills-zh/comet-open/SKILL.md

@@ -57,24 +57,6 @@ openspec/changes/<name>/
 └── tasks.md          # 任务清单（勾选框）
 ```
 
-### 2b. 增量修改已有 Capability（可选）
-
-**触发条件**：proposal.md 中提到修改已有 capability，或用户明确要求增量修改。
-
-**适用场景**：对已归档功能做增量修改（而非全新 capability）。
-
-当 proposal.md 目标涉及修改已有 capability 时：
-1. 查找 `openspec/specs/<capability>/spec.md` 是否已存在主 spec
-2. 如已存在，将主 spec 复制为 delta spec 基线：
-
-```bash
-mkdir -p openspec/changes/<name>/specs/<capability>/
-cp openspec/specs/<capability>/spec.md openspec/changes/<name>/specs/<capability>/spec.md
-```
-
-3. 在复制的 delta spec 中，按 delta 格式组织变更（`## ADDED`、`## MODIFIED`、`## REMOVED`）
-4. 在 proposal.md 中注明 `基于已有 capability: <capability-name>`
-
 ### 3. 初始化 Comet 状态
 
 在 `openspec/changes/<name>/` 下创建独立的 `.comet.yaml` 文件：
@@ -91,19 +73,6 @@ verified_at: null
 archived: false
 ```
 
-【写入验证】创建完成后必须验证：
-  cat openspec/changes/<name>/.comet.yaml
-  确认 workflow 行的值为 "full"
-  确认 phase 行的值为 "design"
-  确认 design_doc 行的值为 "null"
-  确认 plan 行的值为 "null"
-  确认 build_mode 行的值为 "null"
-  确认 verify_mode 行的值为 "null"
-  确认 verify_result 行的值为 "pending"
-  确认 verified_at 行的值为 "null"
-  确认 archived 行的值为 "false"
-  如任一字段不匹配，重试写入后再次验证。最多重试 2 次，仍失败则报告错误并终止。
-
 ### 4. 内容完整性检查
 
 确认三个文档内容完整：

package/assets/skills-zh/comet-verify/SKILL.md

@@ -53,27 +53,6 @@ description: "Comet 阶段 4：验证与收尾。用 /comet-verify 调用。验
 - `light`
 - `full`
 
-Few-shot 示例：
-
-```yaml
-# 全部指标命中“小”
-phase: verify
-verify_mode: light
-verify_result: pending
-```
-
-```yaml
-# 任一指标命中”大”
-phase: verify
-verify_mode: full
-verify_result: pending
-```
-
-【写入验证】更新完成后必须验证：
-  cat openspec/changes/<name>/.comet.yaml
-  确认 verify_mode 行的值为 “<light 或 full>”
-  如不匹配，重试写入后再次验证。最多重试 2 次，仍失败则报告错误并终止。
-
 ### 2a. 轻量验证（小改动）
 
 当规模评估结果为"小"时，跳过 `openspec-verify-change`，直接执行以下检查：
@@ -142,20 +121,13 @@ verify_result: pending
 - `.comet.yaml` 中 `verify_result` 已记录为 `pass`
 - **阶段守卫**：运行 `bash $COMET_GUARD <change-name> verify`，全部 PASS 后才允许流转
 
-退出前在 `.comet.yaml` 中合并更新以下字段（保留其他字段不变）：
+退出前运行 guard 自动流转：
 
-```yaml
-phase: archive
-verify_result: pass
-verified_at: YYYY-MM-DD
+```bash
+bash $COMET_GUARD <change-name> verify --apply
 ```
 
-【写入验证】更新完成后必须验证：
-  cat openspec/changes/<name>/.comet.yaml
-  确认 phase 行的值为 "archive"
-  确认 verify_result 行的值为 "pass"
-  确认 verified_at 行的值非空（格式为 YYYY-MM-DD）
-  如任一字段不匹配，重试写入后再次验证。最多重试 2 次，仍失败则报告错误并终止。
+状态文件自动更新为 `phase: archive`、`verify_result: pass`、`verified_at: YYYY-MM-DD`。
 
 ## 自动流转
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@rpamis/comet",
-  "version": "0.1.6",
+  "version": "0.1.7",
   "description": "OpenSpec + Superpowers dual-star development workflow",
   "keywords": [
     "comet",