breakaway 1.5.0-main.2 → 1.5.0-main.20

package/README.md

@@ -180,6 +180,7 @@ breakaway publishes releases and never deploys an install. Every install, the ow
 - **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, 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>`.
+- **The plugin** for Claude Code (`plugin/`) goes out from the `plugin` branch, never from `main`: Anthropic's plugin directory and this repository's marketplace follow that branch. A stable release runs the **Plugin** workflow, which validates the plugin and moves the branch to the released tag, with `plugin.json`'s version set to the release's. To put a fix out before the next release, the owner runs it by hand on `main` with a release tag, or a commit on `main` a pre-release was made from. As with `site`, a ruleset lets only deploy keys move `plugin`, and the key is the `PLUGIN_DEPLOY_KEY` secret in a `plugin` environment that only `main` can use.
 - **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.5.0-main.2",
+  "version": "1.5.0-main.20",
   "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",

package/scripts/brand-lint.mjs

@@ -2,7 +2,7 @@
 /**
  * Lint breakaway's words against the brand guide's mechanical rules (scripts/lib/brand-lint.js).
  *   node scripts/brand-lint.mjs [path ...]
- * Paths are files or folders; with none, the web app, brand/, the docs, launch/, and the README and root
+ * Paths are files or folders; with none, the web app, brand/, the docs, launch/, the plugin, and the README and root
  * markdown files. Exits 1 and prints each finding. A line opts out with `brand-lint-ignore <rule>`.
  */
 import { readFileSync, readdirSync, statSync, existsSync } from 'node:fs';
@@ -15,6 +15,7 @@ const DEFAULT = [
   'brand',
   'docs',
   'launch',
+  'plugin',
   'site/README.md',
   'site/content',
   'README.md',

package/scripts/plugin.mjs

@@ -0,0 +1,64 @@
+#!/usr/bin/env node
+/**
+ * Writes the breakaway plugin's generated files (CLI-7, docs/specs/IDEA-25-claude-plugin.md): the `tasks` skill, made
+ * from .agents/skills/tasks/SKILL.md for any repository, the session hooks from sessionHooks() in src/init.js, and the
+ * licence. Unlike src/board-files.json they're committed, because the plugin is read from git; a test in
+ * scripts/tasks/plugin.test.js fails when one is behind its source. The rest of plugin/ is written by hand.
+ */
+import { readFileSync, writeFileSync } from 'node:fs';
+import { SKILL } from '../src/prompt.js';
+import { sessionHooks, skillFor } from '../src/init.js';
+import { BREAKAWAY_REPO } from '../src/updates.js';
+
+export const BOARD = BREAKAWAY_REPO;
+export const PLUGIN_DIR = 'plugin/';
+
+/**
+ * The tasks skill as the plugin ships it. A plugin works in any checkout, so the skill names no breakaway rule and
+ * links nowhere a checkout may not have: the board's docs and the core point at GitHub, `AGENTS.md` is the checkout's
+ * own. Each change must find its text, so a skill reworded there fails here instead of shipping half changed.
+ */
+export function pluginSkill(text, board = BOARD) {
+  /** @type {[RegExp, string][]} */
+  const changes = [
+    [
+      /breakaway's work is on the board that tracks this repository/gu,
+      "This repository's work is on the board that tracks it",
+    ],
+    [/breakaway's areas: [^.\n]+\./gu, "This repository's areas are in its `AGENTS.md`."],
+    [
+      /\[`prompts\/core\.md`\]\(\.\.\/\.\.\/\.\.\/prompts\/core\.md\)/gu,
+      `the core: \`tools/tasks/prompts/core.md\` in a repository \`repos init\` set up, and [on GitHub](https://github.com/${board}/blob/main/prompts/core.md)`,
+    ],
+    [/\[`AGENTS\.md`\]\(\.\.\/\.\.\/\.\.\/AGENTS\.md\)/gu, '`AGENTS.md`'],
+    [
+      /Follow \[`prompts\/breakaway\.md`\]\(\.\.\/\.\.\/\.\.\/prompts\/breakaway\.md\), which starts with the core\./gu,
+      "Follow the repository's agent prompt, which `AGENTS.md` names and which starts with the core.",
+    ],
+  ];
+  let out = String(text);
+  for (const [pattern, replacement] of changes) {
+    if (!pattern.test(out))
+      throw new Error(`The tasks skill no longer has ${pattern}: update pluginSkill in scripts/plugin.mjs.`);
+    pattern.lastIndex = 0;
+    out = out.replace(pattern, replacement);
+  }
+  // The rest of the board's docs are on GitHub, as they are for a copy (skillFor).
+  return skillFor(out, board);
+}
+
+/** The plugin's generated files, by their path from the repository's root. */
+export function pluginFiles(read) {
+  return {
+    [`${PLUGIN_DIR}skills/tasks/SKILL.md`]: pluginSkill(read(SKILL)),
+    [`${PLUGIN_DIR}hooks/hooks.json`]: `${JSON.stringify({ hooks: sessionHooks() }, null, 2)}\n`,
+    [`${PLUGIN_DIR}LICENSE`]: read('LICENSE'),
+  };
+}
+
+if (import.meta.url === `file://${process.argv[1]}`) {
+  const ROOT = new URL('../', import.meta.url);
+  const read = (/** @type {string} */ path) => readFileSync(new URL(path, ROOT), 'utf8');
+  for (const [path, content] of Object.entries(pluginFiles(read))) writeFileSync(new URL(path, ROOT), content);
+  console.error('Wrote the plugin’s skill, hooks, and licence in plugin/.');
+}

package/scripts/tasks/cli.js

@@ -23,6 +23,7 @@ export const NO_ARGUMENTS = new Set([
   'next',
   'activity',
   'health',
+  'mcp',
   'connections',
   'export',
   'setup',

package/scripts/tasks/hook-config.js

@@ -7,7 +7,7 @@ import { execFileSync } from 'node:child_process';
 import { existsSync, readFileSync, rmSync } from 'node:fs';
 import { homedir } from 'node:os';
 import { join } from 'node:path';
-import { boardUrl, configDir, parseEnvFile, readSetting } from './settings.js';
+import { boardUrl, configDir, parseEnvFile, readSetting, settingFrom } from './settings.js';
 
 /** The git root of the current folder, or null outside a repository. */
 function gitRoot() {
@@ -69,8 +69,9 @@ export function boardConfig(root = projectRoot()) {
     /* the CLI says what's wrong with it */
   }
   const { url } = boardUrl({ env: process.env, file, taskrc: readOptional(join(root, '.taskrc')), config });
-  // In a cloud session there's no token here: the environment's API credential adds it.
-  const token = readSetting('TOKEN', { env: process.env, file });
+  // In a cloud session there's no token here: the environment's API credential adds it. In the plugin's hooks, its
+  // `token` comes after the CLI's own (CLI-8).
+  const token = settingFrom('TOKEN', { env: process.env, file }).value;
   return { base: url, headers: token ? { Authorization: `Bearer ${token}` } : {} };
 }
 

package/scripts/tasks/mcp.js

@@ -0,0 +1,189 @@
+/**
+ * npx breakaway mcp (docs/specs/IDEA-24-mcp-server.md, section 5; CLI-6): how a checkout connects an MCP client to the
+ * board's /mcp, and whether it answers. Pure apart from the `fetch` it's handed, so it's tested without a board.
+ */
+import { githubFromRemote, pickRepo } from './repo.js';
+
+/** The MCP revision `--check` speaks: the one with an `initialize` handshake, which /mcp accepts (src/mcp.js, LEGACY). */
+export const CHECK_PROTOCOL = '2025-11-25';
+/** The server's name in a client's config. */
+export const SERVER = 'breakaway';
+
+const AGENT = /^[\w.@:/-]{1,64}$/u;
+
+/**
+ * The agent name an MCP connection claims as: --as or BREAKAWAY_AGENT (`named`), else `claude-<branch>` for the
+ * checkout's branch, else `fallback` (the CLI's own default). A branch's `/` and anything a name can't hold become `-`.
+ * @param {{ named?: string | null, branch?: string | null, fallback: string }} options
+ */
+export function mcpAgent({ named, branch, fallback }) {
+  if (named) return named;
+  const b = String(branch ?? '').trim();
+  if (!b || b === 'HEAD') return fallback;
+  const name = (/^claude[-/]/u.test(b) ? b : `claude-${b}`).replace(/[^\w.@:-]+/gu, '-').slice(0, 64);
+  return AGENT.test(name) ? name : fallback;
+}
+
+/**
+ * The `claude mcp add` line and the `.mcp.json` entry for a checkout. The token is always the environment variable
+ * `tokenVar`, never its value: the shell fills it in for the line, and Claude Code for `.mcp.json`. Without `repo` (a
+ * checkout the board doesn't track) there's no X-Breakaway-Repo, and the repository's tools say what's missing.
+ * @param {{ url: string, agent: string, repo?: string | null, tokenVar: string }} options
+ * @returns {{ endpoint: string, command: string, json: { mcpServers: Record<string, any> } }}
+ */
+export function mcpConfig({ url, agent, repo = null, tokenVar }) {
+  const endpoint = `${String(url).replace(/\/+$/u, '')}/mcp`;
+  const headers = {
+    Authorization: `Bearer \${${tokenVar}}`,
+    'X-Breakaway-Agent': agent,
+    ...(repo ? { 'X-Breakaway-Repo': repo } : {}),
+  };
+  const command = [
+    `claude mcp add --transport http ${SERVER} ${endpoint}`,
+    `  --header "Authorization: Bearer $${tokenVar}"`,
+    `  --header "X-Breakaway-Agent: ${agent}"`,
+    ...(repo ? [`  --header "X-Breakaway-Repo: ${repo}"`] : []),
+  ].join(' \\\n');
+  return { endpoint, command, json: { mcpServers: { [SERVER]: { type: 'http', url: endpoint, headers } } } };
+}
+
+/**
+ * `--headers`: the headers Claude Code sends to /mcp, for the plugin's `headersHelper` (CLI-9,
+ * docs/specs/IDEA-25-claude-plugin.md, section 4). Claude Code reads them as JSON from standard output, so the token is
+ * its value here, and only there. Outside a repository the board tracks there's only Authorization, and the repository's
+ * tools say what's missing; without a token there's none, so a session's proxy can add it.
+ * @param {{ token?: string | null, agent: string, repo?: string | null }} options
+ * @returns {Record<string, string>}
+ */
+export function mcpHeaders({ token = null, agent, repo = null }) {
+  return {
+    ...(token ? { Authorization: `Bearer ${token}` } : {}),
+    ...(repo ? { 'X-Breakaway-Agent': agent, 'X-Breakaway-Repo': repo } : {}),
+  };
+}
+
+/**
+ * The repository `--headers` names: the board's slug for the checkout when the board says which (`GET /api/repos`), and
+ * null when it tracks none of them. A plugin's headersHelper runs without the plugin's settings, so with only the
+ * plugin set up there's no token to ask with: then it's the checkout's GitHub `owner/name`, which /mcp matches against
+ * its repositories itself (src/mcp.js). `named` is --repo or BREAKAWAY_REPO. Never throws: Claude Code is waiting.
+ * @param {{ base?: string | null, token?: string | null, named?: string | null, remote?: string | null, fetch: typeof globalThis.fetch }} options
+ * @returns {Promise<string | null>}
+ */
+export async function headersRepo({ base = null, token = null, named = null, remote = null, fetch }) {
+  let registry = null;
+  if (base)
+    try {
+      const res = await fetch(`${String(base).replace(/\/+$/u, '')}/api/repos`, {
+        headers: token ? { Authorization: `Bearer ${token}` } : {},
+        signal: AbortSignal.timeout(5000),
+      });
+      if (res.ok) registry = await res.json();
+    } catch {
+      /* the board can't be reached: /mcp will say so itself */
+    }
+  if (registry) {
+    try {
+      return pickRepo({ named, remote, registry });
+    } catch {
+      return null; // --repo names a repository the board doesn't have
+    }
+  }
+  if (named) return String(named).trim().toLowerCase();
+  return githubFromRemote(remote)?.toLowerCase() ?? null;
+}
+
+/**
+ * What `npx breakaway mcp` prints: the line, the `.mcp.json` entry, and what to check.
+ * @param {{ endpoint: string, command: string, json: object }} config
+ * @param {{ repo?: string | null, tokenVar: string }} options
+ */
+export function mcpLines(config, { repo = null, tokenVar }) {
+  return [
+    `Connect Claude Code to the board's MCP server at ${config.endpoint}:`,
+    '',
+    config.command,
+    '',
+    `Run it where ${tokenVar} is set, then type /mcp in Claude Code. Or put this in the checkout's .mcp.json, which`,
+    `Claude Code fills in from ${tokenVar} when it starts:`,
+    '',
+    JSON.stringify(config.json, null, 2),
+    '',
+    ...(repo
+      ? []
+      : [
+          'This checkout isn’t a repository the board tracks, so there’s no X-Breakaway-Repo header: the tools that work',
+          'in a repository will ask for one. Run this in a tracked checkout, or name one with --repo <slug>.',
+          '',
+        ]),
+    `The token is the board's full token: give it only to a client you run. npx breakaway mcp --check tests the connection.`,
+  ];
+}
+
+/**
+ * `--check`: an `initialize` and a `tools/list` against /mcp with the same headers the config sends, and what came
+ * back. `ok` is false with the board's own error when either fails.
+ * @param {{ endpoint: string, token?: string | null, agent: string, repo?: string | null, fetch: typeof globalThis.fetch }} options
+ * @returns {Promise<{ ok: boolean, lines: string[] }>}
+ */
+export async function checkMcp({ endpoint, token = null, agent, repo = null, fetch }) {
+  const headers = {
+    ...(token ? { Authorization: `Bearer ${token}` } : {}),
+    'Content-Type': 'application/json',
+    Accept: 'application/json, text/event-stream',
+    'X-Breakaway-Agent': agent,
+    ...(repo ? { 'X-Breakaway-Repo': repo } : {}),
+  };
+  const rpc = async (id, method, params, version) => {
+    let res;
+    try {
+      res = await fetch(endpoint, {
+        method: 'POST',
+        headers: { ...headers, ...(version ? { 'MCP-Protocol-Version': version } : {}) },
+        body: JSON.stringify({ jsonrpc: '2.0', id, method, params }),
+      });
+    } catch (error) {
+      return { error: `can't reach ${endpoint} (${reasonOf(error)})` };
+    }
+    const data = await res.json().catch(() => null);
+    // An install from before /mcp answers it with the web app, a 404, or a 405: anything but JSON-RPC.
+    if (res.status !== 401 && (res.status === 404 || res.status === 405 || (res.ok && !data?.jsonrpc)))
+      return {
+        error: `${endpoint} answered ${res.status}: this install has no MCP server yet. Update and deploy it (docs/tasks.md#updates).`,
+      };
+    if (res.status === 401)
+      return {
+        error: `${endpoint} refused the token (401)${data?.error ? `: ${data.error}` : ''}${token ? '' : '. No token is set'}`,
+      };
+    if (data?.error)
+      return { error: `${method} failed: ${data.error.message ?? data.error}${res.ok ? '' : ` (HTTP ${res.status})`}` };
+    if (!res.ok || !data?.result) return { error: `${method} failed: HTTP ${res.status}` };
+    return { result: data.result };
+  };
+
+  const init = await rpc(1, 'initialize', {
+    protocolVersion: CHECK_PROTOCOL,
+    capabilities: {},
+    clientInfo: { name: 'breakaway-cli', version: '1' },
+  });
+  if (init.error) return { ok: false, lines: [`The board's MCP server didn't answer: ${init.error}`] };
+  const listed = await rpc(2, 'tools/list', {}, init.result.protocolVersion ?? CHECK_PROTOCOL);
+  if (listed.error) return { ok: false, lines: [`The board's MCP server didn't answer: ${listed.error}`] };
+  const server = init.result.serverInfo ?? {};
+  const tools = (listed.result.tools ?? []).map((t) => t.name);
+  return {
+    ok: true,
+    lines: [
+      `The board's MCP server answers at ${endpoint}: ${server.name ?? SERVER}${server.version ? ` ${server.version}` : ''}, MCP ${init.result.protocolVersion}.`,
+      `${tools.length} tools: ${tools.join(', ') || 'none'}.`,
+      `As ${agent}${repo ? `, in ${repo}` : ', in no repository (set X-Breakaway-Repo, or run it in a tracked checkout)'}.`,
+    ],
+  };
+}
+
+/** Why a fetch failed: the innermost cause, like ECONNREFUSED. */
+function reasonOf(error) {
+  let root = error;
+  while (root?.cause) root = root.cause;
+  return typeof root?.code === 'string' ? root.code : (root?.message ?? String(error));
+}

package/scripts/tasks/message-wait.mjs

@@ -17,12 +17,15 @@ import { readFileSync, rmSync, writeFileSync } from 'node:fs';
 import { tmpdir } from 'node:os';
 import { join } from 'node:path';
 import { setTimeout as sleep } from 'node:timers/promises';
+import { checkoutRunsHooks } from './plugin-hooks.js';
 import { boardConfig, claimedTask, projectRoot } from './hook-config.js';
 import { sessionRequest } from './proxy.js';
 import { waitForMessages } from './session-messages.js';
 
 async function main() {
   const root = projectRoot();
+  // The plugin's copy of this hook steps aside when the checkout's settings run it too (BRK-159).
+  if (checkoutRunsHooks(root)) return 0;
   const claim = claimedTask(root);
   if (!claim?.agent) return 0;
   for await (const _ of process.stdin); // Claude Code sends the hook's input; it isn't needed.

package/scripts/tasks/plugin-env.js

@@ -0,0 +1,37 @@
+/**
+ * Hands the plugin's settings to the session's Bash commands (CLI-8, docs/specs/IDEA-25-claude-plugin.md, section 2).
+ * Claude Code gives a plugin's options to its hooks as CLAUDE_PLUGIN_OPTION_<option>, but not to the commands its
+ * skills run, so `/breakaway:next` would find no board. A SessionStart hook may append `export` lines to
+ * CLAUDE_ENV_FILE, which Claude Code applies to every later Bash command, so the plugin's SessionStart hook passes
+ * them on under the same names: the CLI still reads them after its own settings (scripts/tasks/settings.js).
+ */
+import { appendFileSync } from 'node:fs';
+import { PLUGIN_OPTIONS } from './settings.js';
+
+/** `value` quoted for a POSIX shell. */
+const quote = (value) => `'${String(value).replace(/'/gu, `'\\''`)}'`;
+
+/**
+ * The `export` lines for the plugin's options that are set, or '' outside a plugin's hook (no CLAUDE_PLUGIN_ROOT)
+ * or when none is.
+ * @param {Record<string, string | undefined>} env
+ */
+export function pluginEnvLines(env) {
+  if (!env.CLAUDE_PLUGIN_ROOT) return '';
+  return Object.values(PLUGIN_OPTIONS)
+    .filter((name) => env[name])
+    .map((name) => `export ${name}=${quote(env[name])}\n`)
+    .join('');
+}
+
+/** Appends them to CLAUDE_ENV_FILE when Claude Code gave one (only SessionStart does). Never throws: hooks stay quiet. */
+export function passPluginEnv(env = process.env, append = appendFileSync) {
+  const lines = env.CLAUDE_ENV_FILE ? pluginEnvLines(env) : '';
+  if (!lines) return false;
+  try {
+    append(env.CLAUDE_ENV_FILE, lines, { mode: 0o600 });
+    return true;
+  } catch {
+    return false;
+  }
+}

package/scripts/tasks/plugin-hooks.js

@@ -0,0 +1,32 @@
+/**
+ * The session hooks when breakaway's plugin runs them (BRK-159, docs/specs/IDEA-25-claude-plugin.md, section 7): a
+ * checkout repos init set up before the plugin, or with --copies, runs the same hooks from its .claude/settings.json,
+ * so a person who installed the plugin would post each entry twice. Claude Code sets CLAUDE_PLUGIN_ROOT for a plugin's
+ * hooks, and then the plugin's hooks step aside for the checkout's.
+ */
+import { readFileSync } from 'node:fs';
+import { join } from 'node:path';
+
+/** A session hook command repos init writes: through npx, any version, or an old copy's script. */
+const BOARD_HOOK =
+  /\bbreakaway(?:@[^\s"]+)? hook (?:session|wait)\b|scripts\/tasks\/(?:session-hook|message-wait)\.mjs/u;
+
+/** A file's text, or null when it can't be read. */
+function readOptional(path) {
+  try {
+    return readFileSync(path, 'utf8');
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * Whether this hook is the plugin's and the checkout's settings already run the board's hooks, so this one does
+ * nothing. Outside the plugin it's always false: the checkout's own hooks always run.
+ */
+export function checkoutRunsHooks(root, env = process.env, read = readOptional) {
+  if (!env.CLAUDE_PLUGIN_ROOT) return false;
+  return ['settings.json', 'settings.local.json'].some((name) =>
+    BOARD_HOOK.test(read(join(root, '.claude', name)) ?? ''),
+  );
+}

package/scripts/tasks/session-hook.mjs

@@ -10,14 +10,21 @@
  * Quiet by design: without a claimed task (.task-session, written by `tasks claim`), with
  * BREAKAWAY_SESSION_LOG=off, or on any error, it does nothing and exits 0. A post
  * that fails leaves its reason in the temp folder, which the CLI's next command here shows (BRK-86).
+ *
+ * Run by the plugin at SessionStart, it first passes the plugin's settings on to the session's Bash commands (CLI-8).
  */
+import { checkoutRunsHooks } from './plugin-hooks.js';
 import { boardConfig, claimedTask, dropClaim, projectRoot } from './hook-config.js';
+import { passPluginEnv } from './plugin-env.js';
 import { clearHookFailure, noteHookFailure, sessionRequest } from './proxy.js';
 import { entryFor } from './session-log.js';
 import { CONTEXT_EVENTS, messageOutput, releasedOutput } from './session-messages.js';
 
 async function main() {
+  passPluginEnv();
   const root = projectRoot();
+  // The plugin's copy of this hook steps aside when the checkout's settings run it too (BRK-159).
+  if (checkoutRunsHooks(root)) return;
   const claim = claimedTask(root);
   if (!claim) return;
 

package/scripts/tasks/settings.js

@@ -15,9 +15,21 @@ export const NAMES = Object.freeze({
   SESSION_LOG: 'BREAKAWAY_SESSION_LOG',
 });
 
+/**
+ * The plugin's settings (CLI-8, docs/specs/IDEA-25-claude-plugin.md, section 2): Claude Code asks for them when the
+ * plugin is enabled and hands them to its hooks as CLAUDE_PLUGIN_OPTION_<option>. They come after the CLI's own, so a
+ * machine set up with `npx breakaway setup`, or a cloud session's environment, keeps working unchanged.
+ */
+export const PLUGIN_OPTIONS = Object.freeze({
+  URL: 'CLAUDE_PLUGIN_OPTION_BOARD_URL',
+  TOKEN: 'CLAUDE_PLUGIN_OPTION_TOKEN',
+  AGENT: 'CLAUDE_PLUGIN_OPTION_AGENT_NAME',
+});
+
 /**
  * A setting's value: from the environment first, then the env file, else `fallback`. The environment always wins,
- * so `BREAKAWAY_URL=… npx breakaway` points one command elsewhere.
+ * so `BREAKAWAY_URL=… npx breakaway` points one command elsewhere. The plugin's options aren't read here: see
+ * `settingFrom`.
  */
 export function readSetting(key, { env = {}, file = {} }, fallback) {
   const name = NAMES[key];
@@ -25,6 +37,23 @@ export function readSetting(key, { env = {}, file = {} }, fallback) {
   return env[name] || file[name] || fallback;
 }
 
+/**
+ * A setting's value and where it came from: the environment, then tasks.env, then the plugin's option for it, else
+ * `{ value: undefined, from: null }`. `from` names the source, never the value, so `health` can print it.
+ * @param {string} key
+ * @param {{ env?: Record<string, string | undefined>, file?: Record<string, string> }} sources
+ * @returns {{ value: string | undefined, from: 'environment' | 'tasks.env' | 'plugin' | null }}
+ */
+export function settingFrom(key, { env = {}, file = {} }) {
+  const name = NAMES[key];
+  if (!name) throw new Error(`no setting ${key}`);
+  if (env[name]) return { value: env[name], from: 'environment' };
+  if (file[name]) return { value: file[name], from: 'tasks.env' };
+  const option = PLUGIN_OPTIONS[key];
+  if (option && env[option]) return { value: env[option], from: 'plugin' };
+  return { value: undefined, from: null };
+}
+
 /**
  * This machine's folder for the board (tasks.env, the Taskwarrior credentials, the routines copy):
  * BREAKAWAY_HOME when it's set (one per install, for a machine that uses two), else ~/.config/breakaway.
@@ -45,16 +74,19 @@ export function taskrcUrl(text) {
 }
 
 /**
- * The board's base URL, and where it came from: the environment or env file (BREAKAWAY_URL), else the checkout's own .taskrc (`sync.server.url`, so the CLI and Taskwarrior agree),
- * else the install's breakaway.config.json (`url`), else null: nothing says which board.
+ * The board's base URL, and where it came from: the environment or tasks.env (BREAKAWAY_URL), else the checkout's own
+ * .taskrc (`sync.server.url`, so the CLI and Taskwarrior agree), else the install's breakaway.config.json (`url`), else
+ * the plugin's `board_url` (CLI-8: a setting of the person's, so anything the machine or checkout says comes first),
+ * else null: nothing says which board.
  */
 export function boardUrl({ env = {}, file = {}, taskrc = null, config = null }) {
   const pick = () => {
-    const set = readSetting('URL', { env, file });
-    if (set) return { url: set, from: 'setting' };
+    if (env[NAMES.URL]) return { url: env[NAMES.URL], from: 'environment' };
+    if (file[NAMES.URL]) return { url: file[NAMES.URL], from: 'tasks.env' };
     const rc = taskrcUrl(taskrc);
     if (rc) return { url: rc, from: '.taskrc' };
     if (config?.url) return { url: config.url, from: 'config' };
+    if (env[PLUGIN_OPTIONS.URL]) return { url: env[PLUGIN_OPTIONS.URL], from: 'plugin' };
     return { url: null, from: 'default' };
   };
   const { url, from } = pick();

package/scripts/tasks.mjs

@@ -49,6 +49,8 @@ import { checkInstall, confirmInstall, tokenTarget, unverifiedInstall } from './
 import { NO_TERMINAL, ask as askIn } from './tasks/ask.js';
 import {
   CLI_PACKAGE,
+  PLUGIN_BRANCH,
+  PLUGIN_REPO,
   PROMPT_SECTIONS,
   initCommitMessage,
   initPlan,
@@ -81,10 +83,20 @@ import {
   unknownSubcommand,
 } from './tasks/cli.js';
 import { keepLines } from './tasks/keep.js';
+import { checkMcp, headersRepo, mcpAgent, mcpConfig, mcpHeaders, mcpLines } from './tasks/mcp.js';
 import { mergeViews, pelotonLines, pelotonPost, pickPeloton } from './tasks/peloton.js';
 import { CLI_VERSION } from '../src/cli-version.js';
 import { parseInstall, secretName } from '../src/install.js';
-import { NAMES, boardUrl, configDir, parseEnvFile, readSetting, taskrcFixes, tildePath } from './tasks/settings.js';
+import {
+  NAMES,
+  boardUrl,
+  configDir,
+  parseEnvFile,
+  readSetting,
+  settingFrom,
+  taskrcFixes,
+  tildePath,
+} from './tasks/settings.js';
 
 const CONFIG_DIR = configDir({ env: process.env, home: homedir() });
 const ENV_FILE = join(CONFIG_DIR, 'tasks.env');
@@ -235,6 +247,11 @@ Reading                (list, next, claim, and add work in this checkout's repos
   github                 the checkout's repository on GitHub: open pull requests, checks, reviews, CI, deploys, alerts  [--sync] [--repo <slug>]
   hook session|wait      the Claude Code session hooks a repository's .claude/settings.json runs (npx breakaway hook session)
   health                 the server's state
+  mcp                    print the claude mcp add line and the .mcp.json entry that connect an MCP client to the board's
+                         /mcp from this checkout, with the token as $BREAKAWAY_TOKEN, never its value. Writes nothing
+    --check              …or check the server answers: initialize and tools/list, or the board's error
+    --headers            …or print the headers Claude Code sends to /mcp as JSON, the token included: the plugin's
+                         headersHelper. Only Authorization outside a repository the board tracks
   export                 every task (all repositories, statuses, and horizons) as JSON, checked against health's count  [--out <file>]
   connections            is everything the board leans on wired up: GitHub, Cloudflare, Claude, sync, push; the fix for each that isn't
 
@@ -292,8 +309,12 @@ Working
                          In a terminal it asks for each section of the agent prompt (Enter takes the default), or
                          takes them from --building --checks --pull-requests --direction --dependency-updates
                          --never-share <text>; --defaults takes the default for the rest without asking
-    --update             refresh the copied files (the CLI, core, skill, Taskwarrior files) in a pull request when they're
-                         older than this checkout's; the repository's own (its prompt, AGENTS.md) are never touched
+                         The tasks skill and the session hooks come from breakaway's Claude Code plugin, which
+                         .claude/settings.json turns on; until the plugin is out, they're copied, and it says so
+    --update             refresh the copied files (core, Taskwarrior files, release helpers) in a pull request when
+                         they're older than this checkout's, and move a repository with copies to the plugin; the
+                         repository's own (its prompt, AGENTS.md) are never touched
+    --copies             copy the tasks skill and the session hooks instead of using the plugin (with or without --update)
     --pipeline           also add the deploy flow: .github/breakaway-pipeline.json for the Workers --staging <name> and
                          --production <name> (asked in a terminal; default <slug>-staging and <slug>), what it renders,
                          and a minimal CI when the repository has no workflow. Only new files: never one it already has
@@ -361,7 +382,9 @@ Projects: ideas and routines are the board's; repos lists each repository's area
 
 Settings: BREAKAWAY_TOKEN, BREAKAWAY_URL, BREAKAWAY_AGENT, BREAKAWAY_REPO, from the environment or tasks.env in
   $BREAKAWAY_HOME (default ~/.config/breakaway).
-  Without BREAKAWAY_URL the board is this checkout's .taskrc sync.server.url. See docs/tasks.md#another-install.`;
+  Without BREAKAWAY_URL the board is this checkout's .taskrc sync.server.url. See docs/tasks.md#another-install.
+  Last come the breakaway plugin's settings for Claude Code (board_url, token, agent_name). health says which
+  source each setting came from.`;
 
 // ---- settings ----------------------------------------------------------------------------
 
@@ -370,8 +393,11 @@ function readEnvFile() {
 }
 
 const fileEnv = readEnvFile();
-/** A setting by its key in NAMES (scripts/tasks/settings.js): `TOKEN` reads BREAKAWAY_TOKEN. */
-const setting = (key, fallback) => readSetting(key, { env: process.env, file: fileEnv }, fallback);
+/**
+ * A setting by its key in NAMES (scripts/tasks/settings.js): `TOKEN` reads BREAKAWAY_TOKEN, then the plugin's `token`
+ * when the CLI runs in a Claude Code session with the breakaway plugin (CLI-8).
+ */
+const setting = (key, fallback) => settingFrom(key, { env: process.env, file: fileEnv }).value ?? fallback;
 const BOARD = boardUrl({
   env: process.env,
   file: fileEnv,
@@ -417,9 +443,11 @@ const FLAGS = new Set([
   'update',
   'defaults',
   'package',
+  'check',
+  'headers',
 ]);
 /** Flags only in repos init (BRK-91): --pipeline takes a file in repos modify, and is a flag there. */
-const INIT_FLAGS = new Set(['pipeline']);
+const INIT_FLAGS = new Set(['pipeline', 'copies']);
 
 function parse(argv) {
   const positional = [];
@@ -474,7 +502,7 @@ async function call(method, path, body, { soft = false } = {}) {
   warnIfStale(res.headers.get('X-Tasks-Cli'), res.headers.get('X-Tasks-Release'));
   if (res.status === 401 && !token)
     fail(
-      `no token. Set BREAKAWAY_TOKEN, put it in ${ENV_FILE}, or add it as an API credential in the cloud environment (see docs/tasks.md#cloud-agents).`,
+      `no token. Set BREAKAWAY_TOKEN, put it in ${ENV_FILE}, set it in the breakaway plugin's settings, or add it as an API credential in the cloud environment (see docs/tasks.md#cloud-agents).`,
     );
   const data = await res.json().catch(() => ({
     // The board always answers in JSON, so anything else came from something in between.
@@ -797,6 +825,29 @@ function changesFrom(o) {
   return c;
 }
 
+/** Where the board's address, token, and agent name came from (CLI-8): the sources only, never a value. */
+function settingSources() {
+  const sources = { env: process.env, file: fileEnv };
+  return { url: BOARD.from, token: settingFrom('TOKEN', sources).from, agent: settingFrom('AGENT', sources).from };
+}
+
+const SOURCE = {
+  environment: 'the environment',
+  'tasks.env': ENV_FILE,
+  '.taskrc': "this checkout's .taskrc",
+  config: "the install's breakaway.config.json",
+  plugin: "the breakaway plugin's settings",
+};
+
+/** settingSources() in a line: `address from …, token from …, agent name from …`. */
+function describeSources({ url, token, agent: name }) {
+  return [
+    `address from ${SOURCE[url] ?? 'nowhere'}`,
+    `token ${token ? `from ${SOURCE[token]}` : "not set (a cloud session's proxy may add it)"}`,
+    `agent name ${name ? `from ${SOURCE[name]}` : 'not set'}`,
+  ].join(', ');
+}
+
 const commands = {
   /** The Claude Code session hooks (BRK-7), so a repository's .claude/settings.json runs them through npx. */
   async hook() {
@@ -1573,12 +1624,68 @@ const commands = {
       return out.join('\n');
     });
   },
+  /** How to connect an MCP client to the board's /mcp from this checkout, and --check whether it answers (CLI-6). */
+  async mcp() {
+    // --headers is the plugin's headersHelper: it asks the board itself, and never fails (CLI-9).
+    const { slug } = opts.headers ? { slug: null } : await checkoutRepo();
+    let branch = null;
+    try {
+      branch = execFileSync('git', ['rev-parse', '--abbrev-ref', 'HEAD'], {
+        encoding: 'utf8',
+        stdio: ['ignore', 'pipe', 'ignore'],
+      }).trim();
+    } catch {
+      /* not a git checkout */
+    }
+    const name = mcpAgent({ named: opts.as ?? setting('AGENT'), branch, fallback: agent() });
+    if (opts.headers) {
+      const token = setting('TOKEN');
+      let remote = null;
+      try {
+        remote = execFileSync('git', ['remote', 'get-url', 'origin'], {
+          encoding: 'utf8',
+          stdio: ['ignore', 'pipe', 'ignore'],
+        });
+      } catch {
+        /* not a git checkout, or no origin */
+      }
+      // Claude Code says which server it's connecting: the plugin's board_url, when the CLI's settings don't name one.
+      const server = process.env.CLAUDE_CODE_MCP_SERVER_URL?.replace(/\/mcp\/?$/u, '');
+      const repo = await headersRepo({
+        base: BASE ?? (server?.startsWith('http') ? server : null),
+        token,
+        named: opts.repo ?? setting('REPO'),
+        remote,
+        fetch,
+      });
+      // Standard output is Claude Code's, and only the headers go there: never --json's wrapping, never a line of text.
+      console.log(JSON.stringify(mcpHeaders({ token, agent: name, repo })));
+      return;
+    }
+    const tokenVar = envName('TOKEN');
+    const config = mcpConfig({ url: BASE, agent: name, repo: slug, tokenVar });
+    if (!opts.check) {
+      print(config, () => mcpLines(config, { repo: slug, tokenVar }).join('\n'));
+      return;
+    }
+    const checked = await checkMcp({
+      endpoint: config.endpoint,
+      token: setting('TOKEN'),
+      agent: name,
+      repo: slug,
+      fetch,
+    });
+    print(checked, (c) => c.lines.join('\n'));
+    if (!checked.ok) process.exitCode = 1;
+  },
   async health() {
-    print(await call('GET', 'health'), (h) =>
+    const settings = settingSources();
+    print({ ...(await call('GET', 'health')), settings }, (h) =>
       [
         h.ok ? 'The task server is healthy.' : `The task server can't read its history: ${h.replicaError}`,
         `  ${h.tasks.pending} open of ${h.tasks.total} tasks, ${h.versions} versions`,
         `  snapshot: ${h.snapshot ? `${h.snapshot.created.slice(0, 16)}, ${h.snapshot.versionsSince} versions since` : 'none'}`,
+        `  settings: ${describeSources(settings)}`,
       ].join('\n'),
     );
   },
@@ -2019,7 +2126,10 @@ async function initRepo(slug) {
     /* not a git checkout */
   }
   const answers = update || readTarget(promptPathOf(repo)) !== null ? {} : await promptAnswers();
+  const plugin = !opts.copies;
   const plan = initPlan({
+    plugin,
+    pluginReleased: plugin ? pluginReleased() : false,
     repo,
     board: board ?? 'TheAnarchoX/breakaway',
     url: BASE,
@@ -2071,7 +2181,7 @@ async function initRepo(slug) {
       : []),
     ...(plan.removals.length
       ? [
-          `${opts['dry-run'] ? 'Would remove' : 'Removing'} ${plan.removals.length} files of the old copy of the CLI (npx breakaway replaces it):`,
+          `${opts['dry-run'] ? 'Would remove' : 'Removing'} ${plan.removals.length} files the board no longer copies here (npx breakaway${plan.plugin ? " and breakaway's plugin replace" : ' replaces'} them):`,
           ...plan.removals.map((p) => `  ${p}`),
         ]
       : []),
@@ -2134,7 +2244,8 @@ async function initRepo(slug) {
     );
   }
   const first = initCommitMessage(repo.slug, {
-    by: `npx breakaway repos init ${repo.slug}${opts.pipeline ? ' --pipeline' : ''}${opts.package ? ' --package' : ''}`,
+    by: `npx breakaway repos init ${repo.slug}${opts.copies ? ' --copies' : ''}${opts.pipeline ? ' --pipeline' : ''}${opts.package ? ' --package' : ''}`,
+    plugin: plan.plugin,
   });
   const title = update ? "Update the task board's agent files" : first.title;
   git(
@@ -2143,7 +2254,7 @@ async function initRepo(slug) {
     title,
     '-m',
     update
-      ? `The board's core, skill, release helpers, and Taskwarrior files as they are in ${board ?? 'breakaway'} now, and the session hooks run through npx, so an old copy of the CLI is removed: run it as npx ${CLI_PACKAGE}. This repository's own files are unchanged. Updated by npx ${CLI_PACKAGE} repos init ${repo.slug} --update.`
+      ? `The board's core, ${plan.plugin ? '' : 'skill, '}release helpers, and Taskwarrior files as they are in ${board ?? 'breakaway'} now, ${plan.plugin ? "and breakaway's Claude Code plugin in .claude/settings.json instead of the copied tasks skill and session hooks" : 'and the session hooks run through npx'}, so an old copy of the CLI is removed: run it as npx ${CLI_PACKAGE}. This repository's own files are unchanged. Updated by npx ${CLI_PACKAGE} repos init ${repo.slug} --update${opts.copies ? ' --copies' : ''}.`
       : `${first.body}${starter.files.length ? ` It also adds the deploy and release flows, rendered from ${starter.files[0].path}.` : ''}`,
   );
   const pushed = spawnSync('git', ['-C', dir, 'push', '-u', 'origin', empty ? `HEAD:refs/heads/${branch}` : work], {
@@ -2169,7 +2280,7 @@ async function initRepo(slug) {
         title,
         '--body',
         update
-          ? `The task board's copied files (its CLI, the core and stub, the tasks skill, and the Taskwarrior files) as they are on the board's repository now, updated by \`npx breakaway repos init ${repo.slug} --update\`. This repository's own files (its agent prompt, AGENTS.md, .taskrc, .envrc, package.json, .claude/settings.json) are unchanged.`
+          ? `The task board's copied files (the core and stub, ${plan.plugin ? '' : 'the tasks skill, '}the release helpers, and the Taskwarrior files) as they are on the board's repository now, updated by \`npx breakaway repos init ${repo.slug} --update${opts.copies ? ' --copies' : ''}\`. ${plan.plugin ? "The tasks skill and the session hooks come from breakaway's Claude Code plugin, which .claude/settings.json turns on, so their copies are removed. " : ''}This repository's own files (its agent prompt, AGENTS.md, .taskrc, .envrc, package.json${plan.plugin ? '' : ', .claude/settings.json'}) are otherwise unchanged.${plan.notes.length ? `\n\nNotes:\n${plan.notes.map((n) => `- ${n}`).join('\n')}` : ''}`
           : `The files the task board's agents need to claim and work a task in this repository, added by \`npx breakaway repos init ${repo.slug}\`. Nothing that was there is changed. If this repository's linter reads plain JavaScript, exclude the copied scripts (tools/tasks/ and the release helpers) from it.${plan.todo.length ? `\n\nStill to do:\n${plan.todo.map((t) => `- ${t}`).join('\n')}` : ''}`,
       ],
       { encoding: 'utf8' },
@@ -2189,6 +2300,24 @@ async function initRepo(slug) {
   console.log(['', ...next].join('\n'));
 }
 
+/**
+ * Whether breakaway's plugin is out (BRK-159): its marketplace gives it out from the plugin branch, which a stable
+ * release moves, so until that branch is there, repos init copies the skill and hooks instead. Null when GitHub can't
+ * be reached, which repos init says, and copies too.
+ */
+function pluginReleased() {
+  try {
+    const heads = execFileSync(
+      'git',
+      ['ls-remote', '--heads', `https://github.com/${PLUGIN_REPO}.git`, `refs/heads/${PLUGIN_BRANCH}`],
+      { encoding: 'utf8', stdio: ['ignore', 'pipe', 'ignore'], timeout: 20_000 },
+    );
+    return heads.trim() !== '';
+  } catch {
+    return null;
+  }
+}
+
 /**
  * The staging and production Workers for repos init --pipeline (BRK-91): --staging and --production, else asked in a
  * terminal, else `<slug>-staging` and `<slug>`.
@@ -2411,9 +2540,10 @@ if (opts.help || command === 'help') {
   process.exitCode = (await import('./tasks/pipeline.js')).run(args, opts);
 } else if (!commands[command]) {
   fail(`no command "${command}". npx breakaway help lists them.`);
-} else if (!BASE && command !== 'init-secrets') {
+} else if (!BASE && command !== 'init-secrets' && command !== 'hook') {
+  // The hooks stay quiet without a board (a plugin installed but not set up, CLI-8): session-hook.mjs checks for itself.
   fail(
-    `no board address. Set BREAKAWAY_URL (in the environment or ${ENV_FILE}), or sync.server.url in this checkout's .taskrc: see docs/tasks.md#another-install.`,
+    `no board address. Set BREAKAWAY_URL (in the environment or ${ENV_FILE}), sync.server.url in this checkout's .taskrc, or the board's address in the breakaway plugin's settings (or run npx breakaway setup): see docs/tasks.md#another-install.`,
   );
 } else if (unknownSubcommand(command, args[0])) {
   fail(unknownSubcommand(command, args[0]));

package/src/init.js

@@ -62,6 +62,101 @@ const TARGET_DIR = 'tools/tasks/';
  */
 export const MANIFEST = `${TARGET_DIR}copied.json`;
 const GITIGNORE = ['.task/', '.task-session', '.env'];
+
+/**
+ * breakaway's Claude Code plugin (docs/specs/IDEA-25-claude-plugin.md, section 3): repos init sets a repository up with
+ * it by default (BRK-158), so .claude/settings.json names breakaway's marketplace and turns the plugin on instead of
+ * running the session hooks, and the tasks skill comes with the plugin instead of a copy. The marketplace lives on
+ * breakaway's own repository, and gives out the plugin from its `plugin` branch, which moves at a stable release.
+ */
+export const PLUGIN_REPO = 'TheAnarchoX/breakaway';
+export const PLUGIN_MARKETPLACE = 'breakaway';
+export const PLUGIN = `breakaway@${PLUGIN_MARKETPLACE}`;
+export const PLUGIN_BRANCH = 'plugin';
+
+/** The two keys .claude/settings.json gets for the plugin: breakaway's marketplace, and the plugin turned on. */
+export function pluginSettings() {
+  return {
+    extraKnownMarketplaces: { [PLUGIN_MARKETPLACE]: { source: { source: 'github', repo: PLUGIN_REPO } } },
+    enabledPlugins: { [PLUGIN]: true },
+  };
+}
+
+/** Whether a hook command is one of the session hooks repos init wrote: through npx, any version, or an old copy's. */
+const BOARD_HOOK =
+  /\bbreakaway(?:@[^\s"]+)? hook (?:session|wait)\b|scripts\/tasks\/(?:session-hook|message-wait)\.mjs/u;
+
+/**
+ * settings.json moved to the plugin (repos init --update): the session hooks repos init wrote are gone, with any event
+ * left empty, and the plugin's two keys are there. A plugin the settings turn off stays off, and the rest is untouched.
+ * Null when it isn't JSON, so the caller says what to do instead.
+ */
+export function withPluginSettings(text) {
+  let settings;
+  try {
+    settings = JSON.parse(text);
+  } catch {
+    return null;
+  }
+  if (!settings || typeof settings !== 'object' || Array.isArray(settings)) return null;
+  const hooks = settings.hooks;
+  if (hooks && typeof hooks === 'object') {
+    for (const [event, groups] of Object.entries(hooks)) {
+      if (!Array.isArray(groups)) continue;
+      const kept = groups
+        .map((group) =>
+          Array.isArray(group?.hooks)
+            ? { ...group, hooks: group.hooks.filter((h) => !BOARD_HOOK.test(String(h?.command ?? ''))) }
+            : group,
+        )
+        .filter((group, i) => !(Array.isArray(group?.hooks) && !group.hooks.length && groups[i].hooks.length));
+      if (kept.length) hooks[event] = kept;
+      else delete hooks[event];
+    }
+    if (!Object.keys(hooks).length) delete settings.hooks;
+  }
+  const want = pluginSettings();
+  settings.extraKnownMarketplaces = {
+    ...want.extraKnownMarketplaces,
+    ...settings.extraKnownMarketplaces,
+  };
+  if (typeof settings.enabledPlugins?.[PLUGIN] !== 'boolean')
+    settings.enabledPlugins = { ...settings.enabledPlugins, ...want.enabledPlugins };
+  return `${JSON.stringify(settings, null, 2)}\n`;
+}
+
+/** Whether two JSON texts hold the same value, whatever their layout. */
+const sameJson = (a, b) => {
+  try {
+    return JSON.stringify(JSON.parse(a)) === JSON.stringify(JSON.parse(b));
+  } catch {
+    return false;
+  }
+};
+
+/** Whether settings.json already has the plugin: breakaway's marketplace, and the plugin named in enabledPlugins. */
+function hasPlugin(text) {
+  try {
+    const settings = JSON.parse(text);
+    return (
+      Boolean(settings?.extraKnownMarketplaces?.[PLUGIN_MARKETPLACE]) && PLUGIN in (settings?.enabledPlugins ?? {})
+    );
+  } catch {
+    return false;
+  }
+}
+
+/**
+ * Why repos init copies the tasks skill and the session hooks when it was asked for the plugin: the plugin isn't out
+ * yet (its branch isn't there), or GitHub couldn't say (`released` null).
+ */
+export function pluginPendingNote(slug, released = false) {
+  const why =
+    released === null
+      ? `GitHub couldn't say whether breakaway's plugin is out yet (the ${PLUGIN_BRANCH} branch on ${PLUGIN_REPO})`
+      : `breakaway's plugin isn't out yet (${PLUGIN_REPO} has no ${PLUGIN_BRANCH} branch until a stable release moves it)`;
+  return `${why}, so this copies the tasks skill and the session hooks instead. Once it's out, npx breakaway repos init ${slug} --update moves the repository to the plugin.`;
+}
 /** Pinned to LF so the shell scripts run on a checkout with core.autocrlf=true (BRK-41). */
 const GITATTRIBUTES = ['scripts/task text eol=lf', '.envrc text eol=lf'];
 
@@ -75,10 +170,13 @@ export function boardSources(read) {
 }
 
 /** The first commit's message for a repository set up from scratch: its title and body, the CLI's and the board's alike. */
-export function initCommitMessage(slug, { by = `npx breakaway repos init ${slug}` } = {}) {
+export function initCommitMessage(slug, { by = `npx breakaway repos init ${slug}`, plugin = true } = {}) {
+  const agentParts = plugin
+    ? "breakaway's Claude Code plugin, turned on in .claude/settings.json (it brings the tasks skill and the session hooks)"
+    : 'the session hooks (they run the CLI through npx), the tasks skill';
   return {
     title: "Set up the task board's agent files",
-    body: `What a board-started agent needs to claim and work a task here: the agent prompt, the board's core, the session hooks (they run the CLI through npx), the tasks skill, AGENTS.md, and Taskwarrior with direnv. Added by ${by}.`,
+    body: `What a board-started agent needs to claim and work a task here: the agent prompt, the board's core, ${agentParts}, AGENTS.md, and Taskwarrior with direnv. Added by ${by}.`,
   };
 }
 
@@ -310,14 +408,20 @@ export function skillFor(text, board, repo = null) {
 }
 
 /** A starter AGENTS.md: how this repository works with the board. The owner adds how to build here. */
-export function agentsMd(repo, board, dir = DEFAULT_DIR) {
+export function agentsMd(repo, board, dir = DEFAULT_DIR, { plugin = true } = {}) {
+  const skill = plugin
+    ? `Use the \`tasks\` skill (from breakaway's Claude Code plugin, which \`.claude/settings.json\` turns on) and the CLI, \`npx breakaway\` (the \`breakaway\` package on npm), to claim, comment, and hand over. It works in this checkout's repository, so \`list\` and \`next\` show only this repository's tasks. The skill is the board's, written for any repository: this repository's areas are above, and its rules are here.`
+    : `Use the \`tasks\` skill (\`${SKILL}\`) and the CLI, \`npx breakaway\` (the \`breakaway\` package on npm), to claim, comment, and hand over. It works in this checkout's repository, so \`list\` and \`next\` show only this repository's tasks. The skill is breakaway's, written for this repository's areas and prompt: where it names breakaway's own files or rules, the board's part applies and the rest doesn't.`;
+  const copied = plugin
+    ? `\`tools/tasks/\`, the release helpers in \`scripts/\`, and \`${PIPELINE_SKILL}\` come from [${board}](https://github.com/${board}). Don't edit them here: change them there. \`${MANIFEST}\` lists every file it copied, and \`repos init --update\` replaces only those: a file it doesn't list is this repository's own, even at a path breakaway copies to. \`.claude/settings.json\` turns on breakaway's plugin (\`${PLUGIN}\`), which brings the \`tasks\` skill, its commands, and the session hooks that show a cloud agent's output on its task, so this repository carries no copy of them.`
+    : `\`tools/tasks/\`, the release helpers in \`scripts/\`, \`${SKILL}\`, and \`${PIPELINE_SKILL}\` come from [${board}](https://github.com/${board}). Don't edit them here: change them there. \`${MANIFEST}\` lists every file it copied, and \`repos init --update\` replaces only those: a file it doesn't list is this repository's own, even at a path breakaway copies to. \`.claude/settings.json\` holds the session hooks that show a cloud agent's output on its task, and they run through \`npx\`, so this repository carries no copy of the CLI.`;
   return `# Agent instructions
 
 <!-- Started by \`npx breakaway repos init\` (breakaway's task board). Add how to build here: setup, tests, style, and anything agents must never do. -->
 
-- **Work lives on the task board.** This repository's tasks are in the areas ${areaList(repo)}. Use the \`tasks\` skill (\`${SKILL}\`) and the CLI, \`npx breakaway\` (the \`breakaway\` package on npm), to claim, comment, and hand over. It works in this checkout's repository, so \`list\` and \`next\` show only this repository's tasks. The skill is breakaway's, written for this repository's areas and prompt: where it names breakaway's own files or rules, the board's part applies and the rest doesn't.
+- **Work lives on the task board.** This repository's tasks are in the areas ${areaList(repo)}. ${skill}
 - **Agents started by the board** follow [\`${promptPathOf(repo)}\`](${promptPathOf(repo)}), which starts with the board's core, \`tools/tasks/prompts/core.md\`.
-- **Copied files.** \`tools/tasks/\`, the release helpers in \`scripts/\`, \`${SKILL}\`, and \`${PIPELINE_SKILL}\` come from [${board}](https://github.com/${board}). Don't edit them here: change them there. \`${MANIFEST}\` lists every file it copied, and \`repos init --update\` replaces only those: a file it doesn't list is this repository's own, even at a path breakaway copies to. \`.claude/settings.json\` holds the session hooks that show a cloud agent's output on its task, and they run through \`npx\`, so this repository carries no copy of the CLI.
+- **Copied files.** ${copied}
 - **Taskwarrior** (optional): \`scripts/task\`, or plain \`task\` with direnv after \`direnv allow\`, uses the board with this checkout's own \`.task/\` database, in the \`${repo.slug}\` context. \`npx breakaway setup\` connects the machine once.
 - **Changes reach \`${repo.defaultBranch || 'main'}\` through pull requests**, which the owner merges. Never merge, force-push, or rewrite \`${repo.defaultBranch || 'main'}\`.
 - **Never put a secret or token** in a file, task, comment, or pull request. The board's token lives in \`${dir}/tasks.env\` (or \`$BREAKAWAY_HOME/tasks.env\`) or the cloud environment's credentials, never in this repository.
@@ -368,6 +472,8 @@ export function initPlan({
   url,
   configDir = DEFAULT_DIR,
   update = false,
+  plugin = true,
+  pluginReleased = true,
   sections = {},
   defaulted = [],
 }) {
@@ -376,6 +482,9 @@ export function initPlan({
   const current = [];
   const notes = [];
   const todo = [];
+  // The plugin unless the repository asked for copies (--copies), and copies while the plugin isn't out yet.
+  const usePlugin = plugin && pluginReleased === true;
+  if (plugin && !usePlugin) notes.push(pluginPendingNote(repo.slug, pluginReleased));
   const add = (path, content, extra = {}) => {
     if (readTarget(path) !== null) skipped.push(path);
     else files.push({ path, content, ...extra });
@@ -455,8 +564,22 @@ export function initPlan({
       `${leftover.join(', ')} came with the old copy of the CLI. Nothing here needs them now: delete the ones this repository doesn't use itself.`,
     );
 
-  add('.claude/settings.json', `${JSON.stringify({ hooks: sessionHooks() }, null, 2)}\n`);
-  if (skipped.includes('.claude/settings.json')) {
+  add(
+    '.claude/settings.json',
+    `${JSON.stringify(usePlugin ? pluginSettings() : { hooks: sessionHooks() }, null, 2)}\n`,
+  );
+  if (usePlugin && skipped.includes('.claude/settings.json')) {
+    // Moving to the plugin (BRK-159): --update takes out the hooks repos init wrote and adds the plugin's two keys.
+    const there = readTarget('.claude/settings.json');
+    const moved = withPluginSettings(there);
+    if (update && moved !== null && !sameJson(moved, there)) {
+      skipped.splice(skipped.indexOf('.claude/settings.json'), 1);
+      files.push({ path: '.claude/settings.json', content: moved, changed: true });
+    } else if (!hasPlugin(there))
+      notes.push(
+        `.claude/settings.json is already there${moved === null ? " and isn't JSON" : ''}: add breakaway's plugin to it (${JSON.stringify(pluginSettings())}), or a started agent won't have the tasks skill and its output won't show on its task.${update ? '' : ` npx breakaway repos init ${repo.slug} --update adds it.`}`,
+      );
+  } else if (skipped.includes('.claude/settings.json')) {
     const there = readTarget('.claude/settings.json');
     const rewired = update ? rewireHooks(there) : there;
     if (rewired !== there) {
@@ -471,9 +594,19 @@ export function initPlan({
       );
   }
   if (readTarget('.claude/skills') === null) files.push({ path: '.claude/skills', link: '../.agents/skills' });
-  copy(SKILL, skillFor(read(SKILL), board, repo));
+  if (!usePlugin) copy(SKILL, skillFor(read(SKILL), board, repo));
+  else if (update && readTarget(SKILL) !== null) {
+    // The plugin brings the tasks skill: the copy repos init wrote goes, and a skill of the repository's own stays.
+    if (owns(SKILL)) {
+      removals.push(SKILL);
+      if (String(readTarget('AGENTS.md') ?? '').includes(SKILL))
+        notes.push(
+          `AGENTS.md still names ${SKILL} and the session hooks in .claude/settings.json: the tasks skill and the hooks come from breakaway's plugin now (${PLUGIN}, turned on in .claude/settings.json), so say that there instead.`,
+        );
+    } else theirs.push(SKILL);
+  }
   copy(PIPELINE_SKILL, skillFor(read(PIPELINE_SKILL), board, repo));
-  add('AGENTS.md', agentsMd(repo, board, configDir));
+  add('AGENTS.md', agentsMd(repo, board, configDir, { plugin: usePlugin }));
   if (!skipped.includes('AGENTS.md')) todo.push('AGENTS.md: add how to build in this repository');
 
   const pkg = readTarget('package.json');
@@ -564,5 +697,5 @@ export function initPlan({
   else if (recordThere === record) current.push(MANIFEST);
   else if (update) files.push({ path: MANIFEST, content: record, changed: true });
   else skipped.push(MANIFEST);
-  return { files, removals, skipped, current, notes, todo };
+  return { files, removals, skipped, current, notes, todo, plugin: usePlugin };
 }

package/src/install.js

@@ -158,7 +158,17 @@ export const secretName = (inst, key) => `${inst.secretsPrefix}${key}`;
 export const docsLink = (inst, anchor) => (inst.docs ? `${inst.docs}${anchor ? `#${anchor}` : ''}` : null);
 
 /** The routes `run_worker_first` sends to the Worker; everything else is the web app. */
-export const WORKER_FIRST = ['/api/*', '/v1/*', '/github/*', '/login', '/logout'];
+export const WORKER_FIRST = [
+  '/api/*',
+  '/v1/*',
+  '/github/*',
+  '/mcp',
+  // The sign-in Claude's apps use for /mcp (BRK-157).
+  '/oauth/*',
+  '/.well-known/oauth-*',
+  '/login',
+  '/logout',
+];
 
 /**
  * The Worker's wrangler config for an install. `local` is for `wrangler dev` (interop): no custom