ptshih

Spec Runner — Testing skill for Claude Code

Testing community

Agent skill and CLI that runs a bounded task feature by feature: a features.json queue kept outside the repository, progress.txt as memory across context windows, one landed commit per feature.

How to install Spec Runner

This entry records only its repository, not the path inside it, so there is no exact command to give. Open ptshih/spec-runner and copy the folder into ~/.claude/skills/, or the file into ~/.claude/agents/.

What Spec Runner does

Agent skill and CLI that runs a bounded task feature by feature: a features.json queue kept outside the repository, progress.txt as memory across context windows, one landed commit per feature. For Claude Code, Pi and Codex.

Alternatives in Testing

Test Runner — Run Python tests with pytest, unittest, or other testing frameworks 23.4k ★
Crlf — Test for CRLF / HTTP response-splitting and host-header injection — Set-Cookie injection, cache poisoning, res 4.5k ★
AI Contribution Skills (Engram) — branch-pr: clean branch and PR workflow 2.5k ★

README

spec-runner

**Run a bounded task feature by feature, one landed commit at a time.**

spec-runner is an agent skill with a small CLI. `features.json` holds the ordered queue, `progress.txt` is the memory that outlives a context window or a session, and `init.sh` is the baseline check. The agent takes the next pending feature, writes the failing test, makes it pass, runs the check, lands the commit, records the pass and continues in the same turn until the queue is complete or a feature is blocked. Nothing external pokes it: the [skill](SKILL.md) supplies the loop, the CLI supplies the state and the guardrails. A pass needs a clean tree and records the landing commit; a queue left in a repository root is refused.

The queue lives outside the repository at `$XDG_STATE_HOME/spec-runner//` (default `~/.local/state`), keyed by the main checkout so a project's worktrees share it. `SPEC_RUNNER_DIR` overrides the location, absolute or relative to the repo root. Nothing in the tree needs ignoring.

Install

The skill directory carries the CLI, so installing the skill installs the tool.

npx skills add ptshih/spec-runner             # copies into ~/.agents/skills and links every detected harness
pi install git:github.com/ptshih/spec-runner  # as a Pi package
claude plugin marketplace add ptshih/spec-runner && claude plugin install spec-runner@spec-runner

Or clone the repository anywhere your harness reads skills from. Requirements: [Bun](https://bun.sh), git and bash. A shell command is optional:

ln -s ~/.agents/skills/spec-runner/scripts/spec-runner.ts ~/.local/bin/spec-runner

Then ask the agent to run spec-runner, or to work feature by feature. The skill defines `spec-runner` as `bun /scripts/spec-runner.ts`.

Commands

Command	What it does
`spec-runner init [title]`	Scaffold `features.json`, `progress.txt` and `init.sh` in the queue directory
`spec-runner status`	Print the queue path, completio