speckit.spex-collab.phase-split

Phase Split Proposal

Ship Pipeline Guard

If .specify/.spex-state exists and its mode is "ship" or status is "running", skip the phase split entirely and return immediately without prompting.

if [ -f ".specify/.spex-state" ]; then
  MODE=$(jq -r '.mode // empty' .specify/.spex-state 2>/dev/null)
  STATUS=$(jq -r '.status // empty' .specify/.spex-state 2>/dev/null)
  if [ "$MODE" = "ship" ] || [ "$STATUS" = "running" ]; then
    echo "Ship mode active, skipping phase split"
  fi
fi

If ship mode is detected, return immediately. Do not display any proposal or prompt the user.

Extension Enabled Check

Verify spex-collab is active:

if [ ! -f ".specify/extensions/spex-collab/extension.yml" ]; then
  echo "spex-collab extension not found, skipping"
fi

If the extension is not found, return without action.

Check for Existing Phase Plan

If .specify/.spex-state already has a collab.phase_plan with entries, a phase plan was previously confirmed:

EXISTING_PLAN=$(jq -r '.collab.phase_plan // empty' .specify/.spex-state 2>/dev/null)

If a phase plan exists and has entries:

• Display: "A phase plan already exists from a previous session."
• Show the existing plan as a table
• Ask: "Use existing plan, or create a new one?"
• If user chooses existing: return (implementation proceeds with saved plan)
• If user chooses new: continue with detection below

Resolve Spec Directory and Read Tasks

PREREQ=$(.specify/scripts/bash/check-prerequisites.sh --json --require-tasks --include-tasks 2>/dev/null)
FEATURE_DIR=$(echo "$PREREQ" | jq -r '.FEATURE_DIR')

Read tasks.md from FEATURE_DIR.

Estimate File Count

Estimate how many files the feature will touch. This determines whether to propose multi-phase splitting or silently default to single phase.

Parse File Paths from plan.md

If plan.md exists in FEATURE_DIR, extract file path references:

PLAN_FILE="${FEATURE_DIR}/plan.md"
ESTIMATED_FILES=0
ESTIMATION_SOURCE="heuristic"

if [ -f "$PLAN_FILE" ]; then
  # Extract file paths: match patterns like src/foo/bar.sh, `path/to/file.md`, ./relative/path.yml
  # Filter: must contain a directory separator (/), have a file extension (1-10 chars)
  # Exclude: URLs (http/https), version-like patterns (v1.5)
  FILE_PATHS=$(grep -oE '[a-zA-Z0-9_./-]+\.[a-zA-Z]{1,10}' "$PLAN_FILE" 2>/dev/null | \
    grep '/' | \
    grep -vE '^https?://' | \
    grep -vE '^//' | \
    grep -v '^v[0-9]' | \
    sort -u)
  FILE_COUNT=$(echo "$FILE_PATHS" | grep -c '.' 2>/dev/null || echo "0")

  if [ "$FILE_COUNT" -ge 5 ]; then
    ESTIMATED_FILES=$FILE_COUNT
    ESTIMATION_SOURCE="plan.md"
  fi
fi