Proposal to rename app-sdk

[jparello]

Proposal: Rename app-sdk to reference-app-sdk for clearer positioning

Summary

This issue proposes renaming the current agntcy/app-sdk repository to agntcy/reference-app-sdk.

The goal is to make the repository name more precise before broader partner adoption, additional proof-of-concept work, and positioning. This is being proposed as a clarification and precision change, not because we have evidence of broad partner confusion.

The app-sdk and coffeeAgntcy goals are outlined in the WG charter. /governance/blob/main/working-groups/coffee-app-sdk/charter.md

The current README already states that app-sdk is intended as an integration and learning surface primarily used with CoffeeAGNTCY, not as the canonical or prescriptive SDK for all AGNTCY subsystems. The proposed rename makes that positioning visible directly in the repository name.

Audiences

This proposal is intended for two audiences:

1. Working Group: To review the practical engineering, documentation, packaging, and partner-impact details.
2. TSC: To review the governance, ecosystem positioning, and timing implications of the rename.

Background

The app-sdk repository is currently used as a reference integration layer for CoffeeAGNTCY and related AGNTCY application patterns. It helps demonstrate how application developers can compose or integrate AGNTCY capabilities across components such as messaging, discovery, identity, observability, and workflows.

The repository is not intended to be the canonical SDK for every AGNTCY subsystem. Component-specific SDKs should remain owned and versioned by their respective component teams.

The current README disclaimer already reflects this positioning. However, the name app-sdk can still be read as broader than intended when viewed in isolation.

Given that we currently have nine proof-of-concept engagements in flight, any repository rename or package-level change could introduce breaking changes or partner disruption if handled poorly. For that reason, this should be handled deliberately, with a short transition plan and clear communication.

Why this change is being proposed

This change is being proposed to make the repository name more precise and to reduce future ambiguity.

Specifically:

• The current name app-sdk may imply a general-purpose or canonical AGNTCY application SDK.
• The actual role of the repo is more specific: a reference application SDK / integration surface used with CoffeeAGNTCY and related reference patterns.
• The README already clarifies this, but the repository name should also reflect the intended scope.
• The rename should be done now, before more proof-of-concept work depends on the current repository name.
• This is a proactive precision change, not a reaction to demonstrated systemic confusion from partners.

Proposed repository rename

Rename:

agntcy/app-sdk

To:

agntcy/reference-app-sdk

Proposed positioning

Suggested short positioning statement:

reference-app-sdk is a reference integration SDK used by CoffeeAGNTCY and related AGNTCY application patterns. It provides a learning and integration surface for building multi-agent reference applications with AGNTCY components. It is not the canonical SDK for every AGNTCY subsystem.

Proposed repo taxonomy

This rename should be part of a clearer AGNTCY repository taxonomy:

Category	Purpose	Example
Component implementations	Implement AGNTCY runtime components	slim, directory-related repos
Component SDKs	SDKs owned by component teams	ACP SDK, Directory SDKs
Reference applications	End-to-end use cases and patterns	coffeeAgntcy
Reference integration SDKs	Integration and learning surfaces for reference apps	reference-app-sdk
Experimental demos	Incubation, experiments, and examples	TBD

Required changes

1. Repository rename

• Rename GitHub repository from agntcy/app-sdk to agntcy/reference-app-sdk.
• Confirm GitHub redirects from the old repo URL continue to work.
• Update repository description.
• Update repository topics if needed.
• Confirm branch protections, maintainers, CODEOWNERS, and settings remain intact after rename.

2. README updates and Charter

Update the WG charter to show the renamed repository

Update the README so the positioning is clear above the fold.

Add a concise opening statement:

reference-app-sdk is a reference integration SDK used by CoffeeAGNTCY and related AGNTCY application patterns. It is intended as a learning and integration surface for reference applications, not as the canonical SDK for every AGNTCY subsystem.

Add a What this is / What this is not table:

This is	This is not
A reference integration SDK used by CoffeeAGNTCY	The canonical SDK for every AGNTCY subsystem
A learning surface for application developers	A replacement for component-specific SDKs
A place to demonstrate cross-component application patterns	A standards authority
A bridge across AGNTCY components in reference app contexts	Ownership of the underlying components

Add or update sections for:

• Purpose and scope.
• Relationship to CoffeeAGNTCY.
• Relationship to component SDKs.
• Versioning expectations.
• Compatibility notes for existing proof-of-concept users.
• Migration instructions from app-sdk to reference-app-sdk.

3. CoffeeAGNTCY README updates

In coffeeAgntcy, update references to app-sdk and clarify the relationship:

• Replace repo references from app-sdk to reference-app-sdk.
• Add a short explanation that CoffeeAGNTCY uses reference-app-sdk as its reference integration SDK.
• Clarify that CoffeeAGNTCY remains the end-to-end reference application and use case implementation.
• Ensure setup docs, architecture docs, workflow docs, and developer guides reference the new repo name.

Suggested text:

CoffeeAGNTCY uses reference-app-sdk as its reference integration SDK. The SDK provides a practical learning and integration layer for this reference application. Component-specific SDKs remain owned by their respective AGNTCY component teams.

4. Package and import compatibility

Decision needed from the WG:

• Should the package name change, or should only the repository name change first?
• Should existing imports remain supported for a transition period?
• Should a compatibility shim be provided?
• Should deprecation warnings be added in a later release?

Recommended approach:

1. Phase 1: Repository rename only

   • Rename the repo to reference-app-sdk.
   • Keep package and import names stable temporarily.
   • Update docs and examples.
   • Avoid immediate breaking changes for the 9 active proof-of-concepts.

2. Phase 2: Package rename proposal if needed

   • Open a separate issue if the WG decieds package/import names need to change.
   • Include compatibility shims and migration guidance.
   • Set a deprecation window.

3. Phase 3: Cleanup

   • Remove old references after proof-of-concept teams have migrated.
   • Archive or redirect old docs as needed.

5. Documentation and link updates

Update references in:

• app-sdk README and docs.
• coffeeAgntcy README and docs.
• AGNTCY docs site references, if any.
• Workshop materials.
• Partner onboarding material.
• Architecture diagrams.
• GitHub Projects or issue templates.
• Release notes.
• Any public blog, demo, or slide links where practical.

6. CI/CD and release updates

• Update repository references in CI workflows.
• Update Docker/build references if present.
• Update package metadata.
• Update release automation.
• Confirm version tags and GitHub releases remain discoverable.
• Confirm downstream examples still build.
• Confirm CoffeeAGNTCY setup still works from a clean checkout.

7. Partner and proof-of-concept impact

Because there are 9 proof-of-concept engagements currently in flight, the WG should explicitly manage partner impact.

• Identify active proof-of-concept consumers of app-sdk.
• Identify whether they depend on repo URL, package name, import path, Docker image, docs links, or examples.
• Provide a migration note.
• Avoid package/import breaking changes in the first rename phase unless absolutely required.
• Communicate the rename as a precision and clarity improvement.

Suggested partner-facing note:

We are renaming `app-sdk` to `reference-app-sdk` to make the repository scope more precise. This repo remains the reference integration SDK used with CoffeeAGNTCY and related AGNTCY application patterns. This is a naming clarification only; it is not intended to change the role of the repo or disrupt current proof-of-concept work.

Suggested timeline

Option A: Conservative timeline

Timeframe	Action
Week 0	WG reviews proposal and confirms scope
Week 1	Notify the TSC of positioning and governance implications
Week 2	Rename repo, update README, update CoffeeAGNTCY references
Week 3	Validate CI, examples, partner setup docs, and redirects
Weeks 4-6	Monitor proof-of-concept impact and collect issues
Later	Decide whether package/import names should change

Option B: Faster timeline

Timeframe	Action
Days 0-2	WG async review
Days 3-5	TSC awareness / approval if needed
Week 1	Rename repo and update top-level docs
Week 2	Complete docs, CI, and CoffeeAGNTCY references
Weeks 3-4	Monitor partner impact

Recommended path: Option A if TSC governance review is required. Option B if the change is treated as a repository clarification with no package/import rename.

Packaging recommendation

Recommended initial packaging approach:

• Keep the current package name and import paths stable during the first phase.
• Rename only the GitHub repository and documentation references first.
• Add clear README language explaining the new repo name and compatibility behavior.
• Create a separate WG issue for any package/import rename if needed.
• Only introduce package-level breaking changes after the active proof-of-concept impact is understood.

This avoids unnecessary disruption while still improving ecosystem clarity.

TSC considerations

The TSC may want to review:

• Whether reference-app-sdk is the right final repo name.
• Positioning of the repo category and taxonomy in other repos (state what is canonical and what is exmaple)
• Our WG would remind the TSC

Guiding Principle

Confirm that app-sdk serves as a neutral onboarding and integration surface while canonical interfaces remain owned by the individual AGNTCY working groups as per charter

Partner Onboarding

Confirm that adopters may onboard through any natural path app-sdk, reference applications, or component SDKs based on their needs.

Component Relationship

Confirm that app-sdk is intended to complement component SDKs and does not replace them.

Governance

Confirm that changes to the role, scope, or charter follow normal working group and governance processes.

Positioning and Documentation

Confirm that confusion should first be addressed through documentation and positioning an dissues before structural changes are considered.

Success Metrics

Confirm that ecosystem adoption and successful outcomes are primary measures of success.

Rename or Structural Changes

Confirm that any proposed rename or restructuring is tied to a clearly defined problem, evidence, and expected outcome.

Working Group decision points

• Approve reference-app-sdk as the new repo name.
• Confirm whether this is a repository-only rename for now.
• Confirm no immediate package/import breaking change.
• Confirm README positioning language.
• Confirm migration note for the 9 active proof-of-concept engagements.
• Confirm target timeline.
• Confirm whether TSC approval is required before execution.

Proposed decision

Approve the repository rename from app-sdk to reference-app-sdk, with no immediate package/import breaking change.

Proceed with README, documentation, and CoffeeAGNTCY updates immediately after WG and TSC alignment.

Package/import renaming, if needed, should be handled as a separate follow-up proposal with a defined compatibility and deprecation plan.

[jparello]

See #608

Overwhelming feedback is to rename the description and not introduce any breaking change to the PoCs in flight.

Also open issue on ACP as those descriptions have been creating far more issues.

[pregnor]

Shouldn't this be taken over to https://github.com/agntcy/app-sdk ?
IMO we should create a clone issue there and close this as this is not coffeeAgntcy related.