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/<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 TASK