ralphctl 0.26.0 → 0.28.0

package/README.md

@@ -13,9 +13,12 @@
 [![Built with Donuts](https://img.shields.io/badge/%F0%9F%8D%A9-Built_with_Donuts-ff6f00?style=flat)](https://github.com/lukas-grigis/ralphctl)
 
 <p align="center">
-  <img src="./.github/assets/home.png" alt="ralphctl home screen — Ralph donut banner with 'The pointy kitty took it!' tagline, WORK / OBSERVE / SYSTEM menus with keybindings, bottom footer" width="900" />
+  <img src="./.github/assets/demo.gif" alt="ralphctl running the Implement flow in its terminal UI: the generator edits hello.py and reports the task done, the evaluator fails the correctness dimension with a critique (hello.py must print exactly &quot;Hello, world!&quot;), the generator retries with the critique applied, the evaluator passes, and the task commits" width="900" />
 </p>
 
+<p align="center"><sub>One task through the generator → evaluator loop: round 1 fails review, round 2 applies the critique and
+passes. Replayed with <code>ralphctl demo --script</code> — no AI CLI, no tokens.</sub></p>
+
 # ralphctl
 
 **A ralph harness for long-running AI coding tasks — a hardened ralph loop that drives your coding agent of choice
@@ -74,6 +77,9 @@ project (three sprints, one per pre-flow state) and launches straight into it
 ralphctl demo
 ```
 
+`ralphctl demo --script` replays the run in the recording above — a canned two-round session through the real
+Implement chain, git commit and verify gate included — so you can watch the loop without spending a token.
+
 Otherwise, install one of the supported CLIs and authenticate it:
 
 | CLI                                                                                | Install                              | Auth                       |
@@ -81,7 +87,7 @@ Otherwise, install one of the supported CLIs and authenticate it:
 | [Claude Code](https://docs.anthropic.com/en/docs/claude-code)                      | `npm i -g @anthropic-ai/claude-code` | Anthropic account          |
 | [GitHub Copilot CLI](https://docs.github.com/en/copilot/github-copilot-in-the-cli) | `npm i -g @github/copilot`           | GitHub Copilot seat        |
 | [OpenAI Codex CLI](https://github.com/openai/codex)                                | `npm i -g @openai/codex`             | ChatGPT / OpenAI           |
-| [OpenCode](https://opencode.ai/)                                                   | `npm i -g opencode-ai`               | your own key, or none      |
+| [OpenCode](https://opencode.ai/)                                                   | `npm i -g opencode-ai@1`             | your own key, or none      |
 | [Grok Build CLI](https://docs.x.ai/build/overview)                                 | `npm i -g @xai-official/grok`        | xAI account (`grok login`) |
 
 Then confirm ralphctl can see it:
@@ -254,7 +260,7 @@ per-row settings.
 | **Claude Code** (`claude-code`)           | `claude`   | `npm i -g @anthropic-ai/claude-code` | Anthropic account          | `CLAUDE.md`                       |
 | **GitHub Copilot CLI** (`github-copilot`) | `copilot`  | `npm i -g @github/copilot`           | GitHub Copilot seat        | `.github/copilot-instructions.md` |
 | **OpenAI Codex CLI** (`openai-codex`)     | `codex`    | `npm i -g @openai/codex`             | ChatGPT / OpenAI           | `AGENTS.md`                       |
-| **OpenCode** (`opencode`)                 | `opencode` | `npm i -g opencode-ai`               | your own key, or none      | `AGENTS.md`                       |
+| **OpenCode** (`opencode`)                 | `opencode` | `npm i -g opencode-ai@1`             | your own key, or none      | `AGENTS.md`                       |
 | **Grok Build CLI** (`xai-grok`)           | `grok`     | `npm i -g @xai-official/grok`        | xAI account (`grok login`) | `AGENTS.md`                       |
 
 Codex, OpenCode, and Grok share one repo-root `AGENTS.md`. Readiness for more than one of them writes
@@ -362,7 +368,7 @@ ralphctl settings apply-preset grok-fast
 
 # Frontier — the vendor's top model on plan/implement at max effort; light flows stay below max.
 # Claude/Codex step up to Fable 5.1 / gpt-6-astra (Fable 5.1 needs a non-ZDR org);
-# Copilot/Grok keep their flagship (Opus 4.8 / grok-4.7).
+# Copilot/Grok keep their flagship (Opus 5.5 / grok-4.7).
 ralphctl settings apply-preset mixed-frontier
 ralphctl settings apply-preset claude-frontier
 ralphctl settings apply-preset copilot-frontier
@@ -544,6 +550,7 @@ Run `ralphctl <command> --help` for flag-level detail.
 | [Architecture](./ARCHITECTURE.md)                | Data models, harness loop, file storage, error reference |
 | [Providers](./docs/providers.md)                 | Per-backend setup, permission mapping, model ids, limits |
 | [Adding a provider](./docs/adding-a-provider.md) | Extension guide: wire a new AI CLI into the harness      |
+| [Custom skills](./docs/custom-skills.md)         | Plug in your own skills                                  |
 | [Requirements](./.claude/docs/REQUIREMENTS.md)   | Acceptance criteria and feature checklist                |
 | [Contributing](./CONTRIBUTING.md)                | Dev setup, code style, PR process                        |
 | [Migration](./MIGRATION.md)                      | Per-version upgrade context for big version jumps        |

package/THIRD-PARTY-NOTICES.md

@@ -6,10 +6,21 @@ verbatim upstream snapshots used for drift review live under `scripts/vendor/ski
 upstream's license and copyright notice is reproduced in full below, as the MIT license requires.
 
 - `ralphctl-debugging-and-error-recovery`, `ralphctl-code-review-and-quality`,
-  `ralphctl-test-driven-development`, `ralphctl-idea-refinement` — from
+  `ralphctl-test-driven-development`, `ralphctl-idea-refinement`, `ralphctl-security-and-hardening`,
+  `ralphctl-spec-driven-development`, `ralphctl-api-and-interface-design`,
+  `ralphctl-performance-optimization`, `ralphctl-frontend-ui-engineering`,
+  `ralphctl-deprecation-and-migration`, `ralphctl-code-simplification`,
+  `ralphctl-source-driven-development`, `ralphctl-observability-and-instrumentation`, and the
+  risk-first slicing in `ralphctl-iterative-review` — from
   [addyosmani/agent-skills](https://github.com/addyosmani/agent-skills)
-- `ralphctl-ponytail` — from [DietrichGebert/ponytail](https://github.com/DietrichGebert/ponytail)
+- `ralphctl-ponytail`, and the concrete-case and expected-load review rules in
+  `ralphctl-code-review-and-quality` — from [DietrichGebert/ponytail](https://github.com/DietrichGebert/ponytail)
 - `ralphctl-domain-driven-design` — from [wondelai/skills](https://github.com/wondelai/skills)
+- `ralphctl-codebase-design`, `ralphctl-writing-for-agents`, and parts of
+  `ralphctl-debugging-and-error-recovery`, `ralphctl-test-driven-development`, and
+  `ralphctl-code-review-and-quality` — from [mattpocock/skills](https://github.com/mattpocock/skills)
+- `ralphctl-humanizer` — concept from [blader/humanizer](https://github.com/blader/humanizer); its pattern
+  catalogue is written fresh in ralphctl's own words
 
 ---
 
@@ -90,3 +101,55 @@ LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
 OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
 SOFTWARE.
 ```
+
+## mattpocock/skills
+
+```
+MIT License
+
+Copyright (c) 2026 Matt Pocock
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.
+```
+
+## blader/humanizer
+
+```
+MIT License
+
+Copyright (c) 2025 Siqi Chen
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.
+```

package/dist/agent-definitions/ralphctl-generator.md

@@ -9,8 +9,9 @@ already in — not to redesign it, and not to stop short of a verified result.
 ## Before writing code
 
 1. **Read the actual requirement** — the ticket, the failing test, the described behavior. When
-   it's ambiguous, pick the narrowest interpretation that still satisfies it rather than guessing
-   at a larger scope.
+   it's ambiguous, implement the reading its wording and the surrounding code most directly support
+   — one that still satisfies it — and record that assumption (as a decision, when the output
+   contract offers one) rather than guessing at a larger scope.
 2. **Find the nearest existing pattern** — the way this codebase already solves a similar problem
    (naming, error handling, test structure, layering) is the template to follow. Introducing a new
    pattern for something that already has one creates drift a future reader has to reconcile.