Skip to content

docs(#4788): add entity provider design concepts to AGENTS.md #4792

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
fullsend-ai-coder wants to merge 4 commits into
base: main
Choose a base branch
from
+42 −0
Open

docs(#4788): add entity provider design concepts to AGENTS.md #4792

Changes from all commits
Commits
Show all changes
4 commits
Select commit Hold shift + click to select a range
cbc174c
docs(#4788): add entity provider design concepts to AGENTS.md
fullsend-ai-coder[bot] Sep 15, 2026
637fd2c
fix: replace double-hyphen with em dash in AGENTS.md
fullsend-ai-coder[bot] Sep 15, 2026
23e615d
style: run prettier on AGENTS.md to fix formatting check
fullsend-ai-coder[bot] Sep 15, 2026
24d068c
fix: format heading with backticks to match convention in PR #4792
fullsend-ai-coder[bot] Sep 15, 2026
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
42 changes: 42 additions & 0 deletions workspaces/ai-integrations/AGENTS.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -165,6 +165,48 @@ The upstream PR number must be documented in the changeset description or
linked issue so reviewers (human and automated) can verify the upstream
alignment.

## Entity Provider Design Concepts

@fullsend-ai-review fullsend-ai-review Bot Sep 15, 2026

Copy link
Copy Markdown

Choose a reason for hiding this comment

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

[low] coherence-document-structure

The new Entity Provider Design Concepts section is a top-level ## heading providing conceptual reference for openspec/changes/ specifications. The existing ## Specifications > ### OpenSpec specification review subsection (line 57) already provides procedural review guidance for the same artifact path, splitting specification-review guidance across two non-adjacent sections.

Suggested fix: Consider making Entity Provider Design Concepts a ### subsection under the existing ## Specifications heading to co-locate all OpenSpec review guidance.


Reference for reviewing and authoring entity provider specifications
(OpenSpec files under `openspec/changes/`).

### Entity identity

Backstage catalog entities are uniquely identified by `(kind, namespace,
name)`. When multiple providers can emit the same identity tuple, the
specification must state how the provider constructs each component and
what happens when a collision with another provider is possible. If the
provider uses caller-supplied prefixes for scoping, the specification
should define the default and document the collision behavior.

### `locationKey` vs `managed-by-location`

These are distinct mechanisms — do not conflate them:

- **`locationKey`** is set on the entity mutation and determines which
provider owns the entity for processing. The catalog uses it to scope
updates and deletions.
- **`backstage.io/managed-by-location`** is an annotation on the entity
showing provenance (which location ingested it). It is informational.

@fullsend-ai-review fullsend-ai-review Bot Sep 15, 2026

Copy link
Copy Markdown

Choose a reason for hiding this comment

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

[low] API behavior claim accuracy

The documentation states that backstage.io/managed-by-location is informational, but this is an oversimplification. The annotation has functional significance beyond display — it is used by the catalog processing engine for entity refresh flows. Characterizing it as purely informational could lead specification reviewers to underweight issues where a spec incorrectly relies on or omits it.

### Full mutation semantics

`type: 'full'` mutations replace the entire set of entities owned by
the provider's locationKey. An entity absent from the next full mutation
is pruned from the catalog. Specifications must explicitly state what
happens when a previously valid entity becomes unmappable (transient
failure, schema drift): is it pruned or retained from the last
successful sync? If retained, how is the stale state communicated?

### Annotation data contracts

When a specification promises that upstream fields are projected into
catalog annotations, it creates a round-trip contract: the original
value should be recoverable. URL normalization, truncation, or lossy
transforms can violate this. Specifications should state which fields
are preserved exactly and which are normalized, and provide a separate
annotation for the original value when normalization is lossy.

## PR Conventions

- All commits must have an `Assisted-by: <model>` footer below the sign offs
Loading