improve(ralph): optimize plugin for simplicity and token efficiency

.autoresearch/autoresearch.jsonl

@@ -1,28 +1,25 @@
-{"type":"config","name":"create-pr-optimize","metricName":"total_bytes","metricUnit":"bytes","bestDirection":"lower"}
-{"run":1,"commit":"d018e0f","metric":9073,"metrics":{"line_count":284,"file_count":6,"word_count":1375},"status":"keep","description":"baseline","timestamp":1775130716,"segment":0}
-{"run":2,"commit":"9e5692e","metric":6268,"metrics":{"line_count":183,"file_count":6,"word_count":917},"status":"keep","description":"compress scripts - remove verbose messages and redundant comments","timestamp":1775130811,"segment":0}
-{"run":3,"commit":"17e69a5","metric":5836,"metrics":{"line_count":169,"file_count":6,"word_count":844},"status":"keep","description":"compress SKILL.md prose","timestamp":1775130856,"segment":0}
-{"run":4,"commit":"6265fd9","metric":4534,"metrics":{"line_count":141,"file_count":5,"word_count":666},"status":"keep","description":"remove unused verify-pr-status.sh","timestamp":1775130894,"segment":0}
-{"run":5,"commit":"3eb5c55","metric":4019,"metrics":{"line_count":122,"file_count":4,"word_count":601},"status":"keep","description":"merge sync-with-base into preflight-check","timestamp":1775130966,"segment":0}
-{"run":6,"commit":"d790d50","metric":3558,"metrics":{"line_count":107,"file_count":3,"word_count":541},"status":"keep","description":"inline lib.sh into preflight, remove lib.sh","timestamp":1775131007,"segment":0}
-{"run":7,"commit":"9706617","metric":3202,"metrics":{"line_count":85,"file_count":3,"word_count":490},"status":"keep","description":"further compress SKILL.md","timestamp":1775131034,"segment":0}
-{"run":8,"commit":"9725788","metric":3103,"metrics":{"line_count":82,"file_count":3,"word_count":471},"status":"keep","description":"compact wait-for-merge.sh","timestamp":1775131065,"segment":0}
-{"run":9,"commit":"7f78174","metric":2884,"metrics":{"line_count":68,"file_count":3,"word_count":448},"status":"keep","description":"further compress preflight-check.sh","timestamp":1775131088,"segment":0}
-{"type":"config","name":"create-pr-skill-tokens","metricName":"skill_bytes","metricUnit":"bytes","bestDirection":"lower"}
-{"run":10,"commit":"1b650ac","metric":1081,"metrics":{"skill_lines":27,"skill_words":151,"script_bytes":1803},"status":"keep","description":"baseline (segment 1 — skill_bytes only)","timestamp":1775131168,"segment":1}
-{"run":11,"commit":"6ba0c3d","metric":802,"metrics":{"skill_lines":23,"skill_words":110,"script_bytes":1803},"status":"keep","description":"compress SKILL.md — remove redundant sections","timestamp":1775131195,"segment":1}
-{"run":12,"commit":"ec416bc","metric":732,"metrics":{"skill_lines":19,"skill_words":100,"script_bytes":1803},"status":"keep","description":"extract script path variable S=","timestamp":1775131213,"segment":1}
-{"run":13,"commit":"9bb6f1e","metric":675,"metrics":{"skill_lines":18,"skill_words":93,"script_bytes":1803},"status":"keep","description":"merge inline comments, remove bold","timestamp":1775131235,"segment":1}
-{"run":14,"commit":"563874d","metric":635,"metrics":{"skill_lines":18,"skill_words":82,"script_bytes":1803},"status":"keep","description":"micro-compress wording","timestamp":1775131249,"segment":1}
-{"run":15,"commit":"059de59","metric":605,"metrics":{"skill_lines":17,"skill_words":82,"script_bytes":1803},"status":"keep","description":"remove explicit template path","timestamp":1775131290,"segment":1}
-{"run":16,"commit":"059de59","metric":608,"metrics":{"skill_lines":16,"skill_words":83,"script_bytes":1803},"status":"discard","description":"merge pr create+merge into one line (bytes increased)","timestamp":1775131309,"segment":1}
-{"run":17,"commit":"96b1a8f","metric":665,"metrics":{"skill_lines":17,"skill_words":92,"script_bytes":1818},"status":"keep","description":"add auto-merge re-enable after CI fix + push -u","timestamp":1775132341,"segment":1}
-{"run":18,"commit":"17c7ef7","metric":665,"metrics":{"skill_lines":17,"skill_words":92,"script_bytes":1818},"status":"keep","description":"edge test: main branch — agent skipped script, did manual logic","timestamp":1775132900,"segment":1}
-{"run":19,"commit":"b2e1f87","metric":794,"metrics":{"skill_lines":20,"skill_words":109,"script_bytes":1818},"status":"keep","description":"clarify scripts MUST be run (test-driven fix)","timestamp":1775132948,"segment":1}
-{"run":20,"commit":"b2e1f87","metric":794,"metrics":{"skill_lines":20,"skill_words":109,"script_bytes":1818},"status":"keep","description":"edge test: nothing-to-commit — agent stopped correctly but preflight ran unnecessarily","timestamp":1775133044,"segment":1}
-{"run":22,"commit":"b2e1f87","metric":794,"metrics":{"skill_lines":20,"skill_words":109,"script_bytes":1818},"status":"keep","description":"must-run test passed, found broken tests referencing deleted scripts","timestamp":1775133359,"segment":1}
-{"run":23,"commit":"dece665","metric":794,"metrics":{"skill_lines":20,"skill_words":109,"script_bytes":1818},"status":"keep","description":"fix broken tests for deleted scripts — 63/63 pass","timestamp":1775133491,"segment":1}
-{"run":25,"commit":"dece665","metric":794,"metrics":{"skill_lines":20,"skill_words":109,"script_bytes":1818},"status":"keep","description":"final validation — both scripts executed, 14 tool calls, PR #607 merged","timestamp":1775133750,"segment":1}
-{"run":26,"commit":"6a0be38","metric":794,"metrics":{"skill_lines":20,"skill_words":109,"script_bytes":1802},"status":"keep","description":"remove --delete-branch from fallback merge","timestamp":1775133769,"segment":1}
-{"run":27,"commit":"494dc0b","metric":776,"metrics":{"skill_lines":20,"skill_words":107,"script_bytes":1802},"status":"keep","description":"remove re-run preflight, reorder main check","timestamp":1775133796,"segment":1}
-{"run":28,"commit":"b792e67","metric":776,"metrics":{"skill_lines":21,"skill_words":107,"script_bytes":1802},"status":"keep","description":"wrap CI fail line for markdownlint","timestamp":1775133928,"segment":1}
+{"type":"config","name":"ralph-optimize","metricName":"skill_bytes","metricUnit":"bytes","bestDirection":"lower"}
+{"run":1,"commit":"c8c2fa1","metric":2914,"metrics":{"skill_lines":90,"cancel_bytes":696,"hook_bytes":3747,"hook_lines":138,"total_bytes":7357},"status":"keep","description":"baseline","timestamp":1775210437,"segment":0}
+{"run":2,"commit":"6934219","metric":1710,"metrics":{"skill_lines":52,"cancel_bytes":696,"hook_bytes":3747,"hook_lines":138,"total_bytes":6153},"status":"keep","description":"compress SKILL.md — flatten JSON, remove redundant prose","timestamp":1775210484,"segment":0}
+{"run":3,"commit":"afeef81","metric":1364,"metrics":{"skill_lines":41,"cancel_bytes":696,"hook_bytes":3747,"hook_lines":138,"total_bytes":5807},"status":"keep","description":"further compress SKILL.md — shorten sections, tighten wording","timestamp":1775210509,"segment":0}
+{"run":4,"commit":"c4b4aba","metric":1364,"metrics":{"skill_lines":41,"cancel_bytes":431,"hook_bytes":3747,"hook_lines":138,"total_bytes":5542},"status":"keep","description":"compress ralph-cancel SKILL.md","timestamp":1775210530,"segment":0}
+{"run":5,"commit":"d70b5f9","metric":1364,"metrics":{"skill_lines":41,"cancel_bytes":431,"hook_bytes":2725,"hook_lines":74,"total_bytes":4520},"status":"keep","description":"simplify ralph-persist.ts — remove interfaces, inline functions","timestamp":1775210565,"segment":0}
+{"run":6,"commit":"01d96d4","metric":1260,"metrics":{"skill_lines":40,"cancel_bytes":431,"hook_bytes":2725,"hook_lines":74,"total_bytes":4416},"status":"keep","description":"micro-compress SKILL.md — merge steps, shorten JSON","timestamp":1775210587,"segment":0}
+{"run":7,"commit":"974f67c","metric":1260,"metrics":{"skill_lines":40,"cancel_bytes":431,"hook_bytes":2157,"hook_lines":52,"total_bytes":3848},"status":"keep","description":"compress ralph-persist.ts — extract helpers, shorten vars","timestamp":1775210616,"segment":0}
+{"run":8,"commit":"0405ab8","metric":1237,"metrics":{"skill_lines":36,"cancel_bytes":431,"hook_bytes":2157,"hook_lines":52,"total_bytes":3825},"status":"keep","description":"replace JSON code block with inline field description","timestamp":1775210641,"segment":0}
+{"run":9,"commit":"465de49","metric":1197,"metrics":{"skill_lines":34,"cancel_bytes":431,"hook_bytes":2157,"hook_lines":52,"total_bytes":3785},"status":"keep","description":"extract $S path var, merge verification+done sections","timestamp":1775210664,"segment":0}
+{"run":10,"commit":"570f903","metric":1193,"metrics":{"skill_lines":36,"cancel_bytes":431,"hook_bytes":2157,"hook_lines":52,"total_bytes":3781},"status":"keep","description":"consolidate flags into single line at bottom","timestamp":1775210689,"segment":0}
+{"run":11,"commit":"fe1ab49","metric":1193,"metrics":{"skill_lines":36,"cancel_bytes":431,"hook_bytes":1962,"hook_lines":48,"total_bytes":3586},"status":"keep","description":"shorten block message, compress variable names","timestamp":1775210722,"segment":0}
+{"run":13,"commit":"823b62e","metric":1249,"metrics":{"skill_lines":32,"cancel_bytes":431,"hook_bytes":1962,"hook_lines":48,"total_bytes":3642},"status":"keep","description":"clarify SKILL.md based on agent test — progress.txt, deslop, review criteria (+123 bytes for clarity)","timestamp":1775211110,"segment":0}
+{"run":14,"commit":"97d4d0b","metric":1272,"metrics":{"skill_lines":31,"cancel_bytes":431,"hook_bytes":1962,"hook_lines":48,"total_bytes":3665},"status":"keep","description":"clarify progress.txt timing, remove redundant parse step","timestamp":1775211256,"segment":0}
+{"run":15,"commit":"59d1f66","metric":1359,"metrics":{"skill_lines":31,"cancel_bytes":431,"hook_bytes":1962,"hook_lines":48,"total_bytes":3752},"status":"keep","description":"define flag behaviors — --no-prd creates minimal prd.json (agent test fix)","timestamp":1775211369,"segment":0}
+{"run":16,"commit":"4ea8184","metric":1396,"metrics":{"skill_lines":31,"cancel_bytes":431,"hook_bytes":1962,"hook_lines":48,"total_bytes":3789},"status":"keep","description":"clarify TDD with existing tests, fix --no-prd wording (agent test fix)","timestamp":1775211475,"segment":0}
+{"run":17,"commit":"0201a7a","metric":1396,"metrics":{"skill_lines":31,"cancel_bytes":525,"hook_bytes":1962,"hook_lines":48,"total_bytes":3883},"status":"keep","description":"add CWD context and hook explanation to ralph-cancel (agent test fix)","timestamp":1775211579,"segment":0}
+{"run":18,"commit":"e6ea5dd","metric":1438,"metrics":{"skill_lines":32,"cancel_bytes":525,"hook_bytes":1962,"hook_lines":48,"total_bytes":3925},"status":"keep","description":"add INSIGHT format to progress.txt, clarify per-story update (agent test)","timestamp":1775211830,"segment":0}
+{"run":19,"commit":"fb6ca04","metric":1438,"metrics":{"skill_lines":32,"cancel_bytes":525,"hook_bytes":2286,"hook_lines":55,"total_bytes":4249},"status":"keep","description":"add story progress to block message (N/M stories done)","timestamp":1775211874,"segment":0}
+{"run":20,"commit":"60ca33c","metric":1098,"metrics":{"skill_lines":29,"cancel_bytes":525,"hook_bytes":2286,"hook_lines":55,"total_bytes":3909},"status":"keep","description":"simplify for universal use — remove $S, add one-at-a-time + slop def. Agent: 7/10","timestamp":1775212030,"segment":0}
+{"run":21,"commit":"52ff4aa","metric":1098,"metrics":{"skill_lines":29,"cancel_bytes":525,"hook_bytes":2286,"hook_lines":55,"total_bytes":3909},"status":"keep","description":"e2e test: /ralph actual invocation — 3 stories, 1 iteration, all pass","timestamp":1775212340,"segment":0}
+{"run":22,"commit":"52ff4aa","metric":1098,"metrics":{"skill_lines":29,"cancel_bytes":525,"hook_bytes":2286,"hook_lines":55,"total_bytes":3909},"status":"keep","description":"e2e test: /ralph --no-prd — single story auto-generated, no confusion, all pass","timestamp":1775212411,"segment":0}
+{"run":23,"commit":"52ff4aa","metric":1098,"metrics":{"skill_lines":29,"cancel_bytes":525,"hook_bytes":2286,"hook_lines":55,"total_bytes":3909},"status":"keep","description":"e2e test: /ralph-cancel — active loop cancelled cleanly, no issues","timestamp":1775212452,"segment":0}
+{"run":24,"commit":"2af754f","metric":1098,"metrics":{"skill_lines":29,"cancel_bytes":525,"hook_bytes":2487,"hook_lines":60,"total_bytes":4110},"status":"keep","description":"include last progress.txt failure in block message","timestamp":1775212490,"segment":0}
+{"run":25,"commit":"72eb631","metric":1098,"metrics":{"skill_lines":29,"cancel_bytes":525,"hook_bytes":2390,"hook_lines":58,"total_bytes":4013},"status":"keep","description":"use Bun.stdin.text() for simpler stdin reading","timestamp":1775212517,"segment":0}

.autoresearch/autoresearch.md

@@ -1,47 +1,36 @@
-# Autoresearch: create-pr token efficiency
+# Autoresearch: Ralph Plugin Optimization
 
 ## Objective
-Optimize the `plugins/me/skills/create-pr/` skill for token efficiency and correctness. SKILL.md is loaded into LLM context when invoked — fewer bytes = less cost. Scripts run at execution time and don't affect token cost, but must be correct.
+Optimize the `plugins/ralph/` plugin for simplicity and token efficiency. SKILL.md files are loaded into LLM context when invoked — fewer bytes = less cost. The hook (ralph-persist.ts) runs at OS level but should also be minimal and clean.
 
 ## Metrics
-- **Primary**: skill_bytes (bytes, lower is better) — SKILL.md byte count
-- **Secondary**: skill_lines, skill_words, script_bytes
+- **Primary**: skill_bytes (bytes, lower is better) — ralph/SKILL.md byte count
+- **Secondary**: skill_lines, cancel_bytes, hook_bytes, hook_lines, total_bytes
 
 ## How to Run
-`./.autoresearch/run.sh` — outputs `METRIC name=number` lines.
+`./.autoresearch/run.sh` — outputs `METRIC name=number` lines. Validates frontmatter, hooks.json, TS compilation, and BATS tests.
 
 ## Files in Scope
 | File | Purpose |
 |------|---------|
-| `plugins/me/skills/create-pr/SKILL.md` | Main skill definition (loaded into LLM context) |
-| `plugins/me/skills/create-pr/scripts/preflight-check.sh` | Pre-push checks + auto-sync |
-| `plugins/me/skills/create-pr/scripts/wait-for-merge.sh` | Wait for CI + merge |
+| `plugins/ralph/skills/ralph/SKILL.md` | Main skill (LLM context — primary target) |
+| `plugins/ralph/skills/ralph-cancel/SKILL.md` | Cancel skill (LLM context) |
+| `plugins/ralph/hooks/ralph-persist.ts` | Stop hook engine (Bun runtime) |
+| `plugins/ralph/hooks/hooks.json` | Hook registration config |
 
 ## Off Limits
-- Do not break the PR workflow
-- Exit codes must be preserved
+- Do not break the persistence loop workflow (activate → iterate → complete)
+- Cancel signal mechanism must work
+- Session isolation must be preserved
+- Stale state recovery must work
+- Always exit 0 (never crash Claude)
+- plugin.json metadata
 
 ## Constraints
-- Scripts must pass shellcheck
+- Tests must pass (ralph_persist.bats + ralph_hooks_json.bats)
 - SKILL.md must have valid frontmatter
-- Tests must pass (63/63)
+- hooks.json must be valid JSON
+- TypeScript must compile with bun
 
 ## What's Been Tried
-### Structural changes (big wins)
-- Removed unused verify-pr-status.sh (-1302 bytes)
-- Merged sync-with-base.sh into preflight-check.sh (-515 bytes)
-- Inlined lib.sh into preflight-check.sh (-461 bytes)
-
-### SKILL.md compression (medium wins)
-- Removed Overview, When to Use, Stop Conditions sections
-- Extracted S= path variable for script paths
-- Removed bold markdown markers, flattened sections
-
-### Test-driven fixes (increased bytes for correctness)
-- "scripts MUST be run" directive (+129 bytes) — agents were skipping scripts
-- auto-merge re-enable after CI fix (+60 bytes) — tested on PR #604
-- push -u in preflight — new branches had no upstream
-
-### Dead ends
-- Merging gh pr create + merge into one line — bytes increased
-- Further compression below ~700 bytes — losing essential information
+(Starting fresh — no experiments yet)

.autoresearch/dashboard.md

@@ -1,31 +1,29 @@
-# Autoresearch Dashboard: create-pr-optimize
+# Autoresearch Dashboard: ralph-optimize
 
-## Segment 1: skill_bytes (SKILL.md only)
-**Runs:** 14 | **Kept:** 12 | **Discarded:** 1 | **Tests:** 1
-**Baseline:** 1081 bytes (#10)
-**Best pure:** 605 bytes (#15, -44.0%)
-**Current:** 794 bytes (#19, -26.5%) — includes test-driven fixes
+**Runs:** 20 | **Kept:** 17 | **Discarded:** 0 | **Crashed:** 0
+**Baseline:** skill=2914, total=7357 bytes
+**Final:** skill=1098 (-62.3%), total=3909 (-46.9%)
+**Agent clarity:** 7/10
 
-| # | commit | skill_bytes | status | description |
-|---|--------|-------------|--------|-------------|
-| 10 | 1b650ac | 1081 | keep | baseline |
-| 11 | 6ba0c3d | 802 (-25.8%) | keep | remove redundant sections |
-| 12 | ec416bc | 732 (-32.3%) | keep | extract S= path variable |
-| 13 | 9bb6f1e | 675 (-37.6%) | keep | merge comments, remove bold |
-| 14 | 563874d | 635 (-41.3%) | keep | micro-compress wording |
-| 15 | 059de59 | 605 (-44.0%) | keep | remove template path |
-| 16 | 059de59 | 608 | discard | merge create+merge lines |
-| 17 | 96b1a8f | 665 | keep | add auto-merge re-enable (test fix) |
-| 18 | - | - | test | edge: main branch — agent skipped scripts |
-| 19 | b2e1f87 | 794 | keep | "scripts MUST be run" directive |
-| 20 | - | - | test | edge: nothing-to-commit — agent handled correctly |
-| 22 | - | - | test | must-run directive confirmed working |
-| 23 | dece665 | 794 | keep | fix broken tests — 63/63 pass |
+| # | skill | cancel | hook | total | description |
+|---|-------|--------|------|-------|-------------|
+| 1 | 2914 | 696 | 3747 | 7357 | baseline |
+| 2 | 1710 | 696 | 3747 | 6153 | compress SKILL.md |
+| 3 | 1364 | 696 | 3747 | 5807 | further compress |
+| 5 | 1364 | 431 | 2725 | 4520 | simplify hook |
+| 7 | 1260 | 431 | 2157 | 3848 | compress hook |
+| 11 | 1193 | 431 | 1962 | 3586 | best pure compression |
+| 15 | 1359 | 431 | 1962 | 3752 | +clarity (agent fixes) |
+| 19 | 1438 | 525 | 2286 | 4249 | +story progress in hook |
+| 20 | 1098 | 525 | 2286 | 3909 | final: simplified for universal use |
 
-## Subagent Test Results
-| PR | Scenario | Result | Finding |
-|----|----------|--------|---------|
-| #601-602 | basic flow (main SKILL) | pass | - |
-| #604 | optimized SKILL | pass | auto-merge disabled after push, push -u needed |
-| #605 | main branch edge | pass | agent skipped scripts (fixed with MUST directive) |
-| #606 | MUST directive test | pass | scripts executed correctly, CI failed on stale tests |
+## Agent Tests (7 total, all pass)
+| Scenario | Clarity Finding |
+|----------|----------------|
+| Simple task | progress.txt init, deslop vague |
+| Multi-story | one-at-a-time unclear |
+| --no-prd | "skip PRD" contradictory |
+| Edge cases | retry flow works |
+| ralph-cancel | CWD + hook explanation needed |
+| Calculator | 7/10 — clean |
+| Calculator --no-prd | 7/10 — auto-generate rule wanted |