ramp-card-management

Files (1)

• SKILL.md

SKILL.md (first lines)

# Card Management

## Non-Negotiables

- Use `ListCards` to inspect cards. Do not substitute a funds/spend-allocation
  listing: funds and cards are different entities.
- A card whose underlying lifecycle state is `ACTIVE` can still be locked and
  unable to spend. Never report spendability from lifecycle state alone.
- Treat `is_spendable`, `active_locks`, and `blocking_task_count` as the live
  effective status. Follow each lock's `remediation_action`; an overdue-task
  sanction routes to `ramp-complete-tasks` rather than repeated manual unlock.
- Pass `--agent` for machine-readable JSON output whenever you need to count
  or inspect returned fields programmatically.
- Report the fields returned by the API. Do not invent card lifecycle states.
- After every activation or unlock attempt, call `ListCards` again for the same
  cardholder and exact card UUID. Do not claim success until the postcondition
  reports `is_spendable: true`.

## Workflow

### Step 1: Inspect card status

MCP:

```text
ListCards(rationale="Inspect the user's card and effective lock status")
```

CLI:

```bash
ramp cards list --rationale "Inspect the user's card and effective lock status" --agent
```

In `--agent` mode the response is wrapped in the standard envelope. Card records
live in the returned `cards` array.

Admins and managers can inspect a visible employee's cards by passing that
cardholder's UUID. Resolve the UUID first, then pass `cardholder_user_uuid`.

```bash
ramp users org-chart --rationale "find the employee's user UUID" --agent
ramp cards list --cardholder_user_uuid "USER_UUID" --rationale "Inspect this employee's card and effective lock status" --agent
```

### Step 2: Interpret effective status

Match the intended card by its `id`, `last_four`, `display_name`, and cardholder.
Inspect its effective lock fields before acting:

- `is_spendable: false` means the card cannot spend even if `card_state` is
  `ACTIVE` or `is_locked` is false.
- `active_locks` lists every effective `CARD` or
  `SPEND_ALLOCATION_MEMBER` lock with its `lock_source` and
  `remediation_action`.
- `blocking_task_count` is the number of outstanding tasks blocking spending.
- `GET_ATTENTION_FEED`: load `ramp-complete-tasks`; do not use
  `LockOrUnlockCard` to bypass the sanction.
- `LOCK_OR_UNLOCK_CARD`: continue to the normal lock/unlock flow below.
- `UNLOCK_FRAUD_LOCKED_CARD`: use the fraud-specific unlock workflow returned
  by the tool. The existing result is `FraudLockDetected`.
- `CONTACT_RAMP`: stop automated unlock attempts and hand the returned lock
  details to Ramp support.

### Step 4: Activate a physical card

First call activation by the physical card's last four digits without
`--confirm_delivery`:

```bash
ramp cards activate --last_four 1234 --rationale "activate the user's new physical card" --agent
```

If the result says delivery confirmation is required, ask the user to confirm
that the physical card has arrived. Only after they confirm, retry with
`--confirm_delivery`:

```bash
ramp cards activate --last_four 1234 --confirm_delivery --rationale "user confirmed their physical card arrived" --agent
```

Do not ask about delivery or set `--confirm_delivery` unless the first call says
it is required.

### Step 5: Lock or unlock a card

Before locking, inspect and show the user the affected card, explain that
locking it will block all transactions until it is unlocked, and ask for
explicit confirmation. Run the lock command only after the user confirms.
Do not infer confirmation from a report of suspicious activity or a lost card.

Unlocking does not require confirmation.

Before unlocking, re-run `ListCards`. If any lock's `remediation_action` is
`GET_ATTENTION_FEED`, stop this manual flow and load `ramp-complete-tasks`. If
`is_spendable` is already true, report the live state without a redundant write.

Lock or unlock a card by its id. The id is a required positional argument:

```bash
ramp cards lock 7f3c0d2a-9b1e-4a55-8c21-0e9d6b2f4a10 --action lock --rationale "user lost their card" --agent
ramp cards lock 7f3c0d2a-9b1e-4a55-8c21-0e9d6b2f4a10 --action unlock --rationale "user found their card" --agent
```

After either write, re-run `ListCards` for the same cardholder. For unlock, the
postcondition passes only when the exact card reports `is_spendable: true`. A
successful unlock response, `is_locked: false`, or an underlying `ACTIVE`
lifecycle state is not sufficient.

If normal unlock returns `CardUnlockBlocked`, it is a typed failed precondition,
not a partial success. Report its `remaining_locks` and `blocking_task_count`;
the returned card remains `is_locked: true` and `is_spendable: false`. Follow
each remaining lock's remediation action instead of retrying the same unlock.

## Fields To Inspect

| Field | Meaning |
|---|---|
| `id` | Card UUID used for card actions |

From ramp-public/skills, MIT.

More from ramp-public/skills