Agent workflows

End-to-end recipes for driving Bowline from a coding agent: lease, work, review, remote bootstrap, and conflict repair.

This page shows the common end-to-end flows an agent runs against Bowline. Each one composes the agent commands under the rules in the agent-native contract. All commands accept --json; mutations accept --dry-run and --idempotency-key.

Run a task in the real project

The default write target for a direct lease is the real project directory. The agent's edits enter the normal local write log and sync as ordinary workspace state. No Git publish is required.

Discover the contract and read state.

bowline contract --json
bowline status ~/Code/acme/web --json

Start a lease for the task and read its context and prompt.

bowline agent start ~/Code/acme/web --task "fix the auth callback race" --json
bowline agent context --lease <id> --json
bowline agent prompt --lease <id>

Explore with bounded, index-backed tools before broad reads.

bowline search "auth callback" ~/Code/acme/web --json
bowline symbols AuthCallback ~/Code/acme/web --path-prefix src --json

Do the work in the project directory, then complete the lease. A non-conflicting Agent Overlay becomes a Workspace Snapshot and advances the Workspace Head automatically.
```
bowline agent complete --lease <id> --json
```

Review before applying with a Work View

When the work needs human review before it touches the main project, start the lease through an isolated Work View. Work-view output never applies to the main project until someone accepts it.

bowline agent start ~/Code/acme/web --task "risky refactor" --work-view --json
# ... agent works in the isolated overlay ...
bowline agent publish --lease <id> --json

The published output is reviewable with bowline review and bowline diff, and a person applies it with bowline accept or drops it with bowline discard. See work with coding agents for the human side.

Extend the hydration budget

A lease has a bounded hydration budget so an agent can't pull the whole workspace. If a task legitimately needs more, request additional budget rather than working around the limit.

bowline agent budget --lease <id> --add 256MiB --json

Bootstrap a remote host and hand off

To run on a remote host, complete a Remote Bootstrap and hand off into a lease in one command. The host becomes a trusted device, and the lease starts in the named project.

bowline connect linux-server-1 \
  --project ~/Code/acme/web \
  --task "fix the auth callback race" \
  --agent codex \
  --json

Trust requires a completed bootstrap

Treat the host as trusted only when bowline connect finishes with no blocked steps and reports trusted: true. SSH reachability, host login, or copied binaries are never workspace trust on their own.

Repair a conflict

Conflict repair is an agent-assisted action a person starts, not a new publishing path. The repair works inside a Conflict Bundle and produces a Resolution Overlay the user accepts.

bowline status --json
bowline resolve --diff <conflict> --json
bowline resolve --agent codex
# or, when no agent CLI is available:
bowline resolve --copy-prompt

The agent must work only inside the bundle's resolution directory, respect Conflict Spans and per-key env merges, avoid source-control actions, and run the narrowest relevant checks. A person accepts the Resolution Overlay before it affects the live project.

Idempotent retries

Wrap retryable mutations with an idempotency key so a retried step replays the stored result instead of acting twice.

bowline agent complete --lease <id> --idempotency-key complete-<id>-1 --json

A replay with the same key and request returns the stored result marked replayed: true; a different request under the same key returns an idempotency_conflict error.

Next steps

Agent-native contract: the rules these flows rely on.
Agent leases: lease lifecycle and overlays.
Work with coding agents: the human side of these flows.