Step 1
Write the spec in Markdown
Put it in one Markdown file, with your own template or a spec framework such as Spec Kit. Write down what you decided. Add the acceptance criteria to the issue as a checklist.
Spec-driven development
Turn the spec you wrote into a verified pull request
You already wrote the spec, so SHIP skips the Planner. Its agents build from your file, then review and test the pull request.
- For
- Engineers and tech leads who write a spec before they write code.
- Instead of
- Code you write yourself from your own spec, or a coding agent you must watch.
Answer 4 questions, then create your account. Your first missions are free.
ship delegate plan SHIP-412 --file docs/plan.mdHow it works
Follow three steps from spec to pull request
Step 2
Run one command
Run ship delegate plan with the file and an issue, or with --title to create the issue. You can run it yourself or ask your coding agent to. Add --file-plan to list the files the change should touch.
Step 3
Merge when the checks pass
Your CI runs. The Reviewer compares the diff with your spec and shows where they differ, and the Tester checks the acceptance criteria on the issue. Then the pull request is ready for you.
Capabilities
Decide what to build, and let the agents build it
Skip the Planner when your plan is ready
The Builder follows your plan and does not write a new one. You make the design decisions, and the agents write the code.
List the files a change should touch
Pass a file plan with --file-plan, and the Builder keeps its edits to the files you listed.
Add instructions for one mission
Pass --prompt-file to give the Builder extra instructions for that mission only. Add --prompt-mode extend to keep your repository's own conventions for the role.
Compare two agents on the same spec
Send the same spec as two missions with different --harness or --model flags, then compare their cost, time and result.
Correct a mission while its pull request is open
Send a correction with ship instruct, and the Builder goes back to the open pull request with it.
FAQ
Frequently asked questions
What is spec-driven development?
Spec-driven development means you write down the decisions and the acceptance criteria before anyone writes code. Then someone builds the change and checks it against that spec. With SHIP, agents do the build, the review and the test.
Which spec formats does SHIP accept?
Any Markdown file. ship delegate plan --file reads the file from your machine and gives it to the Builder as it is. Each mission takes one file, so put the parts you want built into the file you pass.
What if my spec is vague?
Then the code will be vague too, because SHIP builds what the spec says. If you have not made the decisions yet, file the issue without a spec and let the Planner write a plan. Turn on a planner checkpoint to read that plan before the Builder starts.
Can my coding agent send the spec for me?
Yes. Say set up https://letsship.ai/SKILL.md to Claude Code, Codex or another coding agent once. After that, ask it to send a spec, and it writes the file and runs ship delegate plan for you.
Do I need an issue to send a spec?
No. ship delegate plan with --title and --file creates the mission and starts it. With Linear or GitHub Issues, SHIP files the issue for you, and with no tracker the mission lives in the console.
Where do I put the acceptance criteria?
If the project uses Linear or GitHub Issues, put them on the issue as a checklist under an Acceptance criteria heading. The Tester checks the pull request against that list and reads your spec as the plan. If the change misses a criterion that is only in the spec file, you get a note, but the check does not fail.
Hand over your next spec
Install the CLI and send SHIP the spec you already wrote.
Start your first mission
Answer 4 questions, then create your account. Your first missions are free.