docs: add CLAUDE.md with repo purpose, structure, and conventions

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
2026-04-28 12:06:38 +12:00
parent 0272e3df1e
commit b04f718530
1 changed files with 130 additions and 0 deletions
--- a/CLAUDE.md
+++ b/CLAUDE.md
@@ -0,0 +1,130 @@
+# 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
+
+```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, SOPS-encrypted env files) belong in per-installation private repos attached at a lower CRS priority. The `z-ai/v1`, `minimax/v1`, `alibaba-model-studio/v1` contexts here declare the structure but leave `provider.sops.env` to the installation repo.
+
+## 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