Planrunner Skills

Three Claude Code skills for executing trusted Markdown plans on macOS and Linux:

Skill	Use it for	Network behavior owned by this project
Light Runner	small, low-risk, sequential step lists	none
Plan Runner	strict plans with dependencies, recon, gates, and durable resume	none
Max Runner	long runs with one-step session resets and independent Codex review	sends inspected gate evidence through Codex

The release is a source-distributed collection of self-contained skill directories. The Python helpers use only the standard library; there is no Python package or registry publication requirement.

Requirements

• macOS or Linux/POSIX;
• Python 3.10 or newer;
• a current Claude Code release with Agent Skills and subagents;
• Max Runner only: an authenticated codex CLI available on PATH and network access.

Windows is not supported. The optional launchd templates are macOS-only; the core skills and test suite run on both supported operating systems.

Install

Clone the repository:

git clone https://github.com/eddiepohj/planrunner-skills.git
cd planrunner-skills

Then choose an explicit skill directory. For a single project:

./scripts/install.sh --target /absolute/path/to/project/.claude/skills

For a personal installation, pass your Claude Code personal skills directory explicitly. The installer never chooses a home directory, reads a shell profile, or overwrites an existing skill silently. --force first moves each conflicting skill to a sibling .backup directory and refuses to overwrite an existing backup.

Claude Code also supports using the three directories directly as project or personal skills. Each has a SKILL.md plus its required scripts, references, and assets.

Quick start

Copy one of the synthetic examples into a disposable project, review it, and invoke the runner explicitly:

/light-runner /absolute/path/to/PLAN.md
/plan-runner /absolute/path/to/PLAN.md
/max-runner /absolute/path/to/PLAN.md

Light Runner uses examples/light/PLAN.md. Plan Runner and Max Runner use examples/structured/PLAN.md. Max Runner tells you exactly which generated evidence will be sent to Codex and waits for acceptance before Gate 0.

All skill descriptions require an explicit runner request. They mutate projects and may execute plan-authored commands, so explicit invocation is part of the security boundary. Claude Code administrators who need a hard policy can additionally configure local skill visibility/invocation controls.

Configuration

Configuration lives in the plan, not in private home files or undeclared environment variables.

• Plan Runner: see skills/plan-runner/references/plan-schema.md.
• Max Runner: see skills/max-runner/references/plan-schema.md; optional fields include slug, project root, director sweep interval, fable limit, and reviewer model.
• Light Runner: every step needs Goal: and may have Owner:, Tool hint:, Check:, and Depends on:.

Bundled script paths are resolved through Claude Code's ${CLAUDE_SKILL_DIR} substitution. Generated project directives receive an absolute helper path at injection time.

Privacy and security

Plans are trusted executable input. Workers may edit files, and a Check: or Acceptance command may execute arbitrary programs. Review the plan and all commands before running.

The bundled Light Runner and Plan Runner helpers make no network requests. The host agent, workers, or plan commands may. Max Runner's reviewer.py invokes codex exec with an ephemeral session, read-only sandbox, and user/project configuration disabled; it sends the selected artifact and optional context over the network. Inspect artifacts for credentials, private source, paths, and unrelated changes before approval.

Generated _lightrunner, _planrunner, _maxrunner, BUILD-LOG.md, briefs, reports, recon, diffs, and review records can contain sensitive data. They are ignored by this repository's defaults and must be scanned independently before publication.

See SECURITY.md for reporting and trust-boundary details.

Verify

From outside the source directory, Python can execute the absolute script paths directly. Run the hermetic public suite from the release root:

python3 -m unittest discover -s tests -v
python3 scripts/check_release.py .

The suite validates metadata, plan rejection, scaffolding containment, interruption and rerun state, Gate-B evidence, staged/untracked artifacts, explicit installation, and privacy patterns. It uses synthetic temporary projects and does not call network services.

To inspect the Max Runner network command without sending data:

python3 skills/max-runner/scripts/reviewer.py \
  --project-root . --gate b --step demo --round 1 \
  --artifact tests/fixtures/valid-plan.md \
  --emit-dir ./reviewer-dry-run --dry-run

In the works

These roadmap items are exploratory and are not part of the current release contract:

• Provider-neutral adversarial review. Give Max Runner a stable reviewer adapter and typed JSON response contract that can use any compatible adversarial LLM. Initial adapters would target hosted Hugging Face models and local Ollama models alongside the current Codex reviewer. Every backend must preserve explicit opt-in, artifact preview, model provenance, bounded timeouts, and no silent provider fallback.
• A shared runner/AgentView interoperability contract. Have Light Runner, Plan Runner, and Max Runner emit a versioned run manifest and normalized event stream that AgentView can validate directly. Capability declarations, schema versions, reviewer provenance, and redaction flags would make new runners and reviewer backends visible without bespoke layout parsing or ambiguous inference.

Cleanup and uninstall

Stop any user-created scheduler first. Remove only the exact generated run directories you have reviewed:

rm -r /absolute/path/to/project/_lightrunner
rm -r /absolute/path/to/project/_planrunner
rm -r /absolute/path/to/project/_maxrunner

BUILD-LOG.md, generated CLAUDE.md blocks, and .claude/agents may contain unrelated project content; review and remove those selectively rather than using a broad recursive command.

To uninstall the skills, remove the exact plan-runner, light-runner, and max-runner directories from the target you passed to the installer. If --force created .backup directories, restore them manually after reviewing both versions.

Release model

Publish a fresh source archive or new Git repository containing only this snapshot. Do not graft it onto a private repository or copy private Git objects. A GitHub source release is the intended first distribution; no Python wheel is appropriate because the public artifacts are Claude Code skill bundles rather than an importable library.

Author and license

Built by Edvard Pohjavirta. Licensed under Apache License 2.0. See LICENSE and NOTICE.