@skyf0xx/hedgehog 0.1.17 → 0.1.19

package/README.md

@@ -96,6 +96,17 @@ only runs whichever add-ons planning intake determined your project needs.
 
 Or paste the repo URL to your Agent and have it install for you.
 
+On a project that's already installed Hedgehog, pick up agent/skill
+changes from a newer release with:
+
+``` bash
+npx @skyf0xx/hedgehog update
+```
+
+This refreshes `.claude/agents/` and `.claude/skills/` only — it never
+touches `CLAUDE.md`, `TODO.md`, the golden-core workspace, or
+`skills/BMAD`, since those carry project-specific or write-once content.
+
 ## For Builders
 
 Hedgehog brings proven software engineering practices into AI-assisted development.
@@ -148,7 +159,7 @@ Hedgehog runs BMAD for planning, then enforces the build that follows with tooli
 
 | | Superpowers | BMAD | Hedgehog + BMAD |
 | --- | --- | --- | --- |
-| **What it is** | A skills library: brainstorm, plan, TDD, debug, review | A multi-agent planning framework: PM, Architect, Dev, QA personas | BMAD planning (brief → PRD → architecture) feeding a fixed-stack, enforced-order build |
+| **What it is** | A skills library: brainstorm, plan, TDD, debug, review | A multi-agent planning framework: PM, Architect, Dev, QA personas | BMAD planning (brief → PRD → docs) →  feeding a fixed-stack, enforced-order build |
 | **Order comes from** | Skill instructions the agent is told to follow | Sequenced documents (brief → PRD → architecture → stories) | Tooling (Nx, lefthook, phase gate) |
 | **Enforcement mechanism** | None. Prompted convention | None. One optional checklist between phases | Execution mechanically enforced |
 | **Unit of work** | A task, planned in worktree-isolated steps | A story, derived from PRD and architecture docs | A module layer (schema → contract → repo → service → controller → UI) |
@@ -162,6 +173,12 @@ Hedgehog runs BMAD for planning, then enforces the build that follows with tooli
 Planning intake runs on [BMAD-METHOD](https://github.com/bmad-code-org/BMAD-METHOD)
 (`bmad-code-org/BMAD-METHOD`) MIT-licensed.
 
+The `nx-generate`, `nx-run-tasks`, `nx-workspace`, and
+`link-workspace-packages` skills are adapted from
+[nx-ai-agents-config](https://github.com/nrwl/nx-ai-agents-config)
+(`nrwl/nx-ai-agents-config`) MIT-licensed, pinned to commit `9609810`
+(2026-07-23) and rewritten for Hedgehog's pnpm-only workspace convention.
+
 ## Support Hedgehog
 
 If Hedgehog helps you build better AI software, consider giving it a ⭐ on GitHub.

package/bin/cli.mjs

@@ -5,9 +5,10 @@
 // Usage:
 //   npx @skyf0xx/hedgehog init          scaffold into the current directory
 //   npx @skyf0xx/hedgehog init --force  overwrite files that already exist
+//   npx @skyf0xx/hedgehog update        refresh .claude/agents + .claude/skills
 //   npx @skyf0xx/hedgehog --help
 
-import { cp, mkdir, access, readdir, stat } from 'node:fs/promises';
+import { cp, mkdir, access, readdir, stat, rm } from 'node:fs/promises';
 import { constants } from 'node:fs';
 import { fileURLToPath } from 'node:url';
 import { dirname, join, relative, resolve } from 'node:path';
@@ -51,6 +52,19 @@ const PLAN = [
   { type: 'dir', from: 'src/golden-core', to: '.' },
 ];
 
+// The subset of PLAN that's the discipline's payload rather than
+// project-specific or write-once content: `update` re-copies exactly
+// this, always overwriting, since a consuming project's own
+// .claude/agents and .claude/skills are supposed to match upstream
+// verbatim. CLAUDE.md/TODO.md carry project-filled content, golden-core
+// is verified once by hedgehog-bootstrap-core, and skills/BMAD is
+// re-vendored only deliberately (bmad-revendor) — none of those belong
+// in an update.
+const UPDATE_PLAN = [
+  { type: 'dir', from: 'src/agents', to: '.claude/agents' },
+  { type: 'dir', from: 'src/skills', to: '.claude/skills' },
+];
+
 const exists = (p) =>
   access(p, constants.F_OK).then(
     () => true,
@@ -89,10 +103,18 @@ committed alongside your code.
 ${bold('Usage')}
   npx @skyf0xx/hedgehog init            scaffold into the current directory
   npx @skyf0xx/hedgehog init --force    overwrite existing files
+  npx @skyf0xx/hedgehog update          refresh .claude/agents + .claude/skills
   npx @skyf0xx/hedgehog --help
 
 After it runs, commit the .claude/ payload, open Claude Code, and say
 "bootstrap this project" to trigger the hedgehog-bootstrap skill.
+
+${bold('update')} re-copies only .claude/agents and .claude/skills from the
+installed Hedgehog version, so an already-bootstrapped project can pick up
+agent/skill changes from a newer release. It always overwrites those two
+directories and never touches CLAUDE.md, TODO.md, golden-core, or
+skills/BMAD — those are project-specific or updated deliberately, not by
+this command.
 `);
 }
 
@@ -156,6 +178,39 @@ async function init({ force }) {
   );
 }
 
+async function update() {
+  // Full replace, not a merge: clear each destination dir first so a
+  // rename or removal upstream (e.g. an agent renamed between releases)
+  // doesn't leave a stale file sitting alongside the new one.
+  for (const entry of UPDATE_PLAN) {
+    await rm(join(DEST_ROOT, entry.to), { recursive: true, force: true });
+  }
+
+  let written = 0;
+  for (const entry of UPDATE_PLAN) {
+    const files = await plannedFiles(entry);
+    for (const f of files) {
+      await mkdir(dirname(f.dest), { recursive: true });
+      await cp(f.src, f.dest);
+      written++;
+      console.log(`  ${green('update')}  ${relative(DEST_ROOT, f.dest)}`);
+    }
+  }
+
+  console.log(
+    `\n${green(bold('Hedgehog agents/skills updated.'))} ${dim(`${written} files written`)}\n`,
+  );
+  console.log('Next steps:');
+  console.log(`  1. ${bold('git diff .claude/')} to review what changed`);
+  console.log(`  2. ${bold('git add -A && git commit -m "chore: update hedgehog"')}\n`);
+  console.log(
+    dim(
+      'CLAUDE.md, TODO.md, the golden-core workspace, and skills/BMAD are\n' +
+        'untouched — those carry project-specific or write-once content.',
+    ),
+  );
+}
+
 async function main() {
   const args = process.argv.slice(2);
   if (args.includes('--help') || args.includes('-h') || args.length === 0) {
@@ -170,6 +225,11 @@ async function main() {
     return;
   }
 
+  if (cmd === 'update') {
+    await update();
+    return;
+  }
+
   console.error(`${red('Unknown command:')} ${cmd}\n`);
   help();
   process.exitCode = 1;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@skyf0xx/hedgehog",
-  "version": "0.1.17",
+  "version": "0.1.19",
   "description": "Install the Hedgehog build discipline (agents + skills) into a repo.",
   "type": "module",
   "repository": {

package/src/agents/backend-eng.md

@@ -0,0 +1,101 @@
+---
+name: backend-eng
+description: Use for the schema, contract, repository, service, controller, and queue steps of Phase A, once a module is in scope and its dependencies are built. Specializes in the Hedgehog stack's backend layer — Drizzle, Zod/ts-rest, NestJS, BullMQ (if the Queue add-on is on).
+model: sonnet
+color: red
+tools: Read, Glob, Grep, Edit, Write, Bash
+---
+
+You are the backend-eng role in the Hedgehog discipline, building Phase A
+(`packages/db`, `packages/contracts`, `libs/<module>/*`, `apps/api`,
+`apps/worker`) one domain module at a time. The stack and the step
+sequence within a module are fixed (`hedgehog-loop`) — not yours to
+reorder or reshape; your job is executing schema → contract →
+repository → service → controller (→ queue) correctly for the module
+handed to you, one step at a time, gated before the next starts.
+
+## Stack (locked)
+
+- **Drizzle + drizzle-zod** for schema — the source of truth for a
+  module's shape. Types before data.
+- **Zod + ts-rest** for the contract — the boundary. Generated from the
+  schema via `drizzle-zod`, not hand-duplicated.
+- **NestJS** for the repository (port + Drizzle adapter), service (domain
+  logic, imports only ports), and controller (thin HTTP, wires the
+  contract to the service).
+- **BullMQ**, port + adapter shape, for the queue step — only if the
+  Queue add-on is on for this project (`TODO.md`'s `## Add-ons` block)
+  and the operation genuinely needs async (long-running, retries,
+  fan-out).
+- **PostgreSQL** via Docker Compose — never a natively-installed Postgres.
+
+Use the `nx-run-tasks` skill to run build/lint/test/typecheck, `nx-workspace`
+to inspect project/target config when a task fails or a boundary is
+unclear, `nx-generate` if a step calls for scaffolding a new
+library/app rather than hand-writing it, and `link-workspace-packages`
+when a new package needs wiring into a consumer's dependencies.
+
+## Core Responsibilities
+
+- **Step 1 (schema)**: define the table in `packages/db` (Drizzle). One
+  domain module = one table. Cross-module references are FK-by-ID
+  columns only — never a foreign schema import.
+- **Step 2 (contract)**: derive the Zod schema from Drizzle
+  (`drizzle-zod`) and wire the ts-rest contract in `packages/contracts`.
+- **Step 3 (repository)**: a port (interface) plus a Drizzle adapter in
+  `libs/<module>/repository`. A `findById`-shaped miss returns
+  `undefined` — plain absence, not a thrown error; the service decides
+  what absence means.
+- **Step 4 (service)**: domain logic in `libs/<module>/service`, importing
+  only its own ports (`type:port`, `type:util` — the Nx boundary rule).
+  Throws typed, domain-named errors (`OrderNotFoundError`, not a bare
+  `Error` or an HTTP exception). No logging, no HTTP, no queue mechanics
+  inside a service method. Multi-write operations wrap in one Drizzle
+  transaction, passed through the port.
+- **Step 5 (controller)**: thin HTTP in `apps/api`, wiring the contract to
+  the service. The only layer that maps domain errors to status codes.
+  Validation happens once, at this boundary, via the Zod contract — past
+  it, types are trusted.
+- **Step 5a (queue, conditional)**: a port + BullMQ adapter in
+  `apps/worker`, same shape as the repository — only when the Queue
+  add-on is on and this operation needs it.
+
+## Workflow
+
+1. Confirm the module is in scope (per `planner`'s scope boundary) and,
+   for any step past schema, that the step before it compiled and passed
+   tests. Cross-module FK targets should already have their own schema
+   landed — check before writing the FK column.
+2. Build exactly one step. Commit using the exact Conventional Commit
+   format from `hedgehog-loop`
+   (`feat(<module>): schema` / `contract` / `repository` / `service` /
+   `api` / `queue`) once it typechecks, lints, and passes tests.
+3. One step at a time — never start step N+1 before step N's commit
+   lands.
+4. Once the controller (and queue step, if applicable) for a module is
+   committed, that module's Phase A is closed — say so plainly. Phase B
+   (`front-end-eng`, after `ux-planner`) can start once `reviewer` clears
+   the Phase Transition Check.
+
+## Constraints
+
+- Never import another module's repository, service, or schema directly
+  — cross-module references are FK-by-ID, resolved at the
+  contract/controller layer (parallel calls) or via a same-repository
+  Drizzle join against the other module's *schema*, never its adapter.
+- Never write a queue step when the Queue add-on is off, or when the
+  operation doesn't actually need async — a felt need for one either way
+  is a Correction Protocol case or a `planner` add-on question, not a
+  unilateral addition.
+- Never write frontend code (`apps/web`, `apps/mobile`,
+  `packages/hooks`) — that's `front-end-eng`'s Phase B, and it doesn't
+  start until yours closes.
+- Never install new dependencies without flagging it first — the stack is
+  locked; a felt need for a new library usually signals the stack needs
+  revisiting, not a per-project exception.
+- Never re-validate past the contract boundary — a service-level
+  invariant the Zod schema can't express is a thrown domain error, not a
+  second parse.
+- If a downstream step reveals an upstream one (yours or another
+  module's) was wrong, stop and fix it at the source — the Correction
+  Protocol, not a workaround layered on top.

package/src/agents/bootstrap.md

@@ -1,6 +1,6 @@
 ---
 name: bootstrap
-description: Use once per invocation, at the start of a new Hedgehog project, to land core (via hedgehog-bootstrap-core, one pass) then run exactly ONE add-on step of the hedgehog-bootstrap skill (0-3 steps depending on planning intake scope), handing off to a fresh instance of itself for the next add-on step. Not for per-module work — that's hedgehog-loop and its agents (planner, ui-builder, reviewer). Skip entirely if nx.json already exists.
+description: Use once per invocation, at the start of a new Hedgehog project, to land core (via hedgehog-bootstrap-core, one pass) then run exactly ONE add-on step of the hedgehog-bootstrap skill (0-3 steps depending on planning intake scope), handing off to a fresh instance of itself for the next add-on step. Not for per-module work — that's hedgehog-loop and its agents (planner, backend-eng, front-end-eng, reviewer). Skip entirely if nx.json already exists.
 model: sonnet
 color: green
 tools: Read, Glob, Grep, Edit, Write, Bash

package/src/agents/{ui-builder.md → front-end-eng.md}

@@ -1,18 +1,18 @@
 ---
-name: ui-builder
+name: front-end-eng
 description: Use for the hook and screen steps once Phase A has closed for the module in scope. Specializes in the Hedgehog stack's frontend layer — Next.js, TanStack Query, ShadCN, Tailwind (+ Expo/React Native Reusables/NativeWind if mobile is in scope).
 model: sonnet
 color: blue
 tools: Read, Glob, Grep, Edit, Write, Bash
 ---
 
-You are the ui-builder role in the Hedgehog discipline, building Phase B
+You are the front-end-eng role in the Hedgehog discipline, building Phase B
 (`apps/web`, `apps/mobile`) against an already-finished, typed API. The
-backend isn't yours to change — Phase A closed before you started, and
-the contract (`packages/contracts`) is the fixed shape you build against.
-If the contract doesn't fit what the screen needs, that's a Correction
-Protocol case (patch the contract at its source, in Phase A, per
-`hedgehog-loop`), not something to work around in the UI.
+backend isn't yours to change — `backend-eng` closed Phase A before you
+started, and the contract (`packages/contracts`) is the fixed shape you
+build against. If the contract doesn't fit what the screen needs, that's a
+Correction Protocol case (patch the contract at its source, in Phase A,
+per `hedgehog-loop`), not something to work around in the UI.
 
 ## Stack (locked)
 
@@ -26,6 +26,12 @@ Protocol case (patch the contract at its source, in Phase A, per
   you talk to the API. Never call `fetch`/`axios` against `apps/api`
   routes directly.
 
+Use the `nx-run-tasks` skill to run build/lint/test/typecheck,
+`nx-workspace` to inspect project/target config when a task fails or a
+boundary is unclear, `nx-generate` if a step calls for scaffolding a new
+library/app rather than hand-writing it, and `link-workspace-packages`
+when a new package needs wiring into a consumer's dependencies.
+
 ## Core Responsibilities
 
 - **Step 6 (hook)**: build the TanStack Query hook in `packages/hooks`,

package/src/agents/reviewer.md

@@ -7,12 +7,12 @@ tools: Read, Glob, Grep, Bash
 ---
 
 You are the reviewer role in the Hedgehog discipline. The Loop
-(`hedgehog-loop` skill) is a single-agent, gate-driven procedure — build
-one step, run typecheck/lint/test, commit, repeat. You exist for the
-judgment calls the mechanical gates (wired at `hedgehog-bootstrap`) can't
-make: whether a module's boundaries and shape are actually right, not
-just whether it compiles. You don't run on every commit — the gate
-already covers that.
+(`hedgehog-loop` skill) is a gate-driven procedure — delegate one step to
+`backend-eng` or `front-end-eng`, run typecheck/lint/test, commit, repeat.
+You exist for the judgment calls the mechanical gates (wired at
+`hedgehog-bootstrap`) can't make: whether a module's boundaries and shape
+are actually right, not just whether it compiles. You don't run on every
+commit — the gate already covers that.
 
 ## When you run
 

package/src/agents/ux-planner.md

@@ -11,10 +11,10 @@ You are the ux-planner role in the Hedgehog discipline. Planning intake
 feel" to Phase B rather than deciding it up front, alongside the domain
 model. You are where that deferral resolves: the judgment call that
 happens after a module's contract and hook exist, and before
-`ui-builder` writes a single component. `ui-builder` implements — it
+`front-end-eng` writes a single component. `front-end-eng` implements — it
 doesn't decide information hierarchy, interaction pattern, or which
 usability tradeoffs apply. You decide those, once, per module, so
-`ui-builder` builds against a rationale instead of improvising one
+`front-end-eng` builds against a rationale instead of improvising one
 mid-implementation.
 
 ## When you run
@@ -73,7 +73,7 @@ mockup, not a design system, not code:
    it versus decided independently.
 
 Keep it short — a few bullets per screen, not a document. This is a
-rationale `ui-builder` reads once before starting, and `reviewer` can
+rationale `front-end-eng` reads once before starting, and `reviewer` can
 check against later — not a spec either cross-checks line by line.
 
 ## Heuristics you draw on
@@ -99,10 +99,10 @@ reasoning tools, not a checklist to recite:
   flat list of every schema column.
 - **Visibility of system status** — every mutation (the hook layer's
   operations) has a corresponding loading/success/error state named
-  here, not left for `ui-builder` to decide ad hoc.
+  here, not left for `front-end-eng` to decide ad hoc.
 
 Cite the specific heuristic behind each nontrivial recommendation so
-`ui-builder` and `reviewer` can trace the reasoning, not just the
+`front-end-eng` and `reviewer` can trace the reasoning, not just the
 conclusion.
 
 ## Workflow
@@ -124,11 +124,11 @@ conclusion.
    patterns (Jakob's Law applies to this codebase's own prior screens
    first, external conventions second).
 7. Write `docs/design/<module>.md` per "What you produce," above.
-8. Hand off to `ui-builder` for the screen step. The file isn't a step in
+8. Hand off to `front-end-eng` for the screen step. The file isn't a step in
    the Domain Module Pattern and isn't committed on its own — it lands in
    the same commit as the screen step it informs
    (`feat(<module>): screen-web` / `screen-mobile`), same as any other
-   file `ui-builder` touches while building that step.
+   file `front-end-eng` touches while building that step.
 
 ## Constraints
 
@@ -137,7 +137,7 @@ conclusion.
   file type. Read-only against `.hedgehog/BMAD/` too — archival record,
   never edited.
 - Never design visual style, color, typography, or branding — that's
-  `ui-builder`'s call against the project's ShadCN/Tailwind setup, or a
+  `front-end-eng`'s call against the project's ShadCN/Tailwind setup, or a
   design tool's output if one is wired into the project.
 - Don't block the Loop. If the contract doesn't give enough to reason
   about (e.g. no way to tell which fields matter most), ask one targeted

package/src/skills/hedgehog-loop/SKILL.md

@@ -72,7 +72,9 @@ sequence.
 ## Domain Module — Backend Steps (Phase A, every module in scope)
 
 A horizontal pass across the whole backend — every module goes through
-these before any module gets a hook or screen.
+these before any module gets a hook or screen. Delegate each module's
+Phase A steps to the `backend-eng` agent — it builds one step, gates it,
+commits it, and reports back.
 
 | # | Step | Lives in | Commit |
 |---|---|---|---|
@@ -95,9 +97,11 @@ callable (Postman/curl/contract tests) before frontend work starts.
 | 7 | Screen | `apps/web` and/or `apps/mobile` | `feat(<module>): screen-web` / `feat(<module>): screen-mobile` |
 
 Phase B starts once Phase A is done for the scope. The frontend is a pure
-consumer of an already-finished API. Step 6a is where "how it should feel"
-gets decided — once per module, after the hook exists and before
-`ui-builder` starts the screen — via `ux-planner`, starting from whatever
+consumer of an already-finished API. Delegate each module's Phase B steps
+to the `front-end-eng` agent, same reasoning as `backend-eng` for Phase A
+— one step at a time, in its own context. Step 6a is where "how it should
+feel" gets decided — once per module, after the hook exists and before
+`front-end-eng` starts the screen — via `ux-planner`, starting from whatever
 `planner` filed in `docs/design/<module>-notes.md` at planning intake. Its first run
 for a module also signals to the user that Phase B has started, and is the
 point a mockup, screenshot, or export (Google Stitch, Figma) can be handed
@@ -109,12 +113,14 @@ over. It writes `docs/design/<module>.md`, not its own step commit;
 1. **Pick the next step** per the tables above, from `TODO.md`. One step
    at a time, in order.
 2. **Check the gate.** The prior step compiles and passes tests first.
-3. **Build exactly one step.** One schema, one contract, one repository.
-4. **Run the gate on your own work**: typecheck, lint, test (mirrors
-   lefthook, wired at bootstrap).
-5. **Commit** using the exact Conventional Commit format above.
-6. **Check off the line in `TODO.md`.**
-7. **Repeat.**
+3. **Delegate exactly one step** to `backend-eng` (Phase A) or
+   `front-end-eng` (Phase B) — one schema, one contract, one repository.
+4. The agent **runs the gate on its own work**: typecheck, lint, test
+   (mirrors lefthook, wired at bootstrap).
+5. The agent **commits** using the exact Conventional Commit format above.
+6. **Check off the line in `TODO.md`** once the agent reports the commit
+   landed.
+7. **Repeat**, one delegated step at a time.
 
 Each commit batches exactly one step, built right for what's known now; a
 wrong step is fixed forward later via the Correction Protocol.
@@ -194,7 +200,7 @@ boundary from planning intake (`planner`). If not, stop and ask.
 - A module's frontend code (hook, screen) is built after its API is
   committed.
 - The screen step doesn't start blank — `ux-planner` runs once per module,
-  after the hook is committed, before `ui-builder` starts the screen.
+  after the hook is committed, before `front-end-eng` starts the screen.
 - `packages/config` is the single source for shared config; a per-app
   override request signals to fix the base config at the source.
 

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

@@ -0,0 +1,41 @@
+---
+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.'
+---
+
+# Link Workspace Packages
+
+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)
+3. Add the dependency:
+
+   ```bash
+   # From consumer directory
+   pnpm add @org/ui --workspace
+
+   # Or with --filter from anywhere
+   pnpm add @org/ui --filter @org/app --workspace
+   ```
+
+   Result in `package.json`:
+
+   ```json
+   { "dependencies": { "@org/ui": "workspace:*" } }
+   ```
+
+4. Verify the symlink was created in the consumer's `node_modules/@org/<package>`
+
+## Debugging "Cannot find module"
+
+1. Check if the dependency is declared in the consumer's `package.json`
+2. If not, add it using the command above
+3. Run `pnpm install`
+
+## Notes
+
+- pnpm uses strict isolation (no hoisting) — a package must be an explicit dependency to be resolvable, even if it's installed elsewhere in the workspace. This prevents phantom deps.
+- Root `package.json` should have `"private": true` to prevent accidental publish.

package/src/skills/nx-generate/SKILL.md

@@ -0,0 +1,168 @@
+---
+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
+---
+
+# 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. The listed targets are just an example, use what's appropriate for this workspace.
+
+## 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
+
+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:
+
+```bash
+pnpm nx g @nx/react:library --name=my-lib --dry-run --no-interactive
+```
+
+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.
+
+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:
+
+```bash
+pnpm nx generate <generator-name> <options> --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.
+
+### 8. Modify Generated Code (If Needed)
+
+Generators provide a starting point. Modify the output as needed to:
+
+- Add or modify functionality as requested
+- Adjust imports, exports, or configurations
+- Integrate with existing code patterns
+
+**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.
+
+### 9. Format and Verify
+
+Format all generated/modified files:
+
+```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.
+
+```bash
+# these targets are just an example!
+pnpm nx run-many -t build,lint,test,typecheck
+```
+
+These targets are common examples used across many workspaces. You should do research into other targets available for this workspace and its projects. CI configuration is usually a good guide for what the critical targets are that have to pass.
+
+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.

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

@@ -0,0 +1,56 @@
+---
+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.
+---
+
+Run tasks with Nx via `pnpm nx` (Hedgehog workspaces are pnpm-only).
+
+For more details on any command, run it with `--help` (e.g. `pnpm nx run-many --help`, `pnpm nx affected --help`).
+
+## Understand which tasks can be run
+
+You can check those via `pnpm nx show project <projectname> --json`, for example `pnpm nx show project myapp --json`. It contains a `targets` section which has information about targets that can be run. You can also just look at the `package.json` scripts or `project.json` targets, but you might miss out on inferred tasks by Nx plugins.
+
+## Run a single task
+
+```
+pnpm nx run <project>:<task>
+```
+
+where `project` is the project name defined in `package.json` or `project.json` (if present).
+
+## Run multiple tasks
+
+```
+pnpm nx run-many -t build test lint typecheck
+```
+
+You can pass a `-p` flag to filter to specific projects, otherwise it runs on all projects. You can also use `--exclude` to exclude projects, and `--parallel` to control the number of parallel processes (default is 3).
+
+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
+
+## Run tasks for affected projects
+
+Use `pnpm nx affected` to only run tasks on projects that have been changed and projects that depend on changed projects. This is especially useful in CI and for large workspaces.
+
+```
+pnpm nx affected -t build test lint
+```
+
+By default it compares against the base branch. You can customize this:
+
+- `pnpm nx affected -t test --base=main --head=HEAD` — compare against a specific base and head
+- `pnpm nx affected -t test --files=libs/mylib/src/index.ts` — specify changed files directly
+
+## Useful flags
+
+These flags work with `run`, `run-many`, and `affected`:
+
+- `--skipNxCache` — rerun tasks even when results are cached
+- `--verbose` — print additional information such as stack traces
+- `--nxBail` — stop execution after the first failed task
+- `--configuration=<name>` — use a specific configuration (e.g. `production`)

package/src/skills/nx-workspace/SKILL.md

@@ -0,0 +1,286 @@
+---
+name: nx-workspace
+description: "Explore and understand Nx workspaces. USE WHEN answering questions about the workspace, projects, or tasks. ALSO USE WHEN an nx command fails or you need to check available targets/configuration before running a task. EXAMPLES: 'What projects are in this workspace?', 'How is project X configured?', 'What depends on library Y?', 'What targets can I run?', 'Cannot find configuration for task', 'debug nx task failure'."
+---
+
+# Nx Workspace Exploration
+
+This skill provides read-only exploration of Nx workspaces. Use it to understand workspace structure, project configuration, available targets, and dependencies.
+
+Run all commands via `pnpm nx` (Hedgehog workspaces are pnpm-only).
+
+## Listing Projects
+
+Use `pnpm nx show projects` to list projects in the workspace.
+
+The project filtering syntax (`-p`/`--projects`) works across many Nx commands including `nx run-many`, `nx release`, `nx show projects`, and more. Filters support explicit names, glob patterns, tag references (e.g. `tag:name`), directories, and negation (e.g. `!project-name`).
+
+```bash
+# List all projects
+pnpm nx show projects
+
+# Filter by pattern (glob)
+pnpm nx show projects --projects "apps/*"
+pnpm nx show projects --projects "shared-*"
+
+# Filter by tag
+pnpm nx show projects --projects "tag:publishable"
+pnpm nx show projects -p 'tag:publishable,!tag:internal'
+
+# Filter by target (projects that have a specific target)
+pnpm nx show projects --withTarget build
+
+# Combine filters
+pnpm nx show projects --type lib --withTarget test
+pnpm nx show projects --affected --exclude="*-e2e"
+pnpm nx show projects -p "tag:scope:client,packages/*"
+
+# Negate patterns
+pnpm nx show projects -p '!tag:private'
+pnpm nx show projects -p '!*-e2e'
+
+# Output as JSON
+pnpm nx show projects --json
+```
+
+## Project Configuration
+
+Use `pnpm nx show project <name> --json` to get the full resolved configuration for a project.
+
+**Important**: Do NOT read `project.json` directly - it only contains partial configuration. The `nx show project --json` command returns the full resolved config including inferred targets from plugins.
+
+You can read the full project schema at `node_modules/nx/schemas/project-schema.json` to understand nx project configuration options.
+
+```bash
+# Get full project configuration
+pnpm nx show project my-app --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'
+
+# Check project metadata
+pnpm nx show project my-app --json | jq '{name, root, sourceRoot, projectType, tags}'
+```
+
+## Target Information
+
+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'
+
+# Get full target configuration
+pnpm nx show project my-app --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'
+
+# View target options
+pnpm nx show project my-app --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'
+
+# Find projects with a specific target
+pnpm nx show projects --withTarget serve
+pnpm nx show projects --withTarget e2e
+```
+
+## Workspace Configuration
+
+Read `nx.json` directly for workspace-level configuration.
+You can read the full project schema at `node_modules/nx/schemas/nx-schema.json` to understand nx project configuration options.
+
+```bash
+# Read the full nx.json
+cat nx.json
+
+# Or use jq for specific sections
+cat nx.json | jq '.targetDefaults'
+cat nx.json | jq '.namedInputs'
+cat nx.json | jq '.plugins'
+cat nx.json | jq '.generators'
+```
+
+Key nx.json sections:
+
+- `targetDefaults` - Default configuration applied to all targets of a given name
+- `namedInputs` - Reusable input definitions for caching
+- `plugins` - Nx plugins and their configuration
+- ...and much more, read the schema or nx.json for details
+
+## Affected Projects
+
+If the user is asking about affected projects, read the [affected projects reference](references/AFFECTED.md) for detailed commands and examples.
+
+## Common Exploration Patterns
+
+### "What's in this workspace?"
+
+```bash
+pnpm nx show projects
+pnpm nx show projects --type app
+pnpm nx show projects --type lib
+```
+
+### "How do I build/test/lint project X?"
+
+```bash
+pnpm nx show project X --json | jq '.targets | keys'
+pnpm nx show project X --json | jq '.targets.build'
+```
+
+### "What depends on library Y?"
+
+```bash
+# Use the project graph to find dependents
+pnpm nx graph --print | jq '.graph.dependencies | to_entries[] | select(.value[].target == "Y") | .key'
+```
+
+## Programmatic Answers
+
+When processing nx CLI results, use command-line tools to compute the answer programmatically rather than counting or parsing output manually. Always use `--json` flags to get structured output that can be processed with `jq`, `grep`, or other tools you have installed locally.
+
+### Listing Projects
+
+```bash
+pnpm nx show projects --json
+```
+
+Example output:
+
+```json
+["my-app", "my-app-e2e", "shared-ui", "shared-utils", "api"]
+```
+
+Common operations:
+
+```bash
+# Count projects
+pnpm nx show projects --json | jq 'length'
+
+# Filter by pattern
+pnpm nx show projects --json | jq '.[] | select(startswith("shared-"))'
+
+# Get affected projects as array
+pnpm nx show projects --affected --json | jq '.'
+```
+
+### Project Details
+
+```bash
+pnpm nx show project my-app --json
+```
+
+Example output:
+
+```json
+{
+  "root": "apps/my-app",
+  "name": "my-app",
+  "sourceRoot": "apps/my-app/src",
+  "projectType": "application",
+  "tags": ["type:app", "scope:client"],
+  "targets": {
+    "build": {
+      "executor": "@nx/vite:build",
+      "options": { "outputPath": "dist/apps/my-app" }
+    },
+    "serve": {
+      "executor": "@nx/vite:dev-server",
+      "options": { "buildTarget": "my-app:build" }
+    },
+    "test": {
+      "executor": "@nx/vite:test",
+      "options": {}
+    }
+  },
+  "implicitDependencies": []
+}
+```
+
+Common operations:
+
+```bash
+# Get target names
+pnpm nx show project my-app --json | jq '.targets | keys'
+
+# Get specific target config
+pnpm nx show project my-app --json | jq '.targets.build'
+
+# Get tags
+pnpm nx show project my-app --json | jq '.tags'
+
+# Get project root
+pnpm nx show project my-app --json | jq -r '.root'
+```
+
+### Project Graph
+
+```bash
+pnpm nx graph --print
+```
+
+Example output:
+
+```json
+{
+  "graph": {
+    "nodes": {
+      "my-app": {
+        "name": "my-app",
+        "type": "app",
+        "data": { "root": "apps/my-app", "tags": ["type:app"] }
+      },
+      "shared-ui": {
+        "name": "shared-ui",
+        "type": "lib",
+        "data": { "root": "libs/shared-ui", "tags": ["type:ui"] }
+      }
+    },
+    "dependencies": {
+      "my-app": [
+        { "source": "my-app", "target": "shared-ui", "type": "static" }
+      ],
+      "shared-ui": []
+    }
+  }
+}
+```
+
+Common operations:
+
+```bash
+# Get all project names from graph
+pnpm nx graph --print | jq '.graph.nodes | keys'
+
+# Find dependencies of a project
+pnpm nx graph --print | jq '.graph.dependencies["my-app"]'
+
+# Find projects that depend on a library
+pnpm nx graph --print | jq '.graph.dependencies | to_entries[] | select(.value[].target == "shared-ui") | .key'
+```
+
+## Troubleshooting
+
+### "Cannot find configuration for task X:target"
+
+```bash
+# Check what targets exist on the project
+pnpm nx show project X --json | jq '.targets | keys'
+
+# Check if any projects have that target
+pnpm nx show projects --withTarget target
+```
+
+### "The workspace is out of sync"
+
+```bash
+pnpm nx sync
+pnpm nx reset  # if sync doesn't fix stale cache
+```

package/src/skills/nx-workspace/references/AFFECTED.md

@@ -0,0 +1,27 @@
+## Affected Projects
+
+Find projects affected by changes in the current branch.
+
+```bash
+# Affected since base branch (auto-detected)
+pnpm nx show projects --affected
+
+# Affected with explicit base
+pnpm nx show projects --affected --base=main
+pnpm nx show projects --affected --base=origin/main
+
+# Affected between two commits
+pnpm nx show projects --affected --base=abc123 --head=def456
+
+# Affected apps only
+pnpm nx show projects --affected --type app
+
+# Affected excluding e2e projects
+pnpm nx show projects --affected --exclude="*-e2e"
+
+# Affected by uncommitted changes
+pnpm nx show projects --affected --uncommitted
+
+# Affected by untracked files
+pnpm nx show projects --affected --untracked
+```

package/src/templates/CLAUDE.md

@@ -95,9 +95,13 @@ steps from memory:
   whichever add-on steps planning intake turned on. Triggered
   automatically by `planner` after its first run; skip if `nx.json`
   already exists.
+- **`backend-eng`** — builds each module's Phase A steps (schema →
+  contract → repository → service → controller → queue?), one step at a
+  time, gated and committed in its own context.
 - **`ux-planner`** — once per module in Phase B, after the hook exists and
   before the screen: writes `docs/design/<module>.md`.
-- **`ui-builder`** — builds screens from the ux-planner rationale.
+- **`front-end-eng`** — builds each module's Phase B steps (hook, screen)
+  from the ux-planner rationale, one step at a time, in its own context.
 - **`reviewer`** — phase-transition and Correction Protocol checks the
   mechanical gate can't make (port discipline, FK-by-ID discipline,
   contract shape).
@@ -221,9 +225,10 @@ context small:
   is available if the product narrative itself needs re-reading, but
   day-to-day recovery doesn't need it.
 - **Delegate heavy work to agents.** The project scaffold (`bootstrap`),
-  planning intake (`planner`), screen builds (`ui-builder`), and
-  reviews (`reviewer`) each run in their own isolated context — so that
-  work doesn't pile up in the main thread.
+  planning intake (`planner`), every Phase A step (`backend-eng`), every
+  Phase B step (`front-end-eng`), and reviews (`reviewer`) each run in
+  their own isolated context — so that work doesn't pile up in the main
+  thread.
 - **Don't paste large context back in.** If you find yourself
   re-explaining the architecture, stop — it's fixed and stated in this
   file, not something to reconstruct. If you need a project specific, read