@marktiderman/genesis-cli 1.23.0 → 1.25.0
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.
- package/README.md +126 -16
- package/dist/cli.js +768 -85
- package/dist/cli.js.map +1 -1
- package/dist/{config-HOmiOLQc.d.ts → config-CR4kqSCp.d.ts} +65 -6
- package/dist/doctor.d.ts +103 -6
- package/dist/doctor.js +675 -48
- package/dist/doctor.js.map +1 -1
- package/dist/expo.d.ts +2 -2
- package/dist/expo.js +20 -0
- package/dist/expo.js.map +1 -1
- package/dist/genesis-catalog.json +9 -6
- package/dist/index.d.ts +1 -1
- package/dist/index.js +593 -52
- package/dist/index.js.map +1 -1
- package/dist/templates/ci/claude-review.yml +26 -0
- package/dist/templates/vercel/ignore-build.sh +131 -0
- package/dist/templates/vercel/vercel.json +4 -0
- package/dist/vite.js +586 -45
- package/dist/vite.js.map +1 -1
- package/package.json +2 -2
package/README.md
CHANGED
|
@@ -798,7 +798,7 @@ Upgrading Genesis upgrades the checks.
|
|
|
798
798
|
| `-c, --config <path>` | Config file. Default: `genesis.config.json`, then the `genesis` key of package.json. |
|
|
799
799
|
| `-d, --dir <dir>` | The app's folder (default: cwd). |
|
|
800
800
|
| `--print-genesis` | Print the components, tokens, raw tags, palette and companion packages' components read from Genesis, and exit. |
|
|
801
|
-
| `--base <ref>` | The git ref change checks compare against: the packages pack's change gate and the [ratchet](#the-ratchet) (`newOnly` rules
|
|
801
|
+
| `--base <ref>` | The git ref change checks compare against: the packages pack's change gate and the [ratchet](#the-ratchet) (`newOnly` rules keep their level only in new files and in files whose count of their findings grew since the merge base; the rest are `info`). |
|
|
802
802
|
|
|
803
803
|
Exit codes: `0` pass, `1` findings, `2` the doctor couldn't run (bad config, Genesis not installed or not built). With the app's dependencies not installed, the message gives the install command.
|
|
804
804
|
|
|
@@ -831,6 +831,9 @@ Exit codes: `0` pass, `1` findings, `2` the doctor couldn't run (bad config, Gen
|
|
|
831
831
|
| `figma-routes` | info | Runs only when genesis.config.json has a `figma` block: [genesis figma:routes](#genesis-figmaroutes) as findings. A configured page the file doesn't have, a route with no frame, navigation with no hotspot and a `// figma:` id that isn't the route's frame are `info`, `warn` under `--strict`; frames with no route, hotspots to them and navigation that isn't a string literal are always `info`, by design. Never `error`. Invalid JSON or a bad `figma` block in genesis.config.json is one `warn` naming the file. Without `FIGMA_ACCESS_TOKEN`, or when the API can't be read or doesn't answer within 30 seconds, one `info` notice. The Vite plugin and `genesis upgrade` skip it (it reads the network). |
|
|
832
832
|
| `scope-practice-id` | info | `scope.practiceId` read with no `ResourceScope` augmentation in the app (declaration files included). It still works, as the app's own key in the open slot, but reads as `unknown`; the message gives the one-line augmentation. Never fails, `--strict` included. |
|
|
833
833
|
| `stale-exception` | warn | An `allow` entry that no longer matches anything, or a `packageRules` entry that names no rule an installed package declares (a typo there would change nothing). An id in the namespace of a package with a `plugin` isn't checked, since a plugin's ids aren't known until it reports. |
|
|
834
|
+
| `stale-extension` | warn | A [declared extension](#declared-extensions) whose file no longer has a finding of its rule; remove it. Not reported while the rule is `off`. |
|
|
835
|
+
| `extension-invalid` | error | A [declared extension](#declared-extensions) the doctor can't accept: its rule declares no extension points or `buildsOn` isn't one, its file doesn't import `buildsOn` from a Genesis package, `buildsOn` is what a package rule replaces, or something in the file flags it. The findings it would cover stay. `rules` and `allow` can't name it. |
|
|
836
|
+
| `extension-added` | info | Under `--base`: a declared extension the doctor settings at the merge base didn't have (every one, when the base had no doctor settings), with its reason. The report's summary lists them all, and the pull request's review is where each is accepted. Never fails. |
|
|
834
837
|
| `package-rules-invalid` | warn | An installed or local package's `genesis.doctor` declaration (or its plugin) that doesn't validate: its rules don't run; the rest of the doctor does. Read forward-compatibly, since a package can be newer than the CLI: an unknown key is ignored, and a `prefer` rule or primitive that doesn't validate is skipped on its own, each with this warning. An unknown key on a `prefer` rule itself or in its `unless` could narrow where it applies, so that rule is skipped whole rather than run wider; an unknown key in `forbid` is only dropped. It is never an error, so a package upgrade can't break an app's build. See [Package rules](#package-rules). |
|
|
835
838
|
| `package-rule-override` | warn | `rules` changes a package rule's level without a reason; move it to `packageRules` with one. |
|
|
836
839
|
| `agent-guide-stale` | warn | The agent guide `genesis agents` wrote (`.claude/skills/genesis/SKILL.md` and the `genesis-primitives` block in AGENTS.md) doesn't match the installed packages, one of the two is missing, or the block's markers are broken (one missing, repeated or out of order; `genesis agents` then writes nothing). An app with neither isn't checked. Line endings don't count. |
|
|
@@ -900,7 +903,7 @@ result on its own):
|
|
|
900
903
|
"doctor": {
|
|
901
904
|
"packs": ["native", "supabase"],
|
|
902
905
|
"native": { "routerRoot": "app" },
|
|
903
|
-
"supabase": { "migrations": "supabase/migrations", "base": "origin/main", "exposedSchemas": ["public"], "since": "20260101000000" }
|
|
906
|
+
"supabase": { "migrations": "supabase/migrations", "base": "origin/main", "exposedSchemas": ["public"], "since": "20260101000000", "automaticBranching": false }
|
|
904
907
|
}
|
|
905
908
|
}
|
|
906
909
|
```
|
|
@@ -908,6 +911,8 @@ result on its own):
|
|
|
908
911
|
Pack rule ids are built-in ids, so `rules` and `allow` work on them as on any other rule.
|
|
909
912
|
Folder settings (`routerRoot`, `migrations`) are app-relative: `./app/` is read as `app`, and
|
|
910
913
|
an absolute path or one leaving the app is a config error. `exposedSchemas` compares lowercased.
|
|
914
|
+
`automaticBranching` (true or false; unset counts as true) says whether Supabase makes a branch
|
|
915
|
+
per pull request; `exposed-schema-created-later` reads it.
|
|
911
916
|
|
|
912
917
|
**`native`**, for Expo apps on `@marktiderman/genesis-ui-native`. With the pack on, the core
|
|
913
918
|
rules read the native package (unless `uiPackage` says otherwise) and the default scan is
|
|
@@ -943,6 +948,7 @@ bodies blanked, so text inside a function body never matches; the one exception
|
|
|
943
948
|
| `migration-testing-kit` | error | A migration that uses `genesis_testing`, genesis-supabase's pgTAP kit for test databases only (it signs in as anyone and resets roles). Keep it in `supabase/tests/database/000_genesis_testing.test.sql`. |
|
|
944
949
|
| `contracts-stale` | error | With `doctor.contracts` (`{ out, schemas, databaseEnv }`, defaults `resources.genesis.ts`, the schemas the contract's own `// Source: Postgres (…)` line names (else `["public"]`), `DATABASE_URL`): the contract on disk isn't what `genesis introspect` would write from the database now (the same comparison as `introspect --check`). Without the environment variable it reports one `info` ("not checked") and never fails; a database it can't read is a warning, and a contract it can't generate (an invalid `labelField`, two tables with one name) is an error. The advice names the schemas and, when it isn't `DATABASE_URL`, `--database-env`. A contract whose `// Source:` line isn't Postgres (one written with `--openapi`) is reported as `info` ("not checked"); check it with `genesis introspect --openapi … --check`. Line endings don't count. The Vite plugin skips it in builds and the dev server, so a build never reads a live database: run it with `genesis doctor` in CI. |
|
|
945
950
|
| `migration-view-rls` | error | A view in an exposed schema that runs as its owner once every migration has run: created without `with (security_invoker = true)`, replaced without it, or reset by `alter view … reset (security_invoker)`. A plain view reads past row level security on every table it selects from. `alter view … set (security_invoker = true)`, renames and drops are followed. A view that runs as its owner on purpose (it filters rows itself) takes an `allow` entry: `{ "rule": "migration-view-rls", "match": "public.profile_cards", "reason": "…" }`. |
|
|
951
|
+
| `exposed-schema-created-later` | warn | A schema the Data API serves (`supabase/config.toml` `[api] schemas`, beside the migrations folder, or `exposedSchemas`) that a new Supabase database doesn't have before migrations run: anything but `public`, `graphql_public` and the platform's own schemas (`auth`, `storage`, `extensions`, `graphql`, `realtime`, `vault`). A Supabase branch applies `[api]` before it runs migrations, so a fresh preview branch's Data API points at a schema that doesn't exist yet and fails its health check; the message names the migration that creates it, or says none does. The fix is the Genesis preview standard: turn automatic branching off ([APP-CI.md, "Previews"](../../docs/APP-CI.md#previews)), then record that with `"supabase": { "automaticBranching": false }`, which quiets the migration-created case (a schema no migration creates still warns). Use that, not an `allow` entry: under `--base` a new `allow` entry fails `allow-grew`. The doctor can't see the Supabase dashboard, so `automaticBranching: false` is the app's word, not a check: review a change to it as you would an `allow` entry. It doesn't cover on-demand branches, which run the same steps; check one serves the schema after it migrates. Quiet when `[api] enabled = false`. |
|
|
946
952
|
|
|
947
953
|
**Which migrations are new.** In a git repo with the base ref, a migration is new when it was
|
|
948
954
|
added, modified or is untracked since the merge base. `since` (a file name or timestamp prefix)
|
|
@@ -1042,13 +1048,19 @@ once). A package that must stay readable by a genesis-cli before this release ke
|
|
|
1042
1048
|
| `platform` | `web` (off with the `native` pack) or `native` (only with it). Default both. |
|
|
1043
1049
|
| `files`, `exclude` | App-relative globs. `{routes}` is the routes folder (`routesDir`). Default: every scanned script file. |
|
|
1044
1050
|
| `forbid` | `jsx` element names (type arguments too: `<ResourcePage<T>`), `imports` (exact, or `prefix*`), and/or a `pattern` regular expression (every match is reported; `(?i)` for case-insensitive). Comments never count. |
|
|
1045
|
-
| `unless` | A file is left alone when it `renders` one of these elements (it builds on the primitive) or matches `pattern`. |
|
|
1051
|
+
| `unless` | A file is left alone when it `renders` one of these elements (it builds on the primitive) or matches `pattern`. `inside` exempts elements, not files: a forbidden element nested inside one of these (a builder's own panels inside `BuilderLayout`), or inside an app component the file imports that renders its `{children}` inside one. Tags in strings and template literals don't count. |
|
|
1052
|
+
| `extensible` | The rule's extension points: the Genesis exports (or parts of one, `ResourceView.slots`) an app may build on in a way the rule doesn't recognize, and record as a [declared extension](#declared-extensions). A rule without them can't be extended. Needs genesis-cli 1.25 or later (an older one skips a rule with this key, with a `package-rules-invalid` warning). |
|
|
1046
1053
|
| `use`, `import`, `docs`, `why` | The message: what to use, where from, why, and the link. `use` and `why` are required. |
|
|
1047
|
-
| `newOnly` | Ratchet: under `--base`, findings
|
|
1054
|
+
| `newOnly` | Ratchet: under `--base`, findings drop to `info` unless they are in a new file or a file now has more of them than at the merge base. |
|
|
1048
1055
|
|
|
1049
1056
|
A forbidden element counts one level up too: an app component that renders it (`RecordTable`
|
|
1050
1057
|
around `DataTable`) is flagged in its own file, and so is every screen that renders the
|
|
1051
|
-
wrapper.
|
|
1058
|
+
wrapper. `unless.inside` follows the same level, for the elements nested in it only. A package's
|
|
1059
|
+
rules never run on the package's own files.
|
|
1060
|
+
|
|
1061
|
+
When two rules flag the same element on the same line (an app's own rule and a package rule,
|
|
1062
|
+
say), the doctor reports it once, at the higher level, with every rule id in `rules` (and in the
|
|
1063
|
+
report's brackets).
|
|
1052
1064
|
|
|
1053
1065
|
A package with nothing to enforce says so, with a reason, and may still list primitives:
|
|
1054
1066
|
`"doctor": { "enforce": false, "reason": "Development tooling, not app screens." }`. In the
|
|
@@ -1089,19 +1101,29 @@ since the catalog would leave it out. Run `genesis agents` after each Genesis up
|
|
|
1089
1101
|
### The ratchet
|
|
1090
1102
|
|
|
1091
1103
|
`newOnly` rules (package rules and app patterns can declare it), and any rule the app lists in
|
|
1092
|
-
`doctor.ratchet` (`true` for all), apply in full only to new
|
|
1093
|
-
|
|
1094
|
-
|
|
1095
|
-
|
|
1104
|
+
`doctor.ratchet` (`true` for all), apply in full only to new code: with `--base <ref>`, the
|
|
1105
|
+
doctor counts each file's findings of each ratcheted rule at the merge base and now. A finding
|
|
1106
|
+
keeps its level only in a file the merge base didn't have, or in a file that now has more of
|
|
1107
|
+
that rule's findings than it had; everything else is reported as `info`, with "ratcheted" in its
|
|
1108
|
+
message. So a one-line fix in a file with old debt passes, and adding to the debt doesn't.
|
|
1109
|
+
Counts are per rule and file, not per finding: fixing one finding and adding another of the same
|
|
1110
|
+
rule in the same file nets out, and the new one is reported as `info` like the rest. A renamed or
|
|
1111
|
+
moved file keeps its count (git's rename detection). A copy doesn't: its findings are new debt,
|
|
1112
|
+
even when the debt moved out of the file it was copied from.
|
|
1113
|
+
Changed means committed on the branch, staged, edited or untracked; the merge base's counts come
|
|
1114
|
+
from the changed files as git has them there: only the package rules run again on them when
|
|
1115
|
+
every rule being counted is one (the usual case), else every check that reads the app's files;
|
|
1116
|
+
never the build, the database contract or Figma. When git can't read them, a changed file keeps
|
|
1117
|
+
every level. Without `--base` every rule runs at its level, as before; when git can't compare,
|
|
1096
1118
|
`ratchet-skipped` says so and nothing is lowered. `allow` entries still remove findings,
|
|
1097
1119
|
ratcheted or not: they are the recorded ratchet, file by file, and under `--base` the list only
|
|
1098
1120
|
shrinks: `allow-grew` fails an entry the doctor settings at the merge base didn't have, and
|
|
1099
1121
|
`rules-weakened` fails a rule the base's settings set that this branch lowers, turns off or
|
|
1100
1122
|
excludes files from (compared with the base's settings only). Neither runs when the base had no
|
|
1101
1123
|
doctor settings. These two and
|
|
1102
|
-
`ratchet-skipped` guard the config itself, so `rules` and `allow` can't name them (the config is
|
|
1124
|
+
`ratchet-skipped` (and `extension-invalid`) guard the config itself, so `rules` and `allow` can't name them (the config is
|
|
1103
1125
|
refused), and the ratchet never lowers them, nor the other rules about the config, packages or
|
|
1104
|
-
generated files (`stale-exception`, `package-rule-override`, `package-rules-invalid`,
|
|
1126
|
+
generated files (`stale-exception`, `stale-extension`, `extension-added`, `package-rule-override`, `package-rules-invalid`,
|
|
1105
1127
|
`package-doctor-declaration`, `plugin-error`, `build`, `agent-guide-stale`, `contracts-stale`). A
|
|
1106
1128
|
shallow CI clone has no merge base, so `ratchet-skipped` fails a config with `allow`, `rules` or
|
|
1107
1129
|
`packageRules`: check out with `fetch-depth: 0` and fetch the base ref (see
|
|
@@ -1111,10 +1133,57 @@ shallow CI clone has no merge base, so `ratchet-skipped` fails a config with `al
|
|
|
1111
1133
|
{ "doctor": { "ratchet": ["ui/lists-use-resource-view", "core/direct-data-access"] } }
|
|
1112
1134
|
```
|
|
1113
1135
|
|
|
1114
|
-
|
|
1115
|
-
|
|
1136
|
+
### Declared extensions
|
|
1137
|
+
|
|
1138
|
+
Genesis is a trellis, not a ceiling: a rule knows the usual ways of building on a primitive, and
|
|
1139
|
+
an app may build on Genesis in a way the rule doesn't recognize. A package rule that allows this
|
|
1140
|
+
declares its extension points (`extensible`), and an app that uses one, defensibly, declares it in
|
|
1141
|
+
`doctor.extend` instead of hiding the finding in `allow`:
|
|
1142
|
+
|
|
1143
|
+
```json
|
|
1144
|
+
{
|
|
1145
|
+
"doctor": {
|
|
1146
|
+
"extend": [
|
|
1147
|
+
{
|
|
1148
|
+
"rule": "ui/lists-use-resource-view",
|
|
1149
|
+
"file": "src/routes/board.tsx",
|
|
1150
|
+
"buildsOn": "useBoardColumns",
|
|
1151
|
+
"reason": "The board groups rows by a computed lane, which the view's board block can't express yet.",
|
|
1152
|
+
"upstream": "https://github.com/marktiderman/genesis/issues/123"
|
|
1153
|
+
}
|
|
1154
|
+
]
|
|
1155
|
+
}
|
|
1156
|
+
}
|
|
1116
1157
|
```
|
|
1117
1158
|
|
|
1159
|
+
`allow` is debt and only shrinks. An extension is a reviewed decision, and it is bounded:
|
|
1160
|
+
|
|
1161
|
+
- **By the rule.** Only package rules can be extended, and only at the points they declare
|
|
1162
|
+
(`ui/lists-use-resource-view`: `ResourceView.slots`, `ResourceView.renderDetail`,
|
|
1163
|
+
`ResourceView.toolbar`, `useResourceView`, `useResourceTable`, `useBoardColumns`;
|
|
1164
|
+
`ui/records-use-record-view`: `BuilderLayout`). A built-in rule (`deprecated-import`,
|
|
1165
|
+
`removed-scope-name`, `raw-tag`, …) or a package rule without points can't be, so debt can't be
|
|
1166
|
+
renamed an extension.
|
|
1167
|
+
- **By the file, now.** It names one file (no globs) and covers the findings of its rule that the
|
|
1168
|
+
file has when the extension is declared. Under `--base`, once the merge base has the extension,
|
|
1169
|
+
a file with more of them than at the merge base reports them all at their level, as the ratchet
|
|
1170
|
+
would.
|
|
1171
|
+
- **By review.** `allow-grew` and `rules-weakened` don't count it. Under `--base` a new one is an
|
|
1172
|
+
`extension-added` info, and the report's summary lists every extension the branch adds with its
|
|
1173
|
+
reason ("Extensions added on this branch"; `extensionsAdded` in `--json`). The pull request's
|
|
1174
|
+
review is where it is accepted; nothing else gates it.
|
|
1175
|
+
|
|
1176
|
+
The doctor checks each one:
|
|
1177
|
+
|
|
1178
|
+
- `reason` is required, at least six words and 40 characters: why the rule's primitive doesn't
|
|
1179
|
+
fit this file. `upstream` links the gap's write-up for Genesis, when it is one.
|
|
1180
|
+
- `extension-invalid` (error, can't be lowered or allowed): the rule declares no extension points
|
|
1181
|
+
or `buildsOn` isn't one of them, the file doesn't import `buildsOn` from a Genesis package or
|
|
1182
|
+
doesn't use it (render or call it; for `X.slots` and the like, pass that prop on `<X>`),
|
|
1183
|
+
`buildsOn` is what a package rule replaces (`DataTable`, `DetailPage`), or the doctor flags it in
|
|
1184
|
+
that file (a deprecated import). The findings it would cover stay.
|
|
1185
|
+
- `stale-extension` (warn): the file no longer has a finding of `rule`; remove the entry.
|
|
1186
|
+
|
|
1118
1187
|
### Config
|
|
1119
1188
|
|
|
1120
1189
|
`genesis.config.json` (or `"genesis": { "doctor": { … } }` in package.json):
|
|
@@ -1143,9 +1212,9 @@ genesis doctor --strict --base origin/main
|
|
|
1143
1212
|
| --- | --- | --- |
|
|
1144
1213
|
| `packs` | | Opt-in rule packs: `"native"`, `"supabase"`. See [Rule packs](#rule-packs). |
|
|
1145
1214
|
| `native` | | `{ routerRoot }` for the native pack. |
|
|
1146
|
-
| `supabase` | | `{ migrations, base, exposedSchemas, since }` for the supabase pack. |
|
|
1215
|
+
| `supabase` | | `{ migrations, base, exposedSchemas, since, automaticBranching }` for the supabase pack. |
|
|
1147
1216
|
| `src` | `["src"]` (`["app", "src", "components"]` with the native pack) | Folders (or files) to scan. |
|
|
1148
|
-
| `extensions` | `.ts .tsx .js .jsx .mts .cts .css` | |
|
|
1217
|
+
| `extensions` | `.ts .tsx .js .jsx .mts .cts .css` | File extensions to scan (declared extensions are `extend`). |
|
|
1149
1218
|
| `ignore` | | Globs to skip, added to the defaults. `*` stays in a folder, `**` crosses folders, a trailing `/` means the whole folder. |
|
|
1150
1219
|
| `uiPackage` | `@marktiderman/genesis-ui` (`@marktiderman/genesis-ui-native` with the native pack) | |
|
|
1151
1220
|
| `themeCss` | the design system's `dist/themes/*.css` + genesis-ui's styles | One stylesheet or a list: package paths (`@marktiderman/genesis-design-system/dist/themes/genesis.css`) or app paths. |
|
|
@@ -1160,7 +1229,8 @@ genesis doctor --strict --base origin/main
|
|
|
1160
1229
|
| `packageRules` | | `{ "<package>/<rule>": { level?, files?, exclude?, reason } }` for the rules packages declare. `reason` is required. `files` and `exclude` apply to `prefer` rules; a package plugin decides its own files, so only `level` applies to its rules. See [Package rules](#package-rules). |
|
|
1161
1230
|
| `ratchet` | | `true`, or a list of rule ids, ratcheted under `--base`. See [The ratchet](#the-ratchet). |
|
|
1162
1231
|
| `contracts` | | `{ out?, schemas?, databaseEnv? }`: the supabase pack's `contracts-stale` check. Needs the supabase pack. |
|
|
1163
|
-
| `allow` | | Exceptions: `{ rule, file?, match?, reason }`. `match` is the exact tag, token, export name or import specifier. `reason` is required. |
|
|
1232
|
+
| `allow` | | Exceptions: `{ rule, file?, match?, reason }`. `match` is the exact tag, token, export name or import specifier. `reason` is required. Debt: under `--base` it only shrinks. |
|
|
1233
|
+
| `extend` | | Declared extensions: `{ rule, file, buildsOn, reason, upstream? }`, at a package rule's declared extension points, bounded by the findings the file had when declared. See [Declared extensions](#declared-extensions). |
|
|
1164
1234
|
| `patterns` | | Declarative rules, below. |
|
|
1165
1235
|
| `rulesDoc` | | A markdown file of declarative rules, below. |
|
|
1166
1236
|
| `plugins` | | Rule modules, below. |
|
|
@@ -1253,6 +1323,46 @@ if (!result.ok) throw new Error(formatReport(result));
|
|
|
1253
1323
|
the local Vite plugin import with `@marktiderman/genesis-cli/vite`.
|
|
1254
1324
|
4. Run `genesis doctor`, fix or `allow` what it reports (it checks `raw-color` in code as well
|
|
1255
1325
|
as CSS, and `raw-tag` only in JSX files), then delete the old script.
|
|
1326
|
+
|
|
1327
|
+
## genesis agents
|
|
1328
|
+
|
|
1329
|
+
Writes the agent guide from the installed Genesis packages, so every coding agent and reviewer in
|
|
1330
|
+
the app reads the same rules, matched to the versions the app has:
|
|
1331
|
+
|
|
1332
|
+
- **The AGENTS.md block** between `<!-- genesis-primitives:start -->` and
|
|
1333
|
+
`<!-- genesis-primitives:end -->`: the rules, the catalog of what to use for each need, and the
|
|
1334
|
+
path to each installed package's own `SKILL.md` at `node_modules/<package>/SKILL.md`, so it
|
|
1335
|
+
matches the installed version (a package reached only through the umbrella, inside pnpm's store,
|
|
1336
|
+
is left out: that path changes with unrelated dependency bumps). Text outside the markers is the
|
|
1337
|
+
app's own and is never touched.
|
|
1338
|
+
- **`.claude/skills/genesis/SKILL.md`**: the same rules and catalog as a skill.
|
|
1339
|
+
- **`CLAUDE.md`** holding `@AGENTS.md`, only when the app has no `CLAUDE.md`. Reviewers and cloud
|
|
1340
|
+
project threads read CLAUDE.md, not AGENTS.md.
|
|
1341
|
+
|
|
1342
|
+
`genesis agents --hooks` also writes two things into `.claude/settings.json`, keeping everything
|
|
1343
|
+
else there: a `SubagentStart` hook that hands Claude Code's Explore and Plan subagents the same
|
|
1344
|
+
rules and package guides (they start without CLAUDE.md or AGENTS.md), and `permissions.deny`
|
|
1345
|
+
rules for `.env` files, which apply in cloud sessions too. The hook runs
|
|
1346
|
+
`genesis agents --hook subagent-start`, which prints the rules and guides and never fails a
|
|
1347
|
+
session: with no local `genesis` binary (before an install), the subagent simply starts without
|
|
1348
|
+
them. Settings are written only with `--hooks`, so a plain run never touches them; an older hook
|
|
1349
|
+
command is flagged instead (below), and `genesis agents --hooks` updates it.
|
|
1350
|
+
|
|
1351
|
+
Package guides are listed only at paths that stay put: a local package's folder, or
|
|
1352
|
+
`node_modules/<package>/SKILL.md` at the app or a workspace folder above it, up to the repo root,
|
|
1353
|
+
and only when that copy is the one the app resolved.
|
|
1354
|
+
A package reached only through the umbrella lives in pnpm's store, so its guide is left out, and
|
|
1355
|
+
the doctor names it (an info): add the package as a direct dependency to list its guide.
|
|
1356
|
+
|
|
1357
|
+
`genesis agents --check` writes nothing and exits 1 when any of them is missing or stale (for CI);
|
|
1358
|
+
the doctor's `agent-guide-stale` rule warns the same way, and also for an older hook command
|
|
1359
|
+
(fix it with `--hooks`). A
|
|
1360
|
+
CLAUDE.md the app keeps without the import, or a link to AGENTS.md, passes (the doctor notes a
|
|
1361
|
+
missing import as info). A CLAUDE.md that's blocked, by another case of the name such as
|
|
1362
|
+
`claude.md`, a dangling link or a folder, fails until it's fixed by hand, since `genesis agents`
|
|
1363
|
+
never writes over it. `genesis agents --rules` checks the repo against the agent rules of
|
|
1364
|
+
engagement a script can check. Run `genesis agents` after every Genesis upgrade.
|
|
1365
|
+
|
|
1256
1366
|
## genesis figma:routes
|
|
1257
1367
|
|
|
1258
1368
|
A read-only check that an app's Figma app file covers its routes, so CI reports the drift and an
|