Ucp

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 git@github.com: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

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/"

1. If not, check if ./.ucp-spec/ exists

• If yes: Run git pull to update
• If no: Clone the repo (see Spec Repository Handling)

1. 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.