gh-martybonacci-specswarm/commands/ship.md

description, args

description	args
Quality-gated merge to parent branch - validates code quality before allowing merge	name description required --force-quality Override quality threshold (e.g., --force-quality 70) false name description required --skip-tests Skip test validation (not recommended) false

User Input

$ARGUMENTS

You MUST consider the user input before proceeding (if not empty).

Goal

Execute final quality gate validation and merge to parent branch.

Purpose: Enforce quality standards before merging features/bugfixes, preventing low-quality code from entering the codebase.

Workflow: Quality Analysis → Threshold Check → Merge (if passing)

Quality Gates:

• Default threshold: 80% quality score
• Configurable via --force-quality flag
• Reads .specswarm/quality-standards.md for project-specific thresholds

---

Pre-Flight Checks

# Ensure we're in a git repository
if ! git rev-parse --git-dir > /dev/null 2>&1; then
  echo "❌ Error: Not in a git repository"
  echo ""
  echo "This command must be run from within a git repository."
  exit 1
fi

# Get repository root
REPO_ROOT=$(git rev-parse --show-toplevel)
cd "$REPO_ROOT"

# Parse arguments
FORCE_QUALITY=""
SKIP_TESTS=false

for arg in $ARGUMENTS; do
  case "$arg" in
    --force-quality)
      shift
      FORCE_QUALITY="$1"
      ;;
    --skip-tests)
      SKIP_TESTS=true
      ;;
  esac
done

---

Execution Steps

Step 1: Display Banner

echo "🚢 SpecSwarm Ship - Quality-Gated Merge"
echo "══════════════════════════════════════════"
echo ""
echo "This command enforces quality standards before merge:"
echo "  1. Runs comprehensive quality analysis"
echo "  2. Checks quality score meets threshold"
echo "  3. If passing: merges to parent branch"
echo "  4. If failing: reports issues and blocks merge"
echo ""

CURRENT_BRANCH=$(git rev-parse --abbrev-ref HEAD)
echo "📍 Current branch: $CURRENT_BRANCH"
echo ""

---

Step 2: Run Quality Analysis

YOU MUST NOW run the quality analysis using the SlashCommand tool:

Use the SlashCommand tool to execute: /specswarm:analyze-quality

Wait for the quality analysis to complete and extract the quality score from the output.

Expected Output Pattern: Look for quality score in output (e.g., "Overall Quality: 85%")

Store the quality score as QUALITY_SCORE.

---

Step 3: Check Quality Threshold

YOU MUST NOW check if quality meets threshold:

# Determine threshold
DEFAULT_THRESHOLD=80

# Check for project-specific threshold in .specswarm/quality-standards.md
THRESHOLD=$DEFAULT_THRESHOLD

if [ -f ".specswarm/quality-standards.md" ]; then
  # Try to extract threshold from quality standards file
  PROJECT_THRESHOLD=$(grep -i "^quality_threshold:" .specswarm/quality-standards.md | grep -oE '[0-9]+' || echo "")
  if [ -n "$PROJECT_THRESHOLD" ]; then
    THRESHOLD=$PROJECT_THRESHOLD
    echo "📋 Using project quality threshold: ${THRESHOLD}%"
  fi
fi

# Override with --force-quality if provided
if [ -n "$FORCE_QUALITY" ]; then
  THRESHOLD=$FORCE_QUALITY
  echo "⚠️  Quality threshold overridden: ${THRESHOLD}%"
fi

echo ""
echo "🎯 Quality Threshold: ${THRESHOLD}%"
echo "📊 Actual Quality Score: ${QUALITY_SCORE}%"
echo ""

Decision Logic:

IF QUALITY_SCORE >= THRESHOLD:

• ✅ Quality gate PASSED
• Proceed to Step 4 (Merge) ELSE:
• ❌ Quality gate FAILED
• Display failure message
• List top issues from analysis
• Suggest fixes
• EXIT without merging

if [ "$QUALITY_SCORE" -ge "$THRESHOLD" ]; then
  echo "✅ Quality gate PASSED (${QUALITY_SCORE}% >= ${THRESHOLD}%)"
  echo ""
else
  echo "❌ Quality gate FAILED (${QUALITY_SCORE}% < ${THRESHOLD}%)"
  echo ""
  echo "The code quality does not meet the required threshold."
  echo ""
  echo "🔧 Recommended Actions:"
  echo "  1. Review the quality analysis output above"
  echo "  2. Address critical and high-priority issues"
  echo "  3. Run /specswarm:analyze-quality again to verify improvements"
  echo "  4. Run /specswarm:ship again when quality improves"
  echo ""
  echo "💡 Alternatively:"
  echo "  - Override threshold: /specswarm:ship --force-quality 70"
  echo "  - Note: Overriding quality gates is not recommended for production code"
  echo ""
  exit 1
fi

---

Step 4: Merge to Parent Branch

Quality gate passed! YOU MUST NOW merge using the SlashCommand tool:

Use the SlashCommand tool to execute: /specswarm:complete

Wait for the merge to complete.

---

Step 5: Success Report

After successful merge, display:

echo ""
echo "══════════════════════════════════════════"
echo "🎉 SHIP SUCCESSFUL"
echo "══════════════════════════════════════════"
echo ""
echo "✅ Quality gate passed (${QUALITY_SCORE}%)"
echo "✅ Merged to parent branch"
echo "✅ Feature/bugfix complete"
echo ""
echo "📝 Next Steps:"
echo "  - Pull latest changes in other branches"
echo "  - Consider creating a release tag if ready"
echo "  - Update project documentation if needed"
echo ""

---

Error Handling

If any step fails:

1. Quality analysis fails: Report error and suggest checking logs
2. Quality threshold not met: Display issues and exit (see Step 3)
3. Merge fails: Report git errors and suggest manual resolution

All errors should EXIT with clear remediation steps.

---

Notes

Design Philosophy:

• Quality gates prevent technical debt accumulation
• Encourages addressing issues before merge (not after)
• Configurable thresholds balance strictness with pragmatism
• Override flag available but discouraged for production code

Quality Standards File (.specswarm/quality-standards.md):

---
quality_threshold: 85
enforce_gates: true
---

# Project Quality Standards

Minimum quality threshold: 85%
...

If enforce_gates: false, ship will warn but not block merge.