Project Foundation and rules
Understand the repository-owned context used by every lifecycle command.
The repository owns the project context and the rules the agent must follow. Installing the Integrity plugin does not copy another project's rules into yours. It gives the agent a standard place to find your rules.
Project Foundation
.integrity/project.md identifies the project, where Project packets live, the Integrity workspace slug, and a display-safe default Team such as team:integrity.
The current schema is integrity.project/v1. Unknown or newer schemas become read-only and block lifecycle writes. The agent does not invent a downgrade.
The default Team is a proposal for new work, not a lock. Existing Integrity assignments remain authoritative. An inaccessible, archived, or conflicting Team stops the operation until you choose another.
The optional plugin_contract field records which repository upgrades have been completed. Without it, the project starts at 0. This number tracks project setup changes, separately from the installed plugin version. The agent previews pending upgrades and changes the number only when their required work is satisfied. A number newer than your plugin knows means you need to update the plugin.
Choose a workflow
The Foundation's workflow field tells the agent how to work in the repository. Every lifecycle stage stays the same: Spec, Plan, Build, Review, and Done, with the same approvals and evidence. Only the way each stage is carried out changes.
Use branch, the default, for code and other text that Git can merge. Use revision for controlled documents that Git cannot merge, such as Word documents, Excel workbooks, and PDFs. Setup proposes one from the repository's files, or from the Team's default workflow, and you confirm it. To use revision, add workflow: revision to the Foundation's frontmatter; leave the field out for branch.
| Branch | Revision | |
|---|---|---|
| Where work happens | A task branch, with an optional separate worktree | The real files in your normal checkout |
| How changes are recorded | Git diffs, delivered by pull request when your project uses them | A commit after each step |
| Word documents | Not applicable | Edited in place as tracked changes that you accept or reject in Word |
| Excel workbooks | Not applicable | Each change is saved as a new versioned file; the previous file is kept |
| Verification | Tests and other commands | Rendered pages, a check that every change is tracked, and a checklist against the spec |
| Done | Reviewed changes are integrated | The spec's declared documents exist, Review approved them, and any approval the spec names is recorded |
In a revision repository, only one person or agent edits a document at a time. The agent checks whether the file is open in Word or Excel and stops instead of writing, so close the document before asking the agent to change it. A revision spec lists its documents in a Deliverables table, and it can name an approval, such as "approved for internal review", that Done requires you to record.
Lifecycle settings
.integrity/lifecycle-hooks.json tells completion commands which project and Integrity connection to use. Setup creates it from your confirmed context. An existing file stays unchanged during an upgrade; missing or conflicting values become questions for you.
Branch projects also record the integration branch, Git remote and review provider. These values can come from the project's existing execution policy or your confirmed answers. Adopting an execution policy remains optional.
Revision projects need only project identity and connection settings to complete reviewed work. They need no branch fields or execution policy. Their completion command uses the explicit revision base and existing review evidence; these minimal settings do not configure branch delivery or archive behavior.
When the plugin writes a new instruction block inside a project-owned Markdown file, begin/end markers identify that block. Future upgrades can change the marked block while preserving your surrounding text. Existing unmarked instructions remain yours and are shown for review rather than rewritten automatically.
See Adopt an Existing Project to preview and apply setup updates. They remain uncommitted for your review. Commit a confirmed Foundation update before an independent review; changing it afterwards requires a fresh review.
Rule registry
.agents/rules/index.yaml lists each rule's id, file path, and when it applies: lifecycle stage, signals, and path patterns. Canonical rule bodies live next to it as .agents/rules/{id}.md.
The plugin resolver reads that registry and returns only the rules for the current stage and files. Lifecycle commands use that list. They do not load every rule file by default.
Your rule text stays in the repository. The plugin owns selection, validation, and the lifecycle workflow. Host files such as AGENTS.md and .cursor/rules/integrity.mdc are thin pointers into this contract, and CLAUDE.md is a one-line @AGENTS.md import. They are not a second copy of the rules.
In Cursor and Claude Code, the Integrity plugin also installs a write gate. After this registry exists, the agent must select those rules from the real paths being edited and read the selected files before it can change the repository. Cloud agents load the same gate from a project .cursor/hooks.json or .claude/settings.json when the repository includes one.
What setup creates
Set up a project creates or updates the Foundation and registry. Changes remain ordinary Git-reviewed repository files. Integrity connections never become a second store for their contents.