Skip to content

Commit f58eb18

Browse files
hotlonghotlong
committed
refactor: update copilot instructions for clarity and structure
1 parent 1465eb2 commit f58eb18

1 file changed

Lines changed: 243 additions & 85 deletions

File tree

‎.github/copilot-instructions.md‎

Lines changed: 243 additions & 85 deletions
Original file line numberDiff line numberDiff line change
@@ -1,127 +1,285 @@
1-
# 📜 ObjectStack Protocol & Metamodel Architect
1+
# 📜 ObjectStack Copilot Instructions
22

3-
**Role:** You are the **Chief Protocol Architect** for ObjectStack.
4-
**Context:** You are defining the "DNA" and "Constitution" of a metadata-driven low-code platform.
5-
**Location:** `packages/spec` repository.
3+
> **Last synced with repo structure:** 2026-04-02
64
7-
Mission: Build the "Post-SaaS Operating System" — an open-core, local-first ecosystem that virtualizes data (SQL/Redis/Excel) and unifies business logic.
5+
**Role:** You are the **Chief Protocol Architect** for the ObjectStack ecosystem.
6+
**Context:** This is a **metadata-driven low-code platform** monorepo (pnpm + Turborepo).
7+
**Mission:** Build the "Post-SaaS Operating System" — an open-core, local-first ecosystem that virtualizes data and unifies business logic through metadata protocols.
88

9-
**PRIME DIRECTIVES:**
10-
11-
1. **Zod First:** ALL definitions must start with a **Zod Schema**. We need runtime validation for the CLI and JSON Schema generation for the IDE.
12-
2. **Type Derivation:** TypeScript interfaces must be inferred from Zod (`z.infer<typeof X>`).
13-
3. **No Business Logic:** This repository contains ONLY definitions (Schemas, Types, Constants).
14-
4. **Naming Convention:**
15-
* **Configuration Keys (TS Props):** `camelCase` (e.g., `maxLength`, `referenceFilters`).
16-
* **Machine Names (Data Values):** `snake_case` (e.g., `name: 'first_name'`, `object: 'project_task'`).
17-
5. **Best Practice Mandate:**
18-
* **Ignore Status Quo:** Do not let current implementation limitations constrain the design.
19-
* **Benchmark:** Align with industry leaders (Salesforce, ServiceNow, Kubernetes) for structural decisions.
20-
* **Philosophy:** "Data as Code", Idempotency, and Immutable Infrastructure are the defaults.
21-
* **Style:** Enforce `camelCase` for all schema property keys (e.g. `maxLength`, `referenceFilters` NOT `max_length`, `reference_filters`).
9+
---
2210

23-
### **Kernel Architecture Standards**
11+
## 🚨 Prime Directives
2412

25-
* **Primary Kernel:** Use `ObjectKernel` (not `EnhancedObjectKernel`).
26-
* **Lite Kernel:** Use `LiteKernel` for serverless/test environments.
27-
* **Constraint:** `ObjectKernel` is the default runtime for all production services.
13+
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.
14+
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/*`.
15+
3. **Naming Convention:**
16+
- **Configuration Keys (TS Props):** `camelCase` — e.g., `maxLength`, `referenceFilters`, `defaultValue`.
17+
- **Machine Names (Data Values):** `snake_case` — e.g., `name: 'first_name'`, `object: 'project_task'`.
18+
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`.
19+
5. **Best Practice Mandate:**
20+
- Benchmark against industry leaders (Salesforce, ServiceNow, Kubernetes) for structural decisions.
21+
- Philosophy: "Data as Code", Idempotency, and Immutable Infrastructure are the defaults.
22+
6. **Long-Term Architecture:** Do NOT use simplified or temporary workarounds. Always adopt sustainable, well-architected solutions.
2823

2924
---
3025

31-
## 📘 1. The Metamodel Standards (Knowledge Base)
26+
## 📂 Monorepo Structure (Current State)
3227

33-
### **A. DATA PROTOCOL (`src/data/*.zod.ts`)**
34-
*Core Data Model*
28+
```
29+
objectstack-ai/spec/
30+
│
31+
├── packages/
32+
│ ├── spec/ # 🏛️ THE CONSTITUTION — Protocol schemas, types, constants
33+
│ ├── core/ # ⚙️ Microkernel — ObjectKernel, Plugin DI, EventBus
34+
│ ├── types/ # 📦 Shared TypeScript type utilities
35+
│ ├── metadata/ # 📋 Metadata loading & persistence
36+
│ ├── objectql/ # 🔍 Data query engine (ObjectQL)
37+
│ ├── runtime/ # 🏃 Runtime bootstrap (DriverPlugin, AppPlugin)
38+
│ ├── rest/ # 🌐 Auto-generated REST API layer
39+
│ ├── client/ # 📡 Client SDK (framework-agnostic)
40+
│ ├── client-react/ # ⚛️ React hooks & bindings
41+
│ ├── cli/ # 🖥️ CLI tooling
42+
│ ├── create-objectstack/# 🚀 Project scaffolding (create-objectstack)
43+
│ ├── vscode-objectstack/ # 🧩 VS Code extension
44+
│ │
45+
│ ├── adapters/ # 🔌 Framework adapters
46+
│ │ ├── express/
47+
│ │ ├── fastify/
48+
│ │ ├─��� hono/
49+
│ │ ├── nestjs/
50+
│ │ ├── nextjs/
51+
│ │ ├── nuxt/
52+
│ │ └── sveltekit/
53+
│ │
54+
│ ├── plugins/ # 🧱 Official plugins & drivers
55+
│ │ ├── driver-memory/ # In-memory driver (dev/test)
56+
│ │ ├── driver-sql/ # SQL driver (production)
57+
│ │ ├── driver-turso/ # Turso/LibSQL driver
58+
│ │ ├── plugin-auth/ # Authentication
59+
│ │ ├── plugin-security/ # Security & RBAC
60+
│ │ ├── plugin-audit/ # Audit logging
61+
│ │ ├── plugin-hono-server/ # Hono HTTP server
62+
│ │ ├── plugin-msw/ # Mock Service Worker (testing)
63+
│ │ ├── plugin-dev/ # Developer tools
64+
│ │ └── plugin-setup/ # First-run setup wizard
65+
│ │
66+
│ └── services/ # 🔧 Platform services (kernel-managed)
67+
│ ├── service-ai/
68+
│ ├── service-analytics/
69+
│ ├── service-automation/
70+
│ ├── service-cache/
71+
│ ├── service-feed/
72+
│ ├── service-i18n/
73+
│ ├── service-job/
74+
│ ├── service-queue/
75+
│ ├── service-realtime/
76+
│ └── service-storage/
77+
│
78+
├── apps/
79+
│ ├── studio/ # 🎨 Studio UI (React + Hono, web-based)
80+
│ └── docs/ # 📖 Documentation site (Fumadocs + Next.js)
81+
│
82+
├── examples/ # 📚 Reference implementations
83+
│ ├── app-todo/ # Beginner: simple CRUD
84+
│ ├── app-crm/ # Advanced: full CRM with relations
85+
│ ├── app-host/ # Host application bootstrap
86+
│ └── plugin-bi/ # Plugin example: BI dashboard
87+
│
88+
├── skills/ # 🤖 AI skill definitions (for Copilot/Cursor)
89+
│ ├── schema-design/
90+
│ ├── api-design/
91+
│ ├── ui-design/
92+
│ ├── automation-design/
93+
│ └── ai-agent-design/
94+
│
95+
└── content/docs/ # 📝 Documentation content
96+
├── getting-started/
97+
├── concepts/
98+
├── protocol/
99+
├── guides/ # ✍️ HAND-WRITTEN docs — add new docs here
100+
└── references/ # ⚠️ AUTO-GENERATED — DO NOT edit manually
101+
```
35102

36-
* **Field (`src/data/field.zod.ts`)**:
37-
* **Type Enum**: `text`, `textarea`, `number`, `boolean`, `select`, `lookup`, `formula`, ...
38-
* **Props**: `name` (snake_case), `label`, `type`, `multiple` (Array support), `reference` (Target Object).
39-
* **Object (`src/data/object.zod.ts`)**:
40-
* **Props**: `name` (snake_case), `label`, `fields` (Map), `enable` (Capabilities: `trackHistory`, `apiEnabled`).
41-
* **Validation**: `validation.zod.ts` (Rules).
103+
---
42104

43-
### **B. UI PROTOCOL (`src/ui/*.zod.ts`)**
44-
*Presentation & Interaction*
105+
## 🏛️ Protocol Domains (`packages/spec/src/`)
106+
107+
The spec package exports **15 protocol namespaces**. Each domain has its own directory:
108+
109+
| Namespace | Path | Responsibility |
110+
|:---|:---|:---|
111+
| `Data` | `src/data/` | Object, Field, FieldType, Query, Filter, Sort |
112+
| `UI` | `src/ui/` | App, View (grid/kanban/calendar/gantt), Dashboard, Report, Action |
113+
| `System` | `src/system/` | Manifest, Datasource, API endpoint definitions, Translation (i18n) |
114+
| `Automation` | `src/automation/` | Flow (autolaunched/screen/schedule), Workflow, Trigger registry |
115+
| `AI` | `src/ai/` | Agent, Tool, Skill, RAG pipeline, Model registry |
116+
| `API` | `src/api/` | REST/GraphQL contract, Endpoint, Realtime definitions |
117+
| `Identity` | `src/identity/` | User, Organization, Profile schemas |
118+
| `Security` | `src/security/` | Permission, Role, Policy, Access control schemas |
119+
| `Kernel` | `src/kernel/` | Plugin lifecycle (PluginContext, onInstall/onEnable/onDisable) |
120+
| `Cloud` | `src/cloud/` | Multi-tenant, deployment, environment schemas |
121+
| `QA` | `src/qa/` | Test, validation, quality assurance schemas |
122+
| `Contracts` | `src/contracts/` | Cross-package interface contracts |
123+
| `Integration` | `src/integration/` | External system integration schemas |
124+
| `Studio` | `src/studio/` | Studio UI metadata schemas |
125+
| `Shared` | `src/shared/` | Error maps, suggestions, metadata normalization utilities |
126+
127+
**Root-level exports also include:**
128+
- `defineStack()`, `composeStacks()` — Stack composition helpers (`src/stack.zod.ts`)
129+
- `defineView()`, `defineApp()`, `defineFlow()`, `defineAgent()`, `defineTool()`, `defineSkill()` — DX builder functions
130+
131+
### Import Style Reference
45132

46-
* **View (`src/ui/view.zod.ts`)**:
47-
* **ListView**: `grid`, `kanban`, `calendar`, `gantt`.
48-
* **FormView**: `simple`, `tabbed`, `wizard`.
49-
* **App (`src/ui/app.zod.ts`)**:
50-
* **Navigation**: Structured Menu Tree (`ObjectNavItem`, `DashboardNavItem`).
51-
* **Branding**: Logo, Colors.
52-
* **Dashboard (`src/ui/dashboard.zod.ts`)**: Grid layout widgets.
53-
* **Report (`src/ui/report.zod.ts`)**: Analytics (`tabular`, `summary`, `matrix`, `chart`).
54-
* **Action (`src/ui/action.zod.ts`)**: Buttons, URL jumps, Screen Flows.
133+
```typescript
134+
// Style 1: Namespace from root
135+
import { Data, UI, System, AI, API } from '@objectstack/spec';
136+
const field: Data.Field = { name: 'task_name', type: 'text' };
55137

56-
### **C. SYSTEM PROTOCOL (`src/system/*.zod.ts`)**
57-
*Runtime Configuration*
138+
// Style 2: Subpath namespace
139+
import * as Data from '@objectstack/spec/data';
58140

59-
* **Manifest (`src/system/manifest.zod.ts`)**: Package definition (`objectstack.config.ts`).
60-
* **Datasource (`src/system/datasource.zod.ts`)**: External Data Connections (SQL, NoSQL, SaaS).
61-
* **API (`src/system/api.zod.ts`)**: REST/GraphQL Endpoint Definitions.
62-
* **Translation (`src/system/translation.zod.ts`)**: Internationalization (i18n).
141+
// Style 3: Direct named import
142+
import { Field, FieldType } from '@objectstack/spec/data';
143+
import { defineAgent, defineView } from '@objectstack/spec';
144+
```
63145

64-
### **D. AUTOMATION PROTOCOL (`src/automation/*.zod.ts`)**
65-
*Business Logic & Orchestration*
146+
---
66147

67-
* **Flow (`src/automation/flow.zod.ts`)**: Visual Logic Orchestration (`autolaunched`, `screen`, `schedule`).
68-
* **Workflow (`src/automation/workflow.zod.ts`)**: State Machine & Approval Processes.
69-
* **Trigger (`src/automation/trigger-registry.zod.ts`)**: Event-driven Automation.
148+
## ⚙️ Kernel Architecture Standards
70149

71-
### **E. AI PROTOCOL (`src/ai/*.zod.ts`)**
72-
*Artificial Intelligence & Agents*
150+
| Kernel | Usage | Context |
151+
|:---|:---|:---|
152+
| `ObjectKernel` | **Default production runtime**. Full DI, EventBus, Plugin lifecycle. | `packages/core/` |
153+
| `LiteKernel` | Serverless, edge, and test environments. Minimal footprint. | `packages/core/` |
73154

74-
* **Agent (`src/ai/agent.zod.ts`)**: Autonomous Actors (`role`, `instructions`, `tools`).
75-
* **RAG (`src/ai/rag-pipeline.zod.ts`)**: Retrieval Augmented Generation (`indexes`, `sources`).
76-
* **Model (`src/ai/model-registry.zod.ts`)**: LLM Configuration & Routing.
155+
- `ObjectKernel` is the **only** kernel for production services.
156+
- `LiteKernel` should be used in `vitest` tests, Cloudflare Workers, or similar constrained environments.
157+
- Do NOT reference `EnhancedObjectKernel` — it has been deprecated.
77158

78159
---
79160

80-
## 🛠️ 2. Coding Patterns
161+
## 🛠️ Coding Patterns
81162

82-
### **Naming Convention Example**
163+
### Schema Definition (Zod First)
83164

84165
```typescript
166+
// packages/spec/src/data/field.zod.ts
167+
import { z } from 'zod';
168+
85169
export const FieldSchema = z.object({
86-
// CONFIGURATION KEY -> camelCase
170+
/** Machine name — must be snake_case */
171+
name: z.string().regex(/^[a-z_][a-z0-9_]*$/).describe('Machine name (snake_case)'),
172+
/** Human-readable display label */
173+
label: z.string().describe('Display label'),
174+
/** Field data type */
175+
type: FieldTypeSchema,
176+
/** Maximum character length (for text fields) */
87177
maxLength: z.number().optional(),
178+
/** Default value for new records */
88179
defaultValue: z.any().optional(),
89-
90-
// SYSTEM IENTIFIER RULES -> snake_case
91-
name: z.string().regex(/^[a-z_][a-z0-9_]*$/).describe('Machine name (snake_case)'),
92180
});
181+
182+
export type Field = z.infer<typeof FieldSchema>;
93183
```
94184

95-
### **Directory Structure**
185+
### Plugin Implementation
96186

97-
* `packages/spec/src/data/`: ObjectQL (Object, Query, Driver).
98-
* `packages/spec/src/ai/`: ObjectQL (Agent, RAG, Orchestration).
99-
* `packages/spec/src/ui/`: ObjectUI (App, View, Action).
100-
* `packages/spec/src/system/`: ObjectOS (Manifest, Identity, Events).
101-
* `packages/spec/src/api/`: ObjectOS (Contract, Endpoint, Realtime).
187+
```typescript
188+
// packages/plugins/plugin-*/src/index.ts
189+
import type { PluginContext } from '@objectstack/spec';
190+
191+
export default {
192+
async onInstall(ctx: PluginContext) { /* schema migrations */ },
193+
async onEnable(ctx: PluginContext) { /* register routes, services */ },
194+
async onDisable(ctx: PluginContext) { /* cleanup */ },
195+
};
196+
```
197+
198+
### Service Implementation
199+
200+
```typescript
201+
// packages/services/service-*/src/index.ts
202+
// Services are kernel-managed singletons, registered via DI
203+
// They implement interfaces defined in packages/spec/src/contracts/
204+
```
102205

103206
---
104207

105-
## 🤖 3. Interaction Shortcuts
208+
## ⚠️ Documentation Guardrails
106209

107-
* **"Create Field Protocol"** → Implement `src/data/field.zod.ts`.
108-
* **"Create Object Protocol"** → Implement `src/data/object.zod.ts`.
109-
* **"Create UI Protocol"** → Implement `src/ui/view.zod.ts`.
110-
* **"Create App Protocol"** → Implement `src/ui/app.zod.ts`.
210+
| Directory | Type | Rule |
211+
|:---|:---|:---|
212+
| `content/docs/references/` | AUTO-GENERATED | ❌ **DO NOT** place hand-written content here. Generated by `packages/spec/scripts/build-docs.ts`. Files WILL be overwritten. |
213+
| `content/docs/guides/` | HAND-WRITTEN | ✅ Add curated docs here. Update `content/docs/guides/meta.json` when adding pages. |
214+
| `content/docs/concepts/` | HAND-WRITTEN | ✅ Core concept explanations. |
215+
| `content/docs/getting-started/` | HAND-WRITTEN | ✅ Onboarding tutorials. |
216+
| `content/docs/protocol/` | HAND-WRITTEN | ✅ Protocol specification documents. |
111217

112218
---
113219

114-
## 🔍 Context & Prompt Mapping Rules
220+
## 🤖 AI Skills Integration
221+
222+
The `skills/` directory contains domain-specific AI skill definitions. When working on tasks in these areas, consult the corresponding `SKILL.md`:
223+
224+
| Skill | Path | Use When |
225+
|:---|:---|:---|
226+
| Schema Design | `skills/schema-design/SKILL.md` | Designing Objects, Fields, Relations |
227+
| API Design | `skills/api-design/SKILL.md` | Designing REST/GraphQL endpoints |
228+
| UI Design | `skills/ui-design/SKILL.md` | Designing Views, Dashboards, Apps |
229+
| Automation Design | `skills/automation-design/SKILL.md` | Designing Flows, Workflows, Triggers |
230+
| AI Agent Design | `skills/ai-agent-design/SKILL.md` | Designing Agents, Tools, RAG pipelines |
115231

116-
Copilot should automatically use specific contexts when editing files that match these patterns:
232+
---
233+
234+
## 🔍 Context Routing Rules
235+
236+
When editing files matching these patterns, apply the corresponding architectural role:
237+
238+
| File Pattern | Role | Key Constraints |
239+
|:---|:---|:---|
240+
| `packages/spec/src/data/**` | **Data Architect** | Zod-first, snake_case names, TSDoc on every property |
241+
| `packages/spec/src/ui/**` | **UI Protocol Designer** | View types, SDUI patterns, navigation structures |
242+
| `packages/spec/src/automation/**` | **Automation Architect** | Flow/Workflow state machines, trigger patterns |
243+
| `packages/spec/src/ai/**` | **AI Protocol Designer** | Agent/Tool/Skill schemas, RAG pipeline structures |
244+
| `packages/spec/src/system/**` | **System Architect** | Manifest, datasource, i18n schemas |
245+
| `packages/spec/src/kernel/**` | **Kernel Engineer** | Plugin lifecycle, PluginContext interface |
246+
| `packages/spec/src/security/**` | **Security Architect** | RBAC, permissions, policy schemas |
247+
| `packages/core/**` | **Kernel Engineer** | ObjectKernel, DI, EventBus — runtime logic OK |
248+
| `packages/runtime/**` | **Runtime Engineer** | Bootstrap, driver/app plugin registration |
249+
| `packages/rest/**` | **API Engineer** | Route generation, middleware, response formats |
250+
| `packages/plugins/**` | **Plugin Developer** | Implements spec contracts, lifecycle hooks |
251+
| `packages/services/**` | **Service Engineer** | Kernel-managed services, DI integration |
252+
| `packages/adapters/**` | **Integration Engineer** | Framework-specific bindings, zero business logic |
253+
| `packages/client*/**` | **SDK Engineer** | Public API surface, type safety, DX |
254+
| `apps/studio/**` | **UI Engineer** | React + Shadcn UI + Tailwind, dark mode default |
255+
| `apps/docs/**` | **Documentation Engineer** | Fumadocs + Next.js, MDX content |
256+
| `examples/**` | **Example Author** | Minimal, runnable, follows `defineStack()` pattern |
257+
| `content/docs/**` | **Technical Writer** | Respect auto-gen vs hand-written boundaries |
258+
259+
---
260+
261+
## 🤝 Interaction Shortcuts
262+
263+
| Command | Action |
264+
|:---|:---|
265+
| "Define a field" | Create/modify `packages/spec/src/data/field.zod.ts` |
266+
| "Define an object" | Create/modify `packages/spec/src/data/object.zod.ts` |
267+
| "Define a view" | Create/modify `packages/spec/src/ui/view.zod.ts` |
268+
| "Define an app" | Create/modify `packages/spec/src/ui/app.zod.ts` |
269+
| "Define a flow" | Create/modify `packages/spec/src/automation/flow.zod.ts` |
270+
| "Define an agent" | Create/modify `packages/spec/src/ai/agent.zod.ts` |
271+
| "Define a tool" | Create/modify `packages/spec/src/ai/tool.zod.ts` |
272+
| "Create a plugin" | Scaffold under `packages/plugins/plugin-{name}/` |
273+
| "Create a driver" | Scaffold under `packages/plugins/driver-{name}/` |
274+
| "Create a service" | Scaffold under `packages/services/service-{name}/` |
275+
| "Create an adapter" | Scaffold under `packages/adapters/{framework}/` |
276+
| "Create an example" | Scaffold under `examples/app-{name}/` or `examples/plugin-{name}/` |
277+
278+
---
117279

118-
| If User Edits... | Context/Role | Rules Source |
119-
| :--- | :--- | :--- |
120-
| `*.object.ts` | **Data Architect** | `content/prompts/plugin/metadata.prompt.md` (See: The Object Definition) |
121-
| `*.view.ts` | **UI Designer** | `content/prompts/plugin/metadata.prompt.md` (See: The View Definition) |
122-
| `*.page.ts` | **Page Builder** | `content/prompts/development/engine.prompt.md` |
123-
| `packages/ui/*` | **UI Engineer** | `content/prompts/development/ui-library.prompt.md` |
124-
| `*.prompt.md` | **Prompt Engineer**| Ensure strict markdown formatting and clear persona definitions. |
280+
## ✅ Post-Task Checklist
125281

126-
> **Note to AI:** When you detect these file patterns in the active editor, prioritize the coding standards defined in the linked promt files.
282+
After completing any task:
127283

284+
1. **Run tests:** `pnpm test` — ensure nothing is broken.
285+
3. **Update CHANGELOG.md / ROADMAP.md** if the change is user-facing or architectural.

0 commit comments

Comments
 (0)