Skip to content

AGENTS.md

Latest commit

 

History

History
101 lines (79 loc) · 4.73 KB

AGENTS.md

File metadata and controls

101 lines (79 loc) · 4.73 KB
Raw

{{PROJECT_TITLE}} — Agent Instructions

Auto-generated by create-objectstack. Read by Claude Code, Cursor, Codex (AGENTS.md) and GitHub Copilot (.github/copilot-instructions.md). Customise freely.

Project Context

This is an ObjectStack application — a metadata-driven low-code project that defines business objects, views, automations, and AI agents in TypeScript.

  • Entry point: objectstack.config.ts (uses defineStack())
  • Spec package: @objectstack/spec (Zod-first schemas and types)

Verify your work (do this after every metadata change)

Metadata mistakes fail silently at runtime, not at edit time — a bare field reference in a predicate (done instead of record.done) evaluates to null and silently hides an action on every record; a dangling widget binding renders an empty chart. Catch them before you ship:

npm run validate      # schema + CEL predicates + widget bindings (no artifact)
npm run typecheck     # TypeScript types against @objectstack/spec

npm run validate runs the same gates as npm run build (Zod protocol schema, CEL/predicate validation with record.<field> existence checks, and dashboard widget-binding integrity) but emits no dist/ — so it is the fast inner-loop check after editing an *.object.ts / *.view.ts / *.action.ts / *.flow.ts. Both exit non-zero with a located, corrective message on failure. Run npm run build when you need the compiled dist/objectstack.json artifact.

Never report a metadata change as done until npm run validate passes.

Naming Conventions

Context Convention Example
Config keys (TS props) camelCase maxLength, defaultValue
Machine names (data values) snake_case project_task, first_name
Metadata type names singular 'agent', 'view', 'flow'
File names {name}.{type}.ts task.object.ts, main.app.ts

Key Rules

  1. Zod First — All schema definitions start with Zod. Types are derived via z.infer<>.
  2. defineStack() is the single configuration entry point in objectstack.config.ts.
  3. Use Object.values() barrel pattern for metadata arrays.
  4. Import from @objectstack/spec — never use relative paths into the spec package.
  5. Predicates are CEL — visible, disabled, requiredWhen, validation rules, flow conditions and sharing rules reference record fields as record.<field>, never bare <field>. A bare reference is a silent runtime bug (npm run validate now rejects it).

Project Structure

{{PROJECT_NAME}}/
├── objectstack.config.ts    # defineStack() — the single entry point
├── src/
│   ├── objects/              # Business object definitions (snake_case names)
│   ├── views/                # UI view definitions (list, form, kanban, calendar)
│   ├── apps/                 # App navigation & page structure
│   ├── flows/                # Automation flows & workflows
│   ├── actions/              # Custom actions (buttons, bulk ops)
│   ├── dashboards/           # BI dashboards
│   ├── reports/              # Analytics reports
│   ├── agents/               # AI agent definitions
│   ├── i18n/                 # Translation bundles
│   └── handlers/             # Runtime hook handlers

AI Skills

This project uses ObjectStack skills from objectstack-ai/framework. Install or update skills with the standard skills CLI:

npx skills add objectstack-ai/framework/skills

Skills are triggered automatically based on task context:

Skill Trigger Context
objectstack-platform Project setup, defineStack(), driver/adapter selection, plugin lifecycle, DI, services, kernel hooks/events
objectstack-data Define objects, fields, relationships, validations, indexes, lifecycle hooks, permissions/RLS, seed fixtures (defineDataset)
objectstack-query Filters, sorting, pagination, aggregation, ObjectQL
objectstack-ui Views, dashboards, apps, reports, actions, navigation
objectstack-api REST endpoints, authentication, service contracts
objectstack-automation Flows, workflows, triggers, approvals, state machines
objectstack-ai Agents, tools, skills, RAG pipelines, LLM config
objectstack-i18n Translation bundles, locale config, coverage detection
objectstack-formula CEL formula fields, predicates, conditions, dynamic seed values

Learn More