agent task contracts

Make Codex /goal know what done means.

/goal keeps Codex moving. intentfile defines done.

Use a tiny .intent.yaml contract to give agents the objective, boundaries, acceptance criteria, and proof required before they can call a task complete.

codex goal bridge

Persistence is not the same as completion.

Codex /goal gives the agent a durable objective. An intentfile gives that objective an auditable stopping condition. 

npm run intent -- goal task.intent.yaml --target codex

copy this to your agent

Install the skill, verify the CLI, then work from intent.

Install and use intentfile in this workspace.

Repository: https://github.com/rishabhsai/intentfile

Tasks:
1. Clone the repo if it is not already present, then run npm install, npm run build, npm test, npm run typecheck, and npm audit.
2. Use the CLI through npm run intent -- from the repo. If global npm links are acceptable in this environment, run npm link -w packages/cli and verify intent --help.
3. If Codex-style local skills are supported, install the repo skill by copying skills/intentfile to ${CODEX_HOME:-$HOME/.codex}/skills/intentfile. If local skills are not supported, read skills/intentfile/SKILL.md and follow it as your operating guide.
4. Read AGENTS.md, docs/AGENT_ONBOARDING.md, docs/CODEX_GOAL.md, spec/intentfile-v0.1.md, and examples/password-reset.intent.yaml.
5. Create or update a .intent.yaml for the task I give you, validate it, render a brief for the target agent, and if Codex /goal is available render a goal with npm run intent -- goal task.intent.yaml --target codex.
6. Treat the intent objective, constraints, acceptance, and proof_required as the definition of done. Require a .proof.yaml before calling the work done.
7. At the end, report the exact commands you ran, changed files, acceptance status, and any unresolved questions.

This prompt works before npm publish: agents can run the CLI from the cloned repo and install the repo-packaged skill locally when their runtime supports skills.

One file tells the agent what done means.

  • Objective is explicit.
  • Allowed and denied paths are visible.
  • Acceptance criteria are reviewable or machine-checkable.
  • Proof is required before the agent says done.
intent: intentfile/v0.1
id: intent_password_reset
title: Add password reset flow

objective: >
  Implement email-based password reset.

acceptance:
  - id: A1
    statement: Users can request a reset link.
  - id: A2
    command: npm test
    must_pass: true

proof_required:
  - changed_files
  - tests_run
  - acceptance_checklist

Spec.

v0.1 keeps the core small: objective, context, constraints, acceptance, deliverables, and required proof. The schema is strict about the fields that matter, while leaving room for tools to add metadata at the edges.

The verifier is conservative by design. It can check schemas, required proof fields, command results, file existence, and obvious path violations. It does not pretend to prove product correctness without tests.

read the spec codex goal workflow

CLI.

The first implementation ships as a TypeScript npm workspace with a core package and an intent binary.

intent init "Add password reset flow" intent validate password-reset.intent.yaml intent brief password-reset.intent.yaml --target codex intent goal password-reset.intent.yaml --target codex intent proof password-reset.intent.yaml --include-git intent verify password-reset.intent.yaml password-reset.proof.yaml

Proof.

Every completed intent should return a receipt: changed files, commands run, acceptance status, unresolved questions, risk notes, and links to commits or pull requests when available.

That proof can be checked in CI, attached to a pull request, or passed to another agent. 

proof: intentproof/v0.1
intent_id: intent_password_reset
status: completed

acceptance:
  A1:
    status: pass
    notes: Added reset request flow.
  A2:
    status: pass
    command: npm test

tests_run:
  - command: npm test
    status: passed

For agent builders.

Use AGENTS.md for standing repository instructions, llms.txt for discoverable context, and .intent.yaml for the single task being delegated. The files are meant to compose, not compete.

setup guide for AI agents