Task JSON as source of truth for agent work

Boards are useful, but they are not always the right source of truth for agent work.

A board is optimized for humans scanning state. A chat thread is optimized for conversation. An issue is often optimized for coordination. None of those automatically gives an agent a stable execution contract.

That is the role of Task JSON. It is a typed task artifact that sits close to the repo and describes the work in a format both humans and agents can inspect. The point is not love for JSON. The point is to stop losing the task between chat, tracker comments, Markdown notes, dashboards, and “I think we agreed.”

In an agentic workflow, the task needs a machine-readable source of truth. It should capture the current shape of the work:

• goal;
• non-goals;
• scope;
• accepted files or systems;
• expected artifacts;
• acceptance criteria;
• verification commands;
• evidence pointers;
• blockers;
• status;
• external projections.

That list looks bureaucratic until the second or third agent enters the loop. Then it becomes operational memory.

Without a canonical task artifact, every new agent starts by reconstructing meaning. It reads the latest prompt, an older issue, a partial board state, maybe a transcript, maybe a handoff. Each surface may be true in context, but the current contract is unclear. What was promised? What was cancelled? What was verified? Which files are off limits? What is done and what merely sounded done?

Task JSON reduces that ambiguity by separating the model from its projections.

The JSON is the canonical work item. A tracker issue, board card, Markdown summary, dashboard, or Telegram update can still exist, but those surfaces should point back to the task record. They are views for people and systems. They should not become five competing truths.

This matters most during recovery. When a session ends, the next agent should not need to perform archaeology in a chat scrollback. It should be able to open the task artifact and see what the work is trying to change, which surfaces are in scope, what counts as done, which checks matter, and where the latest evidence lives.

It also matters during GitOps. A commit proves source changed. It does not automatically prove the task status is honest, that external projections were updated, or that a failed check was recorded. A task artifact can hold the lifecycle state around the commit: planned, in progress, blocked, done, archived, and the evidence that justifies the state.

The practical design rule is simple: make the task strict enough for automation and readable enough for operators. If only machines can understand it, humans will bypass it. If it is only prose, agents will reinterpret it.

A useful Task JSON rail should support a few habits:

• validate the task shape before treating it as a contract;
• render human-readable projections from the JSON;
• keep evidence as paths or receipts instead of vague claims;
• record blockers explicitly;
• make status transitions visible;
• sync external trackers as projections when needed.

The artifact does not remove judgment. The operator can still change the plan. The point is that the current plan has a durable place to live, and changes to the plan can be made deliberately.

This is why I think Task JSON becomes more important as agents improve. Faster agents do not reduce the need for source of truth. They increase the penalty for not having one. Without a stable task contract, speed turns into drift. With one, the agent can move quickly while the operator still has a handle on scope, status, verification, and recovery.

“Done” should not be a feeling at the end of a persuasive transcript. It should be a state the workflow can inspect.