@synap-core/workspace-templates 0.6.4 → 0.7.0

package/src/business-developer.yaml

@@ -0,0 +1,644 @@
+# Business Developer — a composable, lead-first CRM operating model.
+#
+# This is an ADDITIVE overlay on the CRM workspace, not a second CRM and not a
+# rewrite of shared identity profiles. It deliberately uses workspace-scoped
+# `crm-lead` and `crm-client` role facets instead of the pod-wide `lead` and
+# `client` vocabulary from Foundation. A person or company can therefore be a
+# lead in one CRM workspace without becoming a lead everywhere in the pod.
+#
+# Lifecycle:
+#   person / company + crm-lead → optional deal(s) → won deal → crm-client
+#
+# Deals are commercial proposals attached through CRM's existing
+# `linked_to_deal` relation. The CRM requires one counterparty before a deal
+# can be won, but a counterparty can have more than one proposal over time. A
+# client facet is only added when a deal is won; post-sale delivery belongs to
+# another application.
+
+meta:
+  slug: business-developer
+  name: Business Developer
+  description: "A lead-first sales motion for a CRM workspace: qualify leads, work commercial proposals, and hand won clients to the next system."
+  icon: target
+  color: "#D97706"
+  tags: [crm, sales, lead-management, business-development]
+  isPublic: true
+
+# Compose onto an existing CRM workspace. The resolver installs CRM first, then
+# applies these profiles and relations to that same workspace.
+dependencies:
+  - slug: crm
+    kind: workspace
+    relation: compose
+    reason: "Adds a lead-first business-development workflow to your CRM workspace."
+
+workspace:
+  name: CRM
+  description: A focused pre-sale workspace for lead qualification and commercial proposals.
+  subtype: crm
+  capabilities:
+    - crm.business-development
+
+profiles:
+  # Workspace-local operational status. This is intentionally separate from
+  # Foundation's shared `lead` role: lead ownership, next actions, and CRM
+  # lifecycle status must be visible to this CRM workspace's members only.
+  - slug: crm-lead
+    displayName: CRM Lead
+    icon: user-round-search
+    color: amber
+    description: A person or company actively being qualified or contacted by this CRM workspace.
+    scope: WORKSPACE
+    profileKind: role
+    applicableKinds: [person, company]
+    properties:
+      - slug: lifecycleStage
+        label: Lifecycle stage
+        valueType: string
+        inputType: select
+        enumValues: [new, researching, outreach, engaged, qualified, nurturing, disqualified, converted]
+        constraints: { defaultValue: new }
+      - slug: assignedUserId
+        label: Assigned user ID
+        valueType: string
+        inputType: text
+        placeholder: Workspace member ID
+      - slug: source
+        label: Source
+        valueType: string
+        inputType: select
+        enumValues: [manual, referral, linkedin, email, event, inbound, partner, import, other]
+      - slug: icpScore
+        label: ICP score
+        valueType: number
+        inputType: number
+      - slug: outreachChannels
+        label: Outreach channels
+        valueType: array
+        inputType: text
+        placeholder: linkedin, email, phone
+      - slug: lastContactedAt
+        label: Last contacted at
+        valueType: date
+        inputType: date
+      - slug: nextActionAt
+        label: Next action at
+        valueType: date
+        inputType: date
+      - slug: nextAction
+        label: Next action
+        valueType: string
+        inputType: textarea
+      - slug: qualificationNotes
+        label: Qualification notes
+        valueType: string
+        inputType: textarea
+      - slug: disqualificationReason
+        label: Disqualification reason
+        valueType: string
+        inputType: textarea
+      - slug: convertedAt
+        label: Converted at
+        valueType: date
+        inputType: date
+
+  # The same counterparty receives this facet when one of its commercial
+  # proposals is won. It intentionally carries only handoff context; client
+  # delivery, renewal, and service health remain outside this pre-sale addon.
+  - slug: crm-client
+    displayName: CRM Client
+    icon: badge-check
+    color: emerald
+    description: A CRM lead converted by a won commercial proposal and ready for handoff.
+    scope: WORKSPACE
+    profileKind: role
+    applicableKinds: [person, company]
+    properties:
+      - slug: becameClientAt
+        label: Became client at
+        valueType: date
+        inputType: date
+      - slug: handoffStatus
+        label: Handoff status
+        valueType: string
+        inputType: select
+        enumValues: [pending, ready, handed_off]
+        constraints: { defaultValue: pending }
+      - slug: handoffDestination
+        label: Handoff destination
+        valueType: string
+        inputType: text
+      - slug: handoffNotes
+        label: Handoff notes
+        valueType: string
+        inputType: textarea
+
+  # CRM's original deal profile remains the generic compatibility layer. These
+  # fields are the additive commercial contract used by this addon; applications
+  # that opt into Business Developer read them rather than treating a deal board
+  # as the lead pipeline.
+  - slug: deal
+    displayName: Deal
+    icon: git-branch
+    color: violet
+    properties:
+      - slug: commercialStage
+        label: Commercial stage
+        valueType: string
+        inputType: select
+        enumValues: [draft, proposed, negotiating, won, lost]
+        constraints: { defaultValue: draft }
+      - slug: synapFeeModel
+        label: Synap fee model
+        valueType: string
+        inputType: select
+        enumValues: [fixed, success_fee]
+      - slug: synapFixedFee
+        label: Synap fixed fee
+        valueType: number
+        inputType: number
+      - slug: expectedClientGain
+        label: Expected client gain
+        valueType: number
+        inputType: number
+      - slug: synapSuccessFeeRate
+        label: Synap success fee rate
+        valueType: number
+        inputType: number
+      - slug: sourcedByUserId
+        label: Sourced by user ID
+        valueType: string
+        inputType: text
+      - slug: synapFeeAmount
+        label: Synap fee amount
+        valueType: number
+        inputType: number
+      - slug: commissionEntitlementId
+        label: Commission entitlement
+        valueType: entity_id
+        targetProfileSlug: crm-commission-entitlement
+        inputType: entity_select
+      - slug: commissionStatus
+        label: Commission status
+        valueType: string
+        inputType: select
+        enumValues: [estimated, earned, paid, requires_review, void]
+      - slug: wonAt
+        label: Won at
+        valueType: date
+        inputType: date
+      - slug: lostReason
+        label: Lost reason
+        valueType: string
+        inputType: textarea
+
+  # Immutable-at-creation commission records make first- and repeat-deal
+  # commissions auditable. The CRM creates one on a win: 20% of Synap's fee for
+  # the counterparty's first won deal, then 10% for later won deals.
+  - slug: crm-commission-entitlement
+    displayName: Commission Entitlement
+    icon: receipt-text
+    color: green
+    description: An auditable business-developer commission created from a won deal.
+    scope: WORKSPACE
+    properties:
+      # Correlates this record with its originating deal. The configured
+      # handoff automation uses it as its idempotency key, so a resumed run
+      # cannot create a second entitlement after a partial write.
+      - slug: sourceDealId
+        label: Source deal ID
+        valueType: entity_id
+        targetProfileSlug: deal
+        inputType: entity_select
+      - slug: sourcedByUserId
+        label: Sourced by user ID
+        valueType: string
+        inputType: text
+      - slug: sequence
+        label: Deal sequence
+        valueType: string
+        inputType: select
+        enumValues: [first, subsequent]
+      - slug: rateBps
+        label: Commission rate (basis points)
+        valueType: number
+        inputType: number
+      - slug: feeBasisAmount
+        label: Synap fee basis amount
+        valueType: number
+        inputType: number
+      - slug: estimatedAmount
+        label: Estimated commission amount
+        valueType: number
+        inputType: number
+      - slug: status
+        label: Status
+        valueType: string
+        inputType: select
+        enumValues: [estimated, earned, paid, void]
+        constraints: { defaultValue: estimated }
+      - slug: earnedAt
+        label: Earned at
+        valueType: date
+        inputType: date
+      - slug: paidAt
+        label: Paid at
+        valueType: date
+        inputType: date
+      - slug: voidReason
+        label: Void reason
+        valueType: string
+        inputType: textarea
+
+entityLinks:
+  # The existing generic `linked_to_deal` relation remains the deal ↔
+  # counterparty connection. This overlay adds only the new auditable
+  # commission relation, avoiding a parallel relationship model.
+  - sourceProfileSlug: deal
+    targetProfileSlug: crm-commission-entitlement
+    type: crm_commission_for_deal
+    label: Commission entitlement
+
+# These are guided, proposal-first sessions — not background automations. They
+# never create a deal merely because a lead exists, and never convert a lead to
+# a client until a human-confirmed deal win is proposed and applied.
+playbooks:
+  - name: Qualify a CRM lead
+    description: Research and qualify one CRM lead, then make the next action explicit without creating a commercial proposal automatically.
+    goalTemplate: >-
+      Work on CRM lead ({lead}). Verify and enrich only factual information that
+      can be supported, assess fit, and update its CRM lifecycle stage, ICP score,
+      qualification notes, outreach channels, and next action. Do not create a
+      deal simply because the lead is qualified. If a commercial proposal is
+      warranted, explain why and ask for or propose that next step separately.
+    subjectProfile:
+      profileSlug: crm-lead
+    params:
+      - { name: lead, type: entity, label: CRM lead, required: true }
+    executor: is-agent
+    status: active
+
+  - name: Advance a commercial proposal
+    description: Help progress a linked deal without confusing commercial state with the lead pipeline or client conversion.
+    goalTemplate: >-
+      Work on commercial proposal ({deal}). Confirm its primary counterparty,
+      current commercial stage, fee model, expected fee, and next blocker. Propose
+      the single next action needed to advance it. Never mark the counterparty as
+      a CRM client unless the deal is genuinely won; a win must preserve the
+      sourced business developer and create the appropriate commission entitlement
+      (20% of Synap's fee for the first won deal with that counterparty, 10% later).
+    subjectProfile:
+      profileSlug: deal
+    params:
+      - { name: deal, type: entity, label: Commercial proposal, required: true }
+    executor: is-agent
+    status: active
+
+# The deterministic counterpart to the guided playbooks above. This runs only
+# after a human explicitly confirms the commercial win. It remains entirely
+# domain-configured: generic workflow nodes read, validate, calculate, and
+# write through the Pod's governed facet/relation/entity doors.
+automations:
+  - key: crm-win-and-handoff
+    name: Win and hand off
+    description: Convert one qualified CRM lead after its proposal is won, record its commission entitlement, and leave a resumable handoff trail.
+    triggerType: manual
+    triggerConfig: {}
+    status: active
+    flow:
+      nodes:
+        - id: trigger
+          type: trigger
+          position: { x: 0, y: 0 }
+          data:
+            label: Mark won and hand off
+            triggerType: manual
+            config: {}
+
+        - id: read-deal
+          type: entity_read
+          position: { x: 240, y: 0 }
+          data:
+            label: Read proposal
+            entityId: "{{trigger.payload.entityId}}"
+
+        - id: guard-deal
+          type: guard
+          position: { x: 480, y: 0 }
+          data:
+            label: Confirm proposal is ready
+            checks:
+              - path: steps.read-deal.output.entity.type
+                equals: deal
+                message: This action is only available for a commercial proposal.
+              - path: steps.read-deal.output.entity.properties.commercialStage
+                anyOf:
+                  - { path: steps.read-deal.output.entity.properties.commercialStage, equals: won }
+                  - { path: steps.read-deal.output.entity.properties.dealStage, equals: won }
+                message: Mark the proposal as won before handing it off.
+              - path: steps.read-deal.output.entity.properties.handoffStatus
+                notEquals: handed_off
+                message: This proposal has already been handed off.
+              - path: steps.read-deal.output.entity.properties.sourcedByUserId
+                exists: true
+                message: Set the business developer who sourced this proposal before handing it off.
+              - path: steps.read-deal.output.entity.properties.synapFeeAmount
+                numberGte: 0
+                message: Set the confirmed Synap fee before handing this proposal off.
+
+        - id: find-party
+          type: related_entities
+          position: { x: 720, y: 0 }
+          data:
+            label: Find proposal counterparty
+            entityId: "{{trigger.payload.entityId}}"
+            direction: inbound
+            relationTypes: [linked_to_deal]
+            limit: 2
+
+        - id: guard-party
+          type: guard
+          position: { x: 960, y: 0 }
+          data:
+            label: Confirm one qualified counterparty
+            checks:
+              - path: steps.find-party.output.entities
+                lengthEquals: 1
+                message: A proposal must have exactly one commercial counterparty before it can be handed off.
+
+        - id: read-party
+          type: entity_read
+          position: { x: 1200, y: 0 }
+          data:
+            label: Read CRM lead
+            entityId: "{{steps.find-party.output.entities.0.id}}"
+
+        - id: guard-lead
+          type: guard
+          position: { x: 1440, y: 0 }
+          data:
+            label: Confirm qualified CRM lead
+            checks:
+              - path: steps.read-party.output.entity.facetSlugs
+                arrayIncludes: crm-lead
+                message: The commercial counterparty must still be a CRM lead before it becomes a CRM client.
+
+        # Source-deal claim is the durable idempotency boundary for the whole
+        # financial handoff. It must happen before the first-deal decision so
+        # duplicate clicks cannot reserve different commission policies.
+        - id: claim-commission-entitlement
+          type: claim
+          position: { x: 1680, y: 0 }
+          data:
+            label: Reserve commission entitlement
+            namespace: crm-commission-entitlement
+            key: "{{trigger.payload.entityId}}"
+
+        - id: guard-commission-claim
+          type: guard
+          position: { x: 1920, y: 0 }
+          data:
+            label: Confirm this run owns the commission write
+            checks:
+              - path: steps.claim-commission-entitlement.output.claimed
+                equals: true
+                message: This proposal handoff is already being handled by another workflow run.
+
+        # A durable generic claim serializes the one-time policy decision. It
+        # prevents two concurrent wins for the same counterparty from both
+        # receiving the first-deal rate, while retries of the winning run keep
+        # their original decision.
+        - id: claim-first-client-deal
+          type: claim
+          position: { x: 2160, y: 0 }
+          data:
+            label: Reserve first-client commission rate
+            namespace: crm-commission-first-deal
+            key: "{{steps.read-party.output.entity.id}}"
+
+        # Existing pods may already have won work from before this add-on. Read
+        # that history before applying the claim policy, including the legacy
+        # `dealStage` field until old CRM records are migrated.
+        - id: prior-won-deals
+          type: related_entities
+          position: { x: 2400, y: 0 }
+          data:
+            label: Find earlier won proposals
+            entityId: "{{steps.read-party.output.entity.id}}"
+            direction: outbound
+            relationTypes: [linked_to_deal]
+            excludeEntityId: "{{trigger.payload.entityId}}"
+            propertyAnyEquals:
+              commercialStage: [won]
+              dealStage: [won]
+            limit: 100
+
+        - id: has-no-prior-won-deals
+          type: condition
+          position: { x: 2640, y: 0 }
+          data:
+            label: Is this the first historical win?
+            expression: steps.prior-won-deals.output.count === 0
+
+        - id: is-first-client-deal
+          type: compute
+          position: { x: 2880, y: 120 }
+          data:
+            label: Confirm first-client commission
+            operation: multiply
+            left: "{{steps.claim-first-client-deal.output.claimed}}"
+            right: "{{steps.has-no-prior-won-deals.output.result}}"
+
+        # 1,000 bps for every deal, plus 1,000 bps for the winning first-deal claim.
+        # Number(true) is deliberately supported by the generic compute node,
+        # keeping the first/subsequent policy in config rather than application code.
+        - id: first-deal-bonus-bps
+          type: compute
+          position: { x: 2880, y: 0 }
+          data:
+            label: Calculate first-deal bonus
+            operation: multiply
+            left: 1000
+            right: "{{steps.is-first-client-deal.output.result}}"
+
+        - id: commission-sequence
+          type: select
+          position: { x: 3120, y: 0 }
+          data:
+            label: Label commission sequence
+            when: "{{steps.is-first-client-deal.output.result}}"
+            ifTrue: first
+            ifFalse: subsequent
+
+        - id: commission-rate-bps
+          type: compute
+          position: { x: 3360, y: 0 }
+          data:
+            label: Calculate commission rate
+            operation: add
+            left: 1000
+            right: "{{steps.first-deal-bonus-bps.output.result}}"
+
+        - id: commission-product
+          type: compute
+          position: { x: 3600, y: 0 }
+          data:
+            label: Calculate commission basis points
+            operation: multiply
+            left: "{{steps.read-deal.output.entity.properties.synapFeeAmount}}"
+            right: "{{steps.commission-rate-bps.output.result}}"
+
+        - id: commission-amount
+          type: compute
+          position: { x: 3840, y: 0 }
+          data:
+            label: Calculate commission amount
+            operation: divide
+            left: "{{steps.commission-product.output.result}}"
+            right: 10000
+
+        - id: handoff-time
+          type: compute
+          position: { x: 4080, y: 0 }
+          data:
+            label: Record handoff time
+            operation: now
+
+        - id: create-commission
+          type: output
+          position: { x: 4320, y: 0 }
+          data:
+            label: Record commission entitlement
+            outputType: entity_create
+            config:
+              profileSlug: crm-commission-entitlement
+              title: "Commission · {{steps.read-deal.output.entity.title}}"
+              # The durable claim above serializes creators; this lookup heals a
+              # crash after the entity write but before its step ledger update.
+              dedupeBy: sourceDealId
+              properties:
+                sourceDealId: "{{trigger.payload.entityId}}"
+                sourcedByUserId: "{{steps.read-deal.output.entity.properties.sourcedByUserId}}"
+                sequence: "{{steps.commission-sequence.output.value}}"
+                rateBps: "{{steps.commission-rate-bps.output.result}}"
+                feeBasisAmount: "{{steps.read-deal.output.entity.properties.synapFeeAmount}}"
+                estimatedAmount: "{{steps.commission-amount.output.result}}"
+                status: estimated
+                earnedAt: "{{steps.handoff-time.output.result}}"
+
+        - id: link-commission
+          type: output
+          position: { x: 4560, y: 0 }
+          data:
+            label: Link proposal and commission
+            outputType: relation_create
+            config:
+              fromEntityId: "{{trigger.payload.entityId}}"
+              toEntityId: "{{steps.create-commission.output.entityId}}"
+              relationType: crm_commission_for_deal
+              dedupe: true
+
+        - id: mark-deal-won
+          type: output
+          position: { x: 4800, y: 0 }
+          data:
+            label: Mark proposal won
+            outputType: entity_update
+            config:
+              entityId: "{{trigger.payload.entityId}}"
+              properties:
+                commercialStage: won
+                wonAt: "{{steps.handoff-time.output.result}}"
+                handoffStatus: handed_off
+                commissionEntitlementId: "{{steps.create-commission.output.entityId}}"
+                commissionStatus: estimated
+
+        - id: attach-client
+          type: output
+          position: { x: 5040, y: 0 }
+          data:
+            label: Attach CRM client role
+            outputType: facet_attach
+            config:
+              entityId: "{{steps.read-party.output.entity.id}}"
+              facetSlug: crm-client
+              properties:
+                becameClientAt: "{{steps.handoff-time.output.result}}"
+                handoffStatus: handed_off
+
+        - id: convert-lead
+          type: output
+          position: { x: 5280, y: 0 }
+          data:
+            label: Complete CRM lead lifecycle
+            outputType: facet_update
+            config:
+              entityId: "{{steps.read-party.output.entity.id}}"
+              facetSlug: crm-lead
+              properties:
+                lifecycleStage: converted
+                convertedAt: "{{steps.handoff-time.output.result}}"
+
+      edges:
+        - { id: trigger-read, source: trigger, target: read-deal }
+        - { id: read-guard, source: read-deal, target: guard-deal }
+        - { id: guard-party-search, source: guard-deal, target: find-party }
+        - { id: party-search-guard, source: find-party, target: guard-party }
+        - { id: party-guard-read, source: guard-party, target: read-party }
+        - { id: party-read-guard, source: read-party, target: guard-lead }
+        - { id: lead-guard-commission-claim, source: guard-lead, target: claim-commission-entitlement }
+        - { id: commission-claim-guard, source: claim-commission-entitlement, target: guard-commission-claim }
+        - { id: commission-guard-first-claim, source: guard-commission-claim, target: claim-first-client-deal }
+        - { id: first-claim-history, source: claim-first-client-deal, target: prior-won-deals }
+        - { id: history-condition, source: prior-won-deals, target: has-no-prior-won-deals }
+        - { id: first-confirm-bonus, source: is-first-client-deal, target: first-deal-bonus-bps }
+        - { id: first-history-confirm, source: has-no-prior-won-deals, target: is-first-client-deal }
+        - { id: first-confirm-sequence, source: is-first-client-deal, target: commission-sequence }
+        - { id: bonus-rate, source: first-deal-bonus-bps, target: commission-rate-bps }
+        - { id: rate-product, source: commission-rate-bps, target: commission-product }
+        - { id: product-amount, source: commission-product, target: commission-amount }
+        - { id: amount-time, source: commission-amount, target: handoff-time }
+        - { id: time-commission, source: handoff-time, target: create-commission }
+        - { id: sequence-commission, source: commission-sequence, target: create-commission }
+        - { id: commission-link, source: create-commission, target: link-commission }
+        - { id: link-deal, source: link-commission, target: mark-deal-won }
+        - { id: deal-client, source: mark-deal-won, target: attach-client }
+        - { id: client-lead, source: attach-client, target: convert-lead }
+
+# Rendered by both CRM and Browser through the shared entity-action runner.
+# The lead facet requirement keeps the qualification playbook out of general
+# person/company records; the commercial action is explicitly confirmed because
+# it writes a client handoff and commission record.
+actionPlacements:
+  - profileSlug: person
+    surface: entity-detail
+    kind: playbook
+    ref: Qualify a CRM lead
+    label: Qualify lead
+    when: { requiredFacetSlugs: [crm-lead] }
+
+  - profileSlug: company
+    surface: entity-detail
+    kind: playbook
+    ref: Qualify a CRM lead
+    label: Qualify lead
+    when: { requiredFacetSlugs: [crm-lead] }
+
+  - profileSlug: deal
+    surface: entity-detail
+    kind: playbook
+    ref: Advance a commercial proposal
+    label: Advance proposal
+
+  - profileSlug: deal
+    surface: entity-detail
+    kind: automation
+    ref: Win and hand off
+    label: Hand off won proposal
+    when:
+      propertyAnyEquals: { commercialStage: [won], dealStage: [won] }
+      propertyNotEquals: { handoffStatus: handed_off }
+    confirmation:
+      title: Hand off this won proposal?
+      description: This converts its qualified CRM lead counterparty and records the business developer commission.
+      confirmLabel: Hand off proposal