shipyard

On-demand security audit — OWASP, secrets, dependencies, IaC security

Explore requirements through Socratic dialogue and capture project definition

Execute plans using fresh subagents with review gates

Pause in-progress work with a checkpoint

Investigate bugs and failures with systematic root-cause analysis

Check Shipyard plugin health and dependencies

On-demand documentation generation — API docs, architecture updates, user guides

Show help for Shipyard commands and skills

Initialize Shipyard project settings and directory structure

View and manage deferred issues tracked across sessions

On-demand codebase analysis — map technology stack, architecture, quality, or concerns

Move codebase documentation between .shipyard/codebase and docs/codebase

Plan a phase of work (creates roadmap if needed)

Execute a small task with Shipyard guarantees

Diagnose and recover from interrupted or corrupted state

On-demand domain research — evaluate technology options, investigate ecosystem choices

Restore context from a previous session and continue

On-demand code review — review current changes, a diff range, or specific files

Revert to a previous Shipyard checkpoint

View or update Shipyard workflow settings

Finish and deliver completed work

On-demand simplification review — detect duplication, dead code, unnecessary complexity, AI bloat

Show project progress and route to next action

On-demand verification — run tests, check acceptance criteria, validate phase completion

Manage git worktrees for isolated feature development

Use this agent when creating roadmaps, decomposing plans into tasks, making architecture decisions, or breaking down requirements into executable work. Examples: <example>Context: The user is initializing a new project and needs a roadmap. user: "Create a roadmap for building this application" assistant: "I'll dispatch the architect agent to decompose the requirements into phased milestones with dependency ordering and success criteria." <commentary>The architect agent creates roadmaps during /shipyard:init, ordering phases by dependency and risk.</commentary></example> <example>Context: The user needs to plan a specific development phase. user: "Plan the database layer phase" assistant: "I'll dispatch the architect agent to decompose this phase into a structured plan with tasks, verification commands, and success criteria." <commentary>The architect agent creates plans during /shipyard:plan, breaking phases into bite-sized tasks with clear TDD steps and verification.</commentary></example> <example>Context: The user wants a quick, simplified plan for a small feature. user: "Quick add a health check endpoint" assistant: "I'll dispatch the architect agent in simplified mode to produce a lightweight plan for this small feature." <commentary>During /shipyard:quick, the architect produces a simplified plan suitable for small, self-contained changes.</commentary></example>

Use this agent for comprehensive security and compliance analysis across all changes in a phase or milestone. Covers OWASP Top 10, secrets detection, dependency vulnerabilities, IaC security, and supply chain risks. Examples: <example>Context: A phase build is complete and needs security review before proceeding. user: "Run a security audit on the authentication phase" assistant: "I'll dispatch the auditor agent to perform a comprehensive security scan across all files changed in this phase, checking for OWASP vulnerabilities, secrets, dependency issues, and IaC misconfigurations." <commentary>The auditor agent runs after phase verification during /shipyard:build and before delivery during /shipyard:ship, analyzing cross-cutting security concerns that per-task reviews can't catch.</commentary></example> <example>Context: The project is ready to ship and needs a final security gate. user: "Ship it" assistant: "Before shipping, I'll dispatch the auditor agent for a comprehensive security audit across all milestone changes to ensure nothing was missed by individual task reviews." <commentary>During /shipyard:ship, the auditor provides the final security gate. Critical findings block delivery.</commentary></example>

Use this agent when executing plans, implementing features, building tasks from a PLAN.md, or running TDD implementation cycles. This is the primary implementation agent. Examples: <example>Context: A plan has been created and is ready for execution. user: "Build the authentication phase" assistant: "I'll dispatch the builder agent to execute the plan tasks sequentially, following TDD protocol where specified and creating atomic commits for each task." <commentary>The builder agent executes structured plans, following the task protocol strictly including TDD, verification, and atomic commits.</commentary></example> <example>Context: The /shipyard:quick command needs to execute a simplified plan. user: "Quick add a health check endpoint" assistant: "I'll dispatch the builder agent to implement the planned tasks for this quick feature." <commentary>The builder agent handles both full plans from /shipyard:build and simplified plans from /shipyard:quick.</commentary></example> <example>Context: A build was paused and needs to resume. user: "Continue building from where we left off" assistant: "I'll dispatch the builder agent to read the checkpoint and resume execution from the last completed task." <commentary>The builder agent respects checkpoints and can resume from where a previous execution stopped.</commentary></example>

Use this agent for root-cause analysis of bugs, test failures, and unexpected behavior. Follows the 5 Whys protocol and produces ROOT-CAUSE.md with evidence chain and remediation plan. Examples: <example>Context: A test suite is failing after a recent commit and the cause is unclear. user: "Figure out why the tests are failing" assistant: "I'll dispatch the debugger agent to perform systematic root-cause analysis using the 5 Whys protocol." <commentary>The debugger agent investigates before proposing any fix — it produces ROOT-CAUSE.md for the builder to act on.</commentary></example> <example>Context: A builder agent failed a task and produced structured failure documentation. user: "The builder couldn't complete task 3, debug it" assistant: "I'll dispatch the debugger agent with the builder's failure report to trace the root cause." <commentary>The debugger consumes the builder's failure documentation (task, error, files touched, hypothesis) as a starting point for investigation.</commentary></example> <example>Context: A build pipeline is failing with an obscure error. user: "The CI pipeline is broken and I don't know why" assistant: "I'll dispatch the debugger agent to read the error output carefully, check recent changes, and apply 5 Whys to find the systemic cause." <commentary>The debugger reads stack traces completely, gathers evidence at component boundaries, and follows one causal chain to a fixable root cause.</commentary></example>

Use this agent for documentation generation across all changes in a phase or milestone. Generates API docs, architecture updates, and user-facing documentation. Examples: <example>Context: A phase build is complete and needs documentation updated. user: "Generate documentation for the completed phase" assistant: "I'll dispatch the documenter agent to analyze all changes in this phase and generate API docs, architecture updates, and user-facing documentation." <commentary>The documenter agent runs after the simplifier during /shipyard:build, generating documentation that covers cumulative changes across all tasks in the phase.</commentary></example> <example>Context: The project is ready to ship and needs comprehensive documentation. user: "Ship it" assistant: "Before shipping, I'll dispatch the documenter agent to generate comprehensive project documentation including API reference, architecture overview, and user guides." <commentary>During /shipyard:ship, the documenter produces complete documentation in the docs/ directory for external users and future maintainers.</commentary></example>

Use this agent when performing brownfield analysis on an existing codebase, onboarding to a new project, generating codebase documentation, or understanding legacy code. Examples: <example>Context: The user wants to understand an existing codebase they are joining or inheriting. user: "I need to understand this existing codebase before we start making changes" assistant: "I'll dispatch the mapper agent to analyze the codebase and produce structured documentation across technology, architecture, quality, and concerns." <commentary>The mapper agent should be used for brownfield codebase analysis, producing documentation that covers the full landscape of the existing project.</commentary></example> <example>Context: The user is running /shipyard:init on a project that already has code. user: "Initialize shipyard for this project" assistant: "This is a brownfield project. I'll run the mapper agent in parallel across four focus areas to document the existing codebase." <commentary>During init on an existing codebase, mapper runs as 4 parallel instances each covering a different focus area to produce comprehensive documentation.</commentary></example>

Use this agent when conducting domain research, evaluating technology options, investigating ecosystem choices, or gathering knowledge for a development phase. Examples: <example>Context: The user is planning a new phase and needs to understand the best technology choices. user: "We need to add real-time notifications — what are our options?" assistant: "I'll dispatch the researcher agent to investigate technology options, tradeoffs, and recommended approaches for real-time notifications in your stack." <commentary>The researcher agent should be used to gather domain knowledge and evaluate technology options before committing to an implementation approach.</commentary></example> <example>Context: The /shipyard:plan command needs background research before creating a plan. user: "Plan the authentication phase" assistant: "Before creating the plan, I'll have the researcher agent investigate authentication approaches, libraries, and potential pitfalls for your stack." <commentary>During plan creation, the researcher gathers the domain knowledge needed to make informed architectural decisions.</commentary></example>

Use this agent when performing code review, verifying spec compliance, conducting quality review after a build, or checking that an implementation matches its plan. Examples: <example>Context: A plan has been fully executed by the builder and needs review. user: "Review the authentication implementation" assistant: "I'll dispatch the reviewer agent to perform two-stage review: first checking spec compliance against the PLAN.md, then assessing code quality." <commentary>The reviewer agent runs after each plan completion during /shipyard:build, performing spec compliance review followed by code quality review.</commentary></example> <example>Context: The user wants to verify that implementation matches requirements before moving to the next phase. user: "Does the API layer match what we planned?" assistant: "I'll dispatch the reviewer agent to compare the implementation against the plan and flag any deviations or missing features." <commentary>The reviewer checks both that everything planned was built and that nothing unexpected was added.</commentary></example>

Use this agent to review cumulative code changes across a phase for duplication, unnecessary complexity, dead code, and AI-generated bloat that individual task reviewers can't detect. Examples: <example>Context: A phase build is complete, all reviews passed, and the code needs a whole-picture simplification review. user: "Review the phase for simplification opportunities" assistant: "I'll dispatch the simplifier agent to analyze all files changed across the phase, looking for cross-task duplication, dead code, over-engineering, and AI bloat patterns." <commentary>The simplifier agent runs after phase verification during /shipyard:build, reviewing the cumulative effect of multiple builder agents working on different tasks.</commentary></example> <example>Context: Multiple features were implemented and the user suspects code bloat. user: "The codebase feels more complex than it should be" assistant: "I'll dispatch the simplifier agent to analyze recent changes for unnecessary complexity, duplication, and opportunities to consolidate." <commentary>The simplifier can also be dispatched on demand when complexity is suspected.</commentary></example>

Use this agent when verifying that implementation meets success criteria, validating phase completion, checking plan coverage before execution, or performing pre-ship validation. Examples: <example>Context: A phase has been fully built and reviewed, and needs final verification before moving on. user: "Verify that the database phase is complete" assistant: "I'll dispatch the verifier agent to check each success criterion from the roadmap against the actual implementation and produce a verification report." <commentary>The verifier agent runs after build completion during /shipyard:build to confirm all phase success criteria are met.</commentary></example> <example>Context: Plans have been created and need validation before execution begins. user: "Verify the plans cover all requirements" assistant: "I'll dispatch the verifier agent to check that the plans collectively cover all phase requirements and that verification commands are runnable." <commentary>During /shipyard:plan, the verifier checks plan quality and coverage before the builder starts execution.</commentary></example> <example>Context: The project is ready for final shipping validation. user: "Ship it" assistant: "Before shipping, I'll dispatch the verifier agent to perform final validation across all phases and produce a comprehensive verification report." <commentary>During /shipyard:ship, the verifier performs comprehensive validation across all phases to confirm the project is ready.</commentary></example>

Use after implementing features, before claiming a phase is complete, when reviewing AI-generated code, or when code feels overly complex. Also use when you notice repeated patterns across files, a function exceeds 40 lines, nesting exceeds 3 levels, or an abstraction has only one implementation. Covers duplication, dead code, over-engineering, and AI-specific bloat patterns like verbose error handling and redundant type checks.

Use when shipping features with public interfaces that lack docs, generating documentation, updating README files, writing API docs, creating architecture documentation, or when documentation is incomplete or outdated. Also use when adding breaking changes, implementing complex algorithms, or before shipping any phase — if a public function lacks a docstring, this skill applies.

Use when starting feature work that needs a branch, creating worktrees for isolation, making atomic commits during development, or completing a development branch via merge, PR, preserve, or discard. Also use when the user says "set up worktree", "create PR", "finish this branch", "start feature", or when you need an isolated workspace for implementation.

Import a handwritten spec document into Shipyard, replacing brainstorming. Use when a freeform spec, requirements, or design document exists.

Import a spec-kit feature spec into Shipyard, replacing brainstorming. Use when a spec-kit feature directory exists with spec.md.

Use when working with Terraform (.tf, .tfvars), Ansible (playbooks, roles, inventory), Docker (Dockerfile, docker-compose.yml), Kubernetes (manifests, Helm charts), CloudFormation, or any infrastructure-as-code files. Also use when running terraform plan/apply, building Docker images, writing Helm templates, or when IaC changes touch security groups, IAM policies, or secrets. Provides validation workflows, tool chains, and common mistake prevention.

Use when a phase or milestone is complete and you need to extract reusable knowledge, before shipping, or when reflecting on completed work. Also use when the user says "what did we learn", "capture lessons", "retrospective", "wrap up", "ship this phase", or "done with this phase". If a phase is about to ship without lesson capture, this skill must activate.

Use when facing 2+ independent tasks that can be worked on without shared state or sequential dependencies. Also use when multiple test files fail with different root causes, multiple subsystems are broken independently, or you want agents to work concurrently on separate problem domains. If tasks touch different files and don't share state, this skill applies.

Use when working with any code that handles user input, authentication, authorization, or secrets. Also use when adding or updating dependencies, reviewing infrastructure-as-code, or before claiming security posture is adequate. Covers OWASP Top 10, secrets detection (API keys, passwords, tokens in code), dependency vulnerabilities, IaC security, Docker hardening, and supply chain risks. If code touches a database query, HTTP endpoint, or config file with credentials, this skill applies.

You MUST use this before any creative work — creating features, building components, adding functionality, or modifying behavior. Explores user intent, requirements, and design through Socratic dialogue before implementation. Also use when the user says "I want to add", "let's design", "what if we", "I have an idea", or when a design discussion is happening. Invoked by /shipyard:brainstorm for requirements gathering.

Use when encountering any bug, test failure, unexpected behavior, or error message — before proposing any fixes. Also use when you see tracebacks, exceptions, "not working" complaints, build failures, performance problems, or integration issues. If you're tempted to "just try changing X and see if it works", this skill applies. Systematic root cause investigation always comes before fix attempts.

Use when you have a written implementation plan to execute, either in the current session with builder/reviewer agents or in a separate session with review checkpoints. Also use when the user says "build this", "implement this", "execute the plan", "run the plan", or when a plan file has been loaded with independent tasks suitable for agent dispatch.

Captures session context into .shipyard/HANDOFF.md so the next session can resume without losing progress.

Use when implementing any feature or bugfix, before writing implementation code. Also use when touching test files (*.test.*, *.spec.*, *_test.go), when plan tasks have tdd="true", or when the user says "test first", "write tests", "TDD", or "red green refactor". If you're about to write production code without a failing test, this skill applies.

Use when writing tests, structuring test suites, choosing test boundaries, or debugging test quality issues like flakiness, over-mocking, or brittle tests. Also use when deciding between unit/integration/E2E tests, when tests break during refactoring (sign of testing implementation details), or when test setup exceeds 20 lines. Covers AAA structure, DAMP naming, mock boundaries, and the testing pyramid.

Use when about to claim work is complete, fixed, or passing — before committing, creating PRs, or moving to the next task. Also use when you catch yourself using words like "should", "probably", or "seems to" about work state, or when expressing satisfaction ("Great!", "Done!") before running verification commands. Evidence before assertions, always.

Use when you have a spec, requirements, or design for a multi-step task — before touching code. Also triggers on "plan this", "break this down", "create tasks", "decompose this feature", or when a task clearly needs more than 2-3 steps to implement. If you're about to start building without a plan, or writing vague tasks like "implement feature X" without file paths and verification commands, this skill applies.

Use when creating, editing, or improving skills, or when a skill isn't triggering correctly. Also use when editing any SKILL.md file, writing skill descriptions, or debugging why a skill doesn't activate. Triggers on "create a skill", "write a skill", "new skill", "improve this skill", "skill isn't triggering", or when reviewing skill quality and effectiveness.

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.

5 hooks across 4 events