Shipkit Update

shipkit-update - Install & Update Shipkit

Purpose: One skill to install Shipkit fresh or update an existing installation. Archives previous versions safely and intelligently merges user content.

Role: Bootstrap/update skill. Can be fetched directly from GitHub even before Shipkit is installed.

---

Why This Skill Exists

Updates are tricky without version tracking and safe migration.

This skill provides:

1. Detection - Finds all Shipkit variants (current + legacy naming)
2. Safe archiving - Never deletes, always preserves
3. Clean install - Fresh framework files from source
4. Intelligent merge - Claude merges user content into new structure

---

When to Invoke

User-invoked:

• "Install Shipkit" / "Update Shipkit" / "Upgrade Shipkit"
• /shipkit-update (explicit)
• "Reinstall Shipkit from GitHub"

Bootstrap scenario:

• User pastes GitHub link + "install this"
• Claude fetches this skill directly and executes

---

Prerequisites

For installation:

• Access to GitHub (WebFetch or gh CLI)
• Write access to project root

For update:

• Existing Shipkit installation (any version)

---

Process

Completion Tracking (MANDATORY)

After getting user permission (Step 0), create tasks for every remaining step:

1. TaskCreate: "Detect existing installation"
2. TaskCreate: "Archive existing installation + write MANIFEST.md"
3. TaskCreate: "Run npx installer"
4. TaskCreate: "Merge CLAUDE.md (+ subfolder CLAUDE.md files)"
5. TaskCreate: "Merge settings.json"
6. TaskCreate: "Scan settings.local.json for stale refs"
7. TaskCreate: "Migrate user content from archive"
8. TaskCreate: "Cleanup deprecated .md files"
9. TaskCreate: "Output comprehensive summary"

Rules:

• TaskUpdate each task to completed only after the step is fully done
• The installer completing (Step 3) is NOT the finish line — 5 more steps remain
• Do NOT present the final summary until ALL tasks show completed
• The CLAUDE.md merge task includes subfolder CLAUDE.md files, not just root

Step 0: Request Permissions Upfront

Get user approval once at the start, then run without interruptions.

Present to user:

To update Shipkit, I need permission to:

1. **Run npx installer** — Download and install latest Shipkit from npm
2. **Modify files** — Update .claude/, .shipkit/, and CLAUDE.md

This will:
- Archive your current installation (nothing deleted)
- Install fresh framework files
- Preserve your specs, plans, progress, and other user content

Proceed? [y/n]

If approved: Continue without further permission prompts. If declined: Stop and explain what manual steps user can take.

---

Step 1: Detect Existing Installation

Scan for ALL Shipkit variants:

Detection targets:
├── .shipkit/                    # Current context folder
├── .shipkit-lite/               # Legacy context folder
├── .claude/
│   ├── skills/shipkit-*/        # Current skills
│   ├── skills/lite-*/           # Legacy skills
│   ├── agents/shipkit-*.md      # Current agents
│   ├── agents/lite-*.md         # Legacy agents
│   ├── hooks/shipkit-*.py       # Current hooks
│   ├── hooks/lite-*.py          # Legacy hooks
│   ├── rules/shipkit.md         # Framework rules (replace on update)
│   ├── settings.json            # Main settings (check _shipkit key)
│   └── settings.local.json      # Local overrides (check for stale refs)
├── CLAUDE.md                    # Root (user-editable, merge carefully)
└── **/CLAUDE.md                 # Subfolders (check for Shipkit sections)

Version detection:

• Grep for Shipkit v pattern in all found files
• Check _shipkit key in JSON files
• Look for legacy markers: Shipkit-Lite, lite-, BEGIN Shipkit-Lite
• Record highest version found

Output:

Detected Shipkit installation:
- Version: v1.0.0 (from 12 files)
- Context folder: .shipkit/
- Skills: 15 found (shipkit-* prefix)
- Agents: 6 found
- CLAUDE.md: Has Shipkit section (with markers / without markers)
- settings.json: Has _shipkit key
- settings.local.json: Found (has stale lite-* refs / clean)
- User content: why.md, architecture.json, 3 specs

---

Step 2: Archive Existing Installation

Always archive before any changes.

Create archive folder:

.shipkit-archive/
└── {YYYYMMDD-HHMMSS}/
    ├── context/                     # From .shipkit/ or .shipkit-lite/
    │   └── [entire .shipkit/ contents]
    ├── skills/                      # All shipkit-* and lite-* skills
    ├── agents/                      # All shipkit-* and lite-* agents
    ├── hooks/                       # All shipkit-* and lite-* hooks
    ├── CLAUDE.md.backup             # Full backup of root CLAUDE.md
    ├── settings.json.backup         # Full backup of settings
    └── MANIFEST.md                  # What was archived + versions

MANIFEST.md format:

# Shipkit Archive Manifest
Archived: 2024-01-15 14:30:00
Previous version: v1.0.0
Upgrading to: v1.1.0

## Archived Framework Files
- 15 skills (shipkit-* prefix)
- 7 agents
- 2 hooks
- settings.json entries

## Archived Context (entire .shipkit/ folder)
All files preserved in context/ subfolder.

## Other Backups
- CLAUDE.md (full backup)
- settings.json (full backup)

## Version Map
| File | Version |
|------|---------|
| shipkit-orchestrate/SKILL.md | v1.0.0 |
| shipkit-spec/SKILL.md | v1.0.0 |
| settings.json (_shipkit) | v1.0.0 |
| CLAUDE.md | v1.0.0 (or "no markers") |
...

## Notes
- settings.local.json was NOT archived (user's local file)
- Original files preserved here if merge needs review

---

Step 3: Run npx Installer

Run the npx CLI to install/update framework files:

npx github:stefan-stepzero/shipkit update -y --claude-md skip

> When the npm package is published, this becomes: npx shipkit-dev update -y --claude-md skip

• -y for non-interactive (we already got permission in Step 0)
• --claude-md skip (Claude will do intelligent merge in Step 4)

What the installer handles:

1. Downloads latest from GitHub (or npm once published)
2. Installs:

• Skills → .claude/skills/shipkit-*/
• Agents → .claude/agents/
• Hooks → .claude/hooks/
• Settings → .claude/settings.json (merges — preserves custom permissions)
• Rules → .claude/rules/shipkit.md
• Scripts → .shipkit/scripts/
• HTML Overview → .shipkit/shipkit-overview.html

1. Updates VERSION in .shipkit/

Fallback (if npx unavailable):

curl -sL https://raw.githubusercontent.com/stefan-stepzero/shipkit/main/installers/install.py -o /tmp/shipkit-install.py
python /tmp/shipkit-install.py --from-github -y --claude-md skip
rm /tmp/shipkit-install.py

Why use the npx CLI:

• Single source of truth for "what to install"
• Zero dependencies, handles file copying and settings merge
• Tested and maintained separately
• Claude focuses on intelligence (detection, archiving, merging user content)

---

Step 4: Intelligent Merge (CLAUDE.md)

This is where Claude uses judgment, not rigid rules.

Scenario A: Fresh install (no existing CLAUDE.md)

→ Create CLAUDE.md with full Shipkit template (with BEGIN/END markers)

Scenario B: Existing CLAUDE.md WITH markers

...old shipkit content...

→ Replace content between markers with new template → Update version in markers → Preserve everything outside markers

Scenario C: Existing CLAUDE.md WITHOUT markers (legacy or manual)

Claude analyzes and merges intelligently:

1. Read new Shipkit template (canonical structure)
2. Read old CLAUDE.md content
3. For each piece of old content, determine:

• Is it old Shipkit instruction? → Drop (replaced by new)
• Is it user preference? → Add to "Working Preferences" section
• Is it project-specific knowledge? → Add to "Project Learnings" section
• Is it unrelated to Shipkit? → Preserve below END marker

Judgment calls Claude makes:

| Old Content | Action | |-------------|--------| | "Always use TypeScript strict mode" | → Working Preferences | | "This project uses Prisma for ORM" | → Project Learnings | | "Run /lite-spec for specifications" | → Drop (old command) | | "Check .shipkit-lite/ for context" | → Drop (old path) | | "Never commit .env files" | → Project Learnings | | Company coding standards section | → Preserve below END marker | | Old Shipkit skill reference tables | → Drop (replaced) |

1. Write merged CLAUDE.md with proper markers
2. Archive has original if user wants to review

For subfolder CLAUDE.md files:

• Same logic applies
• Check each **/CLAUDE.md found during detection
• Merge each one individually

---

Step 5: Intelligent Merge (settings.json)

Same principle: Claude merges with judgment.

1. Read new Shipkit settings template
2. Read old .claude/settings.json
3. Merge intelligently:

| Section | Action | |---------|--------| | _shipkit | → Update to new version | | permissions.allow with Skill(shipkit-*) | → Replace with new skill list | | permissions.allow with Skill(lite-*) | → Remove (legacy) | | permissions.allow (other entries) | → Preserve (user's custom permissions) | | permissions.deny | → Merge (keep user's, add Shipkit's) | | hooks (entire section) | → Replace with new template's hooks | | skills, workspace sections | → Replace with new | | Any other keys | → Preserve (user's additions) |

Hooks merge detail: Replace the entire hooks section with the new template. This ensures new hook types are added when they didn't exist in the old settings. All Shipkit hook types must be present:

• SessionStart — context loader (session initialization)
• PostToolUse — skill usage tracking
• TaskCompleted — team quality gate
• TeammateIdle — team quality gate

1. Write valid JSON
2. Archive has original backup

Example preservation:

// Old settings.json had:
"permissions": {
  "allow": [
    "Skill(shipkit-spec)",        // ← Replace (Shipkit)
    "Skill(lite-plan)",           // ← Remove (legacy)
    "WebFetch(domain:myapi.com)", // ← PRESERVE (user)
    "Bash(terraform:*)"           // ← PRESERVE (user)
  ]
}

// New merged settings.json:
"permissions": {
  "allow": [
    "Skill(shipkit-spec)",        // New Shipkit
    "Skill(shipkit-plan)",        // New Shipkit (renamed)
    ...all new shipkit skills...
    "WebFetch(domain:myapi.com)", // Preserved
    "Bash(terraform:*)"           // Preserved
  ]
}

---

Step 6: Handle settings.local.json

Do NOT modify this file. It's the user's local overrides.

But warn if stale patterns detected:

Scan for:

• lite-* references
• Old Shipkit version markers
• Paths to .shipkit-lite/

If found, output warning:

⚠ settings.local.json contains outdated references:
  - "Skill(lite-spec)" → should be "Skill(shipkit-spec)"
  - Path ".shipkit-lite/" → should be ".shipkit/"

This file was NOT modified (it's your local config).
Consider updating these references manually.

---

Step 7: Migrate User Content

Principle: Migrate everything EXCEPT known framework/transient files.

This approach is future-proof — new user content files automatically migrate without needing to update this list.

DON'T migrate (framework - install fresh):

├── templates/          # Framework templates from install
└── queues/             # Transient task queues, start empty

DON'T migrate (purely auto-generated):

├── schema.json         # Auto-generated from migrations
└── env-requirements.md # Auto-generated from .env files

MIGRATE: Everything else in .shipkit/

This includes (but is not limited to):

• why.json - Vision document (deprecated: why.md)
• architecture.json - Architecture decisions
• stack.json - Tech stack (may have manual annotations)
• specs/** - Feature specifications (active and implemented, .json preferred)
• plans/** - Implementation plans (.json preferred)
• progress.json - Session history
• archives/** - Progress archives
• codebase-index.json - Navigation index
• product-discovery.json - User personas and journeys
• engineering-definition.json - Technical approach and data contracts
• codebase-index.json - Component/route index (replaces deprecated implementations.json)
• user-tasks/** - User task lists
• preflight.json - Audit reports
• audits/** - Audit history
• ux-decisions.json - UX decision log (deprecated: ux-decisions.md)
• communications/** - Generated HTML reports
• status.json - Health snapshots
• Any other user-created files

Note on stack.json: While initially auto-generated, users often add manual notes and decisions. Migrating preserves this context. If user wants fresh detection, they can run /shipkit-project-context after update.

Migration process:

1. List all files in archived .shipkit/ context folder
2. Exclude: templates/, queues/, schema.json, env-requirements.md
3. Copy everything else to new .shipkit/
4. Report what was migrated
5. Note that schema.json/env-requirements.md can be regenerated if needed

---

Step 8: Cleanup Deprecated File Formats

Skills now output JSON instead of markdown for structured data.

After migration, scan for deprecated .md files that have been superseded by .json:

| Deprecated File | Replacement | Skill That Creates It | |-----------------|-------------|----------------------| | architecture.md | architecture.json | /shipkit-engineering-definition | | progress.md | progress.json | /shipkit-work-memory | | product-discovery.md | product-discovery.json | /shipkit-product-discovery | | contracts.md | — (folded into engineering-definition.json) | /shipkit-engineering-definition | | preflight.md | preflight.json | /shipkit-preflight | | scale-readiness.md | scale-readiness.json | /shipkit-scale-ready | | prompt-audit.md | prompt-audit.json | /shipkit-prompt-audit | | schema.md | schema.json | /shipkit-project-context | | implementations.md | — (removed, use codebase-index.json) | /shipkit-codebase-index | | specs/active/*.md | specs/active/*.json | /shipkit-spec | | plans/active/*.md | plans/active/*.json | /shipkit-plan | | why.md | why.json | /shipkit-why-project | | ux-decisions.md | ux-decisions.json | /shipkit-ux-audit |

Cleanup process:

1. Scan .shipkit/ for deprecated .md files from the table above
2. For root-level files (architecture.md, progress.md, why.md, etc.):

• Check if .json equivalent already exists
• If YES: Archive .md to .shipkit-archive/{timestamp}/deprecated-md/, remove from .shipkit/
• If NO: Keep .md (will be converted when user runs the skill)

1. For directory-based files (specs/active/, plans/active/):

• Scan each directory for .md files
• For each .md file, check if matching .json exists (same basename)
• If YES: Archive .md to .shipkit-archive/{timestamp}/deprecated-md/{subpath}/, remove from .shipkit/
• If NO: Keep .md (will be converted when user runs /shipkit-spec or /shipkit-plan)

1. Report findings:

Deprecated file formats detected:

Found .md files with .json replacements (archived):
  ✓ architecture.md → archived (architecture.json exists)
  ✓ progress.md → archived (progress.json exists)
  ✓ why.md → archived (why.json exists)
  ✓ specs/active/user-auth.md → archived (user-auth.json exists)
  ✓ plans/active/user-auth.md → archived (user-auth.json exists)

Found .md files pending conversion:
  ⚠ product-discovery.md — run /shipkit-product-discovery to convert
  ⚠ ux-decisions.md — run /shipkit-ux-audit to convert
  ⚠ specs/active/payment-flow.md — run /shipkit-spec to convert
  ⚠ plans/active/api-refactor.md — run /shipkit-plan to convert

These skills now output JSON for structured data.
Run each skill to convert, or keep .md files (they still work).

Why this matters:

• JSON files enable better tooling and cross-skill q

…

Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: stefan-stepzero
• Source: stefan-stepzero/shipkit
• License: MIT

Install and usage instructions live in the source repository linked above.