{
  "feature": "advisor-onboarding",
  "version": "1.0.0",
  "description": "Registration and onboarding process for independent financial advisors with CID approval and mandate signing",
  "category": "workflow",
  "tags": [
    "advisor-registration",
    "approval-workflow",
    "financial-services"
  ],
  "actors": [
    {
      "id": "advisor",
      "name": "Advisor",
      "type": "human",
      "role": "Advisor"
    },
    {
      "id": "onboarding_officer",
      "name": "Onboarding Officer",
      "type": "human",
      "role": "Onboarding-Activ8"
    },
    {
      "id": "cid_officer",
      "name": "CID Officer",
      "type": "human",
      "role": "Onboarding-CID"
    },
    {
      "id": "esignature_service",
      "name": "eSignature Service",
      "type": "external"
    }
  ],
  "fields": [
    {
      "name": "onboarding_id",
      "type": "number",
      "required": true,
      "validation": [
        {
          "type": "required",
          "message": "Onboarding ID required"
        }
      ],
      "label": "Onboarding Id"
    },
    {
      "name": "identification_number",
      "type": "text",
      "required": true,
      "validation": [
        {
          "type": "required",
          "message": "ID number required"
        },
        {
          "type": "unique",
          "message": "ID must be unique"
        }
      ],
      "label": "Identification Number"
    },
    {
      "name": "passport_number",
      "type": "text",
      "required": false,
      "validation": [],
      "label": "Passport Number"
    },
    {
      "name": "first_name",
      "type": "text",
      "required": true,
      "validation": [
        {
          "type": "required",
          "message": "First name required"
        },
        {
          "type": "maxLength",
          "message": "Max 100 characters",
          "value": 100
        }
      ],
      "label": "First Name"
    },
    {
      "name": "last_name",
      "type": "text",
      "required": true,
      "validation": [
        {
          "type": "required",
          "message": "Last name required"
        },
        {
          "type": "maxLength",
          "message": "Max 100 characters",
          "value": 100
        }
      ],
      "label": "Last Name"
    },
    {
      "name": "email",
      "type": "email",
      "required": true,
      "validation": [
        {
          "type": "required",
          "message": "Email required"
        },
        {
          "type": "email",
          "message": "Valid email required"
        }
      ],
      "label": "Email"
    },
    {
      "name": "mobile_phone",
      "type": "phone",
      "required": true,
      "validation": [
        {
          "type": "required",
          "message": "Phone required"
        },
        {
          "type": "phone",
          "message": "Valid phone required"
        }
      ],
      "label": "Mobile Phone"
    },
    {
      "name": "advisor_code",
      "type": "text",
      "required": true,
      "validation": [
        {
          "type": "required",
          "message": "Advisor code required"
        },
        {
          "type": "pattern",
          "message": "Code must be 6-10 alphanumeric",
          "value": "^[A-Z0-9]{6,10}$"
        }
      ],
      "label": "Advisor Code"
    },
    {
      "name": "status",
      "type": "select",
      "required": true,
      "validation": [
        {
          "type": "required",
          "message": "Status required"
        }
      ],
      "options": [
        {
          "value": "initiated",
          "label": "Initiated"
        },
        {
          "value": "in_progress",
          "label": "In Progress"
        },
        {
          "value": "waiting_approval",
          "label": "Waiting Approval"
        },
        {
          "value": "approved",
          "label": "Approved"
        },
        {
          "value": "mandate_signing",
          "label": "Mandate Signing"
        },
        {
          "value": "mandate_signed",
          "label": "Mandate Signed"
        },
        {
          "value": "cancelled",
          "label": "Cancelled"
        },
        {
          "value": "expired",
          "label": "Expired"
        }
      ],
      "label": "Status"
    },
    {
      "name": "cancellation_reason",
      "type": "text",
      "required": false,
      "validation": [],
      "label": "Cancellation Reason"
    },
    {
      "name": "envelope_id",
      "type": "text",
      "required": false,
      "validation": [],
      "label": "Envelope Id"
    }
  ],
  "rules": {
    "validation": [
      "ID and passport must be unique in system",
      "Valid email and phone required",
      "Advisor code format alphanumeric 6-10 chars"
    ],
    "permissions": [
      "Onboarding-Activ8 creates and manages",
      "Onboarding-CID approves",
      "Advisor views own onboarding"
    ]
  },
  "states": {
    "field": "status",
    "values": [
      {
        "name": "initiated",
        "label": "Initiated",
        "initial": true
      },
      {
        "name": "in_progress",
        "label": "In Progress"
      },
      {
        "name": "waiting_approval",
        "label": "Waiting Approval"
      },
      {
        "name": "approved",
        "label": "Approved"
      },
      {
        "name": "mandate_signing",
        "label": "Mandate Signing"
      },
      {
        "name": "mandate_signed",
        "label": "Mandate Signed",
        "terminal": true
      },
      {
        "name": "cancelled",
        "label": "Cancelled",
        "terminal": true
      },
      {
        "name": "expired",
        "label": "Expired",
        "terminal": true
      }
    ]
  },
  "outcomes": {
    "create_advisor_onboarding": {
      "priority": 1,
      "given": [
        {
          "field": "identification_number",
          "source": "input",
          "operator": "exists"
        },
        {
          "field": "email",
          "source": "input",
          "operator": "exists"
        },
        {
          "field": "advisor_code",
          "source": "input",
          "operator": "exists"
        },
        {
          "field": "client.role",
          "source": "session",
          "operator": "eq",
          "value": "Onboarding-Activ8"
        }
      ],
      "then": [
        {
          "action": "create_record",
          "type": "onboarding",
          "target": "onboarding",
          "fields": [
            "identification_number",
            "email",
            "advisor_code"
          ]
        },
        {
          "action": "emit_event",
          "event": "onboarding.created",
          "payload": [
            "onboarding_id"
          ]
        }
      ],
      "result": "Advisor onboarding created"
    },
    "create_advisor_onboarding_duplicate": {
      "priority": 0,
      "error": "DUPLICATE_IDENTITY",
      "given": [
        {
          "any": [
            {
              "field": "identification_number",
              "source": "db",
              "operator": "exists"
            },
            {
              "field": "passport_number",
              "source": "db",
              "operator": "exists"
            }
          ]
        }
      ],
      "then": [
        {
          "action": "emit_event",
          "event": "validation.duplicate_found",
          "payload": [
            "identification_number"
          ]
        }
      ],
      "result": "Error duplicate found"
    },
    "get_advisor_onboarding": {
      "priority": 10,
      "given": [
        {
          "field": "onboarding_id",
          "source": "input",
          "operator": "exists"
        },
        {
          "field": "client.role",
          "source": "session",
          "operator": "in",
          "value": [
            "Onboarding-Activ8",
            "Onboarding-CID"
          ]
        }
      ],
      "then": [
        {
          "action": "emit_event",
          "event": "onboarding.retrieved",
          "payload": [
            "onboarding_id"
          ]
        }
      ],
      "result": "Returns advisor onboarding data"
    },
    "update_advisor_onboarding": {
      "priority": 11,
      "given": [
        {
          "field": "onboarding_id",
          "source": "input",
          "operator": "exists"
        },
        {
          "field": "status",
          "source": "db",
          "operator": "in",
          "value": [
            "initiated",
            "in_progress"
          ]
        },
        {
          "field": "client.role",
          "source": "session",
          "operator": "eq",
          "value": "Onboarding-Activ8"
        }
      ],
      "then": [
        {
          "action": "set_field",
          "target": "updated_at",
          "value": "now"
        },
        {
          "action": "emit_event",
          "event": "onboarding.updated",
          "payload": [
            "onboarding_id"
          ]
        }
      ],
      "result": "Advisor onboarding updated"
    },
    "cancel_advisor_onboarding": {
      "priority": 12,
      "given": [
        {
          "field": "onboarding_id",
          "source": "input",
          "operator": "exists"
        },
        {
          "field": "cancellation_reason",
          "source": "input",
          "operator": "exists"
        },
        {
          "field": "status",
          "source": "db",
          "operator": "not_in",
          "value": [
            "mandate_signed",
            "cancelled"
          ]
        },
        {
          "field": "client.role",
          "source": "session",
          "operator": "eq",
          "value": "Onboarding-Activ8"
        }
      ],
      "then": [
        {
          "action": "transition_state",
          "field": "status",
          "from": "current",
          "to": "cancelled"
        },
        {
          "action": "set_field",
          "target": "cancellation_reason",
          "value": "from_input"
        },
        {
          "action": "emit_event",
          "event": "onboarding.cancelled",
          "payload": [
            "onboarding_id"
          ]
        }
      ],
      "result": "Onboarding cancelled"
    },
    "send_to_approval": {
      "priority": 3,
      "given": [
        {
          "field": "onboarding_id",
          "source": "input",
          "operator": "exists"
        },
        {
          "field": "status",
          "source": "db",
          "operator": "in",
          "value": [
            "initiated",
            "in_progress"
          ]
        },
        {
          "field": "identification_number",
          "source": "db",
          "operator": "exists"
        },
        {
          "field": "client.role",
          "source": "session",
          "operator": "eq",
          "value": "Onboarding-Activ8"
        }
      ],
      "then": [
        {
          "action": "transition_state",
          "field": "status",
          "from": "in_progress",
          "to": "waiting_approval"
        },
        {
          "action": "emit_event",
          "event": "approval.submitted",
          "payload": [
            "onboarding_id"
          ]
        }
      ],
      "result": "Sent for CID approval"
    },
    "cid_approve_onboarding": {
      "priority": 4,
      "given": [
        {
          "field": "onboarding_id",
          "source": "input",
          "operator": "exists"
        },
        {
          "field": "status",
          "source": "db",
          "operator": "eq",
          "value": "waiting_approval"
        },
        {
          "field": "client.role",
          "source": "session",
          "operator": "eq",
          "value": "Onboarding-CID"
        }
      ],
      "then": [
        {
          "action": "transition_state",
          "field": "status",
          "from": "waiting_approval",
          "to": "approved"
        },
        {
          "action": "emit_event",
          "event": "approval.granted",
          "payload": [
            "onboarding_id"
          ]
        }
      ],
      "result": "CID approved onboarding"
    },
    "complete_onboarding_mandate": {
      "priority": 5,
      "given": [
        {
          "field": "onboarding_id",
          "source": "input",
          "operator": "exists"
        },
        {
          "field": "status",
          "source": "db",
          "operator": "eq",
          "value": "approved"
        },
        {
          "field": "client.role",
          "source": "session",
          "operator": "eq",
          "value": "Onboarding-Activ8"
        }
      ],
      "then": [
        {
          "action": "transition_state",
          "field": "status",
          "from": "approved",
          "to": "mandate_signing"
        },
        {
          "action": "set_field",
          "target": "envelope_id",
          "value": "generated"
        },
        {
          "action": "emit_event",
          "event": "mandate.generated",
          "payload": [
            "onboarding_id"
          ]
        }
      ],
      "result": "Mandate sent to eSignature service"
    },
    "handle_mandate_signed": {
      "priority": 6,
      "given": [
        {
          "field": "onboarding_id",
          "source": "input",
          "operator": "exists"
        },
        {
          "field": "status",
          "source": "db",
          "operator": "eq",
          "value": "mandate_signing"
        },
        {
          "field": "envelope_status",
          "source": "input",
          "operator": "eq",
          "value": "signed"
        }
      ],
      "then": [
        {
          "action": "transition_state",
          "field": "status",
          "from": "mandate_signing",
          "to": "mandate_signed"
        },
        {
          "action": "emit_event",
          "event": "mandate.signed",
          "payload": [
            "onboarding_id"
          ]
        }
      ],
      "result": "Mandate signed, onboarding complete"
    },
    "get_creator_onboardings": {
      "priority": 20,
      "given": [
        {
          "field": "client.role",
          "source": "session",
          "operator": "eq",
          "value": "Onboarding-Activ8"
        }
      ],
      "then": [
        {
          "action": "emit_event",
          "event": "list.retrieved",
          "payload": [
            "creator_id"
          ]
        }
      ],
      "result": "Returns created onboardings"
    },
    "get_cid_onboardings": {
      "priority": 21,
      "given": [
        {
          "field": "client.role",
          "source": "session",
          "operator": "eq",
          "value": "Onboarding-CID"
        }
      ],
      "then": [
        {
          "action": "emit_event",
          "event": "list.retrieved",
          "payload": [
            "awaiting_approval"
          ]
        }
      ],
      "result": "Returns pending approvals"
    }
  },
  "errors": [
    {
      "code": "ONBOARDING_NOT_FOUND",
      "status": 404,
      "message": "Onboarding not found"
    },
    {
      "code": "DUPLICATE_IDENTITY",
      "status": 409,
      "message": "Advisor with this identity exists"
    },
    {
      "code": "INVALID_STATUS_TRANSITION",
      "status": 400,
      "message": "Invalid status transition"
    },
    {
      "code": "MISSING_REQUIRED_FIELD",
      "status": 400,
      "message": "Required field missing"
    },
    {
      "code": "INVALID_EMAIL_FORMAT",
      "status": 400,
      "message": "Invalid email"
    },
    {
      "code": "INVALID_PHONE_FORMAT",
      "status": 400,
      "message": "Invalid phone"
    },
    {
      "code": "UNAUTHORIZED_ACCESS",
      "status": 403,
      "message": "Unauthorized"
    },
    {
      "code": "INVALID_ADVISOR_CODE",
      "status": 400,
      "message": "Invalid advisor code"
    },
    {
      "code": "DOCU_SIGN_ERROR",
      "status": 500,
      "message": "eSignature service error"
    },
    {
      "code": "MANDATE_GENERATION_FAILED",
      "status": 500,
      "message": "Mandate generation failed"
    }
  ],
  "events": [
    {
      "name": "onboarding.created",
      "description": "Advisor onboarding created",
      "payload": [
        "onboarding_id"
      ]
    },
    {
      "name": "onboarding.retrieved",
      "description": "Onboarding retrieved",
      "payload": [
        "onboarding_id"
      ]
    },
    {
      "name": "onboarding.updated",
      "description": "Onboarding updated",
      "payload": [
        "onboarding_id"
      ]
    },
    {
      "name": "onboarding.cancelled",
      "description": "Onboarding cancelled",
      "payload": [
        "onboarding_id"
      ]
    },
    {
      "name": "validation.duplicate_found",
      "description": "Duplicate found",
      "payload": [
        "identification_number"
      ]
    },
    {
      "name": "approval.submitted",
      "description": "Submitted for approval",
      "payload": [
        "onboarding_id"
      ]
    },
    {
      "name": "approval.granted",
      "description": "Approval granted",
      "payload": [
        "onboarding_id"
      ]
    },
    {
      "name": "mandate.generated",
      "description": "Mandate generated",
      "payload": [
        "onboarding_id"
      ]
    },
    {
      "name": "mandate.signed",
      "description": "Mandate signed",
      "payload": [
        "onboarding_id"
      ]
    },
    {
      "name": "list.retrieved",
      "description": "List retrieved",
      "payload": [
        "filter"
      ]
    }
  ],
  "related": [
    {
      "feature": "client-onboarding",
      "type": "recommended"
    },
    {
      "feature": "proposals-quotations",
      "type": "optional"
    },
    {
      "feature": "user-auth",
      "type": "required"
    }
  ],
  "sla": {
    "max_duration": "30d"
  },
  "agi": {
    "goals": [
      {
        "id": "reliable_advisor_onboarding",
        "description": "Registration and onboarding process for independent financial advisors with CID approval and mandate signing",
        "success_metrics": [
          {
            "metric": "processing_time",
            "target": "< 5s",
            "measurement": "Time from request to completion"
          },
          {
            "metric": "success_rate",
            "target": ">= 99%",
            "measurement": "Successful operations divided by total attempts"
          }
        ],
        "constraints": [
          {
            "type": "performance",
            "description": "Must not block dependent workflows",
            "negotiable": true
          }
        ]
      }
    ],
    "autonomy": {
      "level": "semi_autonomous",
      "human_checkpoints": [
        "before transitioning to a terminal state"
      ],
      "escalation_triggers": [
        "error_rate > 5"
      ]
    },
    "safety": {
      "action_permissions": [
        {
          "action": "create_advisor_onboarding",
          "permission": "supervised"
        },
        {
          "action": "create_advisor_onboarding_duplicate",
          "permission": "supervised"
        },
        {
          "action": "get_advisor_onboarding",
          "permission": "autonomous"
        },
        {
          "action": "update_advisor_onboarding",
          "permission": "supervised"
        },
        {
          "action": "cancel_advisor_onboarding",
          "permission": "supervised"
        },
        {
          "action": "send_to_approval",
          "permission": "supervised"
        },
        {
          "action": "cid_approve_onboarding",
          "permission": "supervised"
        },
        {
          "action": "complete_onboarding_mandate",
          "permission": "autonomous"
        },
        {
          "action": "handle_mandate_signed",
          "permission": "autonomous"
        },
        {
          "action": "get_creator_onboardings",
          "permission": "supervised"
        },
        {
          "action": "get_cid_onboardings",
          "permission": "autonomous"
        }
      ]
    },
    "tradeoffs": [
      {
        "prefer": "reliability",
        "over": "speed",
        "reason": "workflow steps must complete correctly before proceeding"
      }
    ],
    "coordination": {
      "protocol": "orchestrated",
      "consumes": [
        {
          "capability": "user_auth",
          "from": "user-auth",
          "fallback": "degrade"
        }
      ]
    }
  },
  "ui_hints": {
    "progress_tracking": true,
    "status_badge": true
  }
}