@next-friday/create-app 9.1.1 → 9.2.0

package/templates/nextjs/AGENTS.md

@@ -4,21 +4,21 @@ Next.js App Router web app with React and Tailwind CSS, in TypeScript on pnpm an
 
 ## Commands
 
-| Task                        | Command                                                     |
-| :-------------------------- | :---------------------------------------------------------- |
-| Start with reload           | `pnpm dev`                                                  |
-| One test                    | `pnpm vitest run app/health/route.test.ts -t "<test name>"` |
-| Unit tests                  | `pnpm test`, or `pnpm test:coverage`                        |
-| End-to-end tests            | `pnpm test:e2e`                                             |
-| What `pre-push` runs        | `pnpm check`                                                |
-| Every check                 | `pnpm verify`                                               |
-| Render rules after a change | `pnpm rules:sync`                                           |
+| Task                               | Command                                                     | Healthy output                                                               |
+| :--------------------------------- | :---------------------------------------------------------- | :--------------------------------------------------------------------------- |
+| Start with reload                  | `pnpm dev`                                                  | `✓ Ready in 301ms`                                                           |
+| One test                           | `pnpm vitest run app/health/route.test.ts -t "<test name>"` | `Tests  1 passed (1)`                                                        |
+| Unit tests                         | `pnpm test`, or `pnpm test:coverage`                        | `Tests  2 passed (2)`                                                        |
+| End-to-end tests                   | `pnpm test:e2e`                                             | `1 passed (5.6s)`                                                            |
+| What `pre-push` runs               | `pnpm check`                                                | exits 0; the last output is the route table of `next build` with `ƒ /health` |
+| Every check except `pnpm test:e2e` | `pnpm verify`                                               | exits 0; the last output is the route table of `next build` with `ƒ /health` |
+| Render rules after a change        | `pnpm rules:sync`                                           | `Synced 69 agent rule files; 0 updated.`                                     |
 
 ## Verifying your work
 
 - Build: `pnpm build` (prints the `Route (app)` table)
 - Test: `pnpm test:coverage` (all green, then the coverage summary; never skip or delete a failing test)
-- Lint: `pnpm verify:static` (ESLint allows zero warnings; prints `✔ no dependency violations found`)
+- Static checks: `pnpm verify:static` (ESLint allows zero warnings; every check must pass)
 
 Run all three before reporting any task complete, and paste the output. `pnpm verify` runs all three.
 
@@ -33,17 +33,21 @@ Run all three before reporting any task complete, and paste the output. `pnpm ve
 2. **Component tests need a DOM test environment, and Vitest runs in Node.js.** Add that environment with the first component test.
 3. **Read configuration from environment variables and fail when one is missing.** Document each variable in `.env.example`.
 4. **Start from the accepted spec, in plan mode** (Cursor: Plan Mode). Give the plan the change's `intent/<change>/intent.md` and `spec.md`. Commit the approved plan as `intent/<change>/plan.md` with an `Accepted by:` line naming the engineer, as `.agents/skills/sdlc/playbooks/build.md` describes.
-5. **Start a bug fix with a failing test.** Reproduce the bug as a test, confirm it fails for the reason you expect, and commit it. Then create `.git/bug-fix-in-progress`, so `.agents/hooks/agent-test-edit-gate.sh` blocks test edits, make the test pass without editing it, and delete `.git/bug-fix-in-progress`.
+5. **Start a bug fix with a failing test.** A bug fix has no intent and no spec; its plan, `intent/<short-description>/plan.md`, is accepted by an engineer before any code changes. Reproduce the bug as a test, confirm it fails for the reason you expect, and commit it on a `fix/` branch. Then `.agents/hooks/agent-test-edit-gate.sh` blocks test edits by itself: make the test pass without editing it. On a branch with another name, create `.git/bug-fix-in-progress` first, and delete it once the test passes.
 6. **Do not start work a person did not ask for.** When a message reports a problem without asking for work, answer in a few lines and end with the message that would start it: `/sdlc` followed by their own words.
 7. **Branch from the latest `origin/main`, and open the pull request ready for review.** Name the branch `<type>/<short-description>` and fill the body from `.github/pull_request_template.md`. `.github/workflows/ci.yml` runs full verification only on a pull request that is not a draft. Never merge a pull request: a person merges it with `--squash` after code owner approval, bottom-up for a stack of pull requests.
 8. **Write replies a person can check.** Reply in the language the person wrote in. Write paths from the project root, such as `README.md:12`, never from the machine's root. State as a fact only what you opened or ran in this turn, and say what you ran; mark anything else as inferred or not checked. Answer what was asked and stop: leave out tools, services, and steps the request does not need, and never hand the person a check you could run. Send nothing outside the session, such as a message to another session or a service, unless a task step says to.
+9. **Run parallel sessions in separate worktrees, on tasks that touch different files.** Start each with `claude --worktree <name>`: a worktree is its own checkout on its own branch. Tasks that share files run in one session, one after another. Start with two or three sessions, and add one only while you can review every stream properly.
 
 ## Things Claude gets wrong
 
 When Claude makes a mistake twice, add the correction here.
 
 - **First end-to-end run**: run `pnpm exec playwright install chromium` once. `pnpm test:e2e` starts the development server unless one is already running.
-- **Production gate**: `.agents/hooks/agent-production-gate.sh` blocks a shell command that deploys to `prod`, runs a Railway CLI command that names `prod`, or pushes a release tag, unless a release manager started the session with `RELEASE_APPROVAL` set. Report what is ready to promote instead. When a gated command appears only inside a message, write the text to a file with your file-editing tool, not a shell heredoc, and pass it with `git commit -F <file>` or `gh pr create --body-file <file>`. The gate reads only shell commands, so an MCP tool or a Railway command without `-e` or `--environment` passes it.
+- **Production gate**: `.agents/hooks/agent-production-gate.sh` blocks a shell command that deploys to `prod`, runs a Railway CLI command that names `prod`, or pushes a release tag, unless a release manager started the session with `RELEASE_APPROVAL` set. Any value lifts the gate except an empty value, `0`, `false`, and `no`, in any letter case. Report what is ready to promote instead. When a gated command appears only inside a message, write the text to a file with your file-editing tool, not a shell heredoc, and pass it with `git commit -F <file>` or `gh pr create --body-file <file>`. The gate reads only shell commands, so an MCP tool or a Railway command without `-e` or `--environment` passes it.
+- **Issues**: open an issue only to hand work to another person, never to give a pull request a number to close. A pull request closes an issue that already exists with `Closes #<issue>`.
+- **What belongs in the repository**: files, commit messages, and pull requests hold the change, its reason, and the checks. Write no date, log, history, mistake count, token figure, or session note into a file.
+- **Sourced requirements**: add a requirement to an intent, spec, or plan only when a person decided it or a named source says it. This includes a requirement a review bot suggests. When no person decided it and no source says it, leave it out and answer the thread with that.
 
 <!-- BEGIN:nextjs-agent-rules -->
 

package/templates/nextjs/CONTRIBUTING.md

@@ -8,7 +8,7 @@ Use this guide to prepare changes to this repository.
 - Change the Node.js version in `.nvmrc` and the `Dockerfile` together. Dependabot updates only the `Dockerfile`.
 - Install pnpm once with `npm install --global pnpm`. It switches to the version declared by `package.json#packageManager` automatically.
 - Use Claude Code v2.1.295 or later. It reads `CLAUDE.md`, which imports `AGENTS.md`, and supports the `onFailure` field the agent hooks use.
-- Install gitleaks 8.19 or later, which the `pre-commit` hook runs, and jq, which the agent hooks and the `pre-push` hook (`pnpm gates:check`) need: `brew install gitleaks jq` on macOS, or install them from each project's releases on Linux.
+- Install gitleaks 8.21 or later, which the `pre-commit` hook runs, and jq, which the agent hooks and the `pre-push` hook (`pnpm gates:check`) need: `brew install gitleaks jq` on macOS, or install them from each project's releases on Linux.
 
 From the repository root:
 
@@ -35,9 +35,10 @@ Run the narrowest check that covers the change while you work. Git hooks run the
 | `pre-merge-commit` | blocks merge commits on `main`                                                                                                                                  |
 | `pre-push`         | blocks pushes to `main` except the push that creates it, then `pnpm check`: the static checks, the unit tests related to your changes, and the production build |
 
-- **Scans:** CI also runs coverage, the build, the container image, and the secret, SAST, OSV, CodeQL, dependency-review, and OpenSSF Scorecard scans. Dependabot and OSV-Scanner report vulnerable dependencies.
+- **Scans:** CI also runs coverage, the build, the container image, and the secret, SAST, OSV, CodeQL, dependency-review, and OpenSSF Scorecard scans. CodeQL, dependency-review, and Scorecard run on public repositories, and on private ones when the `CODE_SCANNING` repository variable is `true`. Dependabot and OSV-Scanner report vulnerable dependencies.
 - **End-to-end tests:** run `pnpm test:e2e` when you change pages. It starts the development server unless one is already running. Run `pnpm exec playwright install chromium` once before the first run. CI runs it against the production build on every pull request that is ready for review and changes code.
 - **Coverage:** CI requires 95% branch coverage on changed lines in `app/`, except `layout.tsx`.
+- **Agent evals:** run `pnpm evals:run` after you change `AGENTS.md`, a skill under `.agents/skills/`, or a hook under `.agents/hooks/`, and add a case name to run one case. It runs the cases in `.agents/skill-evals/` with Claude Code on your own Claude login, so it spends your Claude usage, and it is not part of `pnpm verify`.
 
 Run `pnpm verify` for repository changes.
 

package/templates/nextjs/Dockerfile

@@ -1,6 +1,6 @@
 # Runs on any OCI platform (Railway, Fly.io, Cloud Run). On Vercel, deploy without it. The platform sets `PORT`.
 FROM \
-  node@sha256:06d7adf3e0ef61a13f1d28682726366f97a15aa1888c934d3ecec86c33918b53 \
+  node:24.22.1-alpine@sha256:06d7adf3e0ef61a13f1d28682726366f97a15aa1888c934d3ecec86c33918b53 \
   AS build
 ENV NEXT_TELEMETRY_DISABLED=1
 WORKDIR /app
@@ -12,7 +12,7 @@ COPY app ./app
 RUN pnpm build
 
 FROM \
-  node@sha256:06d7adf3e0ef61a13f1d28682726366f97a15aa1888c934d3ecec86c33918b53
+  node:24.22.1-alpine@sha256:06d7adf3e0ef61a13f1d28682726366f97a15aa1888c934d3ecec86c33918b53
 ENV NODE_ENV=production NEXT_TELEMETRY_DISABLED=1 HOSTNAME=0.0.0.0
 WORKDIR /app
 # Apply Alpine security fixes released after the base image, and drop npm, corepack, and yarn: the app never runs them, and their bundled dependencies carry their own CVEs.

package/templates/nextjs/README.md

@@ -1,6 +1,6 @@
 # next-friday-template-nextjs
 
-Next Friday starter for Next.js applications.
+Next.js application.
 
 ## Getting started
 
@@ -12,7 +12,7 @@ pnpm dev
 
 ## After creating a project from this template
 
-Follow [SETUP.md](SETUP.md) in order. It sets up the repository, the reviews, and the AI-native SDLC. In step 1, also replace the `Next Friday Next.js template` text in `app/layout.tsx`, `app/page.tsx`, and their tests.
+Follow [SETUP.md](SETUP.md) in order. It sets up the repository, the reviews, and the AI-native SDLC. In step 1, also replace the `Next.js application` text in `app/layout.tsx`, `app/page.tsx`, and `app/page.test.ts`.
 
 ## Scripts
 
@@ -26,7 +26,9 @@ Follow [SETUP.md](SETUP.md) in order. It sets up the repository, the reviews, an
 | `pnpm check`    | Run the static checks, the unit tests for changed code, and the production build (the `pre-push` hook)            |
 | `pnpm verify`   | Run the static checks, all unit tests with coverage, and the production build                                     |
 
-CI also runs the build, the end-to-end tests, the container image scan, and the security scans, including CodeQL, dependency review, and OpenSSF Scorecard. CodeQL and Scorecard run on public repositories, and on private ones when the `CODE_SCANNING` repository variable is `true`.
+`pnpm build` copies `.env` into `.next/standalone`, where every secret sits in plain text. Keep that folder out of images and archives.
+
+CI also runs the build, the end-to-end tests, the container image scan, and the security scans, including CodeQL, dependency review, and OpenSSF Scorecard. CodeQL, dependency review, and Scorecard run on public repositories, and on private ones when the `CODE_SCANNING` repository variable is `true`.
 
 ## Container
 

package/templates/nextjs/app/layout.tsx

@@ -14,8 +14,8 @@ const geistMono = Geist_Mono({
 });
 
 export const metadata: Metadata = {
-  title: "Next Friday Next.js template",
-  description: "Starter application for Next Friday Next.js projects.",
+  title: "Next.js application",
+  description: "A Next.js application.",
 };
 
 export default function RootLayout(props: LayoutProps<"/">) {

package/templates/nextjs/app/page.test.ts

@@ -6,6 +6,6 @@ import Page from "./page";
 
 describe("Page", () => {
   it("renders the template heading", () => {
-    expect(renderToStaticMarkup(createElement(Page))).toContain("Next Friday Next.js template");
+    expect(renderToStaticMarkup(createElement(Page))).toContain("Next.js application");
   });
 });

package/templates/nextjs/app/page.tsx

@@ -1,7 +1,7 @@
 export default function Page() {
   return (
     <main className="flex flex-1 flex-col items-center justify-center gap-4 p-16 text-center">
-      <h1 className="text-3xl font-semibold tracking-tight">Next Friday Next.js template</h1>
+      <h1 className="text-3xl font-semibold tracking-tight">Next.js application</h1>
       <p className="text-lg text-zinc-600 dark:text-zinc-400">Edit app/page.tsx to get started.</p>
     </main>
   );

package/templates/nextjs/package.json

@@ -2,7 +2,7 @@
   "name": "next-friday-template-nextjs",
   "version": "0.1.0",
   "private": true,
-  "description": "Next Friday Next.js template.",
+  "description": "Next.js application.",
   "repository": {
     "type": "git",
     "url": "git+https://github.com/next-friday/next-friday-template-nextjs.git"
@@ -11,27 +11,27 @@
   "author": "Next Friday",
   "type": "module",
   "scripts": {
+    "bands:check": "node scripts/check-bands.ts",
     "build": "next build",
     "check": "pnpm verify:static && pnpm test:changed && pnpm build",
     "clean": "rm -rf .next coverage *.tsbuildinfo .eslintcache node_modules/.cache",
     "depcruise": "depcruise --config .dependency-cruiser.json app test eslint.config.ts next.config.ts playwright.config.ts postcss.config.mjs vitest.config.ts",
     "dev": "next dev",
+    "evals:run": "node scripts/run-agent-evals.ts",
     "format": "prettier --write --cache .",
     "format:check": "prettier --check --cache . && editorconfig-checker",
     "gates:check": "node scripts/check-agent-gates.ts",
-    "human-gates:check": "node scripts/check-human-gates.ts",
-    "intent:check": "node scripts/check-intent.ts",
     "knip": "knip",
     "lint": "eslint . --fix --cache --max-warnings=0 --no-inline-config",
     "lint:check": "eslint . --cache --max-warnings=0 --no-inline-config",
-    "peers:check": "pnpm peers check",
+    "loop:measure": "node scripts/measure-loop.ts",
+    "plan:check": "node scripts/check-plan.ts",
     "prepare": "husky && next typegen",
     "rules:check": "node scripts/sync-agent-rules.ts --check",
     "rules:sync": "node scripts/sync-agent-rules.ts",
     "sort-package-json": "sort-package-json package.json",
     "sort-package-json:check": "sort-package-json --check package.json",
     "start": "cp -R .next/static .next/standalone/.next/ && (test ! -d public || cp -R public .next/standalone/) && node .next/standalone/server.js",
-    "suppressions:check": "bash .agents/hooks/agent-suppression-gate.sh --repo",
     "test": "vitest run --passWithNoTests",
     "test:changed": "if git rev-parse --quiet --verify origin/main > /dev/null && git diff --quiet \"$(git merge-base origin/main HEAD)\" -- pnpm-lock.yaml pnpm-workspace.yaml \"*package.json\" \"*tsconfig.json\" .husky; then vitest run --changed origin/main --passWithNoTests; else vitest run --passWithNoTests; fi",
     "test:coverage": "vitest run --coverage --passWithNoTests",
@@ -39,7 +39,7 @@
     "test:watch": "vitest",
     "typecheck": "next typegen && tsc --noEmit -p tsconfig.json",
     "verify": "pnpm verify:static && pnpm test:coverage && pnpm build",
-    "verify:static": "pnpm suppressions:check && pnpm rules:check && pnpm gates:check && pnpm human-gates:check && pnpm intent:check && pnpm lint:check && pnpm format:check && pnpm sort-package-json:check && pnpm peers:check && pnpm typecheck && pnpm knip && pnpm depcruise"
+    "verify:static": "pnpm rules:check && pnpm gates:check && pnpm plan:check && pnpm bands:check && pnpm lint:check && pnpm format:check && pnpm sort-package-json:check && pnpm typecheck && pnpm knip && pnpm depcruise"
   },
   "dependencies": {
     "next": "16.4.3",
@@ -53,6 +53,7 @@
     "@next-friday/prettier-config-friday": "4.0.0",
     "@next/eslint-plugin-next": "16.4.3",
     "@playwright/test": "1.64.1",
+    "@swc/core": "1.16.22",
     "@tailwindcss/postcss": "4.3.3",
     "@types/node": "26.6.6",
     "@types/react": "19.3.0",
@@ -61,7 +62,6 @@
     "dependency-cruiser": "18.7.1",
     "editorconfig-checker": "7.0.0",
     "eslint": "10.14.0",
-    "fast-check": "4.10.2",
     "husky": "9.1.7",
     "jiti": "2.7.0",
     "knip": "6.44.1",
@@ -71,7 +71,8 @@
     "sort-package-json": "4.1.0",
     "tailwindcss": "4.3.3",
     "typescript": "7.0.2",
-    "vitest": "5.0.5"
+    "vitest": "5.0.5",
+    "yaml": "2.9.1"
   },
   "packageManager": "pnpm@12.6.0+sha512.3ef68f951cb111ac204b4a5a16f0b2ddf0da56a96e0413e81d855d9f0b55ef926714709028e1cd00c405c2c5fb7b9e8ec4dc46777c805d0373c2f2ff00fd20ec",
   "engines": {

package/templates/nextjs/test/home.e2e.test.ts

@@ -1,11 +1,7 @@
 import {expect, test} from "@playwright/test";
 
-test("home page shows the template heading", async ({page}) => {
-  await page.goto("/");
+test("serves the home page", async ({page}) => {
+  const response = await page.goto("/");
 
-  await expect(
-    page.getByRole("heading", {
-      level: 1,
-    }),
-  ).toHaveText("Next Friday Next.js template");
+  expect(response?.status()).toBe(200);
 });

package/templates/nextjs/tsconfig.json

@@ -17,9 +17,6 @@
         "name": "next"
       }
     ],
-    "paths": {
-      "@/*": ["./*"]
-    },
     "allowJs": true
   },
   "include": [

package/templates/nodejs/.dependency-cruiser.json

@@ -17,8 +17,8 @@
     }
   ],
   "options": {
+    "parser": "swc",
     "skipAnalysisNotInRules": true,
-    "tsPreCompilationDeps": true,
     "enhancedResolveOptions": {
       "conditionNames": ["import", "require", "node", "default", "types"],
       "exportsFields": ["exports"]

package/templates/nodejs/.github/ISSUE_TEMPLATE/bug.yml

@@ -21,7 +21,7 @@ body:
     id: version
     attributes:
       label: Commit
-      placeholder: 769e0ef
+      placeholder: Output of `git rev-parse --short HEAD`
     validations:
       required: true
   - type: textarea
@@ -30,10 +30,10 @@ body:
       label: Environment
       description: List Node.js, operating system, package manager, and the request that triggers the issue.
       placeholder: |
-        Node.js: 24.22.1
-        OS: Ubuntu 24.04 / macOS
-        Package manager: pnpm 12.6.0
-        Request: curl -i http://localhost:3000/
+        Node.js: output of `node --version`
+        OS: Ubuntu / macOS / Windows
+        Package manager: output of `pnpm --version`
+        Request: curl -i http://localhost:3000/health
     validations:
       required: true
   - type: textarea

package/templates/nodejs/.github/workflows/ci.yml

@@ -73,16 +73,14 @@ jobs:
         with:
           cache: true
           require-lockfile: true
-      - name: Reject suppression directives
-        run: pnpm suppressions:check
-      - name: Check Cursor rules match .agents/rules
+      - name: Check rendered agent rules match .agents/rules
         run: pnpm rules:check
       - name: Check agent gates
         run: pnpm gates:check
-      - name: Check human gates
-        run: pnpm human-gates:check
-      - name: Self-test the intent checker
-        run: pnpm intent:check
+      - name: Check plans
+        run: pnpm plan:check
+      - name: Check bands
+        run: pnpm bands:check
       - name: Check lint
         run: pnpm lint:check
       - name: Check formatting
@@ -91,8 +89,6 @@ jobs:
           GITHUB_TOKEN: ${{ github.token }} # editorconfig-checker downloads its binary from GitHub releases; the token avoids the anonymous rate limit.
       - name: Check package.json ordering
         run: pnpm sort-package-json:check
-      - name: Validate peer dependency contracts
-        run: pnpm peers:check
       - name: Check types
         run: pnpm typecheck
       - name: Run Knip
@@ -168,6 +164,59 @@ jobs:
       environment: dev
       commit_sha: ${{ github.sha }}
 
+  triage:
+    name: Triage failed build
+    needs:
+      - changes
+      - checks
+      - image
+    if: failure() && vars.CLAUDE_CI_ENABLED == 'true' && github.event_name == 'pull_request' && github.event.pull_request.head.repo.full_name == github.repository
+    runs-on: ubuntu-latest
+    timeout-minutes: 15
+    permissions:
+      actions: read # Needed to read the logs of the failed jobs.
+      id-token: write # Needed to authenticate the Claude GitHub App with the workflow's OIDC token.
+      pull-requests: write # Needed to post the summary on the pull request.
+    steps:
+      - name: Require a Claude credential
+        env:
+          ANTHROPIC_API_KEY: ${{ secrets.ANTHROPIC_API_KEY }}
+          CLAUDE_CODE_OAUTH_TOKEN: ${{ secrets.CLAUDE_CODE_OAUTH_TOKEN }}
+        run: |
+          [[ -n "$ANTHROPIC_API_KEY" || -n "$CLAUDE_CODE_OAUTH_TOKEN" ]] || { echo "::error::Set the CLAUDE_CODE_OAUTH_TOKEN or ANTHROPIC_API_KEY repository secret"; exit 1; }
+      - name: Collect the build log
+        env:
+          GH_TOKEN: ${{ github.token }}
+          REPOSITORY: ${{ github.repository }}
+          RUN_ID: ${{ github.run_id }}
+        run: |
+          mkdir -p out
+          for job in $(gh api "repos/$REPOSITORY/actions/runs/$RUN_ID/jobs" --paginate --jq '.jobs[] | select(.conclusion == "failure") | .id'); do
+            gh api --allow-escape-sequences "repos/$REPOSITORY/actions/jobs/$job/logs" >> out/build.log
+          done
+      - name: Triage failed build
+        id: triage
+        uses: anthropics/claude-code-action@61a9c274fa7110a66dfafc1bbbced03833eb25fe # v1.0.269
+        with:
+          anthropic_api_key: ${{ secrets.ANTHROPIC_API_KEY }}
+          claude_code_oauth_token: ${{ secrets.CLAUDE_CODE_OAUTH_TOKEN }}
+          prompt: >
+            Read the build log at out/build.log. Identify the most
+            likely cause, say whether the failure looks flaky or real, and write a
+            three-line summary for the PR thread.
+          claude_args: >-
+            --model claude-haiku-5-5
+            --max-turns 5
+            --allowedTools "Read"
+            --json-schema '{"type":"object","properties":{"summary":{"type":"string"}},"required":["summary"]}'
+      - name: Post the summary
+        env:
+          GH_TOKEN: ${{ github.token }}
+          PR_NUMBER: ${{ github.event.pull_request.number }}
+          REPOSITORY: ${{ github.repository }}
+          SUMMARY: ${{ fromJSON(steps.triage.outputs.structured_output).summary }}
+        run: gh pr comment "$PR_NUMBER" --repo "$REPOSITORY" --body "$SUMMARY"
+
   ci:
     name: All Checks
     if: always()

package/templates/nodejs/.github/workflows/sast.yml

@@ -5,11 +5,6 @@ on:
   push:
     branches:
       - main
-    paths-ignore:
-      - "**/*.md"
-      - ".agents/**"
-      - ".claude/**"
-      - ".cursor/**"
   schedule:
     - cron: "17 2 * * 1"
 

package/templates/nodejs/AGENTS.md

@@ -4,20 +4,21 @@ TypeScript HTTP service on `node:http`, without a framework, on pnpm and Node.js
 
 ## Commands
 
-| Task                        | Command                                             |
-| :-------------------------- | :-------------------------------------------------- |
-| Start with reload           | `pnpm start:dev`                                    |
-| One test                    | `pnpm vitest run src/port.test.ts -t "<test name>"` |
-| Unit tests                  | `pnpm test`, or `pnpm test:coverage`                |
-| What `pre-push` runs        | `pnpm check`                                        |
-| Every check                 | `pnpm verify`                                       |
-| Render rules after a change | `pnpm rules:sync`                                   |
+| Task                        | Command                                             | Healthy output                                                                                       |
+| :-------------------------- | :-------------------------------------------------- | :--------------------------------------------------------------------------------------------------- |
+| Start with reload           | `pnpm start:dev`                                    | The only output is `$ node --env-file-if-exists=.env --watch src/main.ts`; `GET /health` answers 200 |
+| Run the build               | `pnpm start`, which builds first                    | `$ tsc -p tsconfig.build.json`, then nothing                                                         |
+| One test                    | `pnpm vitest run src/port.test.ts -t "<test name>"` | `Tests  1 passed \| 9 skipped (10)`                                                                  |
+| Unit tests                  | `pnpm test`, or `pnpm test:coverage`                | `Tests  15 passed (15)`                                                                              |
+| What `pre-push` runs        | `pnpm check`                                        | exits 0; the last line is `$ tsc -p tsconfig.build.json`                                             |
+| Every check                 | `pnpm verify`                                       | exits 0; the last line is `$ tsc -p tsconfig.build.json`                                             |
+| Render rules after a change | `pnpm rules:sync`                                   | `Synced 67 agent rule files; 0 updated.`                                                             |
 
 ## Verifying your work
 
 - Build: `pnpm build` (prints nothing after `$ tsc -p tsconfig.build.json`)
 - Test: `pnpm test:coverage` (all green, then the coverage summary; never skip or delete a failing test)
-- Lint: `pnpm verify:static` (ESLint allows zero warnings; prints `✔ no dependency violations found`)
+- Static checks: `pnpm verify:static` (ESLint allows zero warnings; every check must pass)
 
 Run all three before reporting any task complete, and paste the output. `pnpm verify` runs all three.
 
@@ -31,13 +32,17 @@ Run all three before reporting any task complete, and paste the output. `pnpm ve
 1. **Put tests next to the code as `src/**/*.test.ts`.** Vitest collects only that pattern.
 2. **Read configuration from environment variables and fail when one is missing**, as `parsePort` does. Document each variable in `.env.example`; `pnpm start` and `pnpm start:dev` load `.env`.
 3. **Start from the accepted spec, in plan mode** (Cursor: Plan Mode). Give the plan the change's `intent/<change>/intent.md` and `spec.md`. Commit the approved plan as `intent/<change>/plan.md` with an `Accepted by:` line naming the engineer, as `.agents/skills/sdlc/playbooks/build.md` describes.
-4. **Start a bug fix with a failing test.** Reproduce the bug as a test, confirm it fails for the reason you expect, and commit it. Then create `.git/bug-fix-in-progress`, so `.agents/hooks/agent-test-edit-gate.sh` blocks test edits, make the test pass without editing it, and delete `.git/bug-fix-in-progress`.
+4. **Start a bug fix with a failing test.** A bug fix has no intent and no spec; its plan, `intent/<short-description>/plan.md`, is accepted by an engineer before any code changes. Reproduce the bug as a test, confirm it fails for the reason you expect, and commit it on a `fix/` branch. Then `.agents/hooks/agent-test-edit-gate.sh` blocks test edits by itself: make the test pass without editing it. On a branch with another name, create `.git/bug-fix-in-progress` first, and delete it once the test passes.
 5. **Do not start work a person did not ask for.** When a message reports a problem without asking for work, answer in a few lines and end with the message that would start it: `/sdlc` followed by their own words.
 6. **Branch from the latest `origin/main`, and open the pull request ready for review.** Name the branch `<type>/<short-description>` and fill the body from `.github/pull_request_template.md`. `.github/workflows/ci.yml` runs full verification only on a pull request that is not a draft. Never merge a pull request: a person merges it with `--squash` after code owner approval, bottom-up for a stack of pull requests.
 7. **Write replies a person can check.** Reply in the language the person wrote in. Write paths from the project root, such as `README.md:12`, never from the machine's root. State as a fact only what you opened or ran in this turn, and say what you ran; mark anything else as inferred or not checked. Answer what was asked and stop: leave out tools, services, and steps the request does not need, and never hand the person a check you could run. Send nothing outside the session, such as a message to another session or a service, unless a task step says to.
+8. **Run parallel sessions in separate worktrees, on tasks that touch different files.** Start each with `claude --worktree <name>`: a worktree is its own checkout on its own branch. Tasks that share files run in one session, one after another. Start with two or three sessions, and add one only while you can review every stream properly.
 
 ## Things Claude gets wrong
 
 When Claude makes a mistake twice, add the correction here.
 
-- **Production gate**: `.agents/hooks/agent-production-gate.sh` blocks a shell command that deploys to `prod`, runs a Railway CLI command that names `prod`, or pushes a release tag, unless a release manager started the session with `RELEASE_APPROVAL` set. Report what is ready to promote instead. When a gated command appears only inside a message, write the text to a file with your file-editing tool, not a shell heredoc, and pass it with `git commit -F <file>` or `gh pr create --body-file <file>`. The gate reads only shell commands, so an MCP tool or a Railway command without `-e` or `--environment` passes it.
+- **Production gate**: `.agents/hooks/agent-production-gate.sh` blocks a shell command that deploys to `prod`, runs a Railway CLI command that names `prod`, or pushes a release tag, unless a release manager started the session with `RELEASE_APPROVAL` set. Any value lifts the gate except an empty value, `0`, `false`, and `no`, in any letter case. Report what is ready to promote instead. When a gated command appears only inside a message, write the text to a file with your file-editing tool, not a shell heredoc, and pass it with `git commit -F <file>` or `gh pr create --body-file <file>`. The gate reads only shell commands, so an MCP tool or a Railway command without `-e` or `--environment` passes it.
+- **Issues**: open an issue only to hand work to another person, never to give a pull request a number to close. A pull request closes an issue that already exists with `Closes #<issue>`.
+- **What belongs in the repository**: files, commit messages, and pull requests hold the change, its reason, and the checks. Write no date, log, history, mistake count, token figure, or session note into a file.
+- **Sourced requirements**: add a requirement to an intent, spec, or plan only when a person decided it or a named source says it. This includes a requirement a review bot suggests. When no person decided it and no source says it, leave it out and answer the thread with that.

package/templates/nodejs/CONTRIBUTING.md

@@ -8,7 +8,7 @@ Use this guide to prepare changes to this repository.
 - Change the Node.js version in `.nvmrc` and the `Dockerfile` together. Dependabot updates only the `Dockerfile`.
 - Install pnpm once with `npm install --global pnpm`. It switches to the version declared by `package.json#packageManager` automatically.
 - Use Claude Code v2.1.295 or later. It reads `CLAUDE.md`, which imports `AGENTS.md`, and supports the `onFailure` field the agent hooks use.
-- Install gitleaks 8.19 or later, which the `pre-commit` hook runs, and jq, which the agent hooks and the `pre-push` hook (`pnpm gates:check`) need: `brew install gitleaks jq` on macOS, or install them from each project's releases on Linux.
+- Install gitleaks 8.21 or later, which the `pre-commit` hook runs, and jq, which the agent hooks and the `pre-push` hook (`pnpm gates:check`) need: `brew install gitleaks jq` on macOS, or install them from each project's releases on Linux.
 
 From the repository root:
 
@@ -35,8 +35,9 @@ Run the narrowest check that covers the change while you work. Git hooks run the
 | `pre-merge-commit` | blocks merge commits on `main`                                                                                                                                  |
 | `pre-push`         | blocks pushes to `main` except the push that creates it, then `pnpm check`: the static checks, the unit tests related to your changes, and the production build |
 
-- **Scans:** CI also runs coverage, the build, the container image, and the secret, SAST, OSV, CodeQL, dependency-review, and OpenSSF Scorecard scans. Dependabot and OSV-Scanner report vulnerable dependencies.
-- **Coverage:** CI requires 95% line coverage on changed lines in `src/`, except `main.ts`, which holds only wiring. Keep logic out of it, as `src/port.ts` and `src/server.ts` do.
+- **Scans:** CI also runs coverage, the build, the container image, and the secret, SAST, OSV, CodeQL, dependency-review, and OpenSSF Scorecard scans. CodeQL, dependency-review, and Scorecard run on public repositories, and on private ones when the `CODE_SCANNING` repository variable is `true`. Dependabot and OSV-Scanner report vulnerable dependencies.
+- **Coverage:** CI requires 95% line coverage on changed lines in `src/`, except `main.ts`, which starts the server and handles the shutdown signals. Keep other logic out of it, as `src/port.ts` and `src/server.ts` do.
+- **Agent evals:** run `pnpm evals:run` after you change `AGENTS.md`, a skill under `.agents/skills/`, or a hook under `.agents/hooks/`, and add a case name to run one case. It runs the cases in `.agents/skill-evals/` with Claude Code on your own Claude login, so it spends your Claude usage, and it is not part of `pnpm verify`.
 
 Run `pnpm verify` for repository changes.
 

package/templates/nodejs/Dockerfile

@@ -1,6 +1,6 @@
 # Runs on any OCI platform (Railway, Fly.io, Cloud Run). The platform sets `PORT`.
 FROM \
-  node@sha256:06d7adf3e0ef61a13f1d28682726366f97a15aa1888c934d3ecec86c33918b53 \
+  node:24.22.1-alpine@sha256:06d7adf3e0ef61a13f1d28682726366f97a15aa1888c934d3ecec86c33918b53 \
   AS base
 WORKDIR /app
 COPY package.json pnpm-lock.yaml pnpm-workspace.yaml ./
@@ -16,7 +16,7 @@ FROM base AS prod-deps
 RUN pnpm install --frozen-lockfile --ignore-scripts --prod
 
 FROM \
-  node@sha256:06d7adf3e0ef61a13f1d28682726366f97a15aa1888c934d3ecec86c33918b53
+  node:24.22.1-alpine@sha256:06d7adf3e0ef61a13f1d28682726366f97a15aa1888c934d3ecec86c33918b53
 ENV NODE_ENV=production
 WORKDIR /app
 # Apply Alpine security fixes released after the base image, and drop npm, corepack, and yarn: the app never runs them, and their bundled dependencies carry their own CVEs.
@@ -33,5 +33,5 @@ COPY package.json ./
 COPY --from=prod-deps /app/node_modules ./node_modules
 COPY --from=build /app/dist ./dist
 USER 1000
-HEALTHCHECK --interval=30s --timeout=5s CMD ["node", "-e", "fetch('http://127.0.0.1:' + (process.env.PORT || 3000) + '/health').then(response => process.exit(response.ok ? 0 : 1), () => process.exit(1))"]
+HEALTHCHECK --interval=30s --timeout=5s CMD ["node", "-e", "fetch('http://127.0.0.1:' + process.env.PORT + '/health').then(response => process.exit(response.ok ? 0 : 1), () => process.exit(1))"]
 CMD ["node", "dist/main.js"]

package/templates/nodejs/README.md

@@ -1,6 +1,6 @@
 # next-friday-template-nodejs
 
-Next Friday starter for Node.js HTTP services without a framework.
+Node.js HTTP service without a framework.
 
 ## Getting started
 
@@ -22,17 +22,17 @@ Follow [SETUP.md](SETUP.md) in order. It sets up the repository, the reviews, an
 | :---------------- | :------------------------------------------------------------------------------------------------ |
 | `pnpm start:dev`  | Start in watch mode from `src/main.ts`; loads `.env` when present                                 |
 | `pnpm build`      | Compile to `dist/`                                                                                |
-| `pnpm start`      | Run `dist/main.js`; loads `.env` when present                                                     |
+| `pnpm start`      | Build, then run `dist/main.js` once; loads `.env` when present                                    |
 | `pnpm start:prod` | Run `dist/main.js`; the environment sets `PORT`                                                   |
 | `pnpm test`       | Run tests (`src/**/*.test.ts`)                                                                    |
 | `pnpm check`      | Run the static checks, the tests for changed code, and the production build (the `pre-push` hook) |
 | `pnpm verify`     | Run the static checks, all tests with coverage, and the production build                          |
 
-CI also runs the build, the container image scan, and the security scans, including CodeQL, dependency review, and OpenSSF Scorecard. CodeQL and Scorecard run on public repositories, and on private ones when the `CODE_SCANNING` repository variable is `true`.
+CI also runs the build, the container image scan, and the security scans, including CodeQL, dependency review, and OpenSSF Scorecard. CodeQL, dependency review, and Scorecard run on public repositories, and on private ones when the `CODE_SCANNING` repository variable is `true`.
 
 ## Container
 
-The `Dockerfile` builds a production image that runs as the `node` user. The platform must set `PORT`; Railway sets it automatically.
+The `Dockerfile` builds a production image that runs as a non-root user (UID 1000). The platform must set `PORT`; Railway sets it automatically. The build needs `pnpm-lock.yaml`, so run `pnpm install` once before the first `docker build`.
 
 ```sh
 docker build -t app .

package/templates/nodejs/_gitignore

@@ -2,7 +2,6 @@ node_modules
 .pnpm-store
 
 coverage
-*.tsbuildinfo
 
 .cache