Skip to content

tim-hub/powerball-harness / harness/skills/harness-plan

harness-plan

Verified

Plans and tracks tasks in .claude/harness/plans.json. Use when creating plans, adding tasks, updating markers, checking progress, or brainstorming an idea into tasks.

FileKindSize
SKILL.mdskill md8.0 KB
references/add.mdmarkdown2.7 KB
references/archive.mdmarkdown1.8 KB
references/brainstorm.mdmarkdown3.5 KB
references/create.mdmarkdown15.6 KB
references/planning-quality.mdmarkdown7.6 KB
references/ralph-tasks.mdmarkdown2.8 KB
references/sync.mdmarkdown6.4 KB
references/task-fields.mdmarkdown2.1 KB
references/update.mdmarkdown2.3 KB
templates/plans-md-template.mdmarkdown1.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.
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: 198kUpdated Claude CodeCodexVerifiedInstall
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: 194kUpdated Claude CodeCodexVerifiedInstall
ponytail-debtDietrichGebert/ponytailHarvest every shortcut: comment into one debt ledger, so deferrals get tracked instead of forgotten. One-shot report.Stars: 194kUpdated Claude CodeCodexVerifiedInstall
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: 194kUpdated Claude CodeCodexVerifiedInstall