How Jig builds context for a task
Project knowledge is organized for selective reading. The agent does not need to load the whole handbook every time you ask for a change. Jig helps it find the rules and decisions that apply to the work in front of it, while keeping other relevant material discoverable. Think of a well-organized reference library: a few essential rules stay on the desk, the books needed for the task are opened, and a short catalog points to anything else worth checking.1
Keep the shared foundations
The project’s glossary, architecture, and core rules are always required. A focused task
still needs to respect the whole project’s basic constraints.
2
Find what applies to this task
The agent identifies the files and areas it is working on. Jig uses document metadata to
select the knowledge required for those files, topics, and the current stage of work.
If a selected document depends on another, that document is included too.
3
Read the essentials; browse the rest when needed
Jig returns paths to the required documents and a compact catalog of other potentially
relevant material. The agent reads the required documents and can open additional ones
from their catalog entries. Listing a document does not load its full text.
4
Update the selection as the work grows
When the agent reaches another part of the project or moves to a new stage, it asks for
context again. Newly relevant documents join the reading list. Documents changed since
the agent acknowledged reading them need another look.
An example: changing bookings
Suppose you ask: “Stop people booking a class that is already full.” With knowledge mapped to the relevant areas, the reading list could look like this:
If the work turns out to affect payments too, the agent expands the selection. It does not keep
working with a reading list that only covers bookings.
Why this can save tokens
Tokens are the pieces of text the AI processes. Loading fewer unrelated documents can use fewer input tokens and leave more context space for the task, its code, and the conversation. The catalog helps the agent discover additional knowledge without reading every document in full.This is selective loading of project knowledge, not a cap on everything the AI reads.
Conversation history, code, tool results, and instructions from the coding app also use context.
Savings depend on the task, document sizes, and the agent’s reading choices; Jig does not measure
token savings or promise a percentage.
For developers: selection rules, stages, and reading records
For developers: selection rules, stages, and reading records
jig context resolve selects documents deterministically from metadata. It makes no AI call
and returns paths for the agent to read, rather than injecting document bodies into the model.The catalog also includes active project-wide documents with neither paths nor domains.
Proposed and retired knowledge is excluded from normal resolution. A directory name alone
does not decide applicability: the document’s metadata does.Stage selection is additive.
--stage can bring in additional guidance for the stage;
it never removes required globals, existing matches, or dependencies to make the context smaller.
load: stage is the author’s own choice for one document — a rule that belongs to
consolidation, say — and changes nothing for any other document. An explicit ID or another
document’s requires still brings it in at any stage.
--ids explicitly selects a catalog document when the agent needs its full content.For example, in Jig’s own repository, inspect what an edit to the introduction requires:context acknowledge records the hashes of documents the agent
says it read. context pending identifies required documents that are new or changed;
context guard fails while any remain unacknowledged, naming why each is required, and when it
passes says at which stage the acknowledgements it took were made. Unchanged documents keep their
record across stages; context acknowledge --revoke withdraws one. This records a reading claim, not comprehension or continued presence in the
model’s context; it does not replace a handoff when an agent session changes.See Manual control for task-based commands and
Under the hood for the limits of these records.Risk classes and routes
Every piece of work gets a class from its risk — what a mistake would cost and how hard it is to undo — never from how much typing it takes. The class decides the route. The class comes from three questions, asked about this change being wrong after it shipped:- What takes it back? A revert is cheap. Data already changed, mail already sent, money already moved, another system already told — there is nothing to revert.
- How far does the mistake reach? Does it stop with your repository, or reach your users, your money, or somebody else’s system?
- Who finds it? A test and the next run, or the person it hurt? Silent corruption costs more than a loud outage.
Day to day that usually means: wording and formatting are T0; a contained fix inside one module is
T1; a refactor across files, or a signature other code relies on, is T2; a new boundary, dependency
or data shape is T3. Those are illustrations of the answers above, not a list to match against —
work that appears in none of them still has a class.
T4 is the class most often missed, because the work rarely sounds dangerous. Authentication,
secrets, irreversible data operations, migrations on live data, money and billing are the obvious
half. The other half is not: a mass send of email or notifications, a change to who can see what, a
write into somebody else’s system, a job that walks a whole table in the background, a scheduler
entry that repeats the mistake on its own, a storage format with no way back. What they have in
common is not a subject area — it is that the mistake has left the machine.
The word is not the test. Reading any of the above is not T4: a report over payments, a query
against live data. Neither is a change behind a flag that is off, a test fixture, or a rename in a
file that happens to be called
auth. Ask what a mistake would cost, not what the file is named.
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; when it is
unsure what a mistake would cost, it takes the higher class: a review nobody needed costs less than
a change nobody can undo.
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.
A review is a second reader. Every review in a route — T2’s review, T3’s architecture review,
T4’s independent review — is done by a helper agent that never saw the code being written: it gets
the task and the design, not the author’s account of what was done, and each repeat review is a new
helper. For T4 the review goes further. It runs on another model or tool when you have set one up
(Autopilot: helpers on another model), and otherwise the
pull request says it ran on the same model as the code. Every acceptance criterion needs evidence,
and every serious problem the agent says it fixed is checked by undoing the fix and watching its
test fail.
A code review reads two things, with two readers. T2’s review and T4’s independent review are
done by two helpers in turn, each reading only its own side. The first asks about behaviour: does
the change do what was asked, which input breaks it, and can a guarantee the feature makes be
walked around through some other path in the code. The second asks about standards: every rule
your project wrote down — its decisions, AGENTS.md, CLAUDE.md, CONTRIBUTING.md, linter
settings — checked one by one against the change, plus a short list of well-known code smells
(duplicated code, a misleading name, an abstraction nobody uses yet) that every project gets even
with no rules of its own. A smell is only ever a small finding and never stops the task, and a rule
your project wrote wins over it. A repeat review of a small fix uses one helper for both.
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.
A lighter route
The routes above are the full ones. If your time and tokens matter more to you than a second look at low-risk details, you can ask for a lean route — for all your tasks with the personal settingroute.depth: lean (Configuration), or for one task by saying so (“do this one
lean”, which files it with jig task new <id> --lean). Lean trims only what does not change the
risk assessment:
Lean never trims the tests on the files you changed, CI before a merge, consolidation, a blocking
finding’s re-review, or the class itself: a risky change stays risky however little time you have.
jig task route <task-id> prints the route a task will run, and jig status marks a lean task
with depth=lean. Your setting is yours alone — putting it in the project’s file does nothing.
What a review leaves behind
A review does not end in an opinion. It ends in two records that the rest of the route has to get past. Findings — each problem the review found, written down with a severity: P0 breaks data, security or a rule or decision the project recorded; P1 gives a wrong result on a path that will be used; P2 and P3 are worth fixing but do not block. A P0 or P1 stops the task mechanically: while one is open the agent cannot mark the task ready, cannot record what the project should remember, and cannot commit or open the pull request. A fix alone does not clear it — a second review confirms the fix, reading only what changed since the first review when it can. A P3 is never fixed after the review: it is listed in the pull request. The other way out is a decision that it need not be fixed, and for a P0 or P1 that decision is a human’s. The receipt — what the review actually read: the task’s own change, the project knowledge that applies to it, the approved design, the list of findings. If any of it changes afterwards, the review no longer describes the change, and the task stops again until it has been reviewed once more. A T4 task cannot be finished without a receipt at all. Both are what keeps “reviewed” from meaning “someone said it was fine earlier” (Working with tasks).How far the agent goes
Whether a finished task stays in your working tree or arrives as an open pull request is a setting,agent.git, with five levels: none, commit, push, pr, merge. It is
personal: it lives in a gitignored file, it changes what your agent does in your copy of
the project, and putting it in the shared file does nothing — one person’s trust can never be
switched on for the whole team.
The levels are enforced by a script rather than by the agent’s good intentions: jig task ship
commits the task’s change — what you staged, or with nothing staged the changes to tracked files,
never a new file you did not stage — never force-pushes, never skips your Git hooks, refuses before
the task’s knowledge decision is recorded, and merges only at merge, only on green checks,
and never past your repository’s own branch protection
(Letting the agent ship).
Where a finished task goes
Every project has a flow, chosen once for the whole team in.ai/config.yaml. In the
direct flow, the default, a task’s pull request goes into the main branch. In the staging
flow it goes into a shared staging branch first and waits there, parked, while it is tested;
when someone says “prepare for prod”, a second pull request takes exactly the tested commits of
that task into the main branch. Each task travels on its own, so one that failed its test holds
up nobody else (Test on staging first).
Running without you
The routes above assume you are there between stages. Two things change that. Autopilot runs one task’s route end to end without waiting: same stages, same gates, same rules. Two differences — the review is done by a second agent, which did not write the code, and fixing is capped at two attempts per run, after which Jig itself refuses a third and the run stops rather than circling. A run stops only where a human is genuinely needed: a design to approve, a problem it could not fix, a decision nobody has made, a step that would destroy something. It ends with a report of every stage, every repair and every stop (Autopilot). Unattended is for when those questions are not yours to answer. Where a run would stop, it takes the careful, reversible option instead and writes down in the pull request exactly what it chose without you; where it could not finish, it opens a draft pull request that says so. It never dismisses a serious finding, never skips the review, and merges only what your CI proved (without stops). A run can also take a whole phase of a roadmap instead of one task. The agent becomes a coordinator: it files the phase’s wave of items, gives each task its own worktree and its own agent, and those agents build at the same time while the coordinator ships them, keeps the merge queue and starts the next wave. It writes no code itself. This is the one place Jig runs several agents at once, and it needs an epic branch and the right to open pull requests (running a whole phase).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
The agent uses the context selection process above to find what it needs. The three global documents remain required; other documents are selected through their metadata or discovered in the catalog. As the task’s scope changes, the selection grows with it. This structure is what makes project knowledge usable without loading the whole library.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; an
item whose task is known to have merged counts as done before its checkbox reaches your branch.
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 closed without ever being started (no branch, as a findings task closed by decision, once its source task’s workspace is gone) goes to the same trash: it has no change whose merge could be in doubt;
- a task whose remote state cannot be determined keeps its workspace;
- an abandoned task is archived after 14 days, whatever its remote state, and an active or ready
one nobody touched for 60 days is archived too: its workspace stays, without a time limit, and
jig task unarchivebrings it back; - no task is ever deleted for its 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.