Skip to main content
Comet’s reliability comes from a set of shell scripts that move workflow control out of AI prompt text and into testable, reusable tools. These scripts run on macOS, Linux, and Windows (Git Bash).

​
Scripts

ScriptPurpose
comet-env.shScript discovery helper — exports bundled script paths (COMET_GUARD, COMET_STATE, COMET_HANDOFF, COMET_ARCHIVE, COMET_YAML_VALIDATE)
comet-guard.shPhase transition guard — validates exit conditions, --apply auto-updates .comet.yaml
comet-handoff.shDesign handoff — generates deterministic context packages from OpenSpec artifacts with SHA256 tracing
comet-archive.shOne-command archive — validates state, syncs specs, moves to archive, updates status
comet-yaml-validate.shSchema validator — validates .comet.yaml structure and field values
comet-state.shUnified state management — init/set/get/check/scale

​
Loading Scripts in Your Session

Always locate scripts through comet-env.sh — never hardcode paths. Script locations vary by platform, install scope, and OS. Sourcing comet-env.sh once at the start of a session exports all script paths as environment variables. 
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"
After sourcing comet-env.sh, the following environment variables are available in your session:
VariablePoints to
$COMET_GUARDcomet-guard.sh
$COMET_STATEcomet-state.sh
$COMET_HANDOFFcomet-handoff.sh
$COMET_ARCHIVEcomet-archive.sh
$COMET_YAML_VALIDATEcomet-yaml-validate.sh
You should also validate that all variables were populated before proceeding: 
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

​
Cross-Platform Note

Comet resolves a usable bash executable through COMET_BASH. This variable is exported by comet-env.sh automatically after testing candidate executables — including Git Bash paths on Windows. The Windows WSL launcher (System32/bash.exe) is explicitly excluded. Always invoke scripts as: 
"$COMET_BASH" "$COMET_GUARD" <args>
"$COMET_BASH" "$COMET_STATE" <args>
Using "$COMET_BASH" rather than calling scripts directly ensures Windows Git Bash is handled correctly across all supported platforms.

​
Script Pages

comet-guard.sh

Phase transition guard — validates exit conditions before advancing the workflow

comet-state.sh

Unified state management — the exclusive interface for reading and writing .comet.yaml

comet-handoff.sh

Design context handoff — generates SHA256-traced context packages from OpenSpec artifacts

comet-archive.sh

Automated archive — syncs delta specs, annotates documents, and closes the change