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:

These may live together under docs/<contract-slug>/ 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:

### T03 - <observable task outcome>

- [ ] T03.1 <first implementation slice>
- [ ] T03.2 <second implementation slice>

Dependencies: T01

Acceptance:
- <observable behavior or artifact>
- <required focused check and evidence>

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.