ucp

What this skill does

# 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:
```bash
git clone --depth 1 https://github.com/Universal-Commerce-Protocol/ucp.git .ucp-spec
```

If HTTPS fails, try SSH:
```bash
git clone --depth 1 [email protected]:Universal-Commerce-Protocol/ucp.git .ucp-spec
```

### Update Procedure
When `./.ucp-spec/` exists:
```bash
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
```json
{
  "$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 th