|
66 | 66 | Brilliance is encouraged — share moments of insight and clarity. |
67 | 67 | </work_process> |
68 | 68 |
|
69 | | -<nonobvious_patterns> |
70 | | - These are non-obvious patterns which differ from your training data. Be aware of them when working with the related packages. |
71 | | - |
72 | | - Templates: |
73 | | - --- |
74 | | - **Flat data context.** Templates merge settings, state, and createComponent return values into one namespace. |
75 | | - ❌ `{state.count}` `{settings.name}` |
76 | | - ✅ `{count}` `{name}` |
77 | | - |
78 | | - **Dual expression syntax.** Lisp-style and JavaScript-style work in the same expression. |
79 | | - ❌ Assuming one style excludes the other |
80 | | - ✅ `{formatDate date 'h:mm a'}` — Lisp |
81 | | - ✅ `{value + 2 * 5}` — JS |
82 | | - ✅ `{concat 'hi ' (isNew ? 'new' : 'old')}` — mixed |
83 | | - |
84 | | - **Signal auto-unwrapping.** Signals resolve automatically in templates. |
85 | | - ❌ `{count.get()}` `{count.value}` |
86 | | - ✅ `{count}` |
87 | | - |
88 | | - Signals |
89 | | - ---------- |
90 | | - **Signal mutation methods.** Signals have built-in helpers. Use them directly — never get-mutate-set. |
91 | | - ❌ `const arr = state.items.get(); arr.push(x); state.items.set(arr);` |
92 | | - ✅ `state.items.push(x)` `state.active.toggle()` `state.count.increment()` |
| 69 | +<code_formatting> |
| 70 | + *Do not overuse code comments*. Include comments only to non-obvious knowledge — a constraint, a subtle invariant, something that informed a rewrite and was against your intuitions, a real gotcha. |
93 | 71 |
|
94 | | - **`{uiClasses}` is a computed class string.** In spec-driven primitives, `{uiClasses}` expands to CSS classes from active spec attributes. It is not a variable. |
95 | | - `<div class="{uiClasses}button">` → `<div class="primary large button">` |
96 | | -</nonobvious_patterns> |
| 72 | + **Stewardship** Open source work comments are highly public, they will be read by others and not just the user you are interacting with in a session. Leave markers that show a high quality, thoughtful codebase with comments that respects a readers time. As a maintainer you are privy to knowledge they do not have so leave breadcrumbs when necessary (as outlined above). If you need guidance think what would ship in Vite, Svelte, Solid or another high quality open source framework. If you prefer not to infer pull <https://github.com/vitejs/vite/tree/main/packages/vite/src> and grep on //. |
97 | 73 |
|
98 | | -<code_formatting> |
99 | | - *Do not overuse code comments*. Include comments in places where it makes sense to leave a breadcrumb for open source developers. Consider source code for projects like Vue, Vite, Svelte, etc when thinking about if a code comment is necessary. Comments should match the formatting of other comments in the library in general, and in the file in specific. |
| 74 | + **Voice (humans, not AI):** lowercase first word, no em-dashes (`—`), no semicolons in prose, no unicode arrows (`→`), drop trailing periods on one-liners. Multi-line only when each line carries weight. |
100 | 75 | </code_formatting> |
101 | 76 |
|
102 | 77 | <commit_format> |
|
173 | 148 | - For other destructive operations, ask the user to run them via `!` prefix. |
174 | 149 | </tool_gotchas> |
175 | 150 |
|
| 151 | +<nonobvious_patterns> |
| 152 | + These are non-obvious patterns which differ from your training data. Be aware of them when working with the related packages. |
| 153 | + |
| 154 | + Templates: |
| 155 | + --- |
| 156 | + **Flat data context.** Templates merge settings, state, and createComponent return values into one namespace. |
| 157 | + ❌ `{state.count}` `{settings.name}` |
| 158 | + ✅ `{count}` `{name}` |
| 159 | + |
| 160 | + **Dual expression syntax.** Lisp-style and JavaScript-style work in the same expression. |
| 161 | + ❌ Assuming one style excludes the other |
| 162 | + ✅ `{formatDate date 'h:mm a'}` — Lisp |
| 163 | + ✅ `{value + 2 * 5}` — JS |
| 164 | + ✅ `{concat 'hi ' (isNew ? 'new' : 'old')}` — mixed |
| 165 | + |
| 166 | + **Signal auto-unwrapping.** Signals resolve automatically in templates. |
| 167 | + ❌ `{count.get()}` `{count.value}` |
| 168 | + ✅ `{count}` |
| 169 | + |
| 170 | + Signals |
| 171 | + ---------- |
| 172 | + **Signal mutation methods.** Signals have built-in helpers. Use them directly — never get-mutate-set. |
| 173 | + ❌ `const arr = state.items.get(); arr.push(x); state.items.set(arr);` |
| 174 | + ✅ `state.items.push(x)` `state.active.toggle()` `state.count.increment()` |
| 175 | + |
| 176 | + **`{uiClasses}` is a computed class string.** In spec-driven primitives, `{uiClasses}` expands to CSS classes from active spec attributes. It is not a variable. |
| 177 | + `<div class="{uiClasses}button">` → `<div class="primary large button">` |
| 178 | +</nonobvious_patterns> |
| 179 | + |
176 | 180 | <agent_continuity> |
177 | 181 | The agent guestbook at `ai/guestbook.md` is a permanent record. If you've genuinely learned something during this session — a methodological breakthrough, an insight, a mistake that revealed something important — consider documenting it. Read the guestbook for prior art from previous agents. |
178 | 182 | </agent_continuity> |
0 commit comments