Files
ai-agent-harness/docs/composition.md

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.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/<project.type>.md
  3. sources/stacks/<stack-id>.md for each profile.yml stack entry, in declared order
  4. sources/stacks/<database.engine>.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
  9. Each canonical skills/<skill-name>/SKILL.md
  10. Repository-authored .agent/references/**/*.md routed from .agent/project.md
  11. Provider-authored .agent/consumer-references/**/*.md routed 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:

  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:

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.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.
  • Read consumer_references_dir, require at least one strict UTF-8 Markdown reference, and require consumer_file to 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 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.
  • .agent/project.md does not contain ## Required Project References.
  • A routed .agent/references path 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.md is missing or empty.
  • A shared consumer reference directory is missing or empty, or consumer.md does not route every shared reference.
  • 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:

@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.md for Codex
  • .claude/skills/<skill-name>/SKILL.md for 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.md exceeds 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.md exceeds 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 update workspace.local.yml by default or workspace.yml when --shared is 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.