UCP Skill — Universal Commerce Protocol Implementation

Core Principles

1. Edge runtime is NOT USED — Only Node.js (default) or Bun (opt-in) runtimes
2. Interactive error handling — When ambiguous, ask the user how to proceed
3. Config-driven — All decisions persist in ucp.config.json
4. Spec-grounded — All implementations reference the canonical UCP specification
5. Next.js conventions — Follow App Router patterns for code organization
6. Deep analysis — Use AST parsing and data flow tracing for gap detection

---

Spec Repository Handling

Location Priority

Check in this order:

1. ./ucp/ — User's local copy (use as-is)
2. ./.ucp-spec/ — Previously cloned spec (update it)
3. Neither exists — Clone fresh

Clone Procedure

When cloning is needed:

git clone --depth 1 https://github.com/Universal-Commerce-Protocol/ucp.git .ucp-spec

If HTTPS fails, try SSH:

git clone --depth 1 [email protected]:Universal-Commerce-Protocol/ucp.git .ucp-spec

Update Procedure

When ./.ucp-spec/ exists:

cd .ucp-spec && git pull && cd ..

Gitignore Management

After cloning, ensure .ucp-spec/ is in .gitignore:

• Read .gitignore if it exists
• Check if .ucp-spec/ or .ucp-spec is already listed
• If not, append .ucp-spec/ on a new line

Spec File Locations (read on demand)

docs/specification/overview.md
docs/specification/checkout.md
docs/specification/checkout-rest.md
docs/specification/checkout-mcp.md
docs/specification/checkout-a2a.md
docs/specification/embedded-checkout.md
docs/specification/order.md
docs/specification/fulfillment.md
docs/specification/discount.md
docs/specification/buyer-consent.md
docs/specification/identity-linking.md
docs/specification/ap2-mandates.md
docs/specification/payment-handler-guide.md
docs/specification/tokenization-guide.md
spec/services/shopping/rest.openapi.json
spec/services/shopping/mcp.openrpc.json
spec/services/shopping/embedded.openrpc.json
spec/handlers/tokenization/openapi.json
spec/schemas/shopping/*
spec/discovery/profile_schema.json

---

Configuration File

Location

./ucp.config.json at project root

Schema

{
  "$schema": "./ucp.config.schema.json",
  "ucp_version": "2026-01-11",
  "roles": ["business"],
  "runtime": "nodejs",
  "capabilities": {
    "core": ["dev.ucp.shopping.checkout"],
    "extensions": []
  },
  "transports": ["rest"],
  "transport_priority": ["rest", "mcp", "a2a", "embedded"],
  "payment_handlers": [],
  "features": {
    "ap2_mandates": false,
    "identity_linking": false,
    "multi_destination_fulfillment": false
  },
  "domain": "",
  "existing_apis": {},
  "policy_urls": {
    "privacy": "",
    "terms": "",
    "refunds": "",
    "shipping": ""
  },
  "scaffold_depth": "full",
  "generated_files": [],
  "answers": {},
  "deployment": {
    "platform": "vercel",
    "region": "iad1",
    "mcp": {
      "enabled": false,
      "max_duration": 60
    }
  }
}

Field Descriptions

Field	Type	Description
ucp_version	string	UCP spec version (date-based)
roles	string[]	One or more of: business, platform, payment_provider, host_embedded
runtime	string	nodejs (default) or bun
capabilities.core	string[]	Required capabilities to implement
capabilities.extensions	string[]	Optional extensions to implement
transports	string[]	Enabled transports: rest, mcp, a2a, embedded
transport_priority	string[]	Order to implement transports
payment_handlers	string[]	Payment handler IDs to support
features.ap2_mandates	boolean	Enable AP2 mandate signing
features.identity_linking	boolean	Enable OAuth identity linking
features.multi_destination_fulfillment	boolean	Enable multi-destination shipping
domain	string	Business domain for /.well-known/ucp
existing_apis	object	Map of existing API endpoints to analyze
policy_urls	object	URLs for privacy, terms, refunds, shipping policies
scaffold_depth	string	types | scaffolding | full
generated_files	string[]	Files created by scaffold (for tracking)
answers	object	Raw answers to qualifying questions

---

Sub-command: (no argument)

Trigger

User runs /ucp with no sub-command

Behavior

Display help listing all available sub-commands:

UCP Skill — Universal Commerce Protocol Implementation

Available commands:
  /ucp init      — Initialize UCP in this project (clone spec, create config)
  /ucp consult   — Full consultation: answer qualifying questions, build roadmap
  /ucp plan      — Generate detailed implementation plan
  /ucp gaps      — Analyze existing code against UCP requirements
  /ucp scaffold  — Generate full working UCP implementation
  /ucp validate  — Validate implementation against UCP schemas
  /ucp profile   — Generate /.well-known/ucp discovery profile
  /ucp test      — Generate unit tests for UCP handlers
  /ucp docs      — Generate internal documentation

Typical workflow:
  /ucp init → /ucp consult → /ucp plan → /ucp scaffold → /ucp profile → /ucp test → /ucp validate

Configuration: ./ucp.config.json
Spec location: ./ucp/ or ./.ucp-spec/

---

Sub-command: init

Trigger

User runs /ucp init

Purpose

Bootstrap UCP in a project: clone spec, create config, ask essential questions.

Procedure

Step 1: Check/Clone Spec Repository

1. Check if ./ucp/ exists
   • If yes: "Found local UCP spec at ./ucp/"
2. If not, check if ./.ucp-spec/ exists
   • If yes: Run git pull to update
   • If no: Clone the repo (see Spec Repository Handling)
3. After cloning, add .ucp-spec/ to .gitignore

Step 2: Check for Existing Config

1. Check if ./ucp.config.json exists
2. If yes, ask: "Config file exists. Overwrite, merge, or abort?"
   • Overwrite: Delete and create fresh
   • Merge: Keep existing values as defaults
   • Abort: Stop init

Step 3: Ask Essential Questions (4 questions)

Q1: What role(s) are you implementing?

• Business (merchant of record)
• Platform (consumer app or agent)
• Payment credential provider
• Host embedding checkout
• Multiple (specify)

If user selects multiple roles, WARN:

"Implementing multiple roles is unusual. This is typically for marketplace/aggregator scenarios. Are you sure?"

Q2: What runtime will you use?

• Node.js (recommended, stable)
• Bun (opt-in, experimental)

NOTE: If user mentions Edge, respond:

"Edge runtime is not supported for UCP implementations. Please choose Node.js or Bun."

Q3: What is your business domain?

• The domain that will host /.well-known/ucp
• Example: shop.example.com

Q4: Which transports do you need at launch?

• REST (recommended baseline)
• MCP (Model Context Protocol)
• A2A (Agent-to-Agent)
• Embedded (iframe checkout)

Step 4: Create Config File

Create ./ucp.config.json with:

• Answers from essential questions
• Sensible defaults for other fields
• ucp_version set to latest from spec

Step 5: Output Ready Message

UCP initialized successfully!

Config: ./ucp.config.json
Spec:   ./.ucp-spec/ (or ./ucp/)
Role:   {role}
Domain: {domain}

Next steps:
  /ucp consult  — Complete full consultation (recommended)
  /ucp plan     — Skip to implementation planning
  /ucp gaps     — Analyze existing code first

---

Sub-command: consult

Trigger

User runs /ucp consult

Purpose

Walk through all 12 qualifying questions, update config, produce implementation roadmap.

Prerequisites

• Config file must exist (run /ucp init first)
• Spec must be available

Procedure

Step 1: Load Existing Config

Read ./ucp.config.json and use existing answers as defaults.

Step 2: Walk Through 12 Qualifying Questions

Ask each question. If already answered in config, show current value and ask to confirm or change.

Q1: Are we implementing the business side, the platform side, or both?

• Map to roles in config
• If both/multiple, warn about unusual scenario

Q2: Which UCP version and which capabilities/extensions are in scope?

• Read available versions from spec
• Present capability options:
  • Core: dev.ucp.shopping.checkout (required)
  • Extensions:
    • dev.ucp.shopping.fulfillment
    • dev.ucp.shopping.discount
    • dev.ucp.shopping.buyer_consent
    • dev.ucp.shopping.ap2_mandate
    • dev.ucp.shopping.order
    • dev.ucp.common.identity_linking

Q3: Which payment handlers do we need?

• Wallets (Apple Pay, Google Pay)
• PSP tokenization (Stripe, Adyen, etc.)
• Custom handler
• None yet (decide later)

Q4: Do we need AP2 mandates and signing key infrastructure?

• Yes → set features.ap2_mandates: true
• No → set features.ap2_mandates: false
• If yes, explain: "You'll need to provide JWS signing keys (ES256 recommended)"

Q5: Do we need fulfillment options and multi-group/multi-destination support?

• No fulfillment needed
• Single destination only
• Multi-destination support → set features.multi_destination_fulfillment: true

Q6: Do we need discounts, buyer consent capture, or identity linking?

• Discounts → add dev.ucp.shopping.discount to extensions
• Buyer consent → add dev.ucp.shopping.buyer_consent to extensions
• Identity linking → add dev.ucp.common.identity_linking, set features.identity_linking: true

Q7: What are the existing checkout and order APIs we should map to UCP?

• Ask for existing endpoint paths
• Store in existing_apis object
• Examples: /api/checkout, /api/cart, /api/orders

Q8: What are the required policy URLs?

• Privacy policy URL
• Terms of service URL
• Refund policy URL
• Shipping policy URL
• Store in policy_urls object

Q9: What authentication model is required for checkout endpoints?

• None (anonymous checkout)
• API key
• OAuth 2.0
• Session-based
• Store in answers.authentication_model

Q10: Who will receive order webhooks and what event cadence is required?

• Webhook URL for order events
• Event types needed: order.created, order.updated, order.fulfilled, order.canceled
• Store in answers.webhook_config

Q11: Do we need to support MCP, A2A, or embedded checkout at launch?

• Confirm/update transports array
• Set transport_priority order

Q12: What is the business domain that will host /.well-known/ucp?

• Confirm/update domain field

Step 3: Update Config

Write all answers to ./ucp.config.json

Step 4: Generate Implementation Roadmap

Based on answers, produce a roadmap:

UCP Implementation Roadmap
==========================

Role: Business (merchant)
Version: 2026-01-11
Domain: shop.example.com

Capabilities to implement:
  ✓ dev.ucp.shopping.checkout (core)
  ✓ dev.ucp.shopping.fulfillment
  ✓ dev.ucp.shopping.discount
  ○ dev.ucp.shopping.order

Transports (in order):
  1. REST
  2. MCP

Payment handlers:
  - Stripe tokenization

Key implementation tasks:
  1. Create /.well-known/ucp discovery profile
  2. Implement checkout session endpoints (create, get, update, complete)
  3. Implement fulfillment options logic