@open-tomato/rafa 0.18.0 → 0.20.0

package/README.md

@@ -174,8 +174,8 @@ the next one, so you rarely have to remember it.
 ### 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=tdd-guide skills=dev-planner 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
@@ -196,8 +196,8 @@ it.
   while the project or a loaded user tier holds a different copy, and a
   `project` pin while a loaded user tier does; pin the tier the refusal
   names, or delete or rename the copy it names. `loop start` refuses a
-  plan that names an agent it cannot resolve before any session is paid
-  for.
+  plan that names an agent or a skill it cannot resolve before any
+  session is paid for.
 - User-tier items are invisible unless `loop.settingSources` includes
   `user`. `rafa agent list` shows what a run sees, `rafa agent vendor
   <name>` copies one in or updates it, and `rafa skill check .claude/skills
@@ -205,6 +205,25 @@ it.
   not resolve, a missing field) before it costs a task.
 - The plan format itself is a skill, `dev-planner`, shipped in the rafa
   tier and used when the project has none of its own.
+- **Skills for this task.** A task may declare the skills it needs with
+  `skills=skill1,skill2` on its line. At dispatch, one of three resolvers
+  picks which skills to offer: `planner` uses the task's `skills=`
+  declaration exactly, in order; `tag` ignores `skills=` and ranks every
+  enabled skill against the task text to find the top 3 scoring above a
+  floor of zero; `none` offers no skills. The resolver is set by
+  `task.skills` in `.rafa/config.yaml` (defaulting to `planner`), and the
+  `--skills-resolver=` flag overrides it. A compact skill index is listed
+  in the planner's prompt so the planner sees what skills are available
+  before writing the task. When a task is dispatched, the prompt gains a
+  "Skills for this task" section with the skills the resolver picked, or
+  stays unchanged if none were picked. The dispatch record stores the
+  resolver name and which skills were offered.
+- **Lessons from earlier tasks.** Up to 5 lessons from the learning store
+  are added to a task's prompt as a "Lessons from earlier tasks" section
+  when `task.lessons` is `on` (the default). The lessons are blessed
+  passages from earlier task findings that recurred or reached a
+  confidence floor. When neither skills nor lessons appear, the prompt
+  stays unchanged from before.
 - `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.
@@ -352,9 +371,9 @@ and never none.
 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:
+refuses before any module code runs, so only `./plan`, `./ports` and
+`./learning` 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`.
 
@@ -411,7 +430,7 @@ and a line here is ticked by the change that finishes the feature.
 - ✅ 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
+- ✅ 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
 - ⬜ Config as code: a typed `rafa.config.ts` holding your settings, your
@@ -465,12 +484,15 @@ rafa stands on other people's work and on earlier work of ours.
   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.
+- **Shared learning.** 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. rafa now records
+  lessons in `.rafa/instincts/` — one lesson per task finding that carries
+  a resolution — and pushes them after each task's report. Lessons that
+  meet a confidence floor are blessed and handed to tasks that need them
+  later; lessons that recur enough are promoted into the pages that own
+  their subjects. Sharing lessons across projects and machines is planned
+  for a future version.
 
 ## License
 

package/dist/PROMPT.md

@@ -2,7 +2,7 @@ We shared as much of the plan as this run is configured to share — the whole p
 
 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.
+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. A finding may also carry a `domain`, the area of work its lesson belongs to, one of `code-style`, `testing`, `git`, `debugging`, `workflow`, `security` or `general-best-practices`; leave it out when none fits. `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
@@ -16,6 +16,7 @@ findings:
     resolution: "run bun install before the first test"
     artifact: "Cannot find package"
     signal: loud
+    domain: testing
 skills_used: ["git-workflow"]
 blockers: []
 out_of_scope_bugs:

package/dist/bundled/skills/dev-planner/SKILL.md

@@ -223,6 +223,7 @@ findings:
     resolution: "wrap append in try/finally"
     artifact: "EMFILE: too many open files"
     signal: loud
+    domain: debugging
   - trigger: "SQLite schema migration timing"
     kind: pattern
     what: "migrations run on every store init, not just schema changes"
@@ -262,6 +263,7 @@ Finding entry fields:
 | `resolution` | string | no | How to fix or work around it |
 | `artifact` | string | no | Error message, file path, or code snippet that signals the finding |
 | `signal` | string | yes | `loud` (it surfaced as a failure) or `silent` (it passed while wrong) |
+| `domain` | string | no | The area of work the finding's lesson belongs to: `code-style`, `testing`, `git`, `debugging`, `workflow`, `security` or `general-best-practices`. A value outside the set is reported as an issue and read as absent |
 
 Change note entry fields:
 
@@ -358,12 +360,19 @@ The recognised keys are the `DECLARATION_KEYS` of `src/utils/declaration.ts`, wh
 
 ### `skills=` declaration
 
+When a task needs help from a skill, name those skills with `skills=`. Skill names must come from the skill index provided in this prompt; naming a skill no tier holds is recorded as an issue. Names are comma-separated with no spaces.
+
 `skills` is a recognised key that maps to no flag: there is no CLI flag for a skill, so the names are parsed, kept on the dispatch record and stripped from the task text with the rest of the block. It stands on its own — `{skills=bun-testing}` is a declaration with no other key beside it — and a value that is not a comma-separated list of skill names is recorded as an issue rather than passed on.
 
+A task with no `skills=` declaration is valid — naming none is the answer when no skill guides the task.
+
 ```markdown
   - [ ] Port vitest tests to bun:test  {agent=build-error-resolver skills=bun-testing,vitest-migration}
+  - [ ] Add the Zod schema for `CreateJobRequest` with its unit tests
 ```
 
+The second example above has no `skills=` and is still a valid task declaration.
+
 ---
 
 ## Task sizing (session economics)