jig doctor. It checks the machine, the project and your agent’s instructions, one line
each, and prints a fix for every warning. On Windows, run it in Git Bash, or as
.ai\scripts\jig.cmd doctor in PowerShell.
The agent does not follow Jig
| Symptom | What to do |
|---|---|
| The agent works without classifying the task or creating one | Your AGENTS.md or CLAUDE.md probably lacks the Jig section — jig status shows instructions (...): no Jig section. Ask the agent to “connect Jig to my AGENTS.md”, or add the section by hand (Install). For a single request, name the skill: /jig-task in Claude Code, $jig-task in Codex. |
| The skills are missing in the runtime | Check that the runtime is listed under adapters in .ai/config.yaml, run jig upgrade, and reopen the agent session. |
| The agent does not know a rule your team wrote down | The document may still be proposed — jig status shows the count on its proposals: line. Ask the agent to “review the proposals”. |
Installation
| Symptom | What to do |
|---|---|
jig: command not found | Open a new terminal — the installer’s PATH change reaches only new ones. Otherwise check that ~/.local/bin (or, on Windows, the Jig scripts folder) is on PATH. |
| Something does not work on Windows | Run jig doctor and follow each fix: line; the installer’s log is %LOCALAPPDATA%\jig\install.log. |
self-update refuses | Commit or stash the changes in the Jig checkout. A developer checkout on a branch without an upstream is updated with Git directly. |
framework versions: ... global=unavailable | There is no Jig on PATH, or it is not a full checkout. Harmless in CI; install it where you update from. |
Projects and tasks
| Symptom | What to do |
|---|---|
not inside a git repository | Change into the project, or make the folder a Git repository first. |
project is not initialised | Run jig init in that repository. |
the repository has no commits yet when starting a task | Commit what jig init added, then start again. |
| Starting a task refuses because of uncommitted changes | They belong to other work. Pause the task that owns them (“pause it and stash the changes”), or start the new one in a separate worktree. |
--worktree needs a directory link | The disk supports neither symbolic links nor NTFS junctions (a network or FAT drive). Keep the project on a local disk, or start the task in the current checkout. |
| Several tasks match the branch | Tell the agent which one to continue. |
wrong-base in the housekeeping report | A task’s pull request was merged into a branch other than its base. It is kept; check where the work went. |
| Tasks that are merged but not closed | Say “close what’s merged”; the agent asks you about each one. |
Verification and upgrades
| Symptom | What to do |
|---|---|
| Verification reports skips | The project’s tools are missing — install its dependencies (npm install, composer install, a virtual environment …) and run it again. A skip is not a pass. |
| Verification refuses: framework files pending | Run jig upgrade --dry-run, then jig upgrade, review the change, and verify again. |
| A map line fails a profile | The error names the file and line in .ai/verify/<profile>.map; each line needs a pattern and a decision (Configuration). |
upgrade kept some files | You edited them; the report marks them keep-modified or keep-conflict. Compare with the new version and reconcile by hand. |
upgrade cannot determine the framework source | Pass --from /absolute/path/to/jig; an installed copy is not the full source. |