rhachet 1.19.0 → 1.19.2

package/package.json

@@ -2,7 +2,7 @@
   "name": "rhachet",
   "author": "ehmpathy",
   "description": "A framework for reliable, thorough thought. Weave threads of thought via stitches.",
-  "version": "1.19.0",
+  "version": "1.19.2",
   "repository": "ehmpathy/rhachet",
   "homepage": "https://github.com/ehmpathy/rhachet",
   "keywords": [

package/readme.md

@@ -11,11 +11,11 @@ a framework for reliable, composable, and iteratively improvable thought.
 
 rhachet makes it simple to leverage thought routes - safely, easily, and effectively.
 
-- 🪨 **solid** routes for deterministic automation
-- 🔩 **rigid** routes for augmented workflows
-- 🌊 **fluid** routes for open-ended exploration
+- 🪨 **solid** routes for deterministic operations
+- 🔩 **rigid** routes for augmented orchestration
+- 💧 **fluid** routes for probabalistic exploration
 
-with rhachet, you can:
+with rhachet, you can
 - declare thought routes, reusably and maintainably
 - apply thought routes, observably and reliably
 - compose and accumulate reusable thought skill
@@ -28,49 +28,54 @@ with rhachet, you can:
 
 thought routes describe the determinism profile of an execution path.
 
-| route       | what                                             | when to use                          |
-| ----------- | ------------------------------------------------ | ------------------------------------ |
-| 🪨 **solid** | deterministic throughout                         | scripted automation, data transforms |
-| 🔩 **rigid** | deterministic harness + probabilistic operations | augmented workflows, controlled ai   |
-| 🌊 **fluid** | probabilistic throughout                         | exploration, open-ended problems     |
+| route       | what                                             | when to use                                      |
+| ----------- | ------------------------------------------------ | ------------------------------------------------ |
+| 🪨 **solid** | deterministic throughout                         | whenever you can; faster, cheaper, more reliable |
+| 🔩 **rigid** | deterministic harness + probabilistic operations | when you can control the flow, brain fills gaps  |
+| 💧 **fluid** | probabilistic throughout                         | when brain must decide the flow                  |
 
 the key distinction:
 - 🔩 **rigid**: you know when thought is needed, harness controls
-- 🌊 **fluid**: you don't know when or what thought is needed, brain decides
+- 💧 **fluid**: you don't know when or what thought is needed, brain decides
 
 ## brains
 
 brains are probabilistic imagination mechanisms that provide creative thought capabilities:
 
-| type | what | characteristics |
-| ---- | ---- | --------------- |
-| **brain.atom** | single inference | stateless, one-shot |
+| type           | what                 | characteristics                |
+| -------------- | -------------------- | ------------------------------ |
+| **brain.atom** | single inference     | stateless, one-shot            |
 | **brain.repl** | read-eval-print-loop | stateful, multi-turn, tool use |
 
 brain.atom is for single-turn operations. brain.repl is for multi-turn operations.
 
 ## actors, roles, skills, briefs
 
-rhachet organizes thought operators into a composable hierarchy:
+rhachet organizes thought operators into a composable hierarchy
 
 ```
-actor = brain + role
-role = skills + briefs
+actor
+├── brain
+└── role
+    ├── briefs
+    └── skills
 ```
 
-| concept   | what                               | example                                 |
-| --------- | ---------------------------------- | --------------------------------------- |
-| **actor** | a brain assuming a role            | mechanic actor (claude + mechanic role) |
-| **role**  | a bundle of skills + briefs        | mechanic, reviewer, architect           |
-| **skill** | an executable capability           | review, deliver, init                   |
-| **brief** | context and knowledge for the role | coding standards, domain patterns       |
+| concept     | what                               | example                                      |
+| ----------- | ---------------------------------- | -------------------------------------------- |
+| 🎭 **actor** | a brain in a role                  | mechanic actor (brain:codex + role:mechanic) |
+| 🧢 **role**  | a bundle of skills + briefs        | mechanic, reviewer, architect                |
+| 📚 **brief** | curated knowledge for the role     | code standards, domain patterns              |
+| 💪 **skill** | executable capability for the role | review, deliver, decompose                   |
 
-roles are portable - the same role can be assumed by different brains.
+actors cause action - yet are not agents until delegated to.
 
-skills are composable - they can invoke other skills, nest thought routes, and build complexity incrementally.
+roles are portable - the same role can be assumed by different brains.
 
 briefs are cumulative - they encode institutional knowledge that improves over time.
 
+skills are composable - they can invoke other skills, nest thought routes, and build complexity incrementally.
+
 # install
 
 ```sh
@@ -81,13 +86,13 @@ npm install rhachet
 
 ## cli
 
-rhachet provides cli commands for each thought route:
+rhachet provides cli commands for each thought route
 
 | command           | route   | what it does                               |
 | ----------------- | ------- | ------------------------------------------ |
 | `npx rhachet run` | 🪨 solid | execute a shell skill, no brain            |
 | `npx rhachet act` | 🔩 rigid | execute a skill with deterministic harness |
-| `npx rhachet ask` | 🌊 fluid | converse with an actor, brain decides path |
+| `npx rhachet ask` | 💧 fluid | converse with an actor, brain decides path |
 
 ### setup
 
@@ -106,14 +111,16 @@ export const getRoleRegistries = () => [
 
 ### 🪨 solid: run
 
+deterministic operations, no brain.
+
 ```sh
 npx rhachet run --skill gh.workflow.logs --workflow test
 ```
 
-deterministic execution, no brain involved.
-
 ### 🔩 rigid: act
 
+augmented orchestration, harness controls flow, brain augments.
+
 ```sh
 npx rhachet act \
   --role mechanic --skill review \
@@ -125,9 +132,9 @@ npx rhachet act \
   --brain openai/codex
 ```
 
-deterministic harness controls flow, brain operations are wrapped and validated.
+### 💧 fluid: ask
 
-### 🌊 fluid: ask
+probabilistic exploration, brain decides the path.
 
 ```sh
 npx rhachet ask \
@@ -135,17 +142,15 @@ npx rhachet ask \
   --ask "are birds real?"
 ```
 
-brain decides the path, exploration is the goal.
-
 ## sdk
 
 rhachet provides a type-safe sdk for programmatic actor usage.
 
-| method         | route   | what it does                               |
-| -------------- | ------- | ------------------------------------------ |
-| `actor.run()`  | 🪨 solid | execute a shell skill, no brain            |
-| `actor.act()`  | 🔩 rigid | execute a skill with deterministic harness |
-| `actor.ask()`  | 🌊 fluid | converse with an actor, brain decides path |
+| method        | route   | what it does                               |
+| ------------- | ------- | ------------------------------------------ |
+| `actor.run()` | 🪨 solid | execute a shell skill, no brain            |
+| `actor.act()` | 🔩 rigid | execute a skill with deterministic harness |
+| `actor.ask()` | 💧 fluid | converse with an actor, brain decides path |
 
 ### setup
 
@@ -172,16 +177,18 @@ the `brains` allowlist:
 
 ### 🪨 solid: run
 
+deterministic operations, no brain.
+
 ```ts
 await mechanic.run({
   skill: { 'gh.workflow.logs': { workflow: 'test' } },
 });
 ```
 
-deterministic execution, no brain involved.
-
 ### 🔩 rigid: act
 
+augmented orchestration, harness controls flow, brain augments.
+
 ```ts
 // uses default brain (first in allowlist)
 await mechanic.act({
@@ -195,18 +202,16 @@ await mechanic.act({
 });
 ```
 
-deterministic harness controls flow, brain operations are wrapped and validated.
+### 💧 fluid: ask
 
-### 🌊 fluid: ask
+probabilistic exploration, brain decides the path.
 
 ```ts
-await mechanic.ask({
+await skeptic.ask({
   prompt: 'are birds real?',
 });
 ```
 
-brain decides the path, exploration is the goal.
-
 # vision
 
 build or use digital actors, who work even from your laptop, and work for anyone you choose.