ralphctl 0.14.1 → 0.15.0

package/README.md

@@ -5,9 +5,9 @@
 [![TypeScript](https://img.shields.io/badge/TypeScript-6.0-3178c6?style=flat&logo=typescript&logoColor=white)](https://www.typescriptlang.org/)
 [![Node.js](https://img.shields.io/badge/node-%E2%89%A5_24-5fa04e?style=flat&logo=nodedotjs&logoColor=white)](https://nodejs.org/)
 [![PRs Welcome](https://img.shields.io/badge/PRs-welcome-brightgreen?style=flat&logo=git&logoColor=white)](./CONTRIBUTING.md)
-[![Claude Code](https://img.shields.io/badge/Claude_Code-stable-191919?style=flat&logo=anthropic&logoColor=white)](https://docs.anthropic.com/en/docs/claude-code)
-[![OpenAI Codex](https://img.shields.io/badge/OpenAI_Codex-preview-412991?style=flat&logo=openai&logoColor=white)](https://github.com/openai/codex)
-[![GitHub Copilot](https://img.shields.io/badge/GitHub_Copilot-preview-000?style=flat&logo=githubcopilot&logoColor=white)](https://docs.github.com/en/copilot/github-copilot-in-the-cli)
+[![Claude Code](https://img.shields.io/badge/Claude_Code-supported-191919?style=flat&logo=anthropic&logoColor=white)](https://docs.anthropic.com/en/docs/claude-code)
+[![GitHub Copilot CLI](https://img.shields.io/badge/GitHub_Copilot_CLI-supported-000?style=flat&logo=githubcopilot&logoColor=white)](https://docs.github.com/en/copilot/github-copilot-in-the-cli)
+[![OpenAI Codex CLI](https://img.shields.io/badge/OpenAI_Codex_CLI-supported-412991?style=flat&logo=openai&logoColor=white)](https://github.com/openai/codex)
 [![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">
@@ -16,17 +16,18 @@
 
 # ralphctl
 
-**A ralph harness for long-running AI coding tasks — a hardened ralph loop that
-orchestrates [Claude Code](https://docs.anthropic.com/en/docs/claude-code) across repositories,
-with [GitHub Copilot](https://docs.github.com/en/copilot/github-copilot-in-the-cli) and
-[OpenAI Codex](https://github.com/openai/codex) available in preview.**
+**A ralph harness for long-running AI coding tasks — a hardened ralph loop that drives your coding agent of choice
+([Claude Code](https://docs.anthropic.com/en/docs/claude-code),
+[GitHub Copilot CLI](https://docs.github.com/en/copilot/github-copilot-in-the-cli), or
+[OpenAI Codex CLI](https://github.com/openai/codex)) across one or more repositories.**
 
 > _"I'm helping!"_ — Ralph Wiggum
 
 > [!NOTE]
-> **Active development.** New features and polish ship regularly. The latest release expands the preset
-> matrix to 20 presets across five families (`standard`, `economic`, `strong-gate`, `fast`, `frontier`),
-> each in `mixed` / `claude-only` / `copilot-only` / `codex-only` variants.
+> **Active development.** New features and polish ship regularly. All three providers — Claude Code,
+> GitHub Copilot CLI, and OpenAI Codex CLI — are supported; pick one per flow or mix them, in one command,
+> from a preset matrix of 20 presets across five families (`standard`, `economic`, `strong-gate`, `fast`,
+> `frontier`), each in `mixed` / `claude-only` / `copilot-only` / `codex-only` variants.
 > Upgrades are best-effort: install the latest version, redo your config, proceed.
 > See [Upgrading](#upgrading) and [CHANGELOG](./CHANGELOG.md).
 
@@ -36,18 +37,20 @@ with [GitHub Copilot](https://docs.github.com/en/copilot/github-copilot-in-the-c
 
 The "Ralph" technique comes from Geoffrey Huntley's [Ralph Wiggum as a software engineer](https://ghuntley.com/ralph/):
 point a coding agent at a task and run it in a loop until the work is done. The bare version
-(`while :; do cat PROMPT.md | claude-code; done`) loops blindly — it re-runs the same prompt and hopes each pass lands.
+(`while :; do cat PROMPT.md | claude; done`) loops blindly — it re-runs the same prompt and hopes each pass lands.
 ralphctl is a ralph harness around that idea: instead of blind repetition it runs a generator-evaluator loop, where one
 pass writes the change and a second independent pass reviews it against the task spec before the loop advances. Same
-loop, with a verification gate on every step.
+loop, with a verification gate on every step. For the wider picture — what an agent harness is, and how the
+plan → generate → evaluate → verify loop turns one-shot prompting into a repeatable workflow — see
+[AI Agent Harnesses: A Field Guide](https://lukasgrigis.dev/blog/guides/agent-harnesses/).
 
 ---
 
 ## What is ralphctl?
 
 AI coding agents are powerful but lose context on long tasks, need babysitting when things break, and have no way to
-coordinate changes across multiple repositories. ralphctl wraps your chosen AI CLI — Claude Code, with GitHub Copilot
-and OpenAI Codex in preview — in a
+coordinate changes across multiple repositories. ralphctl wraps your chosen AI CLI — Claude Code, GitHub Copilot CLI,
+or OpenAI Codex CLI — in a
 structured harness that decomposes your work into dependency-ordered tasks, drives each one through
 a [generator-evaluator loop](https://www.anthropic.com/engineering/harness-design-long-running-apps) that catches issues
 before moving on, and persists context across sessions so nothing gets lost.
@@ -64,8 +67,9 @@ npm install -g ralphctl
 
 > Needs [Node.js](https://nodejs.org/) ≥ 24 — `mise use node@24` or `nvm install 24`.
 
-Install [Claude Code](https://docs.anthropic.com/en/docs/claude-code) (or a preview provider — see below) and
-authenticate it, then confirm ralphctl can see it:
+Install one of the supported CLIs — [Claude Code](https://docs.anthropic.com/en/docs/claude-code),
+[GitHub Copilot CLI](https://docs.github.com/en/copilot/github-copilot-in-the-cli), or
+[OpenAI Codex CLI](https://github.com/openai/codex) — and authenticate it, then confirm ralphctl can see it:
 
 ```bash
 ralphctl doctor    # verifies your provider CLI is installed + authenticated — the #1 first-run failure
@@ -99,7 +103,7 @@ ralphctl sprint show <sprint-id>
 ralphctl sprint progress <sprint-id>
 
 # Add / inspect tickets
-ralphctl ticket add
+ralphctl ticket add --title "<title>"
 ralphctl ticket list
 
 # Manage sprint state
@@ -131,23 +135,26 @@ ralphctl settings set ai.implement.evaluator.model    <model-id>
 ## How It Works
 
 ```
-  You describe what to build           ralphctl handles the rest
-  ─────────────────────────           ─────────────────────────────────
-  ┌──────────┐   ┌──────────┐        ┌────────┐   ┌──────┐   ┌───────────┐
-  │  Create  │──>│   Add    │───────>│ Refine │──>│ Plan │──>│ Implement │
-  │  Sprint  │   │ Tickets  │        │ (WHAT) │   │(HOW) │   │   Loop    │
-  └──────────┘   └──────────┘        └────────┘   └──────┘   └───────────┘
-                                          │            │             │
-                                     AI clarifies  AI generates  AI implements
-                                     requirements  task graph    + AI reviews
-                                     with you      from specs    each task
+  You describe what to build              ralphctl drives it to done
+  ─────────────────────────              ────────────────────────────────────────────
+  ┌──────────┐   ┌──────────┐        ┌────────┐   ┌──────┐   ┌───────────┐   ┌────────┐
+  │  Create  │──>│   Add    │───────>│ Refine │──>│ Plan │──>│ Implement │──>│ Review │──> done
+  │  Sprint  │   │ Tickets  │        │ (WHAT) │   │(HOW) │   │   Loop    │   │  Loop  │
+  └──────────┘   └──────────┘        └────────┘   └──────┘   └───────────┘   └────────┘
+                                         │            │            │             │
+                                    AI clarifies  AI builds   AI implements  you steer
+                                    requirements  the task    + AI reviews   revisions,
+                                    with you      graph       each task      close to done
 ```
 
 **Refine** is implementation-agnostic: the AI clarifies requirements with you, ticket by ticket, and flips each one from
 `pending` to `approved`. **Plan** requires every ticket approved — the AI explores the affected repos and generates a
 dependency-ordered task graph. **Implement** drives those tasks in dependency order through a generator-evaluator cycle:
 a second AI pass reviews each task against its spec before the harness marks it done and moves on. Independent tasks in
-the same dependency wave can run in parallel (opt-in) when you want a sprint to finish faster.
+the same dependency wave can run in parallel (opt-in) when you want a sprint to finish faster. **Review** closes the
+loop — once every task lands, the sprint enters `review` and you run human-steered feedback rounds: you flag what's off,
+the AI revises, and the sprint flips to `done` when you're satisfied. Opening a PR (`ralphctl create-pr`) is separate
+and optional.
 
 Key properties:
 
@@ -165,24 +172,24 @@ For the full architectural picture see [`.claude/docs/ARCHITECTURE.md`](./.claud
 
 ---
 
-## Provider Status
+## Providers
 
-> [!IMPORTANT]
-> Not all three AI providers are equally production-ready inside ralphctl.
+ralphctl drives three AI coding CLIs. Choose one per flow — or mix them, say plan with one and implement with
+another — through a [preset](#configuration) or per-row settings. All three are supported and in everyday use.
 
-| Provider                                  | Status                                                                          | Headless flag                                               | Native context file               |
-| ----------------------------------------- | ------------------------------------------------------------------------------- | ----------------------------------------------------------- | --------------------------------- |
-| **Claude Code** (`claude-code`)           | **Stable — primary verified provider**                                          | `--permission-mode bypassPermissions` + per-tool deny list  | `CLAUDE.md` at repo root          |
-| **GitHub Copilot CLI** (`github-copilot`) | Preview — maturing; works well day-to-day, not yet formally verified end-to-end | `--autopilot --allow-all` + `--max-autopilot-continues=200` | `.github/copilot-instructions.md` |
-| **OpenAI Codex** (`openai-codex`)         | Preview — maturing; works well day-to-day, not yet formally verified end-to-end | `-s workspace-write` (topology-scoped)                      | `AGENTS.md`                       |
+| Provider                                  | CLI       | Headless permission mapping                                                                     | Native context file               |
+| ----------------------------------------- | --------- | ----------------------------------------------------------------------------------------------- | --------------------------------- |
+| **Claude Code** (`claude-code`)           | `claude`  | `--permission-mode bypassPermissions` + per-tool deny list                                      | `CLAUDE.md` at repo root          |
+| **GitHub Copilot CLI** (`github-copilot`) | `copilot` | `--autopilot --max-autopilot-continues=200` + `--allow-all` (per-tool deny list when read-only) | `.github/copilot-instructions.md` |
+| **OpenAI Codex CLI** (`openai-codex`)     | `codex`   | `-s workspace-write` (topology-scoped)                                                          | `AGENTS.md`                       |
 
-"Preview" means the integration is in active use and increasingly solid — recent releases run Copilot and Codex well
-across the everyday flows — but harness behaviour against them hasn't been put through the same formal end-to-end
-verification as Claude Code. A couple of features still no-op on them (bundled skill injection, `bodyFile` forensic
-artifacts), and Codex can't fine-grained-deny edits on existing repo files — its sandbox modes are binary, so path
-scope (cwd + `--add-dir`) is the only safety envelope. Parallel execution is provider-agnostic: it works with whichever
-provider each implement role is configured to use, under the same per-provider caveats. If you hit a rough edge on a
-preview provider, please [open an issue](https://github.com/lukas-grigis/ralphctl/issues).
+Claude Code has the most end-to-end mileage inside the harness — it's the most battle-tested of the three — but Copilot
+and Codex run every flow and are supported first-class. Two small differences worth knowing: bundled skill injection
+and `bodyFile` forensic artifacts currently no-op on Copilot and Codex, and Codex's sandbox has only two modes
+(read-only / workspace-write), so path scope (cwd + `--add-dir`) is its fine-grained safety envelope rather than a
+per-tool deny list. Parallel execution is provider-agnostic — it works with whichever provider each implement role is
+configured to use. Hit a rough edge with any provider? Please [open an
+issue](https://github.com/lukas-grigis/ralphctl/issues).
 
 One-shot configuration for any provider: `ralphctl settings apply-preset <name>` where `<name>` is one of
 20 presets across five families — `standard`, `economic`, `strong-gate`, `fast`, and `frontier`, each in
@@ -225,8 +232,8 @@ Configure via the TUI `Settings` view or one-shot CLI commands.
 # Standard — flagship model per flow
 ralphctl settings apply-preset mixed               # best-fit provider per flow
 ralphctl settings apply-preset claude-only         # every flow on Claude Code
-ralphctl settings apply-preset copilot-only        # every flow on GitHub Copilot
-ralphctl settings apply-preset codex-only          # every flow on OpenAI Codex
+ralphctl settings apply-preset copilot-only        # every flow on GitHub Copilot CLI
+ralphctl settings apply-preset codex-only          # every flow on OpenAI Codex CLI
 
 # Economic — implement starts one tier below flagship; escalation ladder climbs only on plateau
 ralphctl settings apply-preset mixed-economic
@@ -364,20 +371,20 @@ readiness / create sprint) stay TUI-only by design. The CLI exposes inspection +
 
 ### Project & Sprint Inspection
 
-| Command                            | Description                               |
-| ---------------------------------- | ----------------------------------------- |
-| `ralphctl project list`            | List registered projects                  |
-| `ralphctl project show <id>`       | Show one project (incl. repositories)     |
-| `ralphctl project remove <id>`     | Delete a project registration             |
-| `ralphctl sprint list`             | List all sprints                          |
-| `ralphctl sprint show <id>`        | Show one sprint (tickets, status, branch) |
-| `ralphctl sprint progress <id>`    | Sprint progress with blocker diagnostics  |
-| `ralphctl sprint set-current <id>` | Switch the current sprint pointer         |
-| `ralphctl ticket add`              | Add a ticket to the current sprint        |
-| `ralphctl ticket list / show <id>` | Inspect tickets                           |
-| `ralphctl ticket remove <id>`      | Remove a ticket from a draft sprint       |
-| `ralphctl task list / show <id>`   | Inspect tasks (planning generates them)   |
-| `ralphctl task unblock <id>`       | Reset a blocked task to `todo`            |
+| Command                               | Description                                                                         |
+| ------------------------------------- | ----------------------------------------------------------------------------------- |
+| `ralphctl project list`               | List registered projects                                                            |
+| `ralphctl project show <id>`          | Show one project (incl. repositories)                                               |
+| `ralphctl project remove <id>`        | Delete a project registration                                                       |
+| `ralphctl sprint list`                | List all sprints                                                                    |
+| `ralphctl sprint show <id>`           | Show one sprint (tickets, status, branch)                                           |
+| `ralphctl sprint progress <id>`       | Sprint progress with blocker diagnostics                                            |
+| `ralphctl sprint set-current <id>`    | Switch the current sprint pointer                                                   |
+| `ralphctl ticket add --title <title>` | Add a ticket to the current sprint (`--sprint`, `--description`, `--link` optional) |
+| `ralphctl ticket list / show <id>`    | Inspect tickets                                                                     |
+| `ralphctl ticket remove <id>`         | Remove a ticket from a draft sprint                                                 |
+| `ralphctl task list / show <id>`      | Inspect tasks (planning generates them)                                             |
+| `ralphctl task unblock <id>`          | Reset a blocked task to `todo`                                                      |
 
 ### Sprint Lifecycle
 
@@ -419,14 +426,15 @@ Run `ralphctl <command> --help` for flag-level detail.
 | [Migration](./MIGRATION.md)                      | Per-version upgrade context for big version jumps        |
 | [Changelog](./CHANGELOG.md)                      | Version history                                          |
 
-**Blog posts:** [Building ralphctl](https://lukasgrigis.dev/blog/building-ralphctl) (
-backstory) | [From task CLI to ralph harness](https://lukasgrigis.dev/blog/ralphctl-agent-harness/) (evaluator
-deep-dive)
+**From the author** ([Lukas Grigis](https://lukasgrigis.dev/)):
+[Building ralphctl](https://lukasgrigis.dev/blog/building-ralphctl) (backstory)
+| [From task CLI to ralph harness](https://lukasgrigis.dev/blog/ralphctl-agent-harness/) (evaluator deep-dive)
+| [The harness era caught up](https://lukasgrigis.dev/blog/ralphctl-harness-era/) (the field converges on the harness bet)
 
-**Further reading:
-** [Harness Engineering for Coding Agent Users](https://martinfowler.com/articles/harness-engineering.html) — Martin
-Fowler (April 2026) | [Harness Design for Long-Running Application Development](https://www.anthropic.com/engineering/harness-design-long-running-apps) —
-Anthropic Engineering
+**Further reading:**
+[AI Agent Harnesses: A Field Guide](https://lukasgrigis.dev/blog/guides/agent-harnesses/) — Lukas Grigis
+| [Harness Engineering for Coding Agent Users](https://martinfowler.com/articles/harness-engineering.html) — Martin Fowler (April 2026)
+| [Harness Design for Long-Running Application Development](https://www.anthropic.com/engineering/harness-design-long-running-apps) — Anthropic Engineering
 
 ---
 

package/THIRD-PARTY-NOTICES.md

@@ -0,0 +1,92 @@
+# Third-party notices
+
+ralphctl bundles skill content adapted from the following MIT-licensed upstream projects. The
+adapted copies live under `src/integration/ai/skills/bundled/` (shipped as `dist/skills/`);
+verbatim upstream snapshots used for drift review live under `scripts/vendor/skills/`. Each
+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
+  [addyosmani/agent-skills](https://github.com/addyosmani/agent-skills)
+- `ralphctl-ponytail` — from [DietrichGebert/ponytail](https://github.com/DietrichGebert/ponytail)
+- `ralphctl-domain-driven-design` — from [wondelai/skills](https://github.com/wondelai/skills)
+
+---
+
+## addyosmani/agent-skills
+
+```
+MIT License
+
+Copyright (c) 2025 Addy Osmani
+
+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.
+```
+
+## DietrichGebert/ponytail
+
+```
+MIT License
+
+Copyright (c) 2026 DietrichGebert
+
+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.
+```
+
+## wondelai/skills
+
+```
+MIT License
+
+Copyright (c) 2025 Wondel.ai sp. z o.o.
+
+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.
+```