@hacksmith/doraval 0.2.45 → 0.2.47

package/README.md

@@ -1,10 +1,14 @@
 # doraval
 
-The context engineering toolkit for coding agents.
+The context engineering toolkit for coding agent orchestrators.
 
-If you've ever shipped a Claude Code skill that stopped firing after a refactor, or wondered whether your plugin's structure actually matches what the agent expects — doraval validates that before it becomes a runtime surprise.
+If you're a senior engineer handing skills to new team members, a company publishing AI resources, or anyone who wants agents (and humans) to succeed on the first attempt instead of after days of debugging — this is for you.
 
-> **Quick start:**
+**The orchestrator problem:** Give 10 new engineers (or agents) a skill and only 3/10 succeed on the first try. 4/10 take hours. 7/10 take a day. 10/10 take days.
+
+doraval helps you **left-shift success** — validate, scaffold, and manage context so the first attempt works across Claude, Cursor, Codex, Copilot, and whatever comes next.
+
+> **Quick start (left-shift success in < 2 minutes):**
 > ```bash
 > # macOS
 > brew install saif-shines/tap/doraval
@@ -14,7 +18,7 @@ If you've ever shipped a Claude Code skill that stopped firing after a refactor,
 > npx @hacksmith/doraval validate .
 > ```
 
-Point it at any local directory or GitHub URL. It auto-detects what you have and tells you what's broken.
+Validate before you hand a skill to a new engineer or publish it. It auto-detects issues across agents and tells you what's broken.
 
 ## Install
 
@@ -130,6 +134,21 @@ doraval skill drift ./skills/my-skill/
 | **Guardrail** | Has explicit `MUST` / `MUST NOT` constraints |
 | **Clarity** | Free of ambiguous words (`maybe`, `perhaps`, `consider`) |
 
+### `eval` — Did the agent follow the skill?
+
+After a real session, evaluate whether the coding agent actually adhered to the skills it invoked.
+
+```bash
+doraval eval                    # pick from recent sessions interactively
+doraval eval --verbose
+doraval judge ./skills/improve/ # evaluate latest session for one skill
+doraval eval history
+```
+
+`eval` uses an LLM judge (via your configured agent) to produce a per-skill `PASS`/`FAIL` with a dynamic checklist, user familiarity score, and closure information (1-shot vs multi-turn vs incomplete).
+
+Requires `doraval init` first. See the [full docs](https://thehacksmith.dev/commands/eval/).
+
 ### `journal` — Decision memory
 
 Record and sync project principles so future you (and agents) don't accidentally contradict past choices.
@@ -173,6 +192,7 @@ doraval claude new          # interactive wizard for skills/plugins (follows off
 doraval validate . --for claude --format json --ci
 doraval skill validate ./my-skill/ --format json --ci
 doraval skill drift ./my-skill/ --format json --ci
+doraval eval --ci --format json
 ```
 
 Exits with code `1` when errors are found. Pipe `--format json` output to `jq` or consume programmatically.