@open-tomato/rafa 0.26.0 → 0.28.0

package/README.md

@@ -175,11 +175,12 @@ the next one, so you rarely have to remember it.
 ### Tracking effort and learning from skills
 
 Each run records what it cost in time, tokens and work, and which skills
-were offered, invoked and worked. Two commands read that record:
+were offered, invoked and worked. Key commands for the effort record:
 
 ```bash
 rafa effort collect        # gather and store session logs
 rafa effort report         # per-plan summary: sessions, tasks, costs
+rafa effort merge <file>   # join another device's store into this one
 ```
 
 `rafa effort report` shows the per-plan tables (sessions by status and
@@ -210,6 +211,26 @@ The report opens with a fixed line explaining that it shows co-occurrence,
 not causation: a skill can be invoked and its failure recur for reasons the
 skill does not cover.
 
+### Starting a second device
+
+To run rafa on a second device for the same project, bring the effort
+store over consistently:
+
+1. On the new device, check for an existing `.rafa/effort/` store and set
+   it aside (rename or back up).
+2. From the primary device, make a consistent copy:
+   ```bash
+   rafa effort copy --to=<path>
+   ```
+   Or use `sqlite3 .rafa/effort/effort.sqlite ".backup <path>"`, but never
+   a plain file copy during a write.
+3. Transfer the copied store and `.rafa/config.yaml` to the new device's
+   `.rafa/` directory.
+4. After both devices have recorded effort, bring them back together with:
+   ```bash
+   rafa effort merge <copied-store-file>
+   ```
+
 ### Which agents and skills are involved
 
 A task line may end with a declaration, for example
@@ -376,6 +397,19 @@ from GitHub Issues:
   file `.rafa/position.json` holds your current place, where you were, and
   where you came from — the same two-slot pattern as `cd -` and
   `git checkout -`, plus a home anchor.
+- **Hopping between epics with `rafa next --roadmap`.** When your epic's
+  work is blocked by an issue in another epic, `rafa next --roadmap`
+  reaches for that blocker, works it, and comes home. You hold two slots:
+  home (your anchor) and current (the work in hand). Reaching for a third
+  would mean letting go of home, so rafa halts if a blocker is itself
+  blocked. The pattern keeps unattended work safe: a hop into another
+  team's epic asks for that team's review before it changes their code.
+  Solo projects see a dry hop — the useful part without the permission
+  check. One team hops between its own epics. Several teams open a pull
+  request when a hop crosses to another board, and `rafa status` says
+  `waiting on #C (owner review)` until the team reviews and approves. The
+  hop record (`.rafa/hop.json`) tracks where home is and what rafa works.
+  When `rafa next` finishes, it deletes the record and returns home.
 - **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