Onboard your repo to TaskShipyard

Connect your repository

Signing up creates your account and its first project, so there is nothing to set up before this step. The dashboard opens on START HERE, which tracks your progress through the stops below and takes the last one for you.

Install the TaskShipyard GitHub App on your organisation and pick the repositories to watch. It is a full-page redirect: there are no tokens to paste and no webhooks to wire up by hand.

You come straight back to the same stop, where you pick the repository from the ones you just granted and the branch your shipments start from and merge back into, both from a list rather than typed. It then shows the dev-environment setup it detected in that repo. On GitLab there is no app to install: a project access token does the same job, under PROJECTS → INTEGRATIONS.

One project is one codebase. A second repository is a second project on the same account: add it there, connect it the same way, and both ship onto one board.

✓Checkpoint: The stop shows your repository and its target branch.

Assign a Claude account

Shipments run on your own Claude subscription, on your own machine, so the account is something you connect once and the whole account shares. Run claude setup-token on your machine, authorize, and paste the line it prints into the START HERE stop.

The token is cleaned as you paste it (a copy out of a wrapped terminal carries the line break INSIDE the token) and checked before it is stored, so a bad paste is refused here rather than at your first run. We read which Claude account it belongs to from the token itself: there is nothing to name.

Connect two accounts if you can. A Claude subscription has a usage window, and when one account reaches it the next shipment moves to the other rather than waiting.

claude setup-token

✓Checkpoint: The stop reads at least one account available to run your shipments.

Add a taskshipyard/ folder

Like a supabase/ folder, a taskshipyard/ folder in your repository tells TaskShipyard how to run and verify your app. It is versioned with your code, so the workstation is configured by the repo rather than by anything hard-coded on our side.

Copy the template closest to your stack and change the port to match your app.

taskshipyard/
├── start.sh          # how your dev environment boots
├── employeebot.md    # your handbook: the stack, and how to test
└── architecture.md   # written by us on your first run, not by you

start.sh

Brings your dev environment up: npm run dev, sst dev, a migration and a seed. The primary and most flexible option.

compose.yaml

For container-native stacks: the workstation runs docker compose up -d instead.

employeebot.md

Your handbook: the company, the stack, and above all how you require a feature to be tested before it counts as done.

architecture.md

Nothing to write. TaskShipyard maps your system on the first run and redraws it on every run after, rendered under PROJECTS → ARCHITECTURE for that codebase.

✓Checkpoint: A workstation can boot your stack from a clean checkout, with nobody configuring it by hand.

Tag an issue with @taskship

Your first issue is opened for you. The last stop of START HERE writes it into the repository you connected, and its one line asks TaskShipyard to onboard itself to your codebase by reading this page. That first shipment is the product demonstrating itself, and you did not have to write a brief for it.

Every issue after that is yours: write it the way you would for a colleague, then mention @taskship in it or in a comment on it. That issue is the whole brief. There is no chat window and no prompt to engineer.

TaskShipyard boots a workstation from your taskshipyard/ folder, runs one agent on that one feature, and holds it to your handbook, including screenshots of the running app, captured on the machine for any framework.

@taskship

✓Checkpoint: A run appears in Shipments, bound to a workstation and working your issue.

Open the running app, then merge

The run pushes a branch and opens a pull request whose body is the agent’s own verification write-up: the screenshots it took, the API responses it got, the cloud resources it created and the database rows its feature writes. The same write-up goes back on the issue.

The stack it built against stays up as a preview, so reviewing is clicking through a running app rather than reading a hundred-file diff. Merge or close it like any other pull request. Production deploys stay a human action.

✓Checkpoint: A reviewed pull request, with the running app that proves it still open in a tab.