using-shipyard

What this skill does

<!-- 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 g