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

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.13",
   "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/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
 

package/skills/nx-workspace/SKILL.md

@@ -5,7 +5,13 @@ description: "Explore and understand Nx workspaces. USE WHEN answering questions
 
 # Nx Workspace Exploration
 
-This skill provides read-only exploration of Nx workspaces. Use it to understand workspace structure, project configuration, available targets, and dependencies.
+Adapted from Nx's stock workspace-exploration skill for this core's own
+project shape: `apps/api`, `apps/web`, `apps/mobile` (Mobile add-on only),
+and per-module `libs/<module>/repository`, `libs/<module>/service`
+alongside the shared `packages/db`, `packages/contracts`, `packages/hooks`,
+`packages/config`. This skill provides read-only exploration; it never
+generates or modifies anything — see `nx-generate` for scaffolding a
+layer and `nx-run-tasks` for running build/lint/test/typecheck.
 
 Run all commands via `pnpm nx` (Hedgehog workspaces are pnpm-only).
 
@@ -21,11 +27,12 @@ pnpm nx show projects
 
 # Filter by pattern (glob)
 pnpm nx show projects --projects "apps/*"
-pnpm nx show projects --projects "shared-*"
+pnpm nx show projects --projects "packages/*"
 
-# Filter by tag
-pnpm nx show projects --projects "tag:publishable"
-pnpm nx show projects -p 'tag:publishable,!tag:internal'
+# Filter by tag (see `hedgehog-loop`'s "Port discipline" for this core's
+# type:service/type:adapter tag scheme)
+pnpm nx show projects --projects "tag:type:service"
+pnpm nx show projects -p 'tag:type:service,!tag:type:adapter'
 
 # Filter by target (projects that have a specific target)
 pnpm nx show projects --withTarget build
@@ -53,15 +60,15 @@ You can read the full project schema at `node_modules/nx/schemas/project-schema.
 
 ```bash
 # Get full project configuration
-pnpm nx show project my-app --json
+pnpm nx show project web --json
 
 # Extract specific parts from the JSON
-pnpm nx show project my-app --json | jq '.targets'
-pnpm nx show project my-app --json | jq '.targets.build'
-pnpm nx show project my-app --json | jq '.targets | keys'
+pnpm nx show project web --json | jq '.targets'
+pnpm nx show project web --json | jq '.targets.build'
+pnpm nx show project web --json | jq '.targets | keys'
 
 # Check project metadata
-pnpm nx show project my-app --json | jq '{name, root, sourceRoot, projectType, tags}'
+pnpm nx show project web --json | jq '{name, root, sourceRoot, projectType, tags}'
 ```
 
 ## Target Information
@@ -70,21 +77,21 @@ Targets define what tasks can be run on a project.
 
 ```bash
 # List all targets for a project
-pnpm nx show project my-app --json | jq '.targets | keys'
+pnpm nx show project web --json | jq '.targets | keys'
 
 # Get full target configuration
-pnpm nx show project my-app --json | jq '.targets.build'
+pnpm nx show project web --json | jq '.targets.build'
 
 # Check target executor/command
-pnpm nx show project my-app --json | jq '.targets.build.executor'
-pnpm nx show project my-app --json | jq '.targets.build.command'
+pnpm nx show project web --json | jq '.targets.build.executor'
+pnpm nx show project web --json | jq '.targets.build.command'
 
 # View target options
-pnpm nx show project my-app --json | jq '.targets.build.options'
+pnpm nx show project web --json | jq '.targets.build.options'
 
 # Check target inputs/outputs (for caching)
-pnpm nx show project my-app --json | jq '.targets.build.inputs'
-pnpm nx show project my-app --json | jq '.targets.build.outputs'
+pnpm nx show project web --json | jq '.targets.build.inputs'
+pnpm nx show project web --json | jq '.targets.build.outputs'
 
 # Find projects with a specific target
 pnpm nx show projects --withTarget serve
@@ -130,7 +137,7 @@ pnpm nx show projects --json
 Example output:
 
 ```json
-["my-app", "my-app-e2e", "shared-ui", "shared-utils", "api"]
+["web", "api-e2e", "hooks", "contracts", "api", "orders", "orders-e2e"]
 ```
 
 Common operations:
@@ -140,7 +147,7 @@ Common operations:
 pnpm nx show projects --json | jq 'length'
 
 # Filter by pattern
-pnpm nx show projects --json | jq '.[] | select(startswith("shared-"))'
+pnpm nx show projects --json | jq '.[] | select(endswith("-e2e"))'
 
 # Get affected projects as array
 pnpm nx show projects --affected --json | jq '.'
@@ -149,29 +156,29 @@ pnpm nx show projects --affected --json | jq '.'
 ### Project Details ("How do I build/test/lint project X?")
 
 ```bash
-pnpm nx show project my-app --json
+pnpm nx show project web --json
 ```
 
 Example output:
 
 ```json
 {
-  "root": "apps/my-app",
-  "name": "my-app",
-  "sourceRoot": "apps/my-app/src",
+  "root": "apps/web",
+  "name": "web",
+  "sourceRoot": "apps/web/src",
   "projectType": "application",
   "tags": ["type:app", "scope:client"],
   "targets": {
     "build": {
-      "executor": "@nx/vite:build",
-      "options": { "outputPath": "dist/apps/my-app" }
+      "executor": "@nx/next:build",
+      "options": { "outputPath": "dist/apps/web" }
     },
     "serve": {
-      "executor": "@nx/vite:dev-server",
-      "options": { "buildTarget": "my-app:build" }
+      "executor": "@nx/next:server",
+      "options": { "buildTarget": "web:build" }
     },
     "test": {
-      "executor": "@nx/vite:test",
+      "executor": "@nx/vitest:vitest",
       "options": {}
     }
   },
@@ -183,16 +190,16 @@ Common operations:
 
 ```bash
 # Get target names
-pnpm nx show project my-app --json | jq '.targets | keys'
+pnpm nx show project web --json | jq '.targets | keys'
 
 # Get specific target config
-pnpm nx show project my-app --json | jq '.targets.build'
+pnpm nx show project web --json | jq '.targets.build'
 
 # Get tags
-pnpm nx show project my-app --json | jq '.tags'
+pnpm nx show project web --json | jq '.tags'
 
 # Get project root
-pnpm nx show project my-app --json | jq -r '.root'
+pnpm nx show project web --json | jq -r '.root'
 ```
 
 ### Project Graph ("What depends on library Y?")
@@ -207,22 +214,22 @@ Example output:
 {
   "graph": {
     "nodes": {
-      "my-app": {
-        "name": "my-app",
+      "web": {
+        "name": "web",
         "type": "app",
-        "data": { "root": "apps/my-app", "tags": ["type:app"] }
+        "data": { "root": "apps/web", "tags": ["type:app"] }
       },
-      "shared-ui": {
-        "name": "shared-ui",
+      "hooks": {
+        "name": "hooks",
         "type": "lib",
-        "data": { "root": "libs/shared-ui", "tags": ["type:ui"] }
+        "data": { "root": "packages/hooks", "tags": ["type:hook"] }
       }
     },
     "dependencies": {
-      "my-app": [
-        { "source": "my-app", "target": "shared-ui", "type": "static" }
+      "web": [
+        { "source": "web", "target": "hooks", "type": "static" }
       ],
-      "shared-ui": []
+      "hooks": []
     }
   }
 }
@@ -235,10 +242,10 @@ Common operations:
 pnpm nx graph --print | jq '.graph.nodes | keys'
 
 # Find dependencies of a project
-pnpm nx graph --print | jq '.graph.dependencies["my-app"]'
+pnpm nx graph --print | jq '.graph.dependencies["web"]'
 
 # Find projects that depend on a library
-pnpm nx graph --print | jq '.graph.dependencies | to_entries[] | select(.value[].target == "shared-ui") | .key'
+pnpm nx graph --print | jq '.graph.dependencies | to_entries[] | select(.value[].target == "hooks") | .key'
 ```
 
 ## Troubleshooting