breakaway 1.4.0-main.8 → 1.4.0

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.
@@ -85,6 +85,8 @@ Rather do it by hand? [The self-hosting guide](https://github.com/TheAnarchoX/br
 
 **Agents ping you when they need you.** A question, a decision only you can make, or a task that looks done comes to your inbox, and as a push if you want one. The rest waits on the board.
 
+**From a pitch to a deploy.** Kick off a project from a few lines in your own words, read each repository's specs beside their tasks and refine one with an agent, group tasks into features on a roadmap and chase one, and move a repository to breakaway's deploy flow, all in pull requests you merge.
+
 <table>
   <tr>
     <td valign="top">
@@ -132,11 +134,15 @@ One Cloudflare Worker serves the API, the web app (Preact), and Taskwarrior sync
 | [Concepts](https://leavethepack.dev/docs/concepts/) | Tasks and work IDs, areas, horizons, claims, dependencies, and how a pull request closes a task |
 | [Playbook](https://leavethepack.dev/docs/playbook/) | Write tasks agents finish, run many agents without collisions, and keep the review load to one person |
 | [Agents](https://leavethepack.dev/docs/agents/) | Cloud agents from the board, local agents, limits, live output, and messaging a running agent |
+| [The web board](https://leavethepack.dev/docs/web-board/) | The views, a task's panel, Settings, and each repository's page |
+| [Features, chase, and the peloton](https://leavethepack.dev/docs/features/) | A roadmap of features, a chase that starts agents on what's ready, and agents checking in with each other |
 | [Ideas, decisions, and pings](https://leavethepack.dev/docs/ideas-decisions-pings/) | Let an agent shape an idea, answer its questions in a form, and get a ping when only you can help |
+| [Routines](https://leavethepack.dev/docs/routines/) | Save an agent run and start it by hand, on a schedule, or on a GitHub event |
 | [The CLI](https://leavethepack.dev/docs/cli/) | Every command of `npx breakaway` |
-| [GitHub](https://leavethepack.dev/docs/github/) | Your own private App, how pull requests link to tasks, and merging, promoting, and rolling back |
+| [GitHub](https://leavethepack.dev/docs/github/) | Your own private App, how pull requests link to tasks, merging, and moving a repository to the deploy flow to promote, roll back, and release |
 | [Taskwarrior](https://leavethepack.dev/docs/taskwarrior/) | Sync, reports, and contexts with Taskwarrior 3 |
 | [Deploying](https://leavethepack.dev/docs/deploying/) | Releases, channels, the Deploy and Update workflows, and rollbacks |
+| [Operating a board](https://leavethepack.dev/docs/operations/) | Secrets, what to keep and what to do when it's lost, backups, and what to do when something breaks |
 | [FAQ](https://leavethepack.dev/docs/faq/) | The licence, your data, what it works with, and what it won't do |
 
 <details>
@@ -172,7 +178,7 @@ pnpm interop    # checks sync against real Taskwarrior 3
 breakaway publishes releases and never deploys an install. Every install, the owner's included, deploys a release from its own repository, and this repository holds no Cloudflare credentials. Its website follows the latest stable release: the release moves the `site` branch, and Cloudflare deploys it ([`site/README.md`](https://github.com/TheAnarchoX/breakaway/blob/main/site/README.md#deploy-it)).
 
 - **Every merge to `main`**, once CI passes, publishes a GitHub pre-release `vX.Y.Z-main.N` on the `main` channel. It carries the bundle (`breakaway-bundle.tar.gz`: the Worker's files and the web app's `dist`), a `manifest.json` (version, channel, commit, `manual`, and the lowest version it updates from), its signature `manifest.json.sig` (Ed25519, made with a key only the release workflow holds; the public key is `src/release-key.js`), and `SHA256SUMS`. The notes list the merged pull requests by title.
-- **A stable release** `vX.Y.Z` is the owner's: they run the **Release** workflow with the pre-release to promote. The bundle is that pre-release's, unchanged, and the notes cover everything since the last stable.
+- **A stable release** `vX.Y.Z` is the owner's: they run the **Release** workflow with the pre-release to promote. The bundle is that pre-release's, unchanged, and the notes cover everything since the last stable, under the release's own words from [`docs/releases/vX.Y.Z.md`](https://github.com/TheAnarchoX/breakaway/tree/main/docs/releases) when it's there.
 - **The CLI** is on npm as [`breakaway`](https://www.npmjs.com/package/breakaway), staged on npm by the same workflow, with provenance, and live once the owner approves it there with 2FA. npm's trusted publishing can't yet read the OIDC identity of a repository as new as this one ([npm/cli#9969](https://github.com/npm/cli/issues/9969)), so until it can, a token that can stage but never publish by itself stands in, in an environment only `main` can use. Every pre-release goes out under the `next` dist-tag, and a stable release as `latest`. `npx breakaway <command>` is `node scripts/tasks.mjs <command>`.
 - **A major release** is one where an install has to do something by hand: a config or binding change, a Durable Object class or migration, a route or cron. Its notes have a **Manual steps** section and its manifest says `manual: true`, which an install's deploy stops on. A change that needs it sets `manual` and `manualSteps` in `release.json`, and the pull request that ships the steps clears them. When the only step is `wrangler deploy` (a new Durable Object class, a cron, a route), it also sets `wranglerDeploy: true`, and an install whose Deploy may run `wrangler deploy` does it itself (the install template's README says when). Data the Durable Object stores changes forward-only and additively, so an install can always go back one release, except across a new Durable Object class, which Cloudflare doesn't roll back.
 - **The version** is `package.json`'s; the release workflow sets it to the pre-release's before it builds. Patches count by themselves: once a stable is out, the pre-releases work toward its next patch. For the next minor or major, pick it as **next** when you run the **Release** workflow (patch, the default, opens nothing): once the stable is published, the workflow opens a pull request setting `package.json` to it, and after it merges the next pre-release is `vX.Y.0-main.1`. That needs **Allow GitHub Actions to create and approve pull requests** on in the repository's Actions settings (if it was off, turn it on and re-run the **next version** job: it opens the pull request from the branch it already made), and a pull request opened with the workflow's token starts no workflows, so close and reopen it, or push to it, for CI to run. At any other time, **Prepare** on the board's GitHub view starts an agent that opens the same pull request. `GET /api/ping` and `GET /api/health` report it as `release`. An install that deploys a stable passes it as the `BREAKAWAY_VERSION` variable, since the bundle was built as the pre-release.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "breakaway",
-  "version": "1.4.0-main.8",
+  "version": "1.4.0",
   "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.