Using Shipyard
What is Shipyard?
Shipyard is a structured project execution framework for Claude Code. It works as a plugin that helps you:
- Plan work in phases — break large projects into manageable pieces with clear success criteria
- Build with parallel agents and TDD — fresh 200k-token context per task, atomic commits, test-driven development
- Review code quality and security automatically — two-stage code review, OWASP security audits, complexity analysis
- Ship with confidence — verification gates, documentation generation, and delivery workflows
Shipyard works as a Claude Code plugin. Install it once, then use slash commands in any project.
Getting Started
New to Shipyard? Follow these steps:
/shipyard:init— Set up your project preferences (interaction mode, git strategy, quality gates). Takes ~1 minute./shipyard:brainstorm— Explore what you want to build through interactive dialogue. Captures a project definition./shipyard:plan 1— Plan your first phase of work. Researches the codebase and decomposes into executable tasks./shipyard:build— Execute the plan with parallel builder agents, review gates, and security audits./shipyard:ship— Verify, audit, document, and deliver your completed work.
For quick one-off tasks, skip the lifecycle and use /shipyard:quick 'description'.
I Want To...
| Goal | Command |
|---|---|
| Set up a new project | /shipyard:init |
| Explore requirements | /shipyard:brainstorm |
| Understand existing code | /shipyard:map |
| Plan a phase | /shipyard:plan [phase] [--skip-research] |
| Build from a plan | /shipyard:build [phase] [--plan N] [--light] |
| Quick one-off task | /shipyard:quick "task" |
| Review my code | /shipyard:review |
| Security check | /shipyard:audit |
| Research technology options | /shipyard:research "topic" |
| Find duplication/complexity | /shipyard:simplify [scope] |
| Generate documentation | /shipyard:document [scope] |
| Run tests and verify | /shipyard:verify [criteria] |
| Check progress | /shipyard:status |
| Change settings | /shipyard:settings |
| Rollback to checkpoint | /shipyard:rollback |
| Recover from errors | /shipyard:recover |
| Ship completed work | /shipyard:ship [--phase | --milestone | --branch] |
How to Access Skills
In Claude Code: Use the Skill tool. When you invoke a skill, its content is loaded and presented to you — follow it directly. Never use the Read tool on skill files.
In other environments: Check your platform's documentation for how skills are loaded.
Available Skills
Shipyard provides 19 skills. Skills are behavioral disciplines — they define HOW to do work, not what to build.
| Skill | What It Actually Does |
|---|---|
shipyard:using-shipyard | Index of all skills/commands with triggers and activation rules (this skill) |
shipyard:shipyard-tdd | Enforces write-failing-test → watch-fail → implement → watch-pass → refactor cycle. Tests written after code prove nothing. |
shipyard:shipyard-debugging | 4-phase investigation (root cause → pattern analysis → hypothesis test → fix). After 3 failed fixes, stop and question architecture. |
shipyard:shipyard-verification | Blocks "done"/"fixed"/"passing" claims until you run the actual command fresh and read the output. Evidence before assertions. |
shipyard:shipyard-brainstorming | One-question-at-a-time Socratic dialogue to turn vague ideas into validated designs with trade-offs before any code is written. |
shipyard:security-audit | Checks OWASP Top 10, scans for hardcoded secrets, audits dependencies and IaC (Terraform/Ansible/Docker). Critical findings block merge. |
shipyard:code-simplification | Post-implementation review for duplication (3+ occurrences → extract), dead code, over-engineering, and AI bloat patterns. |
shipyard:infrastructure-validation | Tool-chain workflows for Terraform (fmt/validate/plan/lint), Ansible (lint/syntax/dry-run), Docker (hadolint/build/trivy). |
shipyard:parallel-dispatch | Routes 2+ independent tasks to concurrent agents with isolated scope/constraints. Prevents sequential bottleneck. |
shipyard:shipyard-writing-plans | Converts specs into executable tasks with exact file paths, code samples, verification commands, and TDD steps for builder handoff. |
shipyard:shipyard-executing-plans | Runs fresh builder agent per task + two-stage review (spec compliance then code quality) + security audit + simplification gate. |
shipyard:git-workflow | Full branch lifecycle: create worktree → setup → baseline tests → work → verify → 4 completion options (merge/PR/keep/discard). |
shipyard:documentation | Generates code comments, API docs (params/returns/examples), architecture docs, and user guides. Verifies examples actually work. |
shipyard:shipyard-writing-skills | TDD for docs: run scenario WITHOUT skill (RED) → document agent rationalizations → write skill countering them (GREEN) → refine. |
shipyard:shipyard-testing | Enforces behavior-based testing via public APIs: AAA structure, DAMP not DRY, name tests after behavior, prefer state over mocks. |
shipyard:lessons-learned | After phase completion, captures what worked/surprised/failed into .shipyard/LESSONS.md and optionally feeds back to CLAUDE.md. |
shipyard:shipyard-handoff | Captures session context into .shipyard/HANDOFF.md so the next session can resume without losing progress. |
shipyard:import-spec | Imports a spec-kit feature directory into Shipyard, replacing brainstorming. Maps spec artifacts to PROJECT.md and ROADMAP.md. |
shipyard:import-spec-file | Imports a handwritten spec document into Shipyard, replacing brainstorming. Interviews to fill gaps via Socratic dialogue. |
Shipyard Commands
Commands are actions — they produce artifacts, change state, or trigger workflows.
Lifecycle Commands (run in order for full projects)
| Command | What It Actually Does |
|---|---|
/shipyard:init | Settings only. Asks ~9 preference questions (interaction mode, git strategy, review depth, quality gates, model routing) and writes .shipyard/config.json. No codebase analysis or planning. |
/shipyard:brainstorm | Socratic dialogue exploring goals/constraints → writes .shipyard/PROJECT.md. Optionally dispatches architect to generate ROADMAP.md with up to 3 revision cycles. |
/shipyard:plan [phase] [--skip-research] | Dispatches researcher → architect → verifier agents to create executable plan files (PLAN-W.P.md) with tasks, file paths, verification commands. Produces RESEARCH.md and context files. |
/shipyard:build [phase] [--plan N] [--light] | Dispatches builder agent per plan + two-stage review + optional security audit/simplification/docs. Handles retries (up to 2) on critical issues. Produces SUMMARY and REVIEW files per plan. |
/shipyard:ship [--phase | --milestone | --branch] | Pre-ship verification + tests + security audit + docs + lessons learned capture. Then presents 4 delivery options: merge locally, push PR, preserve branch, or discard. Archives artifacts. |
Session Management
| Command | What It Actually Does |
|---|---|
/shipyard:status | Reads state files and displays progress dashboard with blockers and next-action suggestion. No side effects. |
/shipyard:resume | Reconstructs context from STATE.json + HISTORY.md + artifacts to detect interrupted work and route to recovery. |
/shipyard:settings | Interactive menu to view/update .shipyard/config.json preferences. Supports list, view <key>, set <key> <value>. |
/shipyard:issues | Manages deferred issues in .shipyard/ISSUES.md with severity tracking. Supports --add, --resolve, --list. |
/shipyard:rollback | Reverts to a gi |