Skip to content

docs: add discovery rules and agent checkout flow #18

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

Jump to bottom
Open
omsaisudarshan108 wants to merge 1 commit into
base: main
Choose a base branch
from
Open

docs: add discovery rules and agent checkout flow #18

omsaisudarshan108 wants to merge 1 commit into from

Conversation

@omsaisudarshan108
Copy link

@omsaisudarshan108 omsaisudarshan108 commented Jan 12, 2026

Summary

  • Expand the discovery profile example in docs/specification/overview.md with Cart, Loyalty, and Post-Order capabilities.
  • Add profile validation rules to clarify required fields and constraints.
  • Add an agent checkout reference flow (sequence diagram + minimal payloads) in docs/specification/checkout-rest.md.
  • Add scripts/regenerate_artifacts.sh and document it in CONTRIBUTING.md.

Testing

  • Not run (docs/script change)

@omsaisudarshan108 omsaisudarshan108 requested a review from a team January 12, 2026 08:41
@jingyli
Copy link
Contributor

jingyli commented Jan 13, 2026

Thank you for your contribution to the Universal Commerce Protocol!

While we appreciate your enthusiasm for UCP, this PR currently seems to be bundling a few things together. To break it down:

  1. Expanding discovery profile example to include additional capabilities/extensions: Given some of the added capabilities/extensions are not UCP-governed constructs, we will decline this part of the change per reasons given in Feat/cart loyalty post order #17. We welcome you to define your own capabilities & extensions, host them on your own domain, and reference them in the profile as long as they follow UCP's governance model.

  2. Documentation updates on minimal payload & sequence diagram & new command definition: We will be evaluating the changes and will provide a formal response within 1-2 weeks, but we encourage you to clean up this PR's scope to be specific to those changes to help with our review process.

@omsaisudarshan108 @claude
docs: add discovery validation rules and agent checkout flow
d5f29e6 
This PR focuses on documentation improvements:

1. Profile Validation Rules: Adds clear validation requirements for
   discovery profiles including version format, service requirements,
   endpoint format, and capability reference constraints.

2. Agent Checkout Reference Flow: Documents the canonical REST
   checkout sequence with a Mermaid diagram and minimal payload examples
   showing the create → update → complete flow.

3. Developer Tooling: Adds regenerate_artifacts.sh script to simplify
   the workflow for regenerating schemas and SDK models in one command.

The discovery profile example now only includes UCP-governed capabilities
(checkout, fulfillment, discount) following governance guidelines.

Co-Authored-By: Claude Sonnet 4.5 <noreply@anthropic.com>
@omsaisudarshan108 omsaisudarshan108 force-pushed the feat/discovery-sdk-agent-flow branch from b397704 to d5f29e6 Compare January 17, 2026 15:00
@omsaisudarshan108
Copy link
Author

omsaisudarshan108 commented Jan 17, 2026

PR Update - Addressed Maintainer Feedback
Thank you @jingyli for the detailed feedback! I've updated this PR to focus specifically on the documentation improvements as requested.

Changes Made
✅ Removed: Non-UCP-governed capabilities from discovery profile example

Removed dev.ucp.shopping.cart
Removed dev.ucp.shopping.loyalty
Removed dev.ucp.shopping.post_order
The business profile example now only includes UCP-governed capabilities (checkout, fulfillment, discount) following the governance model.

✅ Kept: Documentation improvements

Profile Validation Rules (lines 359-370 in overview.md)

Clear validation requirements for discovery profiles
Version format, service requirements, endpoint constraints
Capability reference validation rules
Agent Checkout Reference Flow (checkout-rest.md)

Mermaid sequence diagram showing canonical REST flow
Minimal payload examples for create and complete operations
Demonstrates the create → update → complete pattern
Developer Tooling

New scripts/regenerate_artifacts.sh convenience script
Updated CONTRIBUTING.md with usage instructions
Summary
The PR scope is now clean and focused on documentation enhancements. All changes follow UCP governance guidelines and are ready for your evaluation.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Reviewers

No reviews

Assignees

No one assigned

Labels

None yet

Projects

None yet

Milestone

No milestone

Development

Successfully merging this pull request may close these issues.

2 participants

@omsaisudarshan108 @jingyli