From 91eae12ab00f8db9f246fd2d727384450ece62c8 Mon Sep 17 00:00:00 2001
From: Lincoln Stein <lincoln.stein@gmail.com>
Date: Sat, 28 Feb 2026 12:01:48 -0500
Subject: [PATCH] chore(agents): Ensure that coding agents use pnpm rather than
 npm

---
 .github/AGENTS.md                          | 24 ++++++++++++++++++++++
 .github/workflows/frontend-checks.yml      | 11 ++++++++++
 invokeai/frontend/web/scripts/package.json |  3 ++-
 3 files changed, 37 insertions(+), 1 deletion(-)
 create mode 100644 .github/AGENTS.md

diff --git a/.github/AGENTS.md b/.github/AGENTS.md
new file mode 100644
index 00000000000..9f701a7e33d
--- /dev/null
+++ b/.github/AGENTS.md
@@ -0,0 +1,24 @@
+# Agent Instructions
+
+## Package Management
+
+This project uses **pnpm** exclusively for package management in the frontend (`invokeai/frontend/web/`).
+
+- ✅ Use `pnpm` commands (e.g., `pnpm install`, `pnpm run`)
+- ❌ Never use `npm` or `yarn` commands
+- ❌ Never suggest creating or using `package-lock.json` or `yarn.lock`
+- ✅ The lock file is `pnpm-lock.yaml`
+
+Use the following pnpm commands for typical operations:
+
+- pnpm -C invokeai/frontend/web install
+- pnpm -C invokeai/frontend/web build
+- pnpm -C invokeai/frontend/web lint:tsc
+- pnpm -C invokeai/frontend/web lint:dpdm
+- pnpm -C invokeai/frontend/web lint:eslint
+- pnpm -C invokeai/frontend/web lint:prettier
+
+## Project Structure
+
+- Backend: Python in `invokeai/`
+- Frontend: TypeScript/React in `invokeai/frontend/web/` (uses pnpm)
diff --git a/.github/workflows/frontend-checks.yml b/.github/workflows/frontend-checks.yml
index 43bbfdec0ac..df767676441 100644
--- a/.github/workflows/frontend-checks.yml
+++ b/.github/workflows/frontend-checks.yml
@@ -41,6 +41,17 @@ jobs:
     steps:
       - uses: actions/checkout@v4
 
+      - name: Fail if package-lock.json is added/modified (pnpm only)
+        shell: bash
+        working-directory: .
+        run: |
+          set -euo pipefail
+          git fetch --no-tags --prune --depth=1 origin "${{ github.base_ref }}"
+          if git diff --name-only "origin/${{ github.base_ref }}...HEAD" | grep -E '(^|/)package-lock\.json$'; then
+            echo "::error::package-lock.json was added or modified. This repo uses pnpm only."
+           exit 1
+          fi
+
       - name: check for changed frontend files
         if: ${{ inputs.always_run != true }}
         id: changed-files
diff --git a/invokeai/frontend/web/scripts/package.json b/invokeai/frontend/web/scripts/package.json
index 3dbc1ca591c..985bcf7d652 100644
--- a/invokeai/frontend/web/scripts/package.json
+++ b/invokeai/frontend/web/scripts/package.json
@@ -1,3 +1,4 @@
 {
-  "type": "module"
+  "type": "module",
+  "packageManager": "pnpm@10.12.4"
 }