Skip to content

Commit 61d15b4

Browse files
Claudehotlong
Claude
and
hotlong
authored
Complete skills module refactoring with rules/ and evals/ structure
Agent-Logs-Url: https://github.com/objectstack-ai/framework/sessions/7c9dbfcd-1ebf-450b-8756-2cd8cc41f5f6 Co-authored-by: hotlong <50353452+hotlong@users.noreply.github.com>
1 parent d1ce546 commit 61d15b4

File tree

16 files changed

+944
-1346
lines changed

16 files changed

+944
-1346
lines changed

‎CHANGELOG.md‎

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

88
## [Unreleased]
99

10+
### Changed
11+
- **Skills Module Structure Refactor** — Refactored all skills in `skills/` directory to follow shadcn-ui's fine-grained layering pattern. Each skill now has:
12+
- **Concise `SKILL.md`** — High-level overview with decision trees and quick-start examples, referencing detailed rules
13+
- **`rules/` directory** — Detailed implementation rules with incorrect/correct code examples for better AI comprehension
14+
- **`evals/` directory** — Placeholder for future evaluation tests to validate AI assistant understanding
15+
- **Skills refactored:**
16+
- `objectstack-data` — Extracted rules for naming, relationships, validation, indexing, field types, and hooks (moved from objectstack-hooks)
17+
- `objectstack-kernel` — Extracted rules for plugin lifecycle, service registry, and hooks/events system
18+
- `objectstack-hooks` — **DEPRECATED** and consolidated into `objectstack-data/rules/hooks.md` (hooks are core to data operations)
19+
- `objectstack-ui`, `objectstack-api`, `objectstack-automation`, `objectstack-ai`, `objectstack-i18n`, `objectstack-quickstart` — Added `rules/` and `evals/` structure with initial pattern documentation
20+
- **Benefits:**
21+
- Improved maintainability — Detailed rules are separated from high-level overview
22+
- Better AI comprehension — Incorrect/correct examples make patterns clearer
23+
- Enhanced testability — `evals/` directory ready for skill validation tests
24+
- Reduced skill overlap — Hooks integrated into data skill where they belong
25+
- Preserved skill independence — Each skill remains independently installable/referenceable (no global routing required)
26+
1027
### Fixed
1128
- **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.
1229
- **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‎

Lines changed: 46 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,46 @@
1+
# Evaluation Tests (evals/)
2+
3+
This directory is reserved for future skill evaluation tests.
4+
5+
## Purpose
6+
7+
Evaluation tests (evals) validate that AI assistants correctly understand and apply the rules defined in this skill when generating code or providing guidance.
8+
9+
## Structure
10+
11+
When implemented, evals will follow this structure:
12+
13+
```
14+
evals/
15+
├── naming/
16+
│ ├── test-object-names.md
17+
│ ├── test-field-keys.md
18+
│ └── test-option-values.md
19+
├── relationships/
20+
│ ├── test-lookup-vs-master-detail.md
21+
│ └── test-junction-patterns.md
22+
├── validation/
23+
│ ├── test-script-inversion.md
24+
│ └── test-state-machine.md
25+
└── ...
26+
```
27+
28+
## Format
29+
30+
Each eval file will contain:
31+
1. **Scenario** — Description of the task
32+
2. **Expected Output** — Correct implementation
33+
3. **Common Mistakes** — Incorrect patterns to avoid
34+
4. **Validation Criteria** — How to score the output
35+
36+
## Status
37+
38+
⚠️ **Not yet implemented** — This is a placeholder for future development.
39+
40+
## Contributing
41+
42+
When adding evals:
43+
1. Each eval should test a single, specific rule or pattern
44+
2. Include both positive (correct) and negative (incorrect) examples
45+
3. Reference the corresponding rule file in `rules/`
46+
4. Use realistic scenarios from actual ObjectStack projects

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

Lines changed: 69 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,69 @@
1+
# Agent Design Patterns
2+
3+
Guide for designing AI agents in ObjectStack.
4+
5+
## Agent Types
6+
7+
- **Data Chat** — Natural language query interface for data
8+
- **Metadata Assistant** — Schema design and modification helper
9+
- **Custom Agents** — Domain-specific AI assistants
10+
11+
## Agent Configuration
12+
13+
```typescript
14+
{
15+
name: 'customer_support_agent',
16+
model: 'gpt-4',
17+
systemPrompt: 'You are a helpful customer support agent...',
18+
tools: ['query_records', 'create_record', 'send_email'],
19+
context: {
20+
objects: ['account', 'contact', 'case'],
21+
},
22+
}
23+
```
24+
25+
## Tool Definition
26+
27+
```typescript
28+
{
29+
name: 'query_records',
30+
description: 'Query records from an object',
31+
parameters: {
32+
object: { type: 'string', required: true },
33+
filter: { type: 'object' },
34+
limit: { type: 'number', default: 10 },
35+
},
36+
}
37+
```
38+
39+
## Incorrect vs Correct
40+
41+
### ❌ Incorrect — Vague Tool Description
42+
43+
```typescript
44+
{
45+
name: 'get_data', // ❌ Vague name
46+
description: 'Gets data', // ❌ Vague description
47+
}
48+
```
49+
50+
### ✅ Correct — Clear Tool Definition
51+
52+
```typescript
53+
{
54+
name: 'query_account_records', // ✅ Specific name
55+
description: 'Query account records with optional filters and pagination', // ✅ Clear description
56+
}
57+
```
58+
59+
## Best Practices
60+
61+
1. **Use clear, descriptive tool names** — Agent must understand purpose
62+
2. **Provide detailed tool descriptions** — Include examples
63+
3. **Limit tool count** — 5-10 tools per agent max
64+
4. **Define parameter schemas** — Validate input
65+
5. **Handle errors gracefully** — Return user-friendly messages
66+
67+
---
68+
69+
See parent skill for complete documentation: [../SKILL.md](../SKILL.md)

‎skills/objectstack-api/evals/README.md‎

Lines changed: 46 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,46 @@
1+
# Evaluation Tests (evals/)
2+
3+
This directory is reserved for future skill evaluation tests.
4+
5+
## Purpose
6+
7+
Evaluation tests (evals) validate that AI assistants correctly understand and apply the rules defined in this skill when generating code or providing guidance.
8+
9+
## Structure
10+
11+
When implemented, evals will follow this structure:
12+
13+
```
14+
evals/
15+
├── naming/
16+
│ ├── test-object-names.md
17+
│ ├── test-field-keys.md
18+
│ └── test-option-values.md
19+
├── relationships/
20+
│ ├── test-lookup-vs-master-detail.md
21+
│ └── test-junction-patterns.md
22+
├── validation/
23+
│ ├── test-script-inversion.md
24+
│ └── test-state-machine.md
25+
└── ...
26+
```
27+
28+
## Format
29+
30+
Each eval file will contain:
31+
1. **Scenario** — Description of the task
32+
2. **Expected Output** — Correct implementation
33+
3. **Common Mistakes** — Incorrect patterns to avoid
34+
4. **Validation Criteria** — How to score the output
35+
36+
## Status
37+
38+
⚠️ **Not yet implemented** — This is a placeholder for future development.
39+
40+
## Contributing
41+
42+
When adding evals:
43+
1. Each eval should test a single, specific rule or pattern
44+
2. Include both positive (correct) and negative (incorrect) examples
45+
3. Reference the corresponding rule file in `rules/`
46+
4. Use realistic scenarios from actual ObjectStack projects

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

Lines changed: 70 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,70 @@
1+
# REST API Patterns
2+
3+
Guide for designing REST APIs in ObjectStack.
4+
5+
## Auto-Generated APIs
6+
7+
ObjectStack automatically generates REST APIs for all objects with `apiEnabled: true`:
8+
9+
```
10+
GET /api/v1/objects/{object} # List records
11+
GET /api/v1/objects/{object}/{id} # Get single record
12+
POST /api/v1/objects/{object} # Create record
13+
PATCH /api/v1/objects/{object}/{id} # Update record
14+
DELETE /api/v1/objects/{object}/{id} # Delete record
15+
```
16+
17+
## API Configuration
18+
19+
```typescript
20+
{
21+
enable: {
22+
apiEnabled: true,
23+
apiMethods: ['get', 'list', 'create', 'update', 'delete'],
24+
}
25+
}
26+
```
27+
28+
## Query Parameters
29+
30+
- `filter` — JSON filter expression
31+
- `sort` — Sort fields (e.g., `?sort=-created_at`)
32+
- `limit` — Page size (default: 50, max: 200)
33+
- `offset` — Pagination offset
34+
- `fields` — Select specific fields
35+
36+
## Incorrect vs Correct
37+
38+
### ❌ Incorrect — Exposing Sensitive Objects
39+
40+
```typescript
41+
{
42+
name: 'user_password_reset',
43+
enable: {
44+
apiEnabled: true, // ❌ Sensitive data exposed
45+
}
46+
}
47+
```
48+
49+
### ✅ Correct — Disable API for Sensitive Objects
50+
51+
```typescript
52+
{
53+
name: 'user_password_reset',
54+
enable: {
55+
apiEnabled: false, // ✅ Not exposed via API
56+
}
57+
}
58+
```
59+
60+
## Best Practices
61+
62+
1. **Disable APIs for internal objects** — System/sensitive objects
63+
2. **Use apiMethods whitelist** — Limit operations (e.g., read-only)
64+
3. **Implement rate limiting** — Protect against abuse
65+
4. **Use field-level permissions** — Control data visibility
66+
5. **Validate input** — Use validation rules
67+
68+
---
69+
70+
See parent skill for complete documentation: [../SKILL.md](../SKILL.md)

‎skills/objectstack-automation/evals/README.md‎

Lines changed: 46 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,46 @@
1+
# Evaluation Tests (evals/)
2+
3+
This directory is reserved for future skill evaluation tests.
4+
5+
## Purpose
6+
7+
Evaluation tests (evals) validate that AI assistants correctly understand and apply the rules defined in this skill when generating code or providing guidance.
8+
9+
## Structure
10+
11+
When implemented, evals will follow this structure:
12+
13+
```
14+
evals/
15+
├── naming/
16+
│ ├── test-object-names.md
17+
│ ├── test-field-keys.md
18+
│ └── test-option-values.md
19+
├── relationships/
20+
│ ├── test-lookup-vs-master-detail.md
21+
│ └── test-junction-patterns.md
22+
├── validation/
23+
│ ├── test-script-inversion.md
24+
│ └── test-state-machine.md
25+
└── ...
26+
```
27+
28+
## Format
29+
30+
Each eval file will contain:
31+
1. **Scenario** — Description of the task
32+
2. **Expected Output** — Correct implementation
33+
3. **Common Mistakes** — Incorrect patterns to avoid
34+
4. **Validation Criteria** — How to score the output
35+
36+
## Status
37+
38+
⚠️ **Not yet implemented** — This is a placeholder for future development.
39+
40+
## Contributing
41+
42+
When adding evals:
43+
1. Each eval should test a single, specific rule or pattern
44+
2. Include both positive (correct) and negative (incorrect) examples
45+
3. Reference the corresponding rule file in `rules/`
46+
4. Use realistic scenarios from actual ObjectStack projects

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

Lines changed: 88 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,88 @@
1+
# Flow Types and Patterns
2+
3+
Guide for designing automation flows in ObjectStack.
4+
5+
## Flow Types
6+
7+
ObjectStack supports three flow types:
8+
9+
- **Autolaunched** — Triggered by data events (insert/update/delete)
10+
- **Screen** — User-initiated flows with UI components
11+
- **Schedule** — Time-based/cron-triggered flows
12+
13+
## Autolaunched Flow Pattern
14+
15+
```typescript
16+
{
17+
name: 'new_account_welcome',
18+
type: 'autolaunched',
19+
trigger: {
20+
object: 'account',
21+
event: 'afterInsert',
22+
},
23+
actions: [
24+
{
25+
type: 'send_email',
26+
template: 'welcome_email',
27+
to: '{!account.owner.email}',
28+
},
29+
],
30+
}
31+
```
32+
33+
## Schedule Flow Pattern
34+
35+
```typescript
36+
{
37+
name: 'daily_summary',
38+
type: 'schedule',
39+
schedule: '0 9 * * *', // Daily at 9 AM
40+
actions: [
41+
{
42+
type: 'query_records',
43+
object: 'task',
44+
filter: { due_date: 'TODAY()' },
45+
},
46+
{
47+
type: 'send_email',
48+
template: 'daily_tasks',
49+
},
50+
],
51+
}
52+
```
53+
54+
## Incorrect vs Correct
55+
56+
### ❌ Incorrect — Autolaunched Flow Without Trigger
57+
58+
```typescript
59+
{
60+
type: 'autolaunched', // ❌ No trigger specified
61+
actions: [/* ... */],
62+
}
63+
```
64+
65+
### ✅ Correct — Complete Trigger Configuration
66+
67+
```typescript
68+
{
69+
type: 'autolaunched',
70+
trigger: {
71+
object: 'account',
72+
event: 'afterInsert', // ✅ Trigger specified
73+
},
74+
actions: [/* ... */],
75+
}
76+
```
77+
78+
## Best Practices
79+
80+
1. **Use after* events for autolaunched flows** — Avoid blocking transactions
81+
2. **Limit flow complexity** — Break complex flows into multiple smaller flows
82+
3. **Handle errors gracefully** — Use try/catch, retry policies
83+
4. **Test flows thoroughly** — Validate all paths and edge cases
84+
5. **Monitor flow execution** — Track success/failure rates
85+
86+
---
87+
88+
See parent skill for complete documentation: [../SKILL.md](../SKILL.md)

0 commit comments

Comments
 (0)