[WIP] Refactor skills module structure to align with shadcn-ui

CHANGELOG.md

@@ -7,6 +7,23 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+### Changed
+- **Skills Module Structure Refactor** — Refactored all skills in `skills/` directory to follow shadcn-ui's fine-grained layering pattern. Each skill now has:
+  - **Concise `SKILL.md`** — High-level overview with decision trees and quick-start examples, referencing detailed rules
+  - **`rules/` directory** — Detailed implementation rules with incorrect/correct code examples for better AI comprehension
+  - **`evals/` directory** — Placeholder for future evaluation tests to validate AI assistant understanding
+  - **Skills refactored:**
+    - `objectstack-data` — Extracted rules for naming, relationships, validation, indexing, field types, and hooks (moved from objectstack-hooks)
+    - `objectstack-kernel` — Extracted rules for plugin lifecycle, service registry, and hooks/events system
+    - `objectstack-hooks` — **DEPRECATED** and consolidated into `objectstack-data/rules/hooks.md` (hooks are core to data operations)
+    - `objectstack-ui`, `objectstack-api`, `objectstack-automation`, `objectstack-ai`, `objectstack-i18n`, `objectstack-quickstart` — Added `rules/` and `evals/` structure with initial pattern documentation
+  - **Benefits:**
+    - Improved maintainability — Detailed rules are separated from high-level overview
+    - Better AI comprehension — Incorrect/correct examples make patterns clearer
+    - Enhanced testability — `evals/` directory ready for skill validation tests
+    - Reduced skill overlap — Hooks integrated into data skill where they belong
+    - Preserved skill independence — Each skill remains independently installable/referenceable (no global routing required)
+
 ### Fixed
 - **CI: Replace `pnpm/action-setup@v6` with corepack** — Switched all GitHub Actions workflows (`ci.yml`, `lint.yml`, `release.yml`, `validate-deps.yml`, `pr-automation.yml`) from `pnpm/action-setup@v6` to `corepack enable` to fix persistent `ERR_PNPM_BROKEN_LOCKFILE` errors. Corepack reads the exact `packageManager` field from `package.json` (including SHA verification), ensuring the correct pnpm version is used in CI. Also bumped pnpm store cache keys to v3 and added a pnpm version verification step.
 - **Broken pnpm lockfile** — Regenerated `pnpm-lock.yaml` from scratch to fix `ERR_PNPM_BROKEN_LOCKFILE` ("expected a single document in the stream, but found more") that was causing all CI jobs to fail. The previous merge of PR #1117 only included workflow cache key changes but did not carry over the regenerated lockfile.

skills/objectstack-ai/evals/README.md

@@ -0,0 +1,46 @@
+# Evaluation Tests (evals/)
+
+This directory is reserved for future skill evaluation tests.
+
+## Purpose
+
+Evaluation tests (evals) validate that AI assistants correctly understand and apply the rules defined in this skill when generating code or providing guidance.
+
+## Structure
+
+When implemented, evals will follow this structure:
+
+```
+evals/
+├── naming/
+│   ├── test-object-names.md
+│   ├── test-field-keys.md
+│   └── test-option-values.md
+├── relationships/
+│   ├── test-lookup-vs-master-detail.md
+│   └── test-junction-patterns.md
+├── validation/
+│   ├── test-script-inversion.md
+│   └── test-state-machine.md
+└── ...
+```
+
+## Format
+
+Each eval file will contain:
+1. **Scenario** — Description of the task
+2. **Expected Output** — Correct implementation
+3. **Common Mistakes** — Incorrect patterns to avoid
+4. **Validation Criteria** — How to score the output
+
+## Status
+
+⚠️ **Not yet implemented** — This is a placeholder for future development.
+
+## Contributing
+
+When adding evals:
+1. Each eval should test a single, specific rule or pattern
+2. Include both positive (correct) and negative (incorrect) examples
+3. Reference the corresponding rule file in `rules/`
+4. Use realistic scenarios from actual ObjectStack projects

skills/objectstack-ai/rules/agent-patterns.md

@@ -0,0 +1,69 @@
+# Agent Design Patterns
+
+Guide for designing AI agents in ObjectStack.
+
+## Agent Types
+
+- **Data Chat** — Natural language query interface for data
+- **Metadata Assistant** — Schema design and modification helper
+- **Custom Agents** — Domain-specific AI assistants
+
+## Agent Configuration
+
+```typescript
+{
+  name: 'customer_support_agent',
+  model: 'gpt-4',
+  systemPrompt: 'You are a helpful customer support agent...',
+  tools: ['query_records', 'create_record', 'send_email'],
+  context: {
+    objects: ['account', 'contact', 'case'],
+  },
+}
+```
+
+## Tool Definition
+
+```typescript
+{
+  name: 'query_records',
+  description: 'Query records from an object',
+  parameters: {
+    object: { type: 'string', required: true },
+    filter: { type: 'object' },
+    limit: { type: 'number', default: 10 },
+  },
+}
+```
+
+## Incorrect vs Correct
+
+### ❌ Incorrect — Vague Tool Description
+
+```typescript
+{
+  name: 'get_data',  // ❌ Vague name
+  description: 'Gets data',  // ❌ Vague description
+}
+```
+
+### ✅ Correct — Clear Tool Definition
+
+```typescript
+{
+  name: 'query_account_records',  // ✅ Specific name
+  description: 'Query account records with optional filters and pagination',  // ✅ Clear description
+}
+```
+
+## Best Practices
+
+1. **Use clear, descriptive tool names** — Agent must understand purpose
+2. **Provide detailed tool descriptions** — Include examples
+3. **Limit tool count** — 5-10 tools per agent max
+4. **Define parameter schemas** — Validate input
+5. **Handle errors gracefully** — Return user-friendly messages
+
+---
+
+See parent skill for complete documentation: [../SKILL.md](../SKILL.md)

skills/objectstack-api/evals/README.md

@@ -0,0 +1,46 @@
+# Evaluation Tests (evals/)
+
+This directory is reserved for future skill evaluation tests.
+
+## Purpose
+
+Evaluation tests (evals) validate that AI assistants correctly understand and apply the rules defined in this skill when generating code or providing guidance.
+
+## Structure
+
+When implemented, evals will follow this structure:
+
+```
+evals/
+├── naming/
+│   ├── test-object-names.md
+│   ├── test-field-keys.md
+│   └── test-option-values.md
+├── relationships/
+│   ├── test-lookup-vs-master-detail.md
+│   └── test-junction-patterns.md
+├── validation/
+│   ├── test-script-inversion.md
+│   └── test-state-machine.md
+└── ...
+```
+
+## Format
+
+Each eval file will contain:
+1. **Scenario** — Description of the task
+2. **Expected Output** — Correct implementation
+3. **Common Mistakes** — Incorrect patterns to avoid
+4. **Validation Criteria** — How to score the output
+
+## Status
+
+⚠️ **Not yet implemented** — This is a placeholder for future development.
+
+## Contributing
+
+When adding evals:
+1. Each eval should test a single, specific rule or pattern
+2. Include both positive (correct) and negative (incorrect) examples
+3. Reference the corresponding rule file in `rules/`
+4. Use realistic scenarios from actual ObjectStack projects

skills/objectstack-api/rules/rest-patterns.md

@@ -0,0 +1,70 @@
+# REST API Patterns
+
+Guide for designing REST APIs in ObjectStack.
+
+## Auto-Generated APIs
+
+ObjectStack automatically generates REST APIs for all objects with `apiEnabled: true`:
+
+```
+GET    /api/v1/objects/{object}           # List records
+GET    /api/v1/objects/{object}/{id}      # Get single record
+POST   /api/v1/objects/{object}           # Create record
+PATCH  /api/v1/objects/{object}/{id}      # Update record
+DELETE /api/v1/objects/{object}/{id}      # Delete record
+```
+
+## API Configuration
+
+```typescript
+{
+  enable: {
+    apiEnabled: true,
+    apiMethods: ['get', 'list', 'create', 'update', 'delete'],
+  }
+}
+```
+
+## Query Parameters
+
+- `filter` — JSON filter expression
+- `sort` — Sort fields (e.g., `?sort=-created_at`)
+- `limit` — Page size (default: 50, max: 200)
+- `offset` — Pagination offset
+- `fields` — Select specific fields
+
+## Incorrect vs Correct
+
+### ❌ Incorrect — Exposing Sensitive Objects
+
+```typescript
+{
+  name: 'user_password_reset',
+  enable: {
+    apiEnabled: true,  // ❌ Sensitive data exposed
+  }
+}
+```
+
+### ✅ Correct — Disable API for Sensitive Objects
+
+```typescript
+{
+  name: 'user_password_reset',
+  enable: {
+    apiEnabled: false,  // ✅ Not exposed via API
+  }
+}
+```
+
+## Best Practices
+
+1. **Disable APIs for internal objects** — System/sensitive objects
+2. **Use apiMethods whitelist** — Limit operations (e.g., read-only)
+3. **Implement rate limiting** — Protect against abuse
+4. **Use field-level permissions** — Control data visibility
+5. **Validate input** — Use validation rules
+
+---
+
+See parent skill for complete documentation: [../SKILL.md](../SKILL.md)

skills/objectstack-automation/evals/README.md

@@ -0,0 +1,46 @@
+# Evaluation Tests (evals/)
+
+This directory is reserved for future skill evaluation tests.
+
+## Purpose
+
+Evaluation tests (evals) validate that AI assistants correctly understand and apply the rules defined in this skill when generating code or providing guidance.
+
+## Structure
+
+When implemented, evals will follow this structure:
+
+```
+evals/
+├── naming/
+│   ├── test-object-names.md
+│   ├── test-field-keys.md
+│   └── test-option-values.md
+├── relationships/
+│   ├── test-lookup-vs-master-detail.md
+│   └── test-junction-patterns.md
+├── validation/
+│   ├── test-script-inversion.md
+│   └── test-state-machine.md
+└── ...
+```
+
+## Format
+
+Each eval file will contain:
+1. **Scenario** — Description of the task
+2. **Expected Output** — Correct implementation
+3. **Common Mistakes** — Incorrect patterns to avoid
+4. **Validation Criteria** — How to score the output
+
+## Status
+
+⚠️ **Not yet implemented** — This is a placeholder for future development.
+
+## Contributing
+
+When adding evals:
+1. Each eval should test a single, specific rule or pattern
+2. Include both positive (correct) and negative (incorrect) examples
+3. Reference the corresponding rule file in `rules/`
+4. Use realistic scenarios from actual ObjectStack projects

skills/objectstack-automation/rules/flow-patterns.md

@@ -0,0 +1,88 @@
+# Flow Types and Patterns
+
+Guide for designing automation flows in ObjectStack.
+
+## Flow Types
+
+ObjectStack supports three flow types:
+
+- **Autolaunched** — Triggered by data events (insert/update/delete)
+- **Screen** — User-initiated flows with UI components
+- **Schedule** — Time-based/cron-triggered flows
+
+## Autolaunched Flow Pattern
+
+```typescript
+{
+  name: 'new_account_welcome',
+  type: 'autolaunched',
+  trigger: {
+    object: 'account',
+    event: 'afterInsert',
+  },
+  actions: [
+    {
+      type: 'send_email',
+      template: 'welcome_email',
+      to: '{!account.owner.email}',
+    },
+  ],
+}
+```
+
+## Schedule Flow Pattern
+
+```typescript
+{
+  name: 'daily_summary',
+  type: 'schedule',
+  schedule: '0 9 * * *',  // Daily at 9 AM
+  actions: [
+    {
+      type: 'query_records',
+      object: 'task',
+      filter: { due_date: 'TODAY()' },
+    },
+    {
+      type: 'send_email',
+      template: 'daily_tasks',
+    },
+  ],
+}
+```
+
+## Incorrect vs Correct
+
+### ❌ Incorrect — Autolaunched Flow Without Trigger
+
+```typescript
+{
+  type: 'autolaunched',  // ❌ No trigger specified
+  actions: [/* ... */],
+}
+```
+
+### ✅ Correct — Complete Trigger Configuration
+
+```typescript
+{
+  type: 'autolaunched',
+  trigger: {
+    object: 'account',
+    event: 'afterInsert',  // ✅ Trigger specified
+  },
+  actions: [/* ... */],
+}
+```
+
+## Best Practices
+
+1. **Use after* events for autolaunched flows** — Avoid blocking transactions
+2. **Limit flow complexity** — Break complex flows into multiple smaller flows
+3. **Handle errors gracefully** — Use try/catch, retry policies
+4. **Test flows thoroughly** — Validate all paths and edge cases
+5. **Monitor flow execution** — Track success/failure rates
+
+---
+
+See parent skill for complete documentation: [../SKILL.md](../SKILL.md)