diff --git a/.agents/docs/extension_guide.md b/.agents/docs/extension_guide.md new file mode 100644 index 00000000000..ca3c38b9ed5 --- /dev/null +++ b/.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 | `/.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 | + +## Hierarchy Between Repos + +When working across multiple repos (e.g. `score` + `persistency`): + +- **`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 + ``` + +## 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. 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 ...' + --- + ``` +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/.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 → `/` +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) diff --git a/.github/docs/score_github_api.md b/.github/docs/score_github_api.md new file mode 100644 index 00000000000..5ec90e3aa21 --- /dev/null +++ b/.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/` +- 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: "") { + nodes { number title closed id } + } + } +}' +``` diff --git a/AGENTS.md b/AGENTS.md new file mode 100644 index 00000000000..7e63ea51db9 --- /dev/null +++ b/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.