From 5bc47bc609c113623ef1a4028af56543eab14ee8 Mon Sep 17 00:00:00 2001 From: Uwe Maucher <205777204+umaucher@users.noreply.github.com> Date: Thu, 11 Jun 2026 10:41:49 +0200 Subject: [PATCH 1/3] chore: add AI agent context structure - AGENTS.md: org-wide entry point (cross-tool: Copilot, Claude Code, Codex) - .agents/docs/extension_guide.md: rules for extending agent context across repos - .github/docs/score_github_api.md: GitHub API reference and GraphQL snippets --- .agents/docs/extension_guide.md | 110 +++++++++++++++++++++++++++++++ .github/docs/score_github_api.md | 89 +++++++++++++++++++++++++ AGENTS.md | 34 ++++++++++ 3 files changed, 233 insertions(+) create mode 100644 .agents/docs/extension_guide.md create mode 100644 .github/docs/score_github_api.md create mode 100644 AGENTS.md diff --git a/.agents/docs/extension_guide.md b/.agents/docs/extension_guide.md new file mode 100644 index 00000000000..8a83ef0c7da --- /dev/null +++ b/.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 + +``` +/ +├── 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//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//` | on-demand | ✅ | +| Feature-specific skills | `/.agents/skills//` | on-demand | ✅ | +| File-scoped coding rules | `.github/instructions/.instructions.md` | via `applyTo` | Copilot only | +| Custom agent personas | `.github/agents/.agent.md` | user-invoked | Copilot only | +| Slash-command prompts | `.github/prompts/.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) +- **`/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 → `/.agents/skills/` +2. Create folder: `.agents/skills//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/.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 → `/` +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) diff --git a/.github/docs/score_github_api.md b/.github/docs/score_github_api.md new file mode 100644 index 00000000000..529a1be94ae --- /dev/null +++ b/.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/` +- 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: "") { + 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= +``` + +### Reopen a discussion + +```bash +gh api graphql -f query=' +mutation($id: ID!) { + reopenDiscussion(input: {discussionId: $id}) { + discussion { number closed } + } +}' -f 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=[,,...] # e.g. KEEP=2518,116 +CATEGORY= + +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]})') +" +``` diff --git a/AGENTS.md b/AGENTS.md new file mode 100644 index 00000000000..7264a92963b --- /dev/null +++ b/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. From 59216719d8568b48fb9a010e516cbfa37004ae14 Mon Sep 17 00:00:00 2001 From: Uwe Maucher <205777204+umaucher@users.noreply.github.com> Date: Thu, 11 Jun 2026 14:29:53 +0200 Subject: [PATCH 2/3] chore: trim agent context files to essentials MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit - AGENTS.md: rename 'feature repos' to 'module repos'; add Conventions section with gh CLI rule - extension_guide.md: remove folder ASCII tree, personal-workflow row, cross-repo skills row; drop redundant template descriptions; rename feature→module repos - score_github_api.md: remove Prerequisites section; replace verbose snippets with single annotated query explaining the non-obvious repository() workaround for org discussions --- .agents/docs/extension_guide.md | 50 +++++++++++------------ .github/docs/score_github_api.md | 69 ++++---------------------------- AGENTS.md | 8 +++- 3 files changed, 39 insertions(+), 88 deletions(-) diff --git a/.agents/docs/extension_guide.md b/.agents/docs/extension_guide.md index 8a83ef0c7da..f8a945eca3f 100644 --- a/.agents/docs/extension_guide.md +++ b/.agents/docs/extension_guide.md @@ -11,40 +11,17 @@ repositories. Read this before adding any agent customization file. 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 - -``` -/ -├── 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//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 +## What goes where | Asset | Location | Auto-loaded? | Cross-tool? | |-------|----------|-------------|-------------| | Repo overview, key facts | `AGENTS.md` (root) | ✅ always | ✅ | -| Generic shared skills | `score/.agents/skills//` | on-demand | ✅ | -| Feature-specific skills | `/.agents/skills//` | on-demand | ✅ | +| Module-specific skills | `/.agents/skills//` | on-demand | ✅ | | File-scoped coding rules | `.github/instructions/.instructions.md` | via `applyTo` | Copilot only | | Custom agent personas | `.github/agents/.agent.md` | user-invoked | Copilot only | | Slash-command prompts | `.github/prompts/.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 @@ -58,6 +35,29 @@ When multiple repos are open in the same workspace (e.g. `score` + `persistency` > For standalone use, see: https://github.com/eclipse-score/score/blob/main/AGENTS.md ``` +## Recommended AGENTS.md Structure + +```markdown +# / — Agent Context + +> + + + +## 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. Decide scope: generic (all teams) → `score/.agents/skills/`, feature-specific → `/.agents/skills/` diff --git a/.github/docs/score_github_api.md b/.github/docs/score_github_api.md index 529a1be94ae..5ec90e3aa21 100644 --- a/.github/docs/score_github_api.md +++ b/.github/docs/score_github_api.md @@ -12,17 +12,17 @@ Useful IDs and GraphQL snippets for automating tasks against the eclipse-score G - Org-level discussion URLs: `https://github.com/orgs/eclipse-score/discussions/` - Org discussions are physically stored in the **`eclipse-score/score`** repository -## Prerequisites +## Discussion Categories -- [GitHub CLI (`gh`)](https://cli.github.com/) installed and authenticated: - ```bash - gh auth login --hostname github.com - # Token needs write:discussion scope for mutations - ``` +| Feature Team | Category ID | +|--------------|-------------| +| Persistency FT | `DIC_kwDONP32A84ClSxX` | -## Useful GraphQL Snippets +## GraphQL Notes -### List all discussions in a category +> 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=' @@ -34,56 +34,3 @@ gh api graphql -f query=' } }' ``` - -### Close a discussion - -```bash -gh api graphql -f query=' -mutation($id: ID!) { - closeDiscussion(input: {discussionId: $id}) { - discussion { number closed } - } -}' -f id= -``` - -### Reopen a discussion - -```bash -gh api graphql -f query=' -mutation($id: ID!) { - reopenDiscussion(input: {discussionId: $id}) { - discussion { number closed } - } -}' -f 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=[,,...] # e.g. KEEP=2518,116 -CATEGORY= - -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]})') -" -``` diff --git a/AGENTS.md b/AGENTS.md index 7264a92963b..7e63ea51db9 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -20,6 +20,10 @@ process definitions, and contribution guidelines. - **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 | @@ -29,6 +33,6 @@ process definitions, and contribution guidelines. ## 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/`. +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. From 3c24179482bf3f265b46cace321b4b5e5bf94b17 Mon Sep 17 00:00:00 2001 From: Uwe Maucher <205777204+umaucher@users.noreply.github.com> Date: Thu, 11 Jun 2026 15:47:55 +0200 Subject: [PATCH 3/3] chore: replace 'feature' with 'module' terminology; remove cross-repo skill scope guidance --- .agents/docs/extension_guide.md | 35 ++++++++++++++++----------------- 1 file changed, 17 insertions(+), 18 deletions(-) diff --git a/.agents/docs/extension_guide.md b/.agents/docs/extension_guide.md index f8a945eca3f..ca3c38b9ed5 100644 --- a/.agents/docs/extension_guide.md +++ b/.agents/docs/extension_guide.md @@ -25,11 +25,11 @@ repositories. Read this before adding any agent customization file. ## Hierarchy Between Repos -When multiple repos are open in the same workspace (e.g. `score` + `persistency`): +When working across multiple repos (e.g. `score` + `persistency`): -- **`score/AGENTS.md`** provides org-wide context (always active for all repos in workspace) -- **`/AGENTS.md`** provides feature-specific context, references score for the rest -- Feature `AGENTS.md` must include: +- **`score/AGENTS.md`** provides org-wide context +- **`/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 @@ -60,17 +60,16 @@ rules in `## Key Facts`. ## Adding a New Skill -1. Decide scope: generic (all teams) → `score/.agents/skills/`, feature-specific → `/.agents/skills/` -2. Create folder: `.agents/skills//SKILL.md` -3. Required frontmatter: +1. Create folder: `.agents/skills//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 ...' --- ``` -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/` +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) @@ -86,25 +85,25 @@ rules in `## Key Facts`. - 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. +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/`, feature-specific → `/` +1. Decide scope: org-wide → `score/`, module-specific → `/` 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 +4. If a module doc extends an org-wide one, reference the score doc rather than duplicating content -## Feature Repo Checklist +## Module Repo Checklist -When setting up a new feature repo for agent use: +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 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) +- [ ] `.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)