Claude Code Task Shepherd Skill

task-shepherd-skill

A [Claude Code](https://claude.com/claude-code) skill for running a long, complex task — pre-broken into segments — through to completion without losing the thread. Real state (which segment is current, what happened, what's next) lives in a plan file on disk, never in conversation memory, so it survives `/compact` and turn boundaries by construction.

See [`SKILL.md`](./SKILL.md) for what Claude actually does with this skill: the directory layout, how a plan is written and executed, why segment handoff uses `Monitor` instead of `/loop` + `ScheduleWakeup`, and what to do when a segment reports `blocked`.

The core idea

A **plan** is a directory (`shepherd.yaml` + whatever reference files its segments need). Each turn only ever sees the *one* segment it needs to act on right now, revealed fresh by `next_step.py` — never the whole plan, never future segments. After finishing a segment, `finish_step.py` records the outcome and a short-lived `Monitor` hands off to a fresh turn for the next one. Nothing about resuming correctly depends on the conversation still remembering anything.

Quick start

cd scripts && uv sync
uv run list_plans.py                 # see what's available
uv run next_step.py selftest         # try the bundled self-test fixture

The `selftest` fixture (`shepherds/archives/selftest/`) is a small real scikit-learn pipeline with a genuine bug planted in one segment and an accuracy target the model can't reach in another — it exercises the `on_error` retry path and the `blocked` path with actual code, not a toy simulation.

Status

Prototype (2026-08-31). The core loop (segment reveal → do the work → record outcome → `Monitor` handoff) was verified end to end by a fresh, independent Claude Code session with no prior context — including diagnosing and fixing the planted bug unassisted, correctly refusing to self-authorize a fix for a below-target result, and correctly resuming from a `blocked` state after the u