binaryaaron · Oct 16, 2026
@@ -0,0 +1,20 @@
+# Shared coding-agent guidance
+
+[AGENTS.md](../AGENTS.md) is the canonical instruction source for agents
+contributing to UserSim. [CLAUDE.md](../CLAUDE.md) is a thin discovery adapter;
+it does not define a second workflow. Other clients can read the canonical file
+directly. No client-specific hooks, settings, or autoload integrations are
+provided here.
+
+Keep reviewed shared guidance trackable under `.agents/`. Keep personal
+instructions and utilities under the ignored `.agents/local/`, with private
+logs and session artifacts under `.agents/logs/` and `.agents/sessions/`.
+These three private directories are excluded from both Git and Docker build
+contexts; shared guidance remains included.
+`AGENTS.local.md`, `CLAUDE.local.md`, and client settings/hooks are also private.
+A client may require explicit loading of a local instruction file; this
+repository does not guarantee automatic discovery. Local preferences remain
+subject to the user's instructions and applicable instruction hierarchy.
+
+Executable development behavior belongs in the repository's Mise tasks and
+existing Git hooks/CI checks. Shared adapters require review before inclusion.
@@ -43,6 +43,9 @@ data
 # Private top-level work areas and agent overrides.
 _*/
 .worktrees/
+.agents/local/
+.agents/logs/
+.agents/sessions/
 **/AGENTS.local.md
 **/CLAUDE.local.md
 

@@ -37,4 +37,9 @@
 /mise.lock @NVIDIA-NeMo/user_sim_maintainers
 /.mise/ @NVIDIA-NeMo/user_sim_maintainers
 
+# Shared coding-agent instructions and adapters affect contributor execution.
+/AGENTS.md @NVIDIA-NeMo/user_sim_maintainers
+/CLAUDE.md @NVIDIA-NeMo/user_sim_maintainers
+/.agents/ @NVIDIA-NeMo/user_sim_maintainers
+
 /tests/fixtures/exclusion-policy.json @NVIDIA-NeMo/user_sim_maintainers
@@ -70,6 +70,15 @@ Thumbs.db
 # Private agent overrides and session artifacts; shared guidance stays trackable.
 AGENTS.local.md
 CLAUDE.local.md
+.agents/local/
+.agents/logs/
+.agents/sessions/
+.claude/settings.json
+.claude/logs/
+.claude/hooks/
+.codex/config.toml
+.codex/hooks.json
+.codex/sessions/
 .claude/settings.local.json
 .codex/config.local.toml
 .worktrees/

@@ -0,0 +1,91 @@
+# Developing UserSim
+
+These instructions are for coding agents developing this repository. UserSim's
+simulated users and agents are product behavior: changing their prompts or
+policies changes what an experiment measures.
+
+UserSim generates persona-grounded conversations, evaluates trajectories, and
+produces reports and selected datasets. Read [CONTRIBUTING.md](CONTRIBUTING.md)
+for contributor policy and [architecture/overview.md](architecture/overview.md)
+for the system map.
+
+## Find the owning module
+
+| Path | Responsibility |
+| --- | --- |
+| `src/usersim/cli/` | Command arguments, configuration loading, and pipeline orchestration. |
+| `src/usersim/engine/config.py`, `engine/core/` | Simulation contracts, conversation runtime, model calls, identities, and storage. |
+| `src/usersim/engine/probes/`, `engine/assets/` | Probe behavior, prompts, and shipped asset banks. |
+| `src/usersim/engine/evaluator/` | Evaluation configuration, rubric axes, and scorers. |
+| `src/usersim/reporting/` | Report data and rendered dashboards. |
+| `src/usersim/selection/` | Selection profiles, quality gates, and exports. |
+| `src/usersim/asset_gen/` | Asset generation and validation. |
+
+Follow the neighboring code and keep behavior with its owning module. Read the
+[engine guide](docs/engine/README.md) and [probe authoring guide](docs/engine/AUTHORING_A_PROBE.md)
+for probe work; use the [extension architecture](architecture/plugins.md) and
+[external runtime contract](docs/engine/EXTERNAL_PROBE_RUNTIME.md) for host and
+extension changes. Update the relevant documentation with each change.
+
+## Set up and validate
+
+Mise owns tools and task implementations. Use the repository wrapper,
+`scripts/mise`, so its scoped installation and configuration apply. Make targets
+are compatibility wrappers. See [Mise setup](docs/engineering/mise.md) for
+prerequisites, version pins, and environment overrides.
+
+```bash
+make bootstrap
+scripts/mise run setup
+scripts/mise tasks
+PYTEST_ARGS='tests/test_cli_async.py -q' PYTEST_WORKERS=2 scripts/mise run test
+```
+
+Setup installs Git hooks; linked worktrees share their Git hook directory.
+Use `scripts/mise run setup:ci` when dependencies are needed without installing
+hooks. Work in a separate branch/worktree when isolating concurrent changes:
+
+```bash
+git worktree add -b <branch> ../UserSim-<topic> <base-ref>
+```
+
+Run setup from that worktree and keep its Python environment separate. Preserve
+`UV_PROJECT_ENVIRONMENT` and other documented overrides when selecting a custom
+environment; do not reuse a host environment for installed-package tests.
+
+| Task | When to use it |
+| --- | --- |
+| `scripts/mise run check` | Static checks and tracked-file hooks; hooks may rewrite files, requiring review and another run. |
+| `scripts/mise run check:type` | Blocking source and gate-script type checks. |
+| `scripts/mise run test` | Ordinary offline tests; use `PYTEST_ARGS` for focused selection and bound `PYTEST_WORKERS`. |
+| `scripts/mise run test:e2e` | Installed CLI workflow against the local fake provider. |
+| `scripts/mise run validate:ci` | Complete native validation, archive checks, and e2e against the resulting wheel. |
+| `scripts/mise run test:ci-container` | Bounded CPU container validation with external networking disabled during execution. |
+
+The [CI guide](docs/engineering/ci.md), [e2e guide](docs/engineering/e2e.md), and
+[container guide](docs/engineering/container-tests.md) explain scope and artifacts.
+Ordinary tests suppress external extension discovery and block sockets, including
+loopback. Installed e2e uses separate environments, synthetic inputs, a loopback
+provider, a prepared tokenizer cache, and disabled telemetry. Preserve these
+boundaries. [Live health checks](docs/engineering/health-checks.md) are separate,
+credentialed operations; run them only when applicable and authorized.
+
+## Prepare changes for review
+
+Review a stacked branch against its actual parent, and identify that base in the
+handoff. Rerun affected checks after rebasing. Keep each PR's implementation and
+documentation scoped to its incremental change.
+
+Follow the [PR template](.github/PULL_REQUEST_TEMPLATE.md) and
+[contribution policy](docs/engineering/contribution-policy.md). When a commit is
+authorized, use `git commit --signoff`; its trailer must match the author, and
+each declared co-author needs their own matching sign-off. Cryptographic signing
+is separate from the repository's DCO requirement. Reuse the established Git
+hook and CI checker rather than adding another commit-policy implementation.
+
+Report the behavior changed, exact checks run and their outcomes, and remaining
+limitations. Do not claim unrun tests, CI results, live-provider acceptance, or
+human review. Keep credentials, private endpoints, personal model preferences,
+and client settings out of shared files. See [.agents/README.md](.agents/README.md)
+for shared versus local guidance; optional local files do not imply client
+autoload support or override the user's instructions.
@@ -0,0 +1,5 @@
+# Claude coding-agent entry point
+
+Canonical repository instructions live in [AGENTS.md](AGENTS.md).
+
+@AGENTS.md
@@ -105,6 +105,14 @@ passes the check automatically.
         this project or the open source license(s) involved.
   ```
 
+## Coding-agent guidance
+
+Coding agents developing this repository should start with
+[AGENTS.md](AGENTS.md). It links the task interface, validation boundaries, and
+review requirements. [Shared agent guidance](.agents/README.md) describes
+reviewed adapters and private local files; keep credentials, personal settings,
+and session artifacts out of shared instructions.
+
 ## Getting set up
 
 Supports Python 3.11 to 3.14. The default development interpreter is Python 3.12

@@ -24,6 +24,96 @@
     "git_ignored": true,
     "docker_included": false
   },
+  {
+    "path": "AGENTS.local.md",
+    "git_ignored": true,
+    "docker_included": false
+  },
+  {
+    "path": "CLAUDE.local.md",
+    "git_ignored": true,
+    "docker_included": false
+  },
+  {
+    "path": ".agents/local/workflow.md",
+    "git_ignored": true,
+    "docker_included": false
+  },
+  {
+    "path": ".agents/logs/session.jsonl",
+    "git_ignored": true,
+    "docker_included": false
+  },
+  {
+    "path": ".agents/sessions/private.md",
+    "git_ignored": true,
+    "docker_included": false
+  },
+  {
+    "path": ".claude/settings.json",
+    "git_ignored": true,
+    "docker_included": false
+  },
+  {
+    "path": ".claude/logs/session.jsonl",
+    "git_ignored": true,
+    "docker_included": false
+  },
+  {
+    "path": ".claude/hooks/private.sh",
+    "git_ignored": true,
+    "docker_included": false
+  },
+  {
+    "path": ".codex/config.toml",
+    "git_ignored": true,
+    "docker_included": false
+  },
+  {
+    "path": ".codex/hooks.json",
+    "git_ignored": true,
+    "docker_included": false
+  },
+  {
+    "path": ".codex/sessions/session.jsonl",
+    "git_ignored": true,
+    "docker_included": false
+  },
+  {
+    "path": ".claude/settings.local.json",
+    "git_ignored": true,
+    "docker_included": false
+  },
+  {
+    "path": ".codex/config.local.toml",
+    "git_ignored": true,
+    "docker_included": false
+  },
+  {
+    "path": ".worktrees/feature/file.py",
+    "git_ignored": true,
+    "docker_included": false
+  },
+  {
+    "path": "AGENTS.md",
+    "git_ignored": false,
+    "docker_included": true
+  },
+  {
+    "path": "CLAUDE.md",
+    "git_ignored": false,
+    "docker_included": true
+  },
+  {
+    "path": ".agents/README.md",
+    "git_ignored": false,
+    "docker_included": true
+  },
+  {
+    "path": ".agents/skills/workflow/SKILL.md",
+    "git_ignored": false,
+    "docker_included": true
+  },
   {
     "path": ".agent-work/plans/engineering-workflows.md",
     "git_ignored": true,