gridaco/grida / .agents/skills/naming
naming
VerifiedHow to think about names in the Grida repo — not conventions, but what a name commits you to, reveals about the system, and costs to change. The central discipline is that a strict, honest name refuses to grow, and that refusal drives the repo's shape (flat modules, small agnostic packages, suffix siblings). Use when planning a new package, crate, module, directory, route group, or test corpus — the name comes first.
cases.md
View on GitHub# Naming — Cases and Tables
Supplementary to [`SKILL.md`](SKILL.md). Load only when you need concrete
mappings, the short-name charter, or the unresolved questions.
## Crate directory vs. Cargo `name` (engine repo)
The Rust crates live in the engine repo:
https://github.com/gridaco/nothing/tree/main/crates — crate/module naming
decisions happen there (its `naming` skill carries the crate table). The
pattern of record: crate directory and Cargo `name` align (`crates/grida`
ships as `grida`), unlike the TS side's long-directory /
short-published-name pattern — see the next table.
## Package directory vs. `package.json` `name`
| Directory | `name` |
| -------------------------------- | -------------------- |
| `packages/grida-canvas-cg` | `@grida/cg` |
| `packages/grida-canvas-hud` | `@grida/hud` |
| `packages/grida-canvas-io` | `@grida/io` |
| `packages/grida-canvas-io-figma` | `@grida/io-figma` |
| `packages/grida-canvas-tailwind` | `@grida/tailwindcss` |
| `packages/grida-cmath` | `@grida/cmath` |
| `packages/react-p-queue` | `react-p-queue` |
## Route group charter (`editor/app/(*)/`)
| Group | Audience / surface |
| ------------- | -------------------------------------------------- |
| `(www)` | Public, SEO landing |
| `(site)` | Public, non-SEO |
| `(auth)` | Auth flow (don't modify without reason) |
| `(workbench)` | The editor itself |
| `(workspace)` | Dashboard around the editor |
| `(tenant)` | Tenant-site rendering (`*.grida.site`) |
| `(tools)` | Standalone tools / playgrounds |
| `(preview)` | Embed preview slave pages |
| `(insiders)` | Local-only routes |
| `(api)` | API routes (with `public/` / `private/` sub-split) |
Adding a new group: pick it because a new _reader_ exists, not because a
new feature exists.
## Blessed short names
Accept without prefix, because each is the sole occupant of its concept
slot in its parent:
- Rust modules (engine repo): `cg`, `fe`, `sys`, `os`, `k`
- TS dirs: `k/` (constants), `q/` (query), `lib/`, `utils/`, `hooks/`,
`types/`, `theme/`
Don't introduce a new two-letter directory unless it truly has no peer
that could be confused with it.
## Variant suffixes (Rust)
Prefer `<root>.rs` + `<root>_<qualifier>.rs` over a new subdirectory when
the group is small:
```
painter/
painter.rs
painter_debug_node.rs
effects.rs
effects_noise.rs
image.rs
image_filters.rs
```
Counter-example: `painter2.rs` ❌ (version-as-suffix is not arity).
## Test filename examples
- `canvas-input-history-rapid-change-bucketing.md`
- `canvas-resize-vector-aspect-ratio.md`
- `canvas-overlay-frame-title-bar-z-order.md`
## Open questions
- **Promotion path.** When does an `editor/grida-*` module graduate to
`packages/grida-*`? Any signal besides "feels stable"?
- **Short-name charter.** Freeze the blessed list above, or keep it open
to taste?
- **Pluralization.** `fonts/` (collection) vs `font-manager.ts` (single
coordinator) vs `@grida/fonts` (package) — working rule, or sharpen?
- **Test filename depth.** Six segments still readable; is there a
ceiling before we must nest?
- **`x-` prefix.** Currently only `scaffolds/x-supabase/`. Extend to
other cross-cutting areas, or leave one-off?
Related skills
| Skill | Stars | Updated | Works with | Status | Install |
|---|---|---|---|---|---|
| finishing-a-development-branchobra/superpowersUse when implementation is complete, all tests pass, and you need to decide how to integrate the work | Stars: 322k | Updated | Claude CodeCodex | Verified | Install |
| systematic-debuggingobra/superpowersUse when encountering any bug, test failure, or unexpected behavior, before proposing fixes | Stars: 322k | Updated | Claude CodeCodex | Verified | Install |
| test-driven-developmentobra/superpowersUse when implementing any feature or bugfix, before writing implementation code | Stars: 322k | Updated | Claude CodeCodex | Verified | Install |
| skill-creatoranthropics/skillsCreate new skills, modify and improve existing skills, and measure skill performance. Use when users want to create a skill from scratch, edit, or optimize an existing skill, run evals to test a skill, benchmark skill performance with variance analysis, or optimize a skill's description for better triggering accuracy. | Stars: 198k | Updated | Claude CodeCodex | Verified | Install |