ShipKit

A structured development workflow system for Claude Code.

Context engineering, executable plans, agent orchestration, and documentation architecture — so Claude Code builds reliably instead of guessing.

npx ship-kit-ma

Works on Mac, Windows, and Linux. Installs to a namespaced directory — won't conflict with your existing commands.

Read the Full Guide — Comprehensive 1,700+ line documentation covering greenfield projects, brownfield onboarding, day-to-day workflows, and advanced agent orchestration.

What It Does

ShipKit gives Claude Code the context it needs to write correct code consistently. It installs 60 slash commands, 14 specialized agents, a three-tier documentation structure, and executable plan format that agents run directly.

The core insight: Plans are prompts, not documents. A spec with structured <task> blocks IS the instruction an agent executes — no interpretation needed.

Quick Start

Option 1: npx (recommended)

cd your-project
npx ship-kit-ma

Option 2: Clone and install

git clone https://github.com/moniav/ShipKit.git
cd your-project
python ../ShipKit/install.py

Option 3: Global install (all projects)

npx ship-kit-ma --global

Then in Claude Code:

/shipkit:workflow:bootstrap    # New project
/shipkit:doc:discover          # Existing project
/shipkit:workflow:resume       # Returning to work

Namespaced Commands

All ShipKit commands are namespaced under shipkit: to avoid conflicts:

/shipkit:workflow:*     # Project workflows
/shipkit:dev:*          # Development tasks
/shipkit:test:*         # Testing utilities
/shipkit:validate:*     # Validation & review
/shipkit:bug:*          # Bug management
/shipkit:doc:*          # Documentation
/shipkit:state:*        # State tracking
/shipkit:research:*     # Research tools
/shipkit:ui:*           # UI development
/shipkit:skill:*        # Custom skills
/shipkit:agent:*        # Agent orchestration
/shipkit:info:*         # Project info
/shipkit:system:*       # ShipKit management (update, etc.)

Your existing commands in .claude/commands/ remain untouched.

What Gets Installed

| Location | Contents | |----------|----------| | .claude/commands/shipkit/ | 60 namespaced commands | | .claude/agents/shipkit/ | 14 specialized agents | | .claude/settings.json | Permissions (merged, not overwritten) | | docs/ | 3-tier documentation templates | | .skills/ | Custom skill directory | | .git/hooks/ | Pre-commit and pre-push hooks |

Core Workflow

/shipkit:workflow:plan          → High-level plan
/shipkit:workflow:discuss       → Capture vision & intent
/shipkit:dev:spec               → Executable plan with <task> blocks
/shipkit:validate:plan          → Verify plan before building
/shipkit:dev:build              → Build with atomic commits per task
/shipkit:validate:accept        → Goal-backward verification + auto-fix

Key Concepts

• Plans as prompts — Specs contain <task> blocks agents execute directly
• Goal-backward verification — Checks goals achieved, not just tasks completed
• Atomic commits — Each task → immediate commit (git bisect, independent revert)
• Session continuity — /shipkit:workflow:pause + /shipkit:workflow:resume for seamless handoff
• Workflow modes — Interactive (confirm each step) or YOLO (auto-approve)
• 7-doc brownfield discovery — STACK, ARCHITECTURE, STRUCTURE, CONVENTIONS, TESTING, INTEGRATIONS, CONCERNS
• Three-tier docs — Context (auto-read), Reference (on-demand), Archive (searchable)
• Deferred issues — Track enhancements without scope creep

Configuration

Edit .claude/config.json:

{
  "workflow": {
    "mode": "interactive",
    "commit_style": "atomic",
    "context_budget_pct": 50,
    "auto_verify_plans": true
  }
}

Install Options

npx ship-kit-ma                  # Install to current directory
npx ship-kit-ma --global         # Install to ~/.claude/ (all projects)
npx ship-kit-ma --check          # Verify installation
npx ship-kit-ma --update         # Update ShipKit only
npx ship-kit-ma --uninstall      # Remove ShipKit (keeps your files)
npx ship-kit-ma --no-hooks       # Skip git hooks

Clean install behavior:

• Deletes and recreates commands/shipkit/ and agents/shipkit/
• Merges new permissions into settings.json (doesn't remove yours)
• Won't overwrite your existing templates or docs

Updating

Just run the installer again:

npx ship-kit-ma@latest

Or if you cloned the repo:

cd ShipKit && git pull
python install.py /path/to/your-project

Uninstalling

npx ship-kit-ma --uninstall

This only removes commands/shipkit/ and agents/shipkit/. Your code, docs, and other commands are preserved.

Full Documentation

See Claude-Code-Development-Workflow-Guide.md for comprehensive documentation:

| Section | Description | |---------|-------------| | Part I: Greenfield | Starting new projects from scratch | | Part II: Brownfield | Onboarding existing codebases | | Part III: Day-to-Day | Session management, feature cycles, bug fixes | | Part IV: Advanced | Agent orchestration, parallel workflows | | Quick Reference | Command cards, file budgets, update triggers |

Output Standards

All agents and commands follow standardized conventions defined in agents/shipkit/OUTPUT_STANDARDS.md:

• File naming conventions for specs, bugs, tests, components, and documentation
• Output notifications with [OK]/[WARN]/[ERROR] status indicators
• Absolute paths from project root for all file operations
• Index updates when new documents are created

Contributing

Contributions welcome! Please open an issue or PR at github.com/moniav/ShipKit.

License

MIT - See LICENSE for details.

GitHub Repository | Full Documentation