Agent Task Contract Framework

A portable installer for adding lightweight, repo-native task contracts to projects worked on by AI coding agents.

The framework was extracted from a production agent workflow and generalized for Codex, Cursor, Claude Code, Replit, and similar platforms. It gives agents a concrete contract file before substantial work begins: scope, out-of-scope items, blast radius, required reads, expected files, validation profile, stop conditions, risks, human decisions, and verification results.

What It Installs

• docs/agent-task.schema.json - strict JSON schema for task contracts.
• docs/agent-workflow-profiles.json - reusable validation profiles such as docs-only, frontend, backend, full-stack, mobile-native, infrastructure, and release-ops.
• docs/agent_tasks/INDEX.md - task contract registry.
• docs/AGENT_TASK_CONTRACTS.md - human and agent operating guide.
• scripts/check-agent-task-contracts.mjs - zero-dependency validator.
• Optional agent adapter docs for AGENTS.md, Codex, Cursor, Claude Code, and Replit-style agents.
• Optional PR-template fragment or safe .github/pull_request_template.md insertion for contract evidence.

Quick Start

Agent-first install

In an agentic coding chat inside the target project, paste:

Install https://github.com/leptoon/agent-task-contract-framework into this repository.

You do not need to add discovery instructions to the request. The install prompt in prompts/INSTALL_WITH_AGENT.md and the installer checklist make target-project discovery standard: agents should inspect existing docs and metadata first, infer answers from evidence and safe defaults, and ask only unresolved policy-changing questions.

Manual install

From this repository:

node bin/install.mjs --print-questions

Use the printed question list as a discovery checklist. Inspect the target repo's existing docs and metadata before asking a human for answers. If the answers are already present, create the answers JSON from those facts and run:

node bin/install.mjs --target C:/path/to/your/project --answers agent-task-framework.answers.local.json

Agents can also pass generated JSON through stdin with --answers -.

Integration modes

Use integrationMode to control how much existing repo policy is patched:

• standalone creates framework files and adapter fragments without touching existing agent/onboarding docs.
• append-marked-blocks appends or updates framework-owned marked blocks in the configured canonical agent entry and adapter docs.
• patch-existing-policy-files also patches .github/pull_request_template.md and composes an existing docs-check package script with scripts/check-agent-task-contracts.mjs when safe.

Use frameworkFileMode: "create-missing" for mature repos with existing custom framework files. Use frameworkFileMode: "overwrite" only when replacing generated framework files is intentional. The CLI --force is limited to generated framework files; existing policy files are still updated only through marked blocks or safe insertions.

Policy-heavy repos can customize schemaTitle, schemaId, changeTypes, and blastRadiusKeys, and can set seedInstallContract to create an initial contract recording the install decision.

Validate the installed framework:

node C:/path/to/your/project/scripts/check-agent-task-contracts.mjs

If the target project has package.json, the installer can add a script such as:

npm run agent:contracts:check

Agent-Driven Install

Use prompts/INSTALL_WITH_AGENT.md when asking Codex, Cursor, Claude Code, Replit, or another coding agent to install the framework. The prompt requires the agent to inspect existing target-project documentation first, infer as much as possible, and ask only unresolved policy-changing questions. A well-documented project may need no questions.

Recommended Project Policy

Use a task contract for substantial agent work, especially when a task touches:

• multiple repositories or packages,
• public API or shared contracts,
• database schema, migrations, or save formats,
• native/mobile code,
• infrastructure or deployment,
• generated assets or AI pipelines,
• broad documentation or workflow policy,
• more than one verification profile.

Small typo fixes, one-file docs changes, and narrow local bug fixes can skip a contract, but the PR should say why the work is not substantial.

Installed Workflow

1. Agent reads the project onboarding docs.
2. Agent checks docs/agent_tasks/INDEX.md.
3. If an accepted contract exists, the agent follows it.
4. If no accepted contract exists for substantial work, the agent drafts a proposed contract and waits for human acceptance before implementation.
5. Agent runs the validation profile and records results in the contract or PR body.

Local Smoke Test

npm run smoke
npm run test:mature-fixture
npm run test:portability

The smoke test installs the framework into tmp/smoke-target using examples/answers.json, then runs the generated validator. The mature fixture test exercises a repo shape with a canonical AGENT_START_HERE.md, existing PR template, existing docs-check script, custom schema taxonomy, companion-repository validation, and a seed install contract. The portability check fails if framework files reintroduce source-project product names, repo slugs, or domain-specific sample vocabulary.

Repository Layout

bin/install.mjs
templates/
  docs/
  scripts/
  agent-docs/
  .github/
prompts/INSTALL_WITH_AGENT.md
examples/

Notes

• The installer has no runtime dependencies beyond Node.js 18+.
• It is intentionally conservative: generated framework files are create-missing by default, existing policy files are preserved outside framework-owned marked blocks, and --force only allows generated framework-file overwrites.
• The validator does not require any task contracts to exist yet; a fresh install with an empty registry is valid.