breakaway 1.2.1-main.5 → 1.2.1-main.7

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.5",
+  "version": "1.2.1-main.7",
   "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,7 +6,7 @@ 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'],
@@ -83,10 +83,10 @@ export const FIX_PROBLEMS = ['conflicts', 'failing', 'review'];
  * 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,10 +96,51 @@ export function pullAgentRequest(action, number, { repo = null, problem, note }
     ...(repo ? { repo } : {}),
     ...(problem ? { problem } : {}),
     ...(typeof note === 'string' && note.trim() ? { note } : {}),
+    ...forceFields(force, by),
   };
   return { request: ['POST', `github/pulls/${n}/${action}`, body] };
 }
 
+/**
+ * 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.
+ * @param {string} prompt
+ * @param {{ repo?: string | null, force?: boolean, by?: string }} [options]
+ */
+export function generalAgentRequest(prompt, { repo = null, force = false, by } = {}) {
+  const text = String(prompt ?? '').trim();
+  if (!text)
+    return { error: 'say what the agent should do: npx breakaway agents new "Tidy the docs" [--image <file>]' };
+  const body = {
+    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).
+ * @param {{ task: { wid?: string, short?: string }, run?: { url?: string, agent?: string } | null, waiting?: string | null, forceable?: boolean }} answer
+ */
+export function generalAgentSummary({ task, run, waiting, forceable }) {
+  const id = task.wid ?? task.short;
+  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

package/scripts/tasks.mjs

@@ -44,6 +44,9 @@ 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 {
+  forceFields,
+  generalAgentRequest,
+  generalAgentSummary,
   githubRequest,
   ideaTask,
   pullAgentRequest,
@@ -133,15 +136,16 @@ 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 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]
   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 tests a Dependabot pull request, 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
@@ -752,8 +756,30 @@ const commands = {
       );
       return;
     }
+    if (sub === 'new') {
+      const built = generalAgentRequest(args.slice(1).join(' '), {
+        repo: opts.repo ?? (await checkoutRepo()).slug,
+        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 +790,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 +965,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;
     }
@@ -1206,6 +1236,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 = 52;
+export const CLI_FINGERPRINT = 'b1542857a107623b';