---
name: agent-work-contracts
description: "Turn multi-step or delegated agent work into a bounded contract with concrete validation and a concise handoff."
---

# Agent work contracts

Use this before work that touches several files, needs investigation, or goes to another agent. Skip it for a one-file change with an obvious check.

A contract states what will change, how to check it, and when to stop. It is not a plan for a whole backlog.

## Resolve ambiguity first

If you cannot write one clear stop condition, ask one scoping question before making a contract. Do not choose between several plausible interpretations for the user.

## Write the contract

Fill in this form with facts from the repository, issue, or user request.

```markdown
**Objective:** <one concrete result>
**Read first:** <files, issue, or source of truth>
**Write scope:** <paths that may change>
**Constraints:** <what must not change; dependencies or scope boundaries>
**Approval:** <none, or action that needs confirmation>
**Validate:** `<exact command>` or <specific file, line, artifact, or observable output>
**Checkpoints:** <when to report or record progress>
**Stop when:** <verifiable completion condition>, or when <specific decision> is required
```

Keep it short.

- Write one objective and one stop condition. Do not turn a backlog into a contract.
- Use literal paths, issue numbers, and commands.
- Do not name a validation command until you confirm it exists. Inspect the project, CI configuration, or task runner first.
- State what must remain unchanged. Add limits like "no new dependencies" or "do not change public APIs" when they apply.
- When tests or evaluations define completion, add: "Do not delete, skip, weaken, or narrow tests to make the work pass."
- Treat a failed check as evidence. Fix it within the contract or stop for the decision named in it.

## Delegate with a bounded brief

Give a delegated task enough context to make progress without letting it drift.

```text
**Objective:** <one outcome>
**Read first:** <specific files or issue>
**Write scope:** <paths the agent may change>
**Constraints:** <invariants and out-of-scope work>
**Validate:** `<exact command>`
**Return:** changed files, validation result, and the handoff below
```

Do not use delegation to discover an unclear task. Investigate first, or ask the user one question.

## Leave a handoff

At a checkpoint, pause, or delegation boundary, leave only what the next person needs. Omit it when investigation and implementation happen in the same session with no pause or delegation boundary.

```text
## Handoff: <task>

**Objective:** <the agreed outcome>
**Current state:** <what changed or what was learned>
**Evidence:** <commands, tests, links, or observations and their result>
**Next smallest step:** <one action>
**Blocker / decision needed:** <none, or one specific question>
**Safety notes:** <pending external action or required approval; secret boundary; or none>
```

Keep handoffs factual. Do not include credentials, tokens, private prompts, or raw logs. Refer only to redacted or access-safe logs and links. Do not claim completion without validation evidence.

## Finish honestly

Before saying the work is done, check that:

1. The objective and stop condition are met.
2. The stated validation passed, or the report says why it could not run.
3. The final report separates evidence from assumptions.
4. Any external or destructive action still has the required approval.

---

This skill is published as an Agent Plugin for [Agent Skills](https://agentskills.io) / [Agent Plugins](https://agent-plugins.org) compatible agents: GitHub Copilot, Claude Code, Cursor, Codex, Gemini CLI, OpenClaw, and more.

**Install (any agent):**

```bash
gh skill install AndreaGriffiths11/agent-work-contracts agent-work-contracts --agent codex --scope user
```

Install is validated against the Agent Skills spec. For per-agent manual install paths, see the [repository README](https://github.com/AndreaGriffiths11/agent-work-contracts).