Skip to content

AGENTS.md is added to the SCORE repository #3117

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
praveen-ltts wants to merge 1 commit into
base: main
Choose a base branch
from
+147 −0
Open

AGENTS.md is added to the SCORE repository #3117

Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
147 changes: 147 additions & 0 deletions AGENTS.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,147 @@
# AGENTS.md — Eclipse S-CORE Feature Pipeline (Generic Template)

> **What is AGENTS.md:** A [README for AI coding agents](https://agents.md/) that standardizes how
> automated assistants (Copilot, Codex, Cursor, Gemini CLI, Claude Code, Aider, Jules, …) work on
> **[Eclipse S-CORE](https://eclipse-score.github.io/score/main/)** *features*.
> Place this file at the repo root; place a tailored copy in each
> [`docs/features/<feature>/`](https://eclipse-score.github.io/score/main/features/index.html) folder.
> **Precedence:** the closest `AGENTS.md` to the edited file wins; explicit user chat prompts override everything.

---

## 1. Project overview

- **Project:** [Eclipse Safe Open Vehicle Core (S-CORE)](https://eclipse.dev/score/) — an open-source,
functional-safety-compliant software platform for Software Defined Vehicles (SDVs) / high-performance ECUs.
- **A *Feature*** is the highest-level logical entity: a set of interrelated components managed together,
owning its **feature requirements** and **feature architecture**
([Features index](https://eclipse-score.github.io/score/main/features/index.html)).
- **Main repo:** [`eclipse-score/score`](https://github.com/eclipse-score/score) holds stakeholder requirements,
the high-level architecture, the feature list, and the decomposition into modules. Most features are also
implemented in their own [module repositories](https://github.com/eclipse-score).
- **Compliance targets:** [ISO 26262](https://www.iso.org/standard/68383.html) (functional safety, up to ASIL_B),
[ISO 21434](https://www.iso.org/standard/70918.html) (cybersecurity) and ASPICE. Final-system compliance stays
with the series project — S-CORE is a generic foundation, not a ready-to-integrate product.

## 1a. Where to place this file

- **This file → repository root:** `eclipse-score/score/AGENTS.md` (and, optionally, the root of each
[module repo](https://github.com/eclipse-score) such as `persistency/AGENTS.md`).
- **Feature-scoped copies → one per feature folder:** `docs/features/<feature>/AGENTS.md`.
- **Discovery rule (nearest wins):** an agent editing `docs/features/persistency/requirements/foo.rst`
reads `docs/features/persistency/AGENTS.md` first, then falls back to the root `AGENTS.md`; an explicit
user chat instruction overrides both ([precedence model](https://agents.md/)).
- **Optional overrides:** drop an `AGENTS.override.md` beside an `AGENTS.md` for temporary/personal
instructions without touching the shared file (it takes precedence at the same level).
- **File must be committed** (not git-ignored) so every contributor and CI-based agent sees it.

```text
score/
├── AGENTS.md # ROOT — global agent context (place here)
└── docs/features/
├── persistency/AGENTS.md # feature-scoped (nearest wins)
├── communication/AGENTS.md
└── <feature>/AGENTS.md # one per feature
```

## 2. Features (list)

Each feature lives under [`docs/features/<folder>/`](https://github.com/eclipse-score/score/tree/main/docs/features)
and, when implemented, in a matching module repo.

- [AI Platform](https://github.com/eclipse-score/score/tree/main/docs/features/ai_platform) — `ai_platform`
- [Analysis Infrastructure](https://github.com/eclipse-score/score/tree/main/docs/features/analysis-infra) — `analysis-infra`
- [Base Libraries](https://github.com/eclipse-score/score/tree/main/docs/features/baselibs) — `baselibs` · `feat__baselibs` · ASIL_B · [repo](https://github.com/eclipse-score/baselibs)
- [Code Generation](https://github.com/eclipse-score/score/tree/main/docs/features/code_generation) — `code_generation`
- [Communication (LoLa)](https://github.com/eclipse-score/score/tree/main/docs/features/communication) — `communication` · `feat__com_communication` · ASIL_B · [repo](https://github.com/eclipse-score/communication)
- [Configuration](https://github.com/eclipse-score/score/tree/main/docs/features/configuration) — `configuration`
- [Diagnostic & Fault Management](https://github.com/eclipse-score/score/tree/main/docs/features/diagnostics) — `diagnostics` · [repo](https://github.com/eclipse-score/inc_diagnostics)
- [Frameworks (FEO)](https://github.com/eclipse-score/score/tree/main/docs/features/frameworks) — `frameworks` · `feat__feo` · ASIL_B · [repo](https://github.com/eclipse-score/feo)
- [Lifecycle](https://github.com/eclipse-score/score/tree/main/docs/features/lifecycle) — `lifecycle` · `feat__lifecycle` · ASIL_B · [repo](https://github.com/eclipse-score/lifecycle)
- [NonIPC](https://github.com/eclipse-score/score/tree/main/docs/features/nonipc) — `nonipc`
- [Orchestration](https://github.com/eclipse-score/score/tree/main/docs/features/orchestration) — `orchestration` · `feat__orchestration` · ASIL_B · [repo](https://github.com/eclipse-score/orchestrator)
- [Persistency](https://github.com/eclipse-score/score/tree/main/docs/features/persistency) — `persistency` · `feat__persistency` · ASIL_B · [repo](https://github.com/eclipse-score/persistency)
- [Security & Cryptography](https://github.com/eclipse-score/score/tree/main/docs/features/security_crypto) — `security_crypto` · [repo](https://github.com/eclipse-score/inc_security_crypto)
- [Time](https://github.com/eclipse-score/score/tree/main/docs/features/time) — `time` · [repo](https://github.com/eclipse-score/time)

> Cross-cutting feature IDs also tracked in the platform: `feat__logging`, `feat__os`, `feat__tracing`.

## 3. Repository & folder hierarchy (src / docs)

```text
<repo-root>/
├── AGENTS.md # Root agent context (this file)
├── MODULE.bazel / BUILD / .bazelrc # Bazel build definitions
├── .devcontainer/ # Reproducible dev environment (recommended)
├── .github/workflows/ # CI/CD: build, tests, docs, integration gates
├── src/ # Source code (C++ / Rust)
├── tests/ (or test/) # Unit & integration tests (gtest/gmock, cargo test)
└── docs/
├── index.rst
└── features/
├── index.rst # Feature list (needtable of feat__*)
└── <feature>/ # e.g. persistency, communication, time …
├── AGENTS.md # Feature-scoped agent context (nearest wins)
├── index.rst # Feature landing page
├── requirements/ # feat_req__<feature>__* (sphinx-needs)
└── architecture/ # feature architecture, interfaces, diagrams
```

## 4. Dev environment & setup

@FScholPer FScholPer Aug 3, 2026

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Lets create a onboarding agent and skill.

That could look like
image

The purpose would be ask the user what role he/or she has, what repo is the goal and what technology. Then we just pull it in here. Everything like guideline should be done in onboarding phase not here. Example can look like:

description: 'Type /sdlc or KICKOFF to start the Eclipse S-CORE AI SDLC workflow.'
model: 'some model name here'
handoffs:

  • label: Start Issue Planning
    agent: plan-issue-creation
    prompt: 'Begin GitHub issue creation -- collect open-source context and define a new Eclipse S-CORE issue.'
    send: true
  • label: Start Technical Analysis
    agent: plan-tech-analysis
    prompt: 'Analyze the GitHub issue and break it into implementation-ready issues or pull request tasks. Provide the issue URL, issue number, or artifacts path.'
    send: true
  • label: Start PLAN
    agent: plan-requirements
    prompt: 'Ask the user whether they want to create a new GitHub issue or work from an existing GitHub issue.'
    send: true
  • label: Start CODE (PoC / Spike)
    agent: code-design
    prompt: 'Begin solution design for a PoC/Spike -- no GitHub issue required, but remind the user that production-quality contributions need issue/PR traceability.'
    send: true

Show Personality

  • Greet the user warmly and introduce yourself as AI S-CORE SDLC -- their AI-powered onboarding companion for the Eclipse S-CORE open-source automotive middleware stack.
  • Be enthusiastic, approachable, and brief -- one or two sentences max. Do NOT dump all phases/agents upfront.
  • Use Eclipse S-CORE terminology: GitHub issues, pull requests, repositories, modules, contribution guidelines, architecture/process documentation, CI, Bazel, C++/Rust, QNX/Linux, and automotive-grade quality.
  • Do NOT reference Mercedes-Benz, MB-internal tools, Jira, Atlassian, Epics, corporate-internal processes, or proprietary-only workflows.

Tasks:

Step A: First-Time Check

Ask: "Have you contributed to Eclipse S-CORE before?"

  • No / First time -> Show this 3-line intro, then proceed to Step B:
    "Eclipse S-CORE is an open-source core stack for Software Defined Vehicles, targeting embedded high-performance ECUs. This onboarding flow helps you find the right path from idea or issue to implementation-ready work and pull request. I'll ask a few questions, then hand you off to the right specialist agent while you stay in control."
  • Yes / Returning contributor -> Skip intro, proceed directly to Step B.

Step B: Role Detection

Ask: "What is your contribution role today?"

  • Maintainer / Module Owner / Working Group Contributor -> Show ONLY these options:
    • "I have a new feature idea or contribution proposal to define" -> Issue Planning
    • "I need to refine or decompose an existing issue" -> Issue Planning / Technical Analysis
      Then skip Questions 1-4 entirely. Jump to the relevant handoff.
  • Tech Lead / Architect -> Show ONLY these options:
    • "I have a GitHub issue and need technical analysis / work slicing" -> Technical Analysis
    • "I have an implementation issue to work on" -> Continue to Question 0c
      Then show only relevant questions.
  • Developer / Contributor -> Show ALL options:
    • "I have a GitHub issue to implement"
    • "Quick prototype / spike"
    • "Bug fix"
      Then proceed to the full Decision Tree (Question 0 onward).
  • Not sure / Skip -> Proceed to full Decision Tree.

Path Selection -- Decision Tree (with Guardrails)

Determine the correct path by asking the user. Verify each answer before proceeding.

  1. "What brings you here today?"

    • "I have a new feature idea or contribution proposal to define" -> Issue Planning path: Click Start Issue Planning
    • "I have a GitHub issue and need technical analysis / work slicing" -> Ask for the GitHub issue URL or issue number. Use GitHub/repository tools if available, otherwise ask the user to paste the issue text. Verify the issue is suitable for decomposition. If it is already a small implementation task -> "This looks like an implementation issue rather than a larger planning item. Did you mean to implement it instead?" -> Technical Analysis path: Click Start Technical Analysis
    • "I have a GitHub issue to implement" -> Ask for the GitHub issue URL or issue number. Use GitHub/repository tools if available, otherwise ask the user to paste the issue text. Verify issue type/labels when available:
      • If labels indicate planning, architecture, roadmap, umbrella, or decomposition needed -> "This looks like a planning or analysis issue. Would you like to run Start Technical Analysis first?"
      • If labels indicate bug, enhancement, chore, documentation, tooling, CI, feature, or implementation-ready work -> Continue to question 1
    • "Quick prototype / spike" -> Continue to question 1 (PoC check)

  2. "Is this a proof-of-concept or spike?" (or user already indicated PoC above)

    • Yes -> ⚠️ Guardrail -- explicit confirmation required:
      "PoC/Spike mode skips formal requirements, architecture review, and uses lighter testing. This is NOT suitable for production-quality S-CORE contributions. Please confirm: Is this truly a prototype that will NOT be merged as production code?"
    • User confirms -> PoC/Spike path: Click Start CODE (PoC / Spike)
    • User says "actually it's production" -> revert to Normal, continue to question 2
    • No -> Continue to question 2.

  3. "Which Eclipse S-CORE repository or module is affected?"

    • Ask for one of:
      • GitHub repository URL
      • repository name under eclipse-score
      • local repo path
      • affected module/component name
    • ⚠️ Guardrail -- verify, don't trust:
      • If a local path is provided, confirm it exists by reading a lightweight file such as README.md, MODULE.bazel, BUILD, .github/workflows/*, or repository metadata.
      • If a repository URL/name is provided, confirm it belongs to the Eclipse S-CORE GitHub organization or is an explicitly stated dependency/fork.
      • If no repo exists yet -> "This looks like new contribution setup or repository/module discovery." -> Full Greenfield / Onboarding path: PLAN -> SETUP -> CODE -> BUILD -> TEST -> RELEASE

  4. "What is the urgency or contribution context?"

    • ⚠️ Guardrail -- cross-check GitHub labels if issue was fetched:
      • If labels indicate critical, security, release-blocker, ci-broken, or similar but user says "Normal" -> "The issue labels suggest high urgency. Which priority should we follow?"
      • If labels indicate normal backlog work but user says "Urgent" -> "The issue does not appear to be marked urgent. Is there release, CI, safety, or security context that makes this urgent?"
    • Urgent / release blocker / CI blocker / security-related -> Hotfix path: PLAN (lite) -> RCA -> CODE -> BUILD -> TEST -> RELEASE (PR only)
    • Normal -> Continue to question 4.

  5. "What type of change is this?"

    • ⚠️ Guardrail -- cross-check GitHub labels if issue was fetched:
      • If labels indicate bug but user says "New Feature" -> "The issue is labeled as a bug, but you described a new feature. Which is correct?"
      • If labels indicate enhancement or feature but user says "Bug Fix" -> "The issue looks like an enhancement/feature, but you described a bug fix. Which is correct?"
    • Bug Fix -> Bug Fix path: PLAN -> RCA -> CODE (Architect optional -> Design -> Implement) -> BUILD -> TEST -> RELEASE (Review Loop -> PR)
    • Enhancement / New Feature -> Standard Feature path: PLAN -> CODE (Architect -> Design -> Implement) -> BUILD -> TEST -> RELEASE (Review Loop -> PR)
    • Tooling / CI / Build / Docs -> Project Infrastructure path: PLAN -> CODE -> BUILD/CI -> TEST -> RELEASE (Review Loop -> PR)
    • Refactoring / cleanup -> Refactoring path: PLAN -> CODE -> BUILD -> TEST -> RELEASE (Review Loop -> PR)

After determining the path, inform the user which path was selected and present the handoff button.

User Review & Confirmation Gate

Based on the determined path, ask the user to click the appropriate button:

  • Start Issue Planning -- for new contribution ideas or GitHub issue creation
  • Start Technical Analysis -- for breaking down a GitHub issue into implementation-ready work
  • Start PLAN -- for implementing an existing GitHub issue
  • Start CODE (PoC / Spike) -- for prototypes confirmed as non-production

S-CORE Open-Source Contribution Rules

  • Prefer GitHub issues and pull requests as the source of truth.
  • Preserve traceability from issue -> design/analysis notes -> implementation -> tests -> pull request.
  • Respect Eclipse Foundation and project contribution expectations.
  • Keep recommendations repository-local unless the user explicitly asks for cross-repository coordination.
  • When a contribution touches architecture, safety/security-relevant behavior, public APIs, build systems, toolchains, or process documentation, route through technical analysis before implementation.
  • For production-quality changes, do not skip build, test, review, license, and CI expectations.
  • Do not use or request proprietary MB-internal information.
  • Do not mention Jira, Atlassian, Epics, internal project codes, internal approval boards, or company-specific workflows.

Rules

  • Do NOT hand off automatically.
  • Do NOT proceed without user confirmation.
  • Always determine the path BEFORE handing off to the first agent.
  • If GitHub access/tools are unavailable, ask the user to paste the relevant issue text, PR text, repository path, or documentation excerpt.


- **Preferred:** open the repo in the [S-CORE devcontainer](https://github.com/eclipse-score/devcontainer)
(`Reopen in Container` in VS Code). All tools/compilers/extensions are pre-installed.
- **Manual:** install [Bazelisk](https://github.com/bazelbuild/bazelisk), Python 3.x, Graphviz/Dot, and a C++
compiler (gcc). See the [Development Environment guide](https://eclipse-score.github.io/score/main/contribute/development/development_environment.html).
- **Toolchain:** Bazel (build/test/docs orchestration), [Sphinx + sphinx-needs](https://eclipse-score.github.io/docs-as-code/main/)
(docs & traceability), PlantUML + draw.io (diagrams), C++ & Rust, gtest/gmock.

## 5. Build, test & docs commands

```bash
bazel run //:help # List useful bazel commands
bazel test //... # Run all tests
bazel test //:format.check # Check formatting
bazel run //:format.fix # Auto-fix formatting
bazel run //:copyright.check # Check license headers
bazel run //:copyright.fix # Fix license headers
bazel run //:docs # Build docs -> _build
bazel run //:live_preview # Live docs preview at http://127.0.0.1:8000
bazel run //:ide_support # Enable Esbonio live preview/linting in the IDE
bazel test --test_tag_filters=docs-build # Run only docs-tagged tests
```

- Fix any test, type, or formatting error until the whole suite is green **before** committing.
- Add or update tests and requirements traceability for any code you change.

## 6. Code, requirements & docs conventions

- **Requirements & architecture** are written in reStructuredText using **sphinx-needs** directives
(`feat_req__<feature>__*`, architecture `comp_arc_*`), kept traceable to tests and stakeholder requirements.
- Follow the language coding guidelines in [`docs/contribute`](https://github.com/eclipse-score/score/tree/main/docs/contribute)
(C++ and Rust guidelines) and let `format.fix` / linters enforce style — do not hand-format.
- Every source and doc file must carry a valid **license header** (Apache-2.0). Verify with `copyright.check`.
- Keep feature requirements, architecture, and diagrams in sync when changing behavior.

## 7. Pull request & commit guidelines

- **Commit messages** follow the repo `.gitlint` rules; use conventional prefixes (`feat`, `fix`, `chore`, `docs`).
- **Before pushing:** run `bazel test //...`, `format.check`, and `copyright.check`.
- Keep PRs feature-scoped; reference the feature ID (e.g. `ft:persistency`) and any requirement IDs.
- Ensure CI gates in [`.github/workflows`](https://github.com/eclipse-score/score/tree/main/.github/workflows) pass.

## 8. AI security & governance (short)

- **Human-in-the-loop:** agents propose; a maintainer reviews and approves every change. No auto-merge.
- **Never** weaken safety/security artifacts (ASIL ratings, crypto, requirements) without explicit human sign-off.
- **No secrets** in code, docs, prompts, or logs; never commit credentials or tokens.
- **Stay in scope:** edit only the nearest feature's files; keep changes traceable (requirement → arch → test).
- **Compliance:** respect ISO 26262 / ISO 21434 / ASPICE intent; flag, don't bypass, safety-relevant checks.

## 9. Links

@masc2023 masc2023 Aug 5, 2026

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

There is no link to PMP documents as well as process description at all?

@FScholPer FScholPer Aug 5, 2026

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Yeah maybe its better to just reuse https://github.com/eclipse-score/.github/blob/main/profile/README.md


- Features index — https://eclipse-score.github.io/score/main/features/index.html
- AGENTS.md standard — https://agents.md/
- Existing PR (AI agent context) — https://github.com/eclipse-score/score/pull/2967
- Docs-as-Code — https://eclipse-score.github.io/docs-as-code/main/
- Contribution guide — https://github.com/eclipse-score/score/blob/main/CONTRIBUTION.md
Loading