@open-tomato/rafa 0.7.1

package/LICENSE

@@ -0,0 +1,202 @@
+
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+   1. Definitions.
+
+      "License" shall mean the terms and conditions for use, reproduction,
+      and distribution as defined by Sections 1 through 9 of this document.
+
+      "Licensor" shall mean the copyright owner or entity authorized by
+      the copyright owner that is granting the License.
+
+      "Legal Entity" shall mean the union of the acting entity and all
+      other entities that control, are controlled by, or are under common
+      control with that entity. For the purposes of this definition,
+      "control" means (i) the power, direct or indirect, to cause the
+      direction or management of such entity, whether by contract or
+      otherwise, or (ii) ownership of fifty percent (50%) or more of the
+      outstanding shares, or (iii) beneficial ownership of such entity.
+
+      "You" (or "Your") shall mean an individual or Legal Entity
+      exercising permissions granted by this License.
+
+      "Source" form shall mean the preferred form for making modifications,
+      including but not limited to software source code, documentation
+      source, and configuration files.
+
+      "Object" form shall mean any form resulting from mechanical
+      transformation or translation of a Source form, including but
+      not limited to compiled object code, generated documentation,
+      and conversions to other media types.
+
+      "Work" shall mean the work of authorship, whether in Source or
+      Object form, made available under the License, as indicated by a
+      copyright notice that is included in or attached to the work
+      (an example is provided in the Appendix below).
+
+      "Derivative Works" shall mean any work, whether in Source or Object
+      form, that is based on (or derived from) the Work and for which the
+      editorial revisions, annotations, elaborations, or other modifications
+      represent, as a whole, an original work of authorship. For the purposes
+      of this License, Derivative Works shall not include works that remain
+      separable from, or merely link (or bind by name) to the interfaces of,
+      the Work and Derivative Works thereof.
+
+      "Contribution" shall mean any work of authorship, including
+      the original version of the Work and any modifications or additions
+      to that Work or Derivative Works thereof, that is intentionally
+      submitted to Licensor for inclusion in the Work by the copyright owner
+      or by an individual or Legal Entity authorized to submit on behalf of
+      the copyright owner. For the purposes of this definition, "submitted"
+      means any form of electronic, verbal, or written communication sent
+      to the Licensor or its representatives, including but not limited to
+      communication on electronic mailing lists, source code control systems,
+      and issue tracking systems that are managed by, or on behalf of, the
+      Licensor for the purpose of discussing and improving the Work, but
+      excluding communication that is conspicuously marked or otherwise
+      designated in writing by the copyright owner as "Not a Contribution."
+
+      "Contributor" shall mean Licensor and any individual or Legal Entity
+      on behalf of whom a Contribution has been received by Licensor and
+      subsequently incorporated within the Work.
+
+   2. Grant of Copyright License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      copyright license to reproduce, prepare Derivative Works of,
+      publicly display, publicly perform, sublicense, and distribute the
+      Work and such Derivative Works in Source or Object form.
+
+   3. Grant of Patent License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      (except as stated in this section) patent license to make, have made,
+      use, offer to sell, sell, import, and otherwise transfer the Work,
+      where such license applies only to those patent claims licensable
+      by such Contributor that are necessarily infringed by their
+      Contribution(s) alone or by combination of their Contribution(s)
+      with the Work to which such Contribution(s) was submitted. If You
+      institute patent litigation against any entity (including a
+      cross-claim or counterclaim in a lawsuit) alleging that the Work
+      or a Contribution incorporated within the Work constitutes direct
+      or contributory patent infringement, then any patent licenses
+      granted to You under this License for that Work shall terminate
+      as of the date such litigation is filed.
+
+   4. Redistribution. You may reproduce and distribute copies of the
+      Work or Derivative Works thereof in any medium, with or without
+      modifications, and in Source or Object form, provided that You
+      meet the following conditions:
+
+      (a) You must give any other recipients of the Work or
+          Derivative Works a copy of this License; and
+
+      (b) You must cause any modified files to carry prominent notices
+          stating that You changed the files; and
+
+      (c) You must retain, in the Source form of any Derivative Works
+          that You distribute, all copyright, patent, trademark, and
+          attribution notices from the Source form of the Work,
+          excluding those notices that do not pertain to any part of
+          the Derivative Works; and
+
+      (d) If the Work includes a "NOTICE" text file as part of its
+          distribution, then any Derivative Works that You distribute must
+          include a readable copy of the attribution notices contained
+          within such NOTICE file, excluding those notices that do not
+          pertain to any part of the Derivative Works, in at least one
+          of the following places: within a NOTICE text file distributed
+          as part of the Derivative Works; within the Source form or
+          documentation, if provided along with the Derivative Works; or,
+          within a display generated by the Derivative Works, if and
+          wherever such third-party notices normally appear. The contents
+          of the NOTICE file are for informational purposes only and
+          do not modify the License. You may add Your own attribution
+          notices within Derivative Works that You distribute, alongside
+          or as an addendum to the NOTICE text from the Work, provided
+          that such additional attribution notices cannot be construed
+          as modifying the License.
+
+      You may add Your own copyright statement to Your modifications and
+      may provide additional or different license terms and conditions
+      for use, reproduction, or distribution of Your modifications, or
+      for any such Derivative Works as a whole, provided Your use,
+      reproduction, and distribution of the Work otherwise complies with
+      the conditions stated in this License.
+
+   5. Submission of Contributions. Unless You explicitly state otherwise,
+      any Contribution intentionally submitted for inclusion in the Work
+      by You to the Licensor shall be under the terms and conditions of
+      this License, without any additional terms or conditions.
+      Notwithstanding the above, nothing herein shall supersede or modify
+      the terms of any separate license agreement you may have executed
+      with Licensor regarding such Contributions.
+
+   6. Trademarks. This License does not grant permission to use the trade
+      names, trademarks, service marks, or product names of the Licensor,
+      except as required for reasonable and customary use in describing the
+      origin of the Work and reproducing the content of the NOTICE file.
+
+   7. Disclaimer of Warranty. Unless required by applicable law or
+      agreed to in writing, Licensor provides the Work (and each
+      Contributor provides its Contributions) on an "AS IS" BASIS,
+      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+      implied, including, without limitation, any warranties or conditions
+      of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+      PARTICULAR PURPOSE. You are solely responsible for determining the
+      appropriateness of using or redistributing the Work and assume any
+      risks associated with Your exercise of permissions under this License.
+
+   8. Limitation of Liability. In no event and under no legal theory,
+      whether in tort (including negligence), contract, or otherwise,
+      unless required by applicable law (such as deliberate and grossly
+      negligent acts) or agreed to in writing, shall any Contributor be
+      liable to You for damages, including any direct, indirect, special,
+      incidental, or consequential damages of any character arising as a
+      result of this License or out of the use or inability to use the
+      Work (including but not limited to damages for loss of goodwill,
+      work stoppage, computer failure or malfunction, or any and all
+      other commercial damages or losses), even if such Contributor
+      has been advised of the possibility of such damages.
+
+   9. Accepting Warranty or Additional Liability. While redistributing
+      the Work or Derivative Works thereof, You may choose to offer,
+      and charge a fee for, acceptance of support, warranty, indemnity,
+      or other liability obligations and/or rights consistent with this
+      License. However, in accepting such obligations, You may act only
+      on Your own behalf and on Your sole responsibility, not on behalf
+      of any other Contributor, and only if You agree to indemnify,
+      defend, and hold each Contributor harmless for any liability
+      incurred by, or claims asserted against, such Contributor by reason
+      of your accepting any such warranty or additional liability.
+
+   END OF TERMS AND CONDITIONS
+
+   APPENDIX: How to apply the Apache License to your work.
+
+      To apply the Apache License to your work, attach the following
+      boilerplate notice, with the fields enclosed by brackets "[]"
+      replaced with your own identifying information. (Don't include
+      the brackets!)  The text should be enclosed in the appropriate
+      comment syntax for the file format. We also recommend that a
+      file or class name and description of purpose be included on the
+      same "printed page" as the copyright notice for easier
+      identification within third-party archives.
+
+   Copyright [yyyy] [name of copyright owner]
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.

package/NOTICE

@@ -0,0 +1,59 @@
+rafa
+Copyright 2026 Marcos Tomatti and the open-tomato contributors
+
+Licensed under the Apache License, Version 2.0 (see LICENSE).
+
+This product builds on the following works. Each is named here because
+rafa would not exist in this shape without it.
+
+1. template-agentic-research
+   https://github.com/marcostomatti/template-agentic-research
+   Copyright 2026 Marcos Tomatti. Licensed under the Apache License,
+   Version 2.0.
+   The loop implementation (the task runner, the plan and report
+   parsers, the effort collection and the tracker) was imported from
+   its `tools/ralph` directory and has been developed here since.
+
+2. Open Tomato
+   https://github.com/open-tomato
+   Copyright Marcos Tomatti and the open-tomato contributors. Licensed
+   under the MIT License.
+   rafa's first loop, the Tracker port's shape, the CLI event format and
+   the hive-learning design that rafa's learning port follows come from
+   projects of that organisation, most of which are not public yet.
+
+3. everything-claude-code, the `continuous-learning-v2` skill
+   https://github.com/affaan-m/everything-claude-code
+   Copyright (c) 2026 Affaan Mustafa. Licensed under the MIT License.
+   rafa's instinct record (trigger, action, confidence, evidence,
+   project and user scope) is adapted from that skill's instinct model.
+   No source file of that project is redistributed in this package.
+
+The MIT License, under which works 2 and 3 are made available:
+
+   Permission is hereby granted, free of charge, to any person obtaining
+   a copy of this software and associated documentation files (the
+   "Software"), to deal in the Software without restriction, including
+   without limitation the rights to use, copy, modify, merge, publish,
+   distribute, sublicense, and/or sell copies of the Software, and to
+   permit persons to whom the Software is furnished to do so, subject to
+   the following conditions:
+
+   The above copyright notice and this permission notice shall be
+   included in all copies or substantial portions of the Software.
+
+   THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
+   EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
+   MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
+   NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE
+   LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION
+   OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION
+   WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
+
+The loop itself, one fresh agent session per step over a plan kept on
+disk, is the "Ralph" technique described by Geoffrey Huntley
+(https://ghuntley.com/ralph/). It is an idea and carries no licence;
+it is named here because the project is named after it.
+
+rafa drives Claude Code, a product of Anthropic, PBC. rafa is not
+affiliated with or endorsed by Anthropic.

package/README.md

@@ -0,0 +1,362 @@
+# rafa
+
+Run a plan through the ralph loop: one Claude Code session per task, one
+commit per task, then a pull request and a wait for CI, from one
+terminal.
+
+What guides it:
+
+- **Tools before judgement.** Whatever code can decide, code decides: the
+  next task, the branch, the version, whether a pull request is green.
+  The agent is asked for the work itself and little else, which leaves
+  less to chance.
+- **Repeatable wherever it can be.** The steps around the agent are
+  scripts with tests, each run once and in a fixed order, so everything
+  that is not the agent's own writing comes out the same on a second
+  run, on another machine and after a resume.
+- **Your tools, not ours.** rafa drives what you already use (git, the
+  GitHub CLI, GitHub Issues) instead of rebuilding it, and keeps each of
+  those behind a small interface. Swapping one is meant to be an add-on,
+  not a migration: other issue trackers are on the way, starting with
+  Linear, and support for coding agents beyond Claude Code is being
+  specified.
+
+> **Alpha.** rafa is built with rafa, in the open, and it is not
+> finished: commands, files and defaults still change between versions,
+> and the [Roadmap](#roadmap) below says what is and is not there yet.
+> Feedback and bug reports are welcome at
+> [github.com/open-tomato/rafa/issues](https://github.com/open-tomato/rafa/issues/new/choose);
+> the order things are being built in is the pinned
+> [Roadmap issue](https://github.com/open-tomato/rafa/issues/31).
+
+## Before you run it
+
+Read this once; rafa also says it the first time you start a run.
+
+- **Every Claude Code session rafa starts runs with
+  `--dangerously-skip-permissions`.** That is what lets a plan run
+  unattended, and it means a task can edit, delete and run anything your
+  user account can, without asking. There is no switch for it yet.
+- **A run acts under your accounts.** It commits, pushes its branch,
+  opens a pull request with `gh`, waits for CI, and may file the
+  blockers and unrelated bugs it meets as issues on the project's
+  tracker.
+- **It spends your Claude usage**, one session per task plus the plan
+  and the wrap-up. `budget=` on a task caps that task.
+- So run it in a repository, on a branch and on a machine where all of
+  that is acceptable: a container or a disposable checkout is a good
+  first home. Nothing here is a sandbox.
+
+On a terminal, `rafa loop start` and `rafa plan create` print these
+notices and ask `Continue? [y] yes  [d] yes, and do not show this again
+[N] cancel`. Answering `d` records it in `~/.rafa/notices.json`
+(`{"dismissed": ["alpha", "danger"]}`); delete the file to see them
+again. Without a terminal they are printed as warnings and the run goes
+on.
+
+## Install
+
+The package is `@open-tomato/rafa` on npm (`publishConfig` names
+`https://registry.npmjs.org/` for the scope as well as in general, so a
+machine that maps `@open-tomato` to another registry still publishes
+there, and `npm publish` builds first through `prepack`). It installs globally under either package manager:
+
+```bash
+npm i -g @open-tomato/rafa
+```
+
+```bash
+bun add -g @open-tomato/rafa
+```
+
+Either one puts the `rafa` binary on `PATH`. The package declares no
+runtime dependency — `dependencies`, `peerDependencies` and
+`optionalDependencies` are all absent — so the install resolves nothing
+beyond the package itself. The binary and every export run under bun,
+which `engines` names: see [Runtime](#runtime) below.
+
+## How to use it
+
+The cycle is always the same five steps, and most commands end by naming
+the next one, so you rarely have to remember it.
+
+1. **Set the project up, once.** In the repository you want to work on:
+
+   ```bash
+   rafa init
+   rafa doctor
+   ```
+
+   `init` writes `.rafa/config.yaml`, keeps `.rafa/` out of git, and on a
+   GitHub repository offers to set up the board (labels, the spec issue
+   template, a pinned Roadmap issue). `doctor` runs every check
+   `loop start` runs before its first session, and starts nothing: the
+   prerequisites your config and the plan name, `gh` and its login when
+   the repository is on GitHub, and the install itself.
+
+2. **Write a spec.** A spec says what you get, where things stand, the
+   design, what can go wrong, the tasks the plan must carry, and how you
+   will know it is done. Either a file, `.rafa/specs/my-feature.md`, or
+   an issue opened from the "Spec" template and labelled `spec:ready`.
+   [docs/specs-and-roadmap.md](docs/specs-and-roadmap.md) has the
+   template and a prompt for drafting one.
+
+3. **Turn the spec into a plan.** One Claude Code session reads the spec
+   and the repository and writes a checklist the loop can parse:
+
+   ```bash
+   rafa plan create --spec=.rafa/specs/my-feature.md
+   rafa plan create --issue=42        # the spec is issue #42's body
+   rafa plan create --next            # the first undone line of the Roadmap issue
+   rafa plan show my-feature          # read it before you run it
+   ```
+
+   The plan lands in `.rafa/plans/PLAN-<stub>.md`, with a
+   `PREREQUISITES-<stub>.md` beside it when something has to be true
+   before the run. Read both. A plan is plain markdown: edit a task, drop
+   one, add one.
+
+4. **Run it.**
+
+   ```bash
+   rafa loop start --plan=.rafa/plans/PLAN-my-feature.md
+   ```
+
+   On `main` it offers to create `feat/<stub>` from the latest base and
+   run there. Then, per task: one Claude Code session, the task's report
+   stored, one commit. A task that reports `blocked` is marked and the
+   run stops with the reason; fix what it names and start again, and the
+   blocked task goes first. After the last task a wrap-up session syncs
+   with the base, bumps the version and the changelog when the project
+   has them, pushes, opens the pull request and waits for CI, spending
+   repair sessions on a red one.
+
+   From another terminal: `rafa loop status`, `rafa loop pause` (after the
+   running task), `rafa loop stop` (now).
+
+5. **Land it and look at what it cost.**
+
+   ```bash
+   rafa pr current        # number, title, checks, URL
+   rafa pr triage         # why is it red, and is the fix simple
+   rafa pr merge          # asks y/N, merges, switches to the base, pulls, deletes both branches
+   rafa release tag       # tag the merged version
+   rafa effort collect && rafa effort report
+   ```
+
+   Then step 2 again, or `rafa plan create --next`.
+
+### Which agents and skills are involved
+
+A task line may end with a declaration, for example
+`{agent=tdd-guide effort=medium}`. The planner writes it; you can change
+it.
+
+- `agent=` routes the task to a Claude Code subagent. The planner picks
+  by the task's SHAPE: implementation, tests, prose, a red build, a
+  review. This repository's own roster is in `.claude/agents/` and its
+  routing table in `context/workflow.md`; yours is whatever your project
+  holds.
+- Sessions load the project's agents and skills only
+  (`--setting-sources project,local`), which keeps each turn smaller and
+  makes a run behave the same on every machine. So an agent that exists
+  only in `~/.claude/agents` is invisible to a run: `rafa agent list`
+  shows what a run sees, `rafa agent vendor <name>` copies one in, and
+  `loop start` refuses a plan that names an agent it cannot resolve,
+  before any session is paid for.
+- The plan format itself is a skill, `dev-planner`, shipped inside the
+  package and used when the project has none of its own.
+- `rafa skill check .claude/skills --project=.` refuses a skill an agent
+  could not follow (a path that does not resolve, a missing field)
+  before it costs a task.
+- `model=`, `effort=`, `tools=` and `budget=` on a task line set the
+  session's model, reasoning effort, tool list and spending cap when no
+  agent decides them.
+
+Every command has help at three levels (`rafa --help`,
+`rafa loop --help`, `rafa loop start --help`), and
+`rafa describe --output=json` is the same roster for a tool or an agent.
+
+## Specs, issues and the roadmap
+
+You can plan from a local file and never touch a board. When you want
+the queue, the specs and their history in one shared place, rafa works
+from GitHub Issues:
+
+- **A spec is an issue**, opened from a template with six headings (what
+  you get, starting position, design, what can go wrong, tasks,
+  definition of done). `rafa init --board` sets up the template, the
+  labels and a pinned "Roadmap" issue.
+- **The roadmap is one ordered task list** in that pinned issue.
+  `rafa plan create --next` takes the first line that is neither done
+  nor already being worked on, and stops rather than skipping ahead when
+  that issue is not ready. `rafa plan create --issue=<n>` plans from one
+  issue directly.
+- **A few labels carry the state**: `type:spec`, `spec:ready` (a person
+  says a plan may be made from it), `spec:needs-work` (details pending,
+  or the planner's review found gaps and listed them), and `type:bug`
+  with `needs-triage` for what a run files on its own.
+- **Safety, in short.** An issue's text ends up in an agent's prompt, so
+  rafa plans only from an issue whose author can write to the
+  repository, that a maintainer has labelled `spec:ready`, that is
+  complete, and that holds no local path or token. Comments are never
+  read into a plan, rafa never applies `spec:ready` by itself, and
+  machine-specific failures a run meets stay off your public tracker.
+- **Other trackers.** GitHub Issues is what works today. Linear support
+  is being ported from the project rafa grew out of, as an optional
+  add-on in a later version. For anything else, open or upvote a request
+  in [the issues](https://github.com/open-tomato/rafa/issues).
+
+The full guide, with the spec template explained, a prompt for drafting
+a spec and every gate in order, is
+[docs/specs-and-roadmap.md](docs/specs-and-roadmap.md).
+
+## From a checkout
+
+To install dependencies:
+
+```bash
+bun install
+```
+
+To run the loop from a checkout (no arguments prints the help):
+
+```bash
+bun src/rafa.ts loop start --plan=<file>
+```
+
+Every command but `init`, the help and `describe` runs inside a rafa
+project: the nearest directory at or above the working directory holding
+`.rafa/config.yaml`. Outside one it prints the `rafa init` hint and exits
+1; `bun src/rafa.ts init --yes` sets up the git toplevel as one.
+
+`bun run build` writes `dist/`, which the `rafa` bin and the package's
+`exports` point at.
+
+This project was created using `bun init` in bun v1.3.14. [Bun](https://bun.com) is a fast all-in-one JavaScript runtime.
+
+## Running rafa from a snapshot
+
+Run the global `rafa` from a copy of the build, never from this
+checkout's `dist/`: `bun run build` opens with `rm -rf dist`, so a loop
+running from `dist/` has its runner replaced by the first task that
+builds. `bun run snapshot` in this checkout, or `rafa self-update` run
+inside it, builds, copies `dist/` into `~/.rafa/runtime/<version>/` with
+the version from `package.json`, points `~/.rafa/bin/rafa` at the copied
+`cli.js`, and prints the path the link resolves to, exiting 0. Both
+install the same way (`src/runtime/install.ts`). The bin is not in
+`~/.bun/bin`, where `bun link` in this checkout re-points `rafa` at the
+checkout's `dist/` with no message, so put `~/.rafa/bin` on `PATH` ahead
+of `~/.bun/bin`; both warn when it is not, and `rafa doctor` checks it.
+Both exit 1 before building anything while a plan tracker in `plan.dir`
+(`.rafa/plans` unless `.rafa/config.yaml` names another) still holds an
+open or blocked task, and name every such tracker. `rafa self-update`
+runs only inside a project, so `rafa init` the checkout first. They exit
+2 when they could not run: a `package.json` that is not rafa's or cannot
+be read, a config or tracker they could not read, or a build, copy or
+link that failed.
+
+A version is installed once. Both also exit 1, before building, when
+`~/.rafa/runtime/<version>/` is already there, naming that directory and
+the version `package.json` gave: a loop may be running from it, and a
+second build under the same version would swap its runner. Raise the
+version to install beside it. `bun run snapshot --force` and
+`rafa self-update --force` install over it anyway, replacing the
+directory whole, so nothing the old build left is kept: the replacement
+is copied beside the directory and renamed into its place, and only then
+is the old one removed, so no reader meets a half-replaced runtime. The
+link lands by a rename too, so a shell meets the old link or the new one
+and never none.
+
+## Runtime
+
+The build targets bun, and `engines` names `bun` alone: there is no
+`engines.node`, because no node version runs the binary. The package
+root, `./cli` and `./store` import `bun:sqlite`, which node's ESM loader
+refuses before any module code runs, so only `./plan` and `./ports` load
+under node at all. `module` points at `./dist/index.js`, the same build
+the root of `exports` names. The package ships no type declarations:
+`exports` names no `types`, and a TypeScript consumer gets TS7016 under
+`strict`.
+
+## Roadmap
+
+What rafa does today and what is planned, in the order it is being
+built. A box is ticked by the change that finishes the feature.
+
+- [x] Run a plan task by task: one Claude Code session per task, one
+  commit per task, then a pull request and a wait for CI
+- [x] Plans that carry their own background, so each task reads only the
+  part of the plan it needs
+- [x] Every task reports back what it did, what it found and what
+  blocked it, and rafa keeps the record
+- [x] See what each plan cost: sessions, tokens and commits per plan
+- [x] Install once, set up any project with `rafa init`
+- [x] Checks before a run: a missing tool or key stops the run with its
+  name, before any session is paid for
+- [x] A spending cap per task
+- [x] One consistent command line, with help at every level that people
+  and agents can both read
+- [x] Stop, pause, resume and check on a running plan
+- [x] Blockers and unrelated bugs found along the way are filed as
+  issues, once each
+- [x] rafa can safely work on its own code and update itself
+- [x] Usable as a library inside other services, not only as a command
+- [x] A health check for skills: one format, and a checker that refuses
+  a broken skill before an agent can follow it
+- [x] The agents a plan needs are checked before the run, and copied
+  into the project with one command
+- [x] Plan straight from the issue board, or from whatever is next on the roadmap
+- [x] Review, merge and clean up pull requests from the command line
+- [x] A failing pull request is diagnosed, and fixed when the fix is simple
+- [x] A version bump and a changelog entry with every pull request
+- [x] Start a plan from the main branch and rafa makes the branch for you
+- [ ] The right skills reach the right task, chosen when the plan is
+  written
+- [ ] Know which skills earn their place and which are ignored
+- [ ] rafa learns from its own runs: what one task works out is handed
+  to the tasks that need it later
+- [ ] Skills and lessons shared across projects and machines
+- [ ] Work on several issues or specs at the same time
+- [ ] Add-ons: install a tracker, an output or a set of skills (Linear,
+  Obsidian and others) without changing rafa
+- [ ] A live terminal dashboard
+
+## Attribution
+
+rafa stands on other people's work and on earlier work of ours.
+[NOTICE](NOTICE) carries the licences; this is the story.
+
+- **The Ralph technique.** Running an agent in a plain loop, one fresh
+  session per step over a plan kept on disk, is the "Ralph" technique
+  described by Geoffrey Huntley in
+  [Ralph Wiggum as a "software engineer"](https://ghuntley.com/ralph/).
+  The name "ralph loop" in this project is a nod to it. What rafa adds
+  around the loop (plans with declared routing, structured task reports,
+  preflight, effort records, the pull request and CI stage) is ours; the
+  idea of the loop is not.
+- **Open Tomato.** rafa's first loop, its issue-tracker port, its CLI
+  event format and the learning design below come from projects in the
+  [open-tomato](https://github.com/open-tomato) organisation. Most of
+  them are not public yet; this section will link the specific
+  repositories as they are published.
+- **Loop implementation.** The code rafa started from was imported from
+  [`marcostomatti/template-agentic-research`](https://github.com/marcostomatti/template-agentic-research)
+  (Apache-2.0), where the loop had grown its plan and report parsers,
+  effort collection and tracker.
+- **Instinct model.** The instinct record (trigger, action, confidence,
+  evidence, scope) is adapted from the `continuous-learning-v2` skill of
+  [`affaan-m/everything-claude-code`](https://github.com/affaan-m/everything-claude-code)
+  by Affaan Mustafa (MIT).
+- **Shared learning (coming).** The design for merging what separate
+  runs learn (one record per lesson, a rule for conflicting lessons,
+  promotion on recurrence) follows Open Tomato's hive-learning design.
+  In rafa it is partly built: lessons are recorded per project today, and
+  sharing them across runs, projects and machines is on the
+  [Roadmap](#roadmap) and not available yet.
+
+## License
+
+Apache-2.0; see [LICENSE](LICENSE). [NOTICE](NOTICE) names the works
+rafa builds on and their licences. rafa drives Claude Code and is not
+affiliated with or endorsed by Anthropic.

package/dist/PROMPT.md

@@ -0,0 +1,28 @@
+We shared as much of the plan as this run is configured to share — the whole plan, your task's stage, or your task line with the plan's context — so you know the context of the overall project and how your scoped task fits into it. Deliver the scoped task at the scope its text states: don't quietly narrow, widen or transform it. Nobody can answer a question while this session runs, so finish the whole task before you write `status: done`; if part of it genuinely cannot be done, do the rest, write `status: blocked`, and name what is missing and why under `blockers`.
+
+Do not stage or commit anything: the loop owns staging and committing, and once this session exits cleanly it runs `git add -A` and commits your work under a subject derived from the task text. Leave your changes in the working tree, and leave them in a state the pre-commit hooks accept — a refused hook blocks the task and stops the loop.
+
+End your final message with exactly one `rafa:report` block shaped like the example below, and write nothing after it: the loop stores what it reads there, and a message without the block stores none of your findings. Write all seven fields, `status`, `feedback`, `findings`, `skills_used`, `blockers`, `out_of_scope_bugs` and `changes`, and write a list with nothing in it as `[]` rather than leaving its field out. `status` is `done` or `blocked`. `feedback` says what was done and how it went. `findings` is a list with one entry per distinct observation, never several merged into one; a finding's `kind` is one of `gotcha`, `pattern`, `location` or `skill-suggestion`, its `signal` is `loud` when it surfaced as a failure or `silent` when something passed while wrong, and its `artifact`, when there is one, is the exact string a recurrence would match on, such as an error message. `skills_used` names each skill you invoked. `blockers` lists what stopped the task, each entry a `what` and, when there is one, an `artifact`, `out_of_scope_bugs` the bugs you saw outside it, each bug with `security` set to `true` or `false`, and `changes` is the changelog for your diff, each entry holding the required fields `level` (one of patch, minor, major, none) and `summary` (a quoted line the user would understand), plus optional `area` (the changelog section). Write those closed-set words and `security` bare, as the example does, and double-quote every other value on one line: an unquoted value that opens with a backtick, `@`, `%` or `[` makes the whole block unreadable, and a `#` after a space silently cuts a value short.
+
+```rafa:report
+status: done
+feedback: |
+  <what was done and how it went, one block>
+findings:
+  - trigger: "when running bun test under a fresh worktree"
+    kind: gotcha
+    what: "node_modules is absent after fork"
+    cause: "worktree creation does not run bun install"
+    resolution: "run bun install before the first test"
+    artifact: "Cannot find package"
+    signal: loud
+skills_used: ["git-workflow"]
+blockers: []
+out_of_scope_bugs:
+  - what: "..."
+    artifact: "..."
+    security: false
+changes:
+  - level: patch
+    summary: "the loop waits for the running task's commit"
+```