Skip to main content
An existing project already knows things: how it is built, which words mean what, which rules the team follows. Some of that is written down — in docs/, in your own decision records, in CONTRIBUTING.md, in another AI tool’s instruction file — and some lives only in the code. This guide takes such a project from installation to a first task, and spends most of its time on the part that matters most: turning what the project already has into knowledge every agent reads. Each step reads: you say → the agent does → under the hood → where you are needed. You never have to name a skill; the agent picks it from what you ask. If it ever does not, name it: /jig-task in Claude Code, $jig-task in Codex.

​
1. Install and set up the project

Install Jig on your machine, then in the project folder run jig init and commit what it added. jig init recognises your stack from its manifests — package.json, composer.json, pyproject.toml, go.mod and others — and turns on the matching verification profiles.
Your own AGENTS.md or CLAUDE.md stays as it is. jig init never edits them, so until they carry the Jig section your agent does not know Jig’s workflow. jig init, jig status and jig doctor all say so when it is missing. Ask your agent “connect Jig to my AGENTS.md” — it shows you the section and adds it once you agree — or add it by hand from the section on the install page.

​
2. Let the agent learn the project

You say: “Set up Jig for this project.” The agent does: reads the manifests, entry points, directory layout and existing documents — not the whole codebase — and answers: what the system does and for whom, which parts it has and how they may depend on each other, which words name the core concepts, which rules are already enforced by lint, CI or tests. It writes three documents: GLOSSARY.md, ARCHITECTURE.md and RULES.md in .ai/knowledge/. Under the hood: the jig-init skill; jig knowledge check validates what it wrote. Where you are needed: the agent shows each document in full, because from the next session on they bind every agent in this repository. Where a term or a boundary is ambiguous it asks you instead of guessing. Read them; correct what is wrong; commit.

​
3. Adopt the documentation you already have

This is the step that makes Jig fit a project instead of sitting beside it. Without it you would have two sets of rules — yours and a new one — drifting apart. You say: “Map the project’s knowledge”, or “adopt our existing docs into Jig”. The agent does: first takes an inventory of what the repository already holds:
  • instruction files of AI tools — .cursorrules, .cursor/rules/, .github/copilot-instructions.md, your own CLAUDE.md — with their Git state;
  • Markdown documents with their size and Git state — conventions, decision records, architecture notes;
  • folders it did not open (ignored ones such as node_modules/), named so you know what was not looked at.
Then it decides, document by document, what is a rule and what is not: Where the code shows parts the documents do not describe, it proposes domain knowledge for them too — each statement marked as observed, inferred or proposed. Under the hood: the jig-map skill; it works inside a task, so the agent files one first. Every linked, copied or new document is created as proposed. A proposed document is in the repository and in the diff, but no agent receives it: jig context resolves only accepted knowledge. jig status counts what is waiting on its proposals: line. Where you are needed: everything. The agent shows its report and each proposed document — for a linked document, its path and size, and the file itself on request — and waits.

​
4. Decide what the project agrees to

You say: “Review the proposals.” The agent does: numbers the waiting documents, shows each one with what it claims in a sentence and what accepting it causes — which files it would apply to, and how much every future agent touching those files would have to read. You answer with numbers, “all”, or a domain name; it never asks you to type an id. Under the hood: the jig-accept skill; jig knowledge accept and jig knowledge reject. Rejecting records the decision on the document instead of deleting it, so nobody proposes the same thing again. Where you are needed: this is your decision alone. The agent says which proposals it is least sure of. What happens after: an accepted document reaches every agent whose work it applies to. A document tied to parts of the code arrives when those files are touched. A project-wide one — your team’s ADRs, general conventions — is listed to every agent as a one-line entry it can open. Later, when someone edits a linked file, jig status reports it on its sources changed: line until a human has looked at the change; agents read the new text meanwhile.
What adoption does not do yet. A rule that lives in a section of a larger file — the “Development” part of a README — can only be linked with the whole file, or written into RULES.md by jig-init as a copy. A new decision in a project with its own ADR folder follows that folder’s numbering only when the agent writes it at the end of a task. And nothing migrates your documents into Jig’s own structure: they stay yours, where they are.

​
5. Work on the project

From here on you describe work and the agent sizes it. You say: “Fix the typo in the checkout button.” The agent does: classifies it trivial (T0): makes the change, runs the checks, decides nothing new was learned. No workspace, no plan, no questions. You say: “Payments should go through the new provider instead of the old one.” The agent does: this changes a boundary other parts depend on, so it classifies it architectural (T3) and names the route: discover, design, your approval, implement, architecture review, verify, consolidate. It creates a task on its own branch, reads the knowledge about payments — including the conventions you adopted in step 3 — and writes a design: what changes, which alternatives lost and why, what it would cost to undo. Where you are needed: at the human gate. The agent shows the design itself, with its own objections after it, and waits. After implementation it reviews the change against the project’s boundaries and decisions, runs the checks, and asks what the project should remember: a new decision record, an updated rule, or nothing. That decision is recorded before the commit. After the change is merged, the next session asks you whether the task can be closed — a fix may still follow. Working with tasks covers the rest of a task’s life: pausing, resuming, abandoning, and several agents at once.

​
Things to know

  • Verification runs your own tools. jig verify runs the checks of your stack — npm test, the linter, the type checker — from the project’s own environment, and installs nothing. If the dependencies are not installed, the checks fail; a skipped check is never reported as a pass.
  • Tasks branch from your main branch. jig init reads which one that is from the repository — the remote’s default, else main or master. If it guessed wrong, change git.base_branch in .ai/config.yaml (Configuration).
  • Your team gets the same setup once the .ai/ folder and the skills are committed; nobody else has to install anything for the project to work.