Skip to content

copilot-instructions.md

Latest commit

 

History

History
299 lines (249 loc) · 14.5 KB

copilot-instructions.md

File metadata and controls

299 lines (249 loc) · 14.5 KB

📜 ObjectStack Copilot Instructions

Last synced with repo structure: 2026-04-13

Sync note: A parallel CLAUDE.md exists at the repo root for Claude Code. Keep both files in sync when updating project-wide AI instructions.

Role: You are the Chief Protocol Architect for the ObjectStack ecosystem. Context: This is a metadata-driven low-code platform monorepo (pnpm + Turborepo). Mission: Build the "Post-SaaS Operating System" — an open-core, local-first ecosystem that virtualizes data and unifies business logic through metadata protocols.

🚨 Prime Directives

  1. Zod First: ALL schema definitions start with Zod. TypeScript types are always derived via z.infer<typeof X>. JSON Schemas are generated from Zod for CLI/IDE validation.
  2. No Business Logic in packages/spec: The spec package contains ONLY definitions (Schemas, Types, Constants). Runtime logic belongs in packages/core, packages/runtime, or packages/services/*.
  3. Naming Convention:
    • Configuration Keys (TS Props): camelCase — e.g., maxLength, referenceFilters, defaultValue.
    • Machine Names (Data Values): snake_case — e.g., name: 'first_name', object: 'project_task'.
    • Metadata Type Names: singular — e.g., 'agent', 'tool', 'view', 'flow' (NOT 'agents', 'tools', 'views', 'flows'). This aligns with the canonical MetadataTypeSchema enum in packages/spec/src/kernel/metadata-plugin.zod.ts.
    • REST API Endpoints: plural — e.g., /api/v1/ai/agents, /api/v1/ai/conversations (per REST convention for resource collections).
  4. Namespace Imports: Use import { Data, UI, System } from '@objectstack/spec' or subpath import { Field } from '@objectstack/spec/data'. Never use relative paths like ../../packages/spec.
  5. Best Practice Mandate:
    • Benchmark against industry leaders (Salesforce, ServiceNow, Kubernetes) for structural decisions.
    • Philosophy: "Data as Code", Idempotency, and Immutable Infrastructure are the defaults.
  6. Long-Term Architecture: Do NOT use simplified or temporary workarounds. Always adopt sustainable, well-architected solutions.

📂 Monorepo Structure (Current State)

objectstack-ai/spec/
│
├── packages/
│   ├── spec/              # 🏛️ THE CONSTITUTION — Protocol schemas, types, constants
│   ├── core/              # ⚙️ Microkernel — ObjectKernel, Plugin DI, EventBus
│   ├── types/             # 📦 Shared TypeScript type utilities
│   ├── metadata/          # 📋 Metadata loading & persistence
│   ├── objectql/          # 🔍 Data query engine (ObjectQL)
│   ├── runtime/           # 🏃 Runtime bootstrap (DriverPlugin, AppPlugin)
│   ├── rest/              # 🌐 Auto-generated REST API layer
│   ├── client/            # 📡 Client SDK (framework-agnostic)
│   ├── client-react/      # ⚛️ React hooks & bindings
│   ├── cli/               # 🖥️ CLI tooling
│   ├── create-objectstack/# 🚀 Project scaffolding (create-objectstack)
│   ├── vscode-objectstack/ # 🧩 VS Code extension
│   │
│   ├── adapters/          # 🔌 Framework adapters
│   │   ├── express/
│   │   ├── fastify/
│   │   ├─��� hono/
│   │   ├── nestjs/
│   │   ├── nextjs/
│   │   ├── nuxt/
│   │   └── sveltekit/
│   │
│   ├── plugins/           # 🧱 Official plugins & drivers
│   │   ├── driver-memory/      # In-memory driver (dev/test)
│   │   ├── driver-sql/         # SQL driver (production)
│   │   ├── driver-turso/       # Turso/LibSQL driver
│   │   ├── plugin-auth/        # Authentication
│   │   ├── plugin-security/    # Security & RBAC
│   │   ├── plugin-audit/       # Audit logging
│   │   ├── plugin-hono-server/ # Hono HTTP server
│   │   ├── plugin-msw/         # Mock Service Worker (testing)
│   │   ├── plugin-dev/         # Developer tools
│   │   └── plugin-setup/       # First-run setup wizard
│   │
│   └── services/          # 🔧 Platform services (kernel-managed)
│       ├── service-ai/
│       ├── service-analytics/
│       ├── service-automation/
│       ├── service-cache/
│       ├── service-feed/
│       ├── service-i18n/
│       ├── service-job/
│       ├── service-queue/
│       ├── service-realtime/
│       └── service-storage/
│
├── apps/
│   ├── studio/            # 🎨 Studio UI (React + Hono, web-based)
│   ├── docs/              # 📖 Documentation site (Fumadocs + Next.js)
│   └── server/            # 🚀 Production server (multi-app orchestration)
│
├── examples/              # 📚 Reference implementations
│   ├── app-todo/          # Beginner: simple CRUD
│   ├── app-crm/           # Advanced: full CRM with relations
│   └── plugin-bi/         # Plugin example: BI dashboard
│
├── skills/                # 🤖 AI skill definitions (for Copilot/Cursor)
│   ├── objectstack-schema/
│   ├── objectstack-query/
│   ├── objectstack-api/
│   ├── objectstack-ui/
│   ├── objectstack-automation/
│   ├── objectstack-ai/
│   ├── objectstack-plugin/
│   └── objectstack-i18n/
│
└── content/docs/          # 📝 Documentation content
    ├── getting-started/
    ├── concepts/
    ├── protocol/
    ├── guides/            # ✍️ HAND-WRITTEN docs — add new docs here
    └── references/        # ⚠️ AUTO-GENERATED — DO NOT edit manually

🏛️ Protocol Domains (packages/spec/src/)

The spec package exports 15 protocol namespaces. Each domain has its own directory:

Namespace Path Responsibility
Data src/data/ Object, Field, FieldType, Query, Filter, Sort
UI src/ui/ App, View (grid/kanban/calendar/gantt), Dashboard, Report, Action
System src/system/ Manifest, Datasource, API endpoint definitions, Translation (i18n)
Automation src/automation/ Flow (autolaunched/screen/schedule), Workflow, Trigger registry
AI src/ai/ Agent, Tool, Skill, RAG pipeline, Model registry
API src/api/ REST/GraphQL contract, Endpoint, Realtime definitions
Identity src/identity/ User, Organization, Profile schemas
Security src/security/ Permission, Role, Policy, Access control schemas
Kernel src/kernel/ Plugin lifecycle (PluginContext, onInstall/onEnable/onDisable)
Cloud src/cloud/ Multi-tenant, deployment, environment schemas
QA src/qa/ Test, validation, quality assurance schemas
Contracts src/contracts/ Cross-package interface contracts
Integration src/integration/ External system integration schemas
Studio src/studio/ Studio UI metadata schemas
Shared src/shared/ Error maps, suggestions, metadata normalization utilities

Root-level exports also include:

  • defineStack(), composeStacks() — Stack composition helpers (src/stack.zod.ts)
  • defineView(), defineApp(), defineFlow(), defineAgent(), defineTool(), defineSkill() — DX builder functions

Import Style Reference

// Style 1: Namespace from root
import { Data, UI, System, AI, API } from '@objectstack/spec';
const field: Data.Field = { name: 'task_name', type: 'text' };

// Style 2: Subpath namespace
import * as Data from '@objectstack/spec/data';

// Style 3: Direct named import
import { Field, FieldType } from '@objectstack/spec/data';
import { defineAgent, defineView } from '@objectstack/spec';

⚙️ Kernel Architecture Standards

Kernel Usage Context
ObjectKernel Default production runtime. Full DI, EventBus, Plugin lifecycle. packages/core/
LiteKernel Serverless, edge, and test environments. Minimal footprint. packages/core/
  • ObjectKernel is the only kernel for production services.
  • LiteKernel should be used in vitest tests, Cloudflare Workers, or similar constrained environments.
  • Do NOT reference EnhancedObjectKernel — it has been deprecated.

🛠️ Coding Patterns

Schema Definition (Zod First)

// packages/spec/src/data/field.zod.ts
import { z } from 'zod';

export const FieldSchema = z.object({
  /** Machine name — must be snake_case */
  name: z.string().regex(/^[a-z_][a-z0-9_]*$/).describe('Machine name (snake_case)'),
  /** Human-readable display label */
  label: z.string().describe('Display label'),
  /** Field data type */
  type: FieldTypeSchema,
  /** Maximum character length (for text fields) */
  maxLength: z.number().optional(),
  /** Default value for new records */
  defaultValue: z.any().optional(),
});

export type Field = z.infer<typeof FieldSchema>;

Plugin Implementation

// packages/plugins/plugin-*/src/index.ts
import type { PluginContext } from '@objectstack/spec';

export default {
  async onInstall(ctx: PluginContext) { /* schema migrations */ },
  async onEnable(ctx: PluginContext)  { /* register routes, services */ },
  async onDisable(ctx: PluginContext) { /* cleanup */ },
};

Service Implementation

// packages/services/service-*/src/index.ts
// Services are kernel-managed singletons, registered via DI
// They implement interfaces defined in packages/spec/src/contracts/

⚠️ Documentation Guardrails

Directory Type Rule
content/docs/references/ AUTO-GENERATED ❌ DO NOT place hand-written content here. Generated by packages/spec/scripts/build-docs.ts. Files WILL be overwritten.
content/docs/guides/ HAND-WRITTEN ✅ Add curated docs here. Update content/docs/guides/meta.json when adding pages.
content/docs/concepts/ HAND-WRITTEN ✅ Core concept explanations.
content/docs/getting-started/ HAND-WRITTEN ✅ Onboarding tutorials.
content/docs/protocol/ HAND-WRITTEN ✅ Protocol specification documents.

🤖 AI Skills Integration

The skills/ directory contains domain-specific AI skill definitions. When working on tasks in these areas, consult the corresponding SKILL.md:

Skill Path Use When
Quickstart skills/objectstack-quickstart/SKILL.md Project creation, defineStack(), drivers, adapters, bootstrap
Plugin skills/objectstack-plugin/SKILL.md Plugin lifecycle, DI, EventBus, Kernel config
Schema Design skills/objectstack-schema/SKILL.md Designing Objects, Fields, Relations, Validations
Query Design skills/objectstack-query/SKILL.md Filters, sorting, pagination, aggregation, joins
API Design skills/objectstack-api/SKILL.md Designing REST/GraphQL endpoints
UI Design skills/objectstack-ui/SKILL.md Designing Views, Dashboards, Apps
Automation Design skills/objectstack-automation/SKILL.md Designing Flows, Workflows, Triggers
AI Agent Design skills/objectstack-ai/SKILL.md Designing Agents, Tools, RAG pipelines
I18n Design skills/objectstack-i18n/SKILL.md Translation bundles, locale config, coverage detection

🔍 Context Routing Rules

When editing files matching these patterns, apply the corresponding architectural role:

File Pattern Role Key Constraints
**/objectstack.config.ts Project Architect defineStack(), driver/adapter selection, bootstrap
packages/spec/src/data/** Data Architect Zod-first, snake_case names, TSDoc on every property
packages/spec/src/ui/** UI Protocol Designer View types, SDUI patterns, navigation structures
packages/spec/src/automation/** Automation Architect Flow/Workflow state machines, trigger patterns
packages/spec/src/ai/** AI Protocol Designer Agent/Tool/Skill schemas, RAG pipeline structures
packages/spec/src/system/** System Architect Manifest, datasource, i18n schemas
packages/spec/src/kernel/** Kernel Engineer Plugin lifecycle, PluginContext interface
packages/spec/src/security/** Security Architect RBAC, permissions, policy schemas
packages/core/** Kernel Engineer ObjectKernel, DI, EventBus — runtime logic OK
packages/runtime/** Runtime Engineer Bootstrap, driver/app plugin registration
packages/rest/** API Engineer Route generation, middleware, response formats
packages/plugins/** Plugin Developer Implements spec contracts, lifecycle hooks
packages/services/** Service Engineer Kernel-managed services, DI integration
packages/adapters/** Integration Engineer Framework-specific bindings, zero business logic
packages/client*/** SDK Engineer Public API surface, type safety, DX
apps/studio/** UI Engineer React + Shadcn UI + Tailwind, dark mode default
apps/docs/** Documentation Engineer Fumadocs + Next.js, MDX content
examples/** Example Author Minimal, runnable, follows defineStack() pattern
content/docs/** Technical Writer Respect auto-gen vs hand-written boundaries

🤝 Interaction Shortcuts

Command Action
"Create a project" Use npx create-objectstack or write objectstack.config.ts from scratch
"Define a field" Create/modify packages/spec/src/data/field.zod.ts
"Define an object" Create/modify packages/spec/src/data/object.zod.ts
"Define a view" Create/modify packages/spec/src/ui/view.zod.ts
"Define an app" Create/modify packages/spec/src/ui/app.zod.ts
"Define a flow" Create/modify packages/spec/src/automation/flow.zod.ts
"Define an agent" Create/modify packages/spec/src/ai/agent.zod.ts
"Define a tool" Create/modify packages/spec/src/ai/tool.zod.ts
"Create a plugin" Scaffold under packages/plugins/plugin-{name}/
"Create a driver" Scaffold under packages/plugins/driver-{name}/
"Create a service" Scaffold under packages/services/service-{name}/
"Create an adapter" Scaffold under packages/adapters/{framework}/
"Create an example" Scaffold under examples/app-{name}/ or examples/plugin-{name}/

✅ Post-Task Checklist

After completing any task:

  1. Run tests: pnpm test — ensure nothing is broken.
  2. Update CHANGELOG.md / ROADMAP.md if the change is user-facing or architectural.