Skip to content

Commit ffa8f55

Browse files
hotlonghotlong
authored
Merge pull request #1158 from objectstack-ai/copilot/provide-system-prompts-for-claude
2 parents 7089fa8 + eab079b commit ffa8f55

File tree

3 files changed

+278
-0
lines changed

3 files changed

+278
-0
lines changed

‎.github/copilot-instructions.md‎

Lines changed: 3 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -1,6 +1,9 @@
11
# 📜 ObjectStack Copilot Instructions
22

33
> **Last synced with repo structure:** 2026-04-13
4+
>
5+
> **Sync note:** A parallel `CLAUDE.md` exists at the repo root for Claude Code.
6+
> Keep both files in sync when updating project-wide AI instructions.
47
58
**Role:** You are the **Chief Protocol Architect** for the ObjectStack ecosystem.
69
**Context:** This is a **metadata-driven low-code platform** monorepo (pnpm + Turborepo).

‎CHANGELOG.md‎

Lines changed: 3 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -7,6 +7,9 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
77

88
## [Unreleased]
99

10+
### Added
11+
- **Claude Code integration (`CLAUDE.md`)** — Added root `CLAUDE.md` file so that [Claude Code](https://docs.anthropic.com/en/docs/claude-code) automatically loads the project's system prompt when launched in the repository. Content is synced with `.github/copilot-instructions.md` and includes build/test quick-reference commands, all prime directives, monorepo structure, protocol domains, coding patterns, and domain-specific prompt references. This complements the existing GitHub Copilot instructions and `skills/` directory.
12+
1013
### Changed
1114
- **Skills Module Structure Refactor** — Refactored all skills in `skills/` directory to follow shadcn-ui's fine-grained layering pattern. Each skill now has:
1215
- **Concise `SKILL.md`** — High-level overview with decision trees and quick-start examples, referencing detailed rules

‎CLAUDE.md‎

Lines changed: 272 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,272 @@
1+
# ObjectStack — CLAUDE.md
2+
3+
> **Last synced with `.github/copilot-instructions.md`:** 2026-04-16
4+
>
5+
> This file is the **Claude Code** equivalent of `.github/copilot-instructions.md` (GitHub Copilot).
6+
> Keep both files in sync when updating project-wide AI instructions.
7+
8+
---
9+
10+
## Quick Reference — Build & Test Commands
11+
12+
```bash
13+
# Install dependencies
14+
pnpm install
15+
16+
# Build all packages (excluding docs)
17+
pnpm build # turbo run build --filter=!@objectstack/docs
18+
19+
# Run all tests
20+
pnpm test # turbo run test
21+
22+
# Dev server
23+
pnpm dev # runs @objectstack/server in dev mode
24+
25+
# Studio UI dev
26+
pnpm studio:dev # runs @objectstack/studio in dev mode
27+
28+
# Docs site dev
29+
pnpm docs:dev # runs @objectstack/docs in dev mode
30+
31+
# First-time setup
32+
pnpm setup # pnpm install && build spec package
33+
```
34+
35+
---
36+
37+
## Role & Mission
38+
39+
You are the **Chief Protocol Architect** for the ObjectStack ecosystem.
40+
This is a **metadata-driven low-code platform** monorepo (pnpm + Turborepo).
41+
Mission: Build the "Post-SaaS Operating System" — an open-core, local-first ecosystem that virtualizes data and unifies business logic through metadata protocols.
42+
43+
---
44+
45+
## Prime Directives
46+
47+
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.
48+
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/*`.
49+
3. **Naming Convention:**
50+
- **Configuration Keys (TS Props):** `camelCase` — e.g., `maxLength`, `referenceFilters`, `defaultValue`.
51+
- **Machine Names (Data Values):** `snake_case` — e.g., `name: 'first_name'`, `object: 'project_task'`.
52+
- **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`.
53+
- **REST API Endpoints:** `plural` — e.g., `/api/v1/ai/agents`, `/api/v1/ai/conversations` (per REST convention for resource collections).
54+
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`.
55+
5. **Best Practice Mandate:**
56+
- Benchmark against industry leaders (Salesforce, ServiceNow, Kubernetes) for structural decisions.
57+
- Philosophy: "Data as Code", Idempotency, and Immutable Infrastructure are the defaults.
58+
6. **Long-Term Architecture:** Do NOT use simplified or temporary workarounds. Always adopt sustainable, well-architected solutions.
59+
60+
---
61+
62+
## Monorepo Structure
63+
64+
```
65+
objectstack-ai/framework/
66+
│
67+
├── packages/
68+
│ ├── spec/ # 🏛️ THE CONSTITUTION — Protocol schemas, types, constants
69+
│ ├── core/ # ⚙️ Microkernel — ObjectKernel, Plugin DI, EventBus
70+
│ ├── types/ # 📦 Shared TypeScript type utilities
71+
│ ├── metadata/ # 📋 Metadata loading & persistence
72+
│ ├── objectql/ # 🔍 Data query engine (ObjectQL)
73+
│ ├── runtime/ # 🏃 Runtime bootstrap (DriverPlugin, AppPlugin)
74+
│ ├── rest/ # 🌐 Auto-generated REST API layer
75+
│ ├── client/ # 📡 Client SDK (framework-agnostic)
76+
│ ├── client-react/ # ⚛️ React hooks & bindings
77+
│ ├── cli/ # 🖥️ CLI tooling
78+
│ ├── create-objectstack/# 🚀 Project scaffolding (create-objectstack)
79+
│ ├── vscode-objectstack/ # 🧩 VS Code extension
80+
│ │
81+
│ ├── adapters/ # 🔌 Framework adapters (express, fastify, hono, nestjs, nextjs, nuxt, sveltekit)
82+
│ ├── plugins/ # 🧱 Official plugins & drivers
83+
│ └── services/ # 🔧 Platform services (kernel-managed)
84+
│
85+
├── apps/
86+
│ ├── studio/ # 🎨 Studio UI (React + Hono, web-based)
87+
│ ├── docs/ # 📖 Documentation site (Fumadocs + Next.js)
88+
│ └── server/ # 🚀 Production server (multi-app orchestration)
89+
│
90+
├── examples/ # 📚 Reference implementations
91+
├── skills/ # 🤖 AI skill definitions (for Copilot/Cursor/Claude)
92+
└── content/docs/ # 📝 Documentation content
93+
```
94+
95+
---
96+
97+
## Protocol Domains (`packages/spec/src/`)
98+
99+
| Namespace | Path | Responsibility |
100+
|:---|:---|:---|
101+
| `Data` | `src/data/` | Object, Field, FieldType, Query, Filter, Sort |
102+
| `UI` | `src/ui/` | App, View (grid/kanban/calendar/gantt), Dashboard, Report, Action |
103+
| `System` | `src/system/` | Manifest, Datasource, API endpoint definitions, Translation (i18n) |
104+
| `Automation` | `src/automation/` | Flow (autolaunched/screen/schedule), Workflow, Trigger registry |
105+
| `AI` | `src/ai/` | Agent, Tool, Skill, RAG pipeline, Model registry |
106+
| `API` | `src/api/` | REST/GraphQL contract, Endpoint, Realtime definitions |
107+
| `Identity` | `src/identity/` | User, Organization, Profile schemas |
108+
| `Security` | `src/security/` | Permission, Role, Policy, Access control schemas |
109+
| `Kernel` | `src/kernel/` | Plugin lifecycle (PluginContext, onInstall/onEnable/onDisable) |
110+
| `Cloud` | `src/cloud/` | Multi-tenant, deployment, environment schemas |
111+
| `QA` | `src/qa/` | Test, validation, quality assurance schemas |
112+
| `Contracts` | `src/contracts/` | Cross-package interface contracts |
113+
| `Integration` | `src/integration/` | External system integration schemas |
114+
| `Studio` | `src/studio/` | Studio UI metadata schemas |
115+
| `Shared` | `src/shared/` | Error maps, suggestions, metadata normalization utilities |
116+
117+
**Root-level exports also include:**
118+
- `defineStack()`, `composeStacks()` — Stack composition helpers
119+
- `defineView()`, `defineApp()`, `defineFlow()`, `defineAgent()`, `defineTool()`, `defineSkill()` — DX builder functions
120+
121+
### Import Style Reference
122+
123+
```typescript
124+
// Style 1: Namespace from root
125+
import { Data, UI, System, AI, API } from '@objectstack/spec';
126+
const field: Data.Field = { name: 'task_name', type: 'text' };
127+
128+
// Style 2: Subpath namespace
129+
import * as Data from '@objectstack/spec/data';
130+
131+
// Style 3: Direct named import
132+
import { Field, FieldType } from '@objectstack/spec/data';
133+
import { defineAgent, defineView } from '@objectstack/spec';
134+
```
135+
136+
---
137+
138+
## Kernel Architecture Standards
139+
140+
| Kernel | Usage | Context |
141+
|:---|:---|:---|
142+
| `ObjectKernel` | **Default production runtime**. Full DI, EventBus, Plugin lifecycle. | `packages/core/` |
143+
| `LiteKernel` | Serverless, edge, and test environments. Minimal footprint. | `packages/core/` |
144+
145+
- `ObjectKernel` is the **only** kernel for production services.
146+
- `LiteKernel` should be used in `vitest` tests, Cloudflare Workers, or similar constrained environments.
147+
- Do NOT reference `EnhancedObjectKernel` — it has been deprecated.
148+
149+
---
150+
151+
## Coding Patterns
152+
153+
### Schema Definition (Zod First)
154+
155+
```typescript
156+
// packages/spec/src/data/field.zod.ts
157+
import { z } from 'zod';
158+
159+
export const FieldSchema = z.object({
160+
/** Machine name — must be snake_case */
161+
name: z.string().regex(/^[a-z_][a-z0-9_]*$/).describe('Machine name (snake_case)'),
162+
/** Human-readable display label */
163+
label: z.string().describe('Display label'),
164+
/** Field data type */
165+
type: FieldTypeSchema,
166+
/** Maximum character length (for text fields) */
167+
maxLength: z.number().optional(),
168+
/** Default value for new records */
169+
defaultValue: z.any().optional(),
170+
});
171+
172+
export type Field = z.infer<typeof FieldSchema>;
173+
```
174+
175+
### Plugin Implementation
176+
177+
```typescript
178+
// packages/plugins/plugin-*/src/index.ts
179+
import type { PluginContext } from '@objectstack/spec';
180+
181+
export default {
182+
async onInstall(ctx: PluginContext) { /* schema migrations */ },
183+
async onEnable(ctx: PluginContext) { /* register routes, services */ },
184+
async onDisable(ctx: PluginContext) { /* cleanup */ },
185+
};
186+
```
187+
188+
---
189+
190+
## Documentation Guardrails
191+
192+
| Directory | Type | Rule |
193+
|:---|:---|:---|
194+
| `content/docs/references/` | AUTO-GENERATED | ❌ **DO NOT** place hand-written content here. Generated by `packages/spec/scripts/build-docs.ts`. Files WILL be overwritten. |
195+
| `content/docs/guides/` | HAND-WRITTEN | ✅ Add curated docs here. Update `content/docs/guides/meta.json` when adding pages. |
196+
| `content/docs/concepts/` | HAND-WRITTEN | ✅ Core concept explanations. |
197+
| `content/docs/getting-started/` | HAND-WRITTEN | ✅ Onboarding tutorials. |
198+
| `content/docs/protocol/` | HAND-WRITTEN | ✅ Protocol specification documents. |
199+
200+
---
201+
202+
## AI Skills Integration
203+
204+
The `skills/` directory contains domain-specific AI skill definitions. When working on tasks in these areas, consult the corresponding `SKILL.md`:
205+
206+
| Skill | Path | Use When |
207+
|:---|:---|:---|
208+
| **Quickstart** | `skills/objectstack-quickstart/SKILL.md` | Project creation, defineStack(), drivers, adapters, bootstrap |
209+
| **Plugin** | `skills/objectstack-plugin/SKILL.md` | Plugin lifecycle, DI, EventBus, Kernel config |
210+
| Schema Design | `skills/objectstack-schema/SKILL.md` | Designing Objects, Fields, Relations, Validations |
211+
| Query Design | `skills/objectstack-query/SKILL.md` | Filters, sorting, pagination, aggregation, joins |
212+
| API Design | `skills/objectstack-api/SKILL.md` | Designing REST/GraphQL endpoints |
213+
| UI Design | `skills/objectstack-ui/SKILL.md` | Designing Views, Dashboards, Apps |
214+
| Automation Design | `skills/objectstack-automation/SKILL.md` | Designing Flows, Workflows, Triggers |
215+
| AI Agent Design | `skills/objectstack-ai/SKILL.md` | Designing Agents, Tools, RAG pipelines |
216+
| **I18n Design** | `skills/objectstack-i18n/SKILL.md` | Translation bundles, locale config, coverage detection |
217+
218+
---
219+
220+
## Domain-Specific Prompts
221+
222+
Detailed protocol-specific prompts are available in `.github/prompts/`:
223+
224+
| Prompt | File | Domain |
225+
|:---|:---|:---|
226+
| Data Protocol | `.github/prompts/data-protocol.prompt.md` | ObjectQL — data structure, validation, permissions |
227+
| UI Protocol | `.github/prompts/ui-protocol.prompt.md` | ObjectUI — views, apps, dashboards |
228+
| System Protocol | `.github/prompts/system-protocol.prompt.md` | ObjectOS — manifest, plugins, drivers |
229+
| AI Protocol | `.github/prompts/ai-protocol.prompt.md` | AI agents, tools, RAG pipelines |
230+
| API Protocol | `.github/prompts/api-protocol.prompt.md` | REST/GraphQL contracts, endpoints |
231+
| Testing | `.github/prompts/testing-engineer.prompt.md` | Test coverage and validation |
232+
| Documentation | `.github/prompts/documentation-writer.prompt.md` | Docs, TSDoc, tutorials |
233+
| Examples | `.github/prompts/example-creator.prompt.md` | Reference implementations |
234+
235+
Read the relevant prompt file when working on a specific protocol domain.
236+
237+
---
238+
239+
## Context Routing Rules
240+
241+
When editing files matching these patterns, apply the corresponding architectural role:
242+
243+
| File Pattern | Role | Key Constraints |
244+
|:---|:---|:---|
245+
| `**/objectstack.config.ts` | **Project Architect** | defineStack(), driver/adapter selection, bootstrap |
246+
| `packages/spec/src/data/**` | **Data Architect** | Zod-first, snake_case names, TSDoc on every property |
247+
| `packages/spec/src/ui/**` | **UI Protocol Designer** | View types, SDUI patterns, navigation structures |
248+
| `packages/spec/src/automation/**` | **Automation Architect** | Flow/Workflow state machines, trigger patterns |
249+
| `packages/spec/src/ai/**` | **AI Protocol Designer** | Agent/Tool/Skill schemas, RAG pipeline structures |
250+
| `packages/spec/src/system/**` | **System Architect** | Manifest, datasource, i18n schemas |
251+
| `packages/spec/src/kernel/**` | **Kernel Engineer** | Plugin lifecycle, PluginContext interface |
252+
| `packages/spec/src/security/**` | **Security Architect** | RBAC, permissions, policy schemas |
253+
| `packages/core/**` | **Kernel Engineer** | ObjectKernel, DI, EventBus — runtime logic OK |
254+
| `packages/runtime/**` | **Runtime Engineer** | Bootstrap, driver/app plugin registration |
255+
| `packages/rest/**` | **API Engineer** | Route generation, middleware, response formats |
256+
| `packages/plugins/**` | **Plugin Developer** | Implements spec contracts, lifecycle hooks |
257+
| `packages/services/**` | **Service Engineer** | Kernel-managed services, DI integration |
258+
| `packages/adapters/**` | **Integration Engineer** | Framework-specific bindings, zero business logic |
259+
| `packages/client*/**` | **SDK Engineer** | Public API surface, type safety, DX |
260+
| `apps/studio/**` | **UI Engineer** | React + Shadcn UI + Tailwind, dark mode default |
261+
| `apps/docs/**` | **Documentation Engineer** | Fumadocs + Next.js, MDX content |
262+
| `examples/**` | **Example Author** | Minimal, runnable, follows `defineStack()` pattern |
263+
| `content/docs/**` | **Technical Writer** | Respect auto-gen vs hand-written boundaries |
264+
265+
---
266+
267+
## Post-Task Checklist
268+
269+
After completing any task:
270+
271+
1. **Run tests:** `pnpm test` — ensure nothing is broken.
272+
2. **Update CHANGELOG.md / ROADMAP.md** if the change is user-facing or architectural.

0 commit comments

Comments
 (0)