# AGENTS.md — {{WORKSPACE_NAME}}

Agent entry point for this superbuild workspace. **Read this file first**, then shared policy under `tools/ai-rules/`.

## Workspace identity

| Field | Value |
|-------|-------|
| Workspace | {{WORKSPACE_NAME}} |
| Superbuild root | Repository root (`CMakeLists.txt`) |
| Shared workflow submodule | `tools/ai-rules/` → `ai-workflows/superbuild-workflow` |

## Shared workflow policy (authoritative)

Shared superbuild AI workflow policy is **not** defined inline in this file. It lives in the submodule:

1. `tools/ai-rules/AGENTS.md` — shared agent expectations
2. `tools/ai-rules/docs/` — architecture, governance, CMake/Conan policy, layout

**Do not** change shared policy by editing files under `tools/ai-rules/` in this repo without upstreaming to `superbuild-workflow`. Bump the submodule after upstream changes.

## Local architecture

### Repository layout

```
{{WORKSPACE_NAME}}/
├── src/           # First-party: {{LIST_SRC_COMPONENTS}}
├── libs/          # Vendored/patched: {{LIST_LIBS_OR_NONE}}
├── tools/ai-rules/ # Shared workflow submodule
├── .cursor/rules/  # Materialized adapters + local overlays
└── ...
```

### Build flow (this workspace)

Document the exact commands your team uses, aligned with shared CMake/Conan policy. See `tools/ai-rules/docs/conan-cmake-rollout.md` (Windows dual-generator policy).

**Linux / macOS (Ninja):**

```bash
conan install . -of build/linux-dev-debug --build=missing -pr:h=conan/profiles/{{LINUX_PROFILE}}
cmake --preset {{LINUX_PRESET}}
cmake --build build/linux-dev-debug
```

**Windows — Ninja (CLI):**

```bash
conan install . -of build/windows-ninja-debug --build=missing -pr:h=conan/profiles/{{WINDOWS_PROFILE}}
cmake --preset {{WINDOWS_NINJA_PRESET}}
cmake --build build/windows-ninja-debug
```

**Windows — Visual Studio generator (debug + installers):**

```bash
conan install . -of build/windows-vs-dev --build=missing -pr:h=conan/profiles/{{WINDOWS_PROFILE}}
cmake --preset {{WINDOWS_VS_PRESET}}
cmake --build build/windows-vs-dev --config Debug    # daily debug
cmake --build build/windows-vs-dev --config Release  # installer / MSBuild pipeline
```

Presets and profiles: see `CMakePresets.json` and `conan/` in this repo.

## Local exceptions

Document deviations from `tools/ai-rules/` policy here. Agents must respect these when working in **this** workspace.

| Topic | Exception | Rationale | Owner |
|-------|-----------|-----------|-------|
| {{TOPIC}} | {{WHAT_DIFFERS}} | {{WHY}} | {{TEAM_OR_PERSON}} |

If no exceptions: state *"No documented exceptions — follow shared policy in `tools/ai-rules/`."*

## Local Cursor rules

- Shared adapters materialized from `tools/ai-rules/cursor/rules/` into `.cursor/rules/`
- Local overlays: `.cursor/rules/90-{{WORKSPACE_SLUG}}-local.mdc` (see `tools/ai-rules/templates/project-local-rule.template.mdc`)

## Agent priorities

1. This file — local exceptions and build commands
2. `tools/ai-rules/AGENTS.md` — shared policy
3. Relevant `tools/ai-rules/docs/*.md` for the task
4. Product code under `src/` (not `tools/ai-rules/`)

## Contacts

| Role | Contact |
|------|---------|
| Superbuild / integration | {{CONTACT}} |
| Shared workflow submodule | Team maintaining `ai-workflows/superbuild-workflow` |