business-as-code 0.2.1 → 2.0.1

package/src/entities/partnerships.ts

@@ -0,0 +1,309 @@
+import type { Noun } from 'ai-database'
+
+/**
+ * Partnership & Vendor Entities
+ * Partner, Vendor, Affiliate, Partnership, Reseller, Integration
+ */
+
+export const Partner: Noun = {
+  singular: 'partner',
+  plural: 'partners',
+  description: 'A business partner that collaborates with the organization',
+  properties: {
+    name: { type: 'string', description: 'Partner organization name' },
+    type: { type: 'string', description: 'Type of partner', examples: ['strategic', 'technology', 'channel', 'solution', 'implementation', 'consulting', 'reseller', 'referral', 'OEM'] },
+    tier: { type: 'string', description: 'Partner tier level', examples: ['platinum', 'gold', 'silver', 'bronze', 'registered'] },
+    status: { type: 'string', description: 'Partnership status', examples: ['prospect', 'onboarding', 'active', 'inactive', 'suspended', 'terminated'] },
+    description: { type: 'string', description: 'Partner description' },
+    website: { type: 'string', description: 'Partner website URL' },
+    logo: { type: 'string', description: 'Partner logo URL' },
+    industry: { type: 'string', description: 'Partner industry' },
+    size: { type: 'string', description: 'Partner company size', examples: ['startup', 'small', 'medium', 'enterprise'] },
+    region: { type: 'string', description: 'Primary region of operation' },
+    territories: { type: 'string[]', description: 'Geographic territories covered' },
+    specializations: { type: 'string[]', description: 'Areas of specialization', examples: ['cloud', 'security', 'data', 'AI', 'mobile', 'e-commerce'] },
+    certifications: { type: 'string[]', description: 'Partner certifications held' },
+    primaryContact: { type: 'string', description: 'Primary contact person' },
+    email: { type: 'string', description: 'Primary contact email' },
+    phone: { type: 'string', description: 'Primary contact phone' },
+    partnerManager: { type: 'string', description: 'Internal partner manager' },
+    startDate: { type: 'date', description: 'Partnership start date' },
+    renewalDate: { type: 'date', description: 'Next renewal date' },
+    revenueShare: { type: 'number', description: 'Revenue share percentage' },
+    referralFee: { type: 'number', description: 'Referral fee percentage' },
+    totalRevenue: { type: 'number', description: 'Total revenue generated' },
+    totalDeals: { type: 'number', description: 'Total deals closed' },
+    lastActivityDate: { type: 'date', description: 'Date of last activity' },
+    nda: { type: 'boolean', description: 'NDA in place' },
+    ndaDate: { type: 'date', description: 'NDA signed date' },
+    portalAccess: { type: 'boolean', description: 'Has partner portal access' },
+    enablementComplete: { type: 'boolean', description: 'Enablement training completed' },
+    score: { type: 'number', description: 'Partner performance score', optional: true },
+    notes: { type: 'string', description: 'Internal notes', optional: true },
+    tags: { type: 'string[]', description: 'Partner tags' },
+    metadata: { type: 'object', description: 'Additional metadata', optional: true },
+  },
+  relationships: {
+    partnership: { type: 'partnership', description: 'Active partnership agreement', backref: 'partner' },
+    deals: { type: 'deal[]', description: 'Deals sourced by partner', backref: 'partner' },
+    leads: { type: 'lead[]', description: 'Leads referred by partner', backref: 'partner' },
+    contacts: { type: 'contact[]', description: 'Partner contacts', backref: 'partner' },
+    integrations: { type: 'integration[]', description: 'Technical integrations', backref: 'partner' },
+  },
+  actions: ['create', 'update', 'onboard', 'activate', 'deactivate', 'suspend', 'terminate', 'upgrade', 'downgrade', 'certify', 'enable', 'review', 'renew'],
+  events: ['created', 'updated', 'onboarded', 'activated', 'deactivated', 'suspended', 'terminated', 'upgraded', 'downgraded', 'certified', 'enabled', 'reviewed', 'renewed'],
+}
+
+export const Vendor: Noun = {
+  singular: 'vendor',
+  plural: 'vendors',
+  description: 'An external supplier or service provider',
+  properties: {
+    name: { type: 'string', description: 'Vendor name' },
+    type: { type: 'string', description: 'Type of vendor', examples: ['supplier', 'contractor', 'consultant', 'SaaS', 'service', 'manufacturer'] },
+    category: { type: 'string', description: 'Vendor category', examples: ['technology', 'operations', 'marketing', 'HR', 'legal', 'finance', 'facilities'] },
+    status: { type: 'string', description: 'Vendor status', examples: ['prospect', 'evaluating', 'approved', 'active', 'preferred', 'suspended', 'terminated'] },
+    website: { type: 'string', description: 'Vendor website' },
+    description: { type: 'string', description: 'Vendor description' },
+    primaryContact: { type: 'string', description: 'Primary contact name' },
+    email: { type: 'string', description: 'Contact email' },
+    phone: { type: 'string', description: 'Contact phone' },
+    address: { type: 'string', description: 'Vendor address' },
+    country: { type: 'string', description: 'Country of operation' },
+    taxId: { type: 'string', description: 'Tax identification number' },
+    paymentTerms: { type: 'string', description: 'Payment terms', examples: ['net-15', 'net-30', 'net-60', 'net-90', 'on-receipt'] },
+    currency: { type: 'string', description: 'Preferred currency' },
+    bankDetails: { type: 'object', description: 'Banking information', optional: true },
+    contractValue: { type: 'number', description: 'Total contract value' },
+    annualSpend: { type: 'number', description: 'Annual spend amount' },
+    startDate: { type: 'date', description: 'Relationship start date' },
+    contractEndDate: { type: 'date', description: 'Current contract end date' },
+    lastOrderDate: { type: 'date', description: 'Last order date' },
+    riskLevel: { type: 'string', description: 'Risk assessment', examples: ['low', 'medium', 'high', 'critical'] },
+    complianceStatus: { type: 'string', description: 'Compliance status', examples: ['compliant', 'pending', 'non-compliant', 'exempt'] },
+    slaScore: { type: 'number', description: 'SLA performance score' },
+    qualityScore: { type: 'number', description: 'Quality rating score' },
+    certifications: { type: 'string[]', description: 'Vendor certifications', examples: ['SOC2', 'ISO27001', 'GDPR', 'HIPAA'] },
+    insuranceCoverage: { type: 'boolean', description: 'Has insurance coverage' },
+    insuranceExpiry: { type: 'date', description: 'Insurance expiry date', optional: true },
+    notes: { type: 'string', description: 'Internal notes', optional: true },
+    tags: { type: 'string[]', description: 'Vendor tags' },
+    metadata: { type: 'object', description: 'Additional metadata', optional: true },
+  },
+  relationships: {
+    contracts: { type: 'contract[]', description: 'Vendor contracts', backref: 'vendor' },
+    orders: { type: 'order[]', description: 'Purchase orders', backref: 'vendor' },
+    invoices: { type: 'invoice[]', description: 'Vendor invoices', backref: 'vendor' },
+    contacts: { type: 'contact[]', description: 'Vendor contacts', backref: 'vendor' },
+    expenses: { type: 'expense[]', description: 'Related expenses', backref: 'vendor' },
+  },
+  actions: ['create', 'update', 'evaluate', 'approve', 'reject', 'activate', 'suspend', 'terminate', 'review', 'audit', 'renew'],
+  events: ['created', 'updated', 'evaluated', 'approved', 'rejected', 'activated', 'suspended', 'terminated', 'reviewed', 'audited', 'renewed'],
+}
+
+export const Affiliate: Noun = {
+  singular: 'affiliate',
+  plural: 'affiliates',
+  description: 'An affiliate partner who promotes products for commission',
+  properties: {
+    name: { type: 'string', description: 'Affiliate name' },
+    type: { type: 'string', description: 'Type of affiliate', examples: ['individual', 'company', 'influencer', 'blogger', 'publisher', 'network'] },
+    status: { type: 'string', description: 'Affiliate status', examples: ['applied', 'pending', 'approved', 'active', 'suspended', 'terminated'] },
+    email: { type: 'string', description: 'Contact email' },
+    website: { type: 'string', description: 'Affiliate website or channel' },
+    platform: { type: 'string', description: 'Primary platform', examples: ['blog', 'youtube', 'instagram', 'tiktok', 'twitter', 'podcast', 'newsletter'] },
+    audienceSize: { type: 'number', description: 'Estimated audience size' },
+    niche: { type: 'string', description: 'Content niche or focus area' },
+    country: { type: 'string', description: 'Country of operation' },
+    affiliateId: { type: 'string', description: 'Unique affiliate identifier' },
+    referralCode: { type: 'string', description: 'Unique referral code' },
+    trackingLink: { type: 'string', description: 'Affiliate tracking link' },
+    commissionRate: { type: 'number', description: 'Commission percentage' },
+    commissionType: { type: 'string', description: 'Commission type', examples: ['percentage', 'flat-rate', 'tiered', 'recurring'] },
+    cookieDuration: { type: 'number', description: 'Cookie duration in days' },
+    payoutThreshold: { type: 'number', description: 'Minimum payout amount' },
+    payoutMethod: { type: 'string', description: 'Preferred payout method', examples: ['paypal', 'bank-transfer', 'check', 'crypto', 'gift-card'] },
+    payoutDetails: { type: 'object', description: 'Payout account details', optional: true },
+    totalClicks: { type: 'number', description: 'Total clicks generated' },
+    totalConversions: { type: 'number', description: 'Total conversions' },
+    conversionRate: { type: 'number', description: 'Conversion rate' },
+    totalRevenue: { type: 'number', description: 'Total revenue generated' },
+    totalCommissions: { type: 'number', description: 'Total commissions earned' },
+    pendingCommissions: { type: 'number', description: 'Pending commission amount' },
+    paidCommissions: { type: 'number', description: 'Total paid commissions' },
+    lastReferralDate: { type: 'date', description: 'Date of last referral' },
+    lastPayoutDate: { type: 'date', description: 'Date of last payout' },
+    joinDate: { type: 'date', description: 'Date joined program' },
+    tier: { type: 'string', description: 'Affiliate tier', examples: ['bronze', 'silver', 'gold', 'platinum', 'diamond'] },
+    promotionalMaterials: { type: 'boolean', description: 'Has access to promo materials' },
+    customLandingPage: { type: 'boolean', description: 'Has custom landing page' },
+    notes: { type: 'string', description: 'Internal notes', optional: true },
+    tags: { type: 'string[]', description: 'Affiliate tags' },
+    metadata: { type: 'object', description: 'Additional metadata', optional: true },
+  },
+  relationships: {
+    referrals: { type: 'lead[]', description: 'Referred leads', backref: 'affiliate' },
+    conversions: { type: 'deal[]', description: 'Converted deals', backref: 'affiliate' },
+    payouts: { type: 'expense[]', description: 'Commission payouts', backref: 'affiliate' },
+    campaigns: { type: 'campaign[]', description: 'Promotional campaigns', backref: 'affiliate' },
+  },
+  actions: ['create', 'update', 'approve', 'reject', 'activate', 'suspend', 'terminate', 'upgrade', 'downgrade', 'payout', 'track'],
+  events: ['created', 'updated', 'approved', 'rejected', 'activated', 'suspended', 'terminated', 'upgraded', 'downgraded', 'paidOut', 'tracked'],
+}
+
+export const Partnership: Noun = {
+  singular: 'partnership',
+  plural: 'partnerships',
+  description: 'A formal partnership agreement between organizations',
+  properties: {
+    name: { type: 'string', description: 'Partnership name' },
+    type: { type: 'string', description: 'Type of partnership', examples: ['strategic', 'technology', 'channel', 'co-marketing', 'co-selling', 'integration', 'reseller', 'white-label', 'OEM'] },
+    status: { type: 'string', description: 'Partnership status', examples: ['proposed', 'negotiating', 'pending-approval', 'active', 'on-hold', 'expired', 'terminated'] },
+    description: { type: 'string', description: 'Partnership description' },
+    objectives: { type: 'string[]', description: 'Partnership objectives' },
+    startDate: { type: 'date', description: 'Partnership start date' },
+    endDate: { type: 'date', description: 'Partnership end date' },
+    autoRenew: { type: 'boolean', description: 'Auto-renewal enabled' },
+    renewalNoticeDays: { type: 'number', description: 'Days notice required for non-renewal' },
+    revenueShare: { type: 'number', description: 'Revenue share percentage' },
+    referralFee: { type: 'number', description: 'Referral fee amount or percentage' },
+    minimumCommitment: { type: 'number', description: 'Minimum annual commitment' },
+    exclusivity: { type: 'boolean', description: 'Exclusive partnership' },
+    exclusivityTerms: { type: 'string', description: 'Exclusivity terms', optional: true },
+    territories: { type: 'string[]', description: 'Geographic territories' },
+    products: { type: 'string[]', description: 'Products covered' },
+    useCase: { type: 'string', description: 'Primary use case or focus' },
+    targetRevenue: { type: 'number', description: 'Target revenue goal' },
+    actualRevenue: { type: 'number', description: 'Actual revenue achieved' },
+    targetDeals: { type: 'number', description: 'Target number of deals' },
+    actualDeals: { type: 'number', description: 'Actual deals closed' },
+    ndaRequired: { type: 'boolean', description: 'NDA required' },
+    ndaSigned: { type: 'boolean', description: 'NDA signed' },
+    contractSigned: { type: 'boolean', description: 'Contract signed' },
+    jointMarketingBudget: { type: 'number', description: 'Joint marketing budget', optional: true },
+    coMarketingApproved: { type: 'boolean', description: 'Co-marketing approved' },
+    integrationRequired: { type: 'boolean', description: 'Technical integration required' },
+    integrationComplete: { type: 'boolean', description: 'Integration completed' },
+    internalOwner: { type: 'string', description: 'Internal partnership owner' },
+    partnerOwner: { type: 'string', description: 'Partner side owner' },
+    executiveSponsor: { type: 'string', description: 'Executive sponsor' },
+    healthScore: { type: 'number', description: 'Partnership health score' },
+    lastReviewDate: { type: 'date', description: 'Last partnership review' },
+    nextReviewDate: { type: 'date', description: 'Next scheduled review' },
+    notes: { type: 'string', description: 'Internal notes', optional: true },
+    tags: { type: 'string[]', description: 'Partnership tags' },
+    metadata: { type: 'object', description: 'Additional metadata', optional: true },
+  },
+  relationships: {
+    partner: { type: 'partner', description: 'Partner organization', backref: 'partnerships', required: true },
+    contract: { type: 'contract', description: 'Partnership contract', backref: 'partnership' },
+    deals: { type: 'deal[]', description: 'Partnership deals', backref: 'partnership' },
+    campaigns: { type: 'campaign[]', description: 'Joint campaigns', backref: 'partnership' },
+    integrations: { type: 'integration[]', description: 'Technical integrations', backref: 'partnership' },
+    milestones: { type: 'milestone[]', description: 'Partnership milestones', backref: 'partnership' },
+  },
+  actions: ['create', 'update', 'propose', 'negotiate', 'approve', 'reject', 'activate', 'pause', 'resume', 'extend', 'terminate', 'renew', 'review'],
+  events: ['created', 'updated', 'proposed', 'negotiated', 'approved', 'rejected', 'activated', 'paused', 'resumed', 'extended', 'terminated', 'renewed', 'reviewed'],
+}
+
+export const Integration: Noun = {
+  singular: 'integration',
+  plural: 'integrations',
+  description: 'A technical integration with a partner or third-party system',
+  properties: {
+    name: { type: 'string', description: 'Integration name' },
+    type: { type: 'string', description: 'Type of integration', examples: ['API', 'webhook', 'SDK', 'embed', 'SSO', 'data-sync', 'marketplace'] },
+    status: { type: 'string', description: 'Integration status', examples: ['planning', 'development', 'testing', 'staging', 'live', 'deprecated', 'disabled'] },
+    description: { type: 'string', description: 'Integration description' },
+    direction: { type: 'string', description: 'Data flow direction', examples: ['inbound', 'outbound', 'bidirectional'] },
+    category: { type: 'string', description: 'Integration category', examples: ['CRM', 'ERP', 'marketing', 'analytics', 'payment', 'communication', 'productivity'] },
+    authentication: { type: 'string', description: 'Authentication method', examples: ['API-key', 'OAuth2', 'JWT', 'basic', 'certificate', 'SAML'] },
+    endpoint: { type: 'string', description: 'API endpoint or URL' },
+    version: { type: 'string', description: 'Integration version' },
+    documentation: { type: 'string', description: 'Documentation URL' },
+    syncFrequency: { type: 'string', description: 'Data sync frequency', examples: ['real-time', 'hourly', 'daily', 'weekly', 'on-demand'] },
+    dataMapping: { type: 'object', description: 'Field mapping configuration', optional: true },
+    rateLimits: { type: 'object', description: 'Rate limiting configuration', optional: true },
+    lastSyncDate: { type: 'date', description: 'Last successful sync' },
+    lastSyncStatus: { type: 'string', description: 'Last sync status', examples: ['success', 'partial', 'failed'] },
+    errorCount: { type: 'number', description: 'Recent error count' },
+    recordsProcessed: { type: 'number', description: 'Total records processed' },
+    enabled: { type: 'boolean', description: 'Integration enabled' },
+    sandboxAvailable: { type: 'boolean', description: 'Sandbox environment available' },
+    productionReady: { type: 'boolean', description: 'Ready for production' },
+    maintainer: { type: 'string', description: 'Internal maintainer' },
+    supportContact: { type: 'string', description: 'Support contact' },
+    launchDate: { type: 'date', description: 'Integration launch date' },
+    deprecationDate: { type: 'date', description: 'Planned deprecation date', optional: true },
+    notes: { type: 'string', description: 'Internal notes', optional: true },
+    tags: { type: 'string[]', description: 'Integration tags' },
+    metadata: { type: 'object', description: 'Additional metadata', optional: true },
+  },
+  relationships: {
+    partner: { type: 'partner', description: 'Integration partner', backref: 'integrations' },
+    partnership: { type: 'partnership', description: 'Related partnership', backref: 'integrations' },
+    product: { type: 'product', description: 'Product integrated', backref: 'integrations' },
+  },
+  actions: ['create', 'update', 'develop', 'test', 'deploy', 'enable', 'disable', 'sync', 'debug', 'deprecate', 'version'],
+  events: ['created', 'updated', 'developed', 'tested', 'deployed', 'enabled', 'disabled', 'synced', 'debugged', 'deprecated', 'versioned'],
+}
+
+export const Reseller: Noun = {
+  singular: 'reseller',
+  plural: 'resellers',
+  description: 'A reseller partner who sells products on behalf of the organization',
+  properties: {
+    name: { type: 'string', description: 'Reseller name' },
+    type: { type: 'string', description: 'Type of reseller', examples: ['VAR', 'distributor', 'MSP', 'SI', 'retail', 'online'] },
+    tier: { type: 'string', description: 'Reseller tier', examples: ['authorized', 'premier', 'elite', 'master'] },
+    status: { type: 'string', description: 'Reseller status', examples: ['prospect', 'onboarding', 'active', 'suspended', 'terminated'] },
+    region: { type: 'string', description: 'Primary region' },
+    territories: { type: 'string[]', description: 'Authorized territories' },
+    verticals: { type: 'string[]', description: 'Industry verticals' },
+    products: { type: 'string[]', description: 'Authorized products' },
+    discountLevel: { type: 'number', description: 'Discount percentage from list price' },
+    margin: { type: 'number', description: 'Expected margin percentage' },
+    minimumOrder: { type: 'number', description: 'Minimum order value' },
+    creditLimit: { type: 'number', description: 'Credit limit' },
+    paymentTerms: { type: 'string', description: 'Payment terms' },
+    quota: { type: 'number', description: 'Annual sales quota' },
+    yearToDateSales: { type: 'number', description: 'Year to date sales' },
+    totalSales: { type: 'number', description: 'Total lifetime sales' },
+    dealCount: { type: 'number', description: 'Total deals closed' },
+    averageDealSize: { type: 'number', description: 'Average deal size' },
+    certifiedReps: { type: 'number', description: 'Number of certified sales reps' },
+    technicalCerts: { type: 'number', description: 'Number of technical certifications' },
+    enablementComplete: { type: 'boolean', description: 'Enablement training completed' },
+    portalAccess: { type: 'boolean', description: 'Has reseller portal access' },
+    dealRegistration: { type: 'boolean', description: 'Can register deals' },
+    coopFunds: { type: 'number', description: 'Co-op marketing funds available' },
+    mdf: { type: 'number', description: 'Market development funds' },
+    lastOrderDate: { type: 'date', description: 'Last order date' },
+    startDate: { type: 'date', description: 'Partnership start date' },
+    renewalDate: { type: 'date', description: 'Next renewal date' },
+    notes: { type: 'string', description: 'Internal notes', optional: true },
+    tags: { type: 'string[]', description: 'Reseller tags' },
+    metadata: { type: 'object', description: 'Additional metadata', optional: true },
+  },
+  relationships: {
+    partner: { type: 'partner', description: 'Parent partner record', backref: 'reseller' },
+    deals: { type: 'deal[]', description: 'Reseller deals', backref: 'reseller' },
+    orders: { type: 'order[]', description: 'Purchase orders', backref: 'reseller' },
+    customers: { type: 'customer[]', description: 'End customers', backref: 'reseller' },
+    contacts: { type: 'contact[]', description: 'Reseller contacts', backref: 'reseller' },
+  },
+  actions: ['create', 'update', 'onboard', 'activate', 'suspend', 'terminate', 'upgrade', 'downgrade', 'certify', 'enable', 'allocateFunds'],
+  events: ['created', 'updated', 'onboarded', 'activated', 'suspended', 'terminated', 'upgraded', 'downgraded', 'certified', 'enabled', 'fundsAllocated'],
+}
+
+// Export all partnership entities
+export const PartnershipEntities = {
+  Partner,
+  Vendor,
+  Affiliate,
+  Partnership,
+  Integration,
+  Reseller,
+}
+
+export default PartnershipEntities

package/src/entities/planning.ts

@@ -0,0 +1,307 @@
+import type { Noun } from 'ai-database'
+
+/**
+ * Planning Entities
+ * Issue, Plan - Planning-focused abstractions for tracking work
+ *
+ * These complement the execution-focused Task in digital-tasks
+ * and the project management entities in projects.ts
+ *
+ * Key distinction:
+ * - Task (digital-tasks): Function execution with workers, queues, runtime
+ * - Task (projects.ts): Project management work item
+ * - Issue (planning.ts): Planning-focused with design, acceptance criteria, notes
+ */
+
+/**
+ * WorkItem - A planning-focused work item (ticket/issue)
+ *
+ * Models the full lifecycle of work from ideation through completion:
+ * - What: title, description
+ * - Why: context, business value
+ * - How: design (implementation approach)
+ * - Done: acceptance criteria
+ * - Context: notes (session handoff, progress tracking)
+ *
+ * This abstraction is backend-agnostic and can be implemented by:
+ * - beads (SQLite) - maps to beads Issue
+ * - Linear - maps to Linear Issue
+ * - GitHub Issues
+ * - Jira - maps to Jira Issue/Ticket
+ * - etc.
+ *
+ * Note: Distinct from entities/risk.ts Issue which represents
+ * operational/business issues (problems requiring resolution).
+ * WorkItem represents planned development work.
+ */
+export const WorkItem: Noun = {
+  singular: 'workItem',
+  plural: 'workItems',
+  description: 'A planning-focused work item with design and acceptance criteria',
+  properties: {
+    // Identity
+    id: { type: 'string', description: 'Unique issue ID' },
+    title: { type: 'string', description: 'Issue title (concise, action-oriented)' },
+
+    // What & Why
+    description: { type: 'string', description: 'Problem statement - WHY this matters (immutable once set)' },
+
+    // How
+    design: { type: 'string', description: 'Implementation approach - HOW to build (can evolve during work)' },
+
+    // Done
+    acceptanceCriteria: { type: 'string', description: 'Definition of done - WHAT success looks like (markdown checklist)' },
+
+    // Context
+    notes: { type: 'string', description: 'Session context - COMPLETED/IN_PROGRESS/NEXT format for handoff' },
+
+    // Status
+    status: {
+      type: 'string',
+      description: 'Issue status',
+      examples: ['open', 'in_progress', 'blocked', 'closed'],
+    },
+    priority: {
+      type: 'number',
+      description: 'Priority level (0=critical, 1=high, 2=normal, 3=low)',
+    },
+    issueType: {
+      type: 'string',
+      description: 'Type of issue',
+      examples: ['task', 'bug', 'feature', 'epic', 'chore'],
+    },
+
+    // Assignment
+    assignee: { type: 'string', description: 'Assigned person or agent', optional: true },
+
+    // Timing
+    createdAt: { type: 'datetime', description: 'When created' },
+    updatedAt: { type: 'datetime', description: 'When last updated' },
+    closedAt: { type: 'datetime', description: 'When closed', optional: true },
+    closeReason: { type: 'string', description: 'Why issue was closed', optional: true },
+
+    // Estimation
+    estimatedMinutes: { type: 'number', description: 'Estimated time in minutes', optional: true },
+
+    // External references
+    externalRef: { type: 'string', description: 'External system reference (PR, commit, etc.)', optional: true },
+
+    // Compaction (for long-running issues)
+    compactionLevel: { type: 'number', description: 'How many times compressed', optional: true },
+
+    // Metadata
+    labels: { type: 'string[]', description: 'Issue labels/tags' },
+    metadata: { type: 'object', description: 'Additional metadata', optional: true },
+  },
+  relationships: {
+    // Hierarchy
+    parent: { type: 'workItem', description: 'Parent work item (for epics)', backref: 'children' },
+    children: { type: 'workItem[]', description: 'Child work items', backref: 'parent' },
+
+    // Dependencies
+    blockedBy: { type: 'workItem[]', description: 'Work items blocking this one', backref: 'blocks' },
+    blocks: { type: 'workItem[]', description: 'Work items this one blocks', backref: 'blockedBy' },
+    relatedTo: { type: 'workItem[]', description: 'Related work items (soft link)', backref: 'relatedTo' },
+    discoveredFrom: { type: 'workItem', description: 'Work item this was discovered from (provenance)', backref: 'discovered' },
+    discovered: { type: 'workItem[]', description: 'Work items discovered while working on this', backref: 'discoveredFrom' },
+
+    // Project context
+    project: { type: 'project', description: 'Parent project', backref: 'workItems' },
+
+    // Plan context
+    plan: { type: 'plan', description: 'Parent plan', backref: 'workItems' },
+
+    // Comments
+    comments: { type: 'comment[]', description: 'Work item comments', backref: 'workItem' },
+
+    // Events
+    events: { type: 'event[]', description: 'Work item events (audit trail)', backref: 'workItem' },
+  },
+  actions: [
+    'create',
+    'update',
+    'assign',
+    'start',
+    'block',
+    'unblock',
+    'close',
+    'reopen',
+    'comment',
+    'link',
+    'unlink',
+  ],
+  events: [
+    'created',
+    'updated',
+    'assigned',
+    'started',
+    'blocked',
+    'unblocked',
+    'closed',
+    'reopened',
+    'commented',
+    'linked',
+    'unlinked',
+  ],
+}
+
+/**
+ * Comment - A comment on an issue
+ */
+export const Comment: Noun = {
+  singular: 'comment',
+  plural: 'comments',
+  description: 'A comment on an issue',
+  properties: {
+    id: { type: 'string', description: 'Comment ID' },
+    text: { type: 'string', description: 'Comment text (markdown)' },
+    author: { type: 'string', description: 'Comment author' },
+    createdAt: { type: 'datetime', description: 'When created' },
+  },
+  relationships: {
+    workItem: { type: 'workItem', description: 'Parent work item', backref: 'comments', required: true },
+  },
+  actions: ['create', 'update', 'delete'],
+  events: ['created', 'updated', 'deleted'],
+}
+
+/**
+ * Event - An audit trail event on an issue
+ */
+export const Event: Noun = {
+  singular: 'event',
+  plural: 'events',
+  description: 'An audit trail event for issue changes',
+  properties: {
+    id: { type: 'string', description: 'Event ID' },
+    eventType: {
+      type: 'string',
+      description: 'Type of event',
+      examples: [
+        'created',
+        'status_changed',
+        'priority_changed',
+        'assigned',
+        'unassigned',
+        'dependency_added',
+        'dependency_removed',
+        'label_added',
+        'label_removed',
+        'commented',
+      ],
+    },
+    actor: { type: 'string', description: 'Who triggered the event' },
+    oldValue: { type: 'string', description: 'Previous value', optional: true },
+    newValue: { type: 'string', description: 'New value', optional: true },
+    comment: { type: 'string', description: 'Optional comment on the change', optional: true },
+    createdAt: { type: 'datetime', description: 'When event occurred' },
+  },
+  relationships: {
+    workItem: { type: 'workItem', description: 'Parent work item', backref: 'events', required: true },
+  },
+  actions: ['create'],
+  events: ['created'],
+}
+
+/**
+ * WorkItemComment - Alias for Comment (for clarity)
+ */
+export const WorkItemComment = Comment
+
+/**
+ * WorkItemEvent - Alias for Event (for clarity)
+ */
+export const WorkItemEvent = Event
+
+/**
+ * Plan - A high-level planning document that generates issues
+ *
+ * Bridges Strategy → Plan → Issues → Tasks
+ *
+ * A Plan captures:
+ * - Goals and objectives
+ * - Constraints and assumptions
+ * - Design decisions
+ * - Issue breakdown
+ */
+export const Plan: Noun = {
+  singular: 'plan',
+  plural: 'plans',
+  description: 'A high-level planning document that generates issues',
+  properties: {
+    id: { type: 'string', description: 'Plan ID' },
+    title: { type: 'string', description: 'Plan title' },
+    description: { type: 'string', description: 'What this plan aims to achieve' },
+
+    // Goals
+    objectives: { type: 'string[]', description: 'Plan objectives' },
+    successCriteria: { type: 'string[]', description: 'How we know the plan succeeded' },
+
+    // Constraints
+    constraints: { type: 'string[]', description: 'Constraints to work within' },
+    assumptions: { type: 'string[]', description: 'Assumptions made' },
+    risks: { type: 'string[]', description: 'Identified risks' },
+
+    // Design
+    approach: { type: 'string', description: 'Overall approach (markdown)' },
+    decisions: { type: 'string[]', description: 'Key decisions made' },
+    tradeoffs: { type: 'string[]', description: 'Trade-offs considered' },
+
+    // Status
+    status: {
+      type: 'string',
+      description: 'Plan status',
+      examples: ['draft', 'review', 'approved', 'in_progress', 'completed', 'abandoned'],
+    },
+
+    // Timing
+    createdAt: { type: 'datetime', description: 'When created' },
+    updatedAt: { type: 'datetime', description: 'When last updated' },
+    approvedAt: { type: 'datetime', description: 'When approved', optional: true },
+    approvedBy: { type: 'string', description: 'Who approved', optional: true },
+
+    // Metadata
+    tags: { type: 'string[]', description: 'Plan tags' },
+    metadata: { type: 'object', description: 'Additional metadata', optional: true },
+  },
+  relationships: {
+    // Work items generated from this plan
+    workItems: { type: 'workItem[]', description: 'Work items generated from this plan', backref: 'plan' },
+
+    // Project context
+    project: { type: 'project', description: 'Parent project', backref: 'plans' },
+
+    // Author
+    author: { type: 'resource', description: 'Plan author', backref: 'plans' },
+  },
+  actions: ['create', 'update', 'submit', 'approve', 'reject', 'start', 'complete', 'abandon'],
+  events: ['created', 'updated', 'submitted', 'approved', 'rejected', 'started', 'completed', 'abandoned'],
+}
+
+/**
+ * Dependency types for issue relationships
+ */
+export const DependencyTypes = {
+  /** Hard blocker - issue A blocks issue B from starting */
+  blocks: 'blocks',
+  /** Soft link - issues are related but not blocking */
+  related: 'related',
+  /** Hierarchical - epic/subtask relationship */
+  parentChild: 'parent-child',
+  /** Provenance - issue B discovered while working on A */
+  discoveredFrom: 'discovered-from',
+} as const
+
+export type DependencyType = (typeof DependencyTypes)[keyof typeof DependencyTypes]
+
+// Export all planning entities
+export const PlanningEntities = {
+  WorkItem,
+  WorkItemComment,
+  WorkItemEvent,
+  Comment,
+  Event,
+  Plan,
+}
+
+export default PlanningEntities