What a task is
When the agent starts a task it creates:- a branch of its own, cut from your main branch — or from an epic branch, when the task belongs to a specification that is released at once (New project);
- a workspace in
.ai/workspace/tasks/<id>/— the task description, analysis, plan or design, whatever its route needs. Workspaces are local to your machine and never committed: they are notes for the people and agents working on the task, not documentation.
.ai/knowledge/ and is committed with the code.
Small work — a typo, a one-file fix that fits in one session — needs no workspace at all.
Talking about tasks
You do not need commands; these are the kinds of things you say:A task’s states
Paused is a mark on an active or ready task, not a state of its own: it says the work was
set aside, with a reason, and it comes back where it was.
How a task ends
Every task ends with the question what should the project remember? — a new decision record, an updated rule, or explicitly nothing. The agent records that answer before the commit, so the knowledge travels in the same pull request as the code. A merge alone does not close a task: a fix can still follow it. At the start of a session the agent checks which of your tasks were merged, names each one and asks whether it can be closed. Nothing is closed without your yes. What is left behind is cleaned up automatically. The workspace of a closed task is moved to a trash folder, and deleted from there after a week. A task whose remote state cannot be determined keeps its workspace. An abandoned task’s workspace goes to the trash after two weeks, whatever its remote state. The trigger is a Claude Code session hook or a scheduler you choose (Configuration).Several agents at once
One checkout holds one piece of uncommitted work. When an agent is already working and you want to start something else, say “start the caching task in a separate worktree”. The agent creates a second working copy of the repository next to it (in../<project>.worktrees/<id> by default), cut
from the freshest main branch, and leaves the current work alone. Open a new agent session in that
folder — the agent tells you the path; some runtimes can switch there on their own.
Each worktree has its own branch and its own uncommitted changes; the task list in the original
checkout still shows every task and where it runs. Review and commit in the worktree as you would
anywhere. When the task is closed, the worktree is removed with it — but only if it has no
uncommitted changes. Worktrees you or your agent created by hand are never removed.
When the work turns out bigger
A task starts with a class the agent chose from the risk it saw. When the work turns out bigger — a “local fix” that touches an interface other parts depend on — the agent re-classifies it and runs the stages the new class requires, including your approval where the new route has a human gate. Risk sets the floor: a one-line change to authentication is never trivial.Who commits
Jig’s scripts never push, and never commit — apart from the one first commit the Windows installer makes in a repository it created itself. Whether the agent may commit, push or open pull requests is your project’s rule, written in yourAGENTS.md or your runtime’s settings — not Jig’s.