Skip to content

gridaco/grida / .agents/skills/naming

naming

Verified

How 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.

FileKindSize
SKILL.mdskill md9.8 KB
cases.mdmarkdown3.5 KB
# 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?
finishing-a-development-branchobra/superpowersUse when implementation is complete, all tests pass, and you need to decide how to integrate the workStars: 322kUpdated Claude CodeCodexVerifiedInstall
systematic-debuggingobra/superpowersUse when encountering any bug, test failure, or unexpected behavior, before proposing fixesStars: 322kUpdated Claude CodeCodexVerifiedInstall
test-driven-developmentobra/superpowersUse when implementing any feature or bugfix, before writing implementation codeStars: 322kUpdated Claude CodeCodexVerifiedInstall
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: 198kUpdated Claude CodeCodexVerifiedInstall