@next-friday/create-app 9.1.0 → 9.2.0

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

@@ -56,9 +56,48 @@ jobs:
 
           echo "full_verification=$full_verification" >> "$GITHUB_OUTPUT"
 
+  affected-apps:
+    name: Detect Affected Apps
+    needs: changes
+    if: needs.changes.outputs.full_verification == 'true' || github.event_name == 'schedule'
+    runs-on: ubuntu-latest
+    timeout-minutes: 10
+    outputs:
+      apps: ${{ steps.affected.outputs.apps }}
+    steps:
+      - name: Checkout repository
+        uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7
+        with:
+          fetch-depth: 0
+          persist-credentials: false
+      - name: Fetch the pull request base
+        if: github.event_name == 'pull_request'
+        env:
+          BASE_REF: ${{ github.base_ref }}
+        run: git fetch --no-tags origin "$BASE_REF"
+      - name: Set up Node.js and pnpm
+        uses: pnpm/setup@fbda4c85fc2e1e08721cd8763afea8f48d60f024 # v3.0.0
+        with:
+          cache: true
+          require-lockfile: true
+      - name: List affected apps
+        id: affected
+        env:
+          EVENT_NAME: ${{ github.event_name }}
+          BASE_REF: ${{ github.base_ref }}
+        run: |
+          if [[ "$EVENT_NAME" == "pull_request" ]]; then
+            apps="$(bash .github/scripts/affected-apps.sh "origin/$BASE_REF" HEAD)"
+          else
+            apps="$(bash .github/scripts/affected-apps.sh)"
+          fi
+          echo "apps=$apps" >> "$GITHUB_OUTPUT"
+
   checks:
     name: Static Checks, Tests & Build
-    needs: changes
+    needs:
+      - changes
+      - affected-apps
     if: needs.changes.outputs.full_verification == 'true'
     runs-on: ubuntu-latest
     timeout-minutes: 20
@@ -112,16 +151,14 @@ jobs:
         run: |
           echo "TURBO_FILTER=--affected" >> "$GITHUB_ENV"
           echo "TURBO_SCM_BASE=origin/$BASE_REF" >> "$GITHUB_ENV"
-      - 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
@@ -130,8 +167,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
@@ -145,15 +180,12 @@ jobs:
         env:
           NEXT_TELEMETRY_DISABLED: "1"
       - name: Install Playwright browsers
+        env:
+          AFFECTED_APPS: ${{ needs.affected-apps.outputs.apps }}
         run: |
-          if [[ -n "${TURBO_FILTER-}" ]]; then
-            mapfile -t apps < <(bash .github/scripts/affected-apps.sh "$TURBO_SCM_BASE" HEAD)
-          else
-            mapfile -t apps < <(bash .github/scripts/affected-apps.sh)
-          fi
-          for app in "${apps[@]}"; do
+          while IFS= read -r app; do
             pnpm --filter "./apps/$app" exec playwright install --with-deps chromium
-          done
+          done < <(jq --raw-output '.[]' <<< "$AFFECTED_APPS")
       - name: Run end-to-end tests
         run: pnpm test:e2e
         env:
@@ -173,12 +205,35 @@ jobs:
           fi
 
   image:
-    name: Container Image
-    needs: changes
-    if: needs.changes.outputs.full_verification == 'true' || github.event_name == 'schedule'
+    name: Container Image (${{ matrix.app }})
+    needs:
+      - changes
+      - affected-apps
+    if: (needs.changes.outputs.full_verification == 'true' || github.event_name == 'schedule') && needs.affected-apps.outputs.apps != '[]'
     runs-on: ubuntu-latest
     timeout-minutes: 20
+    strategy:
+      fail-fast: false
+      matrix:
+        app: ${{ fromJSON(needs.affected-apps.outputs.apps) }}
+    services:
+      postgres:
+        image: postgres:17.11-alpine@sha256:266d3c257594e195b309ae9d1805e54c788f1d7b375f56bf6c367aac6c917e7b
+        env:
+          POSTGRES_PASSWORD: postgres
+          POSTGRES_DB: payload
+        ports:
+          - 5432:5432
+        options: >-
+          --health-cmd "pg_isready --username postgres"
+          --health-interval 5s
+          --health-timeout 5s
+          --health-retries 10
     env:
+      APP: ${{ matrix.app }}
+      DATABASE_URL: postgres://postgres:postgres@localhost:5432/payload
+      PAYLOAD_SECRET: ci-only-secret
+      APP_URL: http://localhost:3000
       HADOLINT_VERSION: 2.15.1
       HADOLINT_SHA256: c7187db94eeeeca956519a6af171adc31453941a1e777961f6e680f697c8c507
       TRIVY_VERSION: 0.76.1
@@ -187,112 +242,39 @@ jobs:
       - name: Checkout repository
         uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7
         with:
-          fetch-depth: 0
           persist-credentials: false
-      - name: Fetch the pull request base
-        if: github.event_name == 'pull_request'
-        env:
-          BASE_REF: ${{ github.base_ref }}
-        run: git fetch --no-tags origin "$BASE_REF"
-      - name: Set up Node.js and pnpm
-        uses: pnpm/setup@fbda4c85fc2e1e08721cd8763afea8f48d60f024 # v3.0.0
-        with:
-          cache: true
-          require-lockfile: true
-      - name: List affected apps
-        id: affected
-        env:
-          EVENT_NAME: ${{ github.event_name }}
-          BASE_REF: ${{ github.base_ref }}
-        run: |
-          if [[ "$EVENT_NAME" == "pull_request" ]]; then
-            mapfile -t apps < <(bash .github/scripts/affected-apps.sh "origin/$BASE_REF" HEAD)
-          else
-            mapfile -t apps < <(bash .github/scripts/affected-apps.sh)
-          fi
-          {
-            echo "app=false"
-            echo "backoffice=false"
-            for app in "${apps[@]}"; do
-              echo "$app=true"
-            done
-          } >> "$GITHUB_OUTPUT"
       - name: Lint Dockerfile
-        env:
-          AFFECTED_APP: ${{ steps.affected.outputs.app }}
-          AFFECTED_BACKOFFICE: ${{ steps.affected.outputs.backoffice }}
         run: |
           curl --silent --show-error --fail --location --output hadolint \
             "https://github.com/hadolint/hadolint/releases/download/v${HADOLINT_VERSION}/hadolint-linux-x86_64"
           echo "${HADOLINT_SHA256}  hadolint" | sha256sum --check --strict
           chmod +x hadolint
-          files=()
-          if [[ "$AFFECTED_APP" == "true" ]]; then
-            files+=(apps/app/Dockerfile)
-          fi
-          if [[ "$AFFECTED_BACKOFFICE" == "true" ]]; then
-            files+=(apps/backoffice/Dockerfile)
-          fi
-          if [[ "${#files[@]}" -gt 0 ]]; then
-            ./hadolint "${files[@]}"
-          fi
-      - name: Build images
-        env:
-          AFFECTED_APP: ${{ steps.affected.outputs.app }}
-          AFFECTED_BACKOFFICE: ${{ steps.affected.outputs.backoffice }}
-        run: |
-          if [[ "$AFFECTED_APP" == "true" ]]; then
-            docker build --file apps/app/Dockerfile --tag app:ci .
-          fi
-          if [[ "$AFFECTED_BACKOFFICE" == "true" ]]; then
-            docker build --file apps/backoffice/Dockerfile --tag backoffice:ci .
-          fi
-      - name: Smoke test images
-        env:
-          AFFECTED_APP: ${{ steps.affected.outputs.app }}
-          AFFECTED_BACKOFFICE: ${{ steps.affected.outputs.backoffice }}
+          ./hadolint "apps/$APP/Dockerfile"
+      - name: Build image
+        run: docker build --file "apps/$APP/Dockerfile" --tag "$APP:ci" .
+      - name: Smoke test image
         id: smoke
         run: |
-          if [[ "$AFFECTED_APP" == "true" ]]; then
-            docker run --detach --name app --env PORT=3000 --publish 3000:3000 app:ci
-            curl --silent --show-error --fail --retry 15 --retry-delay 1 --retry-all-errors --output /dev/null http://localhost:3000/health
-          fi
-          if [[ "$AFFECTED_BACKOFFICE" == "true" ]]; then
-            docker run --detach --name backoffice --env PORT=3001 --env DATABASE_URL=postgres://build-only@localhost/build-only --env PAYLOAD_SECRET=ci-only-secret --env APP_URL=http://localhost:3001 --publish 3001:3001 backoffice:ci
-            curl --silent --show-error --fail --retry 15 --retry-delay 1 --retry-all-errors --output /dev/null http://localhost:3001/health
-          fi
+          docker run --detach --name "$APP" --network host --env PORT=3000 --env DATABASE_URL --env PAYLOAD_SECRET --env APP_URL "$APP:ci"
+          curl --silent --show-error --fail --retry 15 --retry-delay 1 --retry-all-errors --output /dev/null http://localhost:3000/health
       - name: Show container logs
         if: failure() && steps.smoke.outcome == 'failure'
-        run: |
-          if docker container inspect app >/dev/null 2>&1; then
-            docker logs app
-          fi
-          if docker container inspect backoffice >/dev/null 2>&1; then
-            docker logs backoffice
-          fi
-      - name: Scan images for vulnerabilities
-        env:
-          AFFECTED_APP: ${{ steps.affected.outputs.app }}
-          AFFECTED_BACKOFFICE: ${{ steps.affected.outputs.backoffice }}
+        run: docker logs "$APP"
+      - name: Scan image for vulnerabilities
         run: |
           archive="trivy_${TRIVY_VERSION}_Linux-64bit.tar.gz"
           curl --silent --show-error --fail --location --output "$archive" \
             "https://github.com/aquasecurity/trivy/releases/download/v${TRIVY_VERSION}/${archive}"
           echo "${TRIVY_SHA256}  ${archive}" | sha256sum --check --strict
           tar --extract --gzip --file "$archive" trivy
-          if [[ "$AFFECTED_APP" == "true" ]]; then
-            ./trivy image --exit-code 1 --severity HIGH,CRITICAL --ignore-unfixed --no-progress app:ci
-          fi
-          if [[ "$AFFECTED_BACKOFFICE" == "true" ]]; then
-            ./trivy image --exit-code 1 --severity HIGH,CRITICAL --ignore-unfixed --no-progress backoffice:ci
-          fi
+          ./trivy image --exit-code 1 --severity HIGH,CRITICAL --ignore-unfixed --no-progress "$APP:ci"
 
   deploy-dev:
     name: Deploy to dev
     needs:
       - checks
       - image
-    if: github.event_name == 'push' && github.ref == 'refs/heads/main' && vars.DEPLOY_ENABLED == 'true'
+    if: ${{ !cancelled() && needs.checks.result == 'success' && contains(fromJSON('["success", "skipped"]'), needs.image.result) && github.event_name == 'push' && github.ref == 'refs/heads/main' && vars.DEPLOY_ENABLED == 'true' }}
     permissions:
       contents: read
       actions: read # Needed by deploy.yml to find the CI run of the deployed commit.
@@ -301,12 +283,67 @@ jobs:
       environment: dev
       commit_sha: ${{ github.sha }}
 
+  triage:
+    name: Triage failed build
+    needs:
+      - changes
+      - affected-apps
+      - 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()
     timeout-minutes: 5
     needs:
       - changes
+      - affected-apps
       - checks
       - image
     runs-on: ubuntu-latest

package/templates/turborepo/.github/workflows/deploy.yml

@@ -51,6 +51,7 @@ jobs:
           persist-credentials: false
       - name: Require the commit on main with passing CI and a deployment to the previous environment
         if: github.event_name == 'workflow_dispatch'
+        shell: bash
         env:
           GH_TOKEN: ${{ github.token }}
           REPOSITORY: ${{ github.repository }}
@@ -115,14 +116,16 @@ jobs:
           require-lockfile: true
       - name: List affected apps
         id: affected
+        shell: bash
         env:
           COMMIT_SHA: ${{ inputs.commit_sha }}
           GH_TOKEN: ${{ github.token }}
-          RAILWAY_ENVIRONMENT: ${{ inputs.environment }}
           REPOSITORY: ${{ github.repository }}
         run: |
           previous=""
           latest=""
+          deploy_runs="$(gh api --paginate "repos/$REPOSITORY/actions/workflows/deploy.yml/runs?status=success&branch=main&per_page=50" --jq '.workflow_runs[] | [.id, .display_title] | @tsv')"
+          ci_runs="$(gh api "repos/$REPOSITORY/actions/workflows/ci.yml/runs?event=push&branch=main&status=success&per_page=50" --jq '.workflow_runs[] | [.id, .head_sha] | @tsv')"
           while IFS=$'\t' read -r run_id title; do
             [[ -z "$run_id" ]] && continue
             if [[ "$title" =~ ^Deploy\ ([0-9a-f]{40})\ to\ ${RAILWAY_ENVIRONMENT}$ ]]; then
@@ -136,7 +139,7 @@ jobs:
               latest="$completed"
               previous="$candidate"
             fi
-          done < <(gh api --paginate "repos/$REPOSITORY/actions/workflows/deploy.yml/runs?status=success&branch=main&per_page=50" --jq '.workflow_runs[] | [.id, .display_title] | @tsv')
+          done <<< "$deploy_runs"
           while IFS=$'\t' read -r run_id head_sha; do
             [[ -z "$run_id" || "$head_sha" == "$COMMIT_SHA" ]] && continue
             completed="$(gh api "repos/$REPOSITORY/actions/runs/$run_id/jobs" | jq -r --arg env "$RAILWAY_ENVIRONMENT" '[.jobs[] | select(.conclusion == "success" and .name == "Deploy to \($env) / Deploy to \($env)") | .completed_at] | max // empty')"
@@ -144,20 +147,14 @@ jobs:
               latest="$completed"
               previous="$head_sha"
             fi
-          done < <(gh api "repos/$REPOSITORY/actions/workflows/ci.yml/runs?event=push&branch=main&status=success&per_page=50" --jq '.workflow_runs[] | [.id, .head_sha] | @tsv')
+          done <<< "$ci_runs"
           if [[ -n "$previous" ]]; then
             git cat-file -e "$previous^{commit}" 2>/dev/null || git fetch --no-tags origin "$previous"
-            mapfile -t apps < <(bash .github/scripts/affected-apps.sh "$previous" "$COMMIT_SHA")
+            apps="$(bash .github/scripts/affected-apps.sh "$previous" "$COMMIT_SHA")"
           else
-            mapfile -t apps < <(bash .github/scripts/affected-apps.sh)
+            apps="$(bash .github/scripts/affected-apps.sh)"
           fi
-          {
-            echo "app=false"
-            echo "backoffice=false"
-            for app in "${apps[@]}"; do
-              echo "$app=true"
-            done
-          } >> "$GITHUB_OUTPUT"
+          echo "apps=$apps" >> "$GITHUB_OUTPUT"
       - name: Install verified Railway CLI
         run: |
           archive="railway-v${RAILWAY_CLI_VERSION}-x86_64-unknown-linux-musl.tar.gz"
@@ -169,34 +166,38 @@ jobs:
       - name: Deploy
         env:
           RAILWAY_TOKEN: ${{ secrets.RAILWAY_TOKEN }}
-          DEPLOY_APP: ${{ steps.affected.outputs.app }}
-          DEPLOY_BACKOFFICE: ${{ steps.affected.outputs.backoffice }}
+          DEPLOY_APPS: ${{ steps.affected.outputs.apps }}
         run: |
-          if [[ "$DEPLOY_APP" == "true" ]]; then
+          affected() {
+            jq --exit-status --arg app "$1" 'index($app) != null' <<< "$DEPLOY_APPS" > /dev/null
+          }
+          if affected app; then
             railway up --ci --service "$RAILWAY_SERVICE_APP" --environment "$RAILWAY_ENVIRONMENT"
           fi
-          if [[ "$DEPLOY_BACKOFFICE" == "true" ]]; then
+          if affected backoffice; then
             railway up --ci --service "$RAILWAY_SERVICE_BACKOFFICE" --environment "$RAILWAY_ENVIRONMENT"
           fi
       - name: Require a healthy deployment
         env:
-          DEPLOY_APP: ${{ steps.affected.outputs.app }}
-          DEPLOY_BACKOFFICE: ${{ steps.affected.outputs.backoffice }}
+          DEPLOY_APPS: ${{ steps.affected.outputs.apps }}
         run: |
+          affected() {
+            jq --exit-status --arg app "$1" 'index($app) != null' <<< "$DEPLOY_APPS" > /dev/null
+          }
           wait_health() {
-            url="$1"
+            health_url="${1%/}/health"
             for _ in $(seq 30); do
-              if curl --silent --fail --output /dev/null "$url/health"; then
+              if curl --silent --fail --output /dev/null "$health_url"; then
                 return 0
               fi
               sleep 10
             done
-            echo "::error::$url/health did not respond"
+            echo "::error::$health_url did not respond"
             return 1
           }
-          if [[ "$DEPLOY_APP" == "true" ]]; then
+          if affected app; then
             wait_health "$APP_URL"
           fi
-          if [[ "$DEPLOY_BACKOFFICE" == "true" ]]; then
+          if affected backoffice; then
             wait_health "$BACKOFFICE_URL"
           fi

package/templates/turborepo/.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/turborepo/AGENTS.md

@@ -4,24 +4,24 @@ Turborepo workspace in TypeScript on pnpm and Node.js `>=24.22.1 <25`. `apps/app
 
 ## Commands
 
-| Task                          | Command                                                                                    |
-| :---------------------------- | :----------------------------------------------------------------------------------------- |
-| Start both apps with reload   | `pnpm dev`                                                                                 |
-| One test                      | `pnpm --filter ./apps/backoffice exec vitest run src/environment.test.ts -t "<test name>"` |
-| Tests in one app              | `TURBO_FILTER=--filter=./apps/app pnpm test`                                               |
-| Unit tests                    | `pnpm test`, or `pnpm test:coverage`                                                       |
-| End-to-end tests              | `pnpm test:e2e`                                                                            |
-| Regenerate after a collection | `pnpm generate:types`, `pnpm generate:importmap`                                           |
-| Create a migration            | `pnpm migrate:create <name>`                                                               |
-| What `pre-push` runs          | `pnpm check`                                                                               |
-| Every check                   | `pnpm verify`                                                                              |
-| Render rules after a change   | `pnpm rules:sync`                                                                          |
+| Task                               | Command                                                                                    | Healthy output                                                                                                               |
+| :--------------------------------- | :----------------------------------------------------------------------------------------- | :--------------------------------------------------------------------------------------------------------------------------- |
+| Start both apps with reload        | `pnpm dev`                                                                                 | `✓ Ready in 300ms` from each app                                                                                             |
+| One test                           | `pnpm --filter ./apps/backoffice exec vitest run src/environment.test.ts -t "<test name>"` | `Tests  1 passed \| 4 skipped (5)`                                                                                           |
+| Tests in one app                   | `TURBO_FILTER=--filter=./apps/app pnpm test`                                               | `Tasks:    1 successful, 1 total`                                                                                            |
+| Unit tests                         | `pnpm test`, or `pnpm test:coverage`                                                       | `Tasks:    2 successful, 2 total`                                                                                            |
+| End-to-end tests                   | `pnpm test:e2e`                                                                            | `Tasks:    4 successful, 4 total`, with `DATABASE_URL` pointing at a running database                                        |
+| Regenerate after a collection      | `pnpm generate:types`, `pnpm generate:importmap`                                           | `INFO: Compiling TS types for Collections and Globals...`, then nothing; `No new imports found, skipping writing import map` |
+| Create a migration                 | `pnpm migrate:create <name>`                                                               | `INFO: Migration created at` the new file under `migrations/`, then `INFO: Done.`                                            |
+| What `pre-push` runs               | `pnpm check`                                                                               | exits 0; the output ends with the summary `Tasks:    2 successful, 2 total`                                                  |
+| Every check except `pnpm test:e2e` | `pnpm verify`                                                                              | exits 0; the output ends with the summary `Tasks:    2 successful, 2 total`                                                  |
+| Render rules after a change        | `pnpm rules:sync`                                                                          | `Synced 69 agent rule files; 0 updated.`                                                                                     |
 
 ## Verifying your work
 
 - Build: `pnpm build` (prints `Tasks:    2 successful, 2 total`)
 - Test: `pnpm test:coverage` (all green, and prints `Tasks:    2 successful, 2 total`; never skip or delete a failing test)
-- Lint: `pnpm verify:static` (ESLint allows zero warnings; the dependency check prints `Tasks:    2 successful, 2 total`)
+- 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.
 
@@ -29,19 +29,20 @@ Run all three before reporting any task complete, and paste the output. `pnpm ve
 
 - Root scripts run lint, format, Knip, and the agent checks once for the workspace, and hand `build`, `test`, `typecheck`, and `depcruise` to Turborepo for each app. `TURBO_FILTER` narrows them; the default is every app.
 - The site lives in `apps/app/app/`. The backoffice site lives in `apps/backoffice/src/app/(frontend)/`, its collections in `apps/backoffice/src/collections/`, and its config in `apps/backoffice/src/payload.config.ts`. The root `generate:*` and `migrate*` scripts run in the backoffice.
-- In development, Payload applies collection changes to the database directly. In production, the backoffice applies the migrations in `apps/backoffice/src/migrations/` when it starts.
+- In development, Payload applies collection changes to the database directly. In production, the backoffice applies the migrations in `apps/backoffice/src/migrations/` when Payload first initialises, which `/health` triggers, so the first health check after a deploy applies them, not when the server starts.
 
 ## Conventions
 
-1. **Change the backoffice schema only through collections, then regenerate and commit.** Payload generates `apps/backoffice/src/app/(payload)/`, `apps/backoffice/src/payload-types.ts`, and `apps/backoffice/src/migrations/`; run `pnpm generate:types`, `pnpm generate:importmap`, and `pnpm migrate:create <name>`. Do not edit those files by hand.
+1. **Change the backoffice schema only through collections, then regenerate and commit.** Payload generates `apps/backoffice/src/payload-types.ts`, `apps/backoffice/src/migrations/`, and `apps/backoffice/src/app/(payload)/admin/importMap.ts`; run `pnpm generate:types`, `pnpm generate:importmap`, and `pnpm migrate:create <name>`. Do not edit those files by hand.
 2. **Put unit tests next to the code and Playwright end-to-end tests in `apps/app/test/` and `apps/backoffice/test/` as `*.e2e.test.ts`.** Vitest collects `apps/app/app/**/*.test.{ts,tsx}` and `apps/backoffice/src/**/*.test.{ts,tsx}`.
 3. **Component tests need a DOM test environment, and Vitest runs in Node.js.** Add that environment with the first component test.
 4. **Read backoffice configuration through `requireEnvironment` in `apps/backoffice/src/environment.ts`.** Document each variable in `.env.example`.
 5. **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.
-6. **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`.
+6. **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.
 7. **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.
 8. **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.
 9. **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.
+10. **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
 
@@ -49,4 +50,7 @@ When Claude makes a mistake twice, add the correction here.
 
 - **Next.js docs live per app**: this Next.js version differs from your training data. Read the guide in `apps/app/node_modules/next/dist/docs/` or `apps/backoffice/node_modules/next/dist/docs/` before writing Next.js code; the workspace root has no `next` package.
 - **Database for `pnpm dev` and end-to-end tests**: the backoffice needs a PostgreSQL database in `DATABASE_URL` and `PAYLOAD_SECRET` in `.env`; the README lists every variable. Run `pnpm --filter ./apps/app exec playwright install chromium` once before the first `pnpm test:e2e`.
-- **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/turborepo/CONTRIBUTING.md

@@ -5,10 +5,11 @@ Use this guide to prepare changes to this repository.
 ## Prerequisites
 
 - Use the Node.js version declared by `.nvmrc` and `package.json#engines`.
-- Change the Node.js version in `.nvmrc` and both Dockerfiles together. Dependabot updates only the Dockerfiles.
+- Change the Node.js version in `.nvmrc`, the `engines` field of the root and both app `package.json` files, and both Dockerfiles together. Dependabot updates only the Dockerfiles.
 - 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.
+- Copy `.env.example` to `.env` unless the CLI created it. `pnpm dev`, `pnpm build`, `pnpm check`, and `pnpm verify` need `DATABASE_URL`, `PAYLOAD_SECRET`, and `APP_URL` from it.
+- 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:
 
@@ -36,9 +37,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.
-- **End-to-end tests:** run `pnpm test:e2e` when you change pages or the admin panel. It starts both development servers unless they are already running, and the backoffice needs `DATABASE_URL` and `PAYLOAD_SECRET` from `.env`. Run `pnpm --filter ./apps/app exec playwright install chromium` once before the first run. CI runs it against the production build and a PostgreSQL service on every pull request that is ready for review and changes code.
+- **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 or the admin panel. It builds both apps first, then starts both development servers unless they are already running. The build and the backoffice need `DATABASE_URL`, `PAYLOAD_SECRET`, and `APP_URL` from `.env`. Run `pnpm --filter ./apps/app exec playwright install chromium` once before the first run. CI runs it against the production build and a PostgreSQL service on every pull request that is ready for review and changes code.
 - **Coverage:** CI requires 95% branch coverage on changed lines in `apps/app/app/` and `apps/backoffice/src/`, except layouts, the Payload config, and generated files.
+- **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/turborepo/README.md

@@ -1,6 +1,6 @@
 # next-friday-template-turborepo
 
-Next Friday starter for a Turborepo workspace. `apps/app` is a Next.js site on port 3000. `apps/backoffice` is a Payload CMS on port 3001. The backoffice API is REST at `/api`.
+Turborepo workspace. `apps/app` is a Next.js site on port 3000. `apps/backoffice` is a Payload CMS on port 3001. The backoffice API is REST at `/api`.
 
 ## Getting started
 
@@ -10,7 +10,7 @@ pnpm install
 pnpm dev
 ```
 
-The CLI created `.env` from `.env.example` and set `PAYLOAD_SECRET` to a random secret. Before `pnpm dev`, set in `.env`:
+The CLI created `.env` from `.env.example` and set `PAYLOAD_SECRET` to a random secret. Before `pnpm dev`, `pnpm build`, `pnpm check`, or `pnpm verify`, set in `.env`:
 
 - `DATABASE_URL`: a PostgreSQL database.
 - `APP_URL`: the URL you open the backoffice at, such as `http://localhost:3001`.
@@ -20,11 +20,11 @@ Then open `http://localhost:3000` for the site and `http://localhost:3001/admin`
 
 **Warning:** until the first user exists, anyone who can reach the backoffice `/admin` can create it. Create the first user in each deployed environment right after its first deploy, before you share the URL.
 
-In development, Payload applies collection changes to the database directly. In production, the server applies the migrations in `apps/backoffice/src/migrations/` when it starts.
+In development, Payload applies collection changes to the database directly. In production, Payload applies the migrations in `apps/backoffice/src/migrations/` when it first initialises, which the backoffice `/health` triggers, so the first health check after a deploy applies them and fails while the database is unreachable.
 
 ## 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 `apps/app/app/layout.tsx`, `apps/app/app/page.tsx`, and their tests, and the `Next Friday Payload template` text in `apps/backoffice/src/app/(frontend)/layout.tsx`, `apps/backoffice/src/app/(frontend)/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 `apps/app/app/layout.tsx`, `apps/app/app/page.tsx`, and `apps/app/app/page.test.ts`, and the `Payload application` text in `apps/backoffice/src/app/(frontend)/layout.tsx`, `apps/backoffice/src/app/(frontend)/page.tsx`, and `apps/backoffice/src/app/(frontend)/page.test.ts`.
 
 ## Scripts
 
@@ -42,13 +42,13 @@ 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 scans, 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`. Pull requests run Turborepo with `--affected` against the base branch, so only packages that changed are typed, tested, built, and scanned. Pushes to `main` and the weekly schedule still run every app. Patch coverage runs only for apps that produced a coverage file.
+CI also runs the build, the end-to-end tests, the container image scans, 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`. Pull requests run Turborepo with `--affected` against the base branch, so only packages that changed are typed, tested, built, and scanned. Pushes to `main` run every app. The weekly schedule rebuilds and scans every container image and runs nothing else. Patch coverage runs only for apps that produced a coverage file.
 
 To reuse task output across CI runs, create a Vercel team, add the repository variable `TURBO_TEAM`, and follow [Turborepo on GitHub Actions](https://turborepo.dev/docs/guides/ci-vendors/github-actions) to allow OIDC. The workflow exchanges GitHub OIDC for a short-lived Remote Cache token. If OIDC is unavailable, set the `TURBO_TOKEN` secret instead. Leave both unset to run without a Remote Cache.
 
 ## Container
 
-Each app has a Dockerfile. Build both from the workspace root. The images run as the `node` user. The app listens on `PORT`, or 3000 when it is unset. The backoffice listens on `PORT`, or 3000 when it is unset, and needs `DATABASE_URL`, `PAYLOAD_SECRET`, and `APP_URL`.
+Each app has a Dockerfile. Build both from the workspace root. The images run as the `node` user and listen on `PORT`, or 3000 when it is unset. The backoffice needs `DATABASE_URL`, `PAYLOAD_SECRET`, and `APP_URL`.
 
 ```sh
 docker build --file apps/app/Dockerfile --tag app .
@@ -81,14 +81,14 @@ On Vercel, deploy an app without its image. The Next.js preset takes precedence
 
    Limit `dev`, `uat`, and `prod` to the `main` branch. Add the release managers as required reviewers on `prod` only; `dev` deploys on every push to `main`, so a reviewer there would hold each push. Environment secrets and variables in a private repository need GitHub Pro, Team, or Enterprise; required reviewers in a private repository need GitHub Enterprise.
 
-3. Set the repository variable `DEPLOY_ENABLED` to `true`. Each push to `main` that passes CI then deploys to `dev`. The workflow compares the commit with the last GitHub deployment to that environment and runs `railway up` only for services whose packages changed. A promotion through `uat` or `prod` uses the same comparison against the commit last deployed there, so several commits still ship every changed service. The first deploy to an environment ships both services.
+3. Set the repository variable `DEPLOY_ENABLED` to `true`. Each push to `main` that passes CI then deploys to `dev`. The workflow compares the commit with the commit of the last successful deploy to that environment, found from the successful `deploy.yml` and `ci.yml` runs on `main`, and runs `railway up` only for services whose packages changed. A promotion through `uat` or `prod` uses the same comparison against the commit last deployed there, so several commits still ship every changed service. The first deploy to an environment ships both services.
 4. Promote with **Actions → Deploy → Run workflow**, giving the environment and the full commit SHA. The workflow requires a successful CI run on `main` for that commit and a successful deployment to the previous environment, then waits for `/health` on each service it uploaded.
 
 Remove the workflow, `railway.json`, and the `deploy-dev` job in `ci.yml` if the project deploys elsewhere.
 
 ## Mobile app
 
-The template does not ship an Expo app. Add one under `apps/mobile` when you need it:
+To add an Expo app, create it under `apps/mobile`:
 
 1. Create the app from the workspace root with `pnpm create expo-app@latest apps/mobile`, then add `packages/*` workspace packages as you share code. Keep `eas.json` and `credentials.json` inside `apps/mobile` and run the EAS CLI from that directory ([Expo: Build with monorepos](https://docs.expo.dev/build-reference/build-with-monorepos/)).
 2. Use `@expo/fingerprint` with `expo-github-action/fingerprint` so a pull request requests a native build only when the native layer changed ([Expo fingerprint](https://docs.expo.dev/versions/latest/sdk/fingerprint/)).