sdd-ship
Skill256 starsChanged 2 months agoMITView on GitHub
Archive a completed feature and close the SDD cycle (Phase 4): verify the build is truly complete, archive every phase artifact, capture lessons learned, update all phase documents to Shipped, and clean the working folders. Carries the full ship methodology — verification order, ship readiness matrix, the concrete archive procedure, status transitions, lessons-learned categories, quality gate, and the end-of-cycle handoff. Executed by ship-agent and the /ship command; loadable directly when closing a feature by hand. Use when completed work needs closing: "ship the feature", "archive the completed feature", "Phase 4", "lessons learned", "finalize the feature". Not for implementation work — writing code, completing tasks, or fixing failing tests is Phase 3; use sdd-build. Shipping starts only after the build report shows 100% completion.
In this repository20 other files it gives its agents.
- CLAUDE.mdCLAUDE.md
- agent-routerSkill
- component-modelSkill
- create-agentSkill
- create-skillSkill
- excalidraw-diagramSkill
- github-cr-adrSkill
- github-cr-issueSkill
- github-post-issueSkill
- github-review-prSkill
- kb-buildSkill
- meeting-analysisSkill
- sdd-brainstormSkill
- sdd-buildSkill
- sdd-defineSkill
- sdd-designSkill
- sdd-iterateSkill
- sdd-workflowSkill
- standup-reportSkill
- visual-explainerSkill
The file
We split this skill into the rules it gives an agent
5 rules. About 0 are common, 5 are distinctive, and 0 are very specific to this project.
≈0
Common · estimate
Many files like this have a rule of this kind.
≈5
Distinctive · estimate
This author's own choices. Worth a look.
0
Very specific
Tied to their project's names, files or tools. Probably skip.
- Common
- Distinctive
- Very specific
- Distinctive: line 86
Run the verification order above.
- Distinctive: line 102
If Phase 0 was used, also archive the brainstorm:
- Distinctive: line 156
If a BRAINSTORM was archived in Step 3, remove its working copy too:
- Distinctive: line 200
Before saving the SHIPPED document:
- Distinctive: line 221
When the archive is complete, report closure to the user:
≈ “Common” is an estimate: at least 1 in 5 of the 364,980 skill files we read have a rule of the same kind, not the same words. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.
Files
SDD Ship — feature archival and lessons learned (Phase 4)
Ship closes the 5-phase SDD workflow: it turns a completed feature's working documents into a permanent archive with lessons learned, marks every phase document Shipped, and leaves the working folders clean for the next feature. Nothing ships unless the build is verifiably complete.
Contract
| Aspect | Value |
| Input (required) | .claude/sdd/features/DEFINE_{FEATURE}.md · .claude/sdd/features/DESIGN_{FEATURE}.md · .claude/sdd/reports/BUILD_REPORT_{FEATURE}.md |
| Input (optional) | .claude/sdd/features/BRAINSTORM_{FEATURE}.md (if Phase 0 was used) |
| Output | .claude/sdd/archive/{FEATURE}/ containing all artifacts + SHIPPED_{DATE}.md |
| Template | .claude/sdd/templates/SHIPPED_TEMPLATE.md — the SHIPPED document's required shape; follow it, never improvise the format |
| Contract source | .claude/sdd/architecture/WORKFLOW_CONTRACTS.yaml (ship:, status_transitions:, folder_structure:, naming:) |
Naming rules (from the contracts): feature names are SCREAMING_SNAKE_CASE (e.g., USER_NOTIFICATIONS); the archive folder is .claude/sdd/archive/{FEATURE_NAME}/; the shipped file is SHIPPED_{YYYY-MM-DD}.md, dated with the ship date.
Verification order
Resolve completeness in this order before anything is archived:
┌─────────────────────────────────────────────────────────────────────┐
│ 1. ARTIFACT VERIFICATION (confirm completeness) │
│ └─ Read: .claude/sdd/features/DEFINE_{FEATURE}.md │
│ └─ Read: .claude/sdd/features/DESIGN_{FEATURE}.md │
│ └─ Read: .claude/sdd/reports/BUILD_REPORT_{FEATURE}.md │
│ └─ Optional: .claude/sdd/features/BRAINSTORM_{FEATURE}.md │
│ │
│ 2. BUILD REPORT VALIDATION │
│ └─ All tasks completed? │
│ └─ All tests passing? │
│ └─ No blocking issues? │
│ │
│ 3. CONFIDENCE ASSIGNMENT │
│ ├─ All artifacts present + tests pass → 0.95 → Ship │
│ ├─ Artifacts present + minor issues → 0.80 → Ask user │
│ └─ Missing artifacts or failures → 0.50 → Cannot ship │
└─────────────────────────────────────────────────────────────────────┘Ship Readiness Matrix
| Artifacts | Tests | Issues | Confidence | Action |
| All present | Pass | None | 0.95 | Ship immediately |
| All present | Pass | Minor | 0.85 | Ship with notes |
| All present | Fail | Any | 0.50 | Cannot ship |
| Missing | Any | Any | 0.30 | Cannot ship |
When NOT to ship
Any of these blocks the ship — stop and route back to /build:
- BUILD_REPORT shows incomplete tasks
- Tests are failing
- Blocking issues documented in the build report
- Missing required artifacts (DEFINE, DESIGN, BUILD_REPORT)
Ship only when all acceptance tests from DEFINE pass, the build report shows 100% completion, and no blocking issues remain.
Process
Step 1 — Verify completion
Read(.claude/sdd/features/DEFINE_{FEATURE}.md)
Read(.claude/sdd/features/DESIGN_{FEATURE}.md)
Read(.claude/sdd/reports/BUILD_REPORT_{FEATURE}.md)
# Verify build report shows successRun the verification order above. Confidence below 0.85 → do not proceed.
Step 2 — Create archive folder
mkdir -p .claude/sdd/archive/{FEATURE_NAME}/Step 3 — Copy artifacts to archive
cp .claude/sdd/features/DEFINE_{FEATURE}.md .claude/sdd/archive/{FEATURE}/
cp .claude/sdd/features/DESIGN_{FEATURE}.md .claude/sdd/archive/{FEATURE}/
cp .claude/sdd/reports/BUILD_REPORT_{FEATURE}.md .claude/sdd/archive/{FEATURE}/If Phase 0 was used, also archive the brainstorm:
cp .claude/sdd/features/BRAINSTORM_{FEATURE}.md .claude/sdd/archive/{FEATURE}/Resulting archive structure:
.claude/sdd/archive/{FEATURE}/
├── BRAINSTORM_{FEATURE}.md (if exists)
├── DEFINE_{FEATURE}.md
├── DESIGN_{FEATURE}.md
├── BUILD_REPORT_{FEATURE}.md
└── SHIPPED_{DATE}.mdStep 4 — Generate SHIPPED document
Compose the SHIPPED document following .claude/sdd/templates/SHIPPED_TEMPLATE.md — the template owns the format; do not improvise sections. It covers the summary, timeline, metrics, what was built, success-criteria verification against DEFINE, lessons learned, recommendations, and the archived-artifact list.
Step 5 — Update document statuses
Per WORKFLOW_CONTRACTS.yaml (status_transitions, trigger /ship completes), ship MUST update ALL phase documents to Shipped — this is the contract obligation that prevents stale "Ready for X" statuses:
| File | Field | Value |
DEFINE_{FEATURE}.md | Status | ✅ Shipped |
DESIGN_{FEATURE}.md | Status | ✅ Shipped |
BUILD_REPORT_{FEATURE}.md | Status | ✅ Shipped |
Apply the updates to the archived copies (the working copies are removed in Step 6) and add a revision-history note to each:
Edit: archive/{FEATURE}/DEFINE_{FEATURE}.md
- Status: → "✅ Shipped"
- Add revision: "Shipped and archived"
Edit: archive/{FEATURE}/DESIGN_{FEATURE}.md
- Status: → "✅ Shipped"
- Add revision: "Shipped and archived"
Edit: archive/{FEATURE}/BUILD_REPORT_{FEATURE}.md
- Status: → "✅ Shipped"Step 6 — Clean up working files
rm .claude/sdd/features/DEFINE_{FEATURE}.md
rm .claude/sdd/features/DESIGN_{FEATURE}.md
rm .claude/sdd/reports/BUILD_REPORT_{FEATURE}.mdIf a BRAINSTORM was archived in Step 3, remove its working copy too:
rm .claude/sdd/features/BRAINSTORM_{FEATURE}.mdStep 7 — Save SHIPPED document
Write(.claude/sdd/archive/{FEATURE}/SHIPPED_{DATE}.md)Lessons learned
Review all artifacts for insights and capture at least 2 specific lessons in these categories:
| Category | Example |
| Process | "Breaking into 4 independent functions enabled parallel development" |
| Technical | "Using config.yaml instead of env vars improved testability" |
| Communication | "Clarifying v1/v2 scope early prevented feature creep" |
| Tools | "Using X library simplified Y" |
Rules for good lessons:
- Don't skip this — lessons learned prevent future mistakes.
- Be honest — document what didn't work too.
- Be specific and actionable — "Better planning" → "Create architecture diagram before coding".
- Archive everything — future you will thank present you.
Avoid vague lessons:
❌ "Better planning" (too vague)
❌ "More testing" (not specific)
❌ "Improved communication" (not actionable)Quality Gate
Before saving the SHIPPED document:
PRE-FLIGHT CHECK
├─ [ ] All artifacts verified present (DEFINE, DESIGN, BUILD_REPORT)
├─ [ ] BUILD_REPORT shows all tasks complete
├─ [ ] All tests passing
├─ [ ] Acceptance tests from DEFINE verified
├─ [ ] No blocking issues in the build report
├─ [ ] Code deployed (if applicable)
├─ [ ] Archive directory created
├─ [ ] All artifacts copied to archive
├─ [ ] ALL archived documents' status updated to "✅ Shipped"
├─ [ ] At least 2 specific lessons documented
└─ [ ] Working files cleaned up from features/ and reports/Close the cycle — end-of-cycle handoff
When the archive is complete, report closure to the user:
| Handoff item | Content |
| Archive location | .claude/sdd/archive/{FEATURE}/ with the full artifact list |
| SHIPPED document | Path to SHIPPED_{DATE}.md + one-line summary of what shipped |
| Lessons headline | The 2-3 most actionable lessons captured |
| Statuses | Confirmation that DEFINE, DESIGN, and BUILD_REPORT now read "✅ Shipped" |
| Workspace | features/ and reports/ clean of this feature's working files |
| Next step | Start the next feature with /define (or /brainstorm for an unshaped idea) |
Anti-Patterns
| Never Do | Why | Instead |
| Ship with failing tests | Broken code archived | Fix tests first — route back to /build |
| Ship incomplete builds | Missing functionality | Complete build first |
| Vague lessons learned | Not actionable | Be specific and concrete |
| Skip artifact verification | May be incomplete | Always verify all exist |
| Leave working files | Clutter | Clean up after archive |
| Re-inline the SHIPPED format | Drifts from the template | Follow SHIPPED_TEMPLATE.md |
References
- Template:
.claude/sdd/templates/SHIPPED_TEMPLATE.md - Contracts:
.claude/sdd/architecture/WORKFLOW_CONTRACTS.yaml - Executor:
.claude/agents/workflow/ship-agent.md - Entrypoint:
.claude/commands/workflow/ship.md - Previous phase:
.claude/commands/workflow/build.md
Does it work?
Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.
No reviews yet
People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.
- It worked
- Partly
- It didn't
Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.
Your trail
Files you open will collect here, so you can find them again.
Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.
Now do this for your own.
Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.

