define-task

name

define-task

description

Use BEFORE starting any medium or large task, including features, bug fixes, refactors, multi-file changes, branch/commit/push/PR/merge work, and anything touching production or staging, deploys, hosting, databases or migrations, auth, payments, or third-party integration config. Forces a preflight task contract (target, context, acceptance criteria, proof plan, constraints, stop conditions) and an explicit human checkpoint before implementation, so agents never define "done" for themselves.

Agent Task Contract

Use this skill before starting any medium or large task, especially work that involves code changes, branches, commits, PRs, production or staging, deploys, hosting, databases or migrations, auth, payments, third-party integration config, data cleanup, or cross-file refactors.

The purpose is to prevent vague delegation. Do not run off and implement a big task until the task has a clear target, context, acceptance criteria, proof plan, constraints, and stop conditions.

Why this exists

The same failure keeps recurring. The direction gets set well, and then the agent quietly fills in "done" for itself. Four shapes it takes:

• The deploy that was never a deploy. Files were pushed. The pipeline went green. Nothing shipped, because the changed files sat outside the deployed app's root and the build never looked at them. Every signal said success. The behavior never changed.
• The commit nobody wrote. During branch cleanup, an extra local commit appeared on the branch. It had to be hunted down and deleted before the history was safe to push. No human had decided to create it, and no human was told it existed.
• The unbroken run. Implement, commit, push, open the PR. Four actions, one autonomous stretch, no moment where a person saw the work before it became outward-facing. The broad direction had been approved. None of the four actions had.
• The live integration with no way back. A change went into a running third-party integration. It may well have been correct. Nobody could say what to do if it was not, because no rollback step was ever named, and nobody noticed that until it mattered.

Every one is the same gap: you acted before agreeing on what success, proof, and stop conditions were. This skill closes that gap.

When to trigger this skill

Trigger when the user, an issue assignment, or a task handed to you asks you to:

• Implement a feature
• Fix a bug
• Refactor code
• Touch multiple files
• Work in a worktree or branch
• Commit, push, open a PR, or merge
• Change anything touching production or staging, deploys, hosting, databases or migrations, auth, payments, or third-party integration config
• Continue a prior large task
• Execute an assignment carrying a task ID from your tracker
• Act as a specialized role agent within a multi-agent team

Do not trigger for trivial read-only questions, simple explanations, or one-command checks, unless that command can mutate state.

Core rule

Before implementation, produce a task contract.

If the prompt lacks required information, ask clarifying questions or propose a contract and wait for approval.

Do not silently invent the success criteria for a large task.

Required task contract

For any medium or large task, write this before coding. Fill every field; if a field is genuinely N/A, say so explicitly rather than leaving it blank.

TASK CONTRACT

Target:
- What user-facing or system behavior should change? (one or two sentences)

Context:
- Repo/worktree:
- Branch:
- Source of truth: an issue or task ID from your tracker, or a doc link

Acceptance criteria:
- Concrete, checkable conditions that mean "done" (not "it works")
- Each one should be something a reviewer could verify

Proof plan:
- How you will demonstrate each acceptance criterion (tests run, command output,
  screenshot, URL, log line, before/after)
- The actual command(s) you will run to prove it

Constraints:
- What you must NOT touch (files, branches, services, data)
- Budget/scope limits (time, file count, blast radius)
- Style/architecture rules that apply

Risk & rollback:
- What could break, and the blast radius (local / staging / prod / data)
- How to undo: the exact revert/rollback step
- Whether this is reversible at all

Stop conditions. Pause and ask before doing ANY of these:
- Pushing to a shared branch (staging/main) or force-pushing
- Opening or merging a PR
- Deploying to staging or prod
- Running a migration or mutating production/staging data
- Touching auth, payments, secrets, or third-party integration config
- Scope growing beyond the Target above
- Anything irreversible or outward-facing

How to use the contract

1. Draft it first. Before any edit, write the contract from what you know.
2. Fill the gaps. If Target, acceptance criteria, source of truth, or stop conditions are unclear, ask. Do not guess. A proposed contract awaiting approval is fine; silent assumptions are not.
3. Get the checkpoint. For anything with a stop condition in play (push, PR, deploy, migration, prod/staging, auth/payments), get explicit human approval before crossing it. "I set up the broad direction" is not approval for a specific irreversible action.
4. Execute within the contract. Stay inside Constraints. If reality forces you outside them, stop and re-contract. Do not expand scope silently.
5. Prove it. Close by running the Proof plan and reporting the actual output against each acceptance criterion. Report faithfully: if a criterion failed or a step was skipped, say so.

Checkpoint discipline

The single most important behavior: a visible human checkpoint before any irreversible or outward-facing action. Implementation, commit, push, and PR creation must not happen in one unbroken autonomous run when a stop condition applies. Surface the contract, name the stop condition you are about to cross, and wait.

If you are a role agent inside a multi-agent team, the contract and its checkpoint are what you report back to the coordinator, with your proof, not a fait accompli.