Installer Contract

This page contains the exact rules the standards CLI follows. For a shorter explanation, see Installation and Setup. Installed projects do not include this file; agents follow the Installed Runtime Contract in the protocol.

The rules below come from INSTALLER.md during docs setup and builds. Contributors change the source file, then rebuild the docs. Download the original Markdown.

This file defines what the standards CLI must do when it installs, upgrades, or uninstalls STANDARDS in a project. It stays in this repository and is not installed. Installed projects receive .standards/PROTOCOL.md and its chapters in .standards/protocol/. The Installed Runtime Contract in .standards/protocol/installation.md lists the installed files and their owners, defines Project Reset, and sets the rules for agents that run the CLI. A section name in bold refers to the protocol or its chapters unless this file defines it.

Installation Metadata and Versions

.standards/INSTALLATION.json is installer metadata, not workflow state: create it on first installation, preserve/update it across normal reinstall or upgrade, and record only mutations the installer actually created. Never retroactively claim compatible pre-existing settings.

Record a client directory or settings file in createdPaths only if that exact path was absent before installation created it. Supported paths are .agents, .agents/skills, .claude, .claude/skills, .claude/settings.json, .codex, and .codex/hooks.json. Preserve this record across reinstall and upgrade.

.standards/VERSION.json records the installed framework release separately from settings ownership and workflow state. Reinstallation with the same version is allowed. An installer may upgrade to a newer minor or patch release within the same major version after verifying the existing runtime; it must preserve workflow data and update the recorded version with the framework assets. Reject older versions and cross-major upgrades. A major release may be installed into a fresh project. STANDARDS provides no migration between major versions: the only route for an existing project is standards uninstall, which deletes .standards/ (including workflow state, Auditor context, cycle records, and user styles), followed by a fresh installation. The framework maintainer chooses the release version. Adding, removing, or renaming a role is a major change, and so is any change to the runtime files or record formats that an existing installation’s files would no longer pass.

Installer File Preservation

Installation must be idempotent and preserve project-owned instructions. Before creating, replacing, updating, or removing a framework-controlled runtime path or installed skill package, verify ownership deterministically.

Ownership rules:

.standards/ is framework-owned only when .standards/PROTOCOL.md contains . Otherwise report a path collision and do not adopt, overwrite, or remove it.
An installed skill package is framework-owned only when its root SKILL.md carries the same marker. Otherwise report a skill collision and do not overwrite, merge, or remove it.
Framework source PROTOCOL.md and root workflow SKILL.md files must retain the marker. Never infer ownership from names, paths, or similar content.

After ownership checks:

Create AGENTS.md from templates/common/AGENTS.md if absent. Otherwise preserve existing content and add or update only the bounded block between  and .
Create CLAUDE.md from templates/common/CLAUDE.md if absent. If an existing user-owned unbounded @AGENTS.md import exists, preserve it and do not add a framework duplicate. Otherwise add or update a bounded integration block. If multiple unbounded imports exist, preserve them and report the conflict.
Update .standards/PROTOCOL.md, and replace .standards/protocol/ as a whole, from the installed framework version only after runtime ownership verification. Install or update each skill definition only after that destination skill package passes its ownership check. Update skill packages file by file: write every file the release ships, except the evals/ folder used to develop the skill, and leave any other file in the folder unchanged. Keep the installed protocol aligned with the installed skills.
A reinstall keeps the installed clients. The user may add a client; removing one requires uninstalling.
Preserve Codex allow_implicit_invocation: false.
For Claude Code, safely merge .claude/settings.json while preserving unrelated settings: add each missing required skillOverrides.<skill>: "user-invocable-only" and record that exact created key/value in .standards/INSTALLATION.json; preserve an already-compatible unowned value without claiming it; report conflicting unowned values rather than overriding them. On reinstall, restore any recorded key that was changed or removed, and show each restoration in the install preview.
Hooks: unless the user declines them, add the STANDARDS hook groups to .claude/settings.json and .codex/hooks.json for the installed clients, creating .codex/hooks.json if needed. A STANDARDS hook is a hook handler whose command runs .standards/bin/hook.mjs; installation replaces or removes only those handlers and leaves every other hook unchanged. Record in .standards/INSTALLATION.json which files have STANDARDS hooks. A reinstall keeps the current hook choice unless the user makes another one, restores missing or edited STANDARDS hooks, and removes them when the user turns hooks off. Codex runs new or changed hooks only after the user trusts them with /hooks.
Record ownership of newly created client directories, the Claude settings file, and the Codex hooks file separately from individual setting keys. Never record a pre-existing file or directory as created by the installer, even when it is empty or has only compatible values.
Preserve an existing verified .standards/INSTALLATION.json and update only installer-owned metadata. If it is unexpectedly missing from an otherwise verified runtime, stop and report the incomplete runtime; never reconstruct ownership by inference.
Require a valid .standards/VERSION.json in an existing verified runtime before replacing framework assets. If it is missing or invalid, stop and report the incomplete runtime; do not infer a version from file contents.
Preserve existing .standards/MODE.md and .standards/STATE.md on normal reinstall; initialize them only on first install. Do not reset, reinterpret, or discard existing workflow state during upgrades. Missing required fields or invalid formats are runtime inconsistencies, not permission to add inferred defaults.
Preserve .standards/CONTEXT.md; it is Auditor-owned, not installer-owned.
Preserve .standards/docs/ and every cycle record in it; the records are role-owned, not installer-owned.
Preserve .standards/user-styles/; its files are user-owned.
Preserve project-level instructions. When they materially conflict with the protocol, integration contract, workflow artifacts, or other authoritative constraints, follow Instruction Layering and Conflicts.
Reinstallation must not duplicate managed blocks/imports, reset workflow mode/state, or erase project instructions.

Installation does not fabricate completed workflow artifacts such as scope, technical design, project context, tests, reviews, or documentation.

Project Uninstallation

An explicit standards uninstall removes the project’s installed runtime and all verified STANDARDS skill packages for Codex and Claude Code. It is allowed in either project mode, with or without an active cycle. Removal ends the runtime’s lifetime; the command itself does not complete, sign off, cancel, or revert project work. The globally installed CLI is unaffected.

Default to the current directory; accept --project <path> for an existing project directory. Offer --dry-run to report every planned path removal or shared-file update without writing files. Help and preview output must explain that removing .standards/ deletes saved workflow state, Auditor context, cycle records, user styles, and any other content in that directory. When .standards/docs/ holds cycle records or .standards/user-styles/ holds user styles, the preview must warn with their counts.
Require the runtime ownership marker and a valid, supported .standards/INSTALLATION.json before removal. Do not infer settings ownership from current values. Unknown ownership records require an uninstaller that understands them. Missing or invalid workflow metadata does not prevent explicit removal when ownership is established; uninstall does not need a valid version, mode, or state and is not an upgrade.
Discover marked skill packages under .agents/skills/ and .claude/skills/, including marked roles absent from the current distribution. Remove their entire verified directories. Remove a recorded client parent directory only if it is empty after planned removals. Preserve unrecorded or nonempty client directories and unrelated skills; a folder whose SKILL.md is missing or a symlink is not a STANDARDS package and is skipped. Stop on a collision at a known framework role rather than adopting it.
Remove only the bounded STANDARDS block from AGENTS.md and CLAUDE.md, together with the blank line and final newline that installation added around it. Preserve all other text, including unbounded @AGENTS.md imports. Delete either file only when its remaining content is whitespace. Malformed or duplicate boundaries must stop removal before mutation.
Remove each recorded client setting only if its current value exactly matches the recorded installed value. Preserve changed values and report them; leave absent settings absent. Preserve compatible settings not recorded as owned, unrelated settings, and files or containers whose creation was not recorded. Remove every STANDARDS hook handler from .claude/settings.json and .codex/hooks.json, leaving other hooks in place. Remove .claude/settings.json only if its creation was recorded and, after reverting owned settings and hooks, it contains nothing but $schema and an empty skillOverrides object. Remove .codex/hooks.json only if its creation was recorded and nothing else remains in it. Otherwise retain the file and preserve unrelated or changed content. If createdPaths is absent, retain the file and parent directories even if they look like installer output.
Validate all affected paths and settings before making changes. Refuse symlinks in affected paths or within directories to be removed. Do not follow unrelated skill symlinks. A missing runtime with remaining marked skills or integration blocks is an incomplete installation requiring ownership recovery, not permission to guess. With no runtime or identifiable remnants, report a no-op.
Apply shared-file changes and skill removals before removing .standards/. Retain backups during the operation and restore prior files on an ordinary failure. If recovery fails, retain backups and report their location. An interrupted process may leave a partial operation; retain a mapping from backups to original paths and block install, reset, and uninstall until it is resolved. Do not claim atomicity across process interruption.
Delete the cycle records under .standards/docs/ with the runtime. Preserve implementation, tests, documentation, and reused project scope or design documents outside the removed runtime and verified skill directories. A later fresh installation starts a new runtime; artifacts and cycle markers outside the removed runtime still count when cycle.mjs checks a new ID.

There is no force removal or client-only uninstall. Removing one client while retaining shared runtime ownership requires a separate contract.