171 lines
10 KiB
Markdown
171 lines
10 KiB
Markdown
# 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:
|
|
|
|
```text
|
|
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:
|
|
|
|
```md
|
|
@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:
|
|
|
|
```text
|
|
.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.
|