# 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 |

This repo is authoritative for all harness, template, workflow, and model content. `agent-runtimes` no longer ships harness/template/model content — CRS is required for any content resolution (local dev or production).

## 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
  workflow/              # Typed workflow task templates (<name>@<version>.yaml)
workflows/               # Workflow DAG definitions
model-registry/          # Model scoring YAMLs (capability dimensions)
models/                  # Model endpoint YAMLs (URLs, auth, parameters)
```

## Harness Conventions

### harness.yaml fields

```yaml
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