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

Using Shipyard with Codex

Shipyard also installs under Codex CLI (0.124.0+) on a best-effort, not-parity basis — all skills run natively; the multi-agent workflows degrade to inline sequential personas.

codex plugin marketplace add lgbarn/shipyard
# then enable the shipyard plugin in Codex

What you get and what degrades is documented in full in docs/using-shipyard-with-codex.md. In short: skills auto-activate identically; orchestration (build/audit/ship/review) runs sequentially in one context (no parallelism, no fresh-context review isolation); and state loads on demand instead of via a session hook.

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/memory/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 analysis with 5 Whys protocol	sonnet	/shipyard:debug

All agents have formal definition files in .claude/agents/ with tool restrictions and model defaults. See docs/AGENT-GUIDE.md for detailed documentation including model assignments, tool access, and composition patterns.

Agent Teams Support

Shipyard now supports Claude Code Agent Teams — an experimental feature where multiple independent Claude Code instances collaborate on the same project by sharing a task list and mailbox.

How It Works

Shipyard's standard execution model uses subagents (the Task tool) to dispatch builders, reviewers, and other agents. Each subagent runs within the lead agent's session, sharing its working directory but with a fresh context window. This is efficient for coordinated work where the lead needs to collect results and make decisions.

Agent Teams introduces a different model: independent Claude Code instances (teammates) that each have their own full session, context window, and tool access. They coordinate through a shared task list and mailbox rather than through a parent-child relationship.

Shipyard detects the teams environment automatically — no configuration needed: