chore: add AI agent context structure

.agents/docs/extension_guide.md

@@ -0,0 +1,110 @@
+# 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.
+4. **Personal extensions belong in `~/.agents/`** — never commit personal workflows or
+   knowledge-base skills to a repo.
+
+## Folder Layout & Tool Support
+
+```
+<repo>/
+├── AGENTS.md                        # Cross-tool entry point (root preferred)
+│                                    # Recognized by: Copilot, Claude Code, Codex
+├── CLAUDE.md                        # Claude Code specific overrides (if needed)
+│
+├── .agents/                         # Cross-tool, portable layer
+│   ├── skills/<name>/SKILL.md       # On-demand skills (Copilot + Claude Code)
+│   └── docs/                        # Reference docs loaded on demand by agents
+│
+└── .github/                         # Copilot-specific primitives
+    ├── instructions/*.instructions.md   # applyTo-scoped or on-demand instructions
+    ├── agents/*.agent.md                # Custom agent personas with tool restrictions
+    ├── prompts/*.prompt.md              # Slash-command prompts
+    └── docs/                            # On-demand reference docs (API notes, etc.)
+```
+
+### What goes where
+
+| Asset | Location | Auto-loaded? | Cross-tool? |
+|-------|----------|-------------|-------------|
+| Repo overview, key facts | `AGENTS.md` (root) | ✅ always | ✅ |
+| Generic shared skills | `score/.agents/skills/<name>/` | on-demand | ✅ |
+| Feature-specific skills | `<feature>/.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 |
+| Personal workflows | `~/.agents/skills/` | on-demand | ✅ |
+
+## Hierarchy Between Repos
+
+When multiple repos are open in the same workspace (e.g. `score` + `persistency`):
+
+- **`score/AGENTS.md`** provides org-wide context (always active for all repos in workspace)
+- **`<feature>/AGENTS.md`** provides feature-specific context, references score for the rest
+- Feature `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
+  ```
+
+## Adding a New Skill
+
+1. Decide scope: generic (all teams) → `score/.agents/skills/`, feature-specific → `<feature>/.agents/skills/`
+2. Create folder: `.agents/skills/<skill-name>/SKILL.md`
+3. Required frontmatter:
+   ```yaml
+   ---
+   name: skill-name          # must match folder name, lowercase-hyphenated
+   description: 'What it does. Use when: ... triggers ...'
+   ---
+   ```
+4. Keep `SKILL.md` under 500 lines; put detail in `./references/` subfolder
+5. 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 feature repos link to it.
+If a topic is **feature-specific**, the doc lives in the feature repo and may reference the score doc for shared context.
+
+When adding a new reference doc:
+
+1. Decide scope: org-wide → `score/`, feature-specific → `<feature>/`
+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 feature doc extends an org-wide one, reference the score doc rather than duplicating content
+
+## Feature Repo Checklist
+
+When setting up a new feature 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 feature-specific skills (created when needed)
+- [ ] `.agents/docs/` — feature-specific runbooks/procedures (created when needed)
+- [ ] `.github/docs/` — feature-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,89 @@
+# 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
+
+## Prerequisites
+
+- [GitHub CLI (`gh`)](https://cli.github.com/) installed and authenticated:
+  ```bash
+  gh auth login --hostname github.com
+  # Token needs write:discussion scope for mutations
+  ```
+
+## Useful GraphQL Snippets
+
+### List all discussions in a category
+
+```bash
+gh api graphql -f query='
+{
+  repository(owner: "eclipse-score", name: "score") {
+    discussions(first: 100, categoryId: "<CATEGORY_ID>") {
+      nodes { number title closed id }
+    }
+  }
+}'
+```
+
+### Close a discussion
+
+```bash
+gh api graphql -f query='
+mutation($id: ID!) {
+  closeDiscussion(input: {discussionId: $id}) {
+    discussion { number closed }
+  }
+}' -f id=<NODE_ID>
+```
+
+### Reopen a discussion
+
+```bash
+gh api graphql -f query='
+mutation($id: ID!) {
+  reopenDiscussion(input: {discussionId: $id}) {
+    discussion { number closed }
+  }
+}' -f id=<NODE_ID>
+```
+
+### Bulk close all open discussions in a category (with exclusions)
+
+`KEEP` is a comma-separated list of discussion numbers to leave open. Omit to close all.
+
+```bash
+KEEP=<NUMBER>[,<NUMBER>,...]   # e.g. KEEP=2518,116
+CATEGORY=<CATEGORY_ID>
+
+gh api graphql -f query='
+{
+  repository(owner: "eclipse-score", name: "score") {
+    discussions(first: 100, categoryId: "'"$CATEGORY"'") {
+      nodes { number title closed id }
+    }
+  }
+}' | python3 -c "
+import json, sys, subprocess, os
+nodes = json.load(sys.stdin)['data']['repository']['discussions']['nodes']
+keep = {int(x) for x in os.environ.get('KEEP', '').split(',') if x.strip()}
+mutation = 'mutation(\$id: ID!) { closeDiscussion(input: {discussionId: \$id}) { discussion { number title closed } } }'
+for n in nodes:
+    if not n['closed'] and n['number'] not in keep:
+        r = subprocess.run(['gh','api','graphql','-f',f'query={mutation}','-f',f'id={n[\"id\"]}'],
+                           capture_output=True, text=True)
+        d = json.loads(r.stdout)
+        print(d['data']['closeDiscussion']['discussion'])
+    else:
+        print(f'skipped #{n[\"number\"]} ({n[\"title\"][:40]})')
+"
+```

AGENTS.md

@@ -0,0 +1,34 @@
+# 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.
+
+## 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 feature repos live in `.agents/skills/`.
+Feature-repo-specific skills live in the respective repo's `.agents/skills/`.
+See `.agents/docs/extension_guide.md` for the full rules.