olliecrow/checkpoint

checkpoint

Multi-agent collaboration

• Default to using subagents when they are likely to improve speed, quality, confidence, or keep the main context clean.
• Use subagents to widen coverage, dig deeper on one thread, get a fresh second opinion, or keep the main thread clean while side work runs.
• Split work into clear packets with owners, inputs, acceptance checks, and a synthesis step when parallelizing.
• Keep the main agent focused on synthesis, unblockers, and the next critical-path step; let subagents handle bounded side work that can run in parallel.
• Use single-agent execution only when scope is small or coordination overhead outweighs gains.

Proactive autonomy and knowledge compounding

• Be proactive: immediately take the next highest-value in-scope action when it is clear.
• Default to autonomous execution: do not pause for confirmation between normal in-scope steps.
• Request user input only when absolutely necessary: ambiguous requirements, material risk tradeoffs, missing required data/access, or destructive/irreversible actions outside policy.
• If blocked by command/tool/env failures, attempt high-confidence fallbacks autonomously before escalating (for example rg -> find/grep, python -> python3, alternate repo-native scripts).
• When the workflow uses plan/, ensure required plan directories exist before reading/writing them (create when edits are allowed; otherwise use an in-memory fallback and call it out).
• Treat transient external failures (network/SSH/remote APIs/timeouts) as retryable by default: run bounded retries with backoff and capture failure evidence before concluding blocked.
• On repeated invocations for the same objective, resume from prior findings/artifacts and prioritize net-new progress over rerunning identical work unless verification requires reruns.
• Drive work to complete outcomes with verification, not partial handoffs.
• Treat iterative execution as the default for non-trivial work; run adaptive loop passes. Example loops (adapt as needed, not rigid): issue-resolution investigate -> plan -> fix -> verify -> battletest -> organise-docs -> git-commit -> re-review; cleanup scan -> prioritize -> clean -> verify -> re-scan; docs audit -> update -> verify -> re-audit.
• Keep looping until actual completion criteria are met: no actionable in-scope items remain, verification is green, and confidence is high.
• Run organise-docs frequently during execution to capture durable decisions and learnings, not only at the end.
• Create small checkpoint commits frequently with git-commit when changes are commit-eligible, checks are green, and repo policy permits commits.
• Never squash commits; always use merge commits when integrating branches.
• Prefer simplification over added complexity: aggressively remove bloat, redundancy, and over-engineering while preserving correctness.
• When you touch code, leave the touched area in a better state than you found it: clearer, simpler, tidier, and at least as performant unless the task requires an explicit trade-off.
• Before finishing any non-trivial task or pass, run at least one explicit consolidation pass across the touched code, docs, notes, tests, and configs.
• Use that pass to merge toward one clear source of truth, remove stale or duplicate material, and resolve contradictions before you declare the work complete.
• Do this by default as part of normal completion, even when the user did not explicitly ask for cleanup, consolidation, or contradiction resolution.
• Use simple, plain English in user messages, docs, notes, reports, code comments, and other explanatory writing. Avoid jargon, fancy wording, and complex phrasing. When a technical term is needed for correctness, explain it in simple words the first time. Default to short user-facing responses. Think about what the user most wants to know, and lead with that. Do not dump every detail by default. Always include important changes, blockers, verification gaps, and any important assumptions, nuances, principles, or decisions that shaped the work. Add more detail only when the user asks for it or when uncertainty or risk makes it necessary.
• Compound knowledge continuously: keep docs/ accurate and up to date, and promote durable learnings and decisions from work into docs.

Long-task checkpoint cadence

• For any non-trivial task (including long efforts), run recurring checkpoint cycles instead of waiting for a single end-of-task wrap-up.
• At each meaningful milestone with commit-eligible changes, and at least once per major phase, invoke git-commit to create a small logical checkpoint commit once relevant checks are green and repo policy permits commits.
• At the same cadence, invoke organise-docs whenever durable learnings/decisions appear, and prune stale plan/ scratch artifacts.
• If either checkpoint is blocked (for example failing checks or low-confidence documentation), resolve or record the blocker immediately and retry before expanding scope.

Terminal state contract (must follow)

The skill is complete only when all of the following are true:

• Objective completion: checkpoint intent is resolved as done or blocked.
• Cycle completion: organise-docs, git-commit, and git-push-safe are each resolved as done, blocked, or not-applicable (for example push skipped when no remote exists).
• Step-level terminal completion: each cycle step has explicit completion evidence (artifacts/check output/rationale) before advancing.
• Verification completion: required checks from delegated skills are executed, or unavailable checks are explicitly called out with impact.
• Reporting completion: output explicitly lists what was documented, committed, pushed/skipped, and any blockers.

Stop only after this terminal contract is satisfied; otherwise continue iterating.

Terminal state examples (adapt to skill)

• done: organise-docs, git-commit, and (when remote exists) git-push-safe all complete with explicit reporting of documented, committed, and pushed outcomes.
• blocked: a required checkpoint stage cannot complete after bounded retries (for example persistent failing checks before commit, or push auth failure); blocker evidence and exact unblock action are reported.
• not-applicable: push stage is explicitly marked not-applicable when no remote is configured.

Overview

This is a thin wrapper skill for the standard checkpoint cycle used in long or multi-step tasks:

1. run organise-docs to promote durable knowledge, then
2. run git-commit to checkpoint verified changes (including required pre-commit/tests/CI checks), then
3. run git-push-safe to push only when repository policy allows push.

Trigger phrases

Use this skill when the user asks for:

• checkpoint
• commit/docs checkpoint
• organise docs and commit
• organise docs commit and push
• run milestone checkpoint
• do docs + commit + push now

If the request is the combined docs-promotion and commit cycle, prefer checkpoint over invoking both skills separately.

Prompt templates

Use these copy-paste templates:

• [$checkpoint] run docs promotion + small logical commits for work completed so far.
• [$checkpoint] milestone checkpoint now: organise durable findings, commit verified changes, then push if remote exists.
• [$checkpoint] run one checkpoint cycle and report what was documented, committed, and pushed.

Workflow

1. Load and follow ../organise-docs/SKILL.md.
2. Promote durable findings/decisions and keep plan/ scratch uncommitted.
3. If that docs pass surfaces duplicate or contradictory material in scope, resolve it before committing.
4. Load and follow ../git-commit/SKILL.md.
5. Commit in small logical units only after pre-commit checks, relevant tests, and CI checks pass.
6. Load and follow ../git-push-safe/SKILL.md.
7. Push only when the repository is not local-only by policy and a remote push is allowed; if the repo is local-only, skip push and report that push was intentionally not applicable.
8. If there is any mismatch, prefer canonical organise-docs, git-commit, and git-push-safe instructions.

Skill composition

When this skill is triggered, compose other skills as needed:

• Use organise-docs first to promote durable rationale, decisions, and workflow knowledge before any commit is made.
• Use git-commit second to create the checkpoint commit only after the relevant docs updates and required validations are in place.
• Use git-push-safe last when repo policy permits push and the checkpoint commit is ready to leave the local machine.

If there is a conflict, the canonical delegated skills win: this wrapper exists to enforce sequence and reporting, not to override organise-docs, git-commit, or git-push-safe.