> ## Documentation Index
> Fetch the complete documentation index at: https://jig.fapost.in/llms.txt
> Use this file to discover all available pages before exploring further.

# Existing project

> Bring Jig into a codebase you already have, and adopt the documentation it already keeps.

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](/install) 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.

<Warning>
  **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](/install#2-set-up-a-project).
</Warning>

## 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:

| What it finds                                                             | What it does                                                                                                                                                                                                                                                                                                           |
| ------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| A rule document Git tracks — conventions, your ADRs, an architecture note | **Links it in place.** A small pointer is created in `.ai/knowledge/sources/`; your file stays where it is and stays the one to edit.                                                                                                                                                                                  |
| Another AI tool's instruction file                                        | Links it the same way, unless every runtime you use already loads it by itself.                                                                                                                                                                                                                                        |
| A rule file Git does not track, or ignores                                | Offers to **copy** it — after showing it to you whole, because it may be a private note. The copy is scanned for things that look like secrets; when something does, it names the line, never the value, and stops until you have looked. The scan catches the obvious only. The original is never changed or deleted. |
| A README, changelog, API reference, guide for people                      | Skips it and says so.                                                                                                                                                                                                                                                                                                  |
| The same rule written in two places, or two places that disagree          | Lists them side by side in its report, with how it would reconcile them — and settles nothing itself. Your existing rules keep their authority until you decide.                                                                                                                                                       |

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.

<Note>
  **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.
</Note>

## 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](/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](/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.