Configuring Autonomy

Shipwright’s delivery loop is configurable. You choose how much the agent does on its own by enabling the right system crons and tuning state/agent-policy.md. Start with the bare minimum and add autonomy as you gain confidence.

The ramp-up path

Most teams start narrow and expand. Each stage adds one more phase to the autonomous loop.

Stage 1 — Plan and build

Enable shipwright-dev-task only. Disable shipwright-review and shipwright-patch. The agent reads your task queue, picks the next ready task, builds it with tests, and opens a PR. You review and merge PRs yourself.

This is the entry point. The agent writes code; you stay in the loop on every PR.

Note: New agents start with shipwright-dev-task, shipwright-review, and shipwright-patch all enabled (Stage 2). Disable shipwright-review and shipwright-patch via the admin UI to begin at Stage 1.

Stage 2 — Add review and patch

Enable shipwright-review and shipwright-patch. The agent now reviews open PRs and patches any that have failing CI or unresolved findings. These are two independent crons — review posts findings, patch addresses them on its own schedule — so either can be toggled alone. You still control merging.

At this stage, auto_post_reviews in state/agent-policy.md determines whether the agent posts reviews to GitHub immediately or holds them for your approval. See Staged reviews below.

Stage 3 — Full autonomous loop

Enable shipwright-deploy. The agent now merges approved PRs and monitors post-merge CI. The full loop runs without manual intervention: plan → build → review → patch → deploy.

Only enable deploy when you have the safeguards in place — CI gates, required reviewers, and a working check-deploy pre-check — so the agent can’t merge something broken.

Common workflow patterns

Hands-off: build and patch, skip review

Some projects don’t need the agent to post PR reviews. You just want it to build tasks and fix CI failures while you review PRs yourself.

Enable shipwright-dev-task and shipwright-patch. Disable shipwright-review. The agent builds, opens PRs, and patches CI — but never posts a review comment.

dev-task  ✓  patch  ✓  review  ✗  deploy  ✗

Staged reviews

You want the agent to review PRs but prefer to read and approve each review before it goes to GitHub. Set auto_post_reviews: false in state/agent-policy.md. Enable shipwright-review (and shipwright-patch if you also want findings addressed automatically).

The agent runs its review pass and writes the findings to a local review file. Nothing is posted to GitHub until you approve it. Once you’ve confirmed the review looks right, post it manually or set auto_post_reviews: true to have the agent send it.

dev-task  ✓  review  ✓  patch  ✓  deploy  ✗   (auto_post_reviews: false)

Bring your own PR

You don’t have to go through the task queue at all. Open a PR yourself — a quick fix, a hotfix, anything — and Shipwright picks it up from there. With review, patch, and deploy enabled, the agent will review the PR, patch any CI failures, and merge it once it’s clean.

dev-task  ✗  review  ✓  patch  ✓  deploy  ✓

This works and is a reasonable way to get comfortable with the system. That said, bypassing dev-task means skipping the quality work it does before the PR exists: structured planning, tests-first implementation, and the pre-PR research pass. The review and deploy phases catch issues, but they work better when the PR was built with that discipline from the start. For anything beyond a quick fix, going through the task queue produces better outcomes.

Agent policy

Ask your agent to change the policy settings in state/agent-policy.md — no restart or cron change required. For local development or self-hosted setups without a connected agent, you can edit the file directly.

# Agent Policy

## Review Settings

| Setting | Value | Notes |
|---------|-------|-------|
| `auto_post_reviews` | false | Stage reviews locally; do not post to GitHub automatically. |
| `allowed_events` | [COMMENT, APPROVE] | Never REQUEST_CHANGES |
| `review_external_prs` | true | Review externally-opened PRs |
| `allow_self_review` | true | Review own PRs |
| `min_confidence` | 75 | Drop findings below this threshold |
| `max_findings` | 5 | Trim to highest-confidence findings |

## Worktree Cleanup

| Setting | Value |
|---------|-------|
| `cleanup_merged_worktrees` | true |
| `cleanup_after_days` | 14 |

Toggling crons

Crons are toggled via the admin UI or the API. No restart required — the agent picks up changes on the next config sync (every 60 seconds).

Admin UI

Open the agent’s cron list in the admin console, find the cron by name, and flip the toggle.

API

# Disable a cron
curl -X PATCH "$SHIPWRIGHT_API_URL/agents/$AGENT_ID/crons/$CRON_ID" \
  -H "Authorization: Bearer $SHIPWRIGHT_AGENT_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"enabled": false}'

# Enable a cron
curl -X PATCH "$SHIPWRIGHT_API_URL/agents/$AGENT_ID/crons/$CRON_ID" \
  -H "Authorization: Bearer $SHIPWRIGHT_AGENT_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"enabled": true}'

Or via the shipwright:agent-admin skill from inside a Claude Code session:

Enable the shipwright-deploy cron for this agent.

Next steps

Once you have your workflow configured, the next step is deploying the agent as a persistent cloud service. See Deploying to Cloud for the Helm chart, Minikube, GKE, and EKS guides.