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.