@open-tomato/rafa 0.9.2 → 0.11.0

package/README.md

@@ -31,7 +31,9 @@ What guides it:
 
 ## Before you run it
 
-Read this once; rafa also says it the first time you start a run.
+Read this once; rafa also says it the first time you start a run. Use
+`rafa plan risk` to see what the plan may do on this machine and under
+your accounts.
 
 - **Every Claude Code session rafa starts runs with
   `--dangerously-skip-permissions`.** That is what lets a plan run
@@ -54,6 +56,8 @@ Read this once; rafa also says it the first time you start a run.
   | `rafa skill backfill --propose` | 🪙 one session per batch of skills; without `--propose`, nothing |
   | `rafa next` | 🪙 when the step it runs is one of the above; it asks before each step |
 
+  The same 🪙 marks appear in `rafa --help` at all levels and in `rafa describe` output.
+
   Everything else reads files, git and GitHub and spends nothing,
   `rafa usage` included (it reads `CLAUDE_USAGE_PERCENT` and asks
   nobody). `rafa loop resume` starts no session itself, but it lets a
@@ -330,6 +334,8 @@ built. A box is ticked by the change that finishes the feature.
 - [x] Start a plan from the main branch and rafa makes the branch for you
 - [x] One command takes you to the next step: merge, clean up, plan,
   branch, start
+- [x] Every command that spends Claude usage says so in its help
+- [x] Before a run, see what it can do on this machine and under your accounts
 - [ ] The right skills reach the right task, chosen when the plan is
   written
 - [ ] Know which skills earn their place and which are ignored

package/dist/SKILL.md

@@ -471,6 +471,27 @@ The report rules in this skill restate `src/report/parse.ts`, which is the autho
 
 ---
 
+## Command-development rule: Claude session declaration
+
+When planning work on rafa commands: every command that can start a Claude
+Code session must declare its `spends` field on its `RafaCommand` definition.
+The field tells the help system, `describe` output, and the spawn guard in
+`src/utils/claude.ts` what Claude usage the command declares. It is optional,
+and takes one of four shapes:
+
+- `{ when: 'always'; what: string }` — the command always starts a session
+- `{ when: 'with'; flag: string; what: string }` — starts a session only when
+  the named flag is passed (flag written as `--resolve`, matched by name)
+- `{ when: 'unless'; flag: string; what: string }` — starts a session unless
+  the named flag is passed
+- `{ when: 'through'; what: string }` — may start a session through a
+  sub-command it calls
+
+The `what` field is a short phrase describing the session (e.g., "one planning
+session"). See `context/cli.md` for the command architecture and examples.
+
+---
+
 ## Examples
 
 Each module task below carries its own unit tests, and each stage closes on a test task over what its modules do together.