tim-hub/powerball-harness / harness/skills/harness-plan
harness-plan
VerifiedPlans and tracks tasks in .claude/harness/plans.json. Use when creating plans, adding tasks, updating markers, checking progress, or brainstorming an idea into tasks.
| File | Kind | Size |
|---|---|---|
| SKILL.md | skill md | 8.0 KB |
| references/add.md | markdown | 2.7 KB |
| references/archive.md | markdown | 1.8 KB |
| references/brainstorm.md | markdown | 3.5 KB |
| references/create.md | markdown | 15.6 KB |
| references/planning-quality.md | markdown | 7.6 KB |
| references/ralph-tasks.md | markdown | 2.8 KB |
| references/sync.md | markdown | 6.4 KB |
| references/task-fields.md | markdown | 2.1 KB |
| references/update.md | markdown | 2.3 KB |
| templates/plans-md-template.md | markdown | 1.4 KB |
references/ralph-tasks.md
View on GitHub# Ralph Tasks — Iterative Loop Task Reference
`[ralph]` marks a task that should be executed by `harness-ralph-loop`.
The loop spawns a fresh Worker subagent per attempt, iterating until both a `<promise>` tag
AND a verify command succeed.
---
## When harness-plan Should Emit `[ralph]`
Apply `[ralph]` when the task description contains any of the following trigger phrases:
| Trigger Phrase | Example Task Description |
|----------------|--------------------------|
| "until tests pass" | "Fix auth module until tests pass" |
| "iterate until X" | "Iterate until lint is clean" |
| "fix until passing" | "Fix CI failures until passing" |
| "loop until clean" | "Loop until clean" |
| "until clean" | "Refactor database layer until clean" |
| "greenfield until tests green" | "Greenfield payment service until tests green" |
Detection is case-insensitive and matches substrings.
---
## Required Per-Task Fields When `[ralph]` Is Applied
When a task receives `[ralph]`, two extra lines are appended **below** the task row
(similar to comment lines — they are not columns):
### `Verify:` line (required)
A bash command that must exit 0 for the loop to terminate.
Auto-inferred from project type when not explicitly specified by the user:
| Project-type signal | Auto-inferred `Verify:` command |
|--------------------|---------------------------------|
| `package.json` present | `npm test` |
| `pyproject.toml` or `setup.py` present | `pytest` |
| `Cargo.toml` present | `cargo test` |
| `go.mod` present | `go test ./...` |
| None of the above found | `# TODO: set Verify command` |
Inference priority: check in the order listed above; use the first match.
### `MaxIter:` line (optional)
Maximum number of Worker attempts before the loop gives up.
Default: `10` (applied automatically when the line is omitted).
---
## Worked Example
The following is a concrete Plans.md excerpt showing a `[ralph]` task block:
```markdown
| Task | Description | DoD | Depends | Status |
|------|-------------|-----|---------|--------|
| 3.2 | Fix flaky integration tests [ralph] | All tests pass (`npm test` exits 0) | 3.1 | cc:TODO |
Verify: npm test
MaxIter: 15
```
Key points:
- `[ralph]` appears inline in the Description column
- `Verify:` and `MaxIter:` appear as plain lines **below** the task row, not as columns
- `MaxIter:` is optional; omit to use the default of 10
---
## Serialization Warning
**Only one `[ralph]` task may be active at a time within a session.**
Ralph tasks serialize within a session because each attempt spawns a fresh Worker subagent
that may mutate shared state (files, test fixtures, databases).
Running two `[ralph]` loops concurrently risks conflicting writes and non-deterministic outcomes.
`harness-ralph-loop` enforces this constraint: if another `[ralph]` task is already in a
`cc:WIP` state, the new loop will wait rather than start a second concurrent loop.
Related skills
| Skill | Stars | Updated | Works with | Status | Install |
|---|---|---|---|---|---|
| slack-gif-creatoranthropics/skillsKnowledge and utilities for creating animated GIFs optimized for Slack. Provides constraints, validation tools, and animation concepts. Use when users request animated GIFs for Slack like "make me a GIF of X doing Y for Slack." | Stars: 198k | Updated | Claude CodeCodex | Verified | Install |
| ponytailDietrichGebert/ponytailLazy senior dev mode for any coding task: the smallest change that fully solves it, and a reply a busy human understands in one read. | Stars: 194k | Updated | Claude CodeCodex | Verified | Install |
| ponytail-debtDietrichGebert/ponytailHarvest every shortcut: comment into one debt ledger, so deferrals get tracked instead of forgotten. One-shot report. | Stars: 194k | Updated | Claude CodeCodex | Verified | Install |
| ponytail-debtDietrichGebert/ponytailList every `shortcut:` comment (and older `ponytail:` ones) as a debt ledger. One-shot report, changes nothing. Use for "ponytail debt", "what did ponytail defer", "list the shortcuts", /ponytail-debt. | Stars: 194k | Updated | Claude CodeCodex | Verified | Install |