/using-shipyard

name: using-shipyard
description: Use when starting any conversation, when the user asks "what should I do", "help me", "how do I use shipyard", or "where do I start". Establishes how to find and use skills, requiring Skill tool invocation before ANY response including clarifying questions. Also use when unsure which skill or command applies to the current situation.

<!-- 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:impor