breakaway 1.2.1-main.2 → 1.2.1-main.21

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

@@ -19,7 +19,7 @@ breakaway's work is on the board that tracks this repository. The CLI is `npx br
 
    A `409` means someone has it or it's blocked. Pick another; never `--force` someone else's claim.
 4. **Read it:** `tasks show <ID>` (description, done when, comments, spec, what it waits for and holds up), then [`AGENTS.md`](../../../AGENTS.md) if you haven't this session.
-5. **Work** on a branch. Record what you learn as you go: `tasks comment <ID> "<finding>"`. Comments are append-only; the description is the current brief, and you edit it only on a task you made or are refining. New work you find becomes `tasks add "<title>" --project <area> --tag agent|owner --horizon <h> --brief "<what and why>" --done-when "<done when>"`, with `--depends <ID>` when it waits for something. breakaway's areas: `board`, `web`, `docs`, `launch`, `brand`.
+5. **Work** on a branch. Record what you learn as you go: `tasks comment <ID> "<finding>"`. Comments are append-only; the description is the current brief, and you edit it only on a task you made or are refining. New work you find becomes `tasks add "<title>" --project <area> --tag agent|owner --horizon <h> --brief "<what and why>" --done-when "<done when>"`, with `--depends <ID>` when it waits for something. breakaway's areas: `board`, `web`, `docs`, `launch`, `brand`, `cli`.
 6. **Hand over:** open the pull request with `Closes <ID>.` in its description, then `tasks modify <ID> --pr <number>` and `tasks comment <ID> "<one-line result>"`. The board moves the task to In review and marks it done when the pull request merges; don't mark it done yourself. If you stop before a pull request: `comment` where you got to, then `release <ID>`.
 
 ## Rules

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "breakaway",
-  "version": "1.2.1-main.2",
+  "version": "1.2.1-main.21",
   "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/prompts/breakaway.md

@@ -9,7 +9,7 @@ The routine on claude.ai holds only the stub, [`prompts/stub.md`](stub.md), whic
 
 ## Repository
 
-breakaway: the repository whose `origin` ends with `/breakaway`. Its areas on the board, with their work-ID prefixes: board (`BRK`), web (`WEB`), docs (`DOC`), launch (`LCH`), and brand (`ID`). Its rules are in `AGENTS.md`; read it first, then the `tasks` skill (`.agents/skills/tasks/SKILL.md`).
+breakaway: the repository whose `origin` ends with `/breakaway`. Its areas on the board, with their work-ID prefixes: board (`BRK`), web (`WEB`), docs (`DOC`), launch (`LCH`), brand (`ID`), and cli (`CLI`). Its rules are in `AGENTS.md`; read it first, then the `tasks` skill (`.agents/skills/tasks/SKILL.md`).
 
 ## Building
 

package/scripts/tasks/cli.js

@@ -6,10 +6,11 @@ import { CLI_PACKAGE } from './init.js';
 
 /** The subcommands each command knows. Without one, each lists or shows (horizon needs close). */
 export const SUBCOMMANDS = {
-  agents: ['next', 'start', 'refine'],
+  agents: ['next', 'start', 'refine', 'new'],
   github: ['fix', 'review'],
   repos: ['add', 'init', 'modify', 'remove', 'setup'],
   routines: ['add', 'modify', 'run', 'trigger', 'revoke', 'pause', 'resume'],
+  features: ['list', 'add', 'show', 'modify'],
   horizon: ['close'],
   hook: ['session', 'wait'],
 };
@@ -79,14 +80,14 @@ export const FIX_PROBLEMS = ['conflicts', 'failing', 'review'];
 
 /**
  * The request behind `npx breakaway github fix <n>` and `github review <n>` (BRK-81): the pull request page's "Fix with an
- * agent" and "Safe to merge?" buttons (`POST github/pulls/<n>/fix` and `/review`). It names the checkout's repository
+ * agent" and "Safe to merge?" or "Review with an agent" buttons (`POST github/pulls/<n>/fix` and `/review`). It names the checkout's repository
  * like `github` does. Returns an error message instead when the number or `problem` can't be right.
  * @param {'fix' | 'review'} action
  * @param {string | number | undefined} number
- * @param {{ repo?: string | null, problem?: string, note?: string }} [options]
- * @returns {{ error?: string, request?: [string, string, Record<string, string>] }}
+ * @param {{ repo?: string | null, problem?: string, note?: string, force?: boolean, by?: string }} [options]
+ * @returns {{ error?: string, request?: [string, string, Record<string, string | boolean>] }}
  */
-export function pullAgentRequest(action, number, { repo = null, problem, note } = {}) {
+export function pullAgentRequest(action, number, { repo = null, problem, note, force = false, by } = {}) {
   const n = String(number ?? '').replace(/^#/u, '');
   if (!/^[1-9]\d{0,8}$/u.test(n)) return { error: `say which pull request: npx breakaway github ${action} <number>` };
   if (problem !== undefined && action !== 'fix') return { error: '--problem is for github fix' };
@@ -96,20 +97,94 @@ export function pullAgentRequest(action, number, { repo = null, problem, note }
     ...(repo ? { repo } : {}),
     ...(problem ? { problem } : {}),
     ...(typeof note === 'string' && note.trim() ? { note } : {}),
+    // Review with an agent is the owner's, so a review always says who asks (BRK-111); a fix only when forcing.
+    ...(action === 'review' ? { ...(force ? { force: true } : {}), ...(by ? { by } : {}) } : forceFields(force, by)),
   };
   return { request: ['POST', `github/pulls/${n}/${action}`, body] };
 }
 
+export const REVIEW_VERDICTS = ['ready', 'follow-up', 'changes'];
+
+/**
+ * `npx breakaway review <ID> --verdict ready|follow-up|changes "<note>"` (BRK-111): an agent's answer on the pull
+ * request that closes its task. The board adds it to the task as a comment and keeps it for the pull request page.
+ * `pr` picks the pull request when the task has several open.
+ * @param {string | undefined} ref
+ * @param {string | undefined} verdict
+ * @param {string | undefined} note
+ * @param {{ by?: string, pr?: string | number }} [options]
+ */
+export function reviewRequest(ref, verdict, note, { by, pr } = {}) {
+  if (!ref) return { error: 'say which task: npx breakaway review <task> --verdict ready "<note>"' };
+  if (!REVIEW_VERDICTS.includes(String(verdict)))
+    return { error: `say the verdict: --verdict ${REVIEW_VERDICTS.join('|')}` };
+  const text = String(note ?? '').trim();
+  if (!text) return { error: 'say what you found: the note is the review (Markdown)' };
+  const n = pr === undefined ? null : String(pr).replace(/^#/u, '');
+  if (n !== null && !/^[1-9]\d{0,8}$/u.test(n)) return { error: '--pr is a pull request number' };
+  return {
+    request: [
+      'POST',
+      `tasks/${encodeURIComponent(ref)}/review`,
+      { verdict, note: text, ...(by ? { by } : {}), ...(n ? { pr: Number(n) } : {}) },
+    ],
+  };
+}
+
+/**
+ * Force start on a request that starts an agent (BRK-107): `force`, and who is asking, so the board can refuse an
+ * agent's name (only the owner forces a start). Nothing when it isn't forced.
+ * @param {unknown} force
+ * @param {string | undefined} by
+ */
+export function forceFields(force, by) {
+  return force ? { force: true, ...(by ? { by } : {}) } : {};
+}
+
+/**
+ * `agents new`: the request that makes a task from a prompt and starts an agent on it. It's the checkout's repository
+ * unless `--repo` names another. It always says who asks, so the board refuses an agent's name: only the owner starts one.
+ * With `decision` (`agents new --decision <ID> ["<note>"]`, BRK-110) the board writes the prompt from that answered
+ * decision, in the decision's repository, and the text is the owner's note under it.
+ * @param {string} prompt
+ * @param {{ repo?: string | null, force?: boolean, by?: string, decision?: string | null }} [options]
+ */
+export function generalAgentRequest(prompt, { repo = null, force = false, by, decision = null } = {}) {
+  const text = String(prompt ?? '').trim();
+  if (!text && !decision)
+    return { error: 'say what the agent should do: npx breakaway agents new "Tidy the docs" [--image <file>]' };
+  const body = {
+    ...(decision ? { decision, ...(text ? { note: text } : {}) } : { prompt: text }),
+    ...(repo ? { repo } : {}),
+    ...(force ? { force: true } : {}),
+    ...(by ? { by } : {}),
+  };
+  return { request: ['POST', 'agents/general', body] };
+}
+
+/**
+ * What the CLI says about a general agent's answer: the task and that it started, or why it waits (and whether Force
+ * start could skip that), or, from a decision, the open one that already has it.
+ * @param {{ task: { wid?: string, short?: string }, run?: { url?: string, agent?: string } | null, waiting?: string | null, forceable?: boolean, already?: string | null }} answer
+ */
+export function generalAgentSummary({ task, run, waiting, forceable, already }) {
+  const id = task.wid ?? task.short;
+  if (!run && already) return `${id} already refines from these answers: ${already}.`;
+  if (run) return `Started ${run.agent ? `${run.agent} ` : 'an agent '}on ${id}${run.url ? `: ${run.url}` : ''}`;
+  return `Saved ${id}, waiting to start: ${waiting ?? 'no room yet'}.${forceable ? ` Start it now past the board's limits: npx breakaway agents start ${id} --force` : ''}`;
+}
+
 /**
  * What the CLI says about an answer to those requests: which task and agent took the pull request, or who already has it.
  * @param {'fix' | 'review'} action
  * @param {string | number} number
- * @param {{ task: { wid?: string, short?: string }, run?: { url?: string, agent?: string } | null, already?: string | null }} answer
+ * @param {{ task: { wid?: string, short?: string }, run?: { url?: string, agent?: string, kind?: string } | null, already?: string | null }} answer
  */
 export function pullAgentSummary(action, number, { task, run, already }) {
   const id = task.wid ?? task.short;
   if (!run) return `${id} already has it: ${already}.`;
-  const what = action === 'fix' ? `fixing #${number}` : `testing #${number}`;
+  const what =
+    action === 'fix' ? `fixing #${number}` : run.kind === 'pr-review' ? `reviewing #${number}` : `testing #${number}`;
   return `Started ${run.agent ? `${run.agent}, ` : 'an agent '}${what} on ${id}${run.url ? `: ${run.url}` : ''}`;
 }
 
@@ -132,3 +207,197 @@ export function ideaTask(idea, { horizon = 'auto', auto = false, repo = null } =
     ...(repo ? { repo } : {}),
   };
 }
+
+/**
+ * The fields `features add` and `features modify` send (BRK-85, IDEA-28 section 1): only the ones given. `--release none`
+ * (or an empty one) leaves the feature unplanned, and `v1.2.0` is read as `1.2.0`.
+ * @param {{ title?: string, brief?: string, release?: string, state?: string }} options
+ */
+export function featureBody({ title, brief, release, state } = {}) {
+  const body = {};
+  if (title !== undefined) body.title = String(title);
+  if (brief !== undefined) body.brief = String(brief);
+  if (release !== undefined) {
+    const r = String(release).trim();
+    body.release = r === 'none' ? '' : r.replace(/^v(?=\d)/u, '');
+  }
+  if (state !== undefined) body.state = String(state);
+  return body;
+}
+
+/**
+ * The request behind `npx breakaway chase <slug> [stop] [--parallel <n>] [--dry-run]` (BRK-85, IDEA-28 section 3):
+ * without `stop` it starts the chase, or keeps a running one going with the new `--parallel`; `--dry-run` shows what
+ * would start now and changes nothing. It always says who asks, so the board refuses an agent's name: a chase is the
+ * owner's.
+ * @param {string | undefined} slug
+ * @param {string | undefined} action
+ * @param {{ parallel?: string | number, dryRun?: boolean, by?: string }} [options]
+ * @returns {{ error?: string, request?: [string, string, Record<string, unknown>] }}
+ */
+export function chaseRequest(slug, action, { parallel, dryRun = false, by } = {}) {
+  if (!slug) return { error: 'say which feature: npx breakaway chase <slug> [stop] [--parallel <n>] [--dry-run]' };
+  if (action !== undefined && action !== 'stop')
+    return { error: `chase has no "${String(action).slice(0, 40)}": npx breakaway chase <slug> [stop]` };
+  let limit;
+  if (parallel !== undefined) {
+    limit = Number(parallel);
+    if (!Number.isInteger(limit) || limit < 1)
+      return { error: '--parallel is how many agents at once in one area: a whole number, 1 or more' };
+  }
+  if (action === 'stop' && limit !== undefined)
+    return { error: '--parallel is for a chase that runs: npx breakaway chase <slug> --parallel <n>' };
+  const body = {
+    on: action !== 'stop',
+    ...(limit !== undefined ? { parallel: limit } : {}),
+    ...(dryRun ? { dryRun: true } : {}),
+    ...(by ? { by } : {}),
+  };
+  return { request: ['POST', `features/${encodeURIComponent(slug.toLowerCase())}/chase`, body] };
+}
+
+const plural = (n, one, many = `${one}s`) => `${n} ${n === 1 ? one : many}`;
+const idOf = (t) => t.wid ?? t.short ?? String(t.uuid ?? '').slice(0, 8);
+
+/**
+ * A feature's progress in one line: "4 of 10 done: 2 running, 1 ready, 1 waiting for you".
+ * @param {{ total: number, done: number, running?: number, ready?: number, waiting?: number, needsYou?: number, inReview?: number }} p
+ */
+export function progressLine(p) {
+  if (!p.total) return 'no tasks yet';
+  const rest = [
+    p.inReview && `${p.inReview} in review`,
+    p.running && `${p.running} running`,
+    p.ready && `${p.ready} ready`,
+    p.waiting && `${p.waiting} waiting on other tasks`,
+    p.needsYou && `${p.needsYou} waiting for you`,
+  ].filter(Boolean);
+  return `${p.done} of ${p.total} done${rest.length ? `: ${rest.join(', ')}` : ''}`;
+}
+
+/** The chase in a few words for a feature's line, or null when it's off. */
+function chaseWords(chase) {
+  if (!chase || chase.state === 'off') return null;
+  if (chase.state === 'on') return `chasing, ${chase.parallel} at once in an area`;
+  if (chase.state === 'done') return 'chase ended';
+  return 'chase stopped';
+}
+
+/**
+ * What `npx breakaway features` prints: features by release, then unplanned, then the tags that could be features
+ * and the tasks with a release tag and no feature.
+ * @param {{ features: any[], suggestions?: any[], releaseTasks?: any[] }} data
+ */
+export function featureListLines({ features, suggestions = [], releaseTasks = [] }) {
+  const out = [];
+  if (!features.length)
+    out.push('No features yet. Make one: npx breakaway features add <slug> --title "<title>" [--release 1.2.0]');
+  const width = Math.max(12, ...features.map((f) => f.slug.length));
+  let group;
+  for (const f of features) {
+    const release = f.release ?? 'Unplanned';
+    if (release !== group) {
+      if (group !== undefined) out.push('');
+      out.push(release);
+      group = release;
+    }
+    const notes = [
+      progressLine(f.progress),
+      f.shipped ? 'shipped' : null,
+      chaseWords(f.chase),
+      f.conflicts?.length ? `${plural(f.conflicts.length, 'task')} in two features` : null,
+    ].filter(Boolean);
+    out.push(`  ${f.slug.padEnd(width)} ${f.title} · ${notes.join(' · ')}`);
+  }
+  if (suggestions.length) {
+    out.push('', 'Tags that could be features (npx breakaway features add <slug>):');
+    for (const s of suggestions)
+      out.push(`  ${s.slug} (${plural(s.open, 'open task')}${s.release ? `, ${s.release}` : ''})`);
+  }
+  for (const r of releaseTasks)
+    out.push('', `Other tasks in ${r.release}: ${r.tasks.map((t) => t.wid ?? t.description).join(', ')}`);
+  return out;
+}
+
+/**
+ * A chase's state, live line, and what holds it, as `features show` and `chase` print them (IDEA-28 section 3.9).
+ * @param {any} chase
+ * @param {string} [slug] the feature's, for the command that starts it
+ */
+export function chaseLines(chase, slug = '<slug>') {
+  if (!chase) return [];
+  const out = [];
+  const head = {
+    on: `On since ${String(chase.startedAt ?? '')
+      .slice(0, 16)
+      .replace('T', ' ')} UTC, ${plural(chase.parallel, 'agent')} at once in an area`,
+    stopped: 'Stopped: running agents finish, nothing new starts',
+    done: 'Ended: every task is done or in review',
+    off: `Off (npx breakaway chase ${slug} starts it, ${plural(chase.parallel, 'agent')} at once in an area)`,
+  }[chase.state];
+  out.push(`  Chase       ${head ?? chase.state}`);
+  if (chase.summary) out.push(`              ${chase.summary}`);
+  for (const n of chase.needsYou ?? []) out.push(`  Needs you   ${idOf(n)} ${n.why}${blocking(n)}`);
+  for (const s of chase.stuck ?? [])
+    out.push(`  Stuck       ${idOf(s)} ${s.why}${s.last ? `; last: ${oneLine(s.last)}` : ''}`);
+  const queue = chase.queue ?? [];
+  if (queue.length) {
+    out.push('  Next');
+    for (const q of queue) out.push(`    ${idOf(q).padEnd(9)} ${q.ready ? 'ready to start' : q.reason}${blocking(q)}`);
+  }
+  return out;
+}
+
+const oneLine = (text) => {
+  const flat = String(text).replace(/\s+/gu, ' ').trim();
+  return flat.length > 120 ? `${flat.slice(0, 117)}…` : flat;
+};
+/** Why a pulled-in blocker is in the chase (section 3.1). */
+const blocking = (t) => (t.blocks?.length ? ` (in the chase because it blocks ${t.blocks.join(', ')})` : '');
+
+/**
+ * What `npx breakaway features show <slug>` prints: the record, its progress, its chase, and its tasks in dependency order.
+ * @param {any} f
+ */
+export function featureLines(f) {
+  const out = [`${f.title} (${f.slug})`, ''];
+  const row = (k, v) => v && out.push(`  ${k.padEnd(11)} ${v}`);
+  row('Release', f.release ?? 'unplanned');
+  row('State', f.shipped && f.state !== 'shipped' ? 'shipped (every task is done and live)' : f.state);
+  row('Progress', progressLine(f.progress));
+  out.push(...chaseLines(f.chase, f.slug));
+  // The chase's own Needs you says more (merges, connections), so the feature's is shown only without one.
+  if (!f.chase?.needsYou) for (const n of f.needsYou ?? []) row('Needs you', `${idOf(n)} ${n.why}`);
+  for (const c of f.conflicts ?? []) row('Two features', `${c.wid} is in ${c.features.join(' and ')}: it counts here`);
+  if (f.brief) out.push('', ...f.brief.split('\n').map((l) => `  ${l}`));
+  if (f.tasks?.length) {
+    out.push('', '  Tasks');
+    for (const t of f.tasks)
+      out.push(`    ${idOf(t).padEnd(9)} ${t.state.padEnd(9)} ${t.description}${t.why ? ` (${t.why})` : ''}`);
+  } else out.push('', `  No tasks yet: tag them with ${f.slug} (npx breakaway modify <ref> --tag ${f.slug}).`);
+  return out;
+}
+
+/**
+ * What `npx breakaway chase` prints after the board answers: what it started or would start, then the chase. `parallel`
+ * is the limit a dry run tried, which the board doesn't keep.
+ * @param {string} slug
+ * @param {{ dryRun?: boolean, chase: any, started?: string[], wouldStart?: string[] }} answer
+ * @param {{ stop?: boolean, parallel?: number }} [options]
+ */
+export function chaseSummary(slug, { dryRun, chase, started = [], wouldStart = [] }, { stop = false, parallel } = {}) {
+  let first;
+  if (dryRun) {
+    const limit = parallel ? ` with ${plural(parallel, 'agent')} at once in an area` : '';
+    first = `A chase of ${slug}${limit} would start ${wouldStart.length ? `${wouldStart.join(', ')} now` : 'nothing now'}. Nothing was started.`;
+  } else if (stop) first = `Stopped the chase of ${slug}. Running agents finish and open their pull requests.`;
+  else if (chase.state !== 'on') first = `The chase of ${slug} isn’t on (${chase.state}).`;
+  else if (started.length) first = `Chasing ${slug}: started ${started.join(', ')}.`;
+  else {
+    const next = (chase.queue ?? []).filter((q) => q.ready).map(idOf);
+    first = next.length
+      ? `Chasing ${slug}: the board starts ${next.join(', ')} on its next check.`
+      : `Chasing ${slug}: nothing can start right now; the board starts each task when it’s ready.`;
+  }
+  return [first, '', ...chaseLines(chase, slug)].join('\n');
+}

package/scripts/tasks.mjs

@@ -44,10 +44,20 @@ import { githubFromRemote, inRepo, pickRepo } from './tasks/repo.js';
 import { NO_TERMINAL, ask as askIn } from './tasks/ask.js';
 import { CLI_PACKAGE, PROMPT_SECTIONS, initPlan, machineTaskrc, promptSections } from './tasks/init.js';
 import {
+  chaseRequest,
+  chaseSummary,
+  featureBody,
+  featureLines,
+  featureListLines,
+  progressLine,
+  forceFields,
+  generalAgentRequest,
+  generalAgentSummary,
   githubRequest,
   ideaTask,
   pullAgentRequest,
   pullAgentSummary,
+  reviewRequest,
   staleCliWarning,
   unknownSubcommand,
 } from './tasks/cli.js';
@@ -133,15 +143,26 @@ Reading                (list, next, claim, and add work in this checkout's repos
     --project <p> --horizon <h> --tag <t>
   activity               recent changes, newest first  [--limit <n>]
   agents                 cloud agents: what's running, what's waiting to start
-  agents start <ref>     start a Claude cloud agent on a task  [--note <text>]
-  agents refine <ref>    start an agent that improves a task, not builds it  --note <what to look at or change>
+  agents new "<prompt>"  start an agent from a prompt: it makes its own task  [--image <file>]… [--repo <slug>] [--force] (owner)
+  agents new --decision <ref> ["<note>"]   start an agent that brings the work waiting for an answered decision in line with its answers; the board writes its prompt  [--force] (owner)
+  agents start <ref>     start a Claude cloud agent on a task  [--note <text>] [--force]
+  agents refine <ref>    start an agent that improves a task, not builds it  --note <what to look at or change> [--force]
   agents plan [<plan>]   your Claude plan and what it allows; pro, max5, or max20 picks one (owner) and sets the limits to its defaults
   agents next            start the next few ready tasks, one per area  [--count <n>] [--dry-run] [--repo <slug>]
   routines               saved prompts the owner runs with a button, and their caps
-  routines run <slug>    run one now: makes a RUN task and starts an agent on it  [--note <text>]
+  routines run <slug>    run one now: makes a RUN task and starts an agent on it  [--note <text>] [--force]
+  features               features by release: each one's progress and chase, and tags that could be features
+  features show <slug>   one feature: its release, progress, what waits for you, its chase, and its tasks in order
+  chase <slug>           start a chase (owner): the board starts an agent on every ready task in the feature and on
+                         what blocks it, within its limits, until all are done or in review
+    --parallel <n>       the most agents at once in one area (default 3); on a running chase, it changes it
+    --dry-run            show what would start now, and start nothing
+  chase <slug> stop      stop it (owner): nothing new starts; running agents finish
   horizon close          close now: finished tasks go to the archive, next becomes now, later becomes next  [--dry-run]
-  github fix <n>         start an agent on a pull request's conflicts, failing checks, or review comments (owner)  [--problem conflicts|failing|review] [--note <text>] [--repo <slug>]
-  github review <n>      start an agent that tests a Dependabot pull request, as Safe to merge? does (owner)  [--note <text>] [--repo <slug>]
+  github fix <n>         start an agent on a pull request's conflicts, failing checks, or review comments (owner)  [--problem conflicts|failing|review] [--note <text>] [--repo <slug>] [--force]
+  github review <n>      start an agent that reviews a pull request that can merge as it stands, on the task it closes, as
+                         Review with an agent does; on a Dependabot one it tests the update, as Safe to merge? does
+                         (owner)  [--note <text>] [--repo <slug>] [--force]
   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
@@ -153,6 +174,8 @@ Working
                          refuses another repository's task unless --repo names it
   release <ref>          give it back  [--force]
   comment <ref> <text>   add a comment (signed with your agent name); note is the same command
+  review <ref> --verdict ready|follow-up|changes <note>   your review of the pull request that closes the task you
+                         hold: a comment on it, and the review on the pull request's page (the note is Markdown)  [--pr <n>]
   done <ref>             finish it  [--note <text>] [--pr <url>]
   add <description>      new task; gets the next work ID for its project
     --project <p> --tag <t>… --priority H|M|L --horizon now|next|later
@@ -205,6 +228,9 @@ Working
                          --agents-max <n|none> and --agents-hourly <n|none> cap its agents under the board's shared limits,
                          --prompt <path|none> says where its agent prompt is in its checkout (default tools/tasks/routine-prompt.md)
                          --pipeline <file.json|none> sets its deploy pipeline ({"workers": {"staging", "production"}, "workflows": {...}, "deployPaths"}) or clears it
+  features add <slug>    new feature: its tasks join by carrying <slug> as a tag  [--title <text>]
+                         [--brief <text> | --brief-file <path>] [--release <x.y.z>] (agents add one without a release)
+  features modify <slug> change one (owner): --title, --brief, --brief-file, --release <x.y.z|none>, --state open|shipped
   routines add <slug>    new routine (owner)  --name <text> --prompt <text> | --prompt-file <path>  [--done-when <text>] [--horizon now|next|later] [--gap <minutes>] [--daily <n>]
                          [--repo <slug>] the repository it runs in (default: the checkout's)
   routines modify <slug> change one (owner): the same options (--repo <slug> moves it), and --enabled yes|no; --schedule "0 9 * * 1" runs it on a cron schedule (UTC), --schedule "" clears it; --trigger-start auto|wait sets whether a webhook or GitHub event starts the agent or waits for your Start; --github-events pr_merged,release_published,workflow_failed (or "") starts it on those GitHub events
@@ -752,8 +778,33 @@ const commands = {
       );
       return;
     }
+    if (sub === 'new') {
+      const decision = typeof opts.decision === 'string' ? opts.decision : null;
+      const built = generalAgentRequest(args.slice(1).join(' '), {
+        // From a decision, the board runs it in the decision's repository unless --repo says otherwise.
+        repo: opts.repo ?? (decision ? null : (await checkoutRepo()).slug),
+        decision,
+        force: Boolean(opts.force),
+        by: opts.as ?? setting('AGENT'),
+      });
+      if (built.error || !built.request) fail(built.error ?? 'bad request');
+      if ((opts.image ?? []).length > 4) fail('an agent takes up to 4 images');
+      for (const file of opts.image ?? []) if (!existsSync(file)) fail(`can't read ${file}`);
+      const answer = await call(...built.request);
+      // The task exists now: attach the images to it, as an idea's are.
+      for (const file of opts.image ?? []) {
+        const image = await upload(ref(answer.task), file);
+        if (!opts.json) console.log(`Attached ${image.name} (${Math.ceil(image.size / 1024)} KB).`);
+      }
+      print(answer, generalAgentSummary);
+      return;
+    }
     if (sub === 'start') {
-      const { task, run } = await call('POST', 'agents/start', { ref: need(args[1], 'task'), note: opts.note });
+      const { task, run } = await call('POST', 'agents/start', {
+        ref: need(args[1], 'task'),
+        note: opts.note,
+        ...forceFields(opts.force, opts.as ?? setting('AGENT')),
+      });
       print({ task, run }, () => `Started an agent on ${task.wid ?? task.short}: ${run.url}`);
       return;
     }
@@ -764,6 +815,7 @@ const commands = {
         ref: need(args[1], 'task'),
         note: opts.note,
         mode: 'refine',
+        ...forceFields(opts.force, opts.as ?? setting('AGENT')),
       });
       print({ task, run }, () => `Started an agent refining ${task.wid ?? task.short}: ${run.url}`);
       return;
@@ -938,7 +990,10 @@ const commands = {
     };
     const clean = (o) => Object.fromEntries(Object.entries(o).filter(([, v]) => v !== undefined));
     if (sub === 'run') {
-      const { task, run } = await call('POST', `routines/${enc(need(args[1], 'routine'))}/run`, { note: opts.note });
+      const { task, run } = await call('POST', `routines/${enc(need(args[1], 'routine'))}/run`, {
+        note: opts.note,
+        ...forceFields(opts.force, opts.as ?? setting('AGENT')),
+      });
       print({ task, run }, () => `Started ${task.wid}: ${run.url}`);
       return;
     }
@@ -1012,6 +1067,60 @@ const commands = {
       ].join('\n'),
     );
   },
+  async features() {
+    const sub = args[0];
+    const body = () =>
+      featureBody({
+        title: opts.title,
+        brief: opts['brief-file'] ? readFileSync(opts['brief-file'], 'utf8') : opts.brief,
+        release: opts.release,
+        state: opts.state,
+      });
+    // Who asks, so the board can refuse an agent what's the owner's (a release, a change).
+    const by = opts.as ?? setting('AGENT');
+    if (sub === 'add') {
+      const slug = need(args[1], 'slug').toLowerCase();
+      const { feature } = await call('POST', 'features', { slug, ...body(), ...(by ? { by } : {}) });
+      print({ feature }, (d) =>
+        [
+          `Added the feature ${d.feature.slug}${d.feature.release ? `, aimed at ${d.feature.release}` : ''}: ${progressLine(d.feature.progress)}.`,
+          `Tasks join it by the tag: npx breakaway modify <ref> --tag ${d.feature.slug}`,
+        ].join('\n'),
+      );
+      return;
+    }
+    if (sub === 'modify') {
+      const changes = body();
+      if (!Object.keys(changes).length) fail('say what to change: --title, --brief, --release, or --state');
+      const { feature } = await call('PATCH', `features/${enc(need(args[1], 'feature').toLowerCase())}`, {
+        ...changes,
+        ...(by ? { by } : {}),
+      });
+      print({ feature }, (d) => `Saved ${d.feature.slug}.`);
+      return;
+    }
+    if (sub === 'show') {
+      const { feature } = await call('GET', `features/${enc(need(args[1], 'feature').toLowerCase())}`);
+      print({ feature }, (d) => featureLines(d.feature).join('\n'));
+      return;
+    }
+    print(await call('GET', 'features'), (d) => featureListLines(d).join('\n'));
+  },
+  async chase() {
+    const built = chaseRequest(args[0], args[1], {
+      parallel: opts.parallel,
+      dryRun: Boolean(opts['dry-run']),
+      by: opts.as ?? setting('AGENT'),
+    });
+    if (built.error) fail(built.error);
+    const answer = await call(...built.request);
+    print(answer, (d) =>
+      chaseSummary(args[0].toLowerCase(), d, {
+        stop: args[1] === 'stop',
+        parallel: opts.parallel === undefined ? undefined : Number(opts.parallel),
+      }),
+    );
+  },
   async next() {
     const body = { agent: agent(), claim: Boolean(opts.claim), project: opts.project, horizon: opts.horizon };
     const repo = await scopedRepo();
@@ -1046,6 +1155,12 @@ const commands = {
     unmarkSession(task);
     print(task, (t) => `Released ${ref(t)}.`);
   },
+  async review() {
+    const built = reviewRequest(args[0], opts.verdict, args.slice(1).join(' '), { by: agent(), pr: opts.pr });
+    if (built.error || !built.request) fail(built.error ?? 'bad request');
+    const { review, task } = await call(...built.request);
+    print({ review, task }, (r) => `Left your review of #${r.review.pr} on ${ref(r.task)}: ${r.review.label}.`);
+  },
   // The board's `annotate` route is the comments route's alias; using it keeps this working on a board that hasn't deployed /comments yet.
   async comment() {
     const text = args.slice(1).join(' ');
@@ -1206,6 +1321,8 @@ const commands = {
         repo: (await checkoutRepo()).slug,
         problem: opts.problem,
         note: opts.note,
+        force: Boolean(opts.force),
+        by: opts.as ?? setting('AGENT'),
       });
       if (built.error || !built.request) fail(built.error ?? 'bad request');
       const answer = await call(...built.request);

package/src/cli-version.js

@@ -4,5 +4,5 @@
  * and how to update it. scripts/tasks/version.test.js fails when the copied files change and this doesn't:
  * so it lives in the board's package (CLD-135) and the CLI imports it from here.
  */
-export const CLI_VERSION = 50;
-export const CLI_FINGERPRINT = '2eb2f4fbe777547e';
+export const CLI_VERSION = 55;
+export const CLI_FINGERPRINT = 'e4ee0503a3e3699a';

package/src/decision.js

@@ -239,3 +239,75 @@ export function summarize(questions, answers) {
   });
   return `Decided by the owner: ${parts.join('; ')}`;
 }
+
+/** Tags that aren't a feature's (IDEA-28 section 1): the board's own, horizons, and release tags. */
+const NOT_FEATURES = new Set(['agent', 'owner', 'decide', 'idea', 'general']);
+export const featureTags = (tags) =>
+  (tags ?? []).filter((t) => !NOT_FEATURES.has(t) && !t.startsWith('horizon-') && !/^v\d/u.test(t));
+
+/** One answer as words, in full but for a long open answer. */
+function spell(q, answer) {
+  if (!answer) return 'no answer';
+  if (q.type === 'open') return clip(answer.value.trim(), 1500);
+  const label = (id) =>
+    id === 'other' ? `something else: ${answer.other}` : (q.options.find((o) => o.id === id)?.label ?? id);
+  if (q.type === 'choice') return label(answer.value);
+  if (q.type === 'multi') return answer.value.length ? answer.value.map(label).join(', ') : 'none';
+  if (q.type === 'rank') return answer.value.map((id, i) => `${i + 1}. ${label(id)}`).join(', ');
+  if (q.type === 'scale')
+    return `${answer.value} (${q.min}${q.minLabel ? ` ${q.minLabel}` : ''} to ${q.max}${q.maxLabel ? ` ${q.maxLabel}` : ''})`;
+  return String(answer.value);
+}
+
+/** The longest the prompt may be: a task's description. */
+const MAX_BRIEF = 10000;
+
+/**
+ * Refine from the answers (docs/specs/IDEA-30-new-agent.md, section 8): the prompt the board writes for a general
+ * agent that brings the work waiting for an answered decision in line with its answers. `decision` is the decision's
+ * task (its `ref` is its work ID or short ID), `waiting` the open tasks that depend on it, and `note` the owner's,
+ * which goes under the board's prompt. Returns the task's title and description.
+ * @param {{ ref: string, description: string, spec?: string | null, questions: any[], answers: Record<string, any> }} decision
+ * @param {{ ref: string, description: string, tags?: string[], spec?: string | null }[]} waiting
+ * @param {string | null} [note]
+ */
+export function refinePrompt(decision, waiting, note = null) {
+  const title = clip(`Refine from the answers to ${decision.ref}: ${decision.description}`, 200);
+  const questions = decision.questions.flatMap((q, i) => {
+    const answer = decision.answers[q.id];
+    return [
+      `${i + 1}. ${q.prompt.trim()}`,
+      `   Answer: ${spell(q, answer)}`,
+      ...(answer?.comment ? [`   The owner's note: ${answer.comment.trim()}`] : []),
+    ];
+  });
+  const specs = [...new Set([decision.spec, ...waiting.map((t) => t.spec)].filter(Boolean))];
+  const held = waiting.map((t) => {
+    const features = featureTags(t.tags);
+    return `- ${t.ref}: ${t.description}${features.length ? ` (feature: ${features.join(', ')})` : ''}`;
+  });
+  const after = [
+    '',
+    'What to do',
+    `- Change the tasks waiting for ${decision.ref}, and their dependencies, so they match the answers (the cross-task edits a general agent may make, each change noted).`,
+    `- Update ${specs.length ? 'the spec' : 'any spec the tasks link'} to match, in one pull request that closes your own task.`,
+    '- Add the tasks the answers need, filled in and depending on what they wait for.',
+    '- Ask a new decision for anything the answers leave open. Never change these answers: only the owner does.',
+    '- If nothing in the repository needs to change, comment what you changed on the board, task by task, and release your task.',
+    ...(note && String(note).trim() ? ['', 'Note from the owner:', String(note).trim().slice(0, 4000)] : []),
+  ];
+  const intro = `The owner answered the decision on ${decision.ref} (${decision.description}). Bring the work waiting for it in line with the answers.`;
+  const rest = [
+    '',
+    `Waiting for ${decision.ref}`,
+    ...(held.length ? held : ['- Nothing open waits for it: look for tasks and specs the answers change.']),
+    ...(specs.length ? ['', specs.length === 1 ? 'Spec' : 'Specs', ...specs.map((s) => `- ${s}`)] : []),
+    ...after,
+  ].join('\n');
+  // Too long for a description: the answers give way first, since they stay on the decision for the agent to read.
+  const more = `\n… (the rest is on ${decision.ref}: npx breakaway show ${decision.ref})`;
+  const answers = ['', 'Questions and answers', ...questions].join('\n');
+  const room = MAX_BRIEF - intro.length - rest.length - 1;
+  const middle = answers.length <= room ? answers : `${answers.slice(0, Math.max(0, room - more.length))}${more}`;
+  return { title, brief: `${intro}${middle}\n${rest}`.slice(0, MAX_BRIEF) };
+}