comet

Flow chain: open → design → build → verify → archive

Continuous execution requirement: starting from the detected phase, the agent automatically continues through all later phases. But auto-advancing only applies at transition points without user decisions. When encountering user decision points, must use the current platform's available user input/confirmation mechanism to pause and wait for the user's explicit response. Must not use recommendation rules, defaults, or historical preferences to substitute for user confirmation, and must not just output a text prompt and then continue executing.

Distinguish phase advancement vs automatic handoff: each sub-skill runs phase guard --apply before exit to advance the .comet.yaml phase field. This step always happens and is not controlled by auto_transition. After that, the sub-skill runs "$COMET_BASH" "$COMET_STATE" next <name> to resolve the next action: when auto_transition is not false, output is NEXT: auto (auto-invoke next skill); when auto_transition is false, output is NEXT: manual (do not invoke next skill, show a manual run hint). Therefore auto_transition only controls next skill invocation, not phase advancement. Regardless of auto_transition, user decision points below remain blocking.

Decision points are blocking points: whenever reaching any of the following nodes, the current /comet invocation must stop, and follow the comet/reference/decision-point.md protocol to obtain the user's explicit choice. Only after the user explicitly chooses can the corresponding state fields be written and operations executed, then auto-advance resumes.

Nodes requiring user participation (pause only at these nodes):

1. Open phase proposal/design/tasks review and confirmation
2. Confirm design approach during brainstorming
3. Plan-ready pause choice during build phase, followed by workflow configuration selection (isolation + execution method + TDD mode)
4. Decide to fix or accept deviation when verify fails (including Spec drift handling)
5. Choose branch handling method for finishing-branch
6. Archive phase final confirmation before running the archive script
7. Encounter upgrade conditions (hotfix/tweak → full workflow)
8. Build phase scope expansion requiring redesign or new change split
9. Open phase large PRD requiring confirmation to split into multiple changes

Agents should not skip these decision points; other unambiguous phase transitions must proceed automatically, must not exit midway. At decision points, must not skip user confirmation or choose automatically — must explicitly obtain the user's choice through the current platform's available user input/confirmation mechanism before continuing.

Red Flags — when these thoughts appear, STOP and check:

Subcommand Quick Reference

/comet
  ↓ Auto-detect
/comet-open ──→ /comet-design ──→ /comet-build ──→ /comet-verify ──→ /comet-archive
  (OpenSpec)      (Superpowers)     (Superpowers)     (Both)          (OpenSpec)

/comet-hotfix (preset, skip brainstorming)
  open ──→ build ──→ verify ──→ archive
    ↑ If upgrade triggered → block for confirmation → supplement Design Doc → return to full workflow

/comet-tweak (preset, skip brainstorming and full plan)
  open ──→ lightweight build ──→ light verify ──→ archive
    ↑ If upgrade triggered → block for confirmation → supplement Design Doc → return to full workflow

Reference Appendix

State Machine Hard Constraints

• Before build → verify, isolation must be branch or worktree
• Before build → verify, build_mode must be selected
• build_mode: subagent-driven-development must also have subagent_dispatch: confirmed
• Before full workflow leaves build phase, tdd_mode must be selected as tdd or direct
• build_mode: direct is allowed by default only for hotfix / tweak; full workflow requires direct_override: true
• build_pause is not an execution method and must not be written to build_mode
• These constraints are enforced by both comet-guard.sh build --apply and comet-state.sh transition <name> build-complete

.comet.yaml Field Reference

See comet/reference/comet-yaml-fields.md for complete field reference with examples and descriptions.

File Structure

See comet/reference/file-structure.md for the complete directory layout and artifact organization.

Auto-Transition Protocol

See comet/reference/auto-transition.md for the complete automatic handoff workflow.

Context Recovery

See comet/reference/context-recovery.md for structured recovery after context compression.

Decision Point Protocol

See comet/reference/decision-point.md for the complete user decision point protocol.

Debug Gate Protocol

See comet/reference/debug-gate.md for the complete debug gate protocol.

Script Location

Comet scripts are distributed in comet/scripts/. Do not hardcode paths — locate once, cache in env vars. This block is a standard boilerplate repeated in every sub-skill for independent loadability; changes must be kept in sync across all files (boilerplate version: v2, update this version when changing to help locate files needing sync):

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"

# Stop workflow when script location fails
if [ -z "$COMET_GUARD" ] || [ -z "$COMET_STATE" ] || [ -z "$COMET_HANDOFF" ] || [ -z "$COMET_ARCHIVE" ]; then
  echo "ERROR: Comet scripts not found. Ensure the comet skill is installed." >&2
  echo "Expected path pattern: */comet/scripts/comet-*.sh under project or platform skill directories" >&2
  return 1
fi

Auto state update: Guard supports --apply flag, automatically updating .comet.yaml state fields after checks pass:

"$COMET_BASH" "$COMET_GUARD" <change-name> <phase> --apply

--apply delegates to comet-state transition. Use these semantic events when state changes need to be expressed directly:

"$COMET_BASH" "$COMET_STATE" transition <change-name> open-complete
"$COMET_BASH" "$COMET_STATE" transition <change-name> design-complete
"$COMET_BASH" "$COMET_STATE" transition <change-name> build-complete
"$COMET_BASH" "$COMET_STATE" transition <change-name> verify-pass
"$COMET_BASH" "$COMET_STATE" transition <change-name> verify-fail
"$COMET_BASH" "$COMET_STATE" transition <archive-name> archived

Resolve next action: after guard-based phase advancement, use the next subcommand to determine whether to auto-invoke the next skill:

"$COMET_BASH" "$COMET_STATE" next <change-name>

Output format: NEXT: auto|manual|done + SKILL: <skill-name> (omitted for done) + HINT (for manual only). With auto_transition: false, output is manual, which pauses only the next skill invocation and does not block phase updates.

Archive script: Complete all archive steps in one command:

"$COMET_BASH" "$COMET_ARCHIVE" <change-name>

After loading comet, agents should run the variable assignments above once, then reuse $COMET_GUARD, $COMET_STATE, $COMET_HANDOFF, $COMET_ARCHIVE throughout the session.

Best Practices

1. brainstorming cannot be skipped — Every change must undergo deep design (except hotfix and tweak)
2. delta spec is a living document — Freely modify during phase 3, sync at archive
3. Handoff packages are generated by scripts — OpenSpec → Superpowers context must be generated through comet-handoff.sh as compact traceable excerpts (use --full when needed), and validated by guard for source/hash/mode
4. Keep tasks.md in sync — Check off each completed task
5. Commit frequently — One commit per task, message reflects design intent
6. Verify before archive confirmation — Enter /comet-archive only after /comet-verify passes, but wait for final user confirmation before running the archive script
7. Classify incremental updates — Small edits, medium brainstorming, large new changes
8. Plan must associate with change — File header contains change: and design-doc: metadata
9. Archive closure — design doc and plan must mark archived-with status
10. Modifying existing features — Just open a new change
11. Preset has limits — Switch to full workflow promptly when hotfix/tweak meet upgrade conditions