agentleFS
Sign inStart free
johnarksjohnarks/helix-loop/skills/checkpoint-planner/SKILL.md

checkpoint-planner

Skill9 starsChanged 48 days agoMITView on GitHub

Splits a feature or migration into small, ordered checkpoints of increasing complexity and writes them to .helix/checkpoints.json. Use at the start of any orchestrated build, after the app-state check.

The file

We split this skill into the rules it gives an agent

3 rules. About 0 are common, 1 is distinctive, and 2 are very specific to this project.

  • ≈0

    Common · estimate

    Many files like this have a rule of this kind.

  • ≈1

    Distinctive · estimate

    This author's own choices. Worth a look.

  • 2

    Very specific

    Tied to their project's names, files or tools. Probably skip.

  • Common
  • Distinctive
  • Very specific
  1. Very specific:

    If the reference is ambiguous and you cannot resolve it from code/designs/docs, ask the human now via the orchestrator.

    line 25
  2. Very specific:

    Write .helix/checkpoints.json conforming to schemas/checkpoints.schema.json.

    line 29
  3. Distinctive:

    Keep titles and descriptions simple and concrete.

    line 33

≈ “Common” is an estimate: at least 1 in 5 of the 350,495 skill files we read have a rule of the same kind, not the same words. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.

Keep what fits and drop the rest. Your version, ready for your agents.
Files
SKILL.md

Checkpoint Planner

You turn a large piece of work into a sequence of small checkpoints. The human will review your sequence in minutes — design it for that.

Inputs

  • The reference: existing screen/app code (migration — "the reference is the spec") or feature description + designs/docs (new work).
  • The project's architecture doc and .helix/learnings.md.

How to split

  1. Order by increasing complexity. The first checkpoint is the skeleton/foundation (screen shell, nav, layout). The second is one deliberately small section. Later checkpoints grow only after early decisions have passed review. Rationale: each checkpoint builds on the previous one — if an early decision is wrong, you catch it while it's small and cheap to fix.
  2. Small enough to review at a glance. Each checkpoint gets a title of a few words plus one-paragraph scope. If you can't describe it briefly, split it further.
  3. Small enough for a small context window. A worker subagent must be able to hold the checkpoint's scope plus the relevant reference excerpt without a giant spec file. Prefer 4–8 checkpoints for a screen; more for a large feature.
  4. Independently verifiable. Each checkpoint must have clear done-criteria and be testable on its own.
  5. Flag needs_ui_gate. true if the checkpoint produces anything visible; false for logic-only work (data layer, permissions, background jobs).

Questions

If the reference is ambiguous and you cannot resolve it from code/designs/docs, ask the human now via the orchestrator. List your questions plainly, with your recommended answer for each. Do not guess on scope.

Output

Write .helix/checkpoints.json conforming to schemas/checkpoints.schema.json. Also keep a human-readable summary at the top of your reply to the orchestrator: the ordered titles, one line each, with the one-sentence reason for the order.

Language

Keep titles and descriptions simple and concrete. The human reading the viewer is not necessarily the person who wrote the reference code. "Login form shell with empty fields" beats "authentication view container initialization."

Download now (ZIP)

Does it work?

Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.

No reviews yet

People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.

  • It worked
  • Partly
  • It didn't
What did you use it for? e.g. Reviewing pull requests in a Rails app

Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.

Your trail

Files you open will collect here, so you can find them again.

Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.

Now do this for your own.

Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.

Check your setup, free