Jeg har brugt mange mange timer på at raffinere en agent kontrakt, som gør det meget let at arbejde struktureret med en AI agent.

Kontrakten er maskin læsbar (json med sigende felt navn).

Nedenstående er en markdown "projektion" af json kontrakten.

Det gør kontrakten læsbar og forståelig for udviklere og AI agenter.

Nederst i hver kontrakt er altid en opsummerende forklaring målrettet 4 niveauer af forståelse.

Man kan finde mange opskrifter og lignende Skills og procedure-samlinger på nettet.

Jeg har valgt at bruge terminologien "Kontrakt" - og læner mig op af rfc2119 fordi det giver mening at følge årtiers erfaringer med hvordan man definere protokoller.

Selvsagt forventer jeg ikke at nogen - andre end mig - bruger min "agent_task_contract_v1" - alle kan selv definere deres egen - og næsten alle gør det.

---

GENERATED FILE — do not edit by hand.
Source: contract.json (related, prose.fields, instance_methods, governance, rules).
Regenerate: node scripts/generate-contract-projection.js --id agent_task_contract_v1

agent_task_contract_v1

Stability: draft

Summary: Machine-readable envelope for constrained AI- or human-led implementation: allowed paths, verification commands, evidence, and invariants. Paired JSON Schema: agent-task.schema.json. Validator: scripts/validate-agent-task.mjs.

Contract id: agent_task_contract_v1
Kind: governance (procedure; not a kernel or plugin runtime interface).
Purpose: Define a machine-readable envelope for bounded AI- or human-led implementation: scope, verification, and evidence. This contract does not define how a model reasons; it defines what may be edited, what must hold, and what must be reported.

No instance_methods.required.

Machine-checkable rules (rules[])

Role

agent_task_contract_v1 applies to out-of-tree task files (e.g. task.json) consumed by scripts/validate-agent-task.mjs and to contributors following those files. The provider side is the task author (writes the envelope). The consumer side is the implementer (human or tool) that executes within the envelope. The kernel’s plugin provider / consumer roles are not used for this document.

Normative principles

1. A task MUST declare a taskId.
2. A task MUST declare a human-readable goal.
3. A task MUST declare at least one allowed path prefix (allowedPaths).
4. A task MUST declare required verification commands (requiredCommands).
5. A task SHOULD declare targetContracts when work is contract-backed.
6. A task SHOULD declare targetPlugins when work affects specific plugins.
7. A task MUST declare forbiddenPaths when architectural risk exists.
8. A task MUST declare invariants for protected behavior.
9. A task MUST NOT allow silent contract changes; use allowContractChanges: true only with explicit review.
10. A task MUST require review evidence (see requiredEvidence and the catalog below).
11. A task MUST include postCompletion with commands (non-empty); every commands entry MUST appear in requiredCommands . Implementers MUST run those commands after coding and record results in evidence — scripts/validate-agent-task.mjs enforces the subset rule.
12. While completed is not true , postCompletion MUST contain only commands — MUST NOT include outcomeSummary , wisdom , caveats , or estimatePrecision (closure prefilling is forbidden).
13. When completed is true — work is 100% done — postCompletion MUST also include factual closure ( outcomeSummary , wisdom , caveats , estimatePrecision ) per scripts/validate-agent-task.mjs .
14. A task MUST NOT set stoppedAt until completed is true (real finish instant, same edit as closure — scripts/validate-agent-task.mjs).
15. When completed is true , startedAt and stoppedAt MUST both be present with stoppedAt ≥ startedAt .
16. When postCompletion.estimatePrecision is present, variancePercent MUST match 100 * (actualMinutes - estimatedMinutes) / estimatedMinutes (validator tolerance); estimatedMinutes MUST match estimatedDurationMinutes when both are set.
17. A task MUST declare bookkeeping : full (sole value) and estimatedDurationMinutes (integer ≥ 1) — enforced by agent-task.schema.json and scripts/validate-agent-task.mjs .
18. startedAt MUST be omitted until the edit that begins work — MUST NOT prefill wall-clock start on authored-but-not-started envelopes. When completed is true , startedAt , stoppedAt , and postCompletion.estimatePrecision are mandatory per scripts/validate-agent-task.mjs .

---

Task file JSON Schema

Concrete shape of a task file is defined by the sibling JSON Schema. Validate with node scripts/validate-agent-task.mjs <task.json>. The schema requires contractId, taskId, goal, allowedPaths, requiredCommands, postCompletion (with commands on every envelope), requiredEvidence, acceptanceCriteria, bookkeeping ( full only), and estimatedDurationMinutes . Optional: completed, extra postCompletion closure fields (only when completed is true), startedAt (omit until work begins; required when completed is true), stoppedAt (only when completed is true), targetContracts, targetPlugins, forbiddenPaths, forbiddenChanges, invariants, allowContractChanges, notes, and POSTMORTEM (array of non-empty strings — retrospective notes, e.g. production issues missed by tests).

Task envelope fields

Timing and estimates (estimatedDurationMinutes, startedAt, stoppedAt)

Authoring: set estimatedDurationMinutes on every envelope (integer ≥ 1). bookkeeping is full only.

Start: do not set startedAt until the same edit that begins implementation — never prefill on a task that has not started.

Finish: in the closure edit only — set completed : true , add factual postCompletion (including estimatePrecision ), and set stoppedAt to the real completion instant. startedAt must already be set from when work began. Never set stoppedAt or estimatePrecision early or as placeholders.

postCompletion.estimatePrecision: required when completed is true . Fields estimatedMinutes , actualMinutes , variancePercent where variancePercent = 100 * (actualMinutes - estimatedMinutes) / estimatedMinutes . When startedAt / stoppedAt are set, actualMinutes should match that span (validator tolerance). estimatedMinutes must match estimatedDurationMinutes .

Bookkeeping mode (bookkeeping)

Required: bookkeeping MUST be full (sole value; legacy removed).

Wall clock: estimatedDurationMinutes is required on every envelope. startedAt is omitted until the contributor begins work; stoppedAt and postCompletion.estimatePrecision are required when completed is true , with numeric consistency ( scripts/validate-agent-task.mjs ).

Required evidence items (requiredEvidence values)

Each string in requiredEvidence should be one of: changedFiles, commandsRun, commandResults, contractsTouched, pluginsTouched, riskNotes, deviations (as enforced by validate-agent-task.mjs).

Completion semantics

A task is done only when: the work stayed inside allowedPaths; forbiddenPaths were not changed; postCompletion.commands were run after coding and every requiredCommands entry passed; invariants were preserved; requiredEvidence was produced; deviations were disclosed; completed is true ; and postCompletion records factual closure (see below).

Post-completion record (postCompletion)

Always: include postCompletion.commands — non-empty list of shell-ready commands (e.g. npm run check:file-size, targeted test scripts) that must run after coding. Each string MUST appear verbatim in requiredCommands ( scripts/validate-agent-task.mjs enforces the subset rule). requiredCommands remains the full closure gate (may include task self-validation and other checks).

While work is open: postCompletion MUST contain only commands — never prefill outcomeSummary , wisdom , caveats , or estimatePrecision .

When the task is 100% done (same edit as completed : true ): add factual closure:

Rule: Open envelopes: postCompletion has commands only. Closed envelopes: postCompletion must include closure fields and be valid (scripts/validate-agent-task.mjs).

Failure semantics

If completion would require violating the task envelope, the contributor MUST stop and report the need for an explicit envelope change instead of silently exceeding scope.

Explanation levels

Implementer

A task.json (or equivalent) is validated with node scripts/validate-agent-task.mjs against agent-task.schema.json . The envelope must include bookkeeping : full (only value), estimatedDurationMinutes , and postCompletion.commands (each entry also in requiredCommands ). startedAt is omitted until work begins; closure requires startedAt , stoppedAt , and estimatePrecision . It lists allowedPaths , forbiddenPaths , requiredCommands , and requiredEvidence . postCompletion closure fields appear only when completed is true . POSTMORTEM is an optional array of retrospective strings (e.g. issues found after closure). contractId must be agent_task_contract_v1 . This contract is not registered in the kernel; it governs out-of-repo or procedural task files.

Governance

Task envelopes make scope and evidence explicit for AI-assisted or vendor work: you can see what was allowed to change, which verification ran, and what risks were noted. No silent edits to docs/contracts/** without allowContractChanges: true and review—reduces undetected contract drift and supports audit narratives.

Plain

Before an assistant edits the codebase, you write a small JSON “permission slip”: which folders it may touch, which commands it must run to prove the change, and what evidence it must report back. If the work does not fit the slip, you update the slip first—you do not sneak in extra edits.

Child

Like a treasure map for building with blocks: the map says which table you may use, which box is off-limits, and what photo to take when you are done. If you need a different table, you draw a new map and ask a grown-up— you do not quietly move to another table.