~/agent-sdlc / interoperability

AGENT SDLC INTEROPERABILITY PROFILE · V0.1

How they work together.

ORBIT determines what change is justified next. AgDR preserves why a consequential technical decision was made during that work.

Neither standard depends on the other. This profile defines a small, optional way for portable artefacts to reference one another.

v0.1InformativeExperimental interoperability profile

Informative profile. ORBIT and AgDR remain independently conformant. The relationship model described here is optional until adopted normatively by the relevant specifications.

HOW THEY WORK TOGETHER

Independent standards.
Composable artefacts.

Stable identifiers and typed relationships allow artefacts to reference one another without requiring a shared runtime, database, API or universal schema.

ORBIT defines the work context. AgDR can preserve consequential decisions made while carrying out that work.

ORBIT Plan
    ↓
Reconciliation
    ↓
Execution Slice
    ↓
Agent
 ├──→ Code
 └──→ AgDR

EXAMPLE

An AgDR can point to the work it explains.

This record links a decision to an ORBIT execution slice and an acceptance criterion. The relationship is context, not proof.

This record says:

the decision was made while implementing slice-004
the decision contributes context relevant to ac-2

{
  "id": "agdr-12",
  "related": [
    { "rel": "implements", "type": "orbit.execution-slice", "id": "slice-004" },
    { "rel": "contributes-to", "type": "orbit.acceptance-criterion", "id": "ac-2" }
  ],
  "extensions": {}
}

RELATIONSHIP SEMANTICS

Source → target

Relationship direction is always source → target. The source makes the claim; the target is the artefact being referenced.

Relationship	Source → target	Meaning
`related-to`	artefact → artefact	Generic relationship when no stronger meaning applies.
`implements`	artefact → execution slice	Source was created while implementing the target work.
`contributes-to`	artefact → outcome or criterion	Source contributes relevant work, reasoning or evidence toward the target.
`derived-from`	artefact → artefact	Source was derived from the target.
`supersedes`	artefact → artefact	Source replaces the target.
`decision-record`	artefact → AgDR	Target records a consequential decision relevant to the source.
`deliberation-record`	artefact → deliberation record	Target preserves broader deliberation or adjudication.

Registered relationships: related-to · implements · contributes-to · derived-from · supersedes · decision-record · deliberation-record

RELATIONSHIP SHAPE

Small and explicit.

rel is required and names the relationship. type is required and identifies the target type. id is required and identifies the target. href is optional and gives a portable resolution location.

{
  "rel": "implements",
  "type": "orbit.execution-slice",
  "id": "slice-004",
  "href": "https://example.org/orbit/slices/slice-004"
}

COMPLETE EXAMPLES

See the relationship model in full artefacts.

These examples use the native representation of each host specification. The IDs connect the artefacts without forcing one file format.

ORBIT Execution Slice · JSON AgDR Decision Record · Markdown Relationship · JSON / YAML End-to-end composition · Diagram

ORBIT EXECUTION SLICE · JSON

Informative example. Fields match the current ORBIT draft schema.

Copy JSON · View raw JSON

{
  "specVersion": "0.1",
  "id": "slice-004",
  "planId": "plan-auth",
  "outcomeId": "auth",
  "basedOn": {
    "planRevision": 3,
    "reconciliationId": "rec-009",
    "repositories": { "web-app": { "branch": "main", "commit": "81fee032" } }
  },
  "objective": "Configure the existing authentication provider for the corporate identity provider.",
  "why": "Required to satisfy acceptance criterion ac-2.",
  "contributesTo": ["ac-2"],
  "scope": {
    "include": ["Configure the existing provider for corporate SSO"],
    "exclude": ["Authentication architecture redesign"]
  }
}

AgDR DECISION RECORD · MARKDOWN

Informative interoperability extension. Core AgDR conformance does not require relationship metadata.

Copy Markdown · View raw Markdown

---
id: AgDR-0012
timestamp: 2026-09-12T18:42:00Z
agent: codex
model: gpt-5.6
trigger: user-prompt
status: executed
related:
  - rel: implements
    type: orbit.execution-slice
    id: slice-004
  - rel: contributes-to
    type: orbit.acceptance-criterion
    id: ac-2
---

# Use the existing OAuth provider for corporate SSO

> In the context of an existing web application, facing a corporate SSO requirement, I decided to extend the current OAuth provider to preserve session behavior, accepting provider-specific configuration work.

## Context
- The application already contains an OAuth provider.
- The execution slice requires corporate SSO support.

## Options Considered
| Option | Pros | Cons |
| --- | --- | --- |
| Extend the existing provider | Preserves sessions and current integration | Requires provider-specific configuration |
| Add a second authentication framework | Isolates new configuration | Duplicates session and identity handling |

## Decision
Extend the existing provider because it satisfies the slice without introducing a second identity path.

## Consequences
- Existing session behavior remains the default.
- Provider configuration must be tested for corporate identities.

SAME RELATIONSHIP, DIFFERENT SERIALISATIONS

The profile defines semantics, not a mandatory serialisation. ORBIT may be JSON-native while AgDR remains Markdown with YAML frontmatter.

Copy JSON · Copy YAML

{
  "id": "agdr-12",
  "related": [
    { "rel": "implements", "type": "orbit.execution-slice", "id": "slice-004" },
    { "rel": "contributes-to", "type": "orbit.acceptance-criterion", "id": "ac-2" }
  ],
  "extensions": {}
}

rel: implements
type: orbit.execution-slice
id: slice-004

END-TO-END

From plan to decision record.

ORBIT Plan · plan-auth
      │
      └── outcome: auth
             │
             └── criterion: ac-2
                       │
                       ▼
                Reconciliation · rec-009
                       │
                       ▼
               Execution Slice · slice-004
                       │
                       ▼
                    Agent
                       │
                       ├──→ code change
                       │
                       └──→ AgDR · AgDR-0012

Reconciliation determines that slice-004 is justified.
An agent executes the slice and makes a consequential decision.
The agent records that decision as AgDR-0012.
The record references slice-004 with implements.
The record remains useful after the execution session ends.

The relationship means: AgDR-0012 implements slice-004 and contributes context to ac-2.

IDENTIFIERS

Stable identity.

Artefact IDs must remain stable for the lifetime of the artefact. IDs should not be reused. Implementations may use UUIDs, ULIDs or human-readable identifiers. The combination of type and id identifies a target within an interoperability context. An href may provide a portable resolution location.

ARTEFACT TYPES

Registered names.

Agent SDLC types use compact names:

orbit.planorbit.outcomeorbit.acceptance-criterionorbit.reconciliationorbit.execution-sliceagdr.record

External standards may use registered external names or URI-like type identifiers.

UNRESOLVED REFERENCES

Portability across systems.

A relationship remains valid when its target is not locally available. Consumers may display unresolved references. A consumer must not reject an otherwise valid source artefact solely because a target cannot currently be resolved. An AgDR may reference an ORBIT slice stored in a separate planning system.

EXTENSIONS

Namespaced and optional.

Extension namespaces must not change the meaning of core fields. Consumers must ignore namespaces they do not understand and should preserve unknown extensions when rewriting artefacts. Core conformance must not depend on a vendor extension.

{
  "extensions": {
    "apexyard": { "jobId": "job-123" },
    "github": { "pullRequest": 42 }
  }
}

VERSIONING

Each artefact declares its own version.

Relationships may cross specification versions. Consumers should interpret each artefact according to its own declared specVersion. The source and target do not need to use the same version.

EXTERNAL STANDARDS

Participation stays open.

External standards can participate through stable identifiers and typed relationships without becoming part of Agent SDLC. External standards are independently governed and are not part of Agent SDLC.

{ "rel": "deliberation-record", "type": "external.deliberation-record", "id": "record-0042", "href": "https://example.org/deliberation/record-0042" }

External deliberation standards can use this relationship shape without joining Agent SDLC.

CONFORMANCE

Three lightweight roles.

Interop Producer
Emits relationship objects that conform to this profile.

Interop Consumer
Reads relationships, preserves unknown types where possible and does not require local targets.

Interop Resolver
Optionally resolves href values. Resolver support is not required for basic compatibility.

SECURITY

Relationships are claims, not proof.

A relationship does not imply that a target is valid, trusted or conformant. Treat external href values as untrusted input. Do not execute referenced content solely because an artefact links to it.

LIFECYCLE

References preserve history.

Relationships are historical references. Archiving or deleting a target does not invalidate the source artefact. Use supersedes to point to a replacement artefact.

How they work together.

Independent standards.Composable artefacts.

An AgDR can point to the work it explains.

Source → target

Small and explicit.

See the relationship model in full artefacts.

From plan to decision record.

Stable identity.

Registered names.

Portability across systems.

Namespaced and optional.

Each artefact declares its own version.

Participation stays open.

Three lightweight roles.

Relationships are claims, not proof.

References preserve history.

Independent standards.
Composable artefacts.