CEXT-6138: spec process setup and capability discovery design

[obarcelonap]

Description

Introduces spec-driven development infrastructure and the first feature spec.

Spec infrastructure (specs/):

• specs/conventions.md — when to write a spec, two-PR workflow, status model, one-spec-per-ticket rule
• specs/features/_template.md — template for new specs
• Root format:markdown extended to include specs/**/*.md
• AGENTS.md updated with spec authoring guidance

Feature spec (specs/features/CEXT-6138-capability-discovery.md):

• Formal capability discovery mechanism via /__metadata__/openapi.json
• Full OpenAPI spec ships in the SDK package; pre-app-build generates a filtered subset based on active config domains
• Filtered spec bundled into a metadata runtime action at build time (same import … with { type: "json" } pattern as app-config and config actions)
• Auth-gated with IMS bearer token to prevent deployment fingerprinting

Related Issue

CEXT-6138

Motivation and Context

Clients need to know which features and endpoints are active for a given deployment. Today this is inferred at runtime by inspecting API response shapes — a fragile pattern that couples client logic to internal API details. This spec defines a formal discoverability mechanism and establishes the spec process for future SDK features.

How Has This Been Tested?

N/A — spec and tooling only. No runtime code changes.

Types of changes

• Bug fix (non-breaking change which fixes an issue)
• New feature (non-breaking change which adds functionality)
• Breaking change (fix or feature that would cause existing functionality to change)

Checklist:

• I have signed the Adobe Open Source CLA.
• My code follows the code style of this project.
• My change requires a change to the documentation.
• I have updated the documentation accordingly.
• I have read the CONTRIBUTING document.
• I have read the DEVELOPMENT document.
• I have added tests to cover my changes.
• All new and existing tests passed.

[changeset-bot]

⚠️ No Changeset found

Latest commit: c853855

Merging this PR will not cause a version bump for any packages. If these changes should not result in a new version, you're good to go. If these changes should result in a version bump, you need to add a changeset.

This PR includes no changesets

When changesets are added to this PR, you'll see the packages that this PR includes changesets for and the associated semver types

Click here to learn what changesets are, and how to add one.

Click here if you're a maintainer who wants to add a changeset to this PR

[obarcelonap]

@oshmyheliuk thanks for the review, I did a major rework which included changing the spec template, please take a look.

[oshmyheliuk]

I remember we discussed how to reduce the number of runtime actions.
Maybe we can add a new endpoint to one of the already existing actions?

[iivvaannxx]

The only place this would make sense to add is the GET /app-config which is already "taken". We can return it as additional properties maybe tho. For what is worth, if the metadata action is going to return purely static data, the build time should be close to 0. Maybe also the deploy time.

[obarcelonap]

what if we use GET /app-config/openapi.json? this is the same discussion we had about adding new actions for uninstallation process and we decided to keep the actions to the minimum.
@oshmyheliuk @iivvaannxx if you agree I change the spec with this approach.

[iivvaannxx]

Didn't think of that, sounds good to me

[iivvaannxx]

The only place this would make sense to add is the GET /app-config which is already "taken". We can return it as additional properties maybe tho. For what is worth, if the metadata action is going to return purely static data, the build time should be close to 0. Maybe also the deploy time.