Repository setup for agents

Use this guide when you need to configure a repository for Shipper without running shipper setup.

Task 1: Configure dependency bootstrap

Inspect the full repository layout and configure the dependency bootstrap Shipper should run in new worktrees.

Build a bootstrap inventory.

Read .shipper/settings.json, then inspect root and nested manifests/lockfiles such as package.json, package-lock.json, pnpm-lock.yaml, yarn.lock, bun.lockb, Cargo.toml, Cargo.lock, go.mod, go.work, go.sum, pyproject.toml, requirements.txt, Pipfile.lock, and poetry.lock. Also inspect workspace declarations such as npm workspaces, pnpm-workspace.yaml, Yarn workspaces, Cargo workspaces, Go workspaces/modules, Python project files, .github/workflows/, package scripts, repo setup scripts, build scripts, and existing hooks. Produce a concrete list of package/project areas required by known build, type-check, and test commands before choosing commands.
Choose the bootstrap using only existing Shipper configuration.

Use installCommand for the primary/root install when a single command covers the relevant areas. Generate an executable .shipper/hooks/worktree-setup for additional idempotent package or project steps when a single root install is not enough. Do not add a new bootstrap settings schema.

Single root workspace install:
```
{
  "installCommand": "npm install"
}
```
Multi-package bootstrap:
```
{
  "installCommand": "npm install"
}
```
```
#!/usr/bin/env bash
set -euo pipefail

(cd packages/mobile && npm install)
(cd tools/codegen && npm install && npm run build)
```
Save the script as .shipper/hooks/worktree-setup and run:
Terminal window
```
chmod +x .shipper/hooks/worktree-setup
```
Hook-only bootstrap is also valid:
```
{
  "installCommand": ""
}
```
Deliberate no-bootstrap is recorded the same way after confirming with the user that the repository genuinely needs no install step:
```
{
  "installCommand": ""
}
```
Handle native-build and special prerequisites conservatively.

Look for Node native packages, Electron rebuild/package steps, Cargo build scripts, Python extension builds, Go CGO signals, and explicit workflow prerequisite commands. Configure only repository/package-level install, rebuild, or build commands that Shipper can safely run. Do not add apt, brew, Xcode Command Line Tools, SDK, compiler, or system-library provisioning to installCommand or .shipper/hooks/worktree-setup; list those prerequisites for the user to install manually.
Verify the configured bootstrap through Shipper’s runtime primitive.

Create a temporary cold verification checkout from the repository source under .shipper/tmp/bootstrap-verify-<unique-suffix>. This path is gitignored and absent from a clean worktree; create it only as a disposable verification checkout. Prefer git worktree add --detach <tmp> HEAD so the checkout includes the repository manifests, lockfiles, and source. If git worktree is unavailable, copy the tracked working tree instead. Overlay the just-written .shipper/settings.json to <tmp>/.shipper/settings.json. If you generated .shipper/hooks/worktree-setup, copy it to <tmp>/.shipper/hooks/worktree-setup and keep it executable. Then run:
Terminal window
```
shipper bootstrap --cwd <tmp>
```
After bootstrap succeeds, run the single type-check/build follow-up from inside <tmp>. Remove the temporary checkout/worktree when verification finishes.
Run exactly one lightweight follow-up verification when possible.

After bootstrap succeeds, run exactly one known type-check command when available; otherwise run exactly one known build command. Do not run tests, lint, format, or aggregate commands that include tests. If no type-check/build command can be justified from CI or package scripts, state explicitly that bootstrap verification could not be performed.
Report what was configured and why.

Include the package/project areas covered by installCommand, the areas covered by .shipper/hooks/worktree-setup, any manual system prerequisites, the shipper bootstrap --cwd result, and the single type-check/build result or the reason that verification could not run.

Task 2: Generate or update the agent configuration file

Create or update the repository’s agent configuration file so coding agents know which verification commands to run.

Select the target file.

Use CLAUDE.md for Claude Code. Use AGENTS.md for Codex, Copilot, or OpenCode.
Discover CI commands from .github/workflows/.

Treat workflow files as the source of truth. Read every workflow that exists and extract the exact lint, format-check, type-check, build, and test commands CI runs. Do not hardcode generic commands.
Update an existing file in place.

If the target file exists, preserve its content. Add a Commands section if it does not have one. If it already has a commands section, verify it matches CI and update only the commands that need to change.
Create a missing file only with facts you can support.

If the target file does not exist, create it with a brief project description inferred from the repository and a Commands section only when CI commands exist.
Skip commands when no CI configuration exists.

If .github/workflows/ is missing or has no CI commands, omit the Commands section in a new file. Leave an existing commands section unchanged.
Keep the file synchronized with any workflow you create later.

If Task 3 writes .github/workflows/pr-checks.yml, immediately revisit this configuration file and make its Commands section match the selected checks.

Task 3: Scaffold PR-check workflow if missing

Determine whether the repository already has PR-triggered GitHub Actions coverage. Create a workflow only when coverage is missing.

Inspect .github/workflows/*.yml and .github/workflows/*.yaml.

Treat a workflow as sufficient when its top-level on: block includes pull_request, a bare-list pull_request entry, or pull_request_target. Use tolerant string or line-based inspection. Do not add a YAML parser dependency.
Skip scaffolding when PR coverage exists.

If any workflow already covers pull requests, skip the workflow scaffold and continue to Task 4.
Infer verification commands when PR coverage is missing.

Reuse the repository signals from Tasks 1 and 2. The workflow install step must use the same configured installCommand.
- For Node projects, infer scripts named lint, format:check or format-check, typecheck or type-check, test, and build.
- For Cargo projects, infer cargo fmt --check, cargo clippy, cargo test, and cargo build.
- For Go projects, infer go vet, go test ./..., and go build ./....
- For Python projects, infer commands from detected tools such as ruff, mypy, and pytest.
Offer only commands you can justify from detected scripts, lockfiles, or tooling.
Continue without writing a workflow when no commands can be inferred.

Explain that Shipper recommends lint, format-check, type-check, test, and build scripts plus a PR-checks workflow and branch protections because coding agents need deterministic green/red signals and Shipper’s review and merge gates rely on them. Then continue to Task 4.
Present inferred commands and require confirmation before writing.

Describe the planned workflow in natural language only. Do not preview file contents. Explain that .github/workflows/pr-checks.yml will run on pull_request against the default branch, using one human-readable ubuntu-latest job per selected command.

Resolve the default branch.

gh api repos/{owner}/{repo} --jq .default_branch

Check for an existing target file before writing.

If .github/workflows/pr-checks.yml already exists, do not overwrite it. Explain why and skip the write.
Write .github/workflows/pr-checks.yml only after explicit confirmation.

Use on: pull_request: branches: [<default branch>]. Create one job per selected command. Each job should use actions/checkout@v4, the matching ecosystem setup action, the configured installCommand, and then the single verification command. Keep the workflow simple: no matrix, no file-content preview, and no caching beyond what the setup action provides by default.
Sync the agent configuration file.

After writing the workflow, update CLAUDE.md or AGENTS.md so its Commands section matches the selected checks.

See Reference > CLI for command details.

Task 4: Configure branch protections

Always ask whether to configure branch protections after Task 3 resolves, regardless of whether scaffolding succeeded, was skipped, was declined, or had no inferred commands.

If the user declines, continue without configuring protections.
If the user approves, create a repository ruleset.

Use gh api repos/{owner}/{repo}/rulesets -X POST. Target ~DEFAULT_BRANCH and include a name field such as Shipper PR Checks.
Add required status checks only when selected check names exist.

If selected check names exist, include a required_status_checks rule with those names. If no selected check names exist because scaffolding was declined or no commands could be inferred, explain that Shipper cannot configure a “require PR checks to pass” ruleset yet and do not send an empty required_status_checks rule.
Use a workflow-file rule only with the correct rule type.

If Task 3 created .github/workflows/pr-checks.yml and you add a workflow-file rule, use the workflows rule type, not required_workflows. Resolve the repository ID first:
Terminal window
```
gh api repos/{owner}/{repo} --jq .id
```
Include both repository_id and path: ".github/workflows/pr-checks.yml" in the workflow entry.
Do not use classic branch protection APIs.
Handle permissions failures without failing setup.

If gh api returns 403, report that the user lacks permission to administer branch protections and continue setup.