bottega-kit 0.0.0-stage → 0.1.1

package/CHANGELOG.md

@@ -0,0 +1,101 @@
+# Changelog
+
+All notable changes to bottega-kit. Dates are when the version was cut.
+
+## [Unreleased]
+
+## [0.1.1] — 2026-10-23
+
+Documentation only; the commands behave as in 0.1.0.
+
+**Documentation.** The README says why the roles are separate, what to do
+after `run` (read the worktree, `show`, `list`, the four ways on from a stop,
+`pr` on a stopped task, `rm`), what a task costs, and which starter `init`
+writes for each set of CLIs. `docs/process.md` opens with one task followed
+through every command, including the `task.md` it ends with and a task that
+stops. The README and `docs/configuration.md` no longer say every harness
+must report its model: Codex reports none, and its receipts say
+`requested-only`.
+
+**Verification.** `docs/compatibility.md` has a new verified snapshot: one
+live task on 2026-10-23 with Claude Code 2.1.309 and the starter
+configuration, done in round 1, 2.07 USD, then `bottega pr` on GitHub. The
+0.1.0 snapshot is kept below it, marked as not re-run.
+
+## [0.1.0] — 2026-10-23
+
+The first release. A planner, an implementer, a reviewer and an optional judge
+run on Claude Code and Codex in a git worktree, with a receipt for every
+dispatch.
+
+**Tasks and configuration.** `bottega init` writes a starter configuration for
+the harnesses it finds on PATH, and `bottega doctor` checks python3, git, gh,
+the configuration, each role's harness and the environment variables profiles
+reference. A `${NAME}` a profile references is read from your environment or
+from `~/.config/bottega-kit/secrets.env`, one `NAME=value` line each, parsed
+and never executed, refused while anyone but you can read it. `bottega new`
+creates a task: a directory outside the repository
+with `task.md` holding your request verbatim, a worktree beside the repository
+and a `bottega/<task-id>` branch. `show`, `list` and `rm` manage tasks.
+`bottega signal` is the command agents run to report `ready`, `needs-work` or
+`blocked`.
+
+**Planning and approval.** `bottega plan` runs the planner once; its final
+message becomes the plan, or questions you answer inside `task.md` before the
+next `plan`. `bottega approve` checks the plan, gives each to-do item a stable
+`[T<n>]` id, and freezes the plan's hash, the roles and the round cap. The
+`claude` and `codex` drivers keep every flag in one table. A proxied Claude
+profile runs without your Anthropic credentials. Prompts can be overridden
+per user.
+
+**The loop.** `bottega run` alternates the implementer and the reviewer up to
+the cap, then asks the judge if one is bound. It ends done (exit 0) or stopped
+(exit 3) with a reason, and never retries. The reviewer's findings and the
+judge's verdict replace their sections of `task.md`. A planner, reviewer or
+judge that changes tracked code stops the task, and so does a harness that
+reports another model. `bottega resume` continues a stopped task with a fresh
+cap.
+
+**Verified live.** On 2026-10-17 and 2026-10-19 seven tasks ran on two
+throwaway repositories with Claude Code 2.1.302 and 2.1.303 and Codex CLI
+0.163.0, each harness in every role, and `bottega pr` opened a pull request
+on GitHub (`docs/compatibility.md`). The runs found two bugs. A Codex reviewer
+could not find the task by id, because Codex does not pass the orchestrator's
+environment to the agent's shell: `bottega signal` now also accepts the
+absolute task directory, and every prompt names it. A plan with a fenced
+block inside a longer fence lost five lines in the merge: a fence now closes
+only with the same character and at least the same length, as in CommonMark.
+The runs also changed the prompts: the implementer and the reviewer are told
+to give a test suite a long timeout, and that a shell tool handing control
+back while the command runs means wait, not failed. On 2026-10-20 the
+README's proxied profile ran as reviewer: Claude Code 2.1.304 on Z.AI's
+endpoint reported the requested `glm-5.3-flash`, with the key read from
+`secrets.env`.
+
+**Pull requests and packaging.** `bottega pr` commits what is left in the
+worktree, pushes the branch to `origin` and opens the pull request with `gh`.
+It works on a done or a stopped task, and a stopped task's pull request says
+why it stopped. An existing pull request is reported, not duplicated.
+`npx bottega-kit` installs the release that matches the npm package. The
+README and `docs/` describe the process, the configuration and the harness
+flags.
+
+### Known limits
+
+- Verified live on one machine, on three days, with Claude Code 2.1.302 to
+  2.1.304 and Codex CLI 0.163.0, each in every role, and `bottega pr` on a
+  private github.com repository (`docs/compatibility.md`). The Claude Bash
+  deny rules were seen to deny every forbidden command; a 150 s test suite
+  passed under a Claude reviewer and, after a prompt change, under a Codex
+  reviewer that had first given up on it; the Claude `Write` tool created
+  files under `acceptEdits`; a proxied profile on Z.AI ran once, as
+  reviewer, and Claude Code priced it at its own default rate. A GitHub
+  Enterprise host was not exercised; Codex reports no model, so its identity
+  stays `requested-only`.
+- Two harnesses: `claude` and `codex`.
+- A text-patch harness for chat-completion endpoints, and Kimi, Grok and
+  Gemini drivers, are planned for later (`docs/later.md`).
+
+## [0.0.0] — 2026-10-17
+
+- Repository created. Nothing released.

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Matteo Scurati
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/NOTICE

@@ -0,0 +1,44 @@
+bottega-kit
+Copyright (c) 2026 Matteo Scurati
+Licensed under the MIT License (see LICENSE).
+
+This project adapts material from vdaubry/bottega
+(https://github.com/vdaubry/bottega), used under the MIT License.
+bottega-kit takes bottega's process (spec-first planning, a human gate on the
+plan, an implementer and a reviewer alternating over one task document). It
+does not take bottega's platform (web server, database, user interface).
+
+Files adapted from vdaubry/bottega (HEAD 7e5137f, 2026-10-05):
+
+  reference/server/constants/templates/plan-template.md -> templates/task.md
+  reference/server/constants/prompts/planification.md   -> prompts/planner.md
+  reference/server/constants/prompts/implementation.md  -> prompts/implementer.md
+  reference/server/constants/prompts/review.md          -> prompts/reviewer.md
+
+prompts/judge.md is original to bottega-kit.
+
+The vdaubry/bottega licence follows.
+
+--------------------------------------------------------------------------------
+
+MIT License
+
+Copyright (c) 2026 VDA
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,275 @@
-# Temporary Holding Version
+# bottega-kit
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+bottega-kit runs a planner, an implementer, a reviewer and an optional judge on the
+coding agents you already have — Claude Code and Codex today — one role each, in a
+git worktree, with a receipt for every step. You need git, gh, python3 and at least
+one of those CLIs.
+
+Why roles: the agent that reviews the code is not the one that wrote it, and
+it can run on another model or another vendor. You read and approve the plan
+once; after that nothing asks you anything until the task is done or stops,
+and every step is on disk for you to read.
+
+This is not vdaubry/bottega: the process is
+[theirs](https://github.com/vdaubry/bottega); the local, file-based, multi-vendor
+loop is this project.
+
+A task is one plan, which you approve, and then rounds of implementer and
+reviewer until the reviewer is satisfied or the round cap is reached:
+
+```
+bottega new      task directory, worktree and branch; task.md holds your request
+bottega plan     one planner dispatch; may end with questions; repeat until there is a plan
+bottega approve  ids for the to-do items; plan hash, roles and cap recorded
+bottega run      implementer and reviewer, round after round, up to the cap; then the judge
+bottega pr       commit if needed, push to origin, open the pull request
+bottega resume   after a stop, with a fresh cap
+```
+
+A round is one implementer pass and one reviewer pass; the cap is 3 unless
+you change it. Each role runs under a profile from your configuration: a
+harness, which is the CLI that runs the role (`claude` or `codex`), a model
+and an effort. One profile may serve several roles.
+
+## Current release: 0.1.1
+
+Documentation: what to do after `run`, a task followed end to end, what a
+task costs. The commands are those of 0.1.0: `init`, `doctor`, `new`,
+`plan`, `approve`, `run`, `resume`, `pr` and the task commands, on the
+`claude` and `codex` harnesses. 0.1.1 was verified live on 2026-10-23 with
+Claude Code 2.1.309 and the starter configuration, through `bottega pr` on
+GitHub; 0.1.0 was verified with Claude Code 2.1.302 to 2.1.304 and Codex CLI
+0.163.0, each in every role, and a reviewer on Z.AI's endpoint. See
+[docs/compatibility.md](docs/compatibility.md).
+
+## What you need
+
+- git
+- gh, logged in, for `bottega pr`
+- python3 3.9 or newer
+- at least one of `claude` (Claude Code) and `codex` (Codex CLI), logged in
+- node 18 or newer, only for `npx bottega-kit`
+
+## Install
+
+```sh
+npx bottega-kit
+```
+
+This clones the release that matches the npm package, runs its `./install.sh`,
+then `./doctor.sh`, and deletes the clone. `doctor` fails on a new machine
+until you run `bottega init`. Or from a clone:
+
+```sh
+git clone https://github.com/reasance/bottega-kit
+cd bottega-kit
+./install.sh
+```
+
+Both copy the command to `~/.local/share/bottega-kit` and link
+`~/.local/bin/bottega`. `./uninstall.sh`, from a clone, removes them and keeps
+your tasks and configuration.
+
+## Example: Fable plans and judges, Opus implements and reviews
+
+`~/.config/bottega-kit/config.json`, which `bottega init` writes when `claude`
+is on PATH:
+
+```json
+{
+  "schema_version": 1,
+  "profiles": {
+    "fable":         {"harness": "claude", "model": "claude-fable-5-1", "effort": "max"},
+    "opus-builder":  {"harness": "claude", "model": "claude-opus-5-5",  "effort": "high"},
+    "opus-reviewer": {"harness": "claude", "model": "claude-opus-5-5",  "effort": "high"}
+  },
+  "roles": {"planner": "fable", "implementer": "opus-builder",
+            "reviewer": "opus-reviewer", "judge": "fable"},
+  "rounds": 3
+}
+```
+
+With `codex` on PATH as well, `init` also writes a `sol-builder` profile
+(`codex`, `gpt-5.6-sol`, effort `high`) and binds it to no role. With `codex`
+alone, `sol-builder` is the planner, the implementer and the reviewer, and
+there is no judge. Edit the file to bind the roles as you like; `bottega
+doctor` checks it.
+
+The whole sequence, from a repository with an `origin` on GitHub:
+
+```sh
+bottega init
+bottega doctor
+cd your-repo
+echo '{"test_cmd": "make test"}' > bottega.json   # optional: the test command the agents run
+bottega new --title "Add a dry-run flag" --request "Add --dry-run to the export command."
+bottega plan 20261017-0930-add-a-dry-run-flag     # a unique prefix or suffix is enough
+# read task.md; answer any questions in it and run plan again
+bottega approve dry-run-flag
+bottega run dry-run-flag
+# read the changes in the worktree; bottega show dry-run-flag prints where it is
+bottega pr dry-run-flag
+```
+
+`plan` and `run` print one line per dispatch on stdout, and `plan` adds the
+planner's questions when it has any; everything else goes to stderr:
+
+```
+001 planner fable claude-fable-5-1 → planned (2m41s)
+002 implementer opus-builder claude-opus-5-5 → done (6m02s)
+003 reviewer opus-reviewer claude-opus-5-5 → needs-work (2m14s)
+004 implementer opus-builder claude-opus-5-5 → done (3m40s)
+005 reviewer opus-reviewer claude-opus-5-5 → ready (1m55s)
+006 judge fable claude-fable-5-1 → ready (48s)
+```
+
+`pr` prints the pull request's URL, or `pr exists: <url>`.
+[docs/process.md](docs/process.md#a-task-end-to-end) follows one task
+through every command, with the `task.md` it ends with.
+
+## After `run`
+
+`bottega show <task>` prints the worktree, the branch and the path of
+`task.md`, then the phase, the round, the last signal, why the task stopped,
+and one line per dispatch. `bottega list` prints every task and its phase.
+
+**Done** (exit 0). Read the work before you open the pull request. The
+changes are in the worktree, uncommitted: `git status` and `git diff` there,
+and new files are untracked until `pr` commits them. `task.md` holds the
+reviewer's `## Review Findings` and the judge's `## Verdict`. Then
+`bottega pr`.
+
+**Stopped** (exit 3). `run` prints the reason, the receipt of the dispatch
+that stopped it and the resume command; `show` prints them again. Then one
+of:
+
+- `bottega resume <task>`: the same plan, a fresh cap. After `cap-reached` or
+  `judge-needs-work` a new round starts with the implementer; after any other
+  stop the role that stopped runs again.
+- Edit the plan in `task.md`, `bottega approve` it again and `bottega run`:
+  the ids are kept and the loop starts over at round 1. After `blocked`, the
+  reviewer's findings say what is missing.
+- `bottega pr` anyway: the pull request's body starts with the stop reason.
+- `bottega rm <task>`: removes the worktree and the branch. The task
+  directory and its receipts stay.
+
+## What a task costs
+
+You pay your providers; bottega-kit adds nothing. Each Claude Code dispatch's
+cost, as Claude Code reports it, is `cost_usd` in its `run.json`. Codex
+reports none: its usage goes to your ChatGPT plan. For scale, on 2026-10-23
+the starter configuration above added an option to a 21-line Python CLI in
+one round: four dispatches, 2.07 USD and under five minutes, three quarters
+of it the Fable planner and judge. In the 0.1.0 runs, Sonnet at effort
+`medium` cost 0.03 to 0.08 USD a dispatch on the same kind of task. A larger
+task costs more: more files to read, more rounds.
+[docs/compatibility.md](docs/compatibility.md) lists every dispatch of the
+live runs.
+
+## Example: three vendors, no judge
+
+The planner on Claude Code, the implementer on Codex, the reviewer on Claude
+Code pointed at Z.AI's Anthropic-compatible endpoint:
+
+```json
+{
+  "schema_version": 1,
+  "profiles": {
+    "fable":        {"harness": "claude", "model": "claude-fable-5-1", "effort": "max"},
+    "sol-builder":  {"harness": "codex",  "model": "gpt-5.6-sol",     "effort": "high"},
+    "glm-reviewer": {"harness": "claude", "model": "glm-5.3-flash",   "effort": "max",
+                     "env": {"ANTHROPIC_BASE_URL": "https://api.z.ai/api/anthropic",
+                             "ANTHROPIC_AUTH_TOKEN": "${ZAI_API_KEY}",
+                             "ANTHROPIC_DEFAULT_OPUS_MODEL": "glm-5.3-flash"},
+                     "aliases": ["opus"]}
+  },
+  "roles": {"planner": "fable", "implementer": "sol-builder",
+            "reviewer": "glm-reviewer"},
+  "rounds": 3
+}
+```
+
+`${ZAI_API_KEY}` is read when the reviewer runs, from your environment or
+from `~/.config/bottega-kit/secrets.env` (one `NAME=value` line each, mode
+600, parsed and never executed); `doctor` and `approve` refuse while it is set
+in neither. Because `ANTHROPIC_BASE_URL` is set, the reviewer runs with a fresh
+Claude configuration directory and without your Anthropic credentials.
+`aliases` lists other names the endpoint may report for the model; any other
+name stops the run as `identity-mismatch` (on 2026-10-20 Z.AI reported
+`glm-5.3-flash`, the requested name, so the alias went unused). To change one
+role for one task only, pass `--role implementer=sol-builder` to `bottega new`.
+
+## The roles
+
+| role | what it does | what it may change | its product |
+|---|---|---|---|
+| planner | reads the repository and the request, writes the plan or asks questions | nothing | its final message becomes the plan in `task.md` |
+| implementer | works through the unchecked to-do items, adds tests, ticks items | the worktree and the boxes in `task.md`; never commits or pushes | a summary, kept in the receipt |
+| reviewer | checks every ticked item, runs the tests and the manual QA scenarios | nothing it keeps: a changed tracked file stops the task | `## Review Findings` and a signal: `ready`, `needs-work` or `blocked` |
+| judge | optional; reads the plan and the diff, says whether to merge | nothing | `## Verdict` and a signal: `ready` or `needs-work` |
+
+Agents report back by running `bottega signal`. bottega-kit decides what
+happens next from that signal and the files on disk, never from the agent's
+prose. [docs/process.md](docs/process.md) has the loop step by step.
+
+## Exit codes
+
+| code | meaning |
+|---|---|
+| 0 | done |
+| 2 | refused: wrong phase, plan changed since approval, invalid configuration, a binding that no longer works, task locked |
+| 3 | stopped: `blocked`, `cap-reached`, `judge-needs-work`, `dispatch-failed`, `timeout`, `identity-mismatch`, `role-modified-worktree`, `interrupted` |
+| 64 | bad invocation |
+
+A stopped task continues with `bottega resume <task> [--rounds N]`.
+
+## Where things live
+
+- Configuration: `~/.config/bottega-kit/config.json`, and prompt overrides in
+  `~/.config/bottega-kit/prompts/`.
+- Tasks: `~/.local/share/bottega-kit/tasks/<project>/<task-id>/`, holding
+  `task.md`, `state.json` and one receipt directory per dispatch under `runs/`.
+  They live outside the repository, so they outlive the worktree.
+- The worktree: `<repo>-worktrees/<task-id>/`, beside the repository, on the
+  branch `bottega/<task-id>`. `bottega rm` removes it and the branch.
+- A repository may hold `bottega.json` with `test_cmd` and `base`.
+
+[docs/configuration.md](docs/configuration.md) covers every setting.
+
+## What bottega-kit never does
+
+- Retry a failed dispatch, fall back to another model, or substitute a profile.
+- Bring a model of its own. Every dispatch runs a profile you bound. Claude
+  Code reports the model it ran, and it must be the one you asked for; Codex
+  reports none, so its receipts say `requested-only` and rest on the request.
+- Put a secret in its configuration, its prompts, a task or a receipt.
+  Profiles name environment variables; the key file you keep at mode 600 may
+  hold their values; receipts record names, never values.
+- Merge, or push anywhere but `origin`.
+- Let the planner, the reviewer or the judge change your code: their runs are
+  checked against the worktree before and after.
+
+## Not vdaubry/bottega
+
+[vdaubry/bottega](https://github.com/vdaubry/bottega) is a web platform with a
+server, a database and a UI. bottega-kit took its process: the spec-first task
+document, the planner, implementer and reviewer prompts, the plan template,
+the "agents signal with a command" rule, the review cap with no unreviewed fix
+pass, and one worktree per task. It did not take the platform. The judge
+role, the profiles across vendors and the receipts are this project's. See
+`NOTICE` for the files adapted.
+
+## Documentation
+
+- [docs/process.md](docs/process.md): the loop, rounds, resume, signals,
+  receipts, rails.
+- [docs/configuration.md](docs/configuration.md): profiles, roles,
+  `bottega.json`, prompt overrides, environment variables.
+- [docs/compatibility.md](docs/compatibility.md): what each harness is run
+  with, and what has been verified.
+- [docs/later.md](docs/later.md): what is not built yet.
+
+## Licence
+
+MIT. The process and parts of the prompts and the template come from
+[vdaubry/bottega](https://github.com/vdaubry/bottega), also MIT; see `NOTICE`.

package/bin/npm-installer.mjs

@@ -0,0 +1,183 @@
+#!/usr/bin/env node
+// bottega-kit npm installer: a thin wrapper over the repository's ./install.sh.
+//
+// `npx bottega-kit` clones https://github.com/reasance/bottega-kit at the
+// tag that matches this package's own version (bottega-kit--v<version>), runs
+// ./install.sh from the clone, then ./doctor.sh, then deletes the clone.
+// install.sh copies what it installs into BOTTEGA_DATA_HOME and records the
+// repository and ref (never the temporary path) in installed-version.json, so
+// nothing installed points at the deleted clone.
+//
+// Usage:
+//   npx bottega-kit [--ref <tag-or-branch>] [--repo <git-url>] [--skip-doctor]
+//
+// Environment: BOTTEGA_DATA_HOME and BOTTEGA_BIN_HOME, as for ./install.sh.
+// The wrapper never writes a configuration and never handles credentials.
+
+import { spawnSync } from "node:child_process";
+import { mkdtempSync, readFileSync, rmSync, statSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import process from "node:process";
+
+const DEFAULT_REPO = "https://github.com/reasance/bottega-kit";
+const TAG_PREFIX = "bottega-kit--v";
+const USAGE =
+  "usage: npx bottega-kit [--ref <tag-or-branch>] [--repo <git-url>] [--skip-doctor]";
+const REQUIRED = [
+  "install.sh",
+  "doctor.sh",
+  "bin/bottega",
+  "bin/lib/bottega/version.py",
+];
+
+class WrapperError extends Error {
+  constructor(message, code = 1) {
+    super(message);
+    this.code = code;
+  }
+}
+
+function packageVersion() {
+  const text = readFileSync(new URL("../package.json", import.meta.url), "utf8");
+  return JSON.parse(text).version;
+}
+
+function parseArgs(argv) {
+  const options = { ref: null, repo: null, skipDoctor: false, help: false };
+  for (let i = 0; i < argv.length; i += 1) {
+    const arg = argv[i];
+    const [name, inline] = arg.startsWith("--") && arg.includes("=")
+      ? [arg.slice(0, arg.indexOf("=")), arg.slice(arg.indexOf("=") + 1)]
+      : [arg, null];
+    switch (name) {
+      case "--ref":
+      case "--repo": {
+        const value = inline ?? argv[i + 1];
+        if (inline === null) i += 1;
+        if (!value || value.startsWith("--")) {
+          throw new WrapperError(`${name} needs a value\n${USAGE}`, 64);
+        }
+        options[name.slice(2)] = value;
+        break;
+      }
+      case "--skip-doctor":
+        options.skipDoctor = true;
+        break;
+      case "-h":
+      case "--help":
+        options.help = true;
+        break;
+      default:
+        // install.sh takes no arguments, so nothing is forwarded to it.
+        throw new WrapperError(`unknown argument: ${arg}\n${USAGE}`, 64);
+    }
+  }
+  return options;
+}
+
+function run(command, args, options = {}) {
+  const result = spawnSync(command, args, { stdio: "inherit", ...options });
+  if (result.error) {
+    throw new WrapperError(`could not run ${command}: ${result.error.message}`);
+  }
+  return result;
+}
+
+function requireGit() {
+  const probe = spawnSync("git", ["--version"], { stdio: "ignore" });
+  if (probe.error || probe.status !== 0) {
+    throw new WrapperError("git is required", 69);
+  }
+}
+
+function clone(repo, ref, dir) {
+  const result = run(
+    "git",
+    ["clone", "--quiet", "--depth", "1", "--branch", ref, repo, dir],
+    { stdio: ["ignore", "ignore", "pipe"], encoding: "utf8" },
+  );
+  if (result.status !== 0) {
+    const detail = (result.stderr || "").trim();
+    throw new WrapperError(
+      `could not clone ${repo} at ${ref}${detail ? `:\n${detail}` : ""}`,
+    );
+  }
+}
+
+function checkCheckout(dir, expectedVersion, ref) {
+  for (const file of REQUIRED) {
+    let ok = false;
+    try {
+      ok = statSync(join(dir, file)).isFile();
+    } catch {
+      ok = false;
+    }
+    if (!ok) {
+      throw new WrapperError(`${ref} has no ${file}; it is not a bottega-kit release`);
+    }
+  }
+  const text = readFileSync(join(dir, "bin/lib/bottega/version.py"), "utf8");
+  const found = /^__version__ = "([^"]+)"$/m.exec(text)?.[1];
+  if (expectedVersion && found !== expectedVersion) {
+    throw new WrapperError(
+      `${ref} holds bottega-kit ${found ?? "(no version)"}, not ${expectedVersion}`,
+    );
+  }
+}
+
+function main() {
+  const options = parseArgs(process.argv.slice(2));
+  if (options.help) {
+    console.log(USAGE);
+    return 0;
+  }
+  requireGit();
+  const version = packageVersion();
+  const repo = options.repo ?? DEFAULT_REPO;
+  const ref = options.ref ?? `${TAG_PREFIX}${version}`;
+  const parent = mkdtempSync(join(tmpdir(), "bottega-kit-"));
+  const checkout = join(parent, "bottega-kit");
+  try {
+    console.log(`bottega-kit: installing ${ref} from ${repo}`);
+    clone(repo, ref, checkout);
+    // Only the default tag must match this package; --ref is the user's choice.
+    checkCheckout(checkout, options.ref ? null : version, ref);
+    const env = {
+      ...process.env,
+      BOTTEGA_INSTALL_SOURCE: repo,
+      BOTTEGA_INSTALL_REF: ref,
+    };
+    const install = run("./install.sh", [], { cwd: checkout, env });
+    if (install.status !== 0) {
+      throw new WrapperError(
+        `install.sh exited with ${install.status}`,
+        install.status ?? 1,
+      );
+    }
+    if (options.skipDoctor) {
+      return 0;
+    }
+    const doctor = run("./doctor.sh", [], { cwd: checkout, env });
+    if (doctor.status !== 0) {
+      console.error(
+        `bottega-kit: installed, but doctor reported problems (exit ${doctor.status}). ` +
+          "A new install has no configuration yet: run bottega init, then bottega doctor.",
+      );
+      return doctor.status ?? 1;
+    }
+    return 0;
+  } finally {
+    rmSync(parent, { recursive: true, force: true });
+  }
+}
+
+let code;
+try {
+  code = main();
+} catch (error) {
+  if (!(error instanceof WrapperError)) throw error;
+  console.error(`bottega-kit: ${error.message}`);
+  code = error.code;
+}
+process.exit(code);

package/package.json

@@ -1,6 +1,39 @@
 {
   "name": "bottega-kit",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.1.1",
+  "description": "A planner, an implementer, a reviewer and an optional judge on the coding agents you already have, in a git worktree, with a receipt for every step.",
+  "keywords": [
+    "claude-code",
+    "codex",
+    "coding-agents",
+    "git-worktree",
+    "developer-tools"
+  ],
+  "author": {
+    "name": "Matteo Scurati",
+    "url": "https://github.com/matteoscurati"
+  },
+  "homepage": "https://github.com/reasance/bottega-kit#readme",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/reasance/bottega-kit.git"
+  },
+  "bugs": {
+    "url": "https://github.com/reasance/bottega-kit/issues"
+  },
+  "license": "MIT",
+  "type": "module",
+  "bin": {
+    "bottega-kit": "./bin/npm-installer.mjs"
+  },
+  "files": [
+    "bin/npm-installer.mjs",
+    "README.md",
+    "LICENSE",
+    "NOTICE",
+    "CHANGELOG.md"
+  ],
+  "engines": {
+    "node": ">=18"
+  }
+}