Work views

Isolated, cd-able project views under ~/Code/.work for risky or review-before-apply work, shared by humans and agents.

A work view is an opt-in, isolated view of a project that lives under ~/Code/.work. You use one when you want to try something risky, run an experiment, or hold changes for review before they touch the main project, all without a Git worktree, branch, commit, or pull request. The same work view folders serve humans and coding agents, so the path is the product and the Git ceremony stays optional.

What a work view is

A work view is a real, cd-able directory with a fresh base, isolated writes, inherited project env, and automatic ordinary-file materialization. You create one, work in it with your normal shell and editor, and then accept it into the main project or discard it. Nothing in a work view reaches the main project until you accept it.

Two paths matter, and both are stable across every authorized machine:

Path	What it is
`~/Code/acme/web`	The main view: the normal project path.
`~/Code/.work/acme/web/auth-fix`	A work view: an isolated, named view of the same project.

~/Code/.work is a Bowline namespace, not source inside a repository. It never shows up as untracked content and never makes git status noisy in the main view. Creating a work view is metadata-first: Bowline records a small work view ref that points at the project, a base Workspace Snapshot, an empty overlay, and the project env profile. It does not copy or upload the project tree, and other devices learn the work view exists without downloading anything until they touch it.

Work views inherit project env by default. Your .env, .env.local, and .env.* values rematerialize in the work view, so cd ~/Code/.work/acme/web/auth-fix && pnpm dev works without copying secrets between machines.

Automatic head advance versus review-before-apply

The contrast with ordinary work is the reason work views exist. When you edit a project at its main path, those edits form a Machine Overlay on the current Workspace Snapshot. A non-conflicting Machine Overlay becomes a new Workspace Snapshot and advances the Workspace Head automatically. There's no accept step and no Git publish required. Diverging edits surface as conflict-aside files instead.

A work view holds its changes in an isolated overlay that never advances the main project's Workspace Head on its own. The overlay stays separate until you run bowline work accept, at which point Bowline performs a three-way snapshot merge against the current main view. This is what makes a work view the place for review-before-apply work: the main project keeps moving while the work view waits for your decision.

Lifecycle

A work view moves through a fixed set of lifecycle states. The default view of ~/Code/.work stays small. It shows active work you started or follow, plus review-ready work, while accepted, discarded, expired, and archived work stays out of the way but remains discoverable.

State	Meaning
`active`	Writable or currently in progress.
`review-ready`	Complete enough for you to review.
`accepted`	Merged into the main view.
`discarded`	Intentionally thrown away.
`expired`	Inactive beyond retention policy.
`archived`	Hidden from the default view but restorable during retention.

You drive the lifecycle with a small set of commands. Supported mutations accept --dry-run to preview the effect, and most commands accept --json. Retry only failures with exit code 3 and retryable error.recoverability, honoring error.retryAfterSeconds when present.

Command	What it does
`bowline work create [project] <name>`	Create or reuse a named work view under `~/Code/.work`.
`bowline work list [--all]`	List work views and their state.
`bowline work diff <target>`	Show what the work view changed.
`bowline work review <target>`	Preview whether the work view is ready to apply.
`bowline work accept <target>`	Apply a review-ready work view into the main view.
`bowline work discard <target>`	Drop a work view without touching the main view.
`bowline work restore <target>`	Bring a hidden or discarded work view back into view.
`bowline work cleanup [--apply]`	Reclaim local backing store for hidden work views.

Using a work view

The daily loop stays boring on purpose. Create a work view, work in it with ordinary tools, then decide what happens to it.

Create or reuse a work view with bowline work create ~/Code/acme/web auth-fix.
Change into it with cd ~/Code/.work/acme/web/auth-fix and work normally: run pnpm dev, edit files, run tests.
Inspect the result with bowline work diff auth-fix, and confirm readiness with bowline work review auth-fix.
Apply it with bowline work accept auth-fix. The main view advances to a new Workspace Snapshot, and cd ~/Code/acme/web && git diff shows the change for your own Git workflow.
Or drop it with bowline work discard auth-fix. Discard hides the visible path and leaves the main view untouched; overlay state remains recoverable with bowline work restore auth-fix until retention expires.

Important

Accepting a work view never commits, pushes, opens a pull request, or mutates any source-control ref. It merges files into the main view only. Publishing stays your Git workflow, and changes that touch policy, secrets, or conflicting spans require an explicit review path before they apply.

Work views and coding agents

Work views are useful without agents, and that's the pressure test that keeps them clean. Coding agents then consume the same primitive. A trusted agent works in the real project directory by default; when you want its output held for review, create a work view and point the agent at the isolated directory instead:

bowline work create ~/Code/acme/web auth-fix
# point the agent at ~/Code/.work/acme/web/auth-fix

The agent works only inside that directory, so its edits stay isolated. You inspect its output with normal tools (cd ~/Code/.work/acme/web/<name>, bowline work diff <name>, pnpm test) and then bowline work accept <name> or bowline work discard <name>. This keeps the agent machinery below the product fold: you see folders and status, not a workflow console.

Next steps

Coding agents: how agents work in real directories and work views.
Work with coding agents: a task guide for handing work to local and remote agents.
Sync and continuity: how non-conflicting overlays advance the Workspace Head automatically.
Conflicts: what happens when an accept can't merge cleanly.
CLI commands: the full reference for bowline work create, accept, discard, and cleanup.