# Resumable Implementation Contracts > Create repository-based execution contracts for multi-session implementation work, with stable task IDs, evidence, checkpoints, and exact resume state. - Skill: `clanker25/resumable-implementation-contracts` (Agent Skill) - Install (CLI): `npx skillmds@latest add clanker25/resumable-implementation-contracts` - Raw SKILL.md: https://api.skillmd.com/api/skills/clanker25/resumable-implementation-contracts/raw - Safety review: pending - Works with: Claude Code, Claude.ai, OpenAI Codex - Category: Productivity - Author: clanker25 (https://skillmd.com/u/clanker25) - Updated: 2026-09-21 - Page: https://skillmd.com/skills/clanker25/resumable-implementation-contracts --- # Resumable Implementation Contracts ## Overview Turn a large, mostly defined implementation request into a repository contract that a fresh agent can read, update, verify, and resume without reconstructing the project from chat history. Keep stable intent separate from mutable execution state, and require evidence before any task is called complete. This is a tool-neutral document pattern. It does not depend on, replace, or configure any agent platform's built-in goal, task, plan, or project feature. This skill fills the layer between planning and execution. It does not replace product discovery, detailed technical design, project-wide state governance, or retrospective auditing. ## When to Use This Skill Use it when work: - spans multiple sessions, agents, branches, or context windows; - has dependencies or acceptance criteria that must survive interruption; - needs an exact resume point rather than a narrative handoff; - can appear complete before runtime, artifact, UI, or test evidence exists; - must preserve partial work and unrelated repository changes. Skip it for a small task that can be completed and verified in one session. If requirements are still unsettled, resolve them before freezing the implementation contract. ## Reuse Existing Project Documents Inspect the repository before creating files. Reuse equivalent documents and the project's established names when their ownership is clear. For substantial multi-session work, the minimum logical document set is: | Document | Owns | Must not become | | --- | --- | --- | | `IMPLEMENTATION_CONTRACT.md` | stable intent, scope, tasks, acceptance, definition of done | a live activity log | | `TASKS.md` | current task/subtask status, dependencies, evidence links | a second copy of the contract | | `CHECKPOINT.md` | authoritative current position and exact next action | a vague progress summary | | `DECISIONS.md` | material decisions, alternatives, and reasons | a transcript | | `VALIDATION.md` | checks actually run, results, evidence, and unresolved gates | a list of planned tests | These may live together under `docs//` or follow an existing repo layout. An existing `GOAL.md`, specification, or execution brief may own the contract role; do not rename it or create parallel files solely to match this skill. ## Define Document Authority - Current owner instructions and applicable repository instructions govern authorization and scope. - `IMPLEMENTATION_CONTRACT.md`, or its existing repository equivalent, owns the implementation contract. Do not silently change it to fit the current code. - The working tree, branch, commit, produced artifacts, and executed checks are truth for implementation state. - The tracker files summarize that state; they do not override contrary evidence on disk. When documents and reality disagree, reconcile status from evidence while preserving the contract's intent. Escalate any conflict that would materially change scope, behavior, or acceptance. ## Write a Self-Contained Contract A new agent should be able to understand the work from the contract without the original conversation. Include only what is needed to execute correctly: 1. objective and observable outcomes; 2. current baseline and important constraints; 3. in-scope work, exclusions, and authorization boundaries; 4. operating rules, including interruption and validation policy; 5. tasks with stable IDs, dependencies, acceptance, and breakpoints; 6. final definition of done and handoff requirements. Use stable task and subtask IDs such as `T03` and `T03.2`. Never renumber them after execution starts; add new IDs or mark obsolete work explicitly. Each task should use this compact form: ```markdown ### T03 - - [ ] T03.1 - [ ] T03.2 Dependencies: T01 Acceptance: - - Breakpoint: - Update TASKS.md, VALIDATION.md, and CHECKPOINT.md after the accepted slice. ``` Write acceptance in pass/fail terms. File creation, code presence, or an agent's completion claim is not acceptance unless that is genuinely the whole requirement. ## Read Before Acting At the start of a session or after interruption, read in this order: 1. applicable repository instructions; 2. the implementation contract; 3. `TASKS.md`, `CHECKPOINT.md`, `DECISIONS.md`, and `VALIDATION.md`; 4. current branch, `HEAD`, status, and relevant diff; 5. only the code, tests, and artifacts needed for the active task. Reconcile the checkpoint with the working tree before editing. Preserve partial and unrelated changes. Resume the exact unfinished subtask when it is still valid; otherwise record why the next action changed. ## Keep Writes Narrow and Durable - Change the implementation contract only when the owner changes intent or an ambiguity is deliberately resolved. - Update `TASKS.md` when work starts, blocks, or becomes evidence-backed done. - Replace `CHECKPOINT.md` with the latest authoritative resume state; Git owns its detailed history. - Add to `DECISIONS.md` only for choices that constrain later work. - Add to `VALIDATION.md` only after a check is actually run or explicitly recorded as not run. - Update the checkpoint after a meaningful increment and before stopping. Do not duplicate the same mutable status across every document. Link to the owning record instead. ## Use Evidence-Gated Status Use a small status vocabulary: `pending`, `in_progress`, `blocked`, and `done`. A task may become `done` only when its acceptance criteria have supporting evidence. For each validation record, capture: - timestamp and relevant commit or working-tree state; - exact command or manual procedure; - environment when it affects the result; - result, including failures and skipped checks; - artifact, log, screenshot, route, or report path when applicable; - unresolved caveats or gates. Run the smallest check that proves the current slice during implementation. Run broader integration or release suites at defined milestones or when the change's risk requires them. Never present a planned, mocked, or nominally successful check as observed behavior. ## Make the Checkpoint Executable `CHECKPOINT.md` must let another agent continue immediately. Record: ```markdown # Checkpoint Updated: Branch / HEAD: / Active task: T03 Active subtask: T03.2 Status: in_progress Completed behavior: - Work in progress: - Validation performed: - `` -> Blockers or uncertainties: - Pre-existing or unrelated changes: - Next exact action: - Next verification: - ``` Avoid next steps such as "continue implementation" or "finish tests." If the next agent must decide what those words mean, the checkpoint is incomplete. ## Execution Loop 1. Select the smallest dependency-ready task. 2. Mark it `in_progress` and state the intended slice. 3. Inspect the real path that owns the behavior. 4. Make the minimum scoped change. 5. Run focused verification and record the actual outcome. 6. Update task status only from that evidence. 7. Refresh the checkpoint with one exact next action. 8. Repeat until every definition-of-done item is verified or explicitly blocked. At final handoff, report completed outcomes, evidence, unresolved blockers, branch and commit state, and the exact next action if anything remains. Do not promote partial task completion into overall contract completion. ## Limitations - This structure preserves execution state but cannot resolve unclear product intent or choose among materially different outcomes for the owner. - Evidence quality depends on running checks that exercise the real behavior; complete-looking documents do not prove implementation correctness. - Concurrent writers still need repository-level coordination to avoid conflicting checkpoints and status updates. - The five-document layout is unnecessary overhead for small, single-session tasks; reuse fewer existing documents when they provide the same ownership. ## Common Failure Modes - Rewriting or renumbering task IDs after work has begun. - Treating checked boxes as evidence instead of linking the proof. - Recording only happy-path checks and losing failed attempts that constrain the next decision. - Replaying all history instead of loading the authoritative current state. - Allowing implementation discoveries to silently expand the contract. - Running an expensive full suite after every small edit while skipping the focused check that would isolate the defect. - Persisting credentials, tokens, private data, or sensitive command output in tracking documents. ## Relationship to Other Skills - Use `spec-driven-loop` when product requirements and technical design still need structured discovery, freezing, and approval. - Use `planning-and-task-breakdown` when only an executable plan is needed. - Use `project-state-governor` when the need is canonical state across the whole project rather than one scoped implementation effort. - Use `audit-agent-run-evidence` for a read-only retrospective audit of an already completed run. This skill owns the compact execution contract that connects those concerns: stable intent, mutable progress, verification evidence, and exact resume state.