@skyf0xx/hedgehog-core-full-stack-app 1.0.12 → 1.0.14

package/agents/backend-eng.md

@@ -32,9 +32,9 @@ build exactly what its ALLOWED SCOPE names, one layer at a time, gated by
 - **PostgreSQL** via Docker Compose — never a natively-installed Postgres.
 
 Use `nx-run-tasks` (build/lint/test/typecheck), `nx-workspace` (inspecting
-project/target config), `nx-generate` (scaffolding a new library/app), and
-`link-workspace-packages` (wiring a new package into a consumer) as
-needed.
+project/target config), `nx-generate` (running the packet's
+`tools/generators:<layer>` command), and `link-workspace-packages`
+(wiring a new package into a consumer) as needed.
 
 **Every layer you own starts from its generator in `tools/generators/`** —
 one per layer (`schema`, `contract`, `repository`, `service`,

package/agents/front-end-eng.md

@@ -30,9 +30,9 @@ before the next starts.
   routes directly.
 
 Use `nx-run-tasks` (build/lint/test/typecheck), `nx-workspace` (inspecting
-project/target config), `nx-generate` (scaffolding a new library/app), and
-`link-workspace-packages` (wiring a new package into a consumer) as
-needed.
+project/target config), `nx-generate` (running the packet's
+`tools/generators:<layer>` command), and `link-workspace-packages`
+(wiring a new package into a consumer) as needed.
 
 **Both layers you own start from their generator in `tools/generators/`** —
 `hook` lands `packages/hooks`'s shell, `nx.tags`, the query hook set, and

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@skyf0xx/hedgehog-core-full-stack-app",
-  "version": "1.0.12",
+  "version": "1.0.14",
   "description": "Hedgehog's full-stack-app core: an Nx/pnpm/NestJS/Next.js workspace, backend-first domain module build discipline, and the agents and skills that drive it.",
   "type": "module",
   "scripts": {

package/skills/hedgehog-bootstrap/SKILL.md

@@ -163,9 +163,14 @@ write — same treatment as an out-of-scope `apps/mobile`.
 
 ```bash
 npx nx g @nx/js:lib packages/auth --bundler=none --unitTestRunner=vitest
-pnpm add better-auth @thallesp/nestjs-better-auth
 ```
 
+`better-auth` and `@thallesp/nestjs-better-auth` are already declared in
+root `package.json` and resolved by `pnpm-lock.yaml` — the core ships
+them, so there is nothing to install here. Don't run `pnpm add` for
+either: an add resolves against npm at whatever is latest today, which
+is the drift this core pins them to avoid.
+
 Configure the Drizzle adapter against `packages/db`. Add
 `BETTER_AUTH_SECRET: z.string().min(32)` to `packages/config/env.schema.ts`
 now (it doesn't exist in the core schema `hedgehog-bootstrap-full-stack-app-core`
@@ -175,9 +180,10 @@ line reproduces the exact `loadEnv()` crash-on-boot that
 `hedgehog-bootstrap-full-stack-app-core`'s `DATABASE_URL` entry exists to prevent, just
 for this var instead. Tag: `scope:auth`, `type:adapter`.
 
-Also wire the global auth guard on `apps/api`: `pnpm add
-@thallesp/nestjs-better-auth` there too and register the guard
-(secure-by-default) against `packages/auth`. `apps/api`'s
+Also wire the global auth guard on `apps/api`: register the guard
+(secure-by-default) against `packages/auth` — the root declaration
+already resolves `@thallesp/nestjs-better-auth` for every project in the
+workspace, so `apps/api` needs no add of its own. `apps/api`'s
 `depConstraints` entry needs `scope:auth` added to its allowed
 dependencies now — the one deliberate exception to "api reaches things
 only through ports," since auth is cross-cutting infra, not a domain
@@ -195,9 +201,12 @@ skipped, say so plainly and move on — same treatment as an out-of-scope
 
 ```bash
 npx nx g @nx/node:app apps/worker
-pnpm add bullmq ioredis
 ```
 
+`bullmq` and `ioredis` are already declared in root `package.json` and
+resolved by `pnpm-lock.yaml` — same as Auth's packages above. Nothing to
+install here; don't run `pnpm add` for either.
+
 Add a `redis` service to the root `docker-compose.yml` that
 `hedgehog-bootstrap-full-stack-app-core` landed (Postgres-only) and
 `REDIS_URL: z.string().url()` to `packages/config/env.schema.ts` (it
@@ -235,12 +244,49 @@ Skip this step entirely if Mobile isn't on for this project (check
 say so plainly and move on — same pattern as Auth (step 1) and Queue
 (step 2) when their add-on is off.
 
+Mobile's packages are pinned in `addon-versions.json` at the workspace
+root, not named inline here and not declared in root `package.json` —
+Expo pulls a native build matrix that has no business in a project that
+never scaffolds `apps/mobile`. Read every version from that file rather
+than typing one, so this step installs what the core was last gated
+against:
+
 ```bash
+NX_EXPO=$(node -p "require('./addon-versions.json').mobile['@nx/expo']")
+NATIVEWIND=$(node -p "require('./addon-versions.json').mobile.nativewind")
+RNR=$(node -p "require('./addon-versions.json').mobile['@react-native-reusables/cli']")
+
+pnpm add -w -D "@nx/expo@$NX_EXPO"
+pnpm add -w "nativewind@$NATIVEWIND"
+
 npx nx g @nx/expo:app apps/mobile --unitTestRunner=jest
-npx @react-native-reusables/cli@latest init
-npx @react-native-reusables/cli@latest add button text
+
+npx "@react-native-reusables/cli@$RNR" init
+npx "@react-native-reusables/cli@$RNR" add button text
 ```
 
+`-w` is required: this is a pnpm workspace, and an add without it fails
+with `ERR_PNPM_ADDING_TO_ROOT` rather than installing.
+
+`@nx/expo:app` generates `apps/mobile/src/test-setup.ts` with an untyped
+`defineGlobal` helper, which is a `TS7006` error under the core's
+`strict: true` base tsconfig — `mobile:typecheck` fails on a fresh
+scaffold until it is annotated:
+
+```ts
+const defineGlobal = (name: string, value: unknown) => {
+```
+
+Make that edit before the step's commit. `nx-migrate.yml`'s add-on gate
+applies the same annotation, so the day `@nx/expo` ships the types both
+stop being needed together.
+
+`@nx/expo`'s pin is byte-identical to every other `@nx/*` entry in root
+`package.json` — Nx requires its plugin matrix to be version-identical,
+and a mismatch fails at generator time with a resolution error rather
+than at install. If the pin and the `@nx/*` entries have drifted apart,
+stop and fix `addon-versions.json` rather than installing anyway.
+
 `@nx/expo:app`'s own default for `--unitTestRunner` is `none` — pass it
 explicitly, or `apps/mobile` has no `test` target at all and the `screen`
 layer's verify command below fails on a missing target rather than a
@@ -253,7 +299,7 @@ NativeWind and the `@/*` path alias into `apps/mobile/tsconfig.json`
 named components' source into `apps/mobile/src/components/ui/`. `button`
 and `text` are the two the `screen` generator's mobile output imports —
 add any further components `front-end-eng` needs the same way, per
-module, as it builds.
+module, as it builds, at the same pinned CLI version.
 
 Edit `init`'s generated theme (`tailwind.config.js` colors, light/dark)
 to match `apps/web`'s base theme (landed by
@@ -355,6 +401,19 @@ time via `hedgehog next`/`hedgehog verify`, each its own commit.
   (written by `planner` at planning intake) turns that add-on on — say so
   plainly and skip otherwise, don't leave it ambiguous whether the step
   was considered.
+- A skipped Auth or Queue step leaves that add-on's packages declared but
+  unused, since the core ships them in root `package.json`. Delete the
+  skipped add-on's entries (`better-auth` and
+  `@thallesp/nestjs-better-auth` for Auth; `bullmq` and `ioredis` for
+  Queue) and re-run `pnpm install` so the lockfile drops them. Do this in
+  the same commit that records the skip. Mobile needs nothing — its
+  packages were never in the install to begin with.
+- Never write a version number into a command in this file. Auth and
+  Queue versions come from root `package.json`; Mobile's come from
+  `addon-versions.json`. A version typed into a step is invisible to
+  `nx migrate`, to `pnpm outdated`, and to CI's add-on gate, so it drifts
+  silently in whichever direction the day's npm resolution happens to
+  take it.
 - Don't add domain schema, contracts, or any `libs/<module>/*` content —
   that's Phase A, started after Bootstrap, one module at a time.
 - Don't deviate from the package/library choices above, for whichever

package/skills/link-workspace-packages/SKILL.md

@@ -1,33 +1,38 @@
 ---
 name: link-workspace-packages
-description: 'Link workspace packages in the Hedgehog pnpm monorepo. USE WHEN: (1) you just created or generated new packages and need to wire up their dependencies, (2) code imports from a sibling package and needs it added as a dependency, (3) you get resolution errors for workspace packages (@org/*) like "cannot find module", "failed to resolve import", "TS2307", or "cannot resolve". DO NOT patch around with tsconfig paths or manual package.json edits - use pnpm''s workspace commands to fix actual linking.'
+description: 'Link workspace packages in the Hedgehog pnpm monorepo. USE WHEN: (1) you just created or generated new packages and need to wire up their dependencies, (2) code imports from a sibling package and needs it added as a dependency, (3) you get resolution errors for workspace packages like "cannot find module", "failed to resolve import", "TS2307", or "cannot resolve". DO NOT patch around with tsconfig paths or manual package.json edits - use pnpm''s workspace commands to fix actual linking.'
 ---
 
 # Link Workspace Packages
 
+Adapted from Nx's stock workspace-linking skill for this core's own
+package names — plain, unscoped (`db`, `contracts`, `hooks`, `config`,
+plus each module's `libs/<module>/repository` and
+`libs/<module>/service`), not `@org/*`-scoped.
+
 Add dependencies between packages in the workspace using pnpm's `workspace:` protocol — symlinks are only created when a dependency is explicitly declared this way.
 
 ## Workflow
 
-1. Identify consumer package (the one importing)
-2. Identify provider package(s) (being imported)
+1. Identify consumer package (the one importing) — e.g. `apps/api`
+2. Identify provider package(s) (being imported) — e.g. a module's `libs/<module>/service`
 3. Add the dependency:
 
    ```bash
    # From consumer directory
-   pnpm add @org/ui --workspace
+   pnpm add <module>-service --workspace
 
    # Or with --filter from anywhere
-   pnpm add @org/ui --filter @org/app --workspace
+   pnpm add <module>-service --filter api --workspace
    ```
 
    Result in `package.json`:
 
    ```json
-   { "dependencies": { "@org/ui": "workspace:*" } }
+   { "dependencies": { "<module>-service": "workspace:*" } }
    ```
 
-4. Verify the symlink was created in the consumer's `node_modules/@org/<package>`
+4. Verify the symlink was created in the consumer's `node_modules/<package>`
 
 ## Debugging "Cannot find module"
 

package/skills/nx-generate/SKILL.md

@@ -1,165 +1,73 @@
 ---
 name: nx-generate
-description: Generate code using nx generators. INVOKE IMMEDIATELY when user mentions scaffolding, setup, structure, creating apps/libs, or setting up project structure. Trigger words - scaffold, setup, create a new app, create a new lib, project structure, generate, add a new project. ALWAYS use this BEFORE calling nx_docs or exploring - this skill handles discovery internally.
-subagent: general-purpose
-context: fork
+description: Run one of this core's own Nx generators to scaffold a domain-module layer. INVOKE when a claimed packet's LAYER SHAPE section names a `tools/generators:<layer>` command to run.
 ---
 
 # Run Nx Generator
 
-Nx generators are powerful tools that scaffold projects, make automated code migrations or automate repetitive tasks in a monorepo. They ensure consistency across the codebase and reduce boilerplate work.
-
-This skill applies when the user wants to:
-
-- Create new projects like libraries or applications
-- Scaffold features or boilerplate code
-- Run workspace-specific or custom generators
-- Do anything else that an nx generator exists for
-
-## Key Principles
-
-1. **Always use `--no-interactive`** - Prevents prompts that would hang execution
-2. **Read the generator source code** - The schema alone is not enough; understand what the generator actually does
-3. **Match existing repo patterns** - Study similar artifacts in the repo and follow their conventions
-4. **Verify with lint/test/build/typecheck etc.** - Generated code must pass verification, using whatever targets are appropriate for this workspace (CI config is a good guide for which ones are critical).
+Adapted from Nx's stock `nx-generate` skill for this core's closed set of
+generators: `tools/generators/` holds exactly one generator per domain
+module layer (`schema`, `contract`, `repository`, `service`, `controller`,
+`hook`, `screen`), and every layer's task packet already names which one
+to run and with what flags — there is no generator discovery or matching
+step here. `hedgehog-loop`'s "Scaffolding a layer" section owns the full
+flag contract; this skill covers only the mechanics of invoking one.
 
 ## Steps
 
-### 1. Discover Available Generators
-
-Use the Nx CLI to discover available generators:
-
-- List all generators for a plugin: `pnpm nx list @nx/react`
-- View available plugins: `pnpm nx list`
-
-This includes plugin generators (e.g., `@nx/react:library`) and local workspace generators.
-
-### 2. Match Generator to User Request
-
-Identify which generator(s) could fulfill the user's needs. Consider what artifact type they want, which framework is relevant, and any specific generator names mentioned.
-
-**IMPORTANT**: When both a local workspace generator and an external plugin generator could satisfy the request, **always prefer the local workspace generator**. Local generators are customized for the specific repo's patterns.
-
-If no suitable generator exists, you can stop using this skill. However, the burden of proof is high—carefully consider all available generators before deciding none apply.
-
-### 3. Get Generator Options
-
-Use the `--help` flag to understand available options:
-
-```bash
-pnpm nx g @nx/react:library --help
-```
-
-Pay attention to required options, defaults that might need overriding, and options relevant to the user's request.
-
-### Library Buildability
-
-**Default to non-buildable libraries** unless there's a specific reason for buildable.
-
-| Type                        | When to use                                                       | Generator flags                     |
-| --------------------------- | ----------------------------------------------------------------- | ----------------------------------- |
-| **Non-buildable** (default) | Internal monorepo libs consumed by apps                           | No `--bundler` flag                 |
-| **Buildable**               | Publishing to npm, cross-repo sharing, stable libs for cache hits | `--bundler=vite` or `--bundler=swc` |
-
-Non-buildable libs:
-
-- Export `.ts`/`.tsx` source directly
-- Consumer's bundler compiles them
-- Faster dev experience, less config
+### 1. Run the packet's command
 
-Buildable libs:
-
-- Have their own build target
-- Useful for stable libs that rarely change (cache hits)
-- Required for npm publishing
-
-**If unclear, ask the user:** "Should this library be buildable (own build step, better caching) or non-buildable (source consumed directly, simpler setup)?"
-
-### 4. Read Generator Source Code
-
-**This step is critical.** The schema alone does not tell you everything. Reading the source code helps you:
-
-- Know exactly what files will be created/modified and where
-- Understand side effects (updating configs, installing deps, etc.)
-- Identify behaviors and options not obvious from the schema
-- Understand how options interact with each other
-
-To find generator source code:
-
-- For plugin generators: Use `node -e "console.log(require.resolve('@nx/<plugin>/generators.json'));"` to find the generators.json, then locate the source from there
-- If that fails, read directly from `node_modules/<plugin>/generators.json`
-- For local generators: Typically in `tools/generators/` or a local plugin directory. Search the repo for the generator name.
-
-After reading the source, reconsider: Is this the right generator? If not, go back to step 2.
-
-> **⚠️ `--directory` flag behavior can be misleading.**
-> It should specify the full path of the generated library or component, not the parent path that it will be generated in.
->
-> ```bash
-> # ✅ Correct - directory is the full path for the library
-> nx g @nx/react:library --directory=libs/my-lib
-> # generates libs/my-lib/package.json and more
->
-> # ❌ Wrong - this will create files at libs and libs/src/...
-> nx g @nx/react:library --name=my-lib --directory=libs
-> # generates libs/package.json and more
-> ```
-
-### 5. Examine Existing Patterns
-
-Before generating, examine the target area of the codebase:
-
-- Look at similar existing artifacts (other libraries, applications, etc.)
-- Identify naming conventions, file structures, and configuration patterns
-- Note which test runners, build tools, and linters are used
-- Configure the generator to match these patterns
-
-### 6. Dry-Run to Verify File Placement
-
-**Always run with `--dry-run` first** to verify files will be created in the correct location:
+The claimed packet's LAYER SHAPE section prints the exact command,
+already filled in with `--module` and `--fields`. Run it as given:
 
 ```bash
-pnpm nx g @nx/react:library --name=my-lib --dry-run --no-interactive
+nx g ./tools/generators:<layer> --module=<module> [--fields='<name:type,...>'] [--toggleField=<boolField>]
 ```
 
-Review the output carefully. If files would be created in the wrong location, adjust your options based on what you learned from the generator source code.
+Always pass `--no-interactive` if the command is going to run
+unattended and might otherwise prompt.
 
-Note: Some generators don't support dry-run (e.g., if they install npm packages). If dry-run fails for this reason, proceed to running the generator for real.
-
-### 7. Run the Generator
-
-Execute the generator:
+### 2. Dry-run first when the placement is unfamiliar
 
 ```bash
-pnpm nx generate <generator-name> <options> --no-interactive
+nx g ./tools/generators:<layer> --module=<module> --dry-run --no-interactive
 ```
 
-> **Tip:** New packages often need workspace dependencies wired up (e.g., importing shared types, being consumed by apps). The `link-workspace-packages` skill can help add these correctly.
+Most of the time the generator's target paths are already well
+understood (they're fixed by layer, per `hedgehog-loop`), so this step is
+optional — reach for it when something about the module name or flags is
+unusual enough to want to see the file list before it lands.
 
-### 8. Modify Generated Code (If Needed)
+### 3. Read the generator source if a flag's effect is unclear
 
-Generators provide a starting point. Modify the output as needed to:
+The generator's own source lives in `tools/generators/<layer>/generator.ts`
+next to its `schema.json`. Read it before guessing at what a flag does —
+the schema alone doesn't show side effects (barrel wiring, tag
+assignment, module registration).
 
-- Add or modify functionality as requested
-- Adjust imports, exports, or configurations
-- Integrate with existing code patterns
+### 4. Author the entity-specific delta
 
-**Important:** If you replace or delete generated test files (e.g., `*.spec.ts`), either write meaningful replacement tests or remove the `test` target from the project configuration. Empty test suites will cause `nx test` to fail.
+The generator lands the layer's skeleton — package shell, `nx.tags`,
+port-discipline file suffixes, barrel wiring, and (for `screen`)
+placeholder sections. It does not write the module's field-specific
+logic, business rules, or UX. Author that on top, per the packet's
+INTENT and RELEVANT RULES.
 
-### 9. Format and Verify
+**Important:** if a generated test file needs replacing rather than
+extending, write a meaningful replacement — an empty test suite fails
+`nx test`.
 
-Format all generated/modified files:
+### 5. Wire the new package into the workspace
 
-```bash
-pnpm nx format --fix
-```
-
-This example is for built-in nx formatting with prettier. There might be other formatting tools for this workspace, use these when appropriate.
-
-Then verify the generated code works. Keep in mind that the changes you make with a generator or subsequent modifications might impact various projects so it's usually not enough to only run targets for the artifact you just created.
+A layer that's the first arrival in its package needs
+`pnpm install && pnpm nx sync` before verify can see it — see
+`hedgehog-loop`'s "First arrival in a package" for which layers this
+applies to and the override that widens scope for it. The
+`link-workspace-packages` skill covers adding a dependency between two
+existing packages.
 
-```bash
-pnpm nx run-many -t build,lint,test,typecheck
-```
+### 6. Verify
 
-If verification fails with manageable issues (a few lint errors, minor type issues), fix them. If issues are extensive, attempt obvious fixes first, then escalate to the user with details about what was generated, what's failing, and what you've attempted.
+Run whatever the packet's VERIFICATION command specifies. `nx-run-tasks`
+covers running build/lint/test/typecheck directly if you need to check
+something the packet's own command doesn't cover.

package/skills/nx-run-tasks/SKILL.md

@@ -3,6 +3,11 @@ name: nx-run-tasks
 description: Helps with running tasks in an Nx workspace. USE WHEN the user wants to execute build, test, lint, serve, or run any other tasks defined in the workspace.
 ---
 
+Adapted from Nx's stock task-running skill for this workspace's own
+targets (`build`, `lint`, `test`, `typecheck`, `serve`) and projects
+(`api`, `web`, `mobile` when the Mobile add-on is on, plus each domain
+module's `libs/<module>/*`).
+
 Run tasks via `pnpm nx` (see the `nx-workspace` skill for the pnpm-only convention and for checking which targets a project has before running one).
 
 For more details on any command, run it with `--help` (e.g. `pnpm nx run-many --help`, `pnpm nx affected --help`).
@@ -13,7 +18,7 @@ For more details on any command, run it with `--help` (e.g. `pnpm nx run-many --
 pnpm nx run <project>:<task>
 ```
 
-where `project` is the project name defined in `package.json` or `project.json` (if present).
+where `project` is the project name defined in `package.json` or `project.json` (if present) — e.g. `pnpm nx run api:test`, `pnpm nx run web:build`.
 
 ## Run multiple tasks
 
@@ -25,9 +30,9 @@ You can pass a `-p` flag to filter to specific projects, otherwise it runs on al
 
 Examples:
 
-- `pnpm nx run-many -t test -p proj1 proj2` — test specific projects
-- `pnpm nx run-many -t test --projects=*-app --exclude=excluded-app` — test projects matching a pattern
-- `pnpm nx run-many -t test --projects=tag:api-*` — test projects by tag
+- `pnpm nx run-many -t test -p api web` — test specific projects
+- `pnpm nx run-many -t test --projects=*-e2e` — test projects matching a pattern
+- `pnpm nx run-many -t test --projects=tag:type:service` — test projects by tag (see `hedgehog-loop`'s "Port discipline" for this core's tag scheme)
 
 ## Run tasks for affected projects