speckit.spex.submit

Submit - Push and Create PR for Team Review

Ship Pipeline Guard

If .specify/.spex-state exists and its status is running, this command is part of an autonomous pipeline. Check the ask field:

AUTONOMOUS_MODE=false
if [ -f ".specify/.spex-state" ]; then
  STATUS=$(jq -r '.status // empty' .specify/.spex-state 2>/dev/null)
  ASK=$(jq -r '.ask // "always"' .specify/.spex-state 2>/dev/null)
  if [ "$STATUS" = "running" ] && [ "$ASK" != "always" ]; then
    AUTONOMOUS_MODE=true
  fi
fi

In autonomous mode: suppress all interactive prompts.

Argument Parsing

Parse the following flags from arguments:

• If --watch is passed, set WATCH_MODE=true. After PR creation/push, enter a monitoring loop instead of exiting.

WATCH_MODE=false
for arg in "$@"; do
  case "$arg" in
    --watch) WATCH_MODE=true ;;
  esac
done

Watch Mode Configuration

When WATCH_MODE is true, read watch configuration from .specify/extensions/spex/spex-config.yml:

if [ "$WATCH_MODE" = true ]; then
  SPEX_CONFIG=".specify/extensions/spex/spex-config.yml"
  WATCH_TIMEOUT=$(yq -r '.watch.timeout_minutes // 30' "$SPEX_CONFIG" 2>/dev/null)
  WATCH_TIMEOUT=${WATCH_TIMEOUT:-30}
  WATCH_INTERVAL=$(yq -r '.watch.poll_interval_seconds // 60' "$SPEX_CONFIG" 2>/dev/null)
  WATCH_INTERVAL=${WATCH_INTERVAL:-60}
fi

Prerequisites

Verify gh CLI

if ! command -v gh >/dev/null 2>&1; then
  echo "ERROR: The gh CLI is required for PR operations. Install it from https://cli.github.com/"
  # STOP
fi

Verify not on default branch

DEFAULT_BRANCH=$(git symbolic-ref refs/remotes/origin/HEAD 2>/dev/null | sed 's@^refs/remotes/origin/@@' || echo "main")
CURRENT_BRANCH=$(git branch --show-current)
if [ "$CURRENT_BRANCH" = "$DEFAULT_BRANCH" ]; then
  echo "ERROR: Cannot submit from the default branch. Switch to a feature branch first."
  # STOP
fi

Pre-Execution Hooks

Check for extension hooks (before submit):

• Check if .specify/extensions.yml exists in the project root.
• If it exists, read it and look for entries under the hooks.before_submit key
• If the YAML cannot be parsed or is invalid, skip hook checking silently and continue normally
• Filter out hooks where enabled is explicitly false. Treat hooks without an enabled field as enabled by default.
• For each remaining hook, do not attempt to interpret or evaluate hook condition expressions:
  • If the hook has no condition field, or it is null/empty, treat the hook as executable
  • If the hook defines a non-empty condition, skip the hook and leave condition evaluation to the HookExecutor implementation
• Convert hook command names from dot notation to hyphen notation for slash command invocation (e.g., speckit.spex.flow-state becomes /speckit-spex-flow-state)
• Determine prompt behavior based on autonomous mode: when .specify/.spex-state exists with ask of smart or never, optional hooks execute without prompting (treated as mandatory). When ask is "always" or no state file exists, optional hooks prompt as normal.
• For each executable hook, output the following based on its optional flag:
  • Optional hook (optional: true) in interactive mode:

    ## Extension Hooks
    
    **Optional Pre-Hook**: {extension}
    Command: `/{command}`
    Description: {description}
    
    Prompt: {prompt}
    To execute: `/{command}`
    

  • Optional hook (optional: true) in autonomous mode (ask is smart or never): Treat as mandatory (auto-execute without prompting).
  • Mandatory hook (optional: false):

    ## Extension Hooks
    
    **Automatic Pre-Hook**: {extension}
    Executing: `/{command}`
    EXECUTE_COMMAND: {command}
    
    Wait for the result of the hook command before proceeding to Phase 1 Verification.
    

  • If a mandatory hook fails or is declined by the user, STOP. Output an error message indicating which hook failed and do NOT proceed to Phase 1 Verification.
• If no hooks are registered or .specify/extensions.yml does not exist, skip silently