shipyard

Use after implementing features, before claiming a phase is complete, when reviewing AI-generated code, or when code feels overly complex — detects duplication, dead code, over-engineering, and AI-specific bloat patterns

Use when generating documentation, updating README files, writing API docs, creating architecture documentation, or when documentation is incomplete or outdated

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

Use when working with Terraform (.tf, .tfvars), Ansible (playbooks, roles, inventory), Docker (Dockerfile, docker-compose.yml), CloudFormation, or any infrastructure-as-code files — provides validation workflows, tool chains, and common mistake prevention

Use when user asks 'how should I...' or 'what's the best approach...' after exploring code, OR when you've tried to solve something and are stuck, OR for unfamiliar workflows, OR when user references past work. Searches conversation history.

Use when facing 2+ independent tasks that can be worked on without shared state or sequential dependencies

Use when working with any code, infrastructure-as-code, configuration files, dependencies, or before claiming security posture is adequate — covers OWASP Top 10, secrets detection, dependency vulnerabilities, IaC security, Docker hardening, and supply chain risks

You MUST use this before any creative work - creating features, building components, adding functionality, or modifying behavior. Explores user intent, requirements and design before implementation. Also used during /shipyard:init for requirements gathering.

Use when encountering any bug, test failure, or unexpected behavior, before proposing fixes

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

Use when implementing any feature or bugfix, before writing implementation code

Use when writing tests, structuring test suites, choosing test boundaries, or debugging test quality issues like flakiness, over-mocking, or brittle tests

Use when about to claim work is complete, fixed, or passing, before committing or creating PRs - requires running verification commands and confirming output before making any success claims; evidence before assertions always

Use when you have a spec or requirements for a multi-step task, before touching code

Use when creating new skills, editing existing skills, or verifying skills work before deployment