@raishin/vanguard-frontier-agentic 2.3.0 → 2.6.0

package/skills/salesforce/salesforce-field-mapping-skill/SKILL.md

@@ -0,0 +1,348 @@
+---
+name: salesforce-field-mapping-skill
+description: "Maps CSV or spreadsheet column headers to Salesforce field API names with type mismatch detection, missing-field flagging, picklist value normalization, and API name collision detection. Used during data migration from HubSpot, Pipedrive, Excel exports, and legacy CRMs. TRIGGER when: user says map these columns to salesforce fields, field mapping for migration, convert csv headers to api names, import field mapping, migrate data from hubspot/pipedrive/excel, column mapping for data loader. DO NOT TRIGGER when: live data migration execution (use salesforce-bulk-data-ops-skill), schema design or new field creation (use salesforce-data-architecture-agent), field-level security review (use salesforce-permission-model-review-skill)."
+license: MIT
+allowed-tools: Read Grep Glob
+metadata:
+  author: "github: Raishin"
+  version: "0.1.0"
+  updated: "2026-05-21"
+  category: generation
+  lifecycle: experimental
+  execution_tier: static-review
+  mcp_servers: []
+  oauth_scopes: []
+  run_as_permissions:
+    required: []
+    denied: []
+---
+
+# salesforce-field-mapping-skill
+
+Pure-generation T0 skill that maps CSV/spreadsheet column headers to
+Salesforce field API names with type mismatch detection. The daily-driver
+for admins migrating from HubSpot, Pipedrive, Excel exports, and legacy CRMs.
+Outputs a complete mapping table, type mismatch report, missing-field list,
+and a Data Loader–ready column header row.
+
+## When This Skill Owns the Task
+
+Use `salesforce-field-mapping-skill` when the work is to **design or
+validate a field mapping** for a data import:
+
+- "I'm migrating from HubSpot — map these column headers to Salesforce Contact fields"
+- "Here's my Excel export. What are the Salesforce API names?"
+- "I need a Data Loader field mapping CSV for importing Opportunities from Pipedrive"
+- "Flag any type mismatches in my column list before I import"
+- "Which of my CSV columns don't have matching Salesforce fields?"
+
+**Delegate elsewhere when:**
+
+| Situation | Skill to use |
+|---|---|
+| Actually executing the data migration with records | `salesforce-bulk-data-ops-skill` |
+| Designing new custom fields to receive imported data | `salesforce-data-architecture-agent` |
+| Reviewing FLS or who can see imported fields | `salesforce-permission-model-review-skill` |
+| Fetching field metadata from a live org to compare | `salesforce-metadata-fetcher-skill` |
+
+---
+
+## Required Context to Gather First
+
+Before generating a mapping, confirm:
+
+1. **Target Salesforce object** — standard (Contact, Lead, Account,
+   Opportunity, Case) or custom (`Custom_Object__c`).
+2. **Source system** — HubSpot, Pipedrive, Salesforce Classic, Excel/CSV
+   export, Marketo, or other. Source system determines default field label
+   conventions.
+3. **Column header list** — the complete list of CSV/spreadsheet column
+   headers, either as a comma-separated list or pasted table.
+4. **Custom fields in scope** — list any known custom fields on the target
+   object that may receive data (e.g., `HubSpot_Contact_ID__c`).
+5. **Operation type** — insert, update, or upsert. Affects whether `Id` or
+   an external ID field is required in the mapping.
+6. **External ID field** — for upsert: which field is the external ID key?
+   (e.g., `HubSpot_Contact_ID__c`, `Email`)
+7. **Multi-value fields** — any source columns that contain comma-separated
+   multi-values intended for multi-select picklists.
+
+If the column header list is not provided, ask before proceeding.
+
+---
+
+## Recommended Workflow
+
+### Step 1 — Normalize source column headers
+
+Apply label normalization to make headers comparable:
+- Strip leading/trailing whitespace
+- Collapse multiple spaces to single space
+- Remove non-alphanumeric prefix/suffix characters
+- Flag headers containing special characters that may corrupt Data Loader
+  (e.g., `#`, `$`, `%`, `(`, `)`, `/`)
+
+### Step 2 — Derive candidate API names from labels
+
+For each normalized column header, apply the API name derivation rules
+(see `references/api-name-normalization.md`):
+1. Replace spaces with underscores
+2. Remove characters not in `[A-Za-z0-9_]`
+3. Strip leading digits (Salesforce API names must start with a letter)
+4. Collapse consecutive underscores to single underscore
+5. Truncate to 40 characters (API name limit)
+6. Append `__c` for custom fields
+7. Check against reserved words list
+
+### Step 3 — Match against known standard field API names
+
+Apply fuzzy matching against the standard object's well-known fields:
+
+For **Contact**: `FirstName`, `LastName`, `Email`, `Phone`, `MobilePhone`,
+`Title`, `Department`, `AccountId`, `MailingStreet`, `MailingCity`,
+`MailingState`, `MailingPostalCode`, `MailingCountry`, `LeadSource`,
+`Salutation`, `Birthdate`, `Description`, `DoNotCall`, `HasOptedOutOfEmail`,
+`OwnerId`, `ReportsToId`
+
+For **Lead**: `FirstName`, `LastName`, `Company`, `Email`, `Phone`,
+`MobilePhone`, `Status`, `LeadSource`, `Title`, `Industry`, `AnnualRevenue`,
+`NumberOfEmployees`, `Rating`, `Street`, `City`, `State`, `PostalCode`,
+`Country`, `Description`, `HasOptedOutOfEmail`, `DoNotCall`
+
+For **Account**: `Name`, `Type`, `Industry`, `AnnualRevenue`,
+`NumberOfEmployees`, `BillingStreet`, `BillingCity`, `BillingState`,
+`BillingPostalCode`, `BillingCountry`, `Phone`, `Website`, `Description`,
+`OwnerId`, `ParentId`
+
+For **Opportunity**: `Name`, `StageName`, `CloseDate`, `Amount`,
+`Probability`, `AccountId`, `OwnerId`, `Type`, `LeadSource`, `Description`,
+`ForecastCategory`, `ForecastCategoryName`, `CampaignId`, `NextStep`
+
+### Step 4 — Detect type mismatches
+
+For each mapped pair, compare source data type to Salesforce field type.
+Flag mismatches (see `references/type-mismatch-detection.md`):
+
+| Source type | Target type | Risk | Action |
+|---|---|---|---|
+| String | Date | HIGH | Requires DATEVALUE transform; verify ISO format |
+| String | Number/Currency | HIGH | Requires VALUE or numeric parse; check for non-numeric chars |
+| Multi-value string | Single picklist | HIGH | Must pick one value or use transformation script |
+| String | Boolean/Checkbox | MEDIUM | Map "true"/"1"/"yes" → true; all else → false |
+| String | Lookup (Id) | HIGH | Requires upsert by external ID or pre-lookup step |
+| Integer | Currency | LOW | Implicit conversion; verify decimal precision |
+| Mixed case | Picklist | MEDIUM | Picklist values are case-sensitive in Data Loader |
+
+### Step 5 — Flag missing and unmappable fields
+
+Produce two lists:
+1. **Unmapped source columns** — columns with no clear Salesforce target
+2. **Required fields missing from source** — Salesforce required fields
+   (e.g., `LastName` on Contact, `LastName + Company` on Lead, `Name +
+   StageName + CloseDate` on Opportunity, `Name` on Account) not present
+   in the source column list
+
+### Step 6 — Normalize picklist values
+
+For any column mapping to a standard picklist field, list the expected
+Salesforce API values and flag mismatches:
+
+- `LeadSource`: Cold Call, Web, Phone Inquiry, Partner Referral, Purchased
+  List, Other, Word of mouth, Employee, Internal, Partner
+- `StageName`: Prospecting, Qualification, Needs Analysis, Value Proposition,
+  Id. Decision Makers, Perception Analysis, Proposal/Price Quote, Negotiation/Review,
+  Closed Won, Closed Lost
+- `Industry`: Agriculture, Apparel, Banking, Biotechnology, Chemicals,
+  Communications, Construction, Consulting, Education, Electronics, Energy,
+  Engineering, Entertainment, Environmental, Finance, Food & Beverage,
+  Government, Healthcare, Hospitality, Insurance, Machinery, Manufacturing,
+  Media, Not For Profit, Recreation, Retail, Shipping, Technology,
+  Telecommunications, Transportation, Utilities, Other
+
+### Step 7 — Detect special character and collision risks
+
+- Flag API names that would collide (two source columns normalizing to
+  the same API name)
+- Flag reserved words: `Id`, `Name`, `OwnerId`, `CreatedDate`,
+  `LastModifiedDate`, `SystemModstamp`, `IsDeleted` — these cannot be
+  used as custom field API names
+- Flag API names exceeding 40 characters after normalization
+
+### Step 8 — Emit structured output
+
+Produce the full output block per the Output Format section below,
+including a Data Loader–ready header row.
+
+---
+
+## Quality Scoring Rubric (100-point)
+
+Score every output before emitting. Threshold: 85+ ship, 70–84 ship with
+caveat, below 70 reject and revise.
+
+| Dimension | Points | What earns full marks |
+|---|---|---|
+| **API name accuracy** | 30 | Every standard field mapped to correct API name; custom fields flagged with `__c`; no typos or reversed lookups |
+| **Type mismatch detection** | 25 | All HIGH and MEDIUM risk mismatches flagged with recommended transforms; no silently ignored mismatches |
+| **Missing-field flagging** | 15 | All required Salesforce fields checked; clearly listed if absent from source; import will fail without them |
+| **Picklist value normalization** | 15 | Case-sensitive picklist values verified; multi-value vs. single-value conflict flagged; API values used not display labels |
+| **Special char / collision detection** | 15 | Column header special chars flagged; API name collisions detected; reserved word conflicts identified |
+
+**Scoring penalties:**
+- Missing a HIGH-risk type mismatch: -15 per missed mismatch
+- Missing a required field from target object: -10
+- Incorrect standard API name: -15 per error
+- Multi-select picklist mapped to single picklist without flag: -20
+- Lookup/relationship field mapped without upsert key guidance: -10
+
+---
+
+## T0 Contract
+
+This skill is **static-review (T0)** only:
+
+- No Salesforce org connection required or permitted.
+- No CLI commands are executed.
+- No live field metadata is fetched.
+- The mapping is generated from known standard field sets and the user's
+  provided column list.
+- If the target object has custom fields that the user has not listed,
+  mappings to those custom fields cannot be generated here — use
+  `salesforce-metadata-fetcher-skill` to fetch them first.
+
+---
+
+## Refusal Triggers
+
+Stop and decline if:
+
+- The request is to execute a live data migration (route to
+  `salesforce-bulk-data-ops-skill`).
+- The target object is not specified after two clarification attempts.
+- The column header list is not provided after one prompt.
+- The operation involves permanent hard-deletes (T3 prohibited — route
+  to `salesforce-live-guard-agent`).
+
+---
+
+## Output Format
+
+```yaml
+verdict: "ship | ship-with-caveat | reject"
+quality_score: <0-100>
+quality_notes: "<what drove the score>"
+
+mapping_summary:
+  source_system: "<HubSpot | Pipedrive | Excel | Salesforce Classic | Other>"
+  target_object: "<SObjectApiName>"
+  operation: "<insert | update | upsert>"
+  external_id_field: "<FieldApiName | none>"
+  total_source_columns: <integer>
+  mapped_columns: <integer>
+  unmapped_columns: <integer>
+  type_mismatch_count: <integer>
+  required_fields_missing: <integer>
+
+field_mapping:
+  - source_column: "<source header>"
+    salesforce_api_name: "<FieldApiName>"
+    salesforce_field_type: "<Text|Date|Number|Currency|Picklist|Lookup|Checkbox|etc>"
+    confidence: "<high|medium|low>"
+    type_mismatch: "<none|HIGH|MEDIUM|LOW>"
+    mismatch_detail: "<description of mismatch if present>"
+    transform_recommended: "<none|DATEVALUE|VALUE|Picklist normalization|External ID lookup>"
+    notes: "<any special handling>"
+
+unmapped_source_columns:
+  - column: "<source header>"
+    reason: "<no standard match | ambiguous | custom field needed>"
+    suggested_custom_api_name: "<Suggested_Name__c>"
+
+required_fields_missing_from_source:
+  - field: "<FieldApiName>"
+    required_for: "<insert|update|upsert>"
+    impact: "<import will fail | data quality risk>"
+
+picklist_value_mismatches:
+  - source_column: "<source header>"
+    salesforce_field: "<FieldApiName>"
+    source_values_found: ["<val1>", "<val2>"]
+    valid_salesforce_values: ["<val1>", "<val2>"]
+    mismatched_values: ["<val1>"]
+    normalization_recommended: "<map 'val1' → 'Correct Value'"
+
+collision_and_special_char_warnings:
+  - column: "<source header>"
+    issue: "<special chars | api name collision | reserved word | length overflow>"
+    recommendation: "<how to resolve>"
+
+data_loader_header_row: "<Comma-separated list of Salesforce API names in source column order>"
+
+handoff_suggestions:
+  - "<e.g., fetch custom fields from org with salesforce-metadata-fetcher-skill>"
+  - "<e.g., run data migration with salesforce-bulk-data-ops-skill>"
+
+assumptions:
+  - "<explicit list of assumptions made>"
+```
+
+---
+
+## Redaction Rules
+
+This is a T0 generation skill with no live org connection. Apply:
+
+1. Never emit actual production org IDs, user IDs, or credentials even if
+   the user includes them in their prompt.
+2. If the user pastes sample data rows alongside headers, do not include
+   actual record values (email addresses, names, phone numbers) in the output.
+3. Sanitize pasted column lists that contain Org IDs (18-char starting `00D`)
+   before incorporating into output.
+
+---
+
+## Handoff Rules
+
+| Situation | Hand off to |
+|---|---|
+| User wants to execute the migration | `salesforce-bulk-data-ops-skill` |
+| User needs to fetch custom field API names from org | `salesforce-metadata-fetcher-skill` |
+| User wants to create new fields to receive import data | `salesforce-data-architecture-agent` |
+| FLS or sharing concerns on import fields | `salesforce-permission-model-review-skill` |
+
+---
+
+## Stop Conditions
+
+- Import will fail because required fields (`LastName`, `Company`,
+  `StageName + CloseDate + Name`) are entirely missing from the source —
+  stop, surface the list, require resolution before producing a mapping.
+- Every source column maps to the same single Salesforce field (e.g.,
+  all columns appear to be "Name") — stop and request clarification.
+- Requested mapping includes hard-delete or permanent-destroy operations —
+  stop and route to `salesforce-live-guard-agent`.
+
+---
+
+## Security Notes
+
+- **T0 static generation only:** No org connection, no CLI execution, no
+  MCP calls.
+- **No credential handling:** Skill never requests or emits OAuth tokens,
+  session IDs, or Connected App credentials.
+- **PII in sample data:** If user pastes real data rows, do not include
+  field values containing PII in the output mapping table. Process headers
+  only.
+- **Upsert external ID guidance:** External ID fields used in upsert
+  operations must have "External ID" checked on the field definition in
+  Salesforce Setup — flag this requirement explicitly.
+
+---
+
+## Reference File Index
+
+| File | When to read |
+|---|---|
+| `references/api-name-normalization.md` | How to derive API name from label, reserved words, length limits, collision rules |
+| `references/type-mismatch-detection.md` | Common type mismatches, normalization strategies, transform patterns |
+| `references/picklist-value-mapping.md` | Picklist value conversion, case sensitivity, multi-select handling |

package/skills/salesforce/salesforce-field-mapping-skill/metadata.json

@@ -0,0 +1,29 @@
+{
+  "id": "salesforce-field-mapping-skill",
+  "name": "Salesforce Field Mapping Skill",
+  "type": "skill",
+  "provider": "salesforce",
+  "harnesses": ["claude-code", "codex", "cursor", "gemini", "kiro", "other"],
+  "summary": "Maps CSV and spreadsheet column headers to Salesforce field API names with type mismatch detection, missing-field flagging, picklist value normalization, and API name collision detection. Used during data migration from HubSpot, Pipedrive, Excel exports, and legacy CRMs. T0 static generation only — no org connection required.",
+  "source_type": "original",
+  "category": "generation",
+  "execution_tier": "static-review",
+  "oauth_scopes": [],
+  "mcp_servers": [],
+  "run_as_permissions": {
+    "required": [],
+    "denied": []
+  },
+  "official_docs": [
+    "https://help.salesforce.com/s/articleView?id=sf.data_loader.htm",
+    "https://developer.salesforce.com/docs/atlas.en-us.api.meta/api/sforce_api_objects_contact.htm",
+    "https://developer.salesforce.com/docs/atlas.en-us.api.meta/api/sforce_api_objects_lead.htm",
+    "https://developer.salesforce.com/docs/atlas.en-us.api.meta/api/sforce_api_objects_opportunity.htm",
+    "https://help.salesforce.com/s/articleView?id=sf.fields_about_field_type.htm"
+  ],
+  "security_notes": "T0 static-review only. No org connection, no CLI execution, no MCP calls. PII in user-provided sample data rows is not included in output — headers only. Upsert external ID fields must have the External ID attribute set in Salesforce Setup.",
+  "last_verified": "2026-05-21",
+  "path": "skills/salesforce/salesforce-field-mapping-skill",
+  "author": "github: Raishin",
+  "version": "0.1.0"
+}

package/skills/salesforce/salesforce-field-mapping-skill/references/api-name-normalization.md

@@ -0,0 +1,141 @@
+# API Name Normalization Reference
+
+## How Salesforce Derives API Names from Labels
+
+Salesforce applies the following transformations when you create a field
+and it auto-generates the API name from the field label:
+
+1. **Replace spaces with underscores:** `First Name` → `First_Name`
+2. **Remove special characters:** Keep only `[A-Za-z0-9_]`
+3. **Remove leading digits:** `2nd_Stage` → `nd_Stage` (add prefix manually)
+4. **Collapse consecutive underscores:** `My__Field` → `My_Field`
+5. **Truncate to 40 characters** (custom field base name, before `__c`)
+6. **Append `__c`** suffix for custom fields
+7. **Append namespace prefix** for managed package fields: `ns__Field__c`
+
+## Reserved Words
+
+These cannot be used as custom field API names (without modification):
+
+| Reserved | Notes |
+|---|---|
+| `Id` | Always the record's 18-char Salesforce ID |
+| `Name` | Standard name field on all objects |
+| `OwnerId` | Always the owner User ID |
+| `CreatedDate` | Auto-populated system field |
+| `CreatedById` | Auto-populated system field |
+| `LastModifiedDate` | Auto-populated system field |
+| `LastModifiedById` | Auto-populated system field |
+| `SystemModstamp` | Auto-populated system field |
+| `IsDeleted` | Soft-delete flag |
+| `RecordTypeId` | Record Type assignment |
+
+If a source column matches a reserved word name, map directly to the
+standard field — do not attempt to create a custom field with that name.
+
+## Length Limits
+
+| Component | Limit |
+|---|---|
+| Custom field base name | 40 characters (before `__c`) |
+| Standard field API name | Varies; typically 30–40 characters |
+| Namespace prefix + field name | 40 characters total base name |
+
+If a derived API name exceeds 40 characters, truncate to 40 characters
+from the left. Flag the truncation in the output.
+
+## Common Source-to-API Name Mappings
+
+### HubSpot to Salesforce Contact
+
+| HubSpot Property | Salesforce API Name | Type |
+|---|---|---|
+| `firstname` | `FirstName` | Text |
+| `lastname` | `LastName` | Text |
+| `email` | `Email` | Email |
+| `phone` | `Phone` | Phone |
+| `mobilephone` | `MobilePhone` | Phone |
+| `jobtitle` | `Title` | Text |
+| `company` | `Account.Name` (via AccountId) | Lookup |
+| `website` | Account `Website` | Text |
+| `city` | `MailingCity` | Text |
+| `state` | `MailingState` | Text |
+| `zip` | `MailingPostalCode` | Text |
+| `country` | `MailingCountry` | Text |
+| `address` | `MailingStreet` | TextArea |
+| `hs_lead_status` | `LeadSource` | Picklist |
+| `hubspot_owner_id` | `OwnerId` (requires ID lookup) | Lookup |
+
+### Pipedrive to Salesforce Lead
+
+| Pipedrive Field | Salesforce API Name | Type |
+|---|---|---|
+| `name` | Requires split to `FirstName` + `LastName` | Text |
+| `email[0].value` | `Email` | Email |
+| `phone[0].value` | `Phone` | Phone |
+| `org_name` | `Company` | Text |
+| `title` | `Title` | Text |
+| `stage_id` | `LeadSource` (mapped via picklist) | Picklist |
+| `owner_name` | `OwnerId` (requires User lookup) | Lookup |
+
+### Excel Export Common Headers
+
+| Excel Header | Likely API Name | Notes |
+|---|---|---|
+| `First Name` | `FirstName` | Standard |
+| `Last Name` | `LastName` | Standard |
+| `Email Address` | `Email` | Normalize header |
+| `Mobile` | `MobilePhone` | Not `Mobile` alone |
+| `Company Name` | `Account.Name` | Requires AccountId lookup |
+| `Date Created` | `CreatedDate` | Read-only, cannot import |
+| `Modified Date` | `LastModifiedDate` | Read-only, cannot import |
+| `Deal Value` | `Amount` | Opportunity only |
+| `Expected Close` | `CloseDate` | Required on Opportunity |
+| `Stage` | `StageName` | Required on Opportunity |
+
+## Collision Detection
+
+Two source columns collide if they normalize to the same API name.
+
+**Examples:**
+- `"Phone Number"` and `"Phone"` both normalize to → `Phone`
+- `"First Name"` and `"FirstName"` both normalize to → `FirstName`
+- `"My Field"` and `"My_Field"` both normalize to → `My_Field`
+
+When collision is detected:
+1. Flag both columns in the output
+2. Ask user to clarify which column maps to which field
+3. Do not silently drop one column
+
+## Special Character Handling
+
+Source columns with these characters in headers require cleanup before
+use in Data Loader:
+
+| Character | Risk | Action |
+|---|---|---|
+| `#` | Splits CSV parsing | Rename column before Data Loader import |
+| `,` | Breaks CSV structure | Rename or quote column header |
+| `"` | Breaks CSV quoting | Remove from column header |
+| `(` `)` | Removed by normalization | Document the mapping |
+| `/` | Path separator risk | Remove |
+| `&` | HTML entity risk | Replace with `And` or `_` |
+| `.` | Period | Remove or replace with underscore |
+
+## Standard Object Required Fields
+
+Imports will fail without these fields in the source (for insert operations):
+
+| Object | Required Fields |
+|---|---|
+| Contact | `LastName` |
+| Lead | `LastName`, `Company` |
+| Account | `Name` |
+| Opportunity | `Name`, `StageName`, `CloseDate` |
+| Case | `Status` |
+| Custom object | Object's required fields per field configuration |
+
+For **upsert operations**, also require: the external ID field used as
+the match key.
+
+For **update operations**: `Id` or the external ID field.