shipyard

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

Use to inspect or manage Shipyard project state under Codex — show status, resume a previous session, cancel/pause in-progress work, or roll back to a checkpoint. Trigger when the user says "shipyard status", "what's the status", "resume", "continue where we left off", "cancel", "pause this", "roll back", or "restore the checkpoint". Codex has no SessionStart hook, so this skill loads state on demand.

Use when running any multi-step Shipyard workflow under Codex — build, audit, plan, ship, review, research, or map. Explains how Shipyard's parallel-agent workflows degrade to inline sequential execution in Codex, and routes intent to the right workflow skill. Trigger when the user says "build the plan", "audit this", "ship it", "review the code", "run the shipyard build", or asks how Shipyard works in Codex.

Use when performing brownfield analysis on an existing codebase under Codex — onboarding to a new project, generating codebase documentation, or understanding legacy code. Trigger when the user says "map this codebase", "help me understand this code", "document this project", "I just inherited this repo", or runs shipyard init on existing code. This is the Codex inline-sequential form of the mapper agent.

Use when conducting domain research, evaluating technology options, investigating ecosystem choices, or gathering knowledge for a development phase under Codex. Trigger when the user says "research X", "what are our options for", "evaluate these libraries", "what's the best approach to", or before planning a phase. This is the Codex inline-sequential form of the researcher agent.

Use when reviewing code under Codex — verifying spec compliance, conducting quality review after a build, or checking that an implementation matches its plan. Trigger when the user says "review this", "review the implementation", "does this match the plan", "check the code quality", or after a Shipyard build completes. This is the Codex inline-sequential form of the reviewer agent.

Use when delivering or releasing a completed Shipyard phase under Codex — final verification, pre-ship security audit, documentation, and release. Trigger when the user says "ship it", "ship this phase", "release this", "we're done — finalize", or "run the shipyard ship workflow". This is the Codex inline-sequential form of the /shipyard:ship orchestration.

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.

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.

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.