Ways of working

Two paths, one pipeline

Every mission runs the same pipeline, whichever way the work arrives. The stages are the same: Planner, Builder, CI, Reviewer, preview deploy and QA. The retry behavior, the verdicts and the cost accounting are also the same.

The difference is where a mission starts and where it reports to you. That usually depends on who hands the work over.

Neither path is a lesser version of the other. Both lead into the same pipeline.

Ticket to PR

Someone files an issue that describes what they want, with acceptance criteria, and mentions @SHIP on it. That is the whole interface.

The mission reports back on the issue itself. It comments on its progress as it plans, builds, reviews and tests, and it opens a pull request that closes the issue on merge. A comment on the issue is the permission, so nobody involved needs a SHIP login, a token or any installed software.

To give the mission instructions, do the same thing. Reply on the issue with the change you want, and the agents apply it to the open pull request. If you ask for a change to the output of one stage, SHIP runs that stage again and does not start over. The controls are @SHIP pause, @SHIP resume and @SHIP stop. The console has the same three controls as buttons.

SHIP supports two trackers: Linear and GitHub Issues. On GitHub, the trigger is an @SHIP comment from a person with write access to the repository.

Agent to PR

You are in your editor with a coding agent, and you just wrote a spec or finished a branch that you want to hand over. There is no issue, and for this kind of work there usually should not be one.

# You wrote the plan; SHIP skips its own planning and builds from it
ship delegate plan --title "Rate-limit the search endpoint" --file docs/plan.md

# You wrote the code; SHIP reviews it, tests it and drives it to merge
ship delegate pr

The hand-off creates the mission. With no tracker behind it, SHIP creates the mission id itself, for example M-3f9a2c1b04. The mission page in the console is the home of that mission. By design, the id does not look like an issue reference, so nobody looks for an issue that nobody filed.

Your agent can do all of this for you. When it runs set up https://letsship.ai/SKILL.md, it learns when to delegate, which command fits and how to report back. See Getting started.

To give the mission instructions, use ship instruct:

ship instruct M-3f9a2c1b04 -m "Keep the current Node range, override nopt instead"
ship instruct M-3f9a2c1b04 --file review-notes.md
ship instruct M-3f9a2c1b04 -m "FYI staging is down until 14:00" --note

Use ship instruct, not a restart. A restart checks the pull request again against the results it already has. It correctly finds no change and does nothing. The restart looks like a success, but the feedback goes nowhere. An instruction is the channel for new information. The --note flag leaves context for the next agent that runs, and it does not start any work.

This path gives you one thing that the Ticket to PR path does not: per-mission control. The --harness and --model flags set how one mission runs and do not change the project's configuration. The --prompt-file flag gives one role extra instructions for one mission, for example a security pass over this branch. When you add a concern, use --prompt-mode extend so the repository's own conventions for that role stay in place.

Running both

A project does not have to choose. A project with a tracker still accepts hand-offs from the CLI. Both kinds of mission show on the same board, write the same logs and give the same verdicts. Their costs go into the same cost reports.

The paths also cross. For example, ship instruct SHIP-412 sends an instruction to a mission that started from an issue. This helps when the Reviewer finds a problem and you prefer to answer from your terminal, not in a comment. Everything that either path can do is also in the API. So a bot or an internal tool is a third client of the same API, not a special case.

This pattern works well in practice:

• Feature and bug work comes in as issues, because the people who ask for it already work in the tracker. The issue is also the right place for the record of decisions.
• Refactors, upgrades, chores and work that a developer already has in mind come from the terminal. An issue for work that you already specified is only extra work.
• Both kinds of work end as pull requests in the same repository, with the same review and the same tests.

Choosing a project's tracker

You set the project's tracker when you create the project. You can change it later:

• Linear. Mention @SHIP on an issue to start a mission.
• GitHub Issues. Comment @SHIP on an issue in the repository.
• No tracker. Hand work over from the terminal only. Missions live in the console, and nothing asks for an issue first.

If you pick no tracker, you do not lose a capability. The choice only says that the work of this project does not start as an issue. If you connect a tracker later, the Ticket to PR path opens. The missions that you already ran do not change.