Files
ai-agent-harness/README.md

4.3 KiB

KRI Agent Harness

This repository composes deterministic AGENTS.md, paired CLAUDE.md, managed workflow skills, and shared-contract reference copies for repositories under the KRI development workspace.

Requirements

  • Windows PowerShell 5.1 or newer
  • Node.js 20 or newer

The committed dist bundle contains runtime dependencies. npm install is needed only when changing or rebuilding the harness source.

Commands

Run commands from this repository root:

.\scripts\agent-harness.cmd list
.\scripts\agent-harness.cmd plan --project kri-contact-front
.\scripts\agent-harness.cmd plan --contract kri-common
.\scripts\agent-harness.cmd verify --project kri-contact-front
.\scripts\agent-harness.cmd verify --contract kri-common
.\scripts\agent-harness.cmd compose --project kri-contact-front
.\scripts\agent-harness.cmd compose --contract kri-common
.\scripts\agent-harness.cmd register --project kri-contact-front --path _KriContact/contact-front
.\scripts\agent-harness.cmd register --project new-service --path ____Project/new-service --shared

The .cmd launcher invokes the PowerShell wrapper with a process-scoped execution-policy bypass. It does not change the user or machine execution policy. When local scripts are already allowed, scripts\agent-harness.ps1 may be called directly.

plan, verify, and list are read-only. compose writes generated AGENTS.md, CLAUDE.md, managed skills under .agents/skills and .claude/skills, and shared references under .agent-harness/references. It refuses to overwrite an unmanaged file. register writes workspace.local.yml by default; register --shared writes workspace.yml. No command performs Git, database, deployment, or network operations.

Use --contract <contract-id> to select the registered provider first and then only registered consumers of that contract, ordered by project ID. Use --all only when every registered project is intentionally in scope. --project, --contract, and --all are mutually exclusive.

Workspace Files

  • workspace.yml contains shared relative project registrations and is committed.
  • workspace.local.yml contains machine-local registrations and is ignored by Git.
  • workspace.local.example.yml documents the local format.
  • Project paths are relative to workspace_root and may not escape it.

Repository Inputs

Each managed repository owns:

  • .agent/profile.yml
  • .agent/project.md as the concise task-to-reference router
  • .agent/references/*.md for repository-specific detail
  • .agent/consumer.md when it provides a shared contract
  • .agent/consumer-references/*.md for detailed shared consumer contracts

Edit source inputs, run plan, obtain the required approval, then run compose. Use verify to detect stale generated output.

Every project.md must contain ## Required Project References. Each Markdown file under .agent/references must be routed from that section using a repository-relative backticked path. Reference-only content changes do not require recomposition when routing is unchanged, but verify still validates existence, containment, strict UTF-8, and routing completeness.

Managed Skills

The harness owns canonical skill sources under skills/<skill-name>/SKILL.md and composes identical managed copies for both supported agents:

  • Codex: .agents/skills/<skill-name>/SKILL.md
  • Claude Code: .claude/skills/<skill-name>/SKILL.md

The managed set includes project-reference-loader, which reloads only the current references matching each substantive task.

Development

On Windows PowerShell, use npm.cmd because the npm.ps1 shim may be blocked by execution policy:

npm.cmd install
npm.cmd run verify

Workspace Verification

Run a read-only verification of every shared and local project registration from the existing multi-repository workspace:

npm.cmd run verify:workspace

This command uses the committed runtime bundle and does not compose documents, update Git repositories, or access the network.

To retain a local UTF-8 log for the same verification:

npm.cmd run verify:scheduled

Install or remove the weekday Windows scheduled task with:

npm.cmd run schedule:install
npm.cmd run schedule:uninstall

See docs/local-scheduling.md for scheduling, log retention, and failure handling.