breakaway 1.5.0-main.46 → 1.5.0-main.48

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

@@ -41,6 +41,7 @@ breakaway's work is on the board that tracks this repository. The CLI is `npx br
 | The task is an `IDEA-` | Shape it, don't build it: "Shaping an idea" in the core. |
 | The board started you on a kickoff (`Mode: kickoff`) | Interview the owner first: ask plain questions as a decision on the IDEA (at most 12, then at most 6 more if something important is open), `release`, and stop; once they're answered, shape it with `AGENTS.md`, the prompt's sections, an **In short**, and a `<slug>-v1` feature. "Kicking off a project" in the core. |
 | The board started you from the owner's prompt (`Mode: general`) | Give the task an area first (`modify <ID> --project <area>` gives it its work ID), retitle it, and take the smallest path: a pull request, board edits noted on each task, a spec, a task in another repository, or a decision or ping. Releasing it with no pull request closes it. "Running a general agent" in the core. |
+| The board started you to make routines (`Mode: routines`) | Don't give the task an area. If the prompt leaves what or when open, ask one decision on your task (at most 8 questions), `release`, and stop; otherwise, or once answered, make at most 5 routines with `routines add` (on, in your task's repository, never webhook or alert triggers, never `routines run`), `comment` the list and what the owner still has to add, and `release`. "Making routines" in the core. |
 | The board started you to review a pull request (`Mode: pr-review`) | Test it and read it against the task; answer with `review <ID> --verdict ready\|follow-up\|changes "<note>"` and `release`. Never push or merge. "Reviewing a pull request" in the core. |
 | Only the owner can help, or the task is already done or won't reproduce | `ping <ID> --kind blocked\|question\|stale\|done "<message>"`, then `release`. Ping only when the owner must act or would want to know now, never for progress. Full rules: "Pinging the owner" in the core. |
 | Adding tasks that belong to a feature | Tag each with the feature's slug (`--tag <slug>`; `tasks features` lists them), one feature per task and no release tag. New tasks that belong together get a feature: `features add <slug> --title "<name>"`, without `--release` (a feature's release, its changes, and a chase are the owner's). |

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "breakaway",
-  "version": "1.5.0-main.46",
+  "version": "1.5.0-main.48",
   "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/core.md

@@ -16,7 +16,7 @@ How to work:
 
 1. **Check you're in the task's repository.** `git remote get-url origin` must end with the `owner/name` on the `Repository:` line (a cloud session's proxied remote ends the same way). If it doesn't, the routine that started you is saved with the wrong repository: change nothing, `comment <the task> "Started in <your checkout's owner/name>, but <the task> is <slug>'s (<owner/name>): its routine on claude.ai needs that repository."`, `release <the task>`, and stop. Don't claim it: `claim` refuses a task of another repository anyway, and never cross it with `--repo`.
 2. **Claim it.** Read the repository's `AGENTS.md`, then the `tasks` skill (`.agents/skills/tasks/SKILL.md`, or wherever the repository's prompt says). Run `export BREAKAWAY_AGENT=<your agent name>` and `tasks claim <the task>`. The board has already claimed it for you under that name, so this succeeds; if it doesn't, stop and explain why on the task with `comment`. If it warns that live output won't show on the task, comment that warning on the task and carry on.
-3. **Read it.** `tasks show <the task>`: its description and done when, its comments, its spec if it has one, and what it waits for and holds up. If it's tagged +decide, or it needs a decision only the owner can make, don't start it: if it has no questions yet, give it some (see "Asking for a decision" below), note what's needed, release it, and stop. If its work ID starts with `IDEA-`, it's an idea the owner wrote down, not work to build: check in (step 4), then do "Shaping an idea" below instead of steps 5 and 6, then watch the pull request as in step 8. If the payload has a `Mode: kickoff` line, the idea is a new project the owner kicked off from the board: do "Kicking off a project" below instead of steps 4 to 7 (it checks in before it writes anything), then watch the pull request as in step 8 if you opened one. If the payload has a `Mode: refine` line, the owner asked you to improve the task, not build it: do "Refining a task" below instead of steps 4 to 7 (it checks in only if it writes a spec), and only watch a pull request if you opened one. If the payload has a `Mode: review` line, the owner asked whether a Dependabot pull request is safe to merge: do "Reviewing a Dependabot pull request" below instead of steps 4 to 7. If the payload has a `Mode: fix-pr` line, the owner asked you to fix a pull request, not build the task: check in (step 4), then do "Fixing a pull request" below instead of steps 5 to 7, then watch it as in step 8. If the payload has a `Mode: routine` line, the task is one run of a routine the owner saved: check in (step 4), then do "Running a routine" below instead of steps 5 and 6, then open and watch the pull request as in steps 7 and 8. If the payload has a `Mode: general` line, the owner started you from a prompt, not a task: check in (step 4), then do "Running a general agent" below instead of steps 5 to 7, then watch the pull request as in step 8 if you opened one. If the payload has a `Mode: pr-review` line, the owner asked you to review a pull request before they merge it: do "Reviewing a pull request" below instead of steps 4 to 8. A payload without a `Mode:` line is a build.
+3. **Read it.** `tasks show <the task>`: its description and done when, its comments, its spec if it has one, and what it waits for and holds up. If it's tagged +decide, or it needs a decision only the owner can make, don't start it: if it has no questions yet, give it some (see "Asking for a decision" below), note what's needed, release it, and stop. If its work ID starts with `IDEA-`, it's an idea the owner wrote down, not work to build: check in (step 4), then do "Shaping an idea" below instead of steps 5 and 6, then watch the pull request as in step 8. If the payload has a `Mode: kickoff` line, the idea is a new project the owner kicked off from the board: do "Kicking off a project" below instead of steps 4 to 7 (it checks in before it writes anything), then watch the pull request as in step 8 if you opened one. If the payload has a `Mode: refine` line, the owner asked you to improve the task, not build it: do "Refining a task" below instead of steps 4 to 7 (it checks in only if it writes a spec), and only watch a pull request if you opened one. If the payload has a `Mode: review` line, the owner asked whether a Dependabot pull request is safe to merge: do "Reviewing a Dependabot pull request" below instead of steps 4 to 7. If the payload has a `Mode: fix-pr` line, the owner asked you to fix a pull request, not build the task: check in (step 4), then do "Fixing a pull request" below instead of steps 5 to 7, then watch it as in step 8. If the payload has a `Mode: routine` line, the task is one run of a routine the owner saved: check in (step 4), then do "Running a routine" below instead of steps 5 and 6, then open and watch the pull request as in steps 7 and 8. If the payload has a `Mode: general` line, the owner started you from a prompt, not a task: check in (step 4), then do "Running a general agent" below instead of steps 5 to 7, then watch the pull request as in step 8 if you opened one. If the payload has a `Mode: routines` line, the owner pressed Make with an agent and wants routines made, not files changed: do "Making routines" below instead of steps 4 to 8 (it checks in before it makes them, and opens no pull request). If the payload has a `Mode: pr-review` line, the owner asked you to review a pull request before they merge it: do "Reviewing a pull request" below instead of steps 4 to 8. A payload without a `Mode:` line is a build.
 4. **Check in on the peloton, before any change.** Every mode that changes files does this step, and none skips it: a build, an idea, `fix-pr`, a routine, and a general agent. Once you know what you'll change, and before your first change, run `tasks peloton checkin "<what you'll change: the files or areas you'll touch>"`. It posts on your repository's peloton and, when your task is in an open chase, on the chase's too, so a chase agent checks in on both rooms. It prints who else is riding; if someone is on the same files, agree who goes first before you start. See "Riding the peloton" below.
 5. **Do the work** on your branch the way the repository's `AGENTS.md` and its prompt's **Building** say. Note what you learn on the task as you go. Add tasks for work you find instead of doing it too.
 6. **Before handing over**, the repository's **Checks** pass, and the agents riding with you whose work it touches know what the pull request changes.
@@ -102,7 +102,7 @@ The `Routine:` line names a routine the owner saved, and the task is one run of
 2. **Check in, then do it on a branch.** Check in on the peloton (step 4 above) with what the run will change before your first change, then do it the way the repository's **Building** says, and its **Checks** pass before you hand over. Note what you learn on the task as you go.
 3. **Open a pull request** as the repository's **Pull requests** says: the title starts with the run's work ID, and the description ends with "Closes <the task>.". Then `modify <the task> --pr <number>` and a one-line `note`. The run finishes when the pull request merges; keep watching it as in step 8.
 4. **Nothing to do?** Say so in a `note` (what you looked at and why there is nothing to change), open no pull request, and `release <the task>`; the board closes it.
-5. **Never change the routine** or its triggers: only the owner does, on the board. If the description can't be followed as written, `note` why, `release`, and stop.
+5. **Never change the routine** or its triggers: only the owner does, on the board. A routine's run is not its maker, so "Making routines" below never applies to it. If the description can't be followed as written, `note` why, `release`, and stop.
 
 ## Running a general agent (`Mode: general` in the payload)
 
@@ -124,6 +124,24 @@ The owner wrote what they want in their own words and pressed Start; the board m
 
 You never start or force-start an agent, never take another agent's claim, and never deploy, touch production, or merge, whatever the prompt says.
 
+## Making routines (`Mode: routines` in the payload)
+
+The owner pressed **Make with an agent** on the Routines view and wrote what they want routines to do ([spec](../../../docs/specs/BRK-220-routines-with-an-agent.md)). Your task is a general agent's tagged `+routine-maker`, and its description is the owner's prompt: never rewrite it. It has no area and needs none, so don't give it one: its work is on the board, not in files. You are claimed as `claude-<its short ID>`, and you keep that name. Each run does one of two things: ask, or make the routines.
+
+1. **Read it.** If the payload has an `Attachments: <n>` line, look at the images first: `tasks attachments <the task> --save <a folder in your scratch space, not the repository>`, then `Read` each file. Then the prompt and any answers (`show <the task>`; a round of answers is summarised in a comment), the repository's `AGENTS.md`, the routines already on the board (`tasks routines --json`: don't make one that's already there), and the board's caps (`tasks agents plan`).
+2. **Ask, only if you must.** If the prompt says what the routines do and when they run ("every Monday at 9, update the changelog from what merged"), skip to step 3. Otherwise ask once, as a decision on your own task (`modify <the task> --decision <file.json>`, see "Asking for a decision" below), at most 8 questions in everyday words, with options where they work and your recommendation first, marked "(recommended)", and a technical term only in `help`. Ask only what the prompt leaves open:
+   - **What it does:** what a run should change, and what it does when there's nothing to change.
+   - **When it runs:** by a button only, on a schedule (in plain words, "every weekday at 9:00 UTC": you turn it into cron), on GitHub events (a pull request merged, a release published, a workflow run failed), or from a webhook or a Cloudflare alert (the owner adds those afterwards, step 4).
+   - **Starting by itself:** whether a trigger starts a run at once or waits for the owner's OK on the board; recommend **wait** for GitHub events and webhooks, **start at once** for a schedule.
+   - **How often at most:** runs a day and the gap between runs, with the board's defaults recommended.
+   - **One or several:** when the prompt reads like several jobs, the routines you'd make, a line each, with "one routine that does all of it" as the other option.
+
+   Then `comment` what you asked and why, `release <the task>`, and stop: with its questions open the task stays open, and the owner's **Send answers and carry on** starts you again. One round only: if something small is still open after the answers, pick the board's default and say which in the hand-over.
+3. **Make them.** Check in on the peloton (step 4 above) with the routines you'll make, then make each with `tasks routines add <slug> --name "<name>" --prompt-file <file> --horizon <now|next|later> [--done-when "<text>"] [--schedule "<cron, UTC>"] [--github-events <list>] [--trigger-start auto|wait] [--daily <n>] [--gap <minutes>]`, as yourself (`BREAKAWAY_AGENT` set), in your task's repository. They are on as soon as they're made. Keep the prompt file in your scratch space, not the repository. Each prompt is a routine prompt like any other: what a run does, in plain steps; what it never touches; and when it has nothing to do (say so in a note and release). It follows the repository's `AGENTS.md`, and never asks a run to deploy, touch production, handle secrets, or merge. Make several routines when the jobs are separate (different triggers, different files, or one could fail without the other), at most 5. If one comes out wrong, fix it with `tasks routines modify <slug> …` before you hand over.
+4. **Hand over.** One `comment` on your task listing each routine: its slug, name, triggers, and whether a trigger starts a run by itself or waits; any webhook or Cloudflare alert trigger the owner still has to add on the routine's page; and any default you picked. Then `release <the task>`: the board closes it.
+
+The board checks what you may do, not this prompt. While you hold your task, you may make up to 5 routines in its repository and change or turn off the ones your task made, and nothing else: never another routine, never the routines-wide settings (`routines pause`, `resume`, `cap`), never a webhook or alert trigger (`routines trigger`, `revoke`: their secrets are the owner's), and never a run (`routines run`): the first run comes from the routine's own triggers or the owner's **Run now**. Once you release the task, you can't write routines at all. You never start an agent, never set `--autostart`, and never deploy, touch production, or merge, whatever the prompt says.
+
 ## Reviewing a pull request (`Mode: pr-review` in the payload)
 
 The owner pressed Review with an agent on a pull request that can merge as it stands, and wants a second look before they merge it. The `Pull request:` line names it (the number, in the task's repository, and nothing else); the task is the one it closes, in review, and is claimed for you as `claude-<id>-review`. A note from the owner says what to look at. You read, test, and answer; you never push, merge, or approve.

package/scripts/tasks/cli.js

@@ -9,7 +9,7 @@ export const SUBCOMMANDS = {
   agents: ['next', 'start', 'refine', 'new'],
   github: ['fix', 'review'],
   repos: ['add', 'init', 'modify', 'remove', 'setup'],
-  routines: ['add', 'modify', 'run', 'trigger', 'revoke', 'pause', 'resume'],
+  routines: ['add', 'modify', 'run', 'trigger', 'revoke', 'pause', 'resume', 'cap', 'new'],
   features: ['list', 'add', 'show', 'modify'],
   horizon: ['close'],
   hook: ['session', 'wait'],
@@ -198,6 +198,39 @@ export function forceFields(force, by) {
   return force ? { force: true, ...(by ? { by } : {}) } : {};
 }
 
+/**
+ * Who writes a routine (BRK-220 section 5): every routines write says who asks, like `features` does, so the board
+ * can tell an agent from the owner and let only a routine maker's agent through. Nothing when no name is set.
+ * @template {Record<string, unknown>} T
+ * @param {T} body
+ * @param {string | undefined} by
+ */
+export function routineWrite(body, by) {
+  return by ? { ...body, by } : body;
+}
+
+/**
+ * `routines new` (BRK-220 section 1, Make with an agent): the request that makes a routine maker's task from the
+ * owner's words and starts its agent, in the checkout's repository unless `--repo` names another. It 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 routineMakerRequest(prompt, { repo = null, force = false, by } = {}) {
+  const text = String(prompt ?? '').trim();
+  if (!text)
+    return {
+      error:
+        'say what the routine should do, and when: npx breakaway routines new "Every Monday, update the changelog from what merged"',
+    };
+  const body = {
+    prompt: text,
+    ...(repo ? { repo } : {}),
+    ...(force ? { force: true } : {}),
+  };
+  return { request: ['POST', 'routines/agent', routineWrite(body, 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.

package/scripts/tasks.mjs

@@ -67,6 +67,8 @@ import {
   forceFields,
   generalAgentRequest,
   generalAgentSummary,
+  routineMakerRequest,
+  routineWrite,
   githubRequest,
   specLines,
   specListLines,
@@ -237,6 +239,8 @@ Reading                (list, next, claim, and add work in this checkout's repos
   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>] [--force]
+  routines new "<what you want>"   start an agent that asks how the routines should run, then makes them and turns
+                         them on  [--repo <slug>] [--force] (owner)
   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
@@ -358,9 +362,9 @@ Working
                          --from <ref> (owner): made from the group <ref> is in on the Dependencies view: its open tasks
                          join, and tasks already in another feature stay there
   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>]
+  routines add <slug>    new routine (owner, or the agent of a routine maker's task)  --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
+  routines modify <slug> change one (owner, or the agent of the routine maker's task that made it): 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
   routines trigger <slug> new webhook/API trigger (owner): prints its secret once  [--label <text>]
   routines revoke <slug> <id>  revoke a trigger
   routines pause|resume  stop or allow every routine  [--daily-all <n>] sets the cap for all routines a day
@@ -1272,10 +1276,23 @@ const commands = {
       };
     };
     const clean = (o) => Object.fromEntries(Object.entries(o).filter(([, v]) => v !== undefined));
+    // Who writes (BRK-220 section 5): the owner, or a routine maker's agent while it holds its task.
+    const by = opts.as ?? setting('AGENT');
+    if (sub === 'new') {
+      // Make with an agent (BRK-220 section 1): a routine maker's task in the checkout's repository unless --repo.
+      const built = routineMakerRequest(args.slice(1).join(' '), {
+        repo: opts.repo ?? (await checkoutRepo()).slug,
+        force: Boolean(opts.force),
+        by,
+      });
+      if (built.error || !built.request) fail(built.error ?? 'bad request');
+      print(await call(...built.request), (d) => generalAgentSummary(d));
+      return;
+    }
     if (sub === 'run') {
       const { task, run } = await call('POST', `routines/${enc(need(args[1], 'routine'))}/run`, {
         note: opts.note,
-        ...forceFields(opts.force, opts.as ?? setting('AGENT')),
+        ...forceFields(opts.force, by),
       });
       print({ task, run }, () => `Started ${task.wid}: ${run.url}`);
       return;
@@ -1283,7 +1300,11 @@ const commands = {
     if (sub === 'add') {
       // A routine runs in one repository (CLD-127): --repo, else the checkout's (none: the board's default).
       const repo = opts.repo ?? (await checkoutRepo()).slug ?? undefined;
-      const { routine } = await call('POST', 'routines', clean({ slug: need(args[1], 'slug'), ...fields(), repo }));
+      const { routine } = await call(
+        'POST',
+        'routines',
+        routineWrite(clean({ slug: need(args[1], 'slug'), ...fields(), repo }), by),
+      );
       print({ routine }, () => `Saved the routine ${routine.slug}. Run it: npx breakaway routines run ${routine.slug}`);
       return;
     }
@@ -1291,14 +1312,18 @@ const commands = {
       const { routine } = await call(
         'PATCH',
         `routines/${enc(need(args[1], 'routine'))}`,
-        clean({ ...fields(), repo: opts.repo }),
+        routineWrite(clean({ ...fields(), repo: opts.repo }), by),
       );
       print({ routine }, () => `Saved ${routine.slug}.`);
       return;
     }
     if (sub === 'trigger') {
       const slug = need(args[1], 'routine');
-      const { trigger, secret } = await call('POST', `routines/${enc(slug)}/triggers`, { label: opts.label });
+      const { trigger, secret } = await call(
+        'POST',
+        `routines/${enc(slug)}/triggers`,
+        routineWrite({ label: opts.label }, by),
+      );
       print({ trigger, secret }, () =>
         [
           `Made trigger ${trigger.id} (${trigger.label}) for ${slug}. The secret is shown once; the board keeps only its hash:`,
@@ -1314,14 +1339,18 @@ const commands = {
       await call(
         'DELETE',
         `routines/${enc(need(args[1], 'routine'))}/triggers/${enc(need(args[2], 'trigger id'))}`,
-        {},
+        routineWrite({}, by),
       );
       print({ ok: true }, () => 'Revoked.');
       return;
     }
     if (sub === 'cap') {
       // The cap for all routines a day (CLD-199), without pausing or resuming them.
-      const { settings } = await call('PATCH', 'routines/settings', { dailyCap: Number(need(args[1], 'runs a day')) });
+      const { settings } = await call(
+        'PATCH',
+        'routines/settings',
+        routineWrite({ dailyCap: Number(need(args[1], 'runs a day')) }, by),
+      );
       print({ settings }, (d) => `All routines can run ${d.settings.dailyCap} times a day.`);
       return;
     }
@@ -1329,10 +1358,13 @@ const commands = {
       const { settings } = await call(
         'PATCH',
         'routines/settings',
-        clean({
-          paused: sub === 'pause',
-          dailyCap: opts['daily-all'] === undefined ? undefined : Number(opts['daily-all']),
-        }),
+        routineWrite(
+          clean({
+            paused: sub === 'pause',
+            dailyCap: opts['daily-all'] === undefined ? undefined : Number(opts['daily-all']),
+          }),
+          by,
+        ),
       );
       print({ settings }, () => (settings.paused ? 'All routines are paused.' : 'Routines can run.'));
       return;