chore: add AI agent context structure

.agents/docs/extension_guide.md

@@ -0,0 +1,109 @@
+# AI Agent Extension Guide — eclipse-score
+
+This document defines the rules for extending AI agent context across all eclipse-score
+repositories. Read this before adding any agent customization file.
+
+## Guiding Principles
+
+1. **Single point of truth** — never duplicate information that already exists in code or
+   docs. Agent files *point* to sources; they do not repeat them.
+2. **Minimal always-on context** — `AGENTS.md` carries only what an agent cannot infer
+   from reading the repo. Everything else is on-demand.
+3. **Portability** — prefer `.agents/` for cross-tool assets (Copilot, Claude Code,
+   Codex, ...). Use `.github/` only for Copilot-specific primitives.
+
+## What goes where
+
+| Asset | Location | Auto-loaded? | Cross-tool? |
+|-------|----------|-------------|-------------|
+| Repo overview, key facts | `AGENTS.md` (root) | ✅ always | ✅ |
+| Module-specific skills | `<module>/.agents/skills/<name>/` | on-demand | ✅ |
+| File-scoped coding rules | `.github/instructions/<name>.instructions.md` | via `applyTo` | Copilot only |
+| Custom agent personas | `.github/agents/<name>.agent.md` | user-invoked | Copilot only |
+| Slash-command prompts | `.github/prompts/<name>.prompt.md` | user-invoked | Copilot only |
+| Reference data (IDs, snippets) | `.github/docs/` or `.agents/docs/` | on-demand | depends |
+
+## Hierarchy Between Repos
+
+When working across multiple repos (e.g. `score` + `persistency`):
+
+- **`score/AGENTS.md`** provides org-wide context
+- **`<module>/AGENTS.md`** provides module-specific context, references score for the rest
+- Module `AGENTS.md` must include:
+  ```
+  > When working in this repo alongside score, score/AGENTS.md is also active.
+  > For standalone use, see: https://github.com/eclipse-score/score/blob/main/AGENTS.md
+  ```
+
+## Recommended AGENTS.md Structure
+
+```markdown
+# <org>/<repo> — Agent Context
+
+> <standalone note referencing score/AGENTS.md>
+
+<one-line description of the repo's role>
+
+## Key Facts
+
+## Conventions
+
+## On-Demand References
+| Topic | File |
+|-------|------|
+| ...   | ...  |
+```
+
+Use `## Conventions` for any rule that changes how an agent should behave — preferred
+tools, things to never do, required checks before certain actions. Do not put behavioral
+rules in `## Key Facts`.
+
+## Adding a New Skill
+
+1. Create folder: `.agents/skills/<skill-name>/SKILL.md` in the module repo
+2. Required frontmatter:
+   ```yaml
+   ---
+   name: skill-name          # must match folder name, lowercase-hyphenated
+   description: 'What it does. Use when: ... triggers ...'
+   ---
+   ```
+3. Keep `SKILL.md` under 500 lines; put detail in `./references/` subfolder
+4. Do not vendor a skill that already exists in `score/.agents/skills/`
+
+## Adding a New Instruction (Copilot only)
+
+1. Place in `.github/instructions/<name>.instructions.md`
+2. Use `applyTo` for file-scoped rules (e.g. `applyTo: "**/*.rs"`)
+3. Use `description:` for on-demand task rules (e.g. safety review checklist)
+4. Never use `applyTo: "**"` unless truly universal — it loads on every request
+
+## Adding Reference Documentation
+
+- GitHub API IDs, GraphQL snippets, external system IDs → `.github/docs/`
+- Anything an agent needs to *act* (procedures, runbooks) → `.agents/docs/`
+- Link from `AGENTS.md` — do not repeat content inline
+
+The same rules apply to any domain: git conventions, CI/CD runbooks, release procedures, etc.
+If a topic is **org-wide**, the reference doc lives in `score/` and module repos link to it.
+If a topic is **module-specific**, the doc lives in the module repo and may reference the score doc for shared context.
+
+When adding a new reference doc:
+
+1. Decide scope: org-wide → `score/`, module-specific → `<module>/`
+2. Decide type: static IDs / external data → `.github/docs/`, agent procedures / runbooks → `.agents/docs/`
+3. Link to it from `AGENTS.md` under an **On-Demand References** table
+4. If a module doc extends an org-wide one, reference the score doc rather than duplicating content
+
+## Module Repo Checklist
+
+When setting up a new module repo for agent use:
+
+- [ ] `AGENTS.md` at repo root with: FT discussion number → score, ASIL level →
+      `project_config.bzl`, `reference_integration` relationship
+- [ ] `.agents/skills/` — only module-specific skills (created when needed)
+- [ ] `.agents/docs/` — module-specific runbooks/procedures (created when needed)
+- [ ] `.github/docs/` — module-specific reference data, e.g. `score_github_api.md` (created when needed)
+- [ ] `.github/instructions/` — Copilot-only scoped rules (created when needed)
+- [ ] `.github/agents/` — Copilot-only custom agents (created when needed)
+- [ ] `.github/prompts/` — Copilot-only prompts (created when needed)

.github/docs/score_github_api.md

@@ -0,0 +1,36 @@
+# Eclipse Score GitHub API Notes
+
+Useful IDs and GraphQL snippets for automating tasks against the eclipse-score GitHub organization.
+
+> **Repo-specific notes** (category IDs, discussion lists per feature team, etc.) live in the
+> `.github/docs/score_github_api.md` of each respective repository and reference this file.
+
+## Organization
+
+- Login: `eclipse-score`
+- Node ID: `O_kgDOCy9hXw`
+- Org-level discussion URLs: `https://github.com/orgs/eclipse-score/discussions/<number>`
+- Org discussions are physically stored in the **`eclipse-score/score`** repository
+
+## Discussion Categories
+
+| Feature Team | Category ID |
+|--------------|-------------|
+| Persistency FT | `DIC_kwDONP32A84ClSxX` |
+
+## GraphQL Notes
+
+> Org discussions are stored in `eclipse-score/score`, not under an org-level field.
+> Use `repository(owner: "eclipse-score", name: "score") { discussions(...) }` — the intuitive
+> `organization { discussions }` path does not exist in the GitHub GraphQL API.
+
+```bash
+gh api graphql -f query='
+{
+  repository(owner: "eclipse-score", name: "score") {
+    discussions(first: 100, categoryId: "<CATEGORY_ID>") {
+      nodes { number title closed id }
+    }
+  }
+}'
+```

AGENTS.md

@@ -0,0 +1,38 @@
+# eclipse-score/score — Agent Context
+
+This is the **parent documentation and org-level repository** of the
+[eclipse-score](https://github.com/eclipse-score) automotive middleware OSS project.
+Feature implementations live in separate repos (e.g. `persistency`, `communication`,
+`logging`, ...) as individual Bazel modules. This repo holds org-wide documentation,
+process definitions, and contribution guidelines.
+
+## Key Facts
+
+- **Org discussions** are physically hosted in *this* repository even though they appear
+  at `https://github.com/orgs/eclipse-score/discussions/`. Each feature team has its
+  own discussion category.
+- **`reference_integration`** is where all feature modules are integrated and tested
+  end-to-end. Changes here that affect module APIs or process requirements may need to
+  be reflected there.
+- **Documentation toolchain**: Sphinx + sphinx-needs. RST files using `.. req::`,
+  `.. spec::`, `.. needflow::` etc. carry formal requirements-traceability implications.
+  Do not delete or rename need IDs — they may be referenced across repos.
+- **Single point of truth rule**: never duplicate information that already exists in
+  docs or code. AGENTS.md files point to sources; they do not repeat them.
+
+## Conventions
+
+- **GitHub queries**: always use `gh` CLI with GraphQL, never fetch discussion pages via browser/HTTP
+
+## On-Demand References
+
+| Topic | File |
+|-------|------|
+| GitHub org/API IDs, GraphQL snippets | `.github/docs/score_github_api.md` |
+| Agent extension rules & how to add skills/instructions | `.agents/docs/extension_guide.md` |
+
+## Agent Extension (this repo)
+
+Generic skills shared across all module repos live in `.agents/skills/`.
+Module-specific skills live in the respective repo's `.agents/skills/`.
+See `.agents/docs/extension_guide.md` for the full rules.