Documenso Migration Deep DiveSAFE

Model-agnostic agent-skills platform with a harness-free canonical layer, verified adapters, and the ccpi package manager. Explore at tonsofskills.com.

The instruction file, verbatim from the audited commit — this is the text the model reads, and the surface the audit's instruction layer examines. Quoted here so you can judge it without cloning anything.

---
name: documenso-migration-deep-dive
description: 'Execute comprehensive Documenso migration strategies for platform switches.

  Use when migrating from other signing platforms, re-platforming to Documenso,

  or performing major infrastructure changes.

  Trigger with phrases like "migrate to documenso", "documenso migration",

  "switch to documenso", "documenso replatform", "replace docusign".

  '
allowed-tools: Read, Write, Edit, Bash(npm:*), Bash(node:*)
version: 1.14.0
license: MIT
author: Jeremy Longshore <[email protected]>
tags:
- saas
- documenso
- migration
compatibility: Designed for Claude Code
---
# Documenso Migration Deep Dive

## Output

- A staged migration record with document/template/signing compatibility evidence, owner, observation window, and rollback path.
- Preserved prior documents/configuration until the migration acceptance and retention requirements are complete.

## Examples

Migrate a synthetic document/template set in development, verify roles, state transitions, callbacks, audit evidence, and retention, then promote through staging before a production canary. Stop and roll back on authorization, signing, or audit regression; never bulk-migrate sensitive documents as a test.

## Current State

!`npm list 2>/dev/null | head -10`

## Overview

Comprehensive guide for migrating to Documenso from other e-signature platforms (DocuSign, HelloSign, PandaDoc, Adobe Sign). Uses the Strangler Fig pattern for zero-downtime migration with feature flags and rollback support.

## Prerequisites

- Current signing platform documented (APIs, templates, webhooks)
- Documenso account configured (see `documenso-install-auth`)
- Feature flag infrastructure (LaunchDarkly, environment variables, etc.)
- Parallel run capability (both platforms active during migration)

## Migration Strategy: Strangler Fig Pattern

```
Phase 1: Parallel Systems (Week 1-2)
┌──────────┐     ┌─────────────┐
│ Your App │────▶│ Old Platform │  (100% traffic)
│          │     └─────────────┘
│          │────▶│  Documenso   │  (shadow: log only, don't send)
└──────────┘     └─────────────┘

Phase 2: Gradual Cutover (Week 3-4)
┌──────────┐     ┌─────────────┐
│ Your App │────▶│ Old Platform │  (50% traffic via feature flag)
│          │     └─────────────┘
│          │────▶│  Documenso   │  (50% traffic)
└──────────┘     └─────────────┘

Phase 3: Full Migration (Week 5+)
┌──────────┐     ┌─────────────┐
│ Your App │────▶│  Documenso   │  (100% traffic)
└──────────┘     └─────────────┘
                 Old platform decommissioned
```

## Instructions

### Step 1: Pre-Migration Assessment

```typescript
// scripts/assess-current-system.ts
// Inventory your current signing platform usage

interface MigrationAssessment {
  platform: string;
  activeTemplates: number;
  documentsPerMonth: number;
  webhookEndpoints: string[];
  recipientRoles: string[];
  fieldTypes: string[];
  integrations: string[];  // CRM, database, etc.
}

async function assessCurrentSystem(): Promise<MigrationAssessment> {
  // Example for DocuSign
  return {
    platform: "DocuSign",
    activeTemplates: 15,
    documentsPerMonth: 200,
    webhookEndpoints: [
      "https://api.yourapp.com/webhooks/docusign",
    ],
    recipientRoles: ["Signer", "CC", "In Person Signer"],
    fieldTypes: ["Signature", "Date", "Text", "Checkbox", "Initial"],
    integrations: ["Salesforce", "PostgreSQL"],
  };
}
```

### Step 2: Feature Mapping

| DocuSign | HelloSign | Documenso | Notes |
|----------|-----------|-----------|-------|
| Envelope | Signature Request | Document | Documenso v2 also has Envelopes |
| Template | Template | Template | Create via UI, use via API |
| Signer | Signer | SIGNER role | Same concept |
| CC | CC | CC role | Same concept |
| In Person | N/A | Direct Link | Use embedded signing |
| Tabs/Fields | Form Fields | Fields | SIGNATURE, TEXT, DATE, etc. |
| Connect (webhooks) | Callbacks | Webhooks | document.completed, etc. |
| PowerForms | N/A | Direct Links | Public signing URLs |

### Step 3: Template Migration

```typescript
// Templates can't be migrated via API — recreate in Documenso
// Keep template definitions in code for reproducibility

interface TemplateDef {
  name: string;
  description: string;
  recipientRoles: Array<{ role: string; placeholder: string }>;
  fields: Array<{
    recipientIndex: number;
    type: string;
    page: number;
    x: number;
    y: number;
    width: number;
    height: number;
  }>;
}

const TEMPLATES: TemplateDef[] = [
  {
    name: "NDA — Standard",
    description: "Non-disclosure agreement template",
    recipientRoles: [
      { role: "SIGNER", placeholder: "Counterparty" },
      { role: "CC", placeholder: "Legal Team" },
    ],
    fields: [
      { recipientIndex: 0, type: "SIGNATURE", page: 2, x: 10, y: 80, width: 30, height: 5 },
      { recipientIndex: 0, type: "DATE", page: 2, x: 60, y: 80, width: 20, height: 3 },
      { recipientIndex: 0, type: "NAME", page: 2, x: 10, y: 75, width: 30, height: 3 },
    ],
  },
  // ... more templates
];

// Instructions: create each template in the Documenso UI using these specs
// Then record the template IDs in your config
```

### Step 4: Webhook Migration

```typescript
// Map old platform events to Documenso events
const EVENT_MAPPING: Record<string, string> = {
  // DocuSign → Documenso
  "envelope-completed": "document.completed",
  "envelope-sent": "document.sent",
  "envelope-declined": "document.rejected",
  "envelope-voided": "document.cancelled",
  "recipient-completed": "document.signed",

  // HelloSign → Documenso
  "signature_request_all_signed": "document.completed",
  "signature_request_sent": "document.sent",
  "signature_request_declined": "document.rejected",
  "signature_request_signed": "document.signed",
};

// Unified handler that works with both platforms during migration
async function handleSigningEvent(source: "old" | "documenso", event: string, payload: any) {
  const normalizedEvent = source

SAFEgrade B · trust 89/100 Nothing in the source contradicts what it says it does. Grade A is reserved for packages that have also passed the behavioural sandbox.

What the source does

Filesystem

none-observed

Network

none-observed

Shell

none-observed

Dependencies

pinned

Secrets in source

none-found

Findings (0)

No findings outside the package's declared scope.

Gates applied: no_behavioural_pass.