# KRI Agent Harness Composition Specification ## Purpose The composer builds deterministic, self-contained repository instructions from centrally maintained rules and repository-owned metadata. Repository agents read the generated `AGENTS.md`; Claude Code reads the paired `CLAUDE.md`, which imports that generated file. ## Runtime - `scripts/agent-harness.ps1` is the Windows PowerShell 5.1-compatible wrapper. - `scripts/agent-harness.cmd` launches that wrapper with a process-scoped execution-policy bypass for machines that block unsigned local PowerShell scripts; it does not change user or machine policy. - The wrapper requires Node.js 20 or newer and invokes the bundled `dist/cli.cjs` engine. - Runtime dependencies are bundled into `dist`; composing and verifying do not require `npm install` or network access. - Source builds use TypeScript, YAML parsing, JSON Schema validation, and esbuild. ## Workspace Resolution - `workspace.yml` is the committed shared registry and must declare `workspace_root` as the harness's direct parent directory. - `workspace.local.yml` is an optional, Git-ignored registry for machine-local projects and must not override `workspace_root`. - Duplicate project IDs across the shared and local registries are errors. - Every project path is relative to `workspace_root`. Absolute paths, the workspace root itself, and paths that escape the resolved workspace root are rejected. - A registry key must match the repository profile's `project.id`. - Shared contract provider IDs are resolved through the merged registry. ## Inputs The composer reads these inputs as strict UTF-8 text: 1. `sources/base.md` 2. `sources/project-types/.md` 3. `sources/stacks/.md` for each `profile.yml` `stack` entry, in declared order 4. `sources/stacks/.md` once for each unique database engine, in first-declaration order 5. `sources/policies/planned-migration.md` when a `migration` block exists 6. Shared contract consumer files resolved through `catalog/contracts.yml` and the merged workspace registry 7. The target repository's `.agent/project.md` 8. The target repository's `.agent/consumer.md` when the profile provides at least one shared contract The target repository profile is `.agent/profile.yml` and must conform to `schemas/profile.schema.json`. Machine paths never belong in the profile. ## Composition Order Write sections in this order: 1. Deterministic generated-file header 2. Base rules 3. Project-type rules 4. Declared technology-stack rules 5. Derived database-engine rules 6. Active migration policy 7. Consumed shared contracts, ordered by the catalog `order` value 8. The provider repository's own consumer contract, when applicable 9. Project-specific rules Separate non-empty fragments with exactly one blank line. Do not add timestamps, machine paths, Git branches, or other volatile values. Do not silently truncate or summarize a fragment. ## Generated Header Use this logical content, substituting deterministic profile values: ```text GENERATED BY KRI AGENT HARNESS. DO NOT EDIT DIRECTLY. Project: Schema version: Edit the source fragments or repository .agent files, then recompose. ``` Render the header as an HTML comment so it does not become an instruction heading. ## Shared Contract Resolution - A profile declares shared contract IDs under `shared_contracts.consumes` and `shared_contracts.provides`. - Resolve each contract ID in `catalog/contracts.yml`. - Resolve its `provider_project_id` to a repository path through the merged workspace registry. - Read the catalog's `consumer_file` from that provider repository at composition time. - A new composition therefore picks up the latest local consumer contract immediately; committed generated files remain stable until recomposed and committed again. - `--contract ` selects the registered provider first, followed by only profiles that explicitly consume that contract, ordered by project ID. It does not select unrelated registered projects. - Contract selection fails for an unknown contract, an unregistered provider, or a provider profile that does not declare the catalog contract under `shared_contracts.provides`. - Do not allow the same contract in both `provides` and `consumes`. - A provider repository is exempt from automatic layer requirements. Its `consumes` list is explicit so self-imports and circular assumptions are not introduced. - For a non-legacy, non-provider repository, every catalog contract whose `required_layers` contains the project layer must be declared in `consumes`. - A legacy repository may opt into any compatible shared contract, but the composer must not add one implicitly. ## Semantic Validation Fail composition when any of these conditions is true: - The profile has an unknown field, invalid enum value, duplicate ID, or unresolved fragment. - A `nextjs` stack does not also declare `react`. - A database ID is duplicated or its engine fragment does not exist. - `shared_contracts` contains a duplicate, an unknown contract, or a provides/consumes overlap. - A required non-legacy shared contract is missing. - A provider project is not registered or its consumer file is missing or empty. - `.agent/project.md` is missing or empty. - A providing repository's `.agent/consumer.md` is missing or empty. - A migration target containing `nextjs` does not also contain `react`. - Any Markdown, JSON, or YAML input is not strict UTF-8 without BOM. The `access` field for a database is optional. Its absence grants no database execution permission. Any declared access level remains subordinate to the Base rule requiring separate explicit approval for database execution. ## Outputs ### `AGENTS.md` - Self-contained; it must not depend on imports or files outside the repository. - UTF-8 without BOM and LF line endings. - Ends with exactly one newline. - Contains no generated timestamp or absolute machine path. - An existing file without the harness generated marker is unmanaged and must not be overwritten. ### `CLAUDE.md` Write exactly: ```md @AGENTS.md ``` Use UTF-8 without BOM, LF line endings, and exactly one trailing newline. Refuse to overwrite other existing content. ## Size Budget Codex uses a 32 KiB default combined project-instruction limit. To leave room for possible nested guidance: - Warn when generated `AGENTS.md` exceeds 26 KiB (26,624 bytes). - Fail when it exceeds 30 KiB (30,720 bytes). - Never solve an overflow by truncating content. Shorten or split the source rules deliberately. ## Commands - `list`: list shared and local registrations without modifying files. - `plan`: resolve, validate, compose in memory, and report fragments, size, warnings, and output state. - `verify`: compare expected and stored output byte for byte without modifying files; return a failure exit code for drift. - `compose`: atomically replace only managed or missing `AGENTS.md` and `CLAUDE.md` files, then verify them again. - `register`: validate a relative project path and matching profile, then atomically update `workspace.local.yml` by default or `workspace.yml` when `--shared` is explicit. For `plan`, `verify`, and `compose`, select exactly one scope with `--project `, `--contract `, or `--all`. Contract scope processes the provider first and consumers in project-ID order. No command performs Git, database, deployment, paid API, or network operations. `--all` must be explicit; a single project is the normal scope. ## Verification Tests use isolated temporary workspaces. They cover deterministic order, byte-for-byte verification, semantic validation, contract-target selection and isolation, unmanaged-file refusal, safe registration paths, and hard size-limit enforcement.