Risk classes and routes
Every piece of work gets a class from its risk — what it could break and how hard that is to undo — never from how much typing it takes. The class decides the route.
Risk sets the floor. A one-line change to authentication is never T0. When work turns out bigger
than it looked, the agent re-classifies it and runs the stages the new class requires.
At a human gate the agent shows you the document itself — the design, and for T4 the
specification and the alternatives — word for word, with its own objections after it. It records
what you decided and does not implement until you approve. A summary is never what gets approved.
Every route ends in consolidation, even a typo fix: the task decides what the project should
remember, and records “nothing” explicitly when that is the answer.
Project knowledge
.ai/knowledge/ holds what an agent must know to change the project well — the why that the code
cannot say. It is committed with the code and reviewed in pull requests.
Only what is relevant reaches the agent
An agent never reads all of it. Each document declares in a few lines of metadata where it applies — file paths, domains, topics, stages — and the agent asks Jig for what applies to the files it is about to change. The answer comes in two parts:- required — documents the agent must read, because they govern the files or the stage;
- catalog — one line per other document that may matter: the documents of the domains the work is in, and every project-wide document. The agent opens one when it decides it is relevant.
Proposed knowledge waits for a human
Knowledge an agent inferred — a domain map, a linked document, a copied rule file — is created as proposed. It sits at its real path and shows in the diff, but no agent receives it until a human accepts it. Rejecting records the decision rather than deleting the document. Knowledge an agent writes at the end of a task is reviewed in the pull request like the code.Knowledge that drifted
Each document records when it was last reconciled with the code. When the files it describes changed after that, it is reported as stale; when a linked document of your own changed since it was approved,jig status says so until a human has looked at the change.
Specifications
A specification is a plan for work bigger than one task — a feature of tens of tasks, or a new project. It lives in.ai/specs/<id>/: the idea, the stress test it went through, the decisions,
open questions, and a roadmap of phases and items. It is committed and reviewed like any file, but it
is not knowledge: no agent working on the code reads tomorrow’s plan as a description of today’s
system. Its progress is its roadmap’s checkboxes, checked by the tasks that deliver the items.
Epics
A specification whose phases give a user nothing on their own is released once, at the end. It gets an epic branch: its tasks branch from the epic and their pull requests go into it, and the main branch receives the whole feature in one pull request. Finishing the epic lists what is still open in the specification and asks about each item before the specification is retired.Cleanup
Task workspaces are temporary and are cleaned up without anyone remembering to:- a task whose change was merged is flagged until it is closed; once closed, its workspace moves to
.ai/runtime/trash/, and is deleted from there after a retention period (7 days by default); - a task whose remote state cannot be determined keeps its workspace;
- an abandoned task’s workspace goes to the trash after 14 days, whatever its remote state;
- old active tasks are only reported, never deleted for their age.
Measurement
jig measure reports, when you ask:
- knowledge — how many documents, how many stale, unreviewed or without code to describe;
- process — how many tasks of each class, and how they ended;
- change — how big the change each class produced was.