ship-sdlc

name: ship-sdlc description: "Use this skill when shipping a feature end-to-end after plan acceptance: executing, committing, reviewing, fixing critical issues, versioning, and opening a PR in one flow. Dispatches every sub-skill (including execute-plan-sdlc) as an Agent for context isolation, with structured return values driving the pipeline state machine. Arguments: [--auto] [--steps ] [--quick] [--quality full|balanced|minimal] [--bump patch|minor|major|] [--draft] [--dry-run] [--resume] [--init-config]. The <label> form for --bump (e.g. --bump rc) is forwarded to version-sdlc, where it is interpreted as --bump patch --pre <label>; labels must match ^[a-z][a-z0-9]*$. Triggers on: ship it, ship this, full pipeline, execute to PR, ship feature, run the whole thing." user-invocable: true argument-hint: "[--auto] [--steps ] [--quick] [--quality full|balanced|minimal] [--bump patch|minor|major|] [--draft] [--dry-run] [--resume] [--workspace branch|worktree|prompt] [--branch | --tree] [--openspec-change ] [--init-config] [--gc] [--ttl-days ]" model: gemini-3.5-flash-medium

Ship Pipeline

End-to-end feature shipping: execute plan, commit, review, fix critical issues, version, and open a PR. Chains six sub-skills sequentially with a conditional review-fix loop.

Announce at start: "I'm using ship-sdlc (sdlc v{sdlc_version})." — extract the version from the sdlc: line in the session-start system-reminder. If no version is in context, omit the parenthetical.

Step 0 — Plan Mode Check

If the system context contains "Plan mode is active":

1. Locate skill/ship.js (same find pattern used in Step 1c below).
2. Invoke:

/skills/ship-sdlc/scripts/plan_mode_check.sh

> **Contract (Input/Output):**
> - **Input**: None.
> - **Output**: Exits non-zero if plan mode violates pipeline rules.
3. If `PLAN_MODE_EXIT` is non-zero: show any errors from the output file and stop.
4. Read the output JSON from `$PLAN_MODE_OUTPUT_FILE`. Confirm `planModeBlocked === true`. Extract `stateFile`, `flags.bump`, `flags.steps`.
5. Announce:
   > Plan mode is active. ship-sdlc requires write operations (git commit, gh pr create, git tag) and cannot run inside plan mode.
   >
   > **Pipeline state saved to `<stateFile>` with resolved flags:** bump=`<flags.bump>`, steps=`<flags.steps>`.
   >
   > Exit plan mode and re-invoke `/ship-sdlc` (no args needed) — the existing implicit-resume mechanism will pick up the saved state and resume from the first pending step with the originally-resolved flags intact.
6. Run `rm -f "$PLAN_MODE_OUTPUT_FILE"` to clean up the temp output file.
7. Stop. Do not proceed to subsequent steps.

All gates in steps 3–5 cite resolved fields from prepare output (`planModeBlocked`, `stateFile`, `flags.bump`, `flags.steps`) — never re-parse `$ARGUMENTS` directly.

---

## Step 1 (CONSUME): Load Config, Parse Flags, Detect Context

### 1a. --init-config handler

If `--init-config` was passed:

**Redirect:** Suggest running `/setup-sdlc` instead for unified configuration. If user insists on `--init-config`, proceed with the existing walkthrough.

1. Read `./resources/config-format.md` and run the interactive walkthrough to collect the user's answers (steps multi-select, bump type, auto, threshold, workspace isolation).
   After the `steps[]` selection, offer the optional `--quick` profile prompt (R-quick-7):
   > "Would you like to define a `--quick` profile? Select steps that form your shortened pipeline, or skip to omit."
   If the user selects steps, capture them. If the user skips, omit the `--quick` flag when calling `ship-init.js`.
2. Locate and call `ship-init.js` via Bash with the collected answers (append `--quick <csv>` only when the user made a quick-profile selection):
```shell
<PLUGIN_ROOT>/skills/ship-sdlc/scripts/init.sh

Contract (Input/Output):

• Input: Pipeline initialization flags.
• Output: Scaffolds internal ship state.

3. Parse the output JSON from $INIT_OUTPUT_FILE:

• If errors is non-empty, display them and stop.
• Otherwise display the created files list and config JSON for user confirmation.

4. Stop. No pipeline execution.

1a-gc. --gc handler (R39, issue #223)

If --gc (with optional --ttl-days <N>) was passed, run skill/ship.js --gc and stop — no pipeline composition. The prepare script short-circuits: it scans <main-worktree>/.sdlc/execution/ for stale ship- and execute- state files (older than TTL AND whose branch is no longer in git branch --list), removes them, and emits a JSON report.

<PLUGIN_ROOT>/skills/ship-sdlc/scripts/gc.sh

Contract (Input/Output):

• Input: None.
• Output: Garbage collects stale ship runs.

Read the prepare output. The top-level action field will be "gc"; the report field contains {ttlDays, ship: {deleted, kept}, execute: {deleted, kept}}.

Print one line per file:

[deleted] ship-deletedbranch-20240101T000000Z.json — stale+branch-gone
[kept]    ship-main-20260505T120000Z.json — ttl-fresh

Then stop. Do not proceed to step 1b. The pipeline does not run.

1b. Load ship config

Hook context fast-path: If the session-start system-reminder contains a Ship config: line, note it for display. The prepare script (skill/ship.js) remains the authoritative source for config values — the hook line is a user-facing heads-up, not a data source.

Check for ship config via skill/ship.js output (reads from .sdlc/local.json → ship section, with legacy .sdlc/ship-config.json fallback). If found, read and merge. Print loaded config verbosely:

Ship config loaded from .sdlc/local.json (schema v2)
  steps: [execute, commit, review, archive-openspec, pr], draft: false, bump: patch
  reviewThreshold: high
  execute.commitWaves: false

The execute.commitWaves field (Fixes #392 / R35) controls per-wave WIP commits during the execute step. Default false. When set to true in ship config, --commit-waves is appended to the execute step's invocation; the execute-plan-sdlc skill then runs git add -A && git commit -m "wip(execute): wave N — <titles>" after each wave's G9 + G11 pass. The subsequent commit step (commit-sdlc) detects the wip(execute): commits since fork-point and squashes them via soft-reset into the final feature commit, so the user-facing PR history is unchanged. Resolution is centralized in scripts/skill/ship.js (per scripts-over-llm-logic and flag-coherence-cross-skill guardrails) — SKILL.md cites step.invocation, never raw config.execute.commitWaves. If not found: No ship config found — using built-in defaults. Run /setup-sdlc to configure.

Legacy v1 auto-migration: If the loader detects a v1 config (no top-level version, with ship.preset or ship.skip), it migrates in place to schema v2 and emits a single stderr deprecation notice. The migrated shape (ship.steps[]) is what subsequent steps consume.

1c. Prepare pipeline context

Locate and run skill/ship.js with all CLI flags to pre-compute flags, context, and step statuses:

<PLUGIN_ROOT>/skills/ship-sdlc/scripts/prepare.sh

Contract (Input/Output):

• Input: Current branch context.
• Output: Prints JSON manifest containing PR and ship status.

Parse the output JSON from $PREPARE_OUTPUT_FILE. If errors is non-empty, display them and stop. The parsed output replaces manual computation in subsequent sub-steps (1d–1g).

Context-heaviness advisory (implements R35): If the parsed output's top-level contextAdvisory field is a non-empty string, print it verbatim before continuing. The advisory recommends /compact and notes that pipeline state is preserved across compaction (PreCompact + SessionStart hooks). Sourced from $TMPDIR/sdlc-context-stats.json, written by the UserPromptSubmit hook (hooks/context-stats.js); helper at scripts/lib/context-advisory.js. When contextAdvisory is null, emit nothing.

Gitignore warning: If context.sdlcGitignored is false in the output, print:

⚠ Warning: .sdlc/ is not gitignored. Run --init-config to fix, or manually create .sdlc/.gitignore:
  printf '*\n' > .sdlc/.gitignore

1d. Parse flags

Print the flags object from the skill/ship.js output, including the sources map showing where each value came from (CLI, config, or default):

Flag resolution (from skill/ship.js):
  auto:    true  (source: cli)
  steps:   [execute, commit, review, archive-openspec, pr]  (source: config)
  preset:  balanced  (source: cli, legacy sugar; expanded to steps)
  bump:    patch (source: default)
  draft:   false (source: default)

1e. Resume check

Hook context fast-path: If the session-start system-reminder contains an Active pipeline: line, note the state file path and resume point. When the user does not pass --resume explicitly but the hook reported an active pipeline, the Step 1c invocation already appended --hook-active-pipeline (see comment above). The prepare script then either sets flags.implicitResume === true (state file found and fresh) or returns errors[*].id === "implicitResumeNoState" (state file missing). The LLM does NOT scan the filesystem — skill/ship.js is authoritative.

Print resume.found and resume.stateFile from the skill/ship.js output. If resume.found is true, print the state file path and resume point. If false, print that no state file was found and the pipeline will start fresh.

Implicit-resume banner (R-implicit-resume, #359): When flags.implicitResume === true in the prepare output, print the following banner verbatim BEFORE the pipeline table (Step 2). Source <nextPendingStep> from resume.nextPendingStep (provided by detectResumeState() in lib/state.js) and source the step lists from the state file at resume.stateFile:

Resuming after compaction from step <nextPendingStep>.
Completed: <comma-separated step names where status === "completed">.
Pending:   <comma-separated step names where status !== "completed" && status !== "skipped">.

Note: the banner check gates on flags.implicitResume, NOT flags.resume. The prepare script auto-sets flags.resume = true when flags.implicitResume === true so the rest of the pipeline (e.g. Step 5's execute resume forwarding) sees a unified flags.resume regardless of whether the user typed --resume or the hook triggered it.

Missing-state prompt (R-implicit-resume): If the prepare output's errors array contains an entry with id === "implicitResumeNoState", use AskUserQuestion:

Active pipeline reminder found but no state file for current branch. Start fresh, or specify a state path?

Options:

• fresh — re-invoke skill/ship.js without --hook-active-pipeline so the pipeline starts cleanly
• path — ask the user for an explicit state file path, then re-invoke with --state-file <path>
• abort — exit cleanly without dispatching any step

Read ./resources/state-format.md when resuming from a state file.

1f. Context detection

Print the context object values from the skill/ship.js output:

Context detection (from skill/ship.js):
  Plan in context:     yes
  Uncommitted changes: 14 files modified
  Current branch:      feat/ship-sdlc
  Default branch:      main
  gh CLI:              authenticated as <user>
  OpenSpec:            not detected
  .sdlc/ gitignored:   yes

Contradictory-signal override (implements R21): After printing the context detection block, IF context.openspecAuthoritative.path is set AND the current session-start <system-reminder> contains a line matching /openspec.*not initialized|not initialized.*openspec/i, print exactly one line: Ignoring contradictory 'not initialized' signal in session context — openspec/config.yaml exists (authoritative source: SDLC's own check via ship.js prepare output). Then continue the flow. If the contradictory phrase is absent, emit nothing.

1g. Auto-skip logic

Print each step from the steps array in the skill/ship.js output with its status, reason, and skipSource:

Auto-skip decisions (from skill/ship.js):
  execute: will_run — plan detected in context
  commit:  will_run — uncommitted changes detected
  review:  will_run — not in skip set
  received-review: conditional — depends on review verdict
  commit (fixes): conditional — depends on received-review changes
  version: skipped (auto) — auto-skipped — tags are repo-global
  archive-openspec: conditional — openspec change ready for archive
  pr:      will_run — not in skip set

The parenthetical after skipped reflects the step's skipSource field:

• (cli) — user passed --steps on the command line
• (quick) — step is canonical but absent from ship.quick under an active --quick run (R-quick-4); flags.sources.steps === 'quick' in the prepare output
• (config) — skip set loaded from .sdlc/local.json
• (auto) — auto-skipped by computeSteps logic (e.g., worktree mode)
• (condition) — conditional step whose condition was not met

Steps with skipSource: "none" are not skipped and show no parenthetical.

The LLM does not compute these statuses — skill/ship.js is the source of truth.

Step 2 (PLAN): Build Pipeline Plan

The pipeline table is generated from the steps array in the skill/ship.js output. Each row maps:

• Step number: array index + 1
• Skill: step.skill
• Status: step.status
• Args: step.args
• Pause: step.pause ? 'YES' : 'no'

--auto Mode Audit

Not all sub-skills support --auto. This table is the source of truth:

Review verdict conditional logic

After review-sdlc completes, parse the conversation for a Verdict: line. The verdict label (CHANGES REQUESTED / APPROVED WITH NOTES / APPROVED) is display-only — it is included in the run banner but does NOT gate dispatch. Dispatch is gated exclusively by flags.reviewThreshold (resolved by scripts/skill/ship.js):

If the threshold is met → invoke received-review-sdlc (forward "--auto" when flags.auto). Otherwise → collect findings and defer to the pipeline summary report.

Example run-banner lines (display-only — do NOT control dispatch):

Review verdict: CHANGES REQUESTED (1 critical, 2 high)
Review verdict: APPROVED WITH NOTES (3 medium, 1 low)
Review verdict: APPROVED

In --auto mode, dispatch is automatic and received-review-sdlc --auto is forwarded — no interactive pause.

Step 3 (CRITIQUE): Validate Pipeline

Print each validation check:

Pipeline validation:
  [pass] gh CLI authenticated
  [pass] Not on default branch (feat/ship-sdlc)
  [pass] 5 of 7 steps will run
  [pass] All skip values recognized
  [pass] Version step supports --auto (release approval prompt skipped in auto mode)
  [warn] If review finds critical/high issues, pipeline will pause for fix approval

Validation checks:

• gh auth status succeeds
• Current branch is not the default branch (warn if it is — do not block)
• All --steps values are recognized step names: execute, commit, review, version, archive-openspec, pr, learnings-commit
• When flags.sources.steps === 'quick' in the prepare output, verify that flags.steps is non-empty (R-quick-6 error would have fired if ship.quick was missing — non-empty confirms the quick profile resolved correctly). Cite flags.sources.steps, NOT raw --quick or $ARGUMENTS, at all decision sites (R-quick-2, R-quick-3).
• --quick and --steps are mutually exclusive — R-quick-5 error fires if both are present; surface from errors[] in prepare output, not re-checked independently.
• At least one step will run
• Flag combinations are coherent (--bump without version step → warn). --bump accepts major|minor|patch or any pre-release label matching ^[a-z][a-z0-9]*$ (e.g. --bump rc ships an RC release; the label is forwarded verbatim to version-sdlc).

Step 4 (DO): Present Pipeline and Confirm

Dry-run mode

If --dry-run, display the full pipeline table and stop:

Ship Pipeline (dry run)
────────────────────────────────────────────────────────────────
Step  Skill                 Status       Args              Pause?
────────────────────────────────────────────────────────────────
1     execute-plan-sdlc     will run     (none)             no
2     commit-sdlc           will run     --auto            no
3     review-sdlc           will run     --committed       no
4     received-review-sdlc  conditional  (if crit/high)    YES
5     commit-sdlc (fixes)   conditional  --auto            no
6     version-sdlc          skipped      —                 —
7     pr-sdlc               will run     --auto --draft    no
────────────────────────────────────────────────────────────────
Review threshold: critical or high findings trigger fix loop
Interactive pauses: received-review (if triggered)

Auto mode

Display the pipeline table for visibility, then proceed without prompting.

Interactive mode

Display the pipeline table, then:

Use AskUserQuestion to ask:

Run this pipeline?

Options:

• yes — execute as shown
• edit — change steps, flags, or other config
• cancel — stop here

On edit: ask what to change, update flags, rebuild the pipeline table, and re-present. Loop until yes or cancel.

Step 5 (EXECUTE): Run Pipeline Steps Sequentially

Pre-step validation

Before dispatching each step, read its status from the skill/ship.js output:

1. "will_run" → dispatch via Agent tool. Inline-executed steps (skill === null, dispatchMode: null) are not dispatched via a tool — they are handled directly in main context (either as Bash commands or as conditional logic such as parsing a JSON verdict, as specified per-step). This is non-negotiable.
2. "conditional" → evaluate the runtime condition (e.g., review verdict). If condition met → dispatch via Agent tool. If not → print why with the specific condition that was not met.
3. "skipped" → print "skipped" with the reason and skipSource from the script output.

A step with status: "will_run" MUST be dispatched per its dispatchMode. The LLM does not have authority to override dispatchMode or skip a will_run step. Printing a skip message for a "will_run" step is a pipeline violation.

Context budget — dispatch isolation

All sub-skills are Agent-dispatched for context isolation: each Agent loads its SKILL.md in its own context and returns only a structured result (5–10 lines). The ship pipeline's context receives structured data, not sub-skill definitions.

execute-plan-sdlc is the orchestrator and returns a Step-9-formatted result (waves completed, files modified, state file path) for ship's main-context loop to consume. Agent dispatch restores pipeline continuity by returning control to ship-sdlc after execute completes, enabling R37 branch migration, the staging window, and remaining steps. (Fixes #366.)

Dispatch protocol

Invocation source: Each step in the skill/ship.js output includes an invocation field containing the skill name and computed args. Use step.invocation verbatim — do not construct invocations from the examples below.

For each step that will run, apply the dispatch protocol based on step.dispatchMode:

When step.dispatchMode === 'agent' — Agent-tool dispatch (all sub-skills)

1. Print verbose progress header to user:

   ━━━ Ship Pipeline — Step 2/7: Commit ━━━
     Skill: commit-sdlc
     Args: --auto
     Reason: --auto forwarded from ship --auto mode
   

2. Record step start via state/ship.js.

3. Dispatch Agent with: skill name, args from step.invocation, model from step.model (which natively carries the correctly mapped suffix from ship.js), and brief pipeline context (branch, previous step results needed for this step). Pass model: step.model to the Agent tool on every dispatch. When step.isolation is non-null, additionally pass isolation: step.isolation; when step.isolation is null, omit the isolation parameter entirely (the Agent tool schema does not accept null for isolation). The LLM must not add, remove, or change the isolation parameter from what ship.js computed (implements R-agent-isolation-script-driven, C15). Agent prompt template:

   You are executing the <skill-name> skill. Invoke `/<skill-name> <args>` using the Skill tool — this loads the SKILL.md automatically. Return a structured result:
   (1) status — success or failure
   (2) result summary — 2-3 lines
   (3) artifacts — commit hash, tag, PR URL, verdict, etc.
   (4) any warnings or issues encountered
   

4. Receive agent result. Print result to user:

     [done] Step 2 complete: a1b2c3d feat(auth): add OAuth2 PKCE flow
     State saved to .sdlc/execution/ship-<branch>-<timestamp>.json
   

5. Record step completion/failure via state/ship.js.

6. Use result to determine next step (e.g., review verdict → received-review decision). Print decision reasoning:

     Review verdict: APPROVED WITH NOTES (2 medium)
     Decision: CONTINUING — no critical/high issues found
   

Ship-sdlc retains full control of: pipeline table display, validation output, step progress headers, result formatting, state persistence messages, verdict-based flow decisions, and the final summary report. Sub-skills only execute their skill and return structured data — they do not print pipeline-level output.

Main-thread TodoWrite orchestration (R-todowrite-visibility, #427)

ship-sdlc surfaces live pipeline progress in the Antigravity Code task tray via main-thread TodoWrite calls. All derivation logic lives in scripts/lib/ship-todos.js (R-todowrite-visibility clause 11). The MAIN thread invokes the helper via Bash and passes the returned todos[] array to the TodoWrite tool. The helper's marker field is echoed verbatim to stdout (audit trail when the tray is hidden).

Setup (one-time, BEFORE the Step 5 dispatch loop, only when flags.steps.length >= 2):

1. Run: <PLUGIN_ROOT>/skills/ship-sdlc/scripts/todos_wrapper.sh --state-file "$STATE_FILE" --event init (where $STATE_FILE is the resolved ship state file path from Step 1c output).
2. Parse JSON from stdout. Call TodoWrite with todos array.
3. Echo marker verbatim to stdout.

For ultra-short runs (flags.steps.length < 2), skip TodoWrite entirely.

Per-step transition (called at start of EACH Step 5 iteration, BEFORE the verbose progress header):

1. Run: <PLUGIN_ROOT>/skills/ship-sdlc/scripts/todos_wrapper.sh --state-file "$STATE_FILE" --event step --current-step <stepName>.
2. Parse JSON, call TodoWrite, echo marker.

Per-step completion (called AFTER the Agent return and result print, AFTER state/ship.js complete records success):

1. Run: <PLUGIN_ROOT>/skills/ship-sdlc/scripts/todos_wrapper.sh --state-file "$STATE_FILE" --event step --current-step <stepName> --mark-completed <stepName>.
2. Parse JSON, call TodoWrite, echo marker.

Per-step failure (called when state/ship.js fail records a failure):

1. Run: <PLUGIN_ROOT>/skills/ship-sdlc/scripts/todos_wrapper.sh --state-file "$STATE_FILE" --event step --current-step <stepName> --fail-step <stepName>.
2. Parse JSON, call TodoWrite, echo marker.
3. No todo lingers in_progress (helper enforces — AC4).

Resume reconstruction (called inside the existing implicit-resume banner block, BEFORE the pipeline table prints, when flags.resume === true):

1. Run: <PLUGIN_ROOT>/skills/ship-sdlc/scripts/todos_wrapper.sh --state-file "$STATE_FILE" --event resume --current-step <resume.nextPendingStep>.
2. Parse JSON, call TodoWrite, echo marker.

flags.resume === true is the single gate (the prepare script unifies explicit --resume and flags.implicitResume; this matches the existing implicit-resume banner condition and satisfies no-opposite-logical-vectors).

Cross-skill note: execute-plan-sdlc's internal per-wave TodoWrite calls remain (Agent-context bookkeeping). They are NOT parent-visible — see execute-plan-sdlc/SKILL.md Progress signal section and R-todowrite-visibility, issue #427.

Workspace isolation and branch setup (R60, R61, R62, R65, R37 — fixes #378, #379)

Skip on resume re-entry (flags.resume === true) or when WORKSPACE_MODE = continue — the resume block below already handled mode/cwd, and continue requires no setup.

When NOT resuming, resolve workspace mode, enforce default-branch guard, assert correct cwd, and create branch/worktree by calling the unified setup script. Derive <logical-type> and <derived-slug> from the plan title in context:

SETUP_JSON=$(<PLUGIN_ROOT>/skills/ship-sdlc/scripts/workspace_setup.sh \
  --workspace-flag "$WORKSPACE_MODE_FLAG" \
  --prepare-output-file "$PREPARE_OUTPUT_FILE" \
  --logical-type "<logical-type>" \
  --derived-slug "<derived-slug>")

Contract (Input/Output):

• Input: Workspace flags.
• Output: Prints JSON containing worktreePath and branch data.

Where $WORKSPACE_MODE_FLAG is set from the --workspace CLI flag parsed by the prepare script, and $PREPARE_OUTPUT_FILE is the path to the prepare JSON file.

Parse the output SETUP_JSON from stdout:

1. If status is "error", print the error message and halt.
2. Extract workspaceMode, executeBranch, and worktreePath.
3. If worktreePath is set (non-empty), the LLM must explicitly use worktreePath as the current working directory (Cwd parameter) for all subsequent shell commands and Agent dispatches (e.g. execute-plan-sdlc, commit-sdlc, review-sdlc, pr-sdlc, etc.). If worktreePath is empty, continue using the current workspace directory.
4. Pass --branch "$executeBranch" to execute-plan-sdlc in the execute dispatch (see "Execute step" section below) so execute-plan-sdlc knows which branch is active.

The setup script handles ship state migration (state/ship.js migrate) internally before creating any branch or worktree.

Execution loop

Execute step resume: When the pipeline is resuming (gate on flags.resume === true from the prepare output — this is true whether the user typed --resume or the hook triggered implicit resume; do NOT re-parse $ARGUMENTS) and the execute step's status in the ship state file is in_progress:

1. Check for <main-worktree>/.sdlc/execution/execute-<branch>-*.json (an execute-plan-sdlc state file for the current branch). Resolve <main-worktree> via git worktree list --porcelain (first worktree line).
2. If found, dispatch execute-plan-sdlc via the Agent tool with args from step.invocation plus --resume (e.g. "--quality <X> --resume" if the user passed --quality to ship; "--resume" otherwise). Wave progress and gates run inside the Agent's sub-context; the structured return value drives the next step. (Implements R-implicit-resume — flags.resume is the single resume signal regardless of source.)
3. If not found, dispatch via Agent tool normally using step.invocation (execute restarts from scratch)

ship-sdlc does not manage execute-plan-sdlc's state file — execute-plan-sdlc handles its own creation, updates, and cleanup.

Worktree re-entry on resume: Check context.worktree.inLinkedWorktree from the skill/ship.js output. If true, already in the worktree — proceed normally.

If false (resuming from the main worktree but the pipeline originally ran in a worktree), find the worktree for the resume branch:

git worktree list --porcelain

Match the branch from the ship state file against worktree entries. If found and directory exists, cd <path> before continuing. If the worktree directory is gone, warn and fall back to running on the current branch.

Execute-step todo mirroring (R-todowrite-visibility clause 4):

Assign PLAN_FILE by parsing the JSON output of the resolve plan script:

PLAN_FILE=$(<PLUGIN_ROOT>/skills/ship-sdlc/scripts/resolve_plan_file.sh "$SHIP_PREPARE_OUTPUT_FILE" | node -e "process.stdin.on('data',d=>{try{process.stdout.write(JSON.parse(d).planFile||'')}catch(_){}})")

Contract (Input/Output):

• Input: Prepare output file path.
• Output: Prints resolved plan file path.

Where $SHIP_PREPARE_OUTPUT_FILE is the path to the temp file holding the skill/ship.js JSON output. When PLAN_FILE is empty, the ship-todos.js execute event will fail. Surface that error before dispatching.

Before dispatching execute-plan-sdlc, run:

<PLUGIN_ROOT>/skills/ship-sdlc/scripts/todos_wrapper.sh --state-file "$STATE_FILE" --plan-file "$PLAN_FILE" --event execute --current-step execute

Contract (Input/Output):

• Input: --state-file, --event, --current-step.
• Output: Updates the IDE Todo UI and prints confirmation.

$PLAN_FILE is the resolved plan file path. The helper expands the execute step's placeholder substep to one substep per plan task (one ### Task N: heading per substep). Parse JSON, call TodoWrite, echo marker.

Then dispatch execute-plan-sdlc as below. On Agent return (success), run the post-execution completeness invariant before marking the step complete (R-INVARIANT-COMPLETENESS, #432):

<PLUGIN_ROOT>/skills/ship-sdlc/scripts/verify_completeness.sh --state-file "$STATE_FILE" --plan-file "$PLAN_FILE"

Contract (Input/Output):

• Input: --state-file, --plan-file.
• Output: Evaluates task completeness and exits non-zero if incomplete.

If verify-completeness exits 65, the pipeline MUST halt before commit. The missing task IDs appear on stderr as JSON {missingIds, totalPlanned, totalAccounted}. Do NOT advance to the commit step.

Then run per-step-completion: <PLUGIN_ROOT>/skills/ship-sdlc/scripts/todos_wrapper.sh --state-file "$STATE_FILE" --event step --current-step execute --mark-completed execute. The parent does NOT receive per-task completion signals from the Agent; per-task todos all transition to completed atomically on return.

Example dispatch sequence (use step.invocation for actual args):

• Agent: execute-plan-sdlc, args: from step.invocation PLUS --branch "$EXECUTE_BRANCH" when EXECUTE_BRANCH is set (i.e. WORKSPACE_MODE is branch or worktree). When WORKSPACE_MODE is continue, omit --branch (execute handles its own isolation or runs on existing branch). Example: "--quality balanced --branch feat/my-feature". This implements R60 step 5 — execute-plan-sdlc short-circuits its own Step 1 isolation in response (R30).
• Agent: commit-sdlc, args: "--auto"
• Agent: review-sdlc, args: "--committed"
• Agent: received-review-sdlc, args: "--auto" (when flags.auto; otherwise no args)
• Agent: version-sdlc, args: "patch"
• Agent: pr-sdlc, args: "--auto --draft"

Post-execute note (R37 migration moved pre-execute)

Branch migration (R37) now runs before the execute dispatch — inside the pre-execute workspace isolation block (see "Pre-execute workspace isolation" section above). The old post-execute migration block has been removed (fixes #379 — it ran after cwd changed, so git branch --show-current always returned the wrong value).

Subsequent state operations (start, complete, read) automatically pick up the renamed file because state/ship.js resolves by current branch.

Between execute and commit

execute-plan-sdlc does not stage files. Run git add -A -- ':!.sdlc/' with verbose output:

Staging changes from execution:
  A  src/middleware/auth.ts
  A  src/middleware/auth.test.ts
  M  src/routes/index.ts
  Total: 14 files staged
  Reason: execute-plan-sdlc creates files but does not stage them. .sdlc/ excluded to prevent committing runtime state.

Between review and received-review

Evaluate the verdict (see Step 2 conditional logic). Print the decision tree. If received-review-sdlc triggers and makes changes, check git status:

Review fixes applied: 3 files modified
  M  src/middleware/auth.ts
  M  src/routes/index.ts
  M  tests/auth.test.ts
  → Running commit step for review fixes

Then invoke commit-sdlc (step 5) for the fix commit.

After version — post-version ancestry HARD GATE (R-post-version-ancestry, fixes #349)

After the version step dispatches and returns, capture the new tag from the version-sdlc return value as NEW_TAG. When NEW_TAG is set (non-empty) AND EXECUTE_BRANCH is set (non-empty), run the ancestry check:

<PLUGIN_ROOT>/skills/ship-sdlc/scripts/verify_ancestry.sh

Contract (Input/Output):

• Input: None.
• Output: Fails if the branch is not properly rebased.

NEW_TAG is the tag string emitted by version-sdlc (e.g. v1.2.3). EXECUTE_BRANCH is the feature branch variable set during pre-execute workspace isolation (already available in the pipeline shell context). This gate is a no-op when NEW_TAG is unset (version step was skipped or not in flags.steps, e.g., under workspace: worktree). Works correctly under both workspace: branch and workspace: worktree.

Between version and pr — archive-openspec (conditional)

If the archive-openspec step has status: "conditional" in the pipeline plan, execute it inline (no Agent dispatch — this is a deterministic shell operation):

1. Extract the change name from step.args (--change <name>).
2. Call lib/openspec.js::validateChangeStrict(projectRoot, name) via Bash:

   <PLUGIN_ROOT>/skills/ship-sdlc/scripts/openspec_validate.sh '<name>'
   

   Contract (Input/Output):

   • Input: Spec <name>.
   • Output: Validates OpenSpec shape, exits non-zero on error.

3. If ok === false: halt the pipeline. Print the validation errors (stderr) and save state for --resume.
4. If ok === true: prompt the user for approval (skip prompt in --auto mode).
5. On approval, run the archive:

   <PLUGIN_ROOT>/skills/ship-sdlc/scripts/openspec_archive.sh '<name>'
   

   Contract (Input/Output):

   • Input: Spec <name>.
   • Output: Archives the specification.

6. If archive succeeds, commit:

   git add openspec/
   git commit -m "chore(openspec): archive <name>"
   

7. If isArchived(projectRoot, name) already returns true (idempotence), skip with reason "already archived".

If the step has status: "skipped", print the skip reason from step.reason.

After pr — verify-pipeline (conditional, opt-in)

If the verify-pipeline step has status: "will_run" (gated by step membership in flags.steps — cite step.status === "will_run" from the prepare output, not $ARGUMENTS; per flag-coherence-cross-skill), execute it inline (no Agent dispatch — this is a deterministic polling script). Implements R41–R49.

1. Resolve the script path:

/skills/ship-sdlc/scripts/verify_pipeline.sh

> **Contract (Input/Output):**
> - **Input**: None.
> - **Output**: Fetches CI status, exits non-zero on pipeline failure.
2. Run the script with the args from `step.args` plus `--state-file <ship-state-path>`:
   ```bash
   node "$VP_SCRIPT" $STEP_ARGS --state-file "$SHIP_STATE_PATH"

3. Parse the single JSON line on stdout. Branch on status:

   status === "green" — log verify-pipeline: CI green for PR #N and proceed to await-remote-review. Cites R43.

   status === "failed" AND flags.auto === false — interactive (R45). Use AskUserQuestion:

   Wave verify-pipeline failed for PR #N. failed checks: .

   Options: analyze (Recommended) | skip | abort

   • analyze: dispatch verify-pipeline-sdlc subagent (Agent tool, model gemini-3.5-flash-high) with --pr <N> and --logs <inline-log-excerpt-from-failedChecks>. On verdict fix-applied, dispatch commit-sdlc (Agent tool, model gemini-3.5-flash-medium, --auto) directly to commit and push. Then re-run verify-pipeline (loop). Iteration cap = flags.verifyPipelineMaxIterations (default 3, R47); after cap, log warning and proceed to await-remote-review. The pre-existing commit-fixes step entry (already visited before pr) is NOT involved — this dispatch is direct via the Agent tool.
   • skip: log warning, proceed to await-remote-review.
   • abort: write verifyPipelineExhausted: true to the ship state file, exit pipeline 1.

   status === "failed" AND flags.auto === true — non-interactive (R46). Directly dispatch verify-pipeline-sdlc subagent (Agent tool, model gemini-3.5-flash-high) with --pr <N> --logs <excerpt> --auto. On fix-applied, dispatch commit-sdlc --auto directly (Agent tool, model gemini-3.5-flash-medium). Loop with the same iteration cap (flags.verifyPipelineMaxIterations, R47). On cap exhaustion, log warning and proceed.

   status === "timeout" — log warning verify-pipeline: timeout after Ns. The script has already written verifyPipelineExhausted: true to the state file. Proceed to await-remote-review. Cites R48, R49.

   status === "skipped" (resume short-circuit) — log info verify-pipeline: skipped (resumed from prior exhaustion). Proceed. Cites R49.

   status === "error" — log warning verify-pipeline: error — <reason>. Proceed.

Do NOT replicate polling, log fetching, or fix-application logic in this prose — those live in verify-pipeline.js and the verify-pipeline-sdlc skill (per scripts-over-llm-logic).

If the step has status: "skipped", print the skip reason from step.reason and do nothing.

After verify-pipeline — await-remote-review (conditional, opt-in)

If the await-remote-review step has status: "will_run" (gated by step membership in flags.steps — cite step.status === "will_run" from the prepare output, not $ARGUMENTS), execute it inline. Implements R50–R56.

1. Resolve the script path:

/skills/ship-sdlc/scripts/await_review.sh

> **Contract (Input/Output):**
> - **Input**: None.
> - **Output**: Blocks until PR is approved or returns review findings.
2. Run the script with the args from `step.args` plus `--state-file <ship-state-path>`:
   ```bash
   node "$AR_SCRIPT" $STEP_ARGS --state-file "$SHIP_STATE_PATH"

3. Parse the single JSON line on stdout. Branch on status:

   status === "actionable" — directly dispatch received-review-sdlc (Agent tool, model gemini-3.5-flash-high) with --pr <verdict.prNumber> (and --auto when flags.auto === true). After the subagent completes, run git status --porcelain in the main context; if there are working-tree changes, directly dispatch commit-sdlc (Agent tool, model gemini-3.5-flash-medium, --auto) to commit and push. The pre-existing received-review and commit-fixes step entries (already visited before pr) are NOT involved — these dispatches are direct via the Agent tool. Cites R52.

   status === "approved-clean" — log await-remote-review: APPROVED by <reviewer> and proceed. Do NOT dispatch received-review-sdlc. Cites R53.

   status === "timeout" — log warning await-remote-review: timeout after Ns waiting for <reviewers>. The script has already written awaitRemoteReviewExhausted: true to the state file. Proceed. Cites R54, R55.

   status === "skipped" (resume short-circuit) — log info and proceed. Cites R55.

   status === "error" — log warning and proceed.

If the step has status: "skipped", print the skip reason from step.reason and do nothing.

After pr — learnings-commit (final step)

Pipeline-level learnings cannot land in the feature commit (issue #208) — review/version/pr/archive all run after the feature commit. The learnings-commit step exists to capture them in a trailing chore commit so post-pipeline git status is clean.

If the learnings-commit step has status: "will_run", execute it inline (no Agent dispatch — deterministic shell):

1. Run the ship-level Learning Capture (see the ## Learning Capture section below) — append any new entries to .sdlc/learnings/log.md.
2. Check whether anything actually changed:

   git diff --quiet -- .sdlc/learnings/log.md
   

   • Exit 0 (no diff) → skip the commit and report learnings-commit: no-op (no new learnings).
3. If there is a diff:

   git add .sdlc/learnings/log.md
   git commit -m "chore(ship-sdlc): capture pipeline learnings"
   git push
   

   On push failure (offline, auth), report the error but do not halt the pipeline — the local commit still lands and a follow-up git push will deliver it.
4. After the step, git status --porcelain MUST be empty.

If the step has status: "skipped" (omitted from --steps or ship.steps[]), print the skip reason from step.reason and do not perform any of the above. The execute-plan-sdlc-level Learning Capture (R27 in docs/specs/execute-plan-sdlc.md) still runs and lands in the feature commit; only the ship-level append is conditional on this step.

Between last commit and version — rebase on default branch

After all commits are done (feature commit + optional review-fix commit + optional archive commit), rebase onto the latest default branch to ensure a clean merge:

git fetch origin <defaultBranch>

Check if rebase is needed:

git merge-base --is-ancestor origin/<defaultBranch> HEAD

If main is already an ancestor of HEAD, no rebase needed — print "Already up to date with <defaultBranch>" and skip.

Otherwise, attempt rebase:

git rebase origin/<defaultBranch>

If rebase succeeds: Print summary and continue.

Rebase: clean — <N> commits replayed on origin/<defaultBranch>

If rebase fails (conflicts): Abort and handle:

git rebase --abort

List conflicting files from the failed output. Then:

Auto mode: Stop pipeline, save state for --resume. Print:

Rebase: CONFLICTS detected with origin/<defaultBranch>
  Conflicting files:
    - src/foo.ts
    - src/bar.ts
  Pipeline paused. Resolve conflicts manually, then --resume.

Interactive mode: Use AskUserQuestion:

Rebase onto <defaultBranch> has conflicts in files:

• src/foo.ts
• src/bar.ts

1. Pause pipeline — resolve manually, then --resume
2. Skip rebase — create PR with conflicts (GitHub will show merge conflicts)
3. Merge instead — try git merge origin/<defaultBranch> (creates merge commit)

Option 3 fallback: run git merge origin/<defaultBranch>. If that also conflicts, abort and fall back to option 1.

Note: in a worktree, all of this is safe — main working tree is untouched.

State persistence

After each step, update pipeline state using the state wrapper script: <PLUGIN_ROOT>/skills/ship-sdlc/scripts/state_wrapper.sh.

At pipeline start (after Step 1 completes), initialize the state file:

<PLUGIN_ROOT>/skills/ship-sdlc/scripts/state_wrapper.sh init --branch <branch> --flags '<flags JSON>'

Contract (Input/Output):

• Input: Action (init, start, complete, etc.) and step args.
• Output: Mutates pipeline state files.

Before each step: <PLUGIN_ROOT>/skills/ship-sdlc/scripts/state_wrapper.sh start --step After each step: <PLUGIN_ROOT>/skills/ship-sdlc/scripts/state_wrapper.sh complete --step --result "

{
  "method": "bash",
  "normal": "<PLUGIN_ROOT>/skills/ship-sdlc/scripts/state_wrapper.sh cleanup-pipeline",
  "forced": "<PLUGIN_ROOT>/skills/ship-sdlc/scripts/state_wrapper.sh cleanup-pipeline --force"
}

<PLUGIN_ROOT>/skills/ship-sdlc/scripts/todos_wrapper.sh --state-file "$STATE_FILE" --event cleanup --current-step cleanup

Terminal cleanup:
  Current run: deleted ship-<branch>-<ts>.json
  GC swept: 1 ship-* file, 0 execute-* files (1 deleted, kept 1 ttl-fresh)

PIPELINE CONTRACT VIOLATION
The following steps were not resolved:
  - <step>: status "<status>" (expected: completed, skipped, or failed)

State file preserved for debugging: <path>
This is a pipeline bug — all will_run steps must be dispatched.

Ship Pipeline Complete
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
Step  Skill                 Result
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
1     execute-plan-sdlc     [done] 8 tasks, 3 waves completed
2     commit-sdlc           [done] a1b2c3d feat(auth): add OAuth2 PKCE
3     review-sdlc           [done] APPROVED WITH NOTES (2 medium)
4     received-review-sdlc  — not triggered (no critical/high)
5     commit-sdlc (fixes)   — not triggered
6     version-sdlc          — skipped (config default)
7     pr-sdlc               [done] https://github.com/.../pull/42
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

Decisions log:
  - Steps resolved: [execute, commit, review, archive-openspec, pr] (from config default; --quality not forwarded to execute-plan-sdlc — user did not pass --quality)
  - Version step skipped (from config default, bump type: patch)
  - Review found 2 medium issues — below threshold, deferred
  - PR created as draft (from --draft flag)

Deferred review findings (2 medium):
  1. [medium] src/middleware/auth.ts:42 — Consider extracting token validation
  2. [medium] src/routes/index.ts:15 — Missing rate limit on new endpoint
  → Run /received-review-sdlc to address these

State file cleaned up: .sdlc/execution/ship-<branch>-<epoch>.json deleted

main_wt=$(git worktree list --porcelain | head -1 | sed 's/worktree //')
current=$(git rev-parse --show-toplevel)

Worktree kept: <current path>
  Branch: <branch name>
  To remove later: cd <main_wt> && git worktree remove <current>

Note: Version step was skipped (worktree mode — tags are repo-global).
After merging this PR, run on main:
  /version-sdlc <patch|minor|major>
This will tag the release and generate the changelog from all merged commits.

Step <N> (<name>) failed: <error summary>
State saved to: <state file path>
To resume: /ship-sdlc --resume

## YYYY-MM-DD — ship-sdlc: <brief summary>
<what was learned>