using-shipyard

<!-- TOKEN BUDGET: 220 lines / ~660 tokens -->

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:

1. /shipyard:init — Set up your project preferences (interaction mode, git strategy, quality gates). Takes ~1 minute.
2. /shipyard:brainstorm — Explore what you want to build through interactive dialogue. Captures a project definition.
3. /shipyard:plan 1 — Plan your first phase of work. Researches the codebase and decomposes into executable tasks.
4. /shipyard:build — Execute the plan with parallel builder agents, review gates, and security audits.
5. /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