how-to-run-a-sprint

How To Run A Sprint

A Sprinty sprint is item-driven. Do not keep parallel prose trackers when tools are available.

Why Use This Instead Of A Scratch Todo List

An in-session todo list is cheaper, and for a two-step fix it is the right tool. Reach for Sprinty when any of these are true, because a todo list cannot do them:

• The work outlives your context. The ledger is on disk. After compaction, a restart, or a handoff to another session, info({ git_dir }) then sprint_resume({ git_dir }) restores exactly what was done, what is open, and what is blocked. A todo list is gone.
• You need to not fool yourself about "done". item_done refuses without a commit that actually resolves in the repo, and Sprinty runs the item's gates itself rather than taking your word for it. You cannot check the box on work that is not really finished.
• A human wants to watch without interrupting you. sprint_new returns a live dashboard URL.
• The record has to be auditable. The ledger is append-only, and search({ pattern }) queries it.

Cost is real: items need a title, description, code locations, and gates, and closing needs a changelog and coverage. Pay it for multi-commit or multi-session work. Skip it for a one-line fix.

Loop

1. Orient before binding. Call info({ git_dir }) for the default <git_dir>/.sprinty ledger directory, info({ data_dir }) for an explicit ledger directory, or info({ workspace_dirs: [...] }) for a compact workspace view. Resume with sprint_resume({ git_dir, data_dir? }). Start fresh only with sprint_new({ goal, git_dir, data_dir?, context_notes }).
2. Share the dashboard URL returned by sprint_new({}) or sprint_resume({}). Use dashboard_info({}) to re-read it, dashboard_restart({}) to refresh it, overview({}) for compact orientation, and next({}) for the active work window.
3. Create feature-sized subsprints with subsprint_new({ description, goals, gates, dependencies }).
4. Create atomic work with item_add({ subsprint, title, description, code_locations, gates, gate_timeout_ms, dependencies, high_priority }). gate_timeout_ms defaults to 5000; use a positive integer to customize it or null to disable it. If the work is too large, make more items; do not hide scope in notes.
5. Claim before changing code: item_claim({ id }). The connection remembers your identity and claim generation. No token or name is needed on ordinary calls; explicit tokens/generations remain available to advanced clients. Release claims when handing work back. Work against one owning item. Every item_update requires its item id and accepts only allowlisted fields. Use item_update({ id, gates, gate_timeout_ms }) to revise executable gate settings on an open or completed item before close, or item_update({ id, commit_id }) to correct a completed item's verified commit. New manual evidence cannot be added after completion. Structural fields stay immutable.
6. Resolve each item exactly once: item_done({ id, commit_id, changelog }), item_split({ id, description, goals, gates, dependencies }), or item_deprecate({ id, reason }). item_deprecate also accepts a subsprint id to drop a whole subsprint and its open items.
7. Use search({ pattern, context_size:512 }), *_list, and focused *_get tools when you need detail.
8. Optionally preview or export the current changelog with changelog({ path? }).
9. Close with sprint_close({ coverage:{ path, format:"lcov", command }, force? }); Sprinty rechecks gates using item-specific timeouts and writes the canonical changelog automatically. Use force:true only to record and bypass final executable-gate failures; it does not waive ledger or coverage requirements.