spec-kit/templates/commands/ship.md

description, scripts

description	scripts
Automate the release pipeline including pre-flight checks, branch sync, changelog generation, CI verification, and pull request creation.	sh ps scripts/bash/check-prerequisites.sh --json --require-tasks --include-tasks scripts/powershell/check-prerequisites.ps1 -Json -RequireTasks -IncludeTasks

User Input

$ARGUMENTS

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

Pre-Execution Checks

Check for extension hooks (before ship):

• Check if .specify/extensions.yml exists in the project root.
• If it exists, read it and look for entries under the hooks.before_ship 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
• For each executable hook, output the following based on its optional flag:
  • Optional hook (optional: true):

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

  • 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 the Outline.
    

• If no hooks are registered or .specify/extensions.yml does not exist, skip silently

Goal

Automate the complete release engineering workflow: verify readiness, synchronize branches, generate a changelog, verify CI status, create a well-structured pull request, and archive release artifacts. This command transforms the implemented feature into a shippable, reviewable PR with full traceability back to the original specification.

Operating Constraints

SAFE BY DEFAULT: Every destructive operation (force push, branch delete, PR creation) requires explicit user confirmation. Default to dry-run mode for destructive git operations.

TRACEABILITY: The PR description and changelog must link back to spec, plan, tasks, review, and QA artifacts for full audit trail.

Outline

1. Run {SCRIPT} from repo root and parse FEATURE_DIR and AVAILABLE_DOCS list. All paths must be absolute. For single quotes in args like "I'm Groot", use escape syntax: e.g 'I'''m Groot' (or double-quote if possible: "I'm Groot").

2. Pre-Flight Readiness Checks: Run a comprehensive readiness assessment before proceeding:

   Task Completion:

   • Read tasks.md and count total tasks vs. completed tasks (marked [X] or [x])
   • If any tasks are incomplete: STOP and warn. Ask user to confirm proceeding or run /speckit.implement first.

   Review Status (if FEATURE_DIR/reviews/ exists):

   • Read the most recent review report
   • If verdict is ❌ CHANGES REQUIRED: STOP and warn. Recommend running /speckit.review after fixes.
   • If verdict is ⚠️ APPROVED WITH CONDITIONS: Warn but allow proceeding with confirmation.

   QA Status (if FEATURE_DIR/qa/ exists):

   • Read the most recent QA report
   • If verdict is ❌ QA FAILED: STOP and warn. Recommend running /speckit.qa after fixes.
   • If verdict is ⚠️ QA PASSED WITH NOTES: Warn but allow proceeding with confirmation.

   Working Tree:

   • Run git status to check for uncommitted changes
   • If uncommitted changes exist: prompt user to commit or stash before proceeding

   Display a readiness summary:

   Ship Readiness Check:
   ✅ Tasks: 12/12 complete
   ✅ Review: APPROVED
   ⚠️ QA: PASSED WITH NOTES (2 non-critical items)
   ✅ Working tree: Clean
   
   Overall: READY TO SHIP (with notes)
   Proceed? (yes/no)
   

3. Determine Shipping Configuration:

   • Detect the current feature branch: git branch --show-current
   • Determine the target branch (default: main; override via user input or .specify/config.yml)
   • Detect remote name (default: origin; check git remote -v)
   • Check if GitHub CLI (gh) is available for PR creation
   • If gh is not available, generate the PR description as a markdown file for manual creation

4. Branch Synchronization:

   • Fetch latest from remote: git fetch origin
   • Check if feature branch is behind target branch:

     git rev-list --count HEAD..origin/{target_branch}
     

   • If behind, offer to rebase or merge:
     • Rebase (recommended for clean history): git rebase origin/{target_branch}
     • Merge: git merge origin/{target_branch}
   • If conflicts arise: STOP and provide conflict resolution guidance
   • After sync, push the updated feature branch: git push origin {feature_branch}

5. Changelog Generation:

   • Collect changelog inputs:
     • Feature summary from spec.md (overview section)
     • Implementation highlights from completed tasks in tasks.md
     • Git commit messages: git log origin/{target_branch}..HEAD --oneline
   • Generate a structured changelog entry:

     ## [Feature Name] - {date}
     
     ### Added
     - [List of new features/capabilities from spec]
     
     ### Changed
     - [List of modifications to existing behavior]
     
     ### Fixed
     - [List of bug fixes discovered during implementation]
     
     ### Technical Notes
     - [Key architecture decisions from plan.md]
     

   • If a CHANGELOG.md exists at repo root: prepend the new entry (ask for confirmation)
   • If no CHANGELOG.md exists: create one with the entry

6. CI Verification:

   • If GitHub CLI (gh) is available:
     • Check CI status: gh run list --branch {feature_branch} --limit 5
     • If CI is running: wait and report status
     • If CI failed: STOP and display failure details. Recommend fixing before shipping.
     • If CI passed: record the passing run ID for the PR
   • If gh is not available:
     • Remind the user to verify CI status manually before merging
     • Check for local test commands and run them: npm test, pytest, go test ./..., etc.

7. Generate PR Description: Compose a comprehensive PR description from .specify/ artifacts:

   ## Summary
   [One-paragraph summary from spec.md overview]
   
   ## Specification
   [Link to or summary of key requirements from spec.md]
   
   ## Implementation
   [Key implementation decisions from plan.md]
   [Summary of completed tasks from tasks.md]
   
   ## Testing
   [QA results summary if qa/ reports exist]
   [Test coverage information]
   
   ## Review Notes
   [Summary of review findings if reviews/ reports exist]
   [Any conditions or known limitations]
   
   ## Checklist
   - [ ] All tasks completed
   - [ ] Code review passed
   - [ ] QA testing passed
   - [ ] CI pipeline green
   - [ ] Changelog updated
   - [ ] Documentation updated (if applicable)
   
   ---
   *Generated by `/speckit.ship` from spec-driven development artifacts.*
   

8. Create Pull Request:

   • If GitHub CLI (gh) is available:

     gh pr create --base {target_branch} --head {feature_branch} --title "{PR title}" --body-file {pr_description_file}
     

   • If gh is not available:
     • Save the PR description to FEATURE_DIR/releases/pr-description-{timestamp}.md
     • Provide instructions for manual PR creation
     • Output the PR title and description for copy-paste

   PR Title Format: feat: {feature_name} — {one-line summary from spec}

9. Archive Release Artifacts:

   • Create FEATURE_DIR/releases/release-{timestamp}.md with:
     • PR URL (if created via gh)
     • Changelog entry
     • Readiness check results
     • Links to review and QA reports
     • Git commit range: {base_sha}..{head_sha}

10. Post-Ship Summary: Display a completion summary:

    🚀 Ship Complete!
    
    PR: #{pr_number} - {pr_title} ({pr_url})
    Branch: {feature_branch} → {target_branch}
    Commits: {commit_count}
    Files changed: {files_changed}
    Changelog: Updated
    
    Next steps:
    - Review the PR at {pr_url}
    - After merge, run `/speckit.retro` for a retrospective
    

Check for extension hooks (after ship):

• Check if .specify/extensions.yml exists in the project root.
• If it exists, read it and look for entries under the hooks.after_ship 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
• For each executable hook, output the following based on its optional flag:
  • Optional hook (optional: true):

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

  • Mandatory hook (optional: false):

    ## Extension Hooks
    
    **Automatic Hook**: {extension}
    Executing: `/{command}`
    EXECUTE_COMMAND: {command}
    

• If no hooks are registered or .specify/extensions.yml does not exist, skip silently