<p align="center"> <img src="assets/shipyard_logo.png" alt="Shipyard Logo" width="400"> </p>

Shipyard

A Claude Code plugin for structured project execution. Plan work in phases, build with parallel agents and TDD, review with security audits and quality gates, and ship with confidence.

IDEA → /init → /brainstorm → /plan → /build → /ship → SHIPPED
         ↑
         ├── or: /import-spec (from spec-kit) → /plan → /build → /ship
         └── or: /import-spec-file (handwritten spec) → /plan → /build → /ship

Prerequisites

• Claude Code CLI installed and authenticated
• jq (used by session hooks for state injection)

Installation

From GitHub (recommended)

claude plugin marketplace add lgbarn/shipyard
claude plugin install shipyard@shipyard

From a local clone

git clone git@github.com:lgbarn/shipyard.git
claude plugin marketplace add /absolute/path/to/shipyard
claude plugin install shipyard@shipyard

Verify

claude /shipyard:status

Quick Start

Once installed, navigate to any project directory and run:

# Configure project preferences
/shipyard:init

# Explore requirements interactively
/shipyard:brainstorm

# Plan a phase
/shipyard:plan 1

# Build it
/shipyard:build

# Ship it
/shipyard:ship

For the full command reference and common workflows, see docs/QUICKSTART.md.

spec-kit Integration

Shipyard integrates with spec-kit (GitHub's Spec-Driven Development toolkit), letting you use spec-kit's structured specification workflow as a higher-quality alternative to /shipyard:brainstorm.

How It Works

spec-kit produces a rich set of artifacts in specs/[###-feature]/:

| spec-kit artifact | Mapped to | |---|---| | spec.md (user stories, acceptance criteria) | .shipyard/PROJECT.md | | .specify/constitution.md (project principles) | PROJECT.md constraints section | | plan.md (technical implementation plan) | Input for ROADMAP.md generation | | research.md + data-model.md + contracts/ | .shipyard/phases/1/RESEARCH.md | | tasks.md (flat task list with [P] markers) | .shipyard/phases/1/SPECKIT-TASKS.md — seeds the architect |

The /shipyard:plan command automatically detects these staged artifacts:

• Skips the researcher agent when RESEARCH.md already exists
• Seeds the architect with SPECKIT-TASKS.md to generate accurate wave/plan decomposition with less hallucination

Workflow

# 1. Use spec-kit to build the spec
/speckit.specify   My feature description
/speckit.plan      Tech stack choices
/speckit.tasks

# 2. Import into Shipyard (replaces /shipyard:brainstorm)
/shipyard:import-spec specs/001-my-feature

# 3. Continue with the normal Shipyard pipeline
/shipyard:plan 1   # researcher skipped, architect seeded from tasks.md
/shipyard:build 1
/shipyard:ship

/shipyard:import-spec also handles:

• Auto-discovery: if no argument is given, lists available specs/ directories
• [NEEDS CLARIFICATION] markers: surfaced as an Open Questions section in PROJECT.md rather than silently dropped
• Existing PROJECT.md: asks whether to replace or merge

Handwritten Spec Import

Don't have spec-kit? Use /shipyard:import-spec-file to import any existing specification document directly — architecture docs, requirements files, validation specs, RFC-style documents, or anything written by hand.

# Import a handwritten spec file
/shipyard:import-spec-file docs/my-feature-spec.md
/shipyard:import-spec-file /path/to/validation-spec.md

# Or let Shipyard auto-discover spec files in the project root
/shipyard:import-spec-file

The command reads the spec, maps its sections to PROJECT.md, then conducts a short interview to fill any gaps the spec doesn't cover (integration context, success criteria, non-goals). The spec itself is staged as RESEARCH.md so every downstream agent — architect, builder, reviewer — has full access to the original rules during planning and implementation.

/shipyard:import-spec-file handles:

• Any spec format: sections are mapped heuristically (Overview → Description, Rules/Requirements → Functional Requirements, Open Questions → Open Questions, etc.)
• Gap-filling interview: asks 2-5 focused questions about what the spec doesn't define
• Brownfield-aware routing: suggests /shipyard:map first if the project has existing source code without codebase docs
• Existing PROJECT.md: asks whether to replace or merge

Commands

| Command | Purpose | |---------|---------| | /shipyard:init | Configure project preferences and create .shipyard/ directory | | /shipyard:brainstorm | Explore requirements through interactive dialogue | | /shipyard:import-spec [feature-path] | Import a spec-kit feature spec, replacing brainstorming | | /shipyard:import-spec-file [file-path] | Import a handwritten spec file; interviews to fill gaps | | /shipyard:plan [phase] [--skip-research] | Plan a phase of work (creates roadmap if needed) | | /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:settings | View or update workflow settings | | /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:review [target] | On-demand code review — current changes, diff range, or files | | /shipyard:audit [scope] | On-demand security audit — OWASP, secrets, dependencies, IaC | | /shipyard:simplify [scope] | On-demand simplification — duplication, dead code, complexity | | /shipyard:document [scope] | On-demand documentation generation for changes or modules | | /shipyard:research <topic> | On-demand domain/technology research and comparison | | /shipyard:verify [criteria] | On-demand verification — run tests or check acceptance criteria | | /shipyard:map [focus] | On-demand codebase analysis — defaults to all 4 focus areas (technology, architecture, quality, concerns) | | /shipyard:help [topic] | Quick-reference table or detailed help for a specific command/skill | | /shipyard:doctor | Health-check diagnostic — jq, git, skills, hooks, .shipyard/ structure | | /shipyard:cancel | Graceful build interruption — checkpoint, pause, resume later | | /shipyard:debug [description] | Root-cause analysis with 5 Whys protocol via debugger agent |

Skills (Auto-Activating)

Shipyard includes 19 skills that Claude invokes automatically when trigger conditions match:

| 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 | | shipyard-handoff | Session transfer: "handoff", "I'm done for now", "save context" | | lessons-learned | After phase completion, before shipping, reflecting on work | | import-spec | Importing a spec-kit feature directory into Shipyard | | import-spec-file | Importing a handwritten spec document into Shipyard |

Agents

Shipyard dispatches 10 specialized agents for different phases of work:

| Agent | Role | Default Model | Dispatched By | |-------|------|---------------|---------------| | mapper | Brownfield codebase analysis (4 parallel instances) | sonnet | /shipyard:map | | researcher | Domain/technology research | sonnet | /shipyard:plan, /shipyard:research | | architect | Roadmap + plan decomposition | opus | /shipyard:brainstorm, /shipyard:plan, /shipyard:quick | | builder | Task execution with TDD, IaC validation, atomic commits | sonnet | /shipyard:build, /shipyard:quick | | reviewer | Two-stage code review (spec + quality) | sonnet | /shipyard:build, /shipyard:review | | auditor | Comprehensive security & compliance analysis | sonnet | /shipyard:build, /shipyard:ship, /shipyard:audit | | simplifier | Cross-task duplication and complexity analysis | sonnet | /shipyard:build, /shipyard:simplify | | documenter | Documentation generation & updates | sonnet | /shipyard:build, /shipyard:ship, /shipyard:document | | verifier | Post-execution verification (including IaC) | haiku | /shipyard:plan, /shipyard:build, /shipyard:ship, /shipyard:verify | | debugger | Root-cause