10 KiB
KRI Agent Harness Composition Specification
Purpose
The composer builds deterministic repository instructions, workflow skills, and shared-contract reference copies 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. Codex and Claude Code discover their managed skills from their repository-scoped skill directories.
Runtime
scripts/agent-harness.ps1is the Windows PowerShell 5.1-compatible wrapper.scripts/agent-harness.cmdlaunches 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.cjsengine. - Runtime dependencies are bundled into
dist; composing and verifying do not requirenpm installor network access. - Source builds use TypeScript, YAML parsing, JSON Schema validation, and esbuild.
Workspace Resolution
workspace.ymlis the committed shared registry and must declareworkspace_rootas the harness's direct parent directory.workspace.local.ymlis an optional, Git-ignored registry for machine-local projects and must not overrideworkspace_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:
sources/base.mdsources/project-types/<project.type>.mdsources/stacks/<stack-id>.mdfor eachprofile.ymlstackentry, in declared ordersources/stacks/<database.engine>.mdonce for each unique database engine, in first-declaration ordersources/policies/planned-migration.mdwhen amigrationblock exists- Shared contract consumer files resolved through
catalog/contracts.ymland the merged workspace registry - The target repository's
.agent/project.md - The target repository's
.agent/consumer.mdwhen the profile provides at least one shared contract - Each canonical
skills/<skill-name>/SKILL.md - Repository-authored
.agent/references/**/*.mdrouted from.agent/project.md - Provider-authored
.agent/consumer-references/**/*.mdrouted from.agent/consumer.md
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:
- Deterministic generated-file header
- Base rules
- Project-type rules
- Declared technology-stack rules
- Derived database-engine rules
- Active migration policy
- Consumed shared contracts, ordered by the catalog
ordervalue - The provider repository's own consumer contract, when applicable
- 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:
GENERATED BY KRI AGENT HARNESS. DO NOT EDIT DIRECTLY.
Project: <project.id>
Schema version: <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.consumesandshared_contracts.provides. - Resolve each contract ID in
catalog/contracts.yml. - Resolve its
provider_project_idto a repository path through the merged workspace registry. - Read the catalog's
consumer_filefrom that provider repository at composition time. - Read
consumer_references_dir, require at least one strict UTF-8 Markdown reference, and requireconsumer_fileto route every source reference to.agent-harness/references/<contract-id>/.... - Copy those references into each provider and consumer repository as managed, repository-local files. Refuse to overwrite a target without the harness marker.
- A new composition therefore picks up the latest local consumer contract immediately; committed generated files remain stable until recomposed and committed again.
--contract <contract-id>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
providesandconsumes. - A provider repository is exempt from automatic layer requirements. Its
consumeslist is explicit so self-imports and circular assumptions are not introduced. - For a non-legacy, non-provider repository, every catalog contract whose
required_layerscontains the project layer must be declared inconsumes. - 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
nextjsstack does not also declarereact. - A database ID is duplicated or its engine fragment does not exist.
shared_contractscontains 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.mdis missing or empty..agent/project.mddoes not contain## Required Project References.- A routed
.agent/referencespath is missing, escapes the reference root, is invalid UTF-8, or an authored Markdown reference is not routed by.agent/project.md. - A providing repository's
.agent/consumer.mdis missing or empty. - A shared consumer reference directory is missing or empty, or
consumer.mddoes not route every shared reference. - A migration target containing
nextjsdoes not also containreact. - 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:
@AGENTS.md
Use UTF-8 without BOM, LF line endings, and exactly one trailing newline. Refuse to overwrite other existing content.
Managed Skills
For each canonical skill, write identical generated copies to:
.agents/skills/<skill-name>/SKILL.mdfor Codex.claude/skills/<skill-name>/SKILL.mdfor Claude Code
The generated marker follows the YAML front matter so skill discovery remains valid. Managed skills use UTF-8 without BOM, LF line endings, and exactly one trailing newline. Missing and stale managed files may be written; an existing file without the generated marker is unmanaged and must not be overwritten.
The default managed skills are attention-aware-communication for response presentation, karpathy-guidelines for implementation discipline, project-reference-loader for task-scoped context loading, and verification-before-completion for evidence-gated completion claims.
Managed Shared References
For every provided or consumed contract, copy each provider source from its cataloged consumer_references_dir to:
.agent-harness/references/<contract-id>/<relative-source-path>
Generated references use UTF-8 without BOM, LF line endings, a harness marker, and one trailing newline. They are shared by Codex and Claude Code. Edit the provider source and recompose; never edit a generated consumer copy directly.
Size Budget
Codex uses a 32 KiB default combined project-instruction limit. To leave room for possible nested guidance:
- Warn when generated
AGENTS.mdexceeds 26 KiB (26,624 bytes). - Fail when it exceeds 32,000 bytes, leaving 768 bytes below Codex's default 32 KiB combined limit.
- Warn when
.agent/project.mdexceeds 4,096 bytes; keep it near 2-3 KiB and route conditional detail to.agent/references. - Warn when one project reference exceeds 16,384 bytes so it can be split by task scope.
- 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 instructions, skills, and shared references byte for byte while validating authored project references; return a failure exit code for drift.compose: atomically replace only managed or missing instructions, skills, and shared references, then verify them again.register: validate a relative project path and matching profile, then atomically updateworkspace.local.ymlby default orworkspace.ymlwhen--sharedis explicit.
For plan, verify, and compose, select exactly one scope with --project <id>, --contract <contract-id>, 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, project-reference routing, shared-reference distribution, semantic validation, contract-target selection and isolation, unmanaged-file refusal, safe registration paths, and hard size-limit enforcement.