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.

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:

# Checkpoint

Updated: <UTC timestamp>
Branch / HEAD: <branch> / <commit>
Active task: T03
Active subtask: T03.2
Status: in_progress

Completed behavior:
- <verified result and evidence link>

Work in progress:
- <files and partial state that must be preserved>

Validation performed:
- `<exact command>` -> <result>

Blockers or uncertainties:
- <blocker, owner, and condition for clearing it>

Pre-existing or unrelated changes:
- <paths or explicit none observed>

Next exact action:
- <one concrete edit, inspection, or command>

Next verification:
- <focused check that should follow that action>

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.