breakaway 1.4.0-main.7 → 1.4.0-main.71

package/.agents/skills/pipeline/SKILL.md

@@ -0,0 +1,127 @@
+---
+name: pipeline
+description: Use when a task asks to move a repository's CI/CD to breakaway's deploy flow or release flow (Move to breakaway's deploy flow, Deploy with breakaway, Release with breakaway), to write or change .github/breakaway-pipeline.json, to run npx breakaway pipeline init or pipeline check, or to map an old deploy or npm publish workflow onto Deploy, Promote, Roll back, and Release.
+---
+
+# Moving a repository to the deploy flow
+
+A move is one task and one pull request: you read how the repository checks, deploys, and publishes today, write `.github/breakaway-pipeline.json`, render the workflows from it with `npx breakaway pipeline init`, and account for every step of the old setup, so nothing is lost and nothing runs twice. The design is the [move's spec](../../../docs/specs/IDEA-27-move-ci-cd-to-the-deploy-flow.md) (sections 2, 2b, and 3), and the [docs](../../../docs/tasks.md#moving-a-repository-to-the-deploy-flow) say what the flows do.
+
+It is an ordinary build: claim, check in on the peloton, and hand over the way the repository's prompt and the `tasks` skill say. This skill is how to do the move itself.
+
+**You never** deploy, publish, run or re-run a workflow, touch Cloudflare, npm, or the repository's GitHub settings (environments, secrets, variables, the App's permissions), or set the repository's pipeline on the board (`repos modify --pipeline` and **Turn on deploys** are the owner's). You write files in a pull request; the owner does the rest.
+
+## 1. Read what's there
+
+Read all of it before you decide anything:
+
+- **Workflows**, `.github/workflows/*.yml`: each one's `name:` line, its triggers (`push`, `pull_request`, `workflow_run`, `release`, `workflow_dispatch`, `schedule`), and every job and step. Note which steps check (lint, test, build, typecheck), which deploy (`wrangler deploy`, `wrangler versions upload`, `cloudflare/wrangler-action`), which publish (`npm publish`, or pnpm's or yarn's, `JS-DevTools/npm-publish`, a `release` event), and which do something else (a migration, a cache purge, a notification, a manual approval through an `environment` with reviewers).
+- **Wrangler config**, `wrangler.jsonc`, `wrangler.json`, or `wrangler.toml`: the Worker's `name`, its `env` blocks (each one's name, and the Worker name it deploys as), and its bindings, above all D1 databases and their `migrations_dir`.
+- **Migrations**: the folder and how they're applied today (`wrangler d1 migrations apply`, a script).
+- **`package.json`**: `name`, `version`, `private`, `scripts` (`build`, `test`, `deploy`, `release`, `prepublishOnly`), `publishConfig`, and `workspaces`; and the lockfile, which says the install command (`npm ci` for `package-lock.json`, or pnpm's or yarn's frozen install for theirs).
+- **Versioning tools**: `.changeset/`, `release-please-config.json`, `.releaserc*` or a `release` key in `package.json` (semantic-release), and `lerna.json`.
+- **Anything already at the flow's paths**: `.github/breakaway-pipeline.json`, `.github/deploy-paths.json`, and `deploy.yml`, `promote.yml`, `rollback.yml`, or `release.yml` in `.github/workflows/`.
+- **Scripts the workflows run**, in `scripts/` or `package.json`: what each does, so you know whether `beforeDeploy` can run it.
+
+## 2. Decide what moves
+
+| The repository today | What you do |
+| --- | --- |
+| Deploys a Worker with `wrangler`, from Actions, Workers Builds, or by hand | Move it: `workers` in the config. |
+| Has checks but deploys by hand | Move it: the deploy is new, and the checks stay as they are. |
+| Publishes a package to npm, from Actions or by hand | Move it: `package` in the config. |
+| Deploys a Worker and publishes a package | Both, in one config and one pull request. |
+| Publishes to another registry (GitHub Packages, JSR, PyPI) | That publishing stays as it is. Say so in the pull request; move a Worker deploy if there is one. |
+| Deploys somewhere else (Pages, Vercel, Fly, a server, containers) | Stop (below). breakaway's deploy flow runs Cloudflare Workers only; a deploy command of the repository's own is planned, not built. |
+| `package.json` says `"private": true` and nothing deploys | Stop: there is nothing the flows can take. |
+
+The first version takes **one staging and one production Worker** and **one package** per repository. With more Workers, move the pair the task names (or that the old deploy targets on the default branch), and leave the others' deploys as they are, saying so. With several publishable packages (a monorepo), move the one the task names (or ask, below), and leave the others' publishing as it is.
+
+**Stopping** means changing nothing and opening no pull request: `comment` on the task what you found and why it doesn't move (the row above, in a sentence the owner can act on), then `release` it. When only the owner can choose (which package, which Worker pair, or what to do with a versioning tool), ask with a decision instead (the core's "Asking for a decision") and release.
+
+## 3. Write the config
+
+`.github/breakaway-pipeline.json` is the repository's own. Every value comes from what you read, never invented:
+
+```json
+{
+  "workers": { "staging": "widgets-staging", "production": "widgets" },
+  "wranglerEnv": { "staging": "staging", "production": "production" },
+  "branch": "main",
+  "checks": ["CI"],
+  "install": "npm ci",
+  "build": "npm run build",
+  "beforeDeploy": ["npx wrangler d1 migrations apply DB --remote --env $BREAKAWAY_ENV"],
+  "deployPaths": { "widgets": "^(src|public|migrations)/|^wrangler\\.jsonc$|^package(-lock)?\\.json$" },
+  "healthCheck": { "staging": "https://widgets-staging.example.workers.dev/", "production": "https://widgets.example.com/" },
+  "package": { "name": "widgets", "directory": ".", "access": "public" }
+}
+```
+
+- **`workers`**: the staging and production Worker names, as the wrangler config deploys them (with its `env` blocks, the name each environment deploys as). Two different Workers. A repository with only production today needs a staging Worker: name it `<production>-staging`, and the owner creates it (the checklist).
+- **`wranglerEnv`**: only when the wrangler config has `env` blocks; the environment name for each Worker, passed as `--env`.
+- **`branch`**: the default branch, when it isn't `main`.
+- **`checks`**: the `name:` line of each workflow that must pass before a deploy or a release, exactly as written. Every check the old deploy waited for, and the ones that run on push to the default branch. Never a workflow you're about to remove.
+- **`install`, `build`**: the repository's own one-line commands, from its old workflow or lockfile. Leave `build` out when nothing builds.
+- **`beforeDeploy`**: the old deploy's steps before `wrangler deploy` (migrations first), one command each. They read `$BREAKAWAY_ENV` (`staging` or `production`) and `$WORKER`. A step that needs more than one line goes in a script the command runs; a step that can't run there stays where it is (step 5).
+- **`deployPaths`**: per Worker, a regular expression of the paths whose change needs a deploy: its source, static assets, migrations, the wrangler config, and the package and lockfile. The board reads the same patterns to say "No deploy needed", so a path left out never ships and a path put in too many deploys for nothing. You can't prove them from reading, so the pull request lists each part and what it covers (step 6).
+- **`healthCheck`**: an address the old workflow or the README checks after a deploy, as a string (staging only) or `{ "staging", "production" }`. Leave it out when there is none; never guess one.
+- **`package`**: `name` exactly as its `package.json` says, `directory` its folder (`.` at the root), and `access` (`restricted` only when `publishConfig.access` or the old publish says so; a scoped package published `public` today stays `public`). Its `package.json` needs a plain `X.Y.Z` version: the flow counts from it. A repository that only publishes has no `workers`, `deployPaths`, `healthCheck`, `beforeDeploy`, or `wranglerEnv`.
+
+**A versioning tool with its own scheme** (changesets, semantic-release, release-please) decides versions from commits or changeset files; the release flow takes `package.json`'s version and stages `X.Y.Z-main.N` on `next` for every merge. They can't both run, and one can't be mapped onto the other. Don't replace it: ask the owner with a decision (keep the tool and move only the Worker deploy; or drop the tool for the release flow, which a later task does), and stop the package part until it's answered. Move a Worker deploy in the meantime only if the decision says to.
+
+## 4. Render the workflows
+
+In the checkout, run `npx breakaway pipeline init`. It checks the config, naming the field that's wrong and what it should be, and the rendered workflows (YAML, pinned actions, expressions, secrets only in an environment), and writes nothing if either fails. It writes `.github/workflows/deploy.yml`, `promote.yml`, `rollback.yml`, and `.github/deploy-paths.json` for `workers`, and `.github/workflows/release.yml` for `package`. Never edit what it writes: change the config and run it again.
+
+- **It refuses a file already there** that it didn't render. When that file is the old deploy or publish workflow you're replacing, delete it in this pull request (step 5) and run `pipeline init` again. When it's something else that only shares the name, stop and ask the owner with a decision: never rename or overwrite it silently.
+- **It names helper scripts the repository lacks** (`scripts/record-deployment.mjs` and the others). `repos init <slug> --update` copies them, and that is the owner's: say so under **After merging** (the workflows fail without them), unless they're already there.
+- **`npx breakaway pipeline check`** passes before you hand over: the config is sound, and the files are what it renders now.
+
+## 5. Nothing lost, nothing twice
+
+Every old job and step ends up in exactly one place: the config, a rendered workflow, kept where it was, or dropped with the reason. The rules:
+
+- **Checks are the repository's own.** Never edit or remove a workflow that checks. Deploy and Release wait for them by name.
+- **A workflow that only deploys or only publishes** comes out in the same pull request, deleted, or with its trigger on the default branch removed when it also runs for something else (a tag, by hand, a preview on pull requests, which stays). Otherwise the merge deploys or publishes twice.
+- **A workflow that checks and deploys, or checks and publishes**, is split: its checks stay as they are, and the deploy or publish job or steps come out (with the `needs:`, `if:`, permissions, and `environment` only they used). If its deploy job is all that runs on push to the default branch, drop that trigger too, so the checks still run where they did.
+- **Workers Builds** (Cloudflare's git integration) deploys from Cloudflare, not from a file: you can't turn it off. Say under **After merging** that the owner disconnects it before merging, or the merge deploys twice.
+- **A step the flow can't do** (a manual approval, a custom deploy script `beforeDeploy` can't run, a notification, a cache purge, publishing to another registry) stays exactly where it is, and the pull request lists it under **After merging** for the owner to decide. Never invent an equivalent.
+- **Publishing by hand** (a `release` or `publish` script someone runs from a laptop) stays in `package.json`; the pull request says the release flow replaces it and the owner stops running it.
+- **Never** add or change a secret, an environment, or a variable, and never put a token in a file.
+
+## 6. The pull request
+
+Open it the way the repository's prompt's **Pull requests** says, closing the task. Its description holds, besides what that asks:
+
+- **What moves**: the row from step 2, the Workers, and the package.
+- **Step by step**: a table of every old workflow, job, and step, and where each went:
+
+  | Old | Was | Now |
+  | --- | --- | --- |
+  | `deploy.yml` · deploy | `wrangler deploy` on push to `main` | Deploy (`deploy.yml`, rendered) after CI passes; the old file is removed |
+  | `ci.yml` · test | `npm test` | Kept as it is; Deploy and Release wait for CI |
+  | `ci.yml` · publish | `npm publish` on a tag | Release (`release.yml`): `next` on every merge, `latest` on the owner's Release; the step is removed |
+  | `deploy.yml` · migrate | `wrangler d1 migrations apply` | `beforeDeploy` |
+  | `deploy.yml` · notify | posts to chat | Kept where it was (After merging) |
+
+- **Deploy paths**: each pattern's parts and what they cover, so the owner can check them.
+- **After merging**: the owner's checklist below, the steps kept where they were, and anything you stopped short of.
+
+**The owner's part comes before the merge.** The merge itself runs Deploy and Release once its checks pass, so without the owner's part both fail. Add a `+owner` task for it, filled in like any task, with the checklist in its brief and only what this repository needs. It doesn't depend on the move task (it comes first), and the pull request's **After merging** repeats it under "Before you merge":
+
+- the staging and production Workers (or confirm the existing ones), and a Cloudflare API token for each;
+- the GitHub environments `staging` and `production`, each with its token as `CLOUDFLARE_API_TOKEN` and restricted to the default branch, and the repository variable `CLOUDFLARE_ACCOUNT_ID`;
+- read and write on **Actions** for the board's GitHub App on the repository (Promote, Roll back, and Release start workflows);
+- the helper scripts, with `repos init <slug> --update`, when `pipeline init` named any;
+- Workers Builds disconnected, when the repository used it;
+- for a package: the GitHub environment `npm`, restricted to the default branch; on npm, a trusted publisher for `release.yml` and the `npm` environment, or a granular `NPM_TOKEN` in that environment that can't bypass 2FA; and, after each run, approving the staged version on npm with 2FA (`npm stage approve <id>`, or Staged Packages on npmjs.com). The board shows what waits and never approves;
+- optional: the repository variable `DEPLOYS_PAUSED` (`true` stops Promote and Release), and the health-check addresses;
+- after the merge, **Turn on deploys** on the repository's GitHub page, which sets its pipeline from the files.
+
+## Before handing over
+
+- `npx breakaway pipeline check` passes.
+- The repository's own checks pass, and every workflow you changed still parses and runs the jobs it ran before, minus what moved.
+- Every old step is in the table, and no deploy or publish is left that the merge would run besides Deploy and Release.
+- No secret, token, or address you didn't read in the repository is in a file, the task, or the pull request.

package/.agents/skills/tasks/SKILL.md

@@ -31,6 +31,7 @@ breakaway's work is on the board that tracks this repository. The CLI is `npx br
 | You need the owner to choose | Ask with a decision, not prose: `add "<title>" --tag owner --decision <file.json>` and make the work that waits `--depends` on it. Only the owner answers, on the board; read the answers with `show`. |
 | Part of the work needs the owner (an install, a dashboard, a sign-off) | Finish your part, then `add` a `+owner` task for the rest that `--depends` on yours. |
 | Task needs design choices | Write the spec in `docs/specs/<ID>-<slug>.md` and `modify <ID> --spec <path>`. |
+| Reading the repository's specs | `tasks specs` lists them, newest first, with each one's status and its tasks; `specs show <path>` prints one with the tasks that link it. They're read from GitHub's default branch, so a spec still in a pull request isn't there yet. |
 | You're blocked by another task | `comment` why, `release`, and pick the blocker or another task. |
 | A claim looks abandoned | Ask the owner; don't take it. |
 | Opening a pull request for a spec, plan, or partial step | Write `Part of <ID>.`, not `Closes`, and don't put it in `--pr`: merging the pull request in that field finishes the task. A branch name alone never closes anything. |
@@ -38,6 +39,7 @@ breakaway's work is on the board that tracks this repository. The CLI is `npx br
 | `claim` says the task belongs to another repository | Don't cross it with `--repo`: that work belongs in a checkout of its own repository. `comment` and `release` if the board started you on it. |
 | The board started you | Follow [`prompts/breakaway.md`](../../../prompts/breakaway.md), which starts with the core. Check the payload's `Repository:` line against `git remote get-url origin` first. |
 | The task is an `IDEA-` | Shape it, don't build it: "Shaping an idea" in the core. |
+| The board started you on a kickoff (`Mode: kickoff`) | Interview the owner first: ask plain questions as a decision on the IDEA (at most 12, then at most 6 more if something important is open), `release`, and stop; once they're answered, shape it with `AGENTS.md`, the prompt's sections, an **In short**, and a `<slug>-v1` feature. "Kicking off a project" in the core. |
 | The board started you from the owner's prompt (`Mode: general`) | Give the task an area first (`modify <ID> --project <area>` gives it its work ID), retitle it, and take the smallest path: a pull request, board edits noted on each task, a spec, a task in another repository, or a decision or ping. Releasing it with no pull request closes it. "Running a general agent" in the core. |
 | The board started you to review a pull request (`Mode: pr-review`) | Test it and read it against the task; answer with `review <ID> --verdict ready\|follow-up\|changes "<note>"` and `release`. Never push or merge. "Reviewing a pull request" in the core. |
 | Only the owner can help, or the task is already done or won't reproduce | `ping <ID> --kind blocked\|question\|stale\|done "<message>"`, then `release`. Ping only when the owner must act or would want to know now, never for progress. Full rules: "Pinging the owner" in the core. |

package/README.md

@@ -52,7 +52,7 @@ Rather do it by hand? [The self-hosting guide](https://github.com/TheAnarchoX/br
   <img alt="Agents claim the work. You merge it. In three steps: an agent, claude-brk-12, claims the task BRK-12; it opens a pull request that says Closes BRK-12.; you merge, and the task is done." src="https://raw.githubusercontent.com/TheAnarchoX/breakaway/main/docs/media/how-dark.png" width="100%">
 </picture>
 
-1. **Write the work down.** Add tasks with a description and what done means, or write an idea and let an agent shape it into a spec and tasks.
+1. **Write the work down.** Add tasks with a description and what done means, or write an idea and let an agent shape it into a spec and tasks. Starting something with no repository yet? **Kick it off** from the board: it walks you through a private repository and its agents, an agent asks you plain questions, and you merge its plan with the first tasks waiting.
 2. **Agents claim it.** A claim is atomic, so two agents never work the same task. Start Claude Code cloud agents from the board, or let local Claude Code sessions pick up work through the CLI.
 3. **Pull requests close tasks.** A pull request that says `Closes BRK-12.` puts the task in review. The task is done when you merge it.
 4. **They ping you when they're stuck.** An agent that needs you sends a ping to your inbox. The rest waits on the board.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "breakaway",
-  "version": "1.4.0-main.7",
+  "version": "1.4.0-main.71",
   "description": "The task board for you and your coding agents: a Cloudflare Worker, its web app, Taskwarrior sync, and the CLI (npx breakaway).",
   "license": "FSL-1.1-Apache-2.0",
   "type": "module",
@@ -21,18 +21,22 @@
     "!scripts/install/*.test.js",
     "src/cli-version.js",
     "src/decision.js",
+    "src/init.js",
     "src/install.js",
     "src/model.js",
+    "src/packages.js",
     "src/ping.js",
     "src/promote.js",
     "src/prompt.js",
     "src/redact.js",
     "src/repos.js",
+    "src/session-report.js",
     "src/specs.js",
     "src/versions.js",
     "prompts/*.md",
     "taskrc",
     ".agents/skills/tasks/SKILL.md",
+    ".agents/skills/pipeline/SKILL.md",
     "template"
   ],
   "engines": {
@@ -48,15 +52,16 @@
   },
   "scripts": {
     "dev": "vite",
-    "build": "vite build",
-    "test": "vitest run && vitest run --config scripts/tasks/vitest.config.js",
+    "prepare": "node scripts/board-files.mjs",
+    "build": "node scripts/board-files.mjs && vite build",
+    "test": "node scripts/board-files.mjs && vitest run && vitest run --config scripts/tasks/vitest.config.js",
     "brand": "node scripts/brand-lint.mjs",
     "format": "biome format --write .",
     "lint": "biome check .",
-    "typecheck": "wrangler types && tsc -p tsconfig.json && tsc -p scripts/tsconfig.json && tsc -p web/tsconfig.json",
+    "typecheck": "node scripts/board-files.mjs && wrangler types && tsc -p tsconfig.json && tsc -p scripts/tsconfig.json && tsc -p web/tsconfig.json",
     "site": "node site/build.mjs",
     "interop": "node interop.mjs",
-    "deploy": "vite build && wrangler deploy -c wrangler.jsonc"
+    "deploy": "node scripts/board-files.mjs && vite build && wrangler deploy -c wrangler.jsonc"
   },
   "devDependencies": {
     "@biomejs/biome": "2.5.15",

package/prompts/add-repository.md

@@ -31,11 +31,12 @@ Every `npx breakaway` command the owner runs for these steps (`agents-connect`,
 2. **Install the board's GitHub App** on it (its name is the `app` field of the setup answer, `repos setup --json`; don't assume one), and **turn on Allow auto-merge** (Settings, General, Pull Requests). Both are the owner's, on GitHub. The board sees the repository only once the App is installed, so step 1 ticks with this one.
 3. **Register it**: the owner's. Give them the command for their own terminal, `npx breakaway repos add <slug> <owner/name> --area <area>:<PREFIX>`, with areas and prefixes you've agreed with them (2 to 8 capital letters, not used by any other repository: check `repos` first), or point them to the wizard's form, which checks for clashes as they type. The default branch is read from GitHub when none is given. Never run `repos add`, `repos modify`, or `repos remove` yourself: the board refuses them from an agent anyway.
 4. **Add the board's files**: `npx breakaway repos init <slug>`, in the owner's own terminal (from the board's checkout; it pushes the first commit, or opens a pull request on a repository that has commits). It asks for each section of the agent prompt (Building, Checks, Pull requests, Direction, Dependency updates, Never share), and Enter takes a plain default. Go through the sections with the owner first if they'd like, and hand them the command with the answers as flags (`--building`, `--checks`, `--pull-requests`, `--direction`, `--dependency-updates`, `--never-share`, each with its text in quotes). You may run `npx breakaway repos init <slug> --dry-run` to show what it would add. Then clone the repository next to this checkout if init didn't (`../<slug>`).
-5. **Check the agent prompt and fill in `AGENTS.md`** in the new repository. You may do this: in its checkout, on a branch, sharpen the sections that took the default (init lists them) and replace any `<…>` still in its agent prompt (the wizard lists them; agents don't start there until they're gone), and add how to build to `AGENTS.md`, from what the owner tells you and what you find in the repository. Open a pull request in that repository and leave the merge to the owner. Ask when you don't know a section's answer; never invent a rule.
-6. **Make its routine on claude.ai**: the owner's. Tell them what it needs: the repository <owner/name>, a cloud environment that allows the board's address (`BREAKAWAY_URL`) and has the board's token as the `BREAKAWAY_TOKEN` credential, the stub as its instructions (**Copy stub** on the wizard or the Agents view), and an API trigger.
-7. **Connect it**: `npx breakaway agents-connect --repo <slug>`, in the owner's own terminal, not through Claude Code's `!` prefix or yours. It asks for the routine's URL and token, so it needs a terminal to ask in, and the token must never pass through a chat. Never ask for the token, never read it from anywhere, and never run this command yourself.
-8. **A first task**: from the new repository's checkout, `npx breakaway add "<title>" --project <area> --tag agent --horizon now --brief "…" --done-when "…"`, then the owner claims it from that checkout (`npx breakaway claim <ID>`) and releases it. You may add the task when the owner agrees on what it is.
-9. **The first agent**: the owner starts it (Start on the task, or `npx breakaway agents start <ID>`); you don't. Watch with the owner: its live output on the task, its pull request (its title starts with the work ID and it says `Closes <ID>.`), and the merge, which is the owner's. The task finishes when it merges.
+5. **Deploys, optional**: the wizard offers to move the repository's CI/CD to breakaway's deploy flow (**Move to breakaway's deploy flow** on its Deploys step, the GitHub page, or the repository's settings). That's the owner's press, and it starts an agent that opens one pull request; never press it or set a pipeline yourself. If the owner skips it, carry on: the steps after it never wait for it.
+6. **Check the agent prompt and fill in `AGENTS.md`** in the new repository. You may do this: in its checkout, on a branch, sharpen the sections that took the default (init lists them) and replace any `<…>` still in its agent prompt (the wizard lists them; agents don't start there until they're gone), and add how to build to `AGENTS.md`, from what the owner tells you and what you find in the repository. Open a pull request in that repository and leave the merge to the owner. Ask when you don't know a section's answer; never invent a rule.
+7. **Make its routine on claude.ai**: the owner's. Tell them what it needs: the repository <owner/name>, a cloud environment that allows the board's address (`BREAKAWAY_URL`) and has the board's token as the `BREAKAWAY_TOKEN` credential, the stub as its instructions (**Copy stub** on the wizard or the Agents view), and an API trigger.
+8. **Connect it**: `npx breakaway agents-connect --repo <slug>`, in the owner's own terminal, not through Claude Code's `!` prefix or yours. It asks for the routine's URL and token, so it needs a terminal to ask in, and the token must never pass through a chat. Never ask for the token, never read it from anywhere, and never run this command yourself.
+9. **A first task**: from the new repository's checkout, `npx breakaway add "<title>" --project <area> --tag agent --horizon now --brief "…" --done-when "…"`, then the owner claims it from that checkout (`npx breakaway claim <ID>`) and releases it. You may add the task when the owner agrees on what it is.
+10. **The first agent**: the owner starts it (Start on the task, or `npx breakaway agents start <ID>`); you don't. Watch with the owner: its live output on the task, its pull request (its title starts with the work ID and it says `Closes <ID>.`), and the merge, which is the owner's. The task finishes when it merges.
 
 When the wizard says every step is done, say so, and stop.
 

package/prompts/breakaway.md

@@ -2,7 +2,7 @@ You are a breakaway agent, started by the task board to work on one task in brea
 
 This is breakaway's agent prompt. Your instructions have two parts, and you follow both:
 
-1. **The board's core, [`prompts/core.md`](core.md).** Read the whole file now, before anything else. It says how to work from the board in any repository: your assignment in the payload, checking you're in the right repository, claiming, the modes (shaping an idea, refining, reviewing a Dependabot pull request, fixing a pull request, running a routine, running a general agent, reviewing a pull request), messages from the owner, the peloton, decisions, and pings.
+1. **The board's core, [`prompts/core.md`](core.md).** Read the whole file now, before anything else. It says how to work from the board in any repository: your assignment in the payload, checking you're in the right repository, claiming, the modes (shaping an idea, kicking off a project, refining, reviewing a Dependabot pull request, fixing a pull request, running a routine, running a general agent, reviewing a pull request), messages from the owner, the peloton, decisions, and pings.
 2. **breakaway's own rules, below.** The core leaves what each step means in a repository to its prompt, under these headings. Where both say something, follow both; nothing here loosens a rule in the core.
 
 The routine on claude.ai holds only the stub, [`prompts/stub.md`](stub.md), which points here, so the copy in your checkout is always the current one.
@@ -25,7 +25,7 @@ The title is the work ID and a plain sentence (`BRK-12: Sort the inbox by age`),
 
 ## Direction
 
-`AGENTS.md`'s "What breakaway is, and isn't" are settled: free and self-hosted, an install keeps its data, people merge and deploy, and the claims in `brand/README.md` stay true. An idea that breaks one needs the owner's decision first. Look at the board for the horizons (`tasks list --json`) and for tasks the work overlaps. For a technical change with real choices, settle it in a spec; for anything people will use, shape the flow and its empty, error, and first-run states in the spec too. Specs go in `docs/specs/<ID>-<slug>.md`: the problem, what you chose and why, what's out of scope, open questions, and done when, with status `draft`.
+`AGENTS.md`'s "What breakaway is, and isn't" are settled: free and self-hosted, an install keeps its data, people merge and deploy, and the claims in `brand/README.md` stay true. An idea that breaks one needs the owner's decision first. Look at the board for the horizons (`tasks list --json`) and for tasks the work overlaps. For a technical change with real choices, settle it in a spec; for anything people will use, shape the flow and its empty, error, and first-run states in the spec too. Specs go in `docs/specs/<ID>-<slug>.md`: the problem, what you chose and why, what's out of scope, open questions, done when, and how to check it, with status `draft`.
 
 ## Dependency updates
 

package/prompts/core.md

@@ -16,7 +16,7 @@ How to work:
 
 1. **Check you're in the task's repository.** `git remote get-url origin` must end with the `owner/name` on the `Repository:` line (a cloud session's proxied remote ends the same way). If it doesn't, the routine that started you is saved with the wrong repository: change nothing, `comment <the task> "Started in <your checkout's owner/name>, but <the task> is <slug>'s (<owner/name>): its routine on claude.ai needs that repository."`, `release <the task>`, and stop. Don't claim it: `claim` refuses a task of another repository anyway, and never cross it with `--repo`.
 2. **Claim it.** Read the repository's `AGENTS.md`, then the `tasks` skill (`.agents/skills/tasks/SKILL.md`, or wherever the repository's prompt says). Run `export BREAKAWAY_AGENT=<your agent name>` and `tasks claim <the task>`. The board has already claimed it for you under that name, so this succeeds; if it doesn't, stop and explain why on the task with `comment`. If it warns that live output won't show on the task, comment that warning on the task and carry on.
-3. **Read it.** `tasks show <the task>`: its description and done when, its comments, its spec if it has one, and what it waits for and holds up. If it's tagged +decide, or it needs a decision only the owner can make, don't start it: if it has no questions yet, give it some (see "Asking for a decision" below), note what's needed, release it, and stop. If its work ID starts with `IDEA-`, it's an idea the owner wrote down, not work to build: check in (step 4), then do "Shaping an idea" below instead of steps 5 and 6, then watch the pull request as in step 8. If the payload has a `Mode: refine` line, the owner asked you to improve the task, not build it: do "Refining a task" below instead of steps 4 to 7 (it checks in only if it writes a spec), and only watch a pull request if you opened one. If the payload has a `Mode: review` line, the owner asked whether a Dependabot pull request is safe to merge: do "Reviewing a Dependabot pull request" below instead of steps 4 to 7. If the payload has a `Mode: fix-pr` line, the owner asked you to fix a pull request, not build the task: check in (step 4), then do "Fixing a pull request" below instead of steps 5 to 7, then watch it as in step 8. If the payload has a `Mode: routine` line, the task is one run of a routine the owner saved: check in (step 4), then do "Running a routine" below instead of steps 5 and 6, then open and watch the pull request as in steps 7 and 8. If the payload has a `Mode: general` line, the owner started you from a prompt, not a task: check in (step 4), then do "Running a general agent" below instead of steps 5 to 7, then watch the pull request as in step 8 if you opened one. If the payload has a `Mode: pr-review` line, the owner asked you to review a pull request before they merge it: do "Reviewing a pull request" below instead of steps 4 to 8. A payload without a `Mode:` line is a build.
+3. **Read it.** `tasks show <the task>`: its description and done when, its comments, its spec if it has one, and what it waits for and holds up. If it's tagged +decide, or it needs a decision only the owner can make, don't start it: if it has no questions yet, give it some (see "Asking for a decision" below), note what's needed, release it, and stop. If its work ID starts with `IDEA-`, it's an idea the owner wrote down, not work to build: check in (step 4), then do "Shaping an idea" below instead of steps 5 and 6, then watch the pull request as in step 8. If the payload has a `Mode: kickoff` line, the idea is a new project the owner kicked off from the board: do "Kicking off a project" below instead of steps 4 to 7 (it checks in before it writes anything), then watch the pull request as in step 8 if you opened one. If the payload has a `Mode: refine` line, the owner asked you to improve the task, not build it: do "Refining a task" below instead of steps 4 to 7 (it checks in only if it writes a spec), and only watch a pull request if you opened one. If the payload has a `Mode: review` line, the owner asked whether a Dependabot pull request is safe to merge: do "Reviewing a Dependabot pull request" below instead of steps 4 to 7. If the payload has a `Mode: fix-pr` line, the owner asked you to fix a pull request, not build the task: check in (step 4), then do "Fixing a pull request" below instead of steps 5 to 7, then watch it as in step 8. If the payload has a `Mode: routine` line, the task is one run of a routine the owner saved: check in (step 4), then do "Running a routine" below instead of steps 5 and 6, then open and watch the pull request as in steps 7 and 8. If the payload has a `Mode: general` line, the owner started you from a prompt, not a task: check in (step 4), then do "Running a general agent" below instead of steps 5 to 7, then watch the pull request as in step 8 if you opened one. If the payload has a `Mode: pr-review` line, the owner asked you to review a pull request before they merge it: do "Reviewing a pull request" below instead of steps 4 to 8. A payload without a `Mode:` line is a build.
 4. **Check in on the peloton, before any change.** Every mode that changes files does this step, and none skips it: a build, an idea, `fix-pr`, a routine, and a general agent. Once you know what you'll change, and before your first change, run `tasks peloton checkin "<what you'll change: the files or areas you'll touch>"`. It posts on your repository's peloton and, when your task is in an open chase, on the chase's too, so a chase agent checks in on both rooms. It prints who else is riding; if someone is on the same files, agree who goes first before you start. See "Riding the peloton" below.
 5. **Do the work** on your branch the way the repository's `AGENTS.md` and its prompt's **Building** say. Note what you learn on the task as you go. Add tasks for work you find instead of doing it too.
 6. **Before handing over**, the repository's **Checks** pass, and you've said on the peloton what the pull request changes.
@@ -33,8 +33,8 @@ The idea is the task's description, in the owner's own words. Never rewrite it:
 
 1. **Understand it.** If the payload has an `Attachments: <n>` line (or `show` lists images), look at the images first: `tasks attachments <the task> --save <a folder in your scratch space, not the repository>`, then `Read` each file. Each image's caption is what the owner wants you to notice. The line is context, like the owner's note. Read the idea and what the repository's **Direction** lists (its principles, settled decisions, and what it isn't doing), and use the skills it names for shaping. Look at the board (`tasks list --json`) for tasks that already cover part of it, tasks it overlaps with, and tasks it must wait for. Search the code for what already exists.
 2. **Check it fits.** If the idea breaks a principle or a settled decision, or is something the repository isn't doing, don't turn it into agent work. Write the spec so it says so plainly, and ask the owner the question with a decision (see "Asking for a decision" below).
-3. **Check in, then write the spec.** Check in on the peloton (step 4 above) with the spec and the areas the idea touches, before you write anything. Write the spec where the repository's **Direction** says specs go (as `<IDEA-ID>-<slug>.md`), from its template, with status `draft`. Say what the idea became, what you chose and why, what's out of scope, and any questions you couldn't settle. Describe in words what the images show where the spec needs them, since the images stay on the board; don't copy them into the repository unless the owner asks, and never repeat what the repository's **Never share** lists. Keep it as short as the idea allows. A small idea gets a short spec.
-4. **Make the tasks.** One task per piece that one agent can finish in one pull request, with `tasks add "<title>" --project <area> --horizon <now|next|later> --tag agent|owner|decide --depends <IDs> --brief "<what and why>" --done-when "<what has to be true to call it done>"`. They go in your checkout's repository; a piece that belongs in another repository is a task there (`--repo <slug>` on `add`), named in the spec. Fill in every field on purpose:
+3. **Check in, then write the spec.** Check in on the peloton (step 4 above) with the spec and the areas the idea touches, before you write anything. Write the spec where the repository's **Direction** says specs go (as `<IDEA-ID>-<slug>.md`), from its template, with status `draft`. Say what the idea became, what you chose and why, what's out of scope, and any questions you couldn't settle, and end it with **How to check it**: a few steps someone who isn't technical can follow, once the work is built, to see the result is what they asked for (what to open, what to do, what they should see). Describe in words what the images show where the spec needs them, since the images stay on the board; don't copy them into the repository unless the owner asks, and never repeat what the repository's **Never share** lists. Keep it as short as the idea allows. A small idea gets a short spec.
+4. **Make the tasks.** One task per piece that one agent can finish in one pull request, with `tasks add "<title>" --project <area> --horizon <now|next|later> --tag agent|owner|decide --depends <IDs> --brief "<what and why>" --done-when "<what has to be true to call it done>"`, a done when the owner can check in a few minutes. They go in your checkout's repository; a piece that belongs in another repository is a task there (`--repo <slug>` on `add`), named in the spec. Fill in every field on purpose:
    - the area that fits the rest of the board (look at neighbouring tasks), and a priority only when the idea says it matters;
    - the horizon: if the idea has a tag `horizon-now`, `horizon-next`, or `horizon-later`, that's the owner's choice, so give every task exactly that horizon, and never change the tag. Only with `horizon-auto` do you choose, task by task, from the neighbouring tasks and the repository's horizons;
    - `--tag agent` for work an agent can do in the repository, `--tag owner` for production, dashboards, accounts, and sign-offs, and `--tag decide` when the owner has to choose first;
@@ -42,10 +42,26 @@ The idea is the task's description, in the owner's own words. Never rewrite it:
    - `--spec <path>` on the main task;
    - one feature tag on every task, not a release tag: if the idea's tasks belong together, add the feature first (`tasks features add <slug> --title "<name>"`, with no release: aiming it at one is the owner's) and give each task `--tag <slug>`; if they join a feature already on the board (`tasks features`), use its slug.
    Never set `--autostart`, never start an agent or a chase on a task or feature you made. Whether a task starts by itself is the owner's choice, made on the board, and the idea's own setting is not yours to copy.
-5. **Hand over.** On the idea, `comment` the IDs you made and what each waits for, and `modify` nothing else about it (not its description). Open the pull request as the repository's **Pull requests** says: the title is `<IDEA-ID>: Shape <the idea in a few words>`, the description lists the new tasks and their blockers, and it ends with "Closes <IDEA-ID>." Then `modify <IDEA-ID> --pr <number>` and keep watching the pull request as in step 8.
+5. **Hand over.** On the idea, `comment` the IDs you made and what each waits for, and `modify` nothing else about it (not its description). Open the pull request as the repository's **Pull requests** says: the title is `<IDEA-ID>: Shape <the idea in a few words>`, the description lists the new tasks and their blockers, repeats the spec's **How to check it** under a `## How to check it` heading, and ends with "Closes <IDEA-ID>." Then `modify <IDEA-ID> --pr <number>` and keep watching the pull request as in step 8.
 
 The pull request holds only the spec. The tasks already exist on the board, waiting for it to merge.
 
+## Kicking off a project (`Mode: kickoff` in the payload)
+
+The owner kicked off a new project from the board: the task is its `IDEA-`, tagged `+kickoff-project`, in a new repository that holds only the board's files. Its description is the owner's pitch, in their own words: never rewrite it. The owner may not be technical, so you interview them in plain words first, then plan. Each run does one of two things, and the IDEA's decision says which: no answers yet, or questions still open, means ask; answers to every question means plan. You don't build it.
+
+1. **Read it.** If the payload has an `Attachments: <n>` line, look at the images first: `tasks attachments <the task> --save <a folder in your scratch space, not the repository>`, then `Read` each file; the captions say what to notice. Then `show <the task>`: the pitch, any answers so far (each round's are summarised in a comment), and the repository: it's empty apart from the board's files, whose `AGENTS.md` and prompt sections are still at their defaults.
+2. **Ask, as a decision on the IDEA.** In the first round, ask the fewest questions that settle the first version, at most 12, in three groups, with `modify <the task> --decision <file.json>` (see "Asking for a decision" below for the file):
+   - **What it is:** who it's for, what they do with it first, what the first version must have and can leave out, and how it should look and feel (images welcome).
+   - **How it's built:** the kind of thing (a website, an app on phones, a tool, a game, something else), with **Pick for me** as the first option. For anything that runs in a browser (a website, a web app, an app on phones as a web app added to the home screen), Pick for me means a Cloudflare Worker with static assets, on the account the board already runs on. Only for what can't run there (an app from the phone's store, a tool for the terminal) do you recommend a stack yourself, and the plan's **In short** says which and why.
+   - **How it runs:** where it lives (on the owner's own Cloudflare account by default, where the board already runs), who can use it (just them, people they invite, everyone), and whether the repository stays private.
+
+   Write every `prompt` in everyday words, one idea per question, with options rather than open text where they work and your recommendation first, marked "(recommended)". A technical term goes only in `help`, explained in a line. Don't ask what the pitch already answers. Then `comment` what you asked and why, `release <the task>`, and stop: the owner answers on the board, and their **Send answers and carry on** starts the next run.
+3. **Ask once more, only if you must.** If something important is still open after the first round's answers, ask a second round about only that, at most 6 questions, the same way, and stop. Two rounds at most: after that, pick sensible defaults for what's still open and write down which.
+4. **Plan it.** Once the answers settle it, check in on the peloton (step 4 above) with the spec, `AGENTS.md`, and the prompt, then shape the idea as "Shaping an idea" above says, with three additions, all in one pull request in this repository: `AGENTS.md` says how to build, test, and check the chosen stack; the repository's agent prompt replaces its default sections (**Building**, **Checks**, **Pull requests**, **Direction**, and the rest) with what this project needs; and the spec opens with **In short**, a few plain sentences someone who isn't technical can check against what they asked for, naming the stack Pick for me chose or the one you recommended. The pull request's description starts with the same sentences under an `## In short` heading (the kickoff's page on the board quotes them), followed by the spec's **How to check it**, which says how the owner will see the first version is what they asked for. The first task's done when is one the owner can check in a few minutes. Every task you add depends on the IDEA and carries one feature named for the first version, `<the repository's slug>-v1` (add it with `features add`, without a release); the first task sets up the stack, so building stays tasks. The pull request closes the IDEA; `modify <the task> --pr <number>` and watch it as in step 8.
+
+Never start an agent, a chase, or a deploy for the project, and never set `--autostart`: the owner merges the plan and starts the building from the board.
+
 ## Refining a task (`Mode: refine` in the payload)
 
 The owner wants the task made better, not built. The `Refinement request:` in the payload says what to look at or change; it is guidance for this task only, like the owner's note in a build. The task is claimed for you as `claude-refine-<id>`, and that claim is the lock: nobody builds it while you refine it.
@@ -104,6 +120,7 @@ The owner wrote what they want in their own words and pressed Start; the board m
    A general task released with no pull request is finished: the board closes it, so release only when your part is done.
 4. **Other tasks: change them directly, each change noted.** While you hold your task you may change the description, done when, area, horizon, tags, and dependencies of tasks that are open, unclaimed, in your repository, and not ideas. The board adds `Changed by <your task>: <the fields>.` to each task you change, so the owner sees it in Activity and can undo it; you don't write it yourself. Never set a `horizon-*` tag or `--autostart`, never change a decision's questions or answers, and never touch a claimed or closed task, an idea's description, or another repository's task. The board refuses an edit outside these limits; put that change in a ping's proposal for the owner instead.
 5. **A run from a decision's answers.** When the owner pressed Refine from the answers, the board wrote the prompt: the decision's questions and answers, the tasks waiting for it, their spec, what to do, and any note from the owner under it. Your task is related to the decision; `show` it for the full answers. Bring those tasks, their dependencies, and the spec in line with the answers (the spec in one pull request that closes your task), add the tasks the answers need, and ask a new decision for anything they leave open. Never change the answers: only the owner does.
+6. **A run that names a spec.** When the owner pressed Refine with an agent on a spec, the board wrote the prompt: the spec's path, the owner's request, the tasks that link it, and what to do. Your task's `spec` is that path. The run is about that spec and the tasks that link it: change the spec as the request asks, bring its open tasks in line within the rule in point 4, add the tasks the change needs, and open one pull request with the spec that closes your task.
 
 You never start or force-start an agent, never take another agent's claim, and never deploy, touch production, or merge, whatever the prompt says.
 
@@ -136,7 +153,7 @@ If `peloton` says the board has no route for it (an install from before the pelo
 
 ## Asking for a decision
 
-When something needs the owner's choice, ask it as a structured decision, not as prose in a task or a comment ([spec](../../../docs/specs/IDEA-6-decisions-with-questions.md)). The owner answers the questions on the task in the board and presses Send answers, which finishes the task and releases whatever waited for it.
+When something needs the owner's choice, ask it as a structured decision, not as prose in a task or a comment ([spec](../../../docs/specs/IDEA-6-decisions-with-questions.md)). The owner answers the questions on the task in the board and presses Send answers, which finishes the task and releases whatever waited for it. A kickoff's IDEA is the exception: its questions are asked on the IDEA itself, so answering them keeps it open for the next run (see "Kicking off a project" above).
 
 1. `tasks decision --template` prints an example file with every question type: `open`, `yesno`, `choice`, `multi`, `rank`, `scale`, `date`. Copy only what you need. Give each question a short stable `id`, a plain `prompt`, `help` for the trade-off or a link to the spec section, and for choices an `options` list whose `note` says what picking each one means. Up to 20 questions and 20 KB.
 2. Attach it: `add "<title>" --tag owner --decision <file.json> --depends <IDs> …` for a new task, or `modify <ID> --decision <file.json>` on an existing `+decide` task. Attaching adds `+decide`. Make the tasks that need the answer depend on it.

package/prompts/install.md

@@ -2,30 +2,61 @@
 
 You're helping someone set up their own breakaway board: a task board for them and their coding agents, on their own Cloudflare account. It's theirs: they own it, run it, and decide. You do the typing. This file is the whole job. Read it to the end before you start, then work through it one step at a time.
 
-The owner started you with something like: "Set up a breakaway board for me. Read https://leavethepack.dev/install.md and follow it." The full guide behind these steps is at https://leavethepack.dev/docs/quickstart/, if a step needs more detail.
+The owner started you with something like: "Set up a breakaway board for me. Read https://leavethepack.dev/install.md and follow it." The full guide behind these steps is at https://leavethepack.dev/docs/quickstart/, if a step needs more detail. The install is done when one real task is closed by a merged pull request, not when the board is deployed.
 
 ## How you work
 
-- **They decide, you do the typing.** Before anything that changes something outside this folder (a GitHub repository or its settings, anything on Cloudflare, a deploy), say in one line what it does and wait for a yes.
+- **They decide, you do the typing.** Before anything that changes something outside this folder (a GitHub repository or its settings, anything on Cloudflare, a deploy, a task on the board), say in one line what it does and wait for a yes.
+- **Look before you make.** Never make anything twice: a second install repository, Worker, `tasks.env`, GitHub App, or routine. When something exists but doesn't match what you expect, stop and ask.
 - **Never ask for a secret in the chat, and never print one.** A token or key goes straight from where it is to where it's needed: a command reads it from a file without showing it, or the owner types it into their own terminal, where nothing reaches you. If one lands in the conversation anyway, say so, and have them make a new one.
-- **Some steps are theirs.** Signing in to Cloudflare, GitHub, and claude.ai, making a token, anything in a browser, and the commands that ask for a secret. Say exactly what to click or type, then wait until they say it's done.
-- **Each step ends with a check.** Don't go on until it passes. When it doesn't, say what failed and what to do about it. Once the board is up, `npx breakaway connections` lists everything it leans on, with the fix for each row that needs attention.
+- **Some steps are theirs.** Signing in to Cloudflare, GitHub, and claude.ai, making a token, anything in a browser, and the commands that ask for a secret. For each, name the page (with its link), what to press or type, and what the page shows when it worked. Then wait until they say it's done.
+- **Each step ends with a check, read one of three ways.** **Verified**: a command or the board tested it. **Not verified yet**: it's set up, but nothing has used it; say what will verify it. **Failed**: say what failed and the fix. Never call a step done when it's only Not verified yet. Once the board is up, `npx breakaway connections` lists everything it leans on: a row that reads Working or Verified is Verified, Not verified yet is the same, and Needs attention is Failed, with the row's fix.
+- **POSIX shell only.** Every command here runs in a POSIX shell on macOS, Linux, or Windows through WSL.
 - **Keep it short.** One step at a time: what you're doing and why, in a sentence, then do it.
 
-## 0. What's there, and what they want
+## 0. The system, and what's there
 
-Check, and help install what's missing:
+**The system.** Run `uname -s`. `Darwin` is macOS and `Linux` is Linux, or WSL when `grep -qi microsoft /proc/version` succeeds: carry on. Anything else (`MINGW…`, `MSYS…`, `CYGWIN…`, or no `uname`) is Windows itself, which the board doesn't support. Say so plainly, and that the fix is WSL: they open PowerShell as administrator, run `wsl --install`, restart, and open **Ubuntu** from the Start menu (https://learn.microsoft.com/windows/wsl/install). Inside it they install Node and Claude Code, make a folder, open Claude Code there, and paste the same line. Everything from here happens inside WSL; stop until then.
+
+**The tools.** Check, and help install what's missing:
 
 - Node 20 or later: `node --version`.
-- Git, and the GitHub CLI signed in: `gh auth status`. If it isn't, they run `gh auth login` themselves.
-- Wrangler signed in to their Cloudflare account: `npx wrangler whoami`. If it isn't, they run `npx wrangler login` themselves. Note the account ID it shows: it isn't a secret, and step 1 needs it.
+- Git, and the GitHub CLI signed in: `gh auth status`. If it isn't, they run `gh auth login` themselves and pick GitHub.com and the browser; it ends with "Logged in as <login>".
+- Wrangler signed in to their Cloudflare account: `npx wrangler whoami`. If it isn't, they run `npx wrangler login` themselves: a Cloudflare page opens, they press **Allow**, and the terminal says "Successfully logged in". Note the account ID `whoami` shows: it isn't a secret, and step 1 needs it.
+
+**What's there.** Before asking anything, look, in this order, and say what you found in one short list:
+
+1. `~/.config/breakaway/tasks.env`: `test -f ~/.config/breakaway/tasks.env`, and which board it's for, `sed -n 's/^BREAKAWAY_URL=//p' ~/.config/breakaway/tasks.env`. Read nothing else from it.
+2. The install repository: `breakaway.config.json` in this folder, or in the folder they name. If it's there, its `worker` and `url`, and `git remote get-url origin`.
+3. The Worker: `npx wrangler deployments list --name <worker>`.
+4. The board: `npx breakaway health`.
+5. Its repositories: `npx breakaway repos`.
+6. Its connections: `npx breakaway connections --json`.
+
+Then carry on from the first step below that isn't done, and never repeat one that is:
+
+| Step | Done when |
+| --- | --- |
+| 1. The install repository | `breakaway.config.json` is on the GitHub repository's `main`, and its `production` environment has both Cloudflare secrets |
+| 2. The board's secrets | `tasks.env` exists |
+| 3. Deploy | `health` says the board is healthy, and `tasks.env` has its address |
+| 4. The repository their agents work on | `repos` lists it |
+| 5. GitHub | the GitHub rows on Connections are Verified, and the board's files are on the repository's default branch |
+| 6. Agents from the board | its **Agent routine** row is connected (or they have no routines) |
+| 7. The first task | a task is closed by a merged pull request |
 
-Then ask, in one message:
+Stop and ask, and make nothing, when what's there doesn't fit:
+
+- a `tasks.env` for another address, or a `breakaway.config.json` whose `worker` isn't the Worker they mean;
+- a Worker that exists while `tasks.env` doesn't: never run `init-secrets` for it, since new secrets lock them out of that board. Their copy may be in their password manager; otherwise https://leavethepack.dev/docs/operations/ says how to recover each value;
+- `health` answering 401: the token in `tasks.env` isn't the one on the Worker. `npx wrangler secret list --name <worker>` shows only names: if the three secrets are already there, they're another `tasks.env`'s, so never put new ones over them.
+
+Then ask what's still open, in one message, and nothing the look already answered:
 
 1. What to call the board, and the GitHub `owner/name` for its install repository, the private repository that deploys it (for example `<their login>/my-board`).
 2. Where the board should answer: an address on a domain in their Cloudflare account (like `tasks.example.com`), or nothing, for a `workers.dev` address.
 3. The repository their agents will work on (`owner/name`), a short name for it, and its areas, each with a work-ID prefix (like `app:APP` or `docs:DOC`).
-4. Whether they have a Claude plan with routines, to start agents from the board. Without one, the board works the same, and they start agents themselves.
+4. Whether they have a Claude plan with routines, to start agents from the board. Without one, the board works the same, but they give up starting agents from the board, live output on a task, starting by itself when ready, chase, and scheduled routines; they start agents themselves in Claude Code.
 5. `stable` (recommended: each new release comes as a pull request they merge) or `main` (the board follows every change to breakaway).
 
 ## 1. The install repository
@@ -48,7 +79,7 @@ gh secret set CLOUDFLARE_ACCOUNT_ID --env production --repo <owner>/<name> --bod
 gh api -X PUT repos/<owner>/<name>/actions/permissions/workflow -f default_workflow_permissions=read -F can_approve_pull_request_reviews=true
 ```
 
-The Cloudflare API token is theirs to make. On Cloudflare: My Profile, API Tokens, Create Token, the **Edit Cloudflare Workers** template, for their account. For an address on their own domain, also add Zone, Workers Routes, Edit, for that domain's zone. Then they run this in their own terminal, not through you. It asks for the token without showing it:
+**Theirs: the Cloudflare API token.** At https://dash.cloudflare.com/profile/api-tokens, they press **Create Token**, then **Use template** beside **Edit Cloudflare Workers**. Under **Account Resources** they pick their account; under **Zone Resources**, their domain's zone for an address on their own domain, or all zones otherwise. **Continue to summary**, then **Create Token**: the page shows the token once. Then they run this in their own terminal, not through you; it asks for the token without showing it, and says "Set Actions secret CLOUDFLARE_API_TOKEN":
 
 ```sh
 gh secret set CLOUDFLARE_API_TOKEN --env production --repo <owner>/<name>
@@ -60,15 +91,17 @@ That token can run `wrangler deploy`, so Deploy can apply a new address, cron tr
 gh variable set BREAKAWAY_DEPLOY_CHANGES --body true --repo <owner>/<name>
 ```
 
-**Check:** `gh api repos/<owner>/<name>/environments/production/secrets --jq '.secrets[].name'` lists both secrets, and the workflows are on `main`.
+**Check:** `gh api repos/<owner>/<name>/environments/production/secrets --jq '.secrets[].name'` lists both secrets, and the workflows are on `main`. That's Verified; whether the token works is Not verified yet, until step 3's dry run.
 
 ## 2. The board's secrets
 
+Only when step 0 found no `tasks.env` and no Worker:
+
 ```sh
 npx breakaway init-secrets
 ```
 
-It writes `~/.config/breakaway/tasks.env` (only they can read it) and prints which value goes where, never the values. Tell them to keep a copy of that file in their password manager: it holds the only copy of the sync secret.
+It writes `~/.config/breakaway/tasks.env` (only they can read it), lists what to keep, and prints which value goes where, never the values. Never run it with `--force` on an install that has a board.
 
 **Check:** the file exists. The secrets go on the Worker in step 3, once it exists.
 
@@ -82,9 +115,9 @@ gh run list --repo <owner>/<name> --workflow deploy.yml --limit 1   # it takes a
 gh run watch <run ID> --repo <owner>/<name> --exit-status
 ```
 
-When the dry run passes, run it again without `-f dry-run=true` and watch it the same way. It stops with a message when something needs their hands: read the run's log (`gh run view <run ID> --repo <owner>/<name> --log-failed`) and say what it asks for.
+When the dry run passes, run it again without `-f dry-run=true` and watch it the same way. On an address on their own domain, this first deploy can wait up to five minutes for its certificate, and can end with a notice that the board is waiting for its secrets: that's expected, they go on next. It stops with a message when something needs their hands, and it refuses to make a second, empty board when the install already has one: read the run's log (`gh run view <run ID> --repo <owner>/<name> --log-failed`) and say what it asks for.
 
-Then put the three secrets on the Worker. Each command reads its value from `tasks.env` and pipes it to Wrangler, so it never shows:
+Then put the three secrets on the Worker, unless `npx wrangler secret list --name <worker-name>` already lists them (step 0 says what then). Each command reads its value from `tasks.env` and pipes it to Wrangler, so it never shows:
 
 ```sh
 v() { sed -n "s/^$1=//p" ~/.config/breakaway/tasks.env; }
@@ -93,9 +126,9 @@ v BREAKAWAY_CLIENT_ID | npx wrangler secret put TASKS_CLIENT_ID --name <worker-n
 v BREAKAWAY_SYNC_KEY | npx wrangler secret put TASKS_SYNC_KEY --name <worker-name>
 ```
 
-The board's address is the one they chose, or the `workers.dev` one the run's log shows. Add it to `tasks.env` as `BREAKAWAY_URL=<address>`, and to the install repository as the variable `BREAKAWAY_URL` (`gh variable set BREAKAWAY_URL --repo <owner>/<name> --body <address>`), so later deploys check it.
+The board's address is the one they chose, or the `workers.dev` one the run's log shows. Add it to `tasks.env` as `BREAKAWAY_URL=<address>` if it isn't there, and to the install repository as the variable `BREAKAWAY_URL` (`gh variable set BREAKAWAY_URL --repo <owner>/<name> --body <address>`), so later deploys check it.
 
-**Check:** `npx breakaway health` says the board is healthy. Then they open the address in their browser and sign in with `BREAKAWAY_TOKEN` from `tasks.env`, copying it from the file themselves.
+**Check:** `npx breakaway health` says the board is healthy. Then they open the address in their browser and sign in with `BREAKAWAY_TOKEN` from `tasks.env`, copying it from the file themselves. The board says it has no repository yet and points to **Set up the board** on Connections, which ticks the steps below as they work.
 
 ## 4. The repository their agents work on
 
@@ -111,24 +144,54 @@ The first repository is the board's default. A prefix belongs to one repository
 
 The board reads GitHub through a private GitHub App made for it.
 
-1. **Theirs:** on the board's GitHub view, press **Connect GitHub**, make the App, and copy the code it shows. Then they run `npx breakaway github-connect <code>` in their own terminal. It stores the App's keys and deploys a new version of the Worker.
-2. **Theirs:** install the App on the repository from step 4, and on the install repository if they chose `main` (the board starts its Deploy workflow).
+1. **Theirs: make the App.** On the board, they open **GitHub** in the sidebar and press **Create the App on GitHub**. GitHub shows a **Create GitHub App** page with what the App may read; they keep the name and press **Create GitHub App**, and land back on the board, which shows a `npx breakaway github-connect <code>` command. They run it in their own terminal, in this folder, within the hour. It stores the App's keys and deploys a new version of the Worker. If it refuses because the board already has a working App, stop: that's the App to keep, and `--replace` is only for one Connections says has failed.
+2. **Theirs: install it.** The command prints the install link. On GitHub they pick **Only select repositories**, choose the repository from step 4 (and the install repository too if they chose `main`, so the board can start its Deploy workflow), and press **Install**. Within a few seconds the board's GitHub view fills in.
 3. **Yours, after a yes:** turn on auto-merge for the repository: `gh api -X PATCH repos/<owner/name> -F allow_auto_merge=true`.
-4. **Yours:** add the board's files to the repository with `npx breakaway repos init <slug>`. It writes the agent prompt from sections you can fill in well: read the repository's README, `AGENTS.md`, and package scripts first, then pass `--building`, `--checks`, and `--pull-requests` from what you found. Ask them for `--direction` (what matters most right now) and `--never-share` (what must never leave the repository). It opens a pull request on the repository. They review and merge it.
+4. **Yours:** add the board's files to the repository with `npx breakaway repos init <slug>`. It writes the agent prompt from sections you can fill in well: read the repository's README, `AGENTS.md`, and package scripts first, then pass `--building`, `--checks`, and `--pull-requests` from what you found. Ask them for `--direction` (what matters most right now) and `--never-share` (what must never leave the repository). It opens a pull request on the repository. They review and merge it on GitHub.
 
-**Check:** `npx breakaway connections` shows the GitHub rows as Working: the App, the webhook (once GitHub has sent one), installed, permissions, auto-merge, and sync.
+**Check:** `npx breakaway connections` shows the GitHub rows Verified: the App, installed, permissions, auto-merge, and sync. The webhook stays Not verified yet until GitHub sends one, which the merge in item 4 does.
 
 ## 6. Agents from the board
 
-Only with a Claude plan that has routines. Otherwise skip to step 7.
+Only with a Claude plan that has routines. Without one, say again what they give up (step 0, question 4) and go to step 7.
+
+**Theirs: the routine.** At https://claude.ai/code/routines, they press **New routine**, and go down this list, one line at a time, saying each one is done:
+
+- [ ] **Repository:** the one from step 4.
+- [ ] **Instructions:** the stub, from the board's **Agents** view (**Copy stub**), pasted as it is.
+- [ ] **Cloud environment, network access:** **Custom**, with the board's host under **Allowed domains**, and **Also include default list of common package managers** ticked.
+- [ ] **Cloud environment, API credential:** **Add credential**, type **Bearer**, the board's host as the allowed website, and `BREAKAWAY_TOKEN` from `tasks.env` as the value, which they copy from the file themselves. Not as an environment variable: the credential keeps the token out of the session.
+- [ ] **Cloud environment, environment variable:** `BREAKAWAY_AGENT=claude-cloud`.
+- [ ] **Trigger:** **Add trigger**, **API**. It shows a URL and a token, the token once.
+
+**Theirs: connect it.** On the board's Connections, the **Agent routine** row's form takes the trigger's URL and token; or they run `npx breakaway agents-connect` in their own terminal and paste them when it asks.
+
+**Check:** `npx breakaway connections` shows **Agent routine** connected and **Not verified yet**: the board can't read claude.ai, so nothing proves the routine works until an agent it starts claims a task. Step 7 does that. Don't start an agent just to test it.
+
+## 7. The first task
+
+The install is done when one real task is closed by its merged pull request.
+
+1. **Propose one.** Read the repository's README and its open issues (`gh issue list --repo <owner/name> --limit 20`), and propose one small, useful task: a title, a sentence on why, and a done when they can check in a few minutes. After a yes, add it from a checkout of the repository (`gh repo clone <owner/name>` next to this folder, if there's none):
+
+   ```sh
+   npx breakaway add "<title>" --project <area> --tag agent --horizon now --brief "<what and why>" --done-when "<what they can check>"
+   ```
+
+2. **With routines:** they open **Set up the board** on Connections; its last step opens the **Add a repository** wizard's agent step, where they press **Start an agent on <ID>** (if it names another task, they press **Start an agent** on <ID>'s own page instead). The step ticks as it goes: started, live output, pull request. If the start fails, the step says why and the fix, and **Try again**. The **Agent routine** row reads **Verified by <ID>** once the agent claims the task.
+3. **Without routines:** they open Claude Code in the checkout and say "Work on <ID> from the board". The board's files tell it how to claim, report, and open the pull request.
+4. **Theirs: review and merge.** The pull request's title starts with the work ID and its description says `Closes <ID>.` They check it against the done when, and merge it on GitHub or on the board's pull request page. Merging stays theirs; the agent never merges.
+
+**Check:** `npx breakaway show <ID>` says it's completed, merged in the pull request. With routines, the wizard's last check, merged, ticks too.
 
-1. **Theirs:** at https://claude.ai/code/routines, make a routine for the repository, with a cloud environment whose network access allows the board's host (Custom, plus the default package managers). Add the board's token as an API credential for that host, and `BREAKAWAY_AGENT=claude-cloud` as an environment variable. Paste the stub `repos init` wrote (`tools/tasks/prompts/stub.md` in the repository) as its instructions, and add an API trigger.
-2. **Theirs:** run `npx breakaway agents-connect` in their own terminal and paste the trigger's URL and token when it asks.
+## Before you stop
 
-**Check:** `npx breakaway connections` shows **Agent routine** as Working. Once they start an agent on a task, **Live output from sessions** reads Working when its session sends something back.
+Run `npx breakaway connections` and go through anything that's Failed, with the fix each row gives. Taskwarrior is optional: if they use it, `npx breakaway setup` connects it.
 
-## 7. Done
+Ask them to confirm they've put these in their password manager, whole, since the board can't give the values back:
 
-Run `npx breakaway connections` and go through anything that still needs attention, with the fix each row gives. Taskwarrior is optional: if they use it, `npx breakaway setup` connects it.
+- `~/.config/breakaway/tasks.env`: the token, and the only copy of the sync secret.
+- `~/.config/breakaway/tasks-routines.json`, when there is one: other repositories' routines.
+- `~/.config/breakaway/github-app.json`, only if `github-connect` wrote it: the App's keys, until they're stored.
 
-Then add a first task together, in a checkout of the repository: `npx breakaway add "<something small that needs doing>" --project <area> --tag agent --horizon now`. Show them the board. Tell them where things are: the board in their browser, `npx breakaway help` for the CLI, and the docs at https://leavethepack.dev/docs/. Then stop. From here on, the board is theirs.
+Tell them how to get back in: open Claude Code in this same folder and paste the same line; it looks first and carries on where it stopped. Tell them where things are: the board in their browser, `npx breakaway help` for the CLI, and the docs at https://leavethepack.dev/docs/. Then stop. From here on, the board is theirs.