agentleFS
luanmorenommacielluanmorenommaciel/agentspec/.claude/skills/sdd-ship/SKILL.md

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.

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
  1. Distinctive:

    Run the verification order above.

    line 86
  2. Distinctive:

    If Phase 0 was used, also archive the brainstorm:

    line 102
  3. Distinctive:

    If a BRAINSTORM was archived in Step 3, remove its working copy too:

    line 156
  4. Distinctive:

    Before saving the SHIPPED document:

    line 200
  5. Distinctive:

    When the archive is complete, report closure to the user:

    line 221

≈ “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.

Keep what fits and drop the rest. Your version, ready for your agents.
Files
SKILL.md

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

AspectValue
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

ArtifactsTestsIssuesConfidenceAction
All presentPassNone0.95Ship immediately
All presentPassMinor0.85Ship with notes
All presentFailAny0.50Cannot ship
MissingAnyAny0.30Cannot 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 success

Run 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}.md

Step 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:

FileFieldValue
DEFINE_{FEATURE}.mdStatus✅ Shipped
DESIGN_{FEATURE}.mdStatus✅ Shipped
BUILD_REPORT_{FEATURE}.mdStatus✅ 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}.md

If a BRAINSTORM was archived in Step 3, remove its working copy too:

rm .claude/sdd/features/BRAINSTORM_{FEATURE}.md

Step 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:

CategoryExample
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:

  1. Don't skip this — lessons learned prevent future mistakes.
  2. Be honest — document what didn't work too.
  3. Be specific and actionable — "Better planning" → "Create architecture diagram before coding".
  4. 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 itemContent
Archive location.claude/sdd/archive/{FEATURE}/ with the full artifact list
SHIPPED documentPath to SHIPPED_{DATE}.md + one-line summary of what shipped
Lessons headlineThe 2-3 most actionable lessons captured
StatusesConfirmation that DEFINE, DESIGN, and BUILD_REPORT now read "✅ Shipped"
Workspacefeatures/ and reports/ clean of this feature's working files
Next stepStart the next feature with /define (or /brainstorm for an unshaped idea)

Anti-Patterns

Never DoWhyInstead
Ship with failing testsBroken code archivedFix tests first — route back to /build
Ship incomplete buildsMissing functionalityComplete build first
Vague lessons learnedNot actionableBe specific and concrete
Skip artifact verificationMay be incompleteAlways verify all exist
Leave working filesClutterClean up after archive
Re-inline the SHIPPED formatDrifts from the templateFollow 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

Download now (ZIP)

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
What did you use it for? e.g. Reviewing pull requests in a Rails app

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.