jig on your PATH; .ai/scripts/jig runs the project’s installed copy
explicitly. In PowerShell, use .ai\scripts\jig.cmd for that local copy.
Commands keep the records; the agent does the work. Creating a task in the terminal does
not start an AI session or write code. Return to your agent and ask it to continue the named task.
Inspect before changing anything
task list shows the tasks, and says how many are archived (jig task list --status archived lists them); task current looks for the task on this branch. When several match,
choose an explicit ID. status summarizes the project and doctor checks its setup.
A script can read the same task list as JSON with jig task list --json, a task’s documents with
jig task artifacts <id> --json and jig task artifact read <id> <kind> --json, the specs with
jig spec list --json, the queue with jig queue list --json, and what needs you with
jig status --json; see
Reading Jig as data.
To create the browser status file without opening a browser:
jig status --open to create and open it.
Read about the status page.
File a task, then start it
For this example, assume a contained change already classified as T1. Use the appropriate risk class for your actual work..ai/workspace/tasks/booking-message/task.md: the goal, scope, and what a correct result
looks like. Filing the task does not switch branches.
To give the goal as you file it, pass it as one line; it becomes the paragraph under ## Goal:
--from <file> instead.
Begin work separately:
jig queue next, below) is another task that outranks this one, the start
is refused and names that task. To start this one anyway, say why:
jig task start booking-message --out-of-order --reason "<why>". The reason is kept in the task’s
state and jig status shows it, so a start against the queue is never quiet. A task that is not in
the queue starts as it always did.
By default, this switches to a task branch from the project’s configured base. For a separate
working copy, use jig task start booking-message --worktree instead, then work in the directory
it prints. Tasks linked to a spec with an open epic start from that epic.
Starting looks at the goal first — the same paragraph jig task list --goals shows. When ## Goal
in task.md is empty or holds only the template’s comment, a T0–T2 task starts with a warning, and a
T3 or T4 task is refused until the goal is written: put it in task.md with
jig task artifact write booking-message task --from <file> and start again.
A new worktree also gets whatever vendor/, node_modules/ or .env your project’s profiles (and
worktree.carry) declare, and links to the folders
worktree.share names — see
carrying state into a worktree. Add --no-bootstrap
to skip that for this run, or repeat it later with jig task bootstrap booking-message. Then your
project’s own worktree.setup
runs, if it has one.
--share packages gives this one task the links to packages/ that worktree.share gives every
task; jig task bootstrap booking-message --share packages adds them to a task already running.
See sharing for one task.
Pause and resume
--stash to the pause command when you also need to put uncommitted work aside. Resume reports
what changed while the task was paused. Read that report before continuing.
Resume runs in any checkout, unless the pause stashed work: then run it where the task’s branch is
checked out (its worktree, if it has one), because that is where the stash is applied.
If the stashed work conflicts with what changed while the task was paused, resume leaves the
conflicts in your files and keeps the task paused. Resolve them, git add the files (or commit
them), and run jig task resume again: it remembers that the stash is already in your files, does
not apply it a second time, and ends the pause. The stash entry stays in git stash list either way.
When an agent is working on the task, on autopilot or in an ordinary session, ask it to pause
instead:
jig context resolve --task <id> --stage <stage>, the first step of every stage
skill. A stage without a skill of its own, such as a plan, reads none, so the request then waits for
the stage after it. The request waits until then, or until you cancel it. Resume as above, and start
a new session to continue.
Archive and unarchive
.ai/workspace/tasks/, and
its branch, worktree and pull request are not touched. You can archive an active, ready or abandoned
task. Housekeeping does the same for an abandoned task after housekeeping.abandoned_ttl and for an
idle one after housekeeping.stale_after. unarchive returns the task to the status it had.
If an archived task’s work is merged later anyway, housekeeping asks you to close it — but only for a
task that was archived unfinished. A task that was abandoned before it was archived, or absorbed into
another task, stays archived without a question: what happens to it was already decided.
Merge a task into another
booking-message are
copied, not moved, to absorbed/booking-message/ in the receiving task’s notes, and the receiver’s
task.md gets a section that names them. Without --partial the absorbed task is archived (reason
absorbed) and anything in the queue that waited on it waits on the receiver instead; the absorbed
task itself leaves the queue. jig task unarchive brings the task back, but not its queue place or
the queue waits that moved: put them back with jig queue set and jig queue depend. A merge can always be run again. With --partial the task stays open and both sides note
the overlap; the queue is left alone. The receiving task must be active or ready, and a merge that would make the
queue wait in a circle is refused before anything changes.
Jig does not touch your tracker. When the receiving task ships, its commit and pull request name the
absorbed tasks’ issues in an Absorbs: line, so the tracker’s own integration can link or close them.
Close a roadmap item for a task you gave up
jig task abandon does this by itself where it can; jig spec drop <task-id> is the same edit run
by hand, where Jig said it could not. It checks the roadmap item of a spec that names the abandoned
task and ends it with — dropped (<date>): <reason>, or — moved to <ref> (<date>): <reason> when
the task was moved elsewhere. Read about giving a task up.
The edit has to be made where the roadmap is current, so the command refuses in a checkout that is
not that place:
lands on <base>, which is not checked out here: the spec has an open epic, or the task was started from another branch, and the roadmap there is edited in a checkout of that branch. Run the command in one.- the task is not abandoned: abandon it first with
jig task abandon <id> --reason <text>. spec/<id> does not name <task>: the spec’s own branch, left from an earlier session, lacks the item the default branch has. Jig switches back to the default branch; merge it into the spec’s branch and run the command again.
Keep an idea’s draft
While you shape an idea with thejig-idea skill, the agent keeps a draft of the conversation on
disk, so a session that ends early loses one round and not the whole. You can read and manage drafts
yourself:
.ai/workspace/ideas/<id>/draft.md. It is ignored by git: it is not a spec, has
no branch, and jig task start and jig spec new do not see it. write takes --from <file>, or
- to read standard input, and refuses an empty draft. list shows each draft with where it is, how
long ago it was written and whether a spec of that id exists. rename is for an idea whose spec was
given another id, so that jig spec ship finds the draft. drop moves it to trash.
A draft stays until the specification of the same id is committed, when jig spec ship moves it to
trash, or until you drop it; housekeeping never removes one, whatever its age. In a clone with no main
checkout to find (made with --separate-git-dir, or the worktrees of a bare repository), drafts live
under <git-common-dir>/jig/ideas/, one place for every checkout. While a draft exists, jig status
prints drafts: 1 (jig spec draft list).
Order the work
0 (most urgent) to 5, and each number means
one thing, so that you and your agent set “bugs first” the same way:
Your agent gives a task a priority when it files it, and writes to the queue when you ask it to set
priorities; a number already there it changes only when asked.
--priority none takes the priority away. A task given a priority, or a new one, takes its place after the last item with the same or a more urgent number, so the order you read follows the numbers. A move places one item
before or after another, or with --top and --bottom at an end; an epic (epic:<spec-id>) is
ordered beside tasks, and the tasks built on it are ordered within it. A dependency always says why.
jig queue remove takes an item out, and jig queue undepend drops a dependency. A program
reads the queue with jig queue list --json (Reading Jig as data).
A task leaves the queue by itself when it is finished: closing, abandoning or archiving it takes its
entry out, and every jig housekeeping run takes out the entries of tasks that are finished or whose
workspace is gone. jig queue prune does the same on demand (--dry-run only says what would go).
Whatever waited on a closed task no longer waits: that dependency is met. A dependency on a task
that was abandoned or archived stays, because that work never landed: jig queue next names it
broken until you drop it with jig queue undepend. A task you bring back with jig task unarchive,
or by setting an abandoned task active again, is not in the queue any more: give it a priority again
with jig queue set.
To ask which task to take next, run jig queue next. It answers from the queue and from what Jig
already knows, over the network never, and changes nothing:
resume first: names the autopilot runs that stopped for a person and were answered
(jig task autopilot <id> answer): they resume on the next free slot before any new task starts,
most urgent first, then the one that stopped first. A stopped run holds no slot; slots: counts
autopilot.parallel against the runs that are on and not consolidated in the clone. A task that
depends on one whose run is stopped waits with its autopilot run is stopped, waiting for an answer or a free slot — jig status.
A task a watcher could not start now is never advised either, and is named as blocked: one whose autopilot run is stopped for a person or ended not merged (blocked by a stop of <id>), one whose task.md holds only the stub, with no goal under ## Goal yet, and a release’s notes task (release-notes-*), which raises the version and stays yours. A queue held only by such stops answers blocked, not none — the queue holds no task to take: next: none — blocked by a stop of <id> for a stopped or not-merged run, and next: none — blocked: <id> has no goal in its task.md yet or … raises the version, which stays a person's for a stub or a release.
Only a task that is active, not paused and not started yet is advised: what is started is listed on the in progress: line, since the advice is what to start. One waits while anything it depends
on, or the epic it is built on depends on, is not finished. A task is finished when it is closed
or jig housekeeping saw its pull request merged; an epic when its branch has landed. Among the
tasks that do not wait the lowest priority number goes first, with a task without one last; at the
same priority the place in the queue decides, a task on an epic taking its epic’s place. When no task can be taken it says why:
every queued task waits for a dependency, is taken by another session, is already in progress, is held by a stop, is paused, or there is none. A wait that can never end
(broken: the task it waits for was abandoned, archived or is gone) comes with the command that drops it;
one Jig cannot tell (unknown) with the one that may find out. The last line counts the active
tasks that are not in the queue. jig queue next --json gives the same answer to a program
(Reading Jig as data).
A task another session is already working on is not advised, even before it has a branch. Every
session that works a task — writes its documents, sets its state, enters a stage, starts it — leaves
a note of it for the whole clone, and jig queue next passes over a task whose newest note is
another session’s, naming it instead:
next: none — every queued task left is taken by another session. jig queue list prints the same line under the task. Your own session’s tasks are advised
as before, and reading, filing or ordering a task does not take it: that covers reading a task’s
documents, and writing the task document of a task that has no branch yet, which is how a task’s
goal is filed. Any other document before jig task start, and the task document of a task already
started, still take it. A note lapses after
checkout.busy_ttl (12 hours unless you set it), or at once when the runtime says the session ended:
in Claude Code, the SessionEnd hook calling bash "$CLAUDE_PROJECT_DIR"/.ai/scripts/jig-session-end-hook (a new
.claude/settings.json made by jig init has it; add it by hand to an existing one) marks that
session’s notes ended, and the readers skip them. To take over the task of a session that is gone
without it, just work on it — the newest note holds the task. This needs a runtime that names its sessions
(Claude Code does); a session without a name leaves no note and treats every note as another’s.
jig status shows each queued task’s place on its task line — queue=2/5 is second of five on its
level (the top, or the epic it is built on), priority=1 its priority — with what it waits for, and
a pause asked of it with its age, on the lines under it:
--out-of-order shows the task it went ahead of on
its line and the reason under it; the status page marks it “out of order” and its “Needs you” list
asks you to check the reason:
jig status also prints the first line jig queue next gives, after
the task lines, so the answer is where you already look (the status page shows it as “Next task”):
next: none — and the reason; jig queue next has the
lines under it. jig status only reads that answer, it does not work it out again.
jig context --task <id> gives the agent working on the task the same facts as queue: lines.
Without a queue, none of this appears and the output looks as it always has.
jig status reads, and never fetches, so what it says about origin is as of your last fetch. To bring
the clone up, run jig refresh: it fetches origin and fast-forwards the base branch to origin’s, and
nothing else moves. On a task branch your branch and files stay as they are; if you are on the base
branch itself, it fast-forwards there and stops where the change would overwrite your edits. It never
stashes or forces, says in a line why the base could not move, and closes the writes in Jig’s own tree
that are over. How a program uses it is in
Reading Jig as data.
In a project on the staging flow (git.flow: staging), jig status names the flow before the task
lines and says, on each task line, whether the task’s work is on the staging branch:
staging=behind means the task has commits of its own that are not on the staging branch yet, such
as a fix QA asked for; bringing the base branch into the task does not count. Jig reads this from
git each time, by the task’s branch, comparing it with origin’s staging branch — git fetch to see
what colleagues merged. When the flow cannot work, the line says so instead
(flow: staging, not usable: … (jig doctor)). jig housekeeping puts the same word in its report
(on staging: …, behind staging: …), and a task waiting on the staging branch is never archived
as stale. With git.staging_land: external, where your CI merges tasks into the staging branch and
no pull request goes there, this is how you see what CI landed: the same words, read the same way. On
the default direct flow none of this appears.
A shipped task that waits at the staging branch is parked, and it leaves the task lines for one
line of its own:
review waits for a review of its pull request into the staging branch — landing when its review is
approved (or git.staging_review is none) and you land it yourself (agent.git below merge) — and signal waits on the staging branch for “prepare for
prod”. jig task list marks it parked=signal. A parked task is not the current task, jig queue next does not offer it, and another task may start in the checkout it was landed from.
jig task resume <id> takes it back for a fix: it becomes active and appears among the tasks
again until its next jig task ship into the staging branch, verify included — at any
agent.git, also when that ship leaves the commit or the push to you.
signal is read from the staging branch as your checkout last fetched it. With
git.staging_land: external, a task you shipped is listed as an ordinary task — and stays your
current task — until a fetch (jig housekeeping, or git fetch) shows that CI merged it; with
pull requests there is no such gap, since the open pull request keeps it parked for review until
the housekeeping run that hears of the merge also fetches.
A task parked for the signal stays on that line however long it waits; once it has waited
git.staging_stale_after, the drift report below names it as well, since nobody promoted it.
The staging drift report
On the staging flowjig status and jig housekeeping also say where the staging branch drifts
from the base branch, a staging: line each:
- Waiting with no promotion. A task’s work has been on the staging branch for
git.staging_stale_after(14 days unless you set it) and no pull request into the base branch is open or merged for it. The days count from the commit that last brought its work onto the staging branch — the landing merge — so shipping a fix QA asked for starts them again. Every task branch counts, here or on origin, so a colleague’s task is named too — with(jig task promote <id>, from any checkout, or ask its owner): a task is promoted by its id from any checkout whoseagent.gitallows it, or from CI, workspace or not. - A promotion that conflicts. A promotion this checkout opened (
jig task promote) that the forge, at the last housekeeping run, called conflicting with the base branch. Running the command again names the files to resolve, and pushes the merge once you have resolved it. - Work no task owns. Your own commits on the staging branch that the base branch does not have,
that no task branch — yours or anyone’s on origin — holds, and that you have not marked as known:
something committed onto the staging branch directly, or a task whose branch was deleted before its
work reached the base branch. Yours means the author’s email or name is your git user’s (the one
git var GIT_AUTHOR_IDENTnames); a colleague’s commits are not named anywhere, not even injig status --json. Only what the staging branch has and the base branch does not counts, so a task whose promotion was merged with a merge commit and whose branch was deleted leaves nothing here; a squash-merged one still does (see Known issues).jig staging ack --dry-runlists exactly the commits counted, andjig staging ackmarks them as known in this clone (.ai/runtime/staging-acked, by content, so a rebase or cherry-pick on the staging branch keeps the mark): from then on the line counts only new ones.
jig status --json show the same facts as items. Jig takes nothing off the staging branch: what to
do with work on it stays your team’s call.
Inspect the change and its review
main with the task’s actual base from jig task show booking-message. The change inventory
includes committed and local changes; it does not prove that every change belongs to this task.
Findings and the receipt tell you what was reviewed and whether that review still matches the work.
A missing receipt can be expected before review or for a task whose route does not require one.
When the receipt is stale, --since-review shows what changed since the review, and whether a repeat
review may read only that (narrow) or must read everything (full, with the reason). An edit to
GLOSSARY.md, ARCHITECTURE.md or RULES.md alone keeps it narrow and shows that edit too; a
change to a document written for the task’s files, or to which documents apply to them, makes it full.
Ask which knowledge applies
--ids when needed. For an investigation without a task, pass explicit file selectors:
README.md with the actual paths you are investigating. To record documents you have
actually read, use jig context acknowledge; jig context guard checks that record and names
why each document it still asks for is owed (global, paths: skills/**, domains: knowledge):
--stage records at which stage a document was read, and a passing guard reports it — a guard run
for review that says none acknowledged at review passed on what the implementer read. A path may
be written as the guard prints it, with a leading ./, or as an absolute path inside the project.
--revoke withdraws an acknowledgement given by mistake.
How context works.
Review a colleague’s pull request
Thejig-pr-review skill drives this when you give it the link of a GitHub pull request
or a GitLab merge request. The installer and jig self-update place it for you as well as in each
project, so it works in a clone of any repository, with or without Jig. The commands are the same
ones you can run yourself, in your own checkout:
fetch takes the pull request’s head and base into refs of Jig’s own and a detached worktree beside
the repository, <git.worktree_root>/.pr-<n>, without touching your checkout. Read that tree; run
nothing in it. Its method: and show: lines name the review method and the rule for showing a
document in the Jig that ran it: the skill reads them there, not beside itself. draft checks the review against the format the skill keeps and prints it; give it a
file with --from to keep a new one. comments check places the draft on the forge’s own diff and
prints the review as it would be posted, with a hash. comments post posts only that version: it is
refused unless --shown carries the hash check printed, so what you read is what goes out.
A draft may rank its findings (from 0.44.0). A === levels block right after the summary names the
four severities, P0 to P3, one to a line and in the review’s language; each === comment P<n> <position> <path> then names its level and starts with a one-line title. comments check puts the
level’s colour (🔴 🟠 🟡 🟢) and a number before each comment, numbered by level with P0 first, and adds
to the summary a legend and the findings by level. A comment that cannot be placed on the diff moves
into the summary and keeps its number. All of it is part of the version you approve and the hash
covers it. A draft without a levels block is posted as before. Posting a ranked review has not yet
been checked on a live pull or merge request.
After the author pushes fixes:
followup reads your earlier review back from the forge: its open threads and the head you reviewed,
which it finds even after a force-push. The next draft answers each thread fixed or open, and
--login names the account that reviewed when it cannot be told. list shows each fetched pull
request with its head, worktree and whether a draft exists; cleanup takes the worktree, the refs
and the draft of one back.
The record and the draft live in .ai/workspace/pr/<n>/, ignored by git. In a project without Jig
installed they live in <git-common-dir>/jig/pr/<n>/, inside the clone and out of its working tree.
GitHub needs gh, and gh 2.40 or later when several accounts are signed in on the host, so that
Jig can post as the one that may comment; GitLab needs glab. Posting to GitLab and the follow-up
have not yet been checked on a live merge request or pull request.
In Claude Code your own copy of the skill wins over a project’s, so inside a Jig project the
released skill runs; jig status says so when the two differ. Codex may offer both and does not
document which one it uses.
Run the project’s checks
--explain previews each check as full, filtered, skipped or conditional without running
the checks or waiting for another verification. It uses the same scope choice as a plain
jig verify; combine it with --changed, --full, --base or --profile to preview
those choices. Conditional means a tool such as Go or Jest would have to inspect the
project before the final set is known, so a full run remains possible. The preview is
not verification: exit 0 means a plan was printed, exit 2 means an installed profile
could not explain its plan, and exit 1 means the preview failed.
--changed requests checks for the changed files. Each profile says whether it narrowed its work
or ran the full check. A plain jig verify follows the project’s verify.full_run setting.
Configure verification.
Preview a personal setting
This example previews letting the agent commit, push, and open pull requests:--dry-run. To return to the default, use:
.ai/config.local.yaml.
Compare the permission levels before changing one.
Finish through the workflow
Ask the agent to verify the result and record what the project should remember before shipping it.jig task ship follows your personal permissions and checks the task’s completion records.
After the change lands, confirm whether the task can close.
On the staging flow, jig task land <id> lands the task’s open pull request on the staging branch
when you allow merge: after an approval, on the forge, or by a direct merge when it conflicts
(how a task ships). It exits 3 when you decide — no approval yet, or a push the
staging branch refused — and 5 when a conflict waits in its temporary worktree for
jig task land <id> --resolved --note-file <file>; --abort gives the landing up.
These commands are the agent’s, so they follow agent.git. Your own decisions do not:
jig task land <id> --by human lands the pull request whatever agent.git says, and so do
jig task promote <id> --by human, jig task request-review <id> --reviewer <login> --by human
and, on the direct flow, jig task merge-pr <id> --by human, which merges the task’s pull request
on the forge. They look at CI once instead of waiting, refuse a conflict, and never override the
forge’s branch protection. jig task pr-status <id> --json shows why a pull request waits: its
checks, its review and whether it merges cleanly. Your agent never passes --by human.