Adopt an Existing Project
Add Integrity context without replacing a mature repository's instructions.
Open the existing repository and ask your coding agent to set up Integrity. The agent inspects the stack, architecture, commands, tests, deployment, and existing instruction files read-only before proposing project context.
Existing instructions remain authoritative. The agent classifies recurring obligations as candidates in .agents/rules/index.yaml and keeps the detailed text in .agents/rules/ or in the files already in the repository. It does not copy another project's rule catalogue into yours.
Even when .integrity/project.md and .agents/rules/index.yaml already exist, an empty registry in a mature repository can require a focused rule-discovery pass. Missing Team selection also pauses adoption until you choose an accessible active Team.
Review the local diff, resolve every conflict, and request a commit only when the repository mapping is correct. No repository file, Integrity record, or external tracker is silently replaced during adoption.
Update after a plugin upgrade
Updating the plugin does not automatically change an onboarded repository. Ask your agent to check this project's Integrity setup and preview any pending upgrades. It uses the existing project context without restarting the onboarding interview.
The preview groups files to add or replace, files to remove, and items that need your review. Missing settings appear as specific questions. Confirm the project's workspace and connection, then review the proposed diff before asking the agent to apply it. The apply command requires an explicit --apply; preview alone writes nothing.
The first upgrade adds the lifecycle settings file when it is missing. An existing file stays unchanged. New setup creates these settings for both branch and revision projects; revision projects receive only the settings needed to complete their work.
Applied upgrades stay uncommitted so you can review them before requesting a commit. The project records how far its upgrades have completed and stops before unresolved items. Repeating a completed upgrade makes no changes. Edited files proposed for removal and unmarked project instructions require your decision; the agent does not rewrite them automatically.
A pending upgrade can produce a warning when Build starts. If a command actually needs a missing settings file, its error names the file and directs you to the onboarding upgrade. If the repository is ahead of your installed plugin, update the plugin first.
Commit the confirmed setup changes before an independent review of your work. Updating the Project Foundation after that review requires a fresh review.