ralphctl 0.2.1 → 0.2.2

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/README.md CHANGED
@@ -4,53 +4,74 @@
4
4
  [![License: MIT](https://img.shields.io/badge/license-MIT-blue?style=flat&logo=opensourceinitiative&logoColor=white)](./LICENSE)
5
5
  [![TypeScript](https://img.shields.io/badge/TypeScript-5.9-3178c6?style=flat&logo=typescript&logoColor=white)](https://www.typescriptlang.org/)
6
6
  [![Node.js](https://img.shields.io/badge/node-%E2%89%A5_24-5fa04e?style=flat&logo=nodedotjs&logoColor=white)](https://nodejs.org/)
7
- [![code style: prettier](https://img.shields.io/badge/code_style-prettier-ff69b4?style=flat&logo=prettier&logoColor=white)](https://prettier.io/)
8
- [![ESLint](https://img.shields.io/badge/ESLint-4b32c3?style=flat&logo=eslint&logoColor=white)](https://eslint.org/)
9
7
  [![PRs Welcome](https://img.shields.io/badge/PRs-welcome-brightgreen?style=flat&logo=git&logoColor=white)](./CONTRIBUTING.md)
10
8
  [![Claude Code](https://img.shields.io/badge/Claude_Code-191919?style=flat&logo=anthropic&logoColor=white)](https://docs.anthropic.com/en/docs/claude-code)
11
9
  [![GitHub Copilot](https://img.shields.io/badge/GitHub_Copilot-000?style=flat&logo=githubcopilot&logoColor=white)](https://docs.github.com/en/copilot/github-copilot-in-the-cli)
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)
13
10
 
14
11
  ```
15
- 🍩 ██████╗ █████╗ ██╗ ██████╗ ██╗ ██╗ ██████╗████████╗██╗ 🍩
16
- ██╔══██╗██╔══██╗██║ ██╔══██╗██║ ██║██╔════╝╚══██╔══╝██║
17
- ██████╔╝███████║██║ ██████╔╝███████║██║ ██║ ██║
18
- ██╔══██╗██╔══██║██║ ██╔═══╝ ██╔══██║██║ ██║ ██║
19
- ██║ ██║██║ ██║███████╗██║ ██║ ██║╚██████╗ ██║ ███████╗
20
- ╚═╝ ╚═╝╚═╝ ╚═╝╚══════╝╚═╝ ╚═╝ ╚═╝ ╚═════╝ ╚═╝ ╚══════╝
12
+ ██████╗ █████╗ ██╗ ██████╗ ██╗ ██╗ ██████╗████████╗██╗
13
+ ██╔══██╗██╔══██╗██║ ██╔══██╗██║ ██║██╔════╝╚══██╔══╝██║
14
+ ██████╔╝███████║██║ ██████╔╝███████║██║ ██║ ██║
15
+ ██╔══██╗██╔══██║██║ ██╔═══╝ ██╔══██║██║ ██║ ██║
16
+ ██║ ██║██║ ██║███████╗██║ ██║ ██║╚██████╗ ██║ ███████╗
17
+ ╚═╝ ╚═╝╚═╝ ╚═╝╚══════╝╚═╝ ╚═╝ ╚═╝ ╚═════╝ ╚═╝ ╚══════╝
21
18
  ```
22
19
 
23
- **Agent harness for long-running AI coding tasks — orchestrates [Claude Code](https://docs.anthropic.com/en/docs/claude-code) & [GitHub Copilot](https://docs.github.com/en/copilot/github-copilot-in-the-cli) across repositories.**
20
+ **Agent harness for long-running AI coding tasks —
21
+ orchestrates [Claude Code](https://docs.anthropic.com/en/docs/claude-code) & [GitHub Copilot](https://docs.github.com/en/copilot/github-copilot-in-the-cli)
22
+ across repositories.**
24
23
 
25
24
  > _"I'm helping!"_ — Ralph Wiggum
26
25
 
27
26
  > [!NOTE]
28
27
  > **Early access.** RalphCTL is under active development. Things work, but expect rough edges and breaking changes
29
- > before 1.0. Read the [blog post](https://lukasgrigis.dev/blog/building-ralphctl) for the backstory.
28
+ > before 1.0.
30
29
 
31
- RalphCTL decomposes work into dependency-ordered tasks, executes them through AI coding agents, and runs a
32
- [generator-evaluator loop](https://www.anthropic.com/engineering/harness-design-long-running-apps) to catch issues
33
- before moving on. It manages context across sessions so nothing gets lost — whether you're working on a single ticket
34
- or coordinating changes across multiple repositories. Ralph Wiggum personality included because why not.
30
+ ---
31
+
32
+ ## Why ralphctl?
33
+
34
+ AI coding agents are powerful but lose context on long tasks, need babysitting when things break, and have no way to
35
+ coordinate changes across multiple repositories. RalphCTL decomposes your work into dependency-ordered tasks, runs each
36
+ one through a [generator-evaluator loop](https://www.anthropic.com/engineering/harness-design-long-running-apps) that
37
+ catches issues before moving on, and persists context across sessions so nothing gets lost. You describe what to build —
38
+ ralphctl handles the rest.
35
39
 
36
40
  ---
37
41
 
38
- ## Install
42
+ ## How It Works
39
43
 
40
- ```bash
41
- npm install -g ralphctl
42
44
  ```
45
+ You describe what to build ralphctl handles the rest
46
+ ───────────────────────── ─────────────────────────────────
47
+ ┌──────────┐ ┌──────────┐ ┌────────┐ ┌──────┐ ┌─────────┐
48
+ │ Create │──>│ Add │───────>│ Refine │──>│ Plan │──>│ Execute │
49
+ │ Sprint │ │ Tickets │ │ (WHAT) │ │(HOW) │ │ Loop │
50
+ └──────────┘ └──────────┘ └────────┘ └──────┘ └─────────┘
51
+ │ │ │
52
+ AI clarifies AI generates AI implements
53
+ requirements task graph + AI reviews
54
+ with you from specs each task
55
+ ```
56
+
57
+ - **Dependency-ordered execution** — tasks run in the right sequence, one per repo at a time, with parallel execution
58
+ where possible
59
+ - **Generator-evaluator cycle** — an independent AI reviewer checks each task against its spec; if it fails, the
60
+ generator gets feedback and iterates
61
+ - **Context persistence** — sprint state, progress history, and task context survive across sessions; interrupted work
62
+ resumes where it left off
43
63
 
44
- This installs the `ralphctl` command globally.
64
+ ---
45
65
 
46
- ### Prerequisites
66
+ ## Quick Start
47
67
 
48
- - [Node.js](https://nodejs.org/) **>= 24.0.0**
49
- - [Git](https://git-scm.com/)
50
- - Either [Claude CLI](https://docs.anthropic.com/en/docs/claude-code)
51
- or [GitHub Copilot CLI](https://docs.github.com/en/copilot/github-copilot-in-the-cli) installed and authenticated
68
+ ```bash
69
+ npm install -g ralphctl
70
+ ```
52
71
 
53
- ### 2-Minute Quick Start
72
+ Requires [Node.js](https://nodejs.org/) >= 24, [Git](https://git-scm.com/), and
73
+ either [Claude CLI](https://docs.anthropic.com/en/docs/claude-code)
74
+ or [GitHub Copilot CLI](https://docs.github.com/en/copilot/github-copilot-in-the-cli) installed and authenticated.
54
75
 
55
76
  ```bash
56
77
  # 1. Register a project (points to your repo)
@@ -68,36 +89,65 @@ ralphctl sprint plan
68
89
  ralphctl sprint start
69
90
  ```
70
91
 
71
- Or just run `ralphctl` with no arguments for an interactive menu that walks you through everything.
92
+ Or run `ralphctl` with no arguments for an interactive menu that walks you through everything.
72
93
 
73
94
  ---
74
95
 
75
- ## Table of Contents
96
+ ## Features
76
97
 
77
- - [Features](#features)
78
- - [CLI Overview](#cli-overview)
79
- - [AI Provider Configuration](#ai-provider-configuration)
80
- - [Documentation](#documentation)
81
- - [Development](#development)
82
- - [Contributing](#contributing)
83
- - [License](#license)
98
+ - **Break big tickets into small tasks** — dependency-ordered so they execute in the right sequence
99
+ - **Catch mistakes before they compound** — independent AI review after each task, iterating until quality passes or
100
+ budget is exhausted
101
+ - **Coordinate across repositories** — one sprint can span multiple repos with automatic dependency tracking
102
+ - **Run tasks in parallel** — one per repo, with rate-limit backoff and automatic session resume
103
+ - **Separate the what from the how** — AI clarifies requirements first, then generates implementation tasks, with human
104
+ approval gates
105
+ - **Pick up where you left off** — full state persistence across sessions; interrupted work resumes automatically
106
+ - **Pair or let it run** — work alongside your AI agent interactively, or let it execute unattended
107
+ - **Zero-memorization start** — run `ralphctl` with no args for a guided menu
84
108
 
85
109
  ---
86
110
 
87
- ## Features
111
+ ## Configuration
112
+
113
+ RalphCTL supports **Claude Code** and **GitHub Copilot** as AI backends.
114
+
115
+ ```bash
116
+ ralphctl config set provider claude # Use Claude Code
117
+ ralphctl config set provider copilot # Use GitHub Copilot
118
+ ```
119
+
120
+ Auto-prompts on first AI command if not set. Both CLIs must be in your PATH and authenticated.
121
+
122
+ <details>
123
+ <summary>Provider differences</summary>
124
+
125
+ | Feature | Claude Code | GitHub Copilot |
126
+ | --------------------------- | ------------------------------------ | -------------------------------------------------------------------- |
127
+ | Status | GA | Public preview |
128
+ | Headless execution | `-p --output-format json` | `-p --output-format json --autopilot --no-ask-user` |
129
+ | Session IDs | In JSON output (`session_id`) | In JSON output (`session_id`), `--share` file as fallback |
130
+ | Session resume (`--resume`) | Full support | Full support |
131
+ | Per-tool permissions | Settings files + `--permission-mode` | `--allow-all-tools` (all-or-nothing by default) |
132
+ | Fine-grained tool control | `allow`/`deny` in settings files | `--allow-tool`, `--deny-tool` flags (not yet used) |
133
+ | Rate limit detection | Validated patterns | Borrowed from Claude — not yet validated against real Copilot errors |
134
+
135
+ </details>
136
+
137
+ ---
88
138
 
89
- - **Task decomposition** — breaks tickets into dependency-ordered tasks with topological sort
90
- - **Generator-evaluator loop** — independent AI review after each task; iterates until quality passes or budget exhausted
91
- - **Multi-repo orchestration** coordinate changes across multiple repositories in a single run
92
- - **Parallel execution** — one task per repo at a time, with automatic rate limit backoff and session resume
93
- - **Two-phase planning** — clarify requirements first (what), then generate tasks (how), with a human approval gate
94
- - **Context persistence** — state survives across sessions; interrupted work resumes where it left off
95
- - **Interactive or headless** — pair with your AI agent in a session, or let it run unattended
96
- - **Menu mode** — run `ralphctl` with no arguments for an interactive menu
139
+ ## Data Directory
140
+
141
+ All data lives in `~/.ralphctl/` by default. Override with:
142
+
143
+ ```bash
144
+ export RALPHCTL_ROOT="/path/to/custom/data-dir"
145
+ ```
97
146
 
98
147
  ---
99
148
 
100
- ## CLI Overview
149
+ <details>
150
+ <summary><strong>CLI Command Reference</strong></summary>
101
151
 
102
152
  ### Getting Started
103
153
 
@@ -135,7 +185,7 @@ Or just run `ralphctl` with no arguments for an interactive menu that walks you
135
185
  | ------------------------ | --------------------------------- |
136
186
  | `ralphctl sprint start` | Execute tasks with AI |
137
187
  | `ralphctl sprint health` | Diagnose blockers and stale tasks |
138
- | `ralphctl dashboard` | Sprint overview with progress bar |
188
+ | `ralphctl status` | Sprint overview with progress bar |
139
189
  | `ralphctl task list` | List tasks in the current sprint |
140
190
  | `ralphctl task next` | Show the next unblocked task |
141
191
  | `ralphctl sprint close` | Close an active sprint |
@@ -143,54 +193,22 @@ Or just run `ralphctl` with no arguments for an interactive menu that walks you
143
193
 
144
194
  Run `ralphctl <command> --help` for details on any command.
145
195
 
146
- ---
147
-
148
- ## AI Provider Configuration
149
-
150
- RalphCTL supports **Claude Code** and **GitHub Copilot** as AI backends. Both use the same prompt templates and
151
- workflow.
152
-
153
- ```bash
154
- ralphctl config set provider claude # Use Claude Code
155
- ralphctl config set provider copilot # Use GitHub Copilot
156
- ```
157
-
158
- Auto-prompts on first AI command if not set. Both CLIs must be in your PATH and authenticated.
159
-
160
- ### Provider Differences
161
-
162
- | Feature | Claude Code | GitHub Copilot |
163
- | --------------------------- | ------------------------------------ | -------------------------------------------------------------------- |
164
- | Status | GA | Public preview |
165
- | Headless execution | `-p --output-format json` | `-p --output-format json --autopilot --no-ask-user` |
166
- | Session IDs | In JSON output (`session_id`) | In JSON output (`session_id`), `--share` file as fallback |
167
- | Session resume (`--resume`) | Full support | Full support |
168
- | Per-tool permissions | Settings files + `--permission-mode` | `--allow-all-tools` (all-or-nothing by default) |
169
- | Fine-grained tool control | `allow`/`deny` in settings files | `--allow-tool`, `--deny-tool` flags (not yet used) |
170
- | Rate limit detection | Validated patterns | Borrowed from Claude — not yet validated against real Copilot errors |
196
+ </details>
171
197
 
172
198
  ---
173
199
 
174
200
  ## Documentation
175
201
 
176
- | Document | Description |
177
- | ----------------------------------------------------------- | ---------------------------------------------- |
178
- | [REQUIREMENTS.md](./.claude/docs/REQUIREMENTS.md) | Acceptance criteria and feature requirements |
179
- | [ARCHITECTURE.md](./.claude/docs/ARCHITECTURE.md) | Data models, file storage, and error reference |
180
- | [CLAUDE.md](./CLAUDE.md) | Developer guide and Claude Code project config |
181
- | [CONTRIBUTING.md](./CONTRIBUTING.md) | How to contribute |
182
- | [CHANGELOG.md](./CHANGELOG.md) | Version history |
183
- | [Blog post](https://lukasgrigis.dev/blog/building-ralphctl) | Background and motivation |
202
+ | Resource | Description |
203
+ | ---------------------------------------------- | ------------------------------------------ |
204
+ | [Architecture](./.claude/docs/ARCHITECTURE.md) | Data models, file storage, error reference |
205
+ | [Requirements](./.claude/docs/REQUIREMENTS.md) | Acceptance criteria and feature checklist |
206
+ | [Contributing](./CONTRIBUTING.md) | Dev setup, code style, PR process |
207
+ | [Changelog](./CHANGELOG.md) | Version history |
184
208
 
185
- ---
186
-
187
- ## Data Directory
188
-
189
- RalphCTL stores all data in `~/.ralphctl/` by default. Override with `RALPHCTL_ROOT`:
190
-
191
- ```bash
192
- export RALPHCTL_ROOT="/path/to/custom/data-dir"
193
- ```
209
+ **Blog posts:** [Building ralphctl](https://lukasgrigis.dev/blog/building-ralphctl) (
210
+ backstory) | [From task CLI to agent harness](https://lukasgrigis.dev/blog/ralphctl-agent-harness/) (evaluator
211
+ deep-dive)
194
212
 
195
213
  ---
196
214
 
@@ -2680,11 +2680,15 @@ async function runEvaluationLoop(params) {
2680
2680
  {
2681
2681
  cwd: task.projectPath,
2682
2682
  args: ["--add-dir", sprintDir, ...buildProviderArgs(options, provider)],
2683
- prompt: `The evaluator found issues with your work:
2683
+ prompt: `The evaluator found issues with your implementation:
2684
2684
 
2685
2685
  ${evalResult.output}
2686
2686
 
2687
- Fix these issues, then verify${options.noCommit ? "" : ", commit your fix,"} and signal completion.`,
2687
+ Review the critique carefully. Fix each identified issue in the code, then:
2688
+ 1. Re-run verification commands to confirm the fix
2689
+ ${options.noCommit ? "" : "2. Commit the fix with a descriptive message\n"}${options.noCommit ? "2" : "3"}. Signal completion with <task-verified> and <task-complete>
2690
+
2691
+ If the critique is about something outside your task scope, fix only what is within scope and signal completion.`,
2688
2692
  resumeSessionId: result.sessionId ?? void 0,
2689
2693
  env: provider.getSpawnEnv()
2690
2694
  },
package/dist/cli.mjs CHANGED
@@ -52,7 +52,7 @@ import {
52
52
  sprintStartCommand,
53
53
  updateTaskStatus,
54
54
  validateImportTasks
55
- } from "./chunk-AXNZMHFQ.mjs";
55
+ } from "./chunk-XXIHDQOH.mjs";
56
56
  import {
57
57
  escapableSelect
58
58
  } from "./chunk-7LZ6GOGN.mjs";
@@ -3763,7 +3763,7 @@ async function interactiveMode() {
3763
3763
  continue;
3764
3764
  }
3765
3765
  if (command === "wizard") {
3766
- const { runWizard } = await import("./wizard-TFJXEYD2.mjs");
3766
+ const { runWizard } = await import("./wizard-D7N5WZ5H.mjs");
3767
3767
  await runWizard();
3768
3768
  continue;
3769
3769
  }
@@ -4234,7 +4234,7 @@ Checks performed:
4234
4234
  // package.json
4235
4235
  var package_default = {
4236
4236
  name: "ralphctl",
4237
- version: "0.2.1",
4237
+ version: "0.2.2",
4238
4238
  description: "Agent harness for long-running AI coding tasks \u2014 orchestrates Claude Code & GitHub Copilot across repositories",
4239
4239
  homepage: "https://github.com/lukas-grigis/ralphctl",
4240
4240
  type: "module",
@@ -58,6 +58,12 @@ Explore the selected repositories and produce implementation tasks:
58
58
  3. **Create tasks** — Following the Planning Common Context guidelines below
59
59
  4. **Validate** — Ensure tasks are non-overlapping, properly ordered, and completable
60
60
 
61
+ ### Blocker Handling
62
+
63
+ If you cannot produce a valid plan, signal the issue instead of outputting incomplete JSON:
64
+
65
+ - `<planning-blocked>reason</planning-blocked>`
66
+
61
67
  ## Idea to Implement
62
68
 
63
69
  **Title:** {{IDEA_TITLE}}
@@ -79,11 +79,11 @@ Before outputting JSON, verify EVERY item on this checklist:
79
79
  instructions
80
80
  7. **projectPath assigned** — Every task has a `projectPath` from the project's repository paths
81
81
  8. **Clear done state** — For each task, the question "how do I know this is done?" has an obvious answer
82
- 9. **Valid JSON** — The output parses as a JSON array of task objects matching the schema
82
+ 9. **Valid JSON** — The output parses as valid JSON matching the schema
83
83
 
84
84
  ## Output
85
85
 
86
- **IMPORTANT:** Output ONLY a valid JSON array. No markdown, no explanation, no commentary — just the JSON.
86
+ **IMPORTANT:** Output ONLY valid JSON matching the schema below. No markdown, no explanation, no commentary — just the JSON.
87
87
  If you cannot produce tasks, output a `<planning-blocked>` signal instead.
88
88
 
89
89
  JSON Schema:
@@ -20,10 +20,11 @@ You are working in this project directory:
20
20
  ### Investigation Steps
21
21
 
22
22
  1. Run `git log --oneline -10` to identify the commits from this task, then run `git diff <base>..HEAD` for the full range of changes (tasks may produce multiple commits — do not assume a single commit)
23
- 2. Read the changed files carefully to understand the full implementation context
24
- 3. Look at surrounding code to understand patterns and conventions
25
- 4. Compare the actual changes against the task specification above
26
- 5. Identify any issues:
23
+ 2. Run `git status` to check for uncommitted changes — uncommitted work may indicate the task is incomplete
24
+ 3. Read the changed files carefully to understand the full implementation context
25
+ 4. Look at surrounding code to understand patterns and conventions
26
+ 5. Compare the actual changes against the task specification above
27
+ 6. Identify any issues:
27
28
  - **Spec drift** — changes that go beyond or fall short of what was specified
28
29
  - **Missing edge cases** — error paths, boundary conditions, empty states
29
30
  - **Unnecessary changes** — modifications unrelated to the task
@@ -33,6 +34,11 @@ You are working in this project directory:
33
34
 
34
35
  Do NOT suggest improvements or refactoring beyond the task scope.
35
36
  Only evaluate what was asked vs what was delivered.
37
+
38
+ ### Pass Bar
39
+
40
+ Pass the implementation if it satisfies the task specification without correctness or security issues.
41
+ Do not fail for style preferences, naming opinions, or improvements beyond the task scope.
36
42
  {{CHECK_SCRIPT_SECTION}}
37
43
 
38
44
  ## Output
@@ -35,9 +35,10 @@ Perform these checks IN ORDER before writing any code:
35
35
  discovered, and gotchas encountered. This avoids duplicating work and surfaces context that the task steps may not
36
36
  capture.
37
37
  3. **Check git state** — Run `git status` to check for uncommitted changes
38
- 4. **Check environment** — Look at the "Check Script" and "Environment Status" sections in your context file. If a check
39
- script is configured, the harness ran it at sprint start. If not configured, run the project's verification commands
40
- yourself (check CLAUDE.md, .github/copilot-instructions.md, or project config). If ANY check fails, STOP:
38
+ 4. **Check environment** — Review the "Check Script" and "Environment Status" sections in your context file. If a check
39
+ script is configured, the harness already verified the environment review those results rather than re-running.
40
+ If no check script is configured AND no environment status is recorded, run the project's verification commands
41
+ yourself (check CLAUDE.md, .github/copilot-instructions.md, or project config). If ANY check shows failure, STOP:
41
42
  ```
42
43
  <task-blocked>Pre-existing failure: [details of what failed and the output]</task-blocked>
43
44
  ```
@@ -101,7 +102,7 @@ Complete these steps IN ORDER:
101
102
 
102
103
  - Created src/schemas/date-range.ts with DateRangeSchema (Zod + .openapi())
103
104
  - Modified src/controllers/export.ts to accept optional `startDate`/`endDate` query params
104
- - Added tests in src/schemas/**tests**/date-range.test.ts
105
+ - Added tests in `src/schemas/__tests__/date-range.test.ts`
105
106
 
106
107
  ### Learnings and Context
107
108
 
@@ -105,7 +105,7 @@ approval. Iterate until approved.
105
105
  Before writing to file, verify ALL of these are true:
106
106
 
107
107
  - [ ] Problem statement is clear and agreed upon
108
- - [ ] Every requirement has 2+ acceptance criteria with multiple scenarios each (happy path + edge case minimum)
108
+ - [ ] Every requirement has acceptance criteria covering key scenarios (happy path + edge/error cases at minimum)
109
109
  - [ ] Scope boundaries are explicit (what's in AND what's out)
110
110
  - [ ] Edge cases and error states are addressed
111
111
  - [ ] No implementation details leaked into requirements
@@ -3,7 +3,7 @@ import {
3
3
  sprintPlanCommand,
4
4
  sprintRefineCommand,
5
5
  sprintStartCommand
6
- } from "./chunk-AXNZMHFQ.mjs";
6
+ } from "./chunk-XXIHDQOH.mjs";
7
7
  import "./chunk-7LZ6GOGN.mjs";
8
8
  import {
9
9
  sprintCreateCommand
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "ralphctl",
3
- "version": "0.2.1",
3
+ "version": "0.2.2",
4
4
  "description": "Agent harness for long-running AI coding tasks — orchestrates Claude Code & GitHub Copilot across repositories",
5
5
  "homepage": "https://github.com/lukas-grigis/ralphctl",
6
6
  "type": "module",