vertkit-crm-builder

VertKit CRM Builder

VertKit is a tenant-safe CRM/ERP backend foundation for vertical builders. Use the Go API and Postgres as the system of record; use the TypeScript agent runtime for tool routing, permissions, model-provider calls, and CRM automation.

Start Here

1. Read repo truth first: README.md, openapi.yaml, and internal/storage/storage.go.
2. Classify the request:
   • Core platform: reusable CRM behavior. Read references/backend-foundation.md.
   • Vertical CRM module: industry-specific behavior. Read references/vertical-modules.md.
   • Agent runtime / automation: orchestration, approvals, enrichment, or human review. Read references/agent-runtime.md.
3. Use TDD for behavior changes. Add tests before implementation.
4. Run scripts/verify_vertkit.sh before claiming completion.

Non-Negotiable Invariants

• tenant_id is a security boundary, not a filter convenience.
• Tenant-scoped IDs are unique only within a tenant; storage keys and Postgres keys must include tenant ID.
• Validate tenant existence before tenant-scoped writes.
• Reject path/body tenant mismatches.
• Return JSON errors as {"error":"message"}.
• Keep memory storage for fast tests/dev; keep Postgres as the production path.
• Deep-copy mutable maps/slices at store boundaries.
• Update openapi.yaml when public API behavior changes.

Default Architecture

• Go core API owns CRM records and authorization boundaries.
• Postgres owns durable business state and tenant-aware persistence.
• REST + OpenAPI is the public contract for apps, SDKs, and agents.
• TypeScript agent runtime owns tool routing, provider calls, permission checks, and audit events. It must call VertKit APIs instead of writing CRM tables directly.

Common Workflows

Add a core CRM entity or capability

Read references/backend-foundation.md. Implement domain type, storage interface, memory store, Postgres schema/store, API routes, OpenAPI contract, and tests together.

Add vertical behavior

Read references/vertical-modules.md. Prefer custom_fields, rules, and module-specific API layers before changing core structs.

Add a rule/operator/action

Keep rules agent-generatable. Field paths use JSON names like amount, currency, and custom_fields.region. Add regression tests for every new operator, path shape, or action.

Add agent automation

Read references/agent-runtime.md. Treat agent proposals as workflow outputs that call VertKit APIs with tenant context and service credentials.

Completion Bar

Before finishing:

skills/vertkit-crm-builder/scripts/verify_vertkit.sh

If running from outside the repo, cd to the VertKit root first. If the skill is installed globally, use the installed script path and still run it from the project root.