ralphctl 0.25.0 → 0.27.0

package/dist/skills/ralphctl-test-driven-development/SKILL.md

@@ -1,13 +1,14 @@
 ---
 name: ralphctl-test-driven-development
-description: Execute-phase skill — write the failing test before the code that makes it pass; for bug fixes, this is the reproduction test itself. Use for any logic change, bug fix, or behavioural modification; for the full root-cause triage pipeline around an unexpected failure, see ralphctl-debugging-and-error-recovery.
+description: Execute-phase skill — drive changes with the red-green-refactor loop; write the failing test before the code that makes it pass; for bug fixes, this is the reproduction test itself. Use for any logic change, bug fix, or behavioural modification; for the full root-cause triage pipeline around an unexpected failure, see ralphctl-debugging-and-error-recovery.
 license: MIT
 ---
 
 # Test-Driven Development
 
 > Concept from [Addy Osmani — "Test-Driven Development"](https://github.com/addyosmani/agent-skills)
-> (agent-skills, MIT). Adapted for ralphctl's execute phase.
+> (agent-skills, MIT), with the tautological-assertion anti-pattern drawn from
+> [mattpocock/skills](https://github.com/mattpocock/skills) (MIT). Adapted for ralphctl's execute phase.
 
 Write a failing test before writing the code that makes it pass. For bug fixes, reproduce the bug with a
 test before attempting a fix. Tests are proof — "seems right" is not done. A codebase with good tests is an
@@ -23,6 +24,28 @@ AI agent's superpower; a codebase without tests is a liability.
 **When NOT to use:** Pure configuration changes, documentation updates, or static content changes with no
 behavioural impact.
 
+## Discover the Stack First
+
+The TDD cycle is universal; the commands are not. Before writing the first test, find out how _this_
+repository tests, and use its commands for every RED, GREEN, and narrow-check step:
+
+- **Commands the harness hands you** — the prompt's project-tooling or check-gate section, when present, is
+  the authoritative source; prefer it over anything you infer.
+- **Language and build system** — the dependency manifest or build file (`package.json`, `pom.xml` /
+  `build.gradle`, `pyproject.toml`, `go.mod`, `Cargo.toml`, `Gemfile`, a `Makefile`).
+- **Checked-in wrappers** — prefer a repo wrapper or script (`./gradlew`, `./mvnw`, a `Makefile` target) over
+  a globally installed tool.
+- **Test framework and configuration** — and how it runs a single focused test versus the full suite.
+- **Existing conventions** — where tests live, how files are named, what patterns neighbouring tests follow.
+- **Documented commands** — the project's AI context file, README, CONTRIBUTING, and CI workflows show the
+  commands that actually gate merges.
+
+Run the repository's focused-test command during the loop. Never assume a default test command from another
+ecosystem — a Gradle, Cargo, or pytest project has its own equivalent.
+
+The examples below use TypeScript for illustration; the workflow is identical in any language once you have
+discovered the project's own tooling.
+
 ## The TDD Cycle
 
 ```
@@ -298,6 +321,7 @@ describe('TaskService', () => {
 | Anti-Pattern                          | Problem                                                     | Fix                                                                                                                         |
 | ------------------------------------- | ----------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------- |
 | Testing implementation details        | Tests break when refactoring even if behaviour is unchanged | Test inputs and outputs, not internal structure                                                                             |
+| Tautological assertions               | Recomputes the expected value the way the code does         | Expected values come from an independent source — a literal, a worked example, the spec — never the code's own formula      |
 | Flaky tests (timing, order-dependent) | Erode trust in the test suite                               | Use deterministic assertions, isolate test state                                                                            |
 | Testing framework code                | Wastes time testing third-party behaviour                   | Only test YOUR code                                                                                                         |
 | Snapshot abuse                        | Large snapshots nobody reviews, break on any change         | Use snapshots sparingly and review every change                                                                             |
@@ -319,7 +343,10 @@ describe('TaskService', () => {
 ## Red Flags
 
 - Writing code without any corresponding tests
+- Reaching for a default test command without checking what this repository actually uses
 - Tests that pass on the first run (they may not be testing what you think)
+- An expected value computed with the code's own formula (`add(a, b)` checked against `a + b`) — it passes by
+  construction
 - "All tests pass" but no tests were actually run
 - Bug fixes without a reproduction test
 - Tests that verify framework behaviour instead of application behaviour

package/dist/skills/ralphctl-writing-for-agents/SKILL.md

@@ -0,0 +1,113 @@
+---
+name: ralphctl-writing-for-agents
+description: How to write documents an AI agent consumes — project context files (AGENTS.md, CLAUDE.md, and similar), skills, task specs, and requirements. Covers trigger-worded pointers, the cost of always-loaded context, steps that end on checkable completion criteria, leading words, positive phrasing over prohibitions, and pruning restatements, no-ops, and stale lines. Use when drafting or editing any of those documents.
+license: MIT
+---
+
+# Writing for Agents
+
+> Adapted from [mattpocock/skills — "Writing for Agents"](https://github.com/mattpocock/skills) (MIT).
+> Adapted for ralphctl's harness contract.
+
+A reference for writing any document an agent consumes: a project context file, a skill, a task spec, a
+set of requirements. The packaging differs; the writing does not. The same levers make each one
+predictable — the agent takes the same _process_ every run, rather than producing the same output.
+
+The session's prompt still owns the output: its length targets, required sections, and what-to-leave-out
+rules win over anything here.
+
+## When this applies
+
+- **Readiness** — the context-file proposal. Every line is loaded into every future session, so each one
+  must change behaviour versus the default. Point at what the environment already states instead of
+  restating it, but keep every exact command the prompt asks for (build and test lines, setup and verify
+  skill bodies).
+- **Refine** — the requirements are read by the planner and every implementing session. Give each
+  criterion a checkable completion condition, keep each meaning in one place, and phrase the target
+  behaviour positively.
+
+## Context pointers
+
+A **context pointer** is a line in context that names material outside it and encodes when to reach it —
+a skill's description, or a context-file line naming a doc. The pointer's _wording_, not its target,
+decides when and how reliably the agent reaches the material. A must-have target behind a weakly worded
+pointer is a variance bug: sharpen the wording first; inline the material only if that fails.
+
+A pointer states what the material is and lists the **branches** — distinct cases — that should trigger
+it. Every word of an always-loaded pointer costs on every turn, so prune it hardest:
+
+- **Front-load the leading word**; the start of the pointer does the triggering.
+- **One trigger per branch.** Synonyms naming one branch are one branch written twice.
+- **Cut identity the body already carries.**
+
+## The two loads
+
+- **Context load** — always-loaded material (a context-file line, a skill description) spends tokens and
+  attention every turn, whether or not it fires.
+- **Cognitive load** — the human has to know which documents exist and when each matters. Spend it where
+  human judgement matters; remove it where it does not.
+
+Material behind a pointer escapes context load at the price of the pointer's own line.
+
+## Information hierarchy
+
+A document mixes **steps** (ordered actions) and **reference** (definitions, rules, facts consulted on
+demand). Place each piece on a ladder ranked by how immediately the agent needs it:
+
+1. **In-file steps** — what the agent does, in order.
+2. **In-file reference** — consulted on demand; a flat set of peer rules is fine.
+3. **Disclosed reference** — material in another file, reached through a pointer only when needed.
+
+Inline what every branch needs; disclose what only some branches reach. Keep a concept's definition,
+rules, and caveats together under one heading rather than scattered. The failure mode is **sprawl** — a
+document so long that attention thins across it even when every line is live. In a session that writes
+only its proposal, disclose by pointing at a file that already exists.
+
+## Steps and completion criteria
+
+Every step ends on a **completion criterion** — the condition that tells the agent it is done.
+
+- **Clarity** — can the agent tell done from not done? A vague bound ("once understanding is reached")
+  invites premature completion, with attention slipping to the steps still ahead. Sharpen the bound
+  first. Hiding later steps only helps across a real context boundary (a hand-off to a separate session
+  or task).
+- **Demand** — how much the criterion requires. "Every modified model accounted for" forces thorough work
+  where "produce a change list" does not. Demand binds flat reference too: "every rule applied".
+
+The strongest criteria are both checkable and exhaustive.
+
+## Leading words
+
+A **leading word** is a compact concept the model already knows — _tight_ (a tight feedback loop),
+_red_ (a test that fails on the bug), _tracer bullet_. Repeated as a token, it anchors a whole region of
+behaviour in few words by recruiting priors the model already holds. Hunt for passages that spell out a
+triad or a sentence where one such word would do.
+
+**Prohibitions backfire.** Naming the forbidden behaviour puts it in context and makes it more
+available. State the target behaviour ("write one-line comments"). Keep a prohibition only as a hard
+guardrail you cannot phrase positively, and pair it with the positive target.
+
+## Pruning
+
+- **One meaning, one place.** Duplication costs maintenance and tokens and inflates a meaning's
+  prominence. (A leading word repeats a token on purpose, never the meaning.)
+- **The environment is a source of truth.** Config files, the directory layout, `--help` output, and
+  what a manifest script does already state themselves; a document that restates them is a cache that
+  goes stale. Which command to run is different: where the document exists to tell the agent what to run,
+  or the output contract asks for commands, give the exact runnable command, checked against the manifest.
+  Beyond that, write down what the agent cannot find by looking — the unwritten convention, the reason
+  behind a choice, the gotcha no config admits.
+- **Relevance.** A line that never bears on the task, or describes behaviour that has since changed, is
+  sediment. Remove it.
+- **No-ops.** An instruction the model already follows by default says nothing. Delete the whole
+  sentence. A word too weak to beat the default (_be thorough_) needs a stronger word, not more words.
+
+## Self-check
+
+- [ ] Every always-loaded line changes behaviour versus the default.
+- [ ] Each pointer front-loads its trigger and lists one trigger per branch.
+- [ ] Every step ends on a checkable completion criterion.
+- [ ] Nothing restates what the environment already states, and every command the contract asks for is
+      exact and runnable.
+- [ ] Target behaviours are phrased positively.
+- [ ] The prompt's own length and section rules are met.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "ralphctl",
-  "version": "0.25.0",
+  "version": "0.27.0",
   "description": "A ralph harness for long-running AI coding tasks — a generator-evaluator loop that drives Claude Code, GitHub Copilot CLI, OpenAI Codex CLI, OpenCode or Grok Build CLI across one or more repositories",
   "homepage": "https://github.com/lukas-grigis/ralphctl",
   "type": "module",
@@ -49,19 +49,19 @@
   "dependencies": {
     "commander": "^15.0.0",
     "cross-spawn": "^7.0.6",
-    "ink": "^7.1.1",
+    "ink": "^8.0.0",
     "proper-lockfile": "^4.1.2",
     "react": "^19.3.0",
     "typescript-result": "^3.5.2",
-    "zod": "^4.6.0"
+    "zod": "^4.6.7"
   },
   "devDependencies": {
     "@eslint/js": "^10.0.1",
     "@types/cross-spawn": "^6.0.6",
-    "@types/node": "^26.6.2",
+    "@types/node": "^26.6.5",
     "@types/proper-lockfile": "^4.1.4",
     "@types/react": "^19.3.0",
-    "@vitest/coverage-v8": "^5.0.0",
+    "@vitest/coverage-v8": "^5.0.4",
     "eslint": "^10.11.0",
     "eslint-plugin-react-hooks": "^7.1.1",
     "eslint-plugin-sonarjs": "^4.2.0",
@@ -71,13 +71,13 @@
     "jiti": "^2.7.0",
     "knip": "^6.37.0",
     "lint-staged": "^17.5.0",
-    "prettier": "^3.9.8",
-    "tsup": "^8.5.1",
+    "prettier": "^3.9.10",
+    "tsup": "^9.0.0",
     "tsx": "^4.23.15",
     "typescript": "^6.0.3",
-    "typescript-eslint": "^8.70.1",
+    "typescript-eslint": "^8.71.2",
     "vite": "^8.2.2",
-    "vitest": "^5.0.0"
+    "vitest": "^5.0.4"
   },
   "lint-staged": {
     "*.{ts,tsx}": [
@@ -90,6 +90,7 @@
     "build": "tsup && tsx scripts/build-assets.ts",
     "dev": "NODE_ENV=production NODE_OPTIONS=--max-old-space-size=8192 tsx src/index.ts",
     "mock": "tsx scripts/seed-mock.ts",
+    "demo:record": "NODE_ENV=production tsx scripts/record-demo.ts",
     "dev:heap-snapshot": "mkdir -p .diagnostics && NODE_OPTIONS='--max-old-space-size=8192 --heapsnapshot-near-heap-limit=2 --diagnostic-dir=.diagnostics' tsx src/index.ts",
     "start": "NODE_ENV=production NODE_OPTIONS=--max-old-space-size=8192 tsx src/index.ts",
     "typecheck": "tsc",
@@ -100,7 +101,6 @@
     "test:watch": "vitest",
     "coverage": "vitest run --coverage",
     "verify:coverage": "pnpm coverage",
-    "coverage:unused": "tsx scripts/find-unused.ts",
     "deadcode": "knip",
     "skills:update": "tsx scripts/sync-skills.ts",
     "eval": "tsx scripts/eval/main.ts",