agent-runtime-framework/CLAUDE.md

CLAUDE.md — agent-runtime-framework

Purpose

This is the CRS reference config repo for the agent-runtimes platform. It is attached at CP scope (priority 100) with tags [harnesses, templates, workflows, model-registry, models] and provides the default content that all installations inherit.

This repo owns content, not runtime code. Runtime logic lives in agent-runtimes. Changes here take effect when the CP next polls this repo (or on POST /crs/reload).

Relationship to agent-runtimes

Concern	Repo
Harness logic (scripts, CLAUDE.md files)	here
Harness schema, loading, composition	agent-runtimes/entrypoint/harness.py
Task templates	here
Template loading and dispatch-task CLI	agent-runtimes/lib/task_templates.py
Workflow DAGs	here
Workflow engine	agent-runtimes/spec/workflows.md + CP
Model endpoint definitions	here
Model scoring / selection	agent-runtimes/lib/model_selector.py
Spec, tests, entrypoint	agent-runtimes only

The harnesses/ directory in agent-runtimes is the local-dev fallback used before CRS is live. For production, this repo is authoritative.

Repository Structure

harnesses/
  capabilities/          # Container overlay layers (tools, init scripts)
    tdd-file-lock/v1/    # OS-level test file locking (chmod root-owned)
    python-dev/v1/       # Python dev tools
    agent-communication/v1/
  contexts/              # Agent session config layers (CLAUDE.md, scripts, env)
    agent-repo/v1/       # Branch-per-task workspace (init + finalize)
    planning/v1/         # Planning agent methodology + best-practices
    code-methodology/v1/ # Coding agent rules
    security-review/v1/  # Security review methodology
    minimax/v1/          # MiniMax provider config
    anthropic-cloud/v1/  # Anthropic provider config
    gitea-ssh/v1/        # SSH key + config for Gitea access
    ...
  composites/            # Role × model × infra combinations
    code-sonnet-repo/v1/
    code-opus-repo/v1/
    planning-opus-repo/v1/
    ...
task-templates/          # dispatch-task --template <name> YAML files
workflows/               # Workflow DAG definitions
model-registry/          # Model scoring YAMLs (capability dimensions)
models/                  # Model endpoint YAMLs (URLs, auth, parameters)

Harness Conventions

harness.yaml fields

kind: capability | context | composite
name: <kebab-case>
version: <integer>
description: "<one line>"

# context/capability only:
requires: [<capability-or-context-names>]   # must be provided by another layer
provides: [<capability-or-context-names>]   # what this layer declares

scripts:
  init: "./init.sh"       # runs once at container start
  finalize: "./finalize.sh"  # runs after agent exits, before results
  pre_test: "./pre-test-hook.sh"  # runs before each test run (M19+)

env:
  KEY: "value"             # injected into agent env

secrets_required: []       # names the dispatcher must resolve before launch

# composite only:
layers:
  - context: <name>/v<N>
  - capability: <name>/v<N>

Script responsibilities

• init.sh — workspace setup, cloning, directory creation. Must be idempotent.
• finalize.sh — commit + push results, clean up temp files. Runs as the last step.
• pre_test.sh — revert agent modifications to test folders before each test run. Must write {"reverted": N} to /workspace/.agent-output/.pre-test-result.json (atomic: mktemp + mv). Exit non-zero → that test attempt is skipped.

Agent workspace layout (inside containers)

Path	Contents
/workspace/project/	Agent working dir (agents repo branch) — write output here
/workspace/reference/main/	Read-only reference clone of the project repo
/workspace/agent-runtimes/	Main project clone (from pre_action clone action)
/workspace/.agent-output/	Ephemeral output dir (session log, result files)
/opt/harness/	Mounted harness scripts and context files
/opt/harness/context/best-practices/	Best-practices markdown files

No secrets in this repo

This is a public framework repo. Secrets (provider API keys) live in OpenBao via M22 ESO, never in the framework. The minimax/v1 context here declares the structure; the live credential is mounted by ESO from the per-installation OpenBao instance. (Z.ai and Alibaba Model Studio contexts are retired but revivable — see agent-runtimes planning/future/providers F49 / F50.)

Adding a New Harness Context

1. Create harnesses/contexts/<name>/v1/harness.yaml
2. Add any scripts (init.sh, finalize.sh, pre_test.sh) in the same directory
3. Add CLAUDE.md if the context injects agent instructions
4. If composites need updating, add/update harnesses/composites/<composite>/v1/harness.yaml
5. Commit and push — CP picks up on next poll

Adding a New Task Template

1. Create task-templates/<name>.yaml following the existing pattern
2. Required fields: name, description, model, harness, requires_tags, required_params, defaults.timeout
3. Add blocked_combinations for dangerous combinations (e.g. commit_pr + agent-repo)
4. Add warnings for models with known constraints (MiniMax: no web search)

Adding a New Workflow

1. Create workflows/<name>.yaml following spec/workflows.md in agent-runtimes
2. Required: name, version, description, params, nodes
3. Use <<ARTIFACT:node_id:key>> sentinels for inter-node data passing

Source Control

• Remote: git@gitea.oreillyit.nz-ai-enablement:skynet/agent-runtime-framework.git
• Org: skynet
• Small, focused commits — one harness change or template addition per commit
• No SOPS-encrypted files — this repo is public-safe by design