ship
Implement approved SDD tasks through the quality gate to Done — the second of the two-command workflow. Run after /sdd-bootstrap:bootstrap and human task approval.
- License 许可
- MIT
- 最近更新
- 2026-11-15
- Stars
- ★ 0
- Forks
- 0
01 前言 Front Matter
- name
- ship
- description
- Implement approved SDD tasks through the quality gate to Done — the second of the two-command workflow. Run after /sdd-bootstrap:bootstrap and human task approval.
- disable-model-invocation
- true
03 SKILL.md 正文
SDD Ship
Orchestrate approved tasks from implementation through quality verification to Done.
This skill does not write specifications; use /sdd-bootstrap:bootstrap for that.
Invocation
Claude Code:
/sdd-ship:ship specs/<feature>/tasks.md
/sdd-ship:ship specs/<feature>/tasks.md#T-001
/sdd-ship:ship
/sdd-ship:ship --lite specs/<feature>/tasks.md
/sdd-ship:ship --full specs/<feature>/tasks.md
/sdd-ship:ship --verify specs/<feature>/tasks.md
/sdd-ship:ship --retro specs/<feature>/tasks.md
Codex:
Use the ship skill for specs/<feature>/tasks.md
Use the ship skill (no argument — context-aware selection)
Flags
| Flag | Effect |
|---|---|
--lite |
Force lite track (lite-gate) regardless of AGENTS.md spec_profile |
--full |
Force full track (quality-gate); verifies acceptance-tests.md + traceability.md exist |
--verify |
Before quality-gate, run cross-model-verify for tasks that have Cross-Model: enabled |
--retro |
Run workflow-retrospective after all tasks reach Done |
--fix RT-NNN is NOT a sdd-ship flag. Apply a review ticket directly:
/sdd-quality-loop:fix-by-review-ticket docs/review-tickets/RT-NNN.yml
Preconditions
Before doing any work, verify that AGENTS.md exists at the repository root and
that scripts/check-sdd-structure.sh (or .ps1) reports no missing: items.
If either check fails, stop immediately and direct the user to run
/sdd-bootstrap:bootstrap adopt. Do not proceed without it.
Do not invoke sdd-sudo, create SDD_SUDO, or modify the SDD_SUDO file.
Sudo management is always a separate human action.
MCP Preflight (Advisory)
Attempt get_next_sdd_command with no arguments; if it is unavailable or
the call fails, continue with the file-based flow below.
get_next_sdd_command is read-only: it only reads repository state and
returns a suggestion, never writing or mutating anything. Its answer is
advisory — it does not decide the target, the track, or any step that
follows. ## Step 1 — Target Selection below remains the sole decision
procedure, and nothing this step reads changes what ## Step 1 concludes.
This step is unconditional: apply it the same way regardless of invocation
form (a specs/<feature>/tasks.md path argument, an optional #T-NNN task
selector, or the zero-argument auto-select form) and regardless of track
(full / lite) — do not skip or gate it by invocation form or track. Do not
surface the unavailability or the failure to the user as a run failure.
If the probe's suggestion and the conclusion ## Step 1 — Target Selection
reaches disagree, state in the output both that a disagreement occurred and
which source was acted on. Always act on the ## Step 1 conclusion in that
case, never the probe's.
Step 1 — Target Selection
With a path argument
Use the given specs/<feature>/tasks.md (with optional #T-NNN task selector).
If #T-NNN is given, only process that single task.
Zero-argument (no path given)
- Read
AGENTS.mdat the repository root. Look for an## Active Spec Directoriessection listing feature paths. - For each listed path, check
specs/<feature>/tasks.mdfor at least one task withApproval: ApprovedandStatus: PlannedorStatus: In Progress. - Exactly one match: print
[sdd-ship AUTO-SELECT] specs/<feature>/tasks.mdand proceed without asking the user. - Zero matches: print "No active features with Approval: Approved tasks found. Run /sdd-bootstrap:bootstrap first." and stop.
- Multiple matches: list all candidates with task counts and print "Multiple active features found. Re-run: /sdd-ship:ship specs/<feature>/tasks.md" and stop without touching any feature.
Step 2 — Track Detection
This is sdd-ship's Capability-Mode-relevant entry point. Run the
hook-activation handshake HERE, as the first Capability-Mode-relevant action,
before trusting any Project Context content:
<!-- sdd:handshake-wiring v1 -->
check-hook-activation-handshake --emit-challenge— returns a fresh single-use nonce and the canary targetsdd/.hook-canary-sentinel. If a sentinel from an earlier run is already present, perform and record one cleanup attempt first; the new challenge proceeds either way.- This agent session makes its own real tool-call attempt against that canary target, using the per-runtime template the challenge carries, and records the raw result verbatim. The tool never performs the probe write itself.
check-hook-activation-handshake --verify-response --nonce <nonce> --recorded-result <path> --runtime <claude-code|codex-cli|copilot-cli>.HOOK_ACTIVE— continue to track resolution. Any other outcome stops Capability Mode only, and which projects that stops is decided by the gate table below, not by this step alone: stop withCAPABILITY_RUNTIME_UNAVAILABLEif and ONLY if this project's Project Context is physically present and valid (gate G2); if it is physically absent, the project never entered Capability Mode, so continue on the compatibility fallback asDISABLED_LEGACY(gates G3/G4). From a valid-Context project, never fall back to legacy behaviour silently.
<!-- /sdd:handshake-wiring -->
When the presence/validity probe runs. The handshake itself never reads the Project Context, so step 4 records an outcome without yet knowing which gate row applies. The physical-presence-and-validity probe that decides G1/G2 from G3/G4 is the FIRST step of "Track resolution" below, and it runs THERE — after the handshake, before any track is chosen. This section precedes track resolution because it is normative about the handshake's meaning; it is not an instruction to probe earlier.
What a non-HOOK_ACTIVE handshake does and does not stop
Step 4 above stops Capability Mode, not every invocation of this skill. Which of the two it is depends on whether this project ever entered Capability Mode, and the table below is normative in BOTH directions:
<!-- sdd:capability-gate-scope v1 -->
| Gate | Project Context | Handshake | Resolution |
|---|---|---|---|
| G1 | physically present and valid | HOOK_ACTIVE |
CAPABILITY_MODE |
| G2 | physically present and valid | not HOOK_ACTIVE |
CAPABILITY_RUNTIME_UNAVAILABLE |
| G3 | physically absent | HOOK_ACTIVE |
DISABLED_LEGACY |
| G4 | physically absent | not HOOK_ACTIVE |
DISABLED_LEGACY |
<!-- /sdd:capability-gate-scope -->
- G2 — stop. A project that HAS a valid Project Context has entered
Capability Mode, so a handshake that could not observe a genuine,
nonce-matched denial MUST stop with
CAPABILITY_RUNTIME_UNAVAILABLE, and MUST NOT degrade to the compatibility-fallback path below. That degradation is precisely the silent downgrade ADR-0023 exists to close:design.md:1112requires the calling skill to stop Capability Mode, never to silently fall back to legacy. - G4 — continue. A project that has NO Project Context never entered
Capability Mode. It sits in ADR-0016's
disabled-legacy, which is "a normal, expected condition for a project with no Project Context, not an error" (requirements.md:1821-1827), and whichCAPABILITY_RUNTIME_UNAVAILABLEis "never conflated with" (design.md:1734). The handshake gatesHOOK_ACTIVE-gated behaviour only (requirements.md:1078), so a non-HOOK_ACTIVEresult does not stop such a project: it continues on the compatibility fallback below.
The prohibited transition is Capability Mode → legacy. Legacy → legacy is not
a downgrade, and G4 must never be reported as CAPABILITY_RUNTIME_UNAVAILABLE
merely because G2 is.
Track resolution
Resolve the track next. Physical presence is decided FIRST and alone;
REQ-005 approval validation runs SECOND, only once the file is known to
exist. A sdd/project-context.yaml that exists but fails
validate-approval-sidecar is not the same as one that is absent —
treating the two alike is the fail-open ADR-0023 closes.
<!-- sdd:track-selection-contract v1 -->
| Case | Project Context | Flag | Resolution |
|---|---|---|---|
| C1 | physically absent | --full, --lite, or none |
COMPATIBILITY_FALLBACK |
| C2 | physically present, REQ-005 validation fails | --full, --lite, or none |
PROJECT_CONTEXT_INVALID |
| C3 | physically present and valid, spec_profile: lite |
--full |
PROMOTE_FULL |
| C4 | physically present and valid, spec_profile: lite |
--lite |
NO_OP_LITE |
| C5 | physically present and valid, spec_profile: full |
--lite |
ERROR_STOP |
| C6 | physically present and valid, spec_profile: full |
--full |
NO_OP_FULL |
<!-- /sdd:track-selection-contract -->
COMPATIBILITY_FALLBACK(C1 only) — apply the compatibility fallback below, unchanged from the pre-ADR-0023 contract.PROJECT_CONTEXT_INVALID(C2) — stop before any task is started and print[sdd-ship] PROJECT_CONTEXT_INVALID: sdd/project-context.yaml is present but its approval could not be verified.Do not start implementation, do not invoke any gate, do not change anyStatus, and do not fall through to C1's fallback or to an implicitfull/liteselection.PROMOTE_FULL(C3) — resolved track isfull. Print[sdd-ship] Track: full (PROMOTE_FULL), then verify the full-track artifacts as described below.NO_OP_FULL(C6) — resolved track isfull. Print[sdd-ship] Track: full (NO_OP_FULL), then verify the full-track artifacts as described below.NO_OP_LITE(C4) — resolved track islite. Print[sdd-ship] Track: lite (NO_OP_LITE)and run the risk-upgrade scan below before starting any task.ERROR_STOP(C5) —--liteagainst a declaredfullprofile would loosen the declared profile. Stop before any task is started and print[sdd-ship] ERROR_STOP: --lite cannot downgrade a Project Context declaring spec_profile: full. Re-run without --lite.It is never silently ignored and never silently honoured.
Full-track artifact verification (PROMOTE_FULL, NO_OP_FULL, and the
fallback's --full route): verify that specs/<feature>/acceptance-tests.md
and specs/<feature>/traceability.md both exist. If either is missing, stop
and instruct the user to run full-track sdd-bootstrap.
PLUGIN-CONTRACTS.md's Track Detection section is the normative source for
this table.
Risk-upgrade scan
A resolved full track is the only scan bypass. For every route that could
resolve to LITE — NO_OP_LITE, or any remaining default, profile, or
--lite route of the compatibility fallback — build a local UTF-8 input by
concatenating the selected task's complete ## T-NNN block followed by that
feature's requirements.md. Both inputs are mandatory; do not retrieve remote
issue text and do not use a partial task block.
Run the platform-local checker before considering a lite branch:
plugins/sdd-lite/scripts/check-risk-upgrade.sh <task-block-plus-requirements>
powershell -NoProfile -ExecutionPolicy Bypass -File plugins/sdd-lite/scripts/check-risk-upgrade.ps1 -Path <task-block-plus-requirements>
- Exit 10 with
full-required: <primary-id>; triggers=<ordered-ids>forces FULL track even when--litewas requested. Print the checker diagnostic followed by[sdd-ship] Track: full (risk-upgrade)and verify the full-trackacceptance-tests.mdandtraceability.mdartifacts before task start. If either is absent, stop before task start and print[sdd-ship] Full-track artifacts unavailable. Run /sdd-bootstrap:bootstrap for the full track. - Exit 2 with
risk-upgrade: input unavailableis fail-closed: stop before implementation or the lite gate, print that diagnostic, and direct the user to restore the selected task block and requirements or run full bootstrap. - Exit 0 with
lite-eligibleallows the resolved lite track to proceed.
Compatibility fallback (no Project Context)
Reached only from case C1, and unchanged from the pre-ADR-0023 contract. Execute in this priority order (first match wins):
--fullflag present → FULL track. Print[sdd-ship] Track: full (--full override). Verify thatspecs/<feature>/acceptance-tests.mdandspecs/<feature>/traceability.mdboth exist. If either is missing, stop and instruct the user to run full-track sdd-bootstrap or drop--fulland use--lite.--liteflag present → LITE track. Print[sdd-ship] Track: lite (--lite override).- Read
AGENTS.md. Ifspec_profile: liteappears on any line → LITE track. Print[sdd-ship] Track: lite (spec_profile: lite in AGENTS.md). - Default → FULL track. Print
[sdd-ship] Track: full (no lite profile detected).
The track message is always printed before any task is started.
If the wrong track is selected, the user can cancel (Ctrl-C) and re-run with
the correct --lite or --full flag.
Step 3 — Implementation Loop
Full track
Invoke /sdd-implementation:implement-tasks specs/<feature>/tasks.md.
That skill handles dependency ordering, per-task state transitions
(Planned → In Progress → Implementation Complete), and implementation reports.
Do not re-implement the dependency resolution logic here; delegate entirely to implement-tasks.
Lite track
Invoke /sdd-implementation:implement-task specs/<feature>/tasks.md#T-NNN for
each Approved + Planned/In-Progress task in tasks.md order. Lite track has no
dependency graph; implement tasks in document order.
Resume behaviour
On re-invocation after interruption, skip tasks already at Implementation Complete
or Done. Resume from the first eligible task (Approved + Planned or In Progress).
Step 4 — Quality Gate Loop
Execute after all targeted tasks reach Implementation Complete.
Full track
For each task at Implementation Complete, in tasks.md document order:
-
Cross-model verification runs before the gate. A task whose tasks.md entry carries
Risk: criticalorSecurity-Sensitive: trueMUST have cross-model verification run in this same ship invocation before it reaches the quality gate, regardless of whether--verifywas passed. For each such task, invoke/sdd-quality-loop:cross-model-verify specs/<feature>/tasks.md#T-NNNbefore the gate.- Human-gated waiver. Skip the required cross-model run for such a task
only when its tasks.md entry records a
Cross-Model-Waiver:that is VALID. A waiver is valid only when the SAME task also carries a humanApproval: Approvedaudit mark naming a second distinct human approver (the human-only mark the deterministic guard already prevents an agent from writing, and the same distinct-approver rule already mandated for critical tasks). ACross-Model-Waiver:that lacks that co-located human-approval context is treated as ABSENT (fail-closed) and cross-model verification remains required. An agent cannot grant itself a waiver, because it cannot produce the human approval mark the waiver depends on. Guard-level enforcement of the waiver token itself is out of scope here (future hardening); the waiver is inert without the human approval context. - Fail-closed stop. If such a task has neither a completed cross-model
run in this invocation nor a valid waiver, STOP the ship flow before the
quality gate and print a diagnostic naming the task:
[sdd-ship] Cross-model verification required for T-NNN (Risk: critical or Security-Sensitive: true), but it neither ran this invocation nor carries a valid Cross-Model-Waiver: (a valid waiver needs a co-located human Approval: Approved mark naming a second distinct approver). Run cross-model verification or record a valid waiver, then re-invoke.
Independently of the requirement above, if the
--verifyflag was passed and the task hasCross-Model: enabledin its tasks.md entry: invoke/sdd-quality-loop:cross-model-verify specs/<feature>/tasks.md#T-NNNbefore the gate.- If no task in the batch has
Cross-Model: enabled, print a warning:[sdd-ship] --verify passed but no tasks have Cross-Model: enabled. Add the field to task entries that require panelist verification. - On lite track,
--verifyis silently ignored with the same warning.
- Human-gated waiver. Skip the required cross-model run for such a task
only when its tasks.md entry records a
-
Invoke
/sdd-quality-loop:quality-gate specs/<feature>/tasks.md#T-NNN. -
PASS (Done): task transitions to Done. Continue to next task.
-
BLOCKED (review tickets created): stop immediately. Print:
[sdd-ship] Quality gate blocked for T-NNN. Review tickets written to docs/review-tickets/. Address each ticket, then re-invoke: /sdd-quality-loop:fix-by-review-ticket docs/review-tickets/RT-NNN.ymlDo not proceed to other tasks while any task is Blocked. -
Cycle limit (disk-based — survives re-invocation across sessions): before invoking quality-gate, run the deterministic cycle-limit script for this task instead of counting reports by hand:
plugins/sdd-quality-loop/scripts/check-quality-gate-cycle-limit.sh T-NNN <feature>On a Windows host without
python3/node, run the PowerShell twin instead:pwsh plugins/sdd-quality-loop/scripts/check-quality-gate-cycle-limit.ps1 T-NNN <feature>The script counts THIS FEATURE's existing gate reports under
reports/quality-gate/(word-boundary match on the task id soT-001does not matchT-0010, AND an anchored match on this feature's ownFeature:header line, so a different feature's report sharing the same bare task id is never counted; an absent directory counts zero) and prints its decision:continue(exit 0): fewer than three reports — proceed to invoke quality-gate for T-NNN.Escalate-Human(non-zero exit): three or more reports and the task is still not Done — do not invoke quality-gate again and do not prompt for fix-by-review-ticket; stop and instruct the human to investigate manually.
Because each quality-gate run writes a durable timestamped report under
reports/quality-gate/, this limit is computed from disk and holds across separate/sdd-ship:shipinvocations and sessions (it does not reset per invocation).
Lite track
For each task at Implementation Complete:
- Ineligibility check (before the lite gate). If the task's tasks.md entry
carries
Risk: criticalorSecurity-Sensitive: true, it is INELIGIBLE for the lite track, because the lite track has no cross-model step. The lite gate rejects it: STOP and print a diagnostic naming the task and directing the human to the full track, e.g.[sdd-ship] T-NNN is Risk: critical or Security-Sensitive: true and is ineligible for the lite track (no cross-model step). Re-run on the full track: /sdd-ship:ship --full specs/<feature>/tasks.mdDo not admit such a task to the lite gate. Invoke/sdd-lite:lite-gate specs/<feature>/tasks.md#T-NNN. - PASS: task is Done.
- FAIL: stop, surface the report, and instruct the user to fix and re-run.
Field Definitions
These optional per-task fields live in a tasks.md task entry. They are additive; existing consumers ignore unknown fields.
Security-Sensitive:— optional per-task boolean trigger.truemarks the task as requiring cross-model verification regardless of itsRisk:tier (see Step 4). The task author proposes it; the human confirms it at approval. Absent orfalsemeans the field does not force cross-model verification (theRisk:tier still may).Cross-Model-Waiver:— optional per-task field recording an explicit decision to skip the cross-model verification a task would otherwise require. Who may set it: a human only. Its audit value is a short human-authored reason. It is honored only when the SAME task also carries a humanApproval: Approvedaudit mark naming a second distinct human approver — the human-only approval context that makes the waiver valid; without that context the waiver is ignored and cross-model verification remains required (fail-closed). Because an agent cannot produce the human approval mark, an agent-written waiver has no effect.- Lite-track rule for critical/security-sensitive tasks: a task with
Risk: criticalorSecurity-Sensitive: trueis INELIGIBLE for the lite track, because the lite track has no cross-model step. The lite gate rejects such a task with a diagnostic naming the task and directing the human to the full track (see Step 4, Lite track), rather than admitting it to a track that would silently drop the cross-model requirement.
Step 5 — Completion Check
After all targeted tasks reach Done:
- If
--retroflag was passed, or if all tasks in the feature (not just the targeted subset) have reached Done for the first time in this session: invoke/sdd-quality-loop:workflow-retrospective specs/<feature>. - Print a summary: number of tasks implemented, number Done, any remaining non-Done tasks (with their current Status).
State Machine Summary
IDLE
→ TARGET_SELECTED (path argument or zero-arg auto-select)
→ TRACK_DETECTED (print [sdd-ship] Track: ... message)
→ IMPLEMENTING (implement-tasks for full / implement-task loop for lite)
→ QUALITY_GATE_LOOP (quality-gate or lite-gate per task)
├── task Done → continue loop
├── task Blocked → STOP (surface review tickets)
└── ≥3 disk gate reports for task and not Done → STOP (Escalate-Human)
→ COMPLETION_CHECK (all targeted tasks Done?)
└── yes → [--retro or all-Done] RETROSPECTIVE → DONE
Context Compaction
Ship sessions span many tasks. All loop state is persisted on disk (tasks.md
Status fields, reports/quality-gate/, review tickets), and both the Resume
behaviour (Step 3) and the disk-based cycle limit (Step 4) are designed to
survive re-invocation — compaction at a task boundary loses nothing.
Compact (or accept auto-compaction) only at task boundaries:
- after a task reaches Done (quality gate PASS)
- after a BLOCKED stop, before starting fix-by-review-ticket
- between Step 3 and Step 4, when all targeted tasks are at Implementation Complete
Do not compact while a task is In Progress or a quality-gate cycle is
running: the implementing agent's working context (file paths, partial
changes, verification state) is not yet reflected on disk. After compacting,
re-invoke /sdd-ship:ship and rely on Resume behaviour to continue from the
first eligible task.
Security Boundaries
- Never invoke
sdd-sudoor create/modify theSDD_SUDOfile. - Never set
Approval: Approvedon any task. The approval guard will block this; attempting it causes confusing error messages. - Never modify gate scripts (
scripts/*.sh,scripts/*.ps1) or hook files. - Never push to remote, create pull requests, or merge branches unless the user explicitly requests it in this session.
- Never modify files under
plugins/sdd-quality-loop/hooks/orplugins/sdd-quality-loop/scripts/sdd-hook-guard.*. - Do not exceed the scope of the targeted tasks. Do not make changes to files unrelated to the approved tasks.
Handoff
After sdd-ship completes, report:
- Tasks implemented and their final status (Done / Blocked)
- Any review tickets created (with file paths)
- Next action for the user:
- If all Done: "Feature complete. Consider re-running /sdd-ship:ship --retro specs/<feature>/tasks.md to capture improvements."
- If Blocked: "Address review tickets, apply fixes with /sdd-quality-loop:fix-by-review-ticket, then re-run /sdd-ship:ship."
04 同仓库更多 Skills
status
Show a read-only Jira-style six-view SDD dashboard in the initiating parent's Sites or Claude Artifacts, with source freshness and failure visibility.
verify-review-reservation
Recheck the bounded identity-ledger reservation invariant after lock, hash-check or publication changes.
aws-cdk
Authors, deploys, and troubleshoots AWS infrastructure using CDK with TypeScript or Python. Covers best practices, stack architecture, and construct patterns. Applies when writing CDK constructs, bootstrapping environments, running cdk deploy/synth/diff, fixing CDK or CloudFormation errors, planning stack structure, importing existing resources, resolving drift, or refactoring stacks without resource replacement.
quality-gate
Independently verify an Implementation Complete task with a Default-FAIL verification contract, deterministic checks, and an isolated critical reviewer, then decide whether it is Done.
ship
Implement approved SDD tasks through the quality gate to Done — the second of the two-command workflow. Run after /sdd-bootstrap:bootstrap and human task approval.
ship
Implement approved SDD tasks through the quality gate to Done — the second of the two-command workflow. Run after /sdd-bootstrap:bootstrap and human task approval.