st_skill

Overview

This skill manages a durable, repo-committed task plan using an in-place JSONL file (default: .step/st-plan.jsonl) so state survives turns, sessions, and is reviewable in git. It provides mutation commands, deterministic read views, and a lightweight sync protocol to publish update_plan payloads after each change. The model uses an event lane plus periodic checkpoint snapshots for efficient and auditable state.

How this skill works

The tool initializes and rehydrates plan state from a JSONL file that contains typed events and full-state checkpoints. Mutations (add, set-status, set-deps, set-notes, add-comment, remove, import-plan) write atomic JSONL entries and emit a single update_plan payload line that callers must parse and publish. Read-only helpers show ready/blocked/in-progress views and fast query scripts use jq + ripgrep for low-latency inspections.

When to use it

• When you need persistent, git-reviewable TODO state that survives sessions and turns.
• When you want to checkpoint milestones and export/import plan snapshots between environments.
• When you need to track typed dependencies and block/unblock work deterministically.
• When you want a single canonical in-repo source for shared task status and comments.
• When you must publish an update_plan payload after edits for downstream sync.

Best practices

• Keep short, stable item IDs (st-001, st-002...) and prefer show --format markdown for execution views.
• Do not hand-edit existing JSONL lines; use the provided mutation commands to preserve integrity.
• Ensure .step/st-plan.jsonl.lock is gitignored before first mutation to avoid committing locks.
• Allow exactly one in_progress item unless you explicitly enable --allow-multiple-in-progress.
• Validate deps: ensure referenced IDs exist, prevent self-deps and cycles, and normalize types to kebab-case.

Example use cases

• Resume a paused plan across chat turns: run show, then set-status to in_progress and publish update_plan payload.
• Checkpoint a milestone before a risky change: run export to create a portable snapshot for handoff.
• Find next ready tasks for pairing: run ready --format markdown and use the Ready section as the agenda.
• Track blocked work: use set-deps to declare blockers and blocked to inspect waiting items.
• Bulk-import a snapshot to reset state during a large replan using import-plan --replace.