Runs autonomous full-cycle spex pipeline from spec to verify on brainstorm files, with oversight levels, auto-fixes, error handling, and optional PR creation.
From spexnpx claudepluginhub rhuss/cc-spex --plugin spexThis skill uses the workspace's default tool permissions.
This pipeline runs ALL stages without stopping. After completing any stage, you MUST immediately begin the next stage. There are no natural stopping points between stages.
The pipeline is ONE continuous task. It starts at the first stage and runs through the last stage. The ONLY reasons to pause are:
ask is always AND a review stage has findings requiring user input.After every stage: update the state file, then immediately start the next stage. No waiting, no confirmation, no stopping.
This skill chains the entire spex workflow autonomously: specify, clarify, review-spec, plan, review-plan, tasks, implement, deep-review, and verify. Point it at a brainstorm document and choose an oversight level to control how much human oversight the pipeline requires.
This skill requires both superpowers and deep-review traits to be enabled.
Check that required traits are enabled:
SUPERPOWERS=$(jq -r '.traits.superpowers // false' .specify/spex-traits.json 2>/dev/null)
DEEP_REVIEW=$(jq -r '.traits["deep-review"] // false' .specify/spex-traits.json 2>/dev/null)
if [ "$SUPERPOWERS" != "true" ] || [ "$DEEP_REVIEW" != "true" ]; then
echo "ERROR: spex:ship requires both superpowers and deep-review traits."
echo ""
echo "Enable them with:"
echo " /spex:traits enable superpowers deep-review"
echo ""
echo "Missing traits:"
[ "$SUPERPOWERS" != "true" ] && echo " - superpowers"
[ "$DEEP_REVIEW" != "true" ] && echo " - deep-review"
fi
If either trait is missing, STOP with the error message above. Do not proceed.
Before starting the pipeline, verify the working tree is clean:
if [ -n "$(git status --porcelain 2>/dev/null)" ]; then
echo "ERROR: Working tree has uncommitted changes."
echo ""
echo "Please commit or stash your changes before running spex:ship:"
echo " git stash"
echo " # or"
echo " git add -A && git commit -m 'WIP: save before ship'"
fi
If the worktree is dirty, STOP with the error message. Do not proceed.
If --coderabbit is explicitly set (not just inherited from config defaults), validate authentication at startup:
# Only check if --coderabbit was explicitly passed as a flag
which coderabbit >/dev/null 2>&1 && coderabbit auth status 2>&1 || echo "CODERABBIT_AUTH_FAILED"
If auth check fails when CodeRabbit was explicitly requested, STOP with:
ERROR: CodeRabbit authentication failed.
You explicitly requested CodeRabbit with --coderabbit, but auth is not configured.
Run without --coderabbit or configure CodeRabbit authentication first.
If CodeRabbit is only enabled via config defaults (not explicit flag), skip auth validation and let the deep-review stage handle missing tools gracefully.
Parse the invocation arguments. The skill accepts:
brainstorm/. If omitted, auto-detect (see Brainstorm File Resolution below).| Flag | Default | Description |
|---|---|---|
--ask <level> | smart | One of: always, smart, never |
--create-pr | off | Create a pull request after successful completion |
--resume | off | Resume an interrupted pipeline from state file |
--start-from <stage> | (none) | Start from a specific stage (skips prior stages) |
--no-external | (from config) | Disable all external review tools |
--external | (from config) | Enable all external review tools |
--no-coderabbit | (from config) | Disable CodeRabbit |
--coderabbit | (from config) | Enable CodeRabbit |
--no-copilot | (from config) | Disable Copilot |
--copilot | (from config) | Enable Copilot |
Oversight level: Validate that the value is one of always, smart, never. If invalid, fail with:
ERROR: Invalid oversight level "X". Must be one of: always, smart, never
External tool flags: Follow the same resolution pattern as the review-code skill:
Read config defaults:
DEFAULT_ENABLED=$(jq -r '.external_tools.enabled // true' .specify/spex-traits.json 2>/dev/null)
DEFAULT_CODERABBIT=$(jq -r '.external_tools.coderabbit // true' .specify/spex-traits.json 2>/dev/null)
DEFAULT_COPILOT=$(jq -r '.external_tools.copilot // true' .specify/spex-traits.json 2>/dev/null)
Start with config defaults:
coderabbit = DEFAULT_ENABLED && DEFAULT_CODERABBIT
copilot = DEFAULT_ENABLED && DEFAULT_COPILOT
Apply CLI flag overrides (flags always win, applied in order):
--external sets both to true--no-external sets both to false--coderabbit / --no-coderabbit overrides coderabbit only--copilot / --no-copilot overrides copilot onlyTrack whether --coderabbit was explicitly set (for auth validation).
--resume and --start-from are mutually exclusive with each other. If both are provided, fail with:
ERROR: Cannot use both --resume and --start-from. Choose one.
--resume does not accept a brainstorm file. If --resume is set alongside a brainstorm file, fail with:
ERROR: Cannot specify a brainstorm file with --resume. The brainstorm file is read from the state file.
--start-from allows a brainstorm file when starting from specify (since it needs one). When starting from any other stage, a brainstorm file argument is ignored.
The following stage names are accepted: specify, clarify, review-spec, plan, tasks, review-plan, implement, review-code, verify.
If an invalid stage name is provided, fail with:
ERROR: Invalid stage "X". Valid stages are: specify, clarify, review-spec, plan, tasks, review-plan, implement, review-code, verify
Resolve the brainstorm document to use as input:
If a path is provided: Validate it exists.
[ -f "$BRAINSTORM_FILE" ] || echo "ERROR: Brainstorm file not found: $BRAINSTORM_FILE"
If no path is provided: Auto-detect the highest-numbered brainstorm file:
ls -1 brainstorm/[0-9]*.md 2>/dev/null | sort -t/ -k2 -V | tail -1
If no brainstorm files found: Fail with:
ERROR: No brainstorm files found in brainstorm/ directory.
Available files:
$(ls brainstorm/ 2>/dev/null || echo " (directory does not exist)")
Create a brainstorm document first with /spex:brainstorm
The pipeline tracks its progress in .specify/.spex-ship-phase as JSON. All state file operations use the spex-ship-state.sh script. Never write the state file directly.
Locate the script:
SHIP_STATE="$(dirname "$(dirname "$(cd "$(dirname "$0")" && pwd)")")/scripts/spex-ship-state.sh"
# Or find it via the plugin:
SHIP_STATE="$(find ~/.claude -path '*/spex/scripts/spex-ship-state.sh' 2>/dev/null | head -1)"
| Command | What it does |
|---|---|
spex-ship-state.sh create <brainstorm> [--ask <level>] [--start-from <stage>] | Create state file at pipeline start |
spex-ship-state.sh advance | Advance to the next stage (auto-cleans up after stage 8) |
spex-ship-state.sh status | Show current stage and status |
spex-ship-state.sh pause | Set status to paused |
spex-ship-state.sh fail | Set status to failed |
spex-ship-state.sh cleanup | Remove state file (pipeline done) |
After every stage completes, run:
"$SHIP_STATE" advance
This advances stage and stage_index to the next stage with status: running. After the final stage (verify), advance automatically removes the state file and outputs PIPELINE_COMPLETE.
Do NOT manually write JSON to the state file. Always use the script.
When --resume is set:
Read the state file:
if [ ! -f .specify/.spex-ship-phase ]; then
echo "ERROR: No interrupted pipeline found."
echo "Start a new pipeline with: /spex:ship <brainstorm-file>"
exit 1
fi
STATE=$(cat .specify/.spex-ship-phase)
Extract the last stage and its index:
LAST_STAGE=$(echo "$STATE" | jq -r '.stage')
LAST_INDEX=$(echo "$STATE" | jq -r '.stage_index')
AUTONOMY=$(echo "$STATE" | jq -r '.ask')
BRAINSTORM=$(echo "$STATE" | jq -r '.brainstorm_file')
Check the status field to determine resume behavior:
status is "paused" or "failed": resume from LAST_INDEX (retry the same stage).status is "running": resume from LAST_INDEX (the stage was interrupted mid-execution).status is "completed": report that the pipeline already completed and clean up the state file.If the calculated resume index is >= 9, the pipeline was already complete. Report this and clean up.
Reset retries to 0 in the state file before resuming (so the resumed stage gets fresh retry attempts).
Re-validate values from the state file before proceeding:
ask is one of always, smart, neverbrainstorm_file exists (if resuming the specify stage)stage_index is in range 0-8Update the state file with status: running before proceeding.
When --start-from <stage> is set:
Map the stage name to its index (0-8).
Verify that expected artifacts exist for stages that depend on prior output:
clarify and later need spec.md to existplan and later need spec.mdtasks and later need plan.mdreview-plan and later need plan.md and tasks.mdimplement and later need tasks.mdIf expected artifacts are missing, warn (do not fail):
WARNING: Starting from stage "implement" but tasks.md was not found.
The implement stage may fail if required artifacts are missing.
Proceeding anyway...
Create a fresh state file with the starting stage and begin execution.
The brainstorm file is not needed when starting from a stage after specify. If starting from specify, a brainstorm file is required (auto-detect or fail).
These rules are non-negotiable. They override any judgment about efficiency or convenience.
When starting a fresh pipeline (no --start-from, no --resume), you MUST execute ALL 9 stages in sequence: specify, clarify, review-spec, plan, tasks, review-plan, implement, review-code, verify.
You MUST NOT:
When running from stage 0 (specify), the pipeline creates all artifacts from scratch. If spec.md, plan.md, or tasks.md already exist from a prior run, they are overwritten by the new pipeline run. Do NOT reuse artifacts from previous runs unless resuming with --resume or explicitly starting later with --start-from.
--start-from and --resume allow skippingThese are the ONLY two mechanisms for starting at a stage other than specify:
--start-from <stage>: User's explicit choice to skip prior stages. The user takes responsibility for ensuring prior artifacts exist and are valid.--resume: Continues from where a previous run was interrupted, using the state file.If neither flag is set, the pipeline starts at stage 0 and runs through stage 8. No automatic detection of "oh, we can skip ahead because artifacts exist."
Before executing each stage, verify that:
running for the current stageIf a stage fails or is interrupted, the pipeline MUST NOT silently proceed to the next stage. It must either pause (for findings), fail (for errors), or retry (within the 2-retry limit).
Do NOT apply "smart" behavior to the pipeline flow itself:
The --ask flag controls oversight within review stages (how findings are handled). It does NOT control which stages run. ALL stages run regardless of the ask level.
You MUST complete these steps before invoking ANY speckit command or skill. Do not skip ahead to stage execution.
SHIP_STATE="$(find ~/.claude -path '*/spex/scripts/spex-ship-state.sh' 2>/dev/null | head -1)"
[ -x "$SHIP_STATE" ] && echo "SCRIPT_OK: $SHIP_STATE" || echo "SCRIPT_MISSING"
If SCRIPT_MISSING: STOP. The spex plugin may not be installed correctly.
"$SHIP_STATE" create "<brainstorm-file>" --ask "<ask-level>" --start-from "<start-stage>"
The output will confirm: CREATED stage=<stage> index=<N> ask=<level>. If it fails, STOP.
Output a brief status message confirming the pipeline configuration before running any stage:
## spex:ship starting
- **Brainstorm**: <file>
- **Starting stage**: <stage> (<index>/9)
- **Oversight**: <ask-level>
- **State file**: .specify/.spex-ship-phase (created)
Only after all three steps complete successfully, proceed to Pipeline Stages below.
The pipeline executes 9 stages in fixed order:
| Index | Stage | Invocation | Description |
|---|---|---|---|
| 0 | specify | /speckit.specify | Generate spec from brainstorm |
| 1 | clarify | /speckit.clarify | Resolve spec ambiguities |
| 2 | review-spec | {Skill: spex:review-spec} | Validate spec quality |
| 3 | plan | /speckit.plan | Generate implementation plan |
| 4 | tasks | /speckit.tasks | Generate task breakdown |
| 5 | review-plan | {Skill: spex:review-plan} | Validate plan, tasks, and generate REVIEWERS.md |
| 6 | implement | /speckit.implement | Execute implementation |
| 7 | review-code | {Skill: spex:review-code} | Spec compliance + code review + deep review + REVIEWERS.md update |
| 8 | verify | {Skill: spex:verification-before-completion} | Final verification |
When running inside the ship pipeline, no /speckit.* command may pause for user input unless the ask level is always. This overrides any instruction in the speckit command prompts themselves. Specifically:
speckit.specify: Do not ask "Shall I proceed?" after spec creation. Proceed to the next stage.speckit.clarify: Do not present questions interactively in smart or never mode. Auto-select recommended answers.speckit.plan: Do not ask for confirmation before or after planning. Proceed to the next stage.speckit.tasks: Do not ask for confirmation. Proceed to the next stage.speckit.implement: Do not pause at trait overlay gates. Proceed to the next stage.Trait overlays (e.g., superpowers adding review after specify) may run their reviews, but their results are informational. Do NOT pause or ask the user before proceeding. The ship pipeline's own stage gate logic handles all oversight decisions.
This is a hard override. If a speckit command prompt says "present to user" or "wait for answer", and ask is smart or never, you answer it yourself and continue.
Even if spec.md already exists, this stage re-creates it from the brainstorm document. A fresh pipeline means fresh artifacts.
/speckit.specify passing the brainstorm content as the feature description.
FEATURE_BRANCH=$(git branch --show-current)
"$SHIP_STATE" advance to move to Stage 1, then immediately begin it (do not stop).Worktree compatibility: The worktrees trait is NOT recommended with spex:ship. The worktrees overlay creates a sibling worktree during specify, which requires restarting the Claude Code session in the new directory, breaking the autonomous pipeline. Ship works best by creating a feature branch in-place. If you want main isolation, create a worktree manually before starting ship:
git worktree add ../project-wip main
cd ../project-wip && claude
# then: /spex:ship brainstorm/NNN-feature.md
Do NOT skip this stage. Clarify may uncover ambiguities that are not obvious from reading the spec.
Read the ask level from the state file (default: smart).
BEFORE invoking clarify, determine the interaction mode:
ask is smart or never: You are the decision-maker. Do NOT use AskUserQuestion or present options to the user. When the clarify process identifies ambiguities, YOU select the recommended option for each question. If no recommendation exists, use your best judgment based on the spec context. Answer all questions yourself, then encode the answers into the spec.ask is always: Present each question to the user interactively.Invoke /speckit.clarify on the generated spec. The clarify command will try to present interactive questions. In smart and never modes, this is overridden: answer every question yourself with the recommended option. Do NOT wait for user input. Do NOT display questions with "You can reply with..." prompts. Process all questions in a single pass and update the spec.
After clarification completes, run "$SHIP_STATE" advance then immediately begin Stage 2 (do not stop).
Do NOT skip this stage. Review-spec validates structural quality, not just ambiguities.
{Skill: spex:review-spec} to validate spec quality."$SHIP_STATE" advance then immediately begin Stage 3 (do not stop)./speckit.plan to generate the implementation plan.plan.md, research.md, data-model.md, and other artifacts."$SHIP_STATE" advance then immediately begin Stage 4 (do not stop)./speckit.tasks to generate the task breakdown.tasks.md."$SHIP_STATE" advance then immediately begin Stage 5 (do not stop).{Skill: spex:review-plan} to validate plan coverage and task quality.plan.md and tasks.md (generated in stages 3 and 4).REVIEWERS.md."$SHIP_STATE" advance then immediately begin Stage 6 (do not stop)./speckit.implement to execute the implementation plan."$SHIP_STATE" advance then immediately begin Stage 7 (do not stop).{Skill: spex:review-code}."$SHIP_STATE" advance then immediately begin Stage 8 (do not stop).{Skill: spex:verification-before-completion} for final verification."$SHIP_STATE" advance (this outputs PIPELINE_COMPLETE and removes the state file). Immediately proceed to Pipeline Completion (do not stop).After each review stage (review-spec, review-plan, review-code, verify), evaluate the findings:
Classify each finding into one of three categories:
Unambiguous (auto-fixable in smart and never):
Ambiguous (requires judgment, pauses in smart):
Blocker (always pauses, even in never):
| Oversight Level | Unambiguous | Ambiguous | Blocker |
|---|---|---|---|
always | Pause | Pause | Pause |
smart | Auto-fix | Pause | Pause |
never | Auto-fix | Auto-fix | Pause |
When auto-fixing findings:
retries in the state file.Pipeline paused after 2 fix cycles for stage "review-code".
Remaining findings could not be auto-resolved.
[Present remaining findings here]
Please provide guidance on how to proceed.
retries to 0 when moving to the next stage.When the pipeline pauses (due to findings that need human input):
status: "paused".## Pipeline Paused at Stage: review-spec
### Findings Requiring Your Input
**Ambiguous (need your judgment):**
1. [Finding description with context]
2. [Finding description with context]
**Blockers (must be resolved):**
1. [Finding description with context]
Please review these findings and provide guidance. You can:
- Address specific findings ("fix #1 by doing X")
- Skip findings ("skip #2, it's intentional")
- Provide general guidance ("proceed, these are acceptable")
After the user responds:
status: "running".After all stages complete successfully:
status: "completed".started_at.## Pipeline Complete
**Feature branch:** <branch-name>
**Stages completed:** 9/9
**Oversight mode:** <mode>
**Elapsed time:** <duration>
All stages passed successfully:
0. specify - spec.md created
1. clarify - spec clarified
2. review-spec - spec validated
3. plan - plan.md generated
4. tasks - tasks.md generated
5. review-plan - plan validated, REVIEWERS.md generated
6. implement - code implemented
7. review-code - code reviewed, REVIEWERS.md updated
8. verify - verification passed
rm -f .specify/.spex-ship-phaseIf --create-pr is set and all stages passed:
Determine the remote target:
REMOTE=$(git remote | grep -x upstream 2>/dev/null || echo origin)
Push the feature branch:
git push -u "$REMOTE" "$(git branch --show-current)"
Create the PR. Identify the spec directory from the feature branch:
BRANCH=$(git branch --show-current)
SPEC_DIR="specs/${BRANCH}"
FEATURE_NAME=$(head -1 "$SPEC_DIR/spec.md" | sed 's/^# Feature Specification: //')
gh pr create \
--title "$FEATURE_NAME" \
--body "$(cat <<PREOF
## Summary
Autonomous pipeline implementation of $FEATURE_NAME.
See \`$SPEC_DIR/REVIEWERS.md\` for detailed review guidance.
## Artifacts
- Spec: \`$SPEC_DIR/spec.md\`
- Plan: \`$SPEC_DIR/plan.md\`
- Tasks: \`$SPEC_DIR/tasks.md\`
- Review Guide: \`$SPEC_DIR/REVIEWERS.md\`
Generated by \`/spex:ship\` in $AUTONOMY mode.
Assisted-By: Claude Code
PREOF
)"
Report the PR URL.
If --create-pr is not set:
Pipeline complete. No PR created (use --create-pr to auto-create).
Next steps:
- Review changes: git diff main...HEAD
- Create PR manually: gh pr create
- Run additional reviews: /spex:review-code
This skill is invoked by:
/spex:shipThis skill invokes:
/speckit.specify (Stage 0)/speckit.clarify (Stage 1){Skill: spex:review-spec} (Stage 2)/speckit.plan (Stage 3)/speckit.tasks (Stage 4){Skill: spex:review-plan} (Stage 5)/speckit.implement (Stage 6){Skill: spex:review-code} (Stage 7){Skill: spex:verification-before-completion} (Stage 8)Required traits: superpowers, deep-review
Not recommended: worktrees trait (creates a session restart mid-pipeline; use manual worktree setup instead)