Using Shipyard

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...

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.

Shipyard Commands

Commands are actions — they produce artifacts, change state, or trigger workflows.

Lifecycle Commands (run in order for full projects)

Session Management

On-Demand Tools (use anytime, no lifecycle required)

Skill Activation Protocol

When a trigger condition matches, invoke the corresponding skill before responding.

File Pattern Triggers

Task Marker Triggers

State Condition Triggers

Content Pattern Triggers

Natural Language Triggers

The Core Rule

Invoke relevant skills BEFORE any response or action. If there is a reasonable chance a skill applies, invoke it to check. If an invoked skill turns out to be wrong for the situation, you don't need to use it.

Before every response, evaluate triggers in this order:

1. File patterns — check files being discussed, modified, or created
2. Task markers — check any loaded plans or task definitions
3. State conditions — check current workflow state and intent
4. Content patterns — check recent output and user messages

If any trigger matches, invoke the skill before responding. Multiple triggers can fire simultaneously.

Conflict Resolution

When multiple skills could activate for the same situation, follow this priority chain:

1. Debugging (shipyard-debugging) — always investigate root cause before anything else
2. TDD (shipyard-tdd) — if writing code, tests come first
3. Verification (shipyard-verification) — before claiming anything is done
4. Brainstorming (shipyard-brainstorming) — design before implementation
5. Security (security-audit) — security concerns override feature work
6. All others — apply in the order they match

Example: User says "fix this bug and add tests" → debugging first (investigate), then TDD (write failing test), then verification (prove it works).

Red Flags

These thoughts indicate a missed skill invocation:

Skill Priority

When multiple skills could apply: process skills first (brainstorming, debugging), then implementation skills (executing-plans, parallel-dispatch).

Skill Types

Rigid (TDD, debugging, verification): Follow exactly. Flexible (patterns): Adapt to context. The skill itself tells you which.

User Instructions

Instructions say WHAT, not HOW. "Add X" or "Fix Y" doesn't mean skip workflows.

Good: Skill invoked before responding

User: "Add a health check endpoint"

Before responding, check triggers:

• Task marker → this is implementation → check for shipyard:shipyard-tdd (writing code)
• State condition → starting feature work → check for shipyard:git-workflow (branch management)

Result: Invoke shipyard:shipyard-tdd, then proceed with implementation using TDD discipline.

Bad: Skipping skill invocation

User: "Add a health check endpoint"

Immediately start writing code without checking triggers. Miss TDD discipline, skip branch creation, no verification before claiming done.

Good: Multiple triggers fire

User: "Fix the SQL injection bug in the auth module"

Triggers matched:

1. Content pattern → "bug" → invoke shipyard:shipyard-debugging (investigate root cause first)
2. Content pattern → "SQL injection" → invoke shipyard:security-audit (check for related vulnerabilities)
3. State condition → will claim "fixed" when done → invoke shipyard:shipyard-verification (verify before claiming)

Result: Debug first, audit for related issues, verify the fix works.

Converted and distributed by TomeVault — claim your Tome and manage your conversions.