curl -fsSL bottega.sh | sh

That fetches the current release, verifies it against the digest published with it, unpacks it into your install root and links orch and hub onto your PATH.

Requirements

• Bun. Both commands run on it.
• GitHub CLI, authenticated — gh auth login. The repository is private, so the installer downloads the release as you.
• Git, for the projects you point Bottega at. Every writing run is isolated in a disposable worktree of the target project.
• Optional: a local model host — Ollama, vLLM, LM Studio or llama.cpp — for cheap workers and the retrieval index.

If a prerequisite is missing the installer stops and names it, along with the command that clears it. It never installs a runtime on your machine on its own.

What it does

1. Resolves the release to install — the latest, or a version you name: curl -fsSL bottega.sh | sh -s -- 0.1.0
2. Downloads the payload and checks its SHA-256 against the digest published with the release. A mismatch or a truncated download refuses loudly rather than unpacking.
3. Unpacks into ~/.local/share/bottega/<version> and points current at it.
4. Links orch and hub into ~/.local/bin.

Set BOTTEGA_HOME to install somewhere else. Re-running at the same version is safe: it reports the existing installation and leaves it alone.

Check it

orch --version
# Bottega 0.1.0 (e8489ee)

A release prints its version and the commit it was built from. A development checkout says so instead, so a bug report can never be ambiguous about which you are running.

Create the stores

orch init-db
hub migrate

Databases never live in the installation. They resolve to your per-user state directory — $BOTTEGA_STATE_HOME, then $XDG_STATE_HOME, then ~/.local/state/bottega — with orch.db and hub.db under their own concern directories. Upgrading never touches them.

Register a project

Bottega does not hold your code. It keeps a register of the projects it may work on — each an existing Git checkout with its own task-key prefix, landing branch and worktree recipe.

orch project add ~/Projects/atlas
orch project list --json

The register is the authority on which prefix belongs to which project, which branch a pull request targets, and how a disposable worktree is provisioned.

Upgrading and rolling back

Run the installer again for a newer version. Each version keeps its own directory and current is switched to the new one, so a rollback is moving that symlink back:

ln -sfn 0.1.0 ~/.local/share/bottega/current

Old versions are kept until you ask for them to go. --prune removes every version except the one in use; nothing is ever removed silently.

Running from source instead

For working on Bottega itself, a checkout still works and is the supported development path:

git clone <your-remote>/bottega.git
cd bottega
bun install
git config core.hooksPath .githooks
./bin/orch init-db

The tracked hooks refuse AI attribution in commit messages. A checkout and an installed release are equally authorised to create the stores, and --version tells them apart.

1. Open a task

Work without a key cannot be attributed later, so every run needs one. File the task first:

hub task create "Retry failed webhook deliveries with backoff" --project atlas

The key comes back in the project's own prefix — ATL-412 here. It will follow the change into the branch, the commit subject and every run.

2. Write the spec

This is the part that does not delegate. A worker builds faithfully against a written spec; it cannot build against an intention. State what the change means, which way each known ambiguity resolves, and what must stay true afterwards.

3. Dispatch

orch do implement ATL-412 --spec docs/webhook-retries.md

orch do is detached by default: it prints a run id and returns. The pack compiled into the worker's prompt carries your project rules, the job contract and the retrieval context, so you are not pasting any of it in.

run r-4f19 dispatched — detached

4. Watch without blocking

A session that waits silently is indistinguishable from a dead one. Arm the heartbeat instead:

orchestrator/hooks/orch-heartbeat.sh <session-id>

It reports one of three states: blocked — a worker asked something; waiting — runs are live and nothing is needed; clear — nothing outstanding.

5. Answer the question

A worker that reaches a judgement call it was not given stops there. That is the contract working, not a failure.

orch inbox
orch answer r-4f19 "Scope to the new path. File a note for the two call sites."

The run resumes from where it stopped with your ruling in hand. Never continue a chain whose question is unanswered — resuming forces the guess the contract exists to prevent.

6. Read the diff, then score it

orch result r-4f19
orch score r-4f19 full right --note "…"

Score correctness and fidelity separately: a complete, tested change that solved a different problem is a fidelity failure however good the code is. Never score a run you did not read, and never score another session's runs — only the session that read the output can judge it.

7. Land it

Workers never push. Run the gate on the rebased branch you are about to merge, open the pull request, and merge there.

The division

A change consists of decisions and execution. The architect decides what the change means, which ambiguity resolves which way, and what must remain true. A worker contributes execution and must not decide. Judge a delegation by whether a decision leaked to the worker — not by comparing models in the abstract.

Three load-bearing parts

1. A worker that reaches a judgement call stops and asks. It never guesses and then builds on the guess.
2. Asking is cheap and preserves the turn, so a worker can surface every real fork instead of silently resolving it.
3. Fidelity is scored independently, because a complete and technically sound result may still solve a different problem.

The invariants

These are product behaviour, not configuration. A workflow that needs different invariants is a different product.

• One disposable worktree per run.
• Workers never push.
• Escalate every decision.
• Complete review before landing.
• Compile the project's rules into every prompt.
• Record a verdict before the next run routes.

What a worker is given

The pack compiled for a run carries the job contract, the project's rules, and the retrieval context for the change. Research is handed down as a ruling, never as an open question — a networkless worker cannot answer "what is current best practice?", so the architect answers it first and states the conclusion.

Escalation in practice

orch inbox                      # what is waiting on you
orch answer <run> "…"           # record the ruling, resume the run
orch continue <run>             # only after the question is answered

Route from local evidence

Work routes from accepted and rejected runs on your repositories, keyed to the job shape, stack and review lens — not from a generic benchmark, a marketing claim or a global model average. Strength on one kind of work must not hide weakness on another.

Until a job has enough scored runs, it follows your declared preference. Past that threshold it routes by measured accepted rate.

The axes

• Delivery — did it finish the job it was given.
• Quality — is the work sound.
• Fidelity — did it build what the spec asked for. Scored only on the writing jobs, and the axis that catches an agent shipping correct, tested code that solves a different problem.

Scoring a run

orch pending                       # your unscored runs
orch result <run>                  # read it first
orch score <run> full right --note "…"

For a findings-producing review, score each finding's disposition rather than the run as a whole:

orch judge <run> full right \
  --finding 1=accepted:high \
  --finding 2=rejected:medium \
  --note "…"

Rules that keep the evidence honest

• Never score a run you did not read. A guessed verdict teaches the router something false, which is worse than no verdict at all.
• Never score another session's runs. Only the session that read the output can judge it.
• Void your own harness errors. --void keeps the run and excludes it from routing.
• A worker that stopped and asked is faithful. Mark it down and asking stops happening.

Review breadth

A change's tier comes from the higher of its risk and its cognitive size, and the tier fixes both the number of review lenses and a hard ceiling on rounds. At the ceiling, stop and ask — never dispatch another round, whatever the new findings' severity. A clean round ends the ladder.

Why it exists

An agent that greps its way through a repository spends paid context before it writes a line, and a small model runs out of room before it reaches the answer. Retrieval moves that search onto hardware you already own: embedding and reranking cost GPU seconds, not tokens.

What is indexed

• Source, chunked for retrieval.
• Docs and plans from the doc store.
• The project's rules.
• Transcripts of past runs — so "has this been tried?" is answerable.

Two stages

A vector search proposes candidates; a reranker reorders them so the top of the list is the part worth reading. Both stages run against your local model host. The result is packed into the worker's prompt — the architect never fetches it to paste it in, which would spend the exact context the delegation was avoiding.

orch find "where is a run marked void"

The register comes first

A project is registered with its main checkout path, its task-key prefix, its landing branch, which concerns it keeps and how to provision a worktree. The register — not a prompt, not a convention — is the authority.

orch project add ~/Projects/harbor
orch project list --json

Pull requests target the declared landing branch, never an optional production branch. The update verbs verify declared branches and refuse a mismatch.

Keep the tracker the project already has

A project may keep its own task tracker, doc store, workflows or review pipeline. Do not copy a Bottega mechanism into a project that can call Bottega, and do not migrate a project's tasks to put them on the board. Bottega connects to the project's own MCP server and aggregates the result.

• Native — the project uses Bottega's own store through hub.
• Its own application — an app that exposes its tasks, rules and workflows over MCP.
• A hosted tracker — reached through its own MCP server.

Statuses, comments and new tasks are written back to the system of record, so the aggregate board never becomes a second source of truth.

Scoping

Each project registers its own servers and sees no other project's. Scoping is mechanism, not discipline: a project's agent cannot reach another project's surface because it was never given it.

The surface your agents use

Bottega exposes its own MCP surface, so an agent in any harness can read the board, open a task, file a note or record evidence without a bespoke integration per tool. A worker reaches this machine's MCP servers when the run is dispatched with MCP enabled — which is how it fetches its own context instead of being handed a copy.

Filing what you find

orch note "heartbeat reads clear while a worker sits blocked"
hub note same <id>        # a repeat sighting, not a duplicate row
hub note promote <id>     # a human act — never scheduled

Project, run, branch, session, commit and any file anchor are derived when the note is filed. Repetition with cost is the promotion signal; the board never grows by itself.

Compose, do not copy

Ask for a workflow and you get it resolved for the project you named — the steps from the shared catalogue, the facts from the project register.

orch workflow list
orch workflow compose ship-task --project atlas

Do not paste a workflow into a prompt or a repository file. A pasted copy stops matching the catalogue the moment either changes, and the drift is silent.

What a step declares

• Job — the orch job that runs it, if any. A step with a job routes by scored evidence like any other run.
• Autonomy — auto proceeds; ask stops for a ruling and nothing downstream runs until you give one.
• Evidence floor — what the step must produce: a command exit, a recorded artifact, a human ruling, or a tracker transition.
• Needs — the project capabilities it depends on, such as a trunk, a tracker, a gate or release rules.

Modes

A workflow can stop at different depths. A mode selects how far this run goes — planning only, review only, or ship and promote — without becoming a second workflow that can drift from the first.

Where the knowledge comes from

Documents are served in scopes, and a composed workflow names the ones that apply rather than embedding their text:

• global — rules that hold everywhere.
• stack — what is true of this language or runtime.
• project — this repository's own knowledge, read and written through its MCP surface.

An agent fetches what it needs. The architect naming a source costs one line; pasting that source costs the whole document, on every later turn.

Carrying a task across sessions

Work outlives a context window. Two things carry it, and both are artifacts you can read:

• Task documents hold the specification, the research that settled a decision, and the acceptance criteria — attached to the task key, not to a session.
• Resume briefs are written at a task or epic boundary, and before any clear or compaction: where the work stands, which rulings hold, what is still open, and what must not happen yet.

orch doc list --scope resume
orch doc get <subject>

The catalogue

• Plan a task — turn an intent into a specification with the decisions already ruled.
• Fix a defect — diagnose on evidence, then change one thing.
• Review code — independent lenses under a fixed round budget.
• Ship a task — rebase, review, triage, gate, open, merge, promote, close.
• Report an issue — reproduction, environment, and what is not established.
• Sync the docs — bring the store and the tree back into agreement.

Scopes

Every document has a scope, and the scope decides who is given it:

• global — standards that hold across every project on the machine.
• stack — what applies because of the language or runtime.
• project — this repository's architecture, conventions and domain knowledge.
• job — what a particular kind of work needs to know.
• resume — handoffs between sessions. See context management.

Reading and writing

orch doc list --scope project
orch doc get <subject>
orch doc set --scope project --subject <name> --file <path>

Over MCP the same surface is list_docs, get_doc and set_doc, plus project_brief for the short orientation a worker needs before anything else. An unfiltered listing returns every body, so filter by scope.

Hydration

Some documents are rules that agents read as files in the tree. Those are written into the working copy from the store, never edited in place:

orch canon hydrate

Edit the row in the store, hydrate, then commit what hydrate wrote. A file edited by hand is overwritten at the next hydrate and never becomes the rule.

Revisions

A run records the document revisions it was given. When a result is wrong, you can tell whether the worker misread a good document or faithfully followed a bad one — which are different defects with different fixes.

Keeping it true

The store drifts from the code like any documentation. The sync the docs workflow reconciles them deliberately rather than on a schedule, because a scheduled rewrite of documentation nobody read is how a store fills with confident nonsense.

Context management uses the same doc store, in different places. What changes is where a document is attached and who picks it up.

Task documents

A task carries its own documents: the specification a worker built against, the research that settled a decision, the acceptance criteria. They are attached to the key, so they survive every session that touches the task.

hub task doc new <KEY> --title "Specification"
hub task doc list <KEY>

Epic handoffs

Work larger than one task needs its state written down: what is done, what is next, which rulings already stand. That is a task document with a handoff role, so the next session starts from the decisions instead of re-deriving them — or worse, silently re-deciding them.

hub task doc new <KEY> --role handoff

Resume briefs

A brief is offered at a task or epic boundary, and before any clear or compaction. It records:

• where the work stands;
• which rulings hold, so they are not reopened;
• what is still open and needs a decision;
• what must not happen yet.

orch doc list --scope resume
orch doc get <subject>

Open briefs are listed when a session starts. A session never consumes a brief you did not choose — otherwise it is just another invisible context change with better manners.

Why not rely on compaction

Automatic compaction is a lossy transform applied to your context, usually without showing you what it discarded. It is fine for chat and wrong for work, because the parts most easily dropped — a ruling you gave once, a constraint stated early, the reason an approach was rejected — are exactly the parts whose loss is expensive and silent.

When to write one

• At a task or epic boundary.
• Before clearing or compacting a long session.
• Whenever you are about to hand work to someone — or something — that was not present for the decisions.

Dispatching work

• orch jobs — the job types and the axes each is scored on.
• orch guide — what to use for what, and what is still a guess.
• orch do <job> — dispatch. Detached by default; it prints a run id and returns.
• orch contract <job> — the preamble prepended to that job's prompt.
• orch wait / orch result — collect a detached run.

Escalation

• orch inbox — questions waiting on a ruling.
• orch answer <run> — record the ruling and resume.

Judging

• orch pending — runs you dispatched and have not scored.
• orch score <run> — the verdict, with --void for your own harness errors.
• orch judge <run> — per-finding dispositions for a review.

Projects and state

• orch project list --json — the register: prefixes, landing branches, recipes.
• orch doctor — what is wrong with this installation.
• orch monitor — what is wrong on this machine, with --history.
• orch close-out — release terminal worktrees.

Work tracking

• hub task — create, move and close tasks.
• hub note — keep, promote, drop and merge observations.
• hub serve — the dashboard.