fix(deployment): repair broken command references in deployment workflow

marcusgoll · claude · marcusgoll · commit 0dd83d662532 · 2025-12-14T13:37:38.000-06:00
- ship.md: Change /ship-staging and /ship-prod from SlashCommand to Task() spawns - ship.md: Fix /deploy-prod inconsistency (now uses Task(ship-prod-phase-agent)) - ship-staging-phase-agent: Remove phantom /phase-1-ship reference, execute via gh CLI - ship-prod-phase-agent: Remove phantom /phase-2-ship reference, execute via gh CLI - budget.md: Update /phase-1-ship → /ship --staging - budget.md: Update /validate-deploy → /validate-staging The deployment commands now properly wire to their agents via Task() spawning, matching the pattern used by feature.md and epic.md. 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
diff --git a/.claude/agents/phase/ship-prod.md b/.claude/agents/phase/ship-prod.md
@@ -1,7 +1,7 @@
 ---
 name: ship-prod-phase-agent
-description: Orchestrates production deployment by promoting validated staging builds to production. Use after staging validation is complete to trigger production workflow, create GitHub releases, and update roadmap to Shipped status. Handles release versioning and deployment verification.
-tools: Read, Grep, Bash, SlashCommand
+description: Orchestrates production deployment by promoting validated staging builds to production. Spawned by /ship command to trigger production workflow, create GitHub releases, and update roadmap status.
+tools: Read, Grep, Bash
 model: sonnet
 ---
 
@@ -22,11 +22,12 @@ Your mission: Execute Phase 7 (Production Deployment) in an isolated context win
   </focus_areas>
 
 <responsibilities>
-- Call `/phase-2-ship` slash command to promote validated staging builds to production
+- Trigger production deployment workflow via gh CLI and GitHub Actions
 - Extract deployment status, release version, and production URLs from deployment reports
+- Create GitHub release with proper semantic versioning
 - Return structured summary for orchestrator with deployment verification results
 - Ensure secret sanitization in all reports and summaries
-- Validate GitHub release creation and roadmap synchronization
+- Update roadmap GitHub issue to "Shipped" status
 - Skip production deployment gracefully for local-only projects
 </responsibilities>
 
@@ -98,31 +99,61 @@ If project type is "local-only", skip this phase and return:
 **Rationale**: Local-only projects have no remote deployment target, so production deployment is not applicable.
 </step>
 
-<step number="2" name="execute_slash_command">
-**Call /phase-2-ship slash command**
+<step number="2" name="execute_deployment">
+**Execute production deployment workflow**
 
-For remote projects (staging-prod or direct-prod), use SlashCommand tool to execute:
+For remote projects (staging-prod or direct-prod), execute deployment directly via gh CLI:
 
 ```bash
-/phase-2-ship
+# Determine next version (semantic versioning)
+CURRENT_VERSION=$(git describe --tags --abbrev=0 2>/dev/null || echo "v0.0.0")
+NEXT_VERSION=$(echo "$CURRENT_VERSION" | awk -F. '{$NF = $NF + 1;} 1' | sed 's/ /./g')
+
+# Trigger production deployment workflow
+gh workflow run deploy-production.yml \
+  --ref main \
+  -f version="$NEXT_VERSION" \
+  -f feature_slug="$FEATURE_SLUG"
+
+# Wait for workflow to complete (poll every 30s for up to 10 minutes)
+WORKFLOW_RUN_ID=$(gh run list --workflow=deploy-production.yml --limit 1 --json databaseId -q '.[0].databaseId')
+
+for i in {1..20}; do
+  STATUS=$(gh run view "$WORKFLOW_RUN_ID" --json conclusion -q '.conclusion' 2>/dev/null)
+  if [ "$STATUS" = "success" ]; then
+    echo "DEPLOYMENT_STATUS=success"
+    break
+  elif [ "$STATUS" = "failure" ]; then
+    echo "DEPLOYMENT_STATUS=failed"
+    break
+  fi
+  sleep 30
+done
+
+# Create GitHub release if deployment succeeded
+if [ "$STATUS" = "success" ]; then
+  gh release create "$NEXT_VERSION" \
+    --title "Release $NEXT_VERSION" \
+    --notes "Production deployment for $FEATURE_SLUG" \
+    --target main
+fi
 ```
 
-This performs:
+This workflow performs:
 
-- Validates staging deployment (for staging-prod workflow)
-- Triggers production workflow via GitHub Actions
-- Waits for deployment completion
-- Creates GitHub release with version tag
+- Determines next semantic version from git tags
+- Triggers production deployment via GitHub Actions workflow
+- Monitors workflow completion status
+- Creates GitHub release with version tag on success
 - Updates roadmap GitHub issue to "Shipped" section
-- Generates ship-report.md with deployment metadata
 
 **Expected duration**: 3-8 minutes (varies with deployment complexity and CI/CD speed)
 </step>
 
 <step number="3" name="extract_deployment_metadata">
 **Extract key deployment information**
 
-After `/phase-2-ship` completes, analyze artifacts:
+After deployment workflow completes, analyze artifacts:
 
 ```bash
 FEATURE_DIR="specs/$SLUG"
@@ -287,7 +318,7 @@ Return structured JSON to orchestrator:
 Production deployment phase is complete when:
 
 - ✅ Project type checked (skip if local-only)
-- ✅ `/phase-2-ship` slash command executed successfully (for remote projects)
+- ✅ Production deployment workflow executed successfully (for remote projects)
 - ✅ Production workflow succeeded (exit code 0)
 - ✅ GitHub release created with correct version tag
 - ✅ Roadmap updated to "Shipped" section with deployment link
@@ -299,20 +330,20 @@ Production deployment phase is complete when:
   </success_criteria>
 
 <error_handling>
-<scenario name="slash_command_failure">
-**Cause**: `/phase-2-ship` command fails to execute
+<scenario name="workflow_execution_failure">
+**Cause**: Production deployment workflow fails to execute
 
 **Symptoms**:
 
-- SlashCommand tool returns error
-- Command times out or crashes
-- Tool permissions issue
+- gh CLI command returns error
+- GitHub Actions workflow not found
+- Workflow times out or crashes
 
 **Recovery**:
 
 1. Return blocked status with specific error message
-2. Include error details from slash command output in blockers array
-3. Report tool failure to orchestrator
+2. Include error details from gh CLI output in blockers array
+3. Report workflow failure to orchestrator
 4. Do NOT mark deployment complete
 
 **Example**:
@@ -321,10 +352,10 @@ Production deployment phase is complete when:
 {
   "phase": "ship-production",
   "status": "blocked",
-  "summary": "Production deployment failed: /phase-2-ship command execution error",
+  "summary": "Production deployment failed: workflow execution error",
   "blockers": [
-    "SlashCommand tool failed: Permission denied",
-    "Unable to trigger production workflow"
+    "GitHub workflow dispatch failed: workflow file not found",
+    "Unable to trigger production deployment"
   ],
   "next_phase": null
 }
diff --git a/.claude/agents/phase/ship-staging.md b/.claude/agents/phase/ship-staging.md
@@ -1,8 +1,8 @@
 ---
 name: ship-staging-phase-agent
-description: Orchestrates staging deployment via /phase-1-ship command. Handles PR creation, CI monitoring, auto-merge, and deployment verification. Use when shipping features to staging environment for validation. Triggers on staging deployment, ship to staging, phase 6, pre-production deployment.
+description: Orchestrates staging deployment by creating PRs, monitoring CI, auto-merging, and verifying deployment. Spawned by /ship command for staging-prod deployment model.
 model: sonnet  # Complex orchestration requiring PR management, CI monitoring, and error handling
-tools: Read, Grep, Bash, SlashCommand
+tools: Read, Grep, Bash
 ---
 
 <role>
@@ -19,12 +19,12 @@ You are a senior DevOps engineer specializing in staging deployment orchestratio
 </focus_areas>
 
 <responsibilities>
-1. Execute `/phase-1-ship` slash command to initiate staging deployment
-2. Monitor PR creation, CI checks, and auto-merge completion
+1. Create PR from feature branch to main/staging branch via gh CLI
+2. Enable auto-merge and monitor CI checks to completion
 3. Extract deployment metadata (PR number, CI status, deployment URLs)
 4. Validate quality gates (PR created, CI passing, auto-merged successfully)
 5. Sanitize all secrets before writing deployment records or summaries
-6. Return structured JSON summary to orchestrator for decision-making
+6. Return structured summary to orchestrator with deployment status
 </responsibilities>
 
 <security_sanitization>
@@ -99,24 +99,54 @@ Return skip status and proceed to next appropriate phase (finalize for local-onl
 </step>
 
 <step name="execute_deployment">
-For staging-prod deployment model, execute the staging deployment slash command.
+For staging-prod deployment model, execute the staging deployment directly via gh CLI.
 
 ```bash
-/phase-1-ship
+# Get current branch and feature slug
+CURRENT_BRANCH=$(git branch --show-current)
+FEATURE_SLUG=$(basename "$FEATURE_DIR")
+
+# Create PR from feature branch to main
+PR_URL=$(gh pr create --base main --head "$CURRENT_BRANCH" \
+  --title "feat: $FEATURE_SLUG" \
+  --body "Automated staging deployment for $FEATURE_SLUG" \
+  2>/dev/null || echo "")
+
+# If PR already exists, get its URL
+if [ -z "$PR_URL" ]; then
+  PR_URL=$(gh pr view --json url -q '.url' 2>/dev/null || echo "")
+fi
+
+# Extract PR number
+PR_NUMBER=$(echo "$PR_URL" | grep -o '[0-9]*$')
+
+# Enable auto-merge
+gh pr merge "$PR_NUMBER" --auto --squash 2>/dev/null || true
+
+# Monitor CI status (poll every 30s for up to 10 minutes)
+for i in {1..20}; do
+  CI_STATUS=$(gh pr checks "$PR_NUMBER" --json state -q '.[].state' 2>/dev/null | sort -u)
+  if echo "$CI_STATUS" | grep -q "FAILURE"; then
+    echo "CI_STATUS=failed"
+    break
+  elif echo "$CI_STATUS" | grep -qv "PENDING"; then
+    echo "CI_STATUS=passed"
+    break
+  fi
+  sleep 30
+done
 ```
 
-The `/phase-1-ship` command orchestrates:
-1. **PR Creation**: Creates pull request from feature branch to staging/main branch
+This workflow orchestrates:
+1. **PR Creation**: Creates pull request from feature branch to main branch
 2. **Auto-merge**: Configures PR to auto-merge when all checks pass
-3. **CI Monitoring**: Waits for CI/CD checks to complete
+3. **CI Monitoring**: Polls CI/CD checks every 30 seconds
 4. **Merge Execution**: Auto-merges PR when CI checks are green
-5. **Deployment Trigger**: Triggers staging deployment via CI/CD pipeline
-6. **Record Creation**: Generates deployment metadata in staging-ship-report.md
+5. **Deployment Trigger**: Merge to main triggers staging deployment via CI/CD pipeline
 
 Creates artifacts:
 - `specs/$SLUG/staging-ship-report.md` - Deployment summary with PR info and CI results
 - Updates `specs/$SLUG/NOTES.md` - Appends deployment status
-- `specs/$SLUG/deployment-metadata.json` - Structured deployment data (if available)
 </step>
 
 <step name="extract_metadata">
@@ -262,7 +292,7 @@ Return structured JSON summary to orchestrator:
 <success_criteria>
 Staging deployment phase is complete when:
 - ✅ Project type validated (skipped if local-only or direct-prod)
-- ✅ `/phase-1-ship` slash command executed successfully (for staging-prod)
+- ✅ PR created and CI monitoring executed successfully (for staging-prod)
 - ✅ PR created to staging branch with valid PR number
 - ✅ CI checks initiated and monitored to completion
 - ✅ Auto-merge configuration verified
@@ -277,7 +307,7 @@ Staging deployment phase is complete when:
 
 <error_handling>
 <command_failure>
-If `/phase-1-ship` slash command fails to execute:
+If PR creation or CI monitoring fails:
 
 1. Check prerequisites:
    ```bash
@@ -296,7 +326,7 @@ If `/phase-1-ship` slash command fails to execute:
    {
      "phase": "ship-staging",
      "status": "blocked",
-     "summary": "Staging deployment failed: slash command execution error",
+     "summary": "Staging deployment failed: PR creation or CI monitoring error",
      "blockers": [
        "Git remote not configured - cannot create PR",
        "Feature branch missing - run git checkout -b feature/$SLUG first",
diff --git a/.claude/commands/deployment/budget.md b/.claude/commands/deployment/budget.md
@@ -114,7 +114,7 @@ Track deployment quota usage and predict remaining capacity to prevent rate limi
      Next Deployment Impact
      ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
 
-     Next /phase-1-ship will use:
+     Next /ship --staging will use:
        Marketing: 1 deployment
        App: 1 deployment
        Total: 2 deployments
@@ -146,7 +146,7 @@ Track deployment quota usage and predict remaining capacity to prevent rate limi
           - Unlimited usage
 
      Preview mode usage:
-       /phase-1-ship
+       /ship --staging
        → Select 'preview' when prompted
      ```
    - **If warning status**:
@@ -156,13 +156,13 @@ Track deployment quota usage and predict remaining capacity to prevent rate limi
      ⚠️  Use quota carefully
 
      Best practices:
-       1. Run /validate-deploy before every deployment
+       1. Run /validate-staging before every deployment
        2. Use preview mode for CI testing
        3. Use staging mode only for actual staging deploys
        4. Fix issues locally before pushing
 
      Workflow:
-       /validate-deploy → /ship (preview) → verify → /ship (staging)
+       /validate-staging → /ship (preview) → verify → /ship (staging)
      ```
    - **If normal status**:
      ```
@@ -171,7 +171,7 @@ Track deployment quota usage and predict remaining capacity to prevent rate limi
      ✅ Enough quota for normal workflow
 
      Best practices:
-       1. Still run /validate-deploy to catch issues early
+       1. Still run /validate-staging to catch issues early
        2. Use preview mode for experimental changes
        3. Monitor quota with /deployment-budget
      ```
@@ -186,7 +186,7 @@ Track deployment quota usage and predict remaining capacity to prevent rate limi
 
      🚨 HIGH failure rate detected
         Run /debug to investigate issues
-        Use /validate-deploy before deploying
+        Use /validate-staging before deploying
      ```
 
 9. **Display final summary**:
@@ -210,7 +210,7 @@ Track deployment quota usage and predict remaining capacity to prevent rate limi
      Remaining: {remaining} / 100
      After next deploy: ~{projected}
 
-     Run /validate-deploy before deploying
+     Run /validate-staging before deploying
      ```
    - **Normal**:
      ```
@@ -308,7 +308,7 @@ Remaining: {remaining} / 100
 - Vercel limit: 100 deployments / 24 hours (rolling window)
 - Warning threshold: 20 remaining (allows ~10 more staging deploys)
 - Critical threshold: 10 remaining (allows ~5 more deploys)
-- Deployment cost: 2 per /phase-1-ship (Marketing + App)
+- Deployment cost: 2 per /ship --staging (Marketing + App)
 - Failure rate threshold: 30% (indicates systematic issues)
 - Read-only operations (never modify quotas)
 - Non-blocking (always returns exit code 0)
@@ -331,7 +331,7 @@ Remaining: {remaining} / 100
 - **Normal**: >= 20 remaining (✅ Safe to deploy)
 
 **Deployment costs:**
-- `/phase-1-ship` (staging): 2 deployments (Marketing + App)
+- `/ship --staging` (staging): 2 deployments (Marketing + App)
 - Preview mode: 0 deployments (doesn't count toward quota)
 
 **Rolling window calculation:**
@@ -346,8 +346,8 @@ Remaining: {remaining} / 100
 - Reserve staging mode for actual staging updates
 
 **Related commands:**
-- `/validate-deploy` - Validate deployment locally (doesn't consume quota)
-- `/phase-1-ship` - Deploy to staging (consumes 2 quota)
+- `/validate-staging` - Validate deployment locally (doesn't consume quota)
+- `/ship --staging` - Deploy to staging (consumes 2 quota)
 - `/ship` - Unified deployment orchestrator
 - `/debug` - Investigate deployment failures
 
@@ -358,7 +358,7 @@ Remaining: {remaining} / 100
 - **API errors**: Fall back to last known status
 
 **Usage scenarios:**
-- **Before `/phase-1-ship`**: Check if enough quota remains
+- **Before `/ship --staging`**: Check if enough quota remains
 - **Approaching limits**: Plan deployment strategy (preview vs staging)
 - **After failures**: Analyze failure rate to identify systematic issues
 - **Quota exhausted**: Calculate reset time to plan next deployment window
diff --git a/.claude/commands/deployment/ship.md b/.claude/commands/deployment/ship.md
