init

User Input

$ARGUMENTS

Goal

Establish or refresh the SpecSwarm guides under .specswarm/:

1. constitution.md - Project governance and coding principles
2. tech-stack.md - Approved technologies and prohibited patterns
3. quality-standards.md - Quality gates and performance budgets
4. references.md - External authoritative sources (spec corpus, reference codebases, memory dirs)
5. conventions.md - Detected code style and patterns

/ss:init is designed to run at two points in a project's life:

• At project / sprint kickoff — to create the guides from scratch by detecting the tech stack, discovering external references, and proposing principles from memory.
• Mid-development, any time — to reconcile the guides against project reality. On re-run, the command reads both (a) the existing guide files and (b) current project state (package.json, CI, memory dirs, …), surfaces drift between the two, and only updates a guide after the developer accepts the proposed delta. Developer-authored content inside <!-- ss:user-additions --> blocks is always preserved verbatim. A full backup of all .specswarm/*.md is taken on every run as a safety net.

Pass --reset if you want to discard existing guides and regenerate from scratch (the backup is still taken; nothing is permanently lost).

---

Execution Steps

Step 1: Snapshot existing guides (unconditional)

Always back up every .specswarm/*.md file present at the start of the run. This is cheap, always safe, and protects the developer against any reconciliation bug downstream. No "Update / Backup / Cancel" prompt — re-running /ss:init is meant to be safe.

echo "🔍 Snapshotting existing SpecSwarm guides..."
echo ""

REPO_ROOT="$(git rev-parse --show-toplevel 2>/dev/null || pwd)"
BACKUP_TS="$(date +%Y%m%d-%H%M%S)"
BACKUP_DIR="$REPO_ROOT/.specswarm/.backup/$BACKUP_TS"

EXISTING_FILES=()
if [ -d "$REPO_ROOT/.specswarm" ]; then
  shopt -s nullglob
  for f in "$REPO_ROOT/.specswarm"/*.md; do
    EXISTING_FILES+=("$(basename "$f")")
  done
  shopt -u nullglob
fi

# Detect --reset flag from $ARGUMENTS
RESET_MODE=false
if echo "$ARGUMENTS" | grep -q -- '--reset'; then
  RESET_MODE=true
fi

# v7.0.0: Detect --full-scan and --include-user-memory flags
FULL_SCAN_FLAG=false
if echo "$ARGUMENTS" | grep -q -- '--full-scan'; then
  FULL_SCAN_FLAG=true
fi

INCLUDE_USER_MEMORY_FLAG=false
if echo "$ARGUMENTS" | grep -q -- '--include-user-memory'; then
  INCLUDE_USER_MEMORY_FLAG=true
fi

# Detect --minimal flag (referenced by v7.0.0 Steps 3.0 / 4.0 / 4.1 / 4.2 for short-circuit)
MINIMAL_MODE=false
if echo "$ARGUMENTS" | grep -q -- '--minimal'; then
  MINIMAL_MODE=true
fi

if [ ${#EXISTING_FILES[@]} -gt 0 ]; then
  mkdir -p "$BACKUP_DIR"
  for file in "${EXISTING_FILES[@]}"; do
    cp "$REPO_ROOT/.specswarm/$file" "$BACKUP_DIR/$file"
  done

  echo "📦 Backed up ${#EXISTING_FILES[@]} existing guide(s) to:"
  echo "   .specswarm/.backup/$BACKUP_TS/"
  for file in "${EXISTING_FILES[@]}"; do
    echo "     - $file"
  done
  echo ""

  if [ "$RESET_MODE" = true ]; then
    echo "⚠️  --reset flag detected — existing guides will be discarded."
    echo "   Backup above is your recovery path if you change your mind."
    echo ""
  else
    echo "♻️  Reconciliation mode — existing guides will be merged with current project state."
    echo "   Developer-authored content in <!-- ss:user-additions --> blocks is preserved verbatim."
    echo "   You will be prompted to resolve any drift between declared and detected values."
    echo ""
  fi
fi