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
3. 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

<!-- BEGIN Shipkit v*.*.* -->
...old shipkit content...
<!-- END Shipkit v*.*.* -->

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

4. Write merged CLAUDE.md with proper markers
5. 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:

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

4. Write valid JSON
5. 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:

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)

3. 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)

4. 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 queries
• Structured data is machine-readable
• Mixed formats work but JSON is preferred going forward

Output Format

Fresh install (no previous):

✓ Shipkit installed

Installed:
- 29 skills → .claude/skills/shipkit-*/
- 7 agents → .claude/agents/
- 5 hooks → .claude/hooks/
- Framework rules → .claude/rules/shipkit.md
- Settings created
- CLAUDE.md created (user-editable sections)
- HTML Overview → .shipkit/shipkit-overview.html

💡 Open .shipkit/shipkit-overview.html in your browser for a skill reference guide

Next: Run /shipkit-project-context to scan your codebase

Update (with merge):

✓ Shipkit updated v1.0.0 → v1.1.0

Archived to: .shipkit-archive/20240115-143000/
- Full backup preserved (see MANIFEST.md)

Installed fresh:
- 29 skills, 7 agents, 2 hooks

Merged intelligently:
- CLAUDE.md: Shipkit section updated, your preferences preserved
- settings.json: Shipkit entries updated, your custom permissions preserved

Migrated user content:
- why.json ✓
- architecture.json ✓
- stack.json ✓
- specs/active/ (3 .json files) ✓
- plans/active/ (2 .json files) ✓
- product-discovery.json ✓
- engineering-definition.json ✓
- ux-decisions.json ✓
- [... all other user files ...]

Not migrated (purely auto-generated):
- schema.json, env-requirements.md
  ℹ️  Run /shipkit-project-context to regenerate if needed

Deprecated .md files:
- architecture.md → archived (replaced by .json)
- progress.md → archived (replaced by .json)
- why.md → archived (replaced by .json)
- specs/active/user-auth.md → archived (replaced by .json)
- plans/active/user-auth.md → archived (replaced by .json)
- product-discovery.md ⚠ run /shipkit-product-discovery to convert
- ux-decisions.md ⚠ run /shipkit-ux-audit to convert

⚠ settings.local.json has stale refs (see above)

Ready to use. Review merged files, archive has originals.

Error Handling

Context Files This Skill Reads

Detection:

• .shipkit/** - Current context folder
• .shipkit-lite/** - Legacy context folder
• .claude/skills/shipkit-*/** - Current skills
• .claude/skills/lite-*/** - Legacy skills
• .claude/agents/*.md - Installed agents
• .claude/hooks/*.py - Installed hooks
• .claude/settings.json - Main settings
• .claude/settings.local.json - Local overrides (scan only)
• CLAUDE.md - Root instructions
• **/CLAUDE.md - Subfolder instructions

From npm (via npx):

• npx shipkit-dev update — Downloads and installs latest framework files

The npx CLI handles installing:

• Skills, agents, hooks, settings, rules, scripts, overview

Context Files This Skill Writes

Archive (creates):

• .shipkit-archive/{timestamp}/ - Full archive folder
• .shipkit-archive/{timestamp}/MANIFEST.md - What was archived
• .shipkit-archive/{timestamp}/context/ - Entire .shipkit/ contents
• .shipkit-archive/{timestamp}/deprecated-md/ - Deprecated .md files replaced by .json
• .shipkit-archive/{timestamp}/CLAUDE.md.backup - Original CLAUDE.md
• .shipkit-archive/{timestamp}/settings.json.backup - Original settings

Install (creates/overwrites):

• .shipkit/ - Context folder structure
• .shipkit/templates/ - Fresh templates
• .claude/skills/shipkit-*/ - All skills
• .claude/agents/shipkit-*.md - All agents
• .claude/hooks/shipkit-*.py - All hooks
• .claude/rules/shipkit.md - Framework rules (always replaced)

Merge (modifies):

• .claude/settings.json - Merged settings
• CLAUDE.md - Merged with markers
• **/CLAUDE.md - Any subfolder CLAUDE.md files

Does NOT modify:

• .claude/settings.local.json - User's local file (warn only)

GitHub Repository Structure Expected

{repo}/
├── installers/
│   └── install.py                       # Python installer (fetched and run)
├── install/
│   ├── VERSION                          # e.g., "1.3.0"
│   ├── profiles/
│   │   └── shipkit.manifest.json        # What to install
│   ├── skills/
│   │   └── shipkit-*/SKILL.md           # All skills
│   ├── agents/
│   │   └── shipkit-*.md                 # All agents
│   ├── shared/hooks/
│   │   └── shipkit-*.py                 # All hooks
│   ├── rules/
│   │   └── shipkit.md                   # Framework rules (replace on update)
│   ├── settings/
│   │   └── shipkit.settings.json        # Settings template
│   ├── templates/
│   │   └── *.md                         # Template files
│   └── claude-md/
│       └── shipkit.md                   # CLAUDE.md template (user-editable)
├── docs/
│   └── generated/
│       └── shipkit-overview.html        # Skill reference (browser viewable)

Configuration

Default repository (can be overridden):

SHIPKIT_REPO=https://github.com/stefan-stepzero/shipkit

Override via argument:

/shipkit-update repo:myorg/my-shipkit-fork

When This Skill Integrates with Others

After shipkit-update

Before shipkit-update

This skill is typically the first skill run — it bootstraps or updates the entire framework. No prerequisites.

Related Skills

• /shipkit-work-memory — Check session progress after update
• /shipkit-review-shipping — Verify the update completed correctly

After Completion

Post-update checklist:

1. Review merged files — Check CLAUDE.md and settings.json look correct
2. Check archive — Originals in .shipkit-archive/{timestamp}/ if needed
3. Activate skills — Run /reload-skills to activate newly installed skills in this session without restarting (CC 2.1.152+).
4. Test a skill — Try /shipkit-work-memory to verify installation works
5. Optional refresh — Run /shipkit-project-context if you want fresh stack detection

If something looks wrong:

• Archive has all original files
• Restore specific files manually if needed
• Report issues for future improvements

Success Criteria

• Permissions requested upfront (single approval, no interruptions)
• Detects all Shipkit variants (current + legacy naming)
• Archives completely before any modifications
• MANIFEST.md accurately records what was archived with versions
• npx installer executed successfully (or Python fallback)
• Framework files installed fresh match VERSION
• CLAUDE.md merged intelligently (user content preserved)
• settings.json merged intelligently (user permissions preserved)
• settings.local.json untouched (warning if stale)
• User context files migrated (including stack.json)
• Deprecated .md files detected and reported
• .md files with .json equivalents archived and removed
• .md files pending conversion listed with skill to run
• No data loss possible (archive has everything)

Security Notes

• Only fetches from specified GitHub repository
• Runs npx CLI from npm registry (user approved in Step 0)
• CLI only copies files — no network calls, no data exfiltration
• Archives are local, never uploaded
• settings.local.json never modified (privacy)

Key Principle

Archive first, merge with judgment, user reviews result.

Claude uses intelligence to merge, not rigid find-replace rules. The archive is the safety net — if the merge isn't perfect, the original is always available.