Ship software systematically — from idea to production with discipline, parallel agents, and zero context rot.
Shipyard is a Claude Code plugin that combines structured project lifecycle management with rigorous development practices. It replaces ad-hoc workflows with a systematic pipeline: brainstorm requirements, plan in phases, execute with fresh subagents, review with two-stage gates, audit for security, audit for simplification, and ship with confidence.
- Claude Code CLI installed and authenticated
jq(used by session hooks for state injection)
claude plugin marketplace add lgbarn/shipyard
claude plugin install shipyard@shipyardgit clone git@github.com:lgbarn/shipyard.git
claude plugin marketplace add /absolute/path/to/shipyard
claude plugin install shipyard@shipyardclaude /shipyard:statusOnce installed, navigate to any project directory and run:
# Initialize a new project
/shipyard:init
# Plan a phase
/shipyard:plan 1
# Build it
/shipyard:build
# Check progress
/shipyard:status
# Ship it
/shipyard:ship| Command | Purpose |
|---|---|
/shipyard:init |
Initialize project — gather requirements, analyze codebase, create roadmap |
/shipyard:plan [phase] [--skip-research] |
Decompose a phase into executable plans with atomic tasks |
/shipyard:build [phase] [--plan N] [--light] |
Execute plans with parallel builder agents and review gates |
/shipyard:status |
Show progress dashboard and route to next action |
/shipyard:resume |
Restore context from a previous session |
/shipyard:quick [task] |
Execute a small task with full guarantees |
/shipyard:ship [--phase | --milestone | --branch] |
Verify and deliver — merge, PR, or preserve |
/shipyard:issues [--add | --resolve | --list] |
View and manage deferred issues across sessions |
/shipyard:rollback [checkpoint] [--list] |
Revert to a previous checkpoint |
/shipyard:recover |
Diagnose and recover from interrupted state |
/shipyard:move-docs |
Move codebase analysis docs between .shipyard/codebase/ and docs/codebase/ |
/shipyard:worktree [create|list|switch|remove] [name] |
Manage git worktrees for isolated feature development |
/shipyard:memory-search <query> |
Search past conversations for relevant context |
/shipyard:memory-forget |
Delete current session from memory |
/shipyard:memory-status |
Show memory storage statistics |
/shipyard:memory-enable / memory-disable |
Toggle memory on or off |
/shipyard:memory-import |
Import existing conversation history |
Shipyard includes 17 skills that activate automatically based on context:
| Skill | When It Activates |
|---|---|
shipyard-tdd |
Writing any new code, features, or fixes |
shipyard-debugging |
Any error, test failure, or unexpected behavior |
shipyard-verification |
Before claiming any task is complete |
shipyard-brainstorming |
Creative work: features, components, design |
security-audit |
Working with code, configs, dependencies, or IaC |
code-simplification |
After implementation, before shipping, reviewing AI code |
documentation |
After implementation, before shipping, when docs are incomplete |
infrastructure-validation |
Working with Terraform, Ansible, Docker, or IaC files |
parallel-dispatch |
2+ independent tasks that can run concurrently |
shipyard-writing-plans |
Creating implementation plans |
shipyard-executing-plans |
Implementing from a written plan |
git-workflow |
Branch management, commits, delivery |
using-shipyard |
Every session (skill discovery protocol) |
shipyard-testing |
Writing effective, maintainable tests |
shipyard-writing-skills |
Creating new skills |
lessons-learned |
After phase completion, before shipping, reflecting on work |
memory |
When needing past context from previous sessions or solving problems you've encountered before |
Shipyard dispatches specialized agents for different phases of work:
| Agent | Role | Dispatched By |
|---|---|---|
| mapper | Brownfield codebase analysis (4 parallel instances) | /shipyard:init |
| researcher | Domain/technology research | /shipyard:plan |
| architect | Roadmap + plan decomposition | /shipyard:init, /shipyard:plan, /shipyard:quick |
| builder | Task execution with TDD, IaC validation, atomic commits | /shipyard:build, /shipyard:quick |
| reviewer | Two-stage code review (spec + quality) | /shipyard:build |
| auditor | Comprehensive security & compliance analysis | /shipyard:build, /shipyard:ship |
| simplifier | Cross-task duplication and complexity analysis | /shipyard:build |
| documenter | Documentation generation & updates | /shipyard:build, /shipyard:ship |
| verifier | Post-execution verification (including IaC) | /shipyard:plan, /shipyard:build, /shipyard:ship |
IDEA → /init (brainstorm + roadmap)
→ /plan (research + decompose)
→ /build (parallel execute + review)
→ /status (check progress)
→ repeat plan→build per phase
→ /ship (verify + deliver)
→ SHIPPED
Shipyard uses a dual state system:
- File state (
.shipyard/directory): Cross-session persistence for project vision, roadmap, plans, and progress. Survives session restarts and can be committed to git. - Native tasks (TaskCreate/TaskUpdate): In-session UI visibility showing real-time progress of phases and plans.
- Fresh context per task: Each builder agent runs in a clean 200k-token context, preventing quality degradation
- Two-stage review + security audit: Spec compliance and code quality per task, comprehensive security audit per phase
- Configurable gates: Security audit, simplification review, and IaC validation can be toggled in
config.jsonor skipped with--light - Code simplification: Post-phase analysis catches AI-generated duplication and bloat across tasks
- Documentation generation: Post-phase documentation keeps docs synchronized with code changes
- IaC support: Terraform, Ansible, Docker validation workflows built into the builder and verifier
- Max 3 tasks per plan: Keeps each agent's workload within the quality budget
- Atomic commits: Every task produces a separate, revertable commit
- Phase-based planning: Break large projects into manageable phases with clear success criteria
.shipyard/
├── PROJECT.md # Vision, decisions, constraints
├── ROADMAP.md # Phase structure with success criteria
├── STATE.md # Current position, session memory
├── config.json # Workflow preferences
├── codebase/ # Brownfield analysis (default; or docs/codebase/ if configured)
├── phases/
│ └── 01-{name}/
│ ├── RESEARCH.md
│ ├── 01-PLAN.md
│ ├── 01-SUMMARY.md
│ ├── VERIFICATION.md
│ ├── AUDIT-{N}.md # Security audit report
│ ├── SIMPLIFICATION-{N}.md # Code simplification report
│ └── DOCUMENTATION-{N}.md # Documentation generation report
└── quick/ # Ad-hoc tasks
shipyard/
├── .claude-plugin/
│ ├── marketplace.json # Marketplace metadata (version, category)
│ └── plugin.json # Plugin definition (name, description)
├── agents/ # Specialized subagent definitions
│ ├── architect.md # Roadmap and plan decomposition
│ ├── auditor.md # Security and compliance analysis
│ ├── builder.md # Task execution with TDD
│ ├── documenter.md # Documentation generation
│ ├── mapper.md # Brownfield codebase analysis
│ ├── researcher.md # Domain/technology research
│ ├── reviewer.md # Two-stage code review
│ ├── simplifier.md # Complexity and duplication analysis
│ └── verifier.md # Post-execution verification
├── commands/ # Slash command definitions
│ ├── init.md # /shipyard:init
│ ├── plan.md # /shipyard:plan
│ ├── build.md # /shipyard:build
│ ├── status.md # /shipyard:status
│ ├── resume.md # /shipyard:resume
│ ├── quick.md # /shipyard:quick
│ ├── ship.md # /shipyard:ship
│ ├── issues.md # /shipyard:issues
│ ├── move-docs.md # /shipyard:move-docs
│ ├── rollback.md # /shipyard:rollback
│ ├── recover.md # /shipyard:recover
│ └── worktree.md # /shipyard:worktree
├── docs/
│ └── PROTOCOLS.md # Model routing and config.json reference
├── hooks/
│ └── hooks.json # SessionStart hook for state injection
├── scripts/
│ ├── state-read.sh # Adaptive context loading on session start
│ ├── state-write.sh # Updates .shipyard/STATE.md
│ └── checkpoint.sh # Git tag checkpoint management
├── skills/ # Auto-activating skill definitions
│ ├── code-simplification/
│ ├── documentation/
│ ├── git-workflow/
│ ├── infrastructure-validation/
│ ├── lessons-learned/
│ ├── parallel-dispatch/
│ ├── security-audit/
│ ├── shipyard-brainstorming/
│ ├── shipyard-debugging/
│ ├── shipyard-executing-plans/
│ ├── shipyard-tdd/
│ ├── shipyard-testing/
│ ├── shipyard-verification/
│ ├── shipyard-writing-plans/
│ ├── shipyard-writing-skills/
│ └── using-shipyard/
├── test/ # bats-core test suite (dev only)
│ ├── run.sh # Test runner
│ ├── test_helper.bash # Shared fixtures
│ ├── state-read.bats
│ ├── state-write.bats
│ ├── checkpoint.bats
│ ├── integration.bats
│ └── e2e-smoke.bats
├── CHANGELOG.md
├── CONTRIBUTING.md
├── LICENSE
└── package.json
When you run /shipyard:init, Shipyard creates a .shipyard/config.json in your project with these options:
| Option | Values | Default | Description |
|---|---|---|---|
interaction_mode |
interactive, autonomous |
— | Approve each phase or execute full roadmap |
git_strategy |
per_task, per_phase, manual |
— | When to create git commits |
review_depth |
detailed, lightweight |
— | Review gate depth between build steps |
security_audit |
true, false |
true |
Run security audit after each phase |
simplification_review |
true, false |
true |
Check for duplication and complexity |
iac_validation |
auto, true, false |
auto |
Validate Terraform/Ansible/Docker changes |
documentation_generation |
true, false |
true |
Generate docs after each phase |
codebase_docs_path |
.shipyard/codebase, docs/codebase |
.shipyard/codebase |
Where brownfield analysis docs are stored |
model_routing |
object | see docs/PROTOCOLS.md |
Model selection per task type |
context_tier |
auto, minimal, full |
auto |
Context loading at session start |
See docs/PROTOCOLS.md for model routing configuration and the full config.json skeleton.
| Capability | Shipyard v2.2.0 | GSD v1.10.1 | Superpowers v3.6.2 |
|---|---|---|---|
| Project Lifecycle | |||
| Init / requirements gathering | ✅ | ✅ | ✅ |
| Phase-based roadmap | ✅ | ✅ | ❌ |
| Research agents | ✅ (researcher + 4 mappers) | ✅ (4 parallel) | ❌ |
| Discussion / decision capture | ❌ | ✅ | ❌ |
| Structured planning (waves) | ✅ | ✅ | ✅ |
| Max 3 tasks per plan | ✅ | ✅ | ❌ |
| Quick task mode | ✅ | ✅ | ❌ |
| Progress dashboard | ✅ | ✅ | ❌ |
| Ship / deliver command | ✅ | ✅ | ❌ |
| Execution | |||
| Fresh 200k context per agent | ✅ | ✅ | ✅ |
| Parallel wave execution | ✅ | ✅ | ✅ |
| TDD enforcement | ✅ (rigid skill) | ✅ (implicit) | ✅ (rigid skill) |
| Atomic commits per task | ✅ | ✅ | ✅ |
| IaC validation (Terraform, Ansible, Docker) | ✅ | ❌ | ❌ |
| Quality Gates | |||
| Two-stage code review | ✅ (spec + quality) | ✅ (single-stage) | ✅ (spec + quality) |
| Security audit (OWASP, secrets, deps) | ✅ (dedicated agent) | ❌ | ❌ |
| Code simplification | ✅ (skill + agent) | ❌ | 🧪 (lab, experimental) |
| Documentation generation | ✅ (dedicated agent) | ❌ | ❌ |
| Phase verification | ✅ | ✅ | ❌ |
| Configurable gate toggles | ✅ (--light, config.json) |
❌ | ❌ |
| Context & Models | |||
| Multi-model routing | ✅ (7 categories) | ✅ (profiles) | ❌ |
| Adaptive context loading | ✅ (4 tiers) | ✅ (5 tiers, fork) | ✅ (<2k bootstrap) |
| Session resume / state persistence | ✅ | ✅ | ❌ |
| Episodic memory | ✅ (built-in) | ❌ | ✅ (plugin) |
| Git & Recovery | |||
| Git worktree management | ✅ (command + agent context) | ❌ | ✅ (skill) |
| Rollback / checkpoints | ✅ | ✅ (fork) | ❌ |
| State recovery | ✅ | ✅ (fork) | ❌ |
| Issue tracking (cross-session) | ✅ | ✅ (todos) | ❌ |
| Skills & Extensibility | |||
| Auto-activating skills | ✅ (16 skills) | ❌ | ✅ (15+ skills) |
| Deterministic skill triggers | ✅ (4 trigger types) | ❌ | ❌ (description-based) |
| Systematic debugging | ✅ | ✅ | ✅ (4-phase + escalation) |
| Verification before completion | ✅ | ✅ | ✅ |
| Brainstorming / design | ✅ | ✅ (discuss phase) | ✅ |
| Skill authoring guide | ✅ | ❌ | ✅ |
| Plugin marketplace | ❌ | ❌ | ✅ (7 plugins) |
| Distribution | |||
| Install via CLI | ✅ (lgbarn/shipyard) |
✅ (npx get-shit-done-cc) |
✅ (marketplace) |
| Multi-runtime | ❌ (Claude Code) | ✅ (Claude + OpenCode + Gemini) | ❌ (Claude Code) |
| Scale | |||
| Commands | 17 | 20+ | 3 |
| Skills | 17 | 0 | 15+ |
| Named agents | 9 | implicit | implicit |
Shipyard draws inspiration from:
- Superpowers by Jesse Vincent — composable skills, TDD discipline, two-stage code review
- GSD (Get Shit Done) by TÂCHES — project lifecycle management, phase-based planning, context engineering
See CONTRIBUTING.md for how to add commands, skills, and agents, run tests, and submit pull requests.
MIT