Agent workflows

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

Run a task in the real project

The default place to work is the real project directory. Point the agent at ~/Code/<project> and let it use its own filesystem and code tools; there is no session to start and no completion step. Edits enter the normal local write log and sync as ordinary workspace state. No Git publish is required.

1. Discover the contract and read state.

   bowline contract --summary --json
   bowline status --root ~/Code --project ~/Code/acme/web --json

2. Do the work in the project directory with the agent's native tools. As the agent writes, non-conflicting edits become a new Workspace Snapshot and advance the Workspace Head automatically, the same as any other local edit.

3. If another device diverged on the same file in the meantime, the sync engine writes a conflict-aside file next to it instead of merging. bowline status surfaces the aside as attention; reconciling it is the ordinary-edit flow below.

Review before applying with a work view

When the work needs human review before it touches the main project, give the agent an isolated work view instead of the main path. Work-view edits never apply to the main project until someone accepts them.

bowline work create ~/Code/acme/web risky-refactor
# point the agent at ~/Code/.work/acme/web/risky-refactor

The work view is a real, cd-able directory with the project's files and env, so the agent works there exactly as it would in the main path. It is reviewable at any time with bowline work review and bowline work diff, and a person applies it with bowline work accept or drops it with bowline work discard. bowline work list and bowline status show review-ready work. See work with coding agents for the human side.

Work on a remote host

To run an agent on a remote host, first complete a Remote Bootstrap. This is a trust step only: it installs Bowline over SSH and brings the host into device trust, after which the host has the same real ~/Code.

bowline connect linux-server-1 --json

Then point the agent at the project directory on that host yourself — for example, over SSH, launch your agent CLI in ~/Code/acme/web. Bowline does not start or supervise the agent; its job is to make the right workspace state, including env and secrets, exist on the trusted host.

Reconcile a conflict

A conflict is not a state machine. When two devices diverge on the same file, the sync engine writes a deterministically named aside file next to it — the name shape is <path>.bowline-conflict.<prefix> — and the aside syncs like any other file.

bowline conflicts --root ~/Code --json

Each entry carries originPath, asidePath, and a ready-to-run resolveCommand. To pick a side without reading either file:

bowline resolve '<asidePath>' --diff          # read the difference, change nothing
bowline resolve '<asidePath>' --keep-local    # keep the file as it stands
bowline resolve '<asidePath>' --take-remote   # adopt the incoming version

To fold both sides together instead, the agent opens the file and its aside with ordinary read and edit tools, merges the wanted changes into the real file, and deletes the aside. Either route is ordinary file edits, so the result syncs and advances the Workspace Head like any other work. No source-control actions are involved.

bowline status also lists conflict-asides as attention, so an agent already polling status sees them without a second command.

Next steps

• Agent-native contract: the rules these flows rely on.
• Coding agents: the directory and work-view model.
• Work with coding agents: the human side of these flows.