shipyard

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