@cratis/pi 2.21.2 → 2.21.3
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
|
@@ -7,6 +7,8 @@ Cratis repositories come in **two profiles**, and the rules are scoped to them.
|
|
|
7
7
|
|
|
8
8
|
**How to tell:** if the repo's own package is `Cratis.*` / `@cratis/*` and it *builds* the framework, you are in the framework profile. If it *consumes* Cratis to build a product, you are in the application profile.
|
|
9
9
|
|
|
10
|
+
**See [profiles.md](./profiles.md) for a complete list of all available profiles and how to configure them.**
|
|
11
|
+
|
|
10
12
|
Profile-specific rules declare a **`profile:`** in their frontmatter (`application` or `framework`); a rule **without** one is **universal** and applies everywhere — C#/TypeScript style, code quality, specs (`Cratis.Specifications`), documentation, commits/PRs, American English. In this file, everything from **Project Layout** through the **Implementation Workflow** is *application profile* (skip to the Framework profile section if you're contributing to the framework); Philosophy, Authority, Verification, Quality Gates, and the closing sections are universal.
|
|
11
13
|
|
|
12
14
|
> **Arc is a standalone CQRS framework — not bound to event sourcing.** Even within the application profile, Arc provides model-bound commands/queries, validation, authorization, and full-stack proxy generation, and works **without** Chronicle (Arc.Core does not depend on Chronicle). A `[Command]` `Handle()` does not *have* to append events — it can return a response, return `void`, or work through injected services. The event-sourcing behavior (a returned event gets appended; `EventForEventSourceId`; "never inject `IEventLog`") comes from the **Arc + Chronicle** integration. This application is event-sourced, so the slice guidance assumes event-sourced commands — read the event-centric rules as the *house default for this app*, not universal Arc laws.
|
|
@@ -255,6 +257,7 @@ Documentation-only changes use repository-supported non-release intent, ordinari
|
|
|
255
257
|
|
|
256
258
|
| For | Location |
|
|
257
259
|
| --- | --- |
|
|
260
|
+
| **AI Corpus Profiles** — what profiles exist and how to configure them | `profiles.md` |
|
|
258
261
|
| **Contributing to a Cratis framework repo** (framework profile) | `framework.md` |
|
|
259
262
|
| Slice anatomy (commands, `Provide()`, validators, events, projections, read models, reactors, constraints, compliance, cross-slice) | `vertical-slices.md` |
|
|
260
263
|
| C# / TypeScript style | `csharp.md`, `typescript.md` |
|
|
@@ -0,0 +1,221 @@
|
|
|
1
|
+
# AI Corpus Profiles
|
|
2
|
+
|
|
3
|
+
Profiles determine which rules and skills apply to your work. They define the scope of the AI corpus and which documentation, conventions, and skills are available.
|
|
4
|
+
|
|
5
|
+
## Two Main Profile Types
|
|
6
|
+
|
|
7
|
+
### Application Profile
|
|
8
|
+
|
|
9
|
+
**Use when:** You are building an application on Cratis.
|
|
10
|
+
|
|
11
|
+
**What it includes:**
|
|
12
|
+
- Event-sourced CQRS with **Cratis Chronicle** + **Cratis Arc**
|
|
13
|
+
- Vertical slices (commands, events, projections, read models)
|
|
14
|
+
- React + Cratis Components (PrimeReact) frontend in MVVM
|
|
15
|
+
- MongoDB or EF Core for read models
|
|
16
|
+
- Full-stack type safety from C# to TypeScript
|
|
17
|
+
|
|
18
|
+
**Key rules:**
|
|
19
|
+
- [vertical-slices.md](./vertical-slices.md) - slice anatomy and structure
|
|
20
|
+
- [react.md](./react.md) - React + Arc + Cratis Components
|
|
21
|
+
- [components.md](./components.md) - component structure and styling
|
|
22
|
+
- [dialogs.md](./dialogs.md) - dialog patterns
|
|
23
|
+
- [specs.scenarios.csharp.md](./specs.scenarios.csharp.md) - in-process scenario family
|
|
24
|
+
|
|
25
|
+
### Framework Profile
|
|
26
|
+
|
|
27
|
+
**Use when:** You are contributing to a Cratis framework repository itself (Arc, Chronicle, Fundamentals, Components, Specifications).
|
|
28
|
+
|
|
29
|
+
**What it includes:**
|
|
30
|
+
- Library development (not applications)
|
|
31
|
+
- Source generators, the Chronicle kernel (Orleans grains + storage), client SDKs, React component library
|
|
32
|
+
- No vertical slices, no model-bound `[Command]`/`[ReadModel]` artifacts
|
|
33
|
+
- No projections/read-models, no MVVM app components
|
|
34
|
+
|
|
35
|
+
**Key rules:**
|
|
36
|
+
- [framework.md](./framework.md) - repo structure and library/API design
|
|
37
|
+
- [orleans.md](./orleans.md) - Orleans grain conventions
|
|
38
|
+
- [specs.csharp.md](./specs.csharp.md) - universal `Specification` base + NSubstitute
|
|
39
|
+
|
|
40
|
+
## Profile Catalog
|
|
41
|
+
|
|
42
|
+
The complete list of available profiles is defined in [profile-catalog.json](../profile-catalog.json). This catalog includes:
|
|
43
|
+
|
|
44
|
+
### Application Profiles
|
|
45
|
+
|
|
46
|
+
| Profile ID | Description | Automatically Includes |
|
|
47
|
+
|---|---|---|
|
|
48
|
+
| `cratis/application` | Full application stack (C# + React + TypeScript) | `cratis/application/csharp`, `cratis/application/elixir`, `cratis/application/kotlin`, `cratis/application/typescript`, `cratis/arc/core`, `cratis/arc/react`, `cratis/chronicle/core`, `cratis/components`, `cratis/fundamentals`, `cratis/specifications/dotnet`, `cratis/specifications/typescript` |
|
|
49
|
+
| `cratis/application/csharp` | C# backend with Arc + Chronicle | `cratis/arc`, `cratis/arc/react`, `cratis/chronicle`, `cratis/components`, `cratis/fundamentals`, `cratis/language/csharp`, `cratis/specifications/dotnet`, `cratis/specifications/typescript` |
|
|
50
|
+
| `cratis/application/react` | React frontend with Cratis Components | `cratis/arc/core`, `cratis/arc/react`, `cratis/components`, `cratis/fundamentals`, `cratis/specifications/dotnet`, `cratis/specifications/typescript` |
|
|
51
|
+
| `cratis/application/typescript` | TypeScript client for Chronicle | `cratis/chronicle/client-typescript`, `cratis/language/typescript`, `cratis/specifications/typescript` |
|
|
52
|
+
| `cratis/application/arc-chronicle` | Arc + Chronicle integration | `cratis/arc/core`, `cratis/chronicle/core`, `cratis/fundamentals`, `cratis/specifications/dotnet` |
|
|
53
|
+
| `cratis/application/arc-only` | Arc without Chronicle | `cratis/arc/core`, `cratis/fundamentals`, `cratis/specifications/dotnet` |
|
|
54
|
+
| `cratis/application/chronicle-dotnet` | Chronicle .NET client | `cratis/chronicle/client-dotnet`, `cratis/chronicle/core`, `cratis/fundamentals`, `cratis/specifications/dotnet` |
|
|
55
|
+
| `cratis/application/elixir` | Elixir Chronicle client | `cratis/chronicle/client-elixir`, `cratis/language/elixir` |
|
|
56
|
+
| `cratis/application/kotlin` | Kotlin Chronicle client | `cratis/arc/client-kotlin`, `cratis/chronicle/client-kotlin`, `cratis/language/kotlin` |
|
|
57
|
+
|
|
58
|
+
### Framework Profiles
|
|
59
|
+
|
|
60
|
+
| Profile ID | Description | Automatically Includes |
|
|
61
|
+
|---|---|---|
|
|
62
|
+
| `cratis/arc` | Arc CQRS framework | `cratis/arc/csharp`, `cratis/arc/kotlin` |
|
|
63
|
+
| `cratis/chronicle` | Chronicle event sourcing engine | `cratis/chronicle/compliance`, `cratis/chronicle/csharp`, `cratis/chronicle/elixir`, `cratis/chronicle/kotlin`, `cratis/chronicle/multi-tenancy`, `cratis/chronicle/typescript`, `cratis/chronicle/web-workbench` |
|
|
64
|
+
| `cratis/components` | React component library | (no child profiles) |
|
|
65
|
+
| `cratis/fundamentals` | Core primitives (`ConceptAs<T>`, `EventSourceId<T>`) | (no child profiles) |
|
|
66
|
+
| `cratis/specifications` | Specification framework | (no child profiles) |
|
|
67
|
+
|
|
68
|
+
### Engineering Profiles
|
|
69
|
+
|
|
70
|
+
| Profile ID | Description | Automatically Includes |
|
|
71
|
+
|---|---|---|
|
|
72
|
+
| `cratis/engineering` | Engineering conventions and workflows | `cratis/engineering/core`, `cratis/engineering/csharp`, `cratis/engineering/elixir`, `cratis/engineering/kotlin`, `cratis/engineering/react`, `cratis/engineering/typescript` |
|
|
73
|
+
| `cratis/engineering/csharp` | C# engineering conventions | `cratis/engineering/core` |
|
|
74
|
+
| `cratis/engineering/typescript` | TypeScript engineering conventions | `cratis/engineering/core` |
|
|
75
|
+
| `cratis/engineering/react` | React engineering conventions | `cratis/engineering/core` |
|
|
76
|
+
|
|
77
|
+
### Language Profiles
|
|
78
|
+
|
|
79
|
+
| Profile ID | Description |
|
|
80
|
+
|---|---|
|
|
81
|
+
| `cratis/language/csharp` | C# language conventions |
|
|
82
|
+
| `cratis/language/typescript` | TypeScript language conventions |
|
|
83
|
+
| `cratis/language/elixir` | Elixir language conventions |
|
|
84
|
+
| `cratis/language/kotlin` | Kotlin language conventions |
|
|
85
|
+
|
|
86
|
+
### Specialized Profiles
|
|
87
|
+
|
|
88
|
+
| Profile ID | Description |
|
|
89
|
+
|---|---|
|
|
90
|
+
| `cratis/documentation` | Documentation writing |
|
|
91
|
+
| `cratis/review` | Code review, performance, security |
|
|
92
|
+
| `cratis/studio` | Studio MCP safety guidance |
|
|
93
|
+
| `cratis/cli` | CLI operations |
|
|
94
|
+
| `cratis/lens` | Lens browser extension |
|
|
95
|
+
| `cratis/screenplay` | Screenplay event modeling |
|
|
96
|
+
| `cratis/stage` | Stage rendering and sandbox |
|
|
97
|
+
|
|
98
|
+
## How to Use Profiles
|
|
99
|
+
|
|
100
|
+
### 1. Select Your Profile
|
|
101
|
+
|
|
102
|
+
Choose the profile that matches your current work:
|
|
103
|
+
|
|
104
|
+
```json
|
|
105
|
+
{
|
|
106
|
+
"schemaVersion": "1.0.0",
|
|
107
|
+
"profiles": [
|
|
108
|
+
"cratis/application/csharp",
|
|
109
|
+
"cratis/engineering/csharp"
|
|
110
|
+
]
|
|
111
|
+
}
|
|
112
|
+
```
|
|
113
|
+
|
|
114
|
+
### 2. Profile Composition
|
|
115
|
+
|
|
116
|
+
Profiles can compose other profiles. When you select a parent profile, all child profiles are automatically included.
|
|
117
|
+
|
|
118
|
+
**How composition works:**
|
|
119
|
+
- Selecting `cratis/application` automatically includes all its child profiles (listed in the "Automatically Includes" column above)
|
|
120
|
+
- Selecting `cratis/full` includes all full-stack capabilities across C#, TypeScript, Elixir, and Kotlin
|
|
121
|
+
- Selecting `cratis/engineering` automatically includes all engineering convention profiles
|
|
122
|
+
|
|
123
|
+
**Examples:**
|
|
124
|
+
|
|
125
|
+
```json
|
|
126
|
+
{
|
|
127
|
+
"schemaVersion": "1.0.0",
|
|
128
|
+
"profiles": [
|
|
129
|
+
"cratis/application" // Automatically includes all child profiles
|
|
130
|
+
]
|
|
131
|
+
}
|
|
132
|
+
```
|
|
133
|
+
|
|
134
|
+
```json
|
|
135
|
+
{
|
|
136
|
+
"schemaVersion": "1.0.0",
|
|
137
|
+
"profiles": [
|
|
138
|
+
"cratis/application/csharp" // Includes: arc, arc/react, chronicle, components, fundamentals, language/csharp, specifications/dotnet, specifications/typescript
|
|
139
|
+
]
|
|
140
|
+
}
|
|
141
|
+
```
|
|
142
|
+
|
|
143
|
+
```json
|
|
144
|
+
{
|
|
145
|
+
"schemaVersion": "1.0.0",
|
|
146
|
+
"profiles": [
|
|
147
|
+
"cratis/full" // Includes all full-stack capabilities
|
|
148
|
+
]
|
|
149
|
+
}
|
|
150
|
+
```
|
|
151
|
+
|
|
152
|
+
**Note:** The profile-catalog.json file defines the complete composition tree. When you select a parent profile, the system automatically resolves and includes all child profiles listed in the `composes` array.
|
|
153
|
+
|
|
154
|
+
### 3. Multi-Profile Work
|
|
155
|
+
|
|
156
|
+
You can work with multiple profiles simultaneously:
|
|
157
|
+
|
|
158
|
+
```json
|
|
159
|
+
{
|
|
160
|
+
"profiles": [
|
|
161
|
+
"cratis/application/csharp", // Backend development
|
|
162
|
+
"cratis/application/react", // Frontend development
|
|
163
|
+
"cratis/engineering/csharp" // Engineering conventions
|
|
164
|
+
]
|
|
165
|
+
}
|
|
166
|
+
```
|
|
167
|
+
|
|
168
|
+
### 4. Language-Specific Profiles
|
|
169
|
+
|
|
170
|
+
Select language profiles when working with specific languages:
|
|
171
|
+
|
|
172
|
+
```json
|
|
173
|
+
{
|
|
174
|
+
"profiles": [
|
|
175
|
+
"cratis/language/csharp",
|
|
176
|
+
"cratis/language/typescript"
|
|
177
|
+
]
|
|
178
|
+
}
|
|
179
|
+
```
|
|
180
|
+
|
|
181
|
+
### 5. Agent Harnesses Exclusion
|
|
182
|
+
|
|
183
|
+
**Important:** The Agent Harnesses (`.agents/` folder) should **not** include the `skills` folder from the AI corpus. The skills folder is managed separately and should be excluded from agent plugin installations.
|
|
184
|
+
|
|
185
|
+
When configuring agent plugins:
|
|
186
|
+
- The `skills` field in `marketplace.json` should point to an empty array or be omitted
|
|
187
|
+
- The `skills` symlink in `.agents/plugins/` should not reference `../.cratis/ai/skills`
|
|
188
|
+
- Agent Harnesses should only include the rules and profile-catalog.json for profile resolution
|
|
189
|
+
|
|
190
|
+
This ensures that:
|
|
191
|
+
1. Skills are managed independently from agent plugins
|
|
192
|
+
2. The AI corpus remains the source of truth for rules and profiles
|
|
193
|
+
3. Agent Harnesses don't duplicate or override the skills folder
|
|
194
|
+
|
|
195
|
+
## Profile-Specific Rules
|
|
196
|
+
|
|
197
|
+
Every rule file declares its profile in the frontmatter:
|
|
198
|
+
|
|
199
|
+
```markdown
|
|
200
|
+
---
|
|
201
|
+
profile: application
|
|
202
|
+
---
|
|
203
|
+
```
|
|
204
|
+
|
|
205
|
+
- **`profile: application`** - Rules for building applications on Cratis
|
|
206
|
+
- **`profile: framework`** - Rules for contributing to Cratis framework repos
|
|
207
|
+
- **No profile tag** - Universal rules that apply to both profiles
|
|
208
|
+
|
|
209
|
+
## Finding Profile Information
|
|
210
|
+
|
|
211
|
+
- **Full catalog:** [profile-catalog.json](../profile-catalog.json)
|
|
212
|
+
- **Application rules:** [general.md](./general.md) (Application profile section)
|
|
213
|
+
- **Framework rules:** [framework.md](./framework.md)
|
|
214
|
+
- **Engineering conventions:** [csharp.md](./csharp.md), [typescript.md](./typescript.md)
|
|
215
|
+
|
|
216
|
+
## See Also
|
|
217
|
+
|
|
218
|
+
- [general.md](./general.md) - Project instructions and profile overview
|
|
219
|
+
- [vertical-slices.md](./vertical-slices.md) - Application profile architecture
|
|
220
|
+
- [framework.md](./framework.md) - Framework profile architecture
|
|
221
|
+
- [profile-catalog.json](../profile-catalog.json) - Complete profile definitions
|