@next-friday/create-app 2.1.9 → 4.0.0

package/templates/base/.github/workflows/agent-evals.yml

@@ -0,0 +1,128 @@
+name: Agent evals
+
+on:
+  pull_request:
+    types: [opened, synchronize, reopened, ready_for_review]
+  schedule:
+    - cron: "0 2 * * *"
+
+permissions: {}
+
+concurrency:
+  group: ${{ github.workflow }}-${{ github.event.pull_request.number || github.run_id }}
+  cancel-in-progress: true
+
+jobs:
+  list:
+    name: List evals
+    runs-on: ubuntu-latest
+    timeout-minutes: 5
+    permissions:
+      contents: read
+    outputs:
+      evals: ${{ steps.list.outputs.evals }}
+    steps:
+      - name: Checkout repository
+        uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7
+        with:
+          fetch-depth: 0
+          persist-credentials: false
+      - name: List the evals to run
+        id: list
+        env:
+          EVENT_NAME: ${{ github.event_name }}
+          BASE_SHA: ${{ github.event.pull_request.base.sha }}
+        run: |
+          if [[ "$EVENT_NAME" == "schedule" ]] || git diff --name-only "$BASE_SHA" HEAD | grep -qE '^(CLAUDE\.md|AGENTS\.md|REVIEW\.md|\.mcp\.json|\.agents/|\.claude/|\.cursor/|evals/)'; then
+            echo "evals=$(find evals -maxdepth 1 -name '*.json' | sort | jq -R -s -c 'split("\n")[:-1]')" >> "$GITHUB_OUTPUT"
+          else
+            echo 'evals=[]' >> "$GITHUB_OUTPUT"
+          fi
+
+  eval:
+    name: Eval
+    needs: list
+    if: needs.list.outputs.evals != '[]'
+    runs-on: ubuntu-latest
+    timeout-minutes: 30
+    permissions:
+      contents: read
+      id-token: write # Needed to authenticate to Anthropic with the workflow's OIDC token.
+    strategy:
+      fail-fast: false
+      matrix:
+        eval: ${{ fromJSON(needs.list.outputs.evals) }}
+    steps:
+      - name: Checkout repository
+        uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7
+        with:
+          persist-credentials: false
+      - name: Set up Node.js and pnpm
+        uses: pnpm/setup@fbda4c85fc2e1e08721cd8763afea8f48d60f024 # v3.0.0
+        with:
+          cache: true
+          require-lockfile: true
+      - name: Read the eval prompt
+        id: read
+        env:
+          EVAL: ${{ matrix.eval }}
+        run: |
+          {
+            echo "prompt<<EVAL_PROMPT_END"
+            jq -r '.prompt' "$EVAL"
+            echo "EVAL_PROMPT_END"
+          } >> "$GITHUB_OUTPUT"
+      - name: Run the eval task
+        id: claude
+        uses: anthropics/claude-code-action@61a9c274fa7110a66dfafc1bbbced03833eb25fe # v1.0.269
+        with:
+          anthropic_federation_rule_id: ${{ vars.ANTHROPIC_FEDERATION_RULE_ID }}
+          anthropic_organization_id: ${{ vars.ANTHROPIC_ORGANIZATION_ID }}
+          prompt: ${{ steps.read.outputs.prompt }}
+          claude_args: --permission-mode acceptEdits --allowedTools "Read,Edit,Bash(pnpm test)"
+      - name: Check the result
+        env:
+          EVAL: ${{ matrix.eval }}
+          CONCLUSION: ${{ steps.claude.outputs.conclusion }}
+        run: ./evals/check.sh "$EVAL" "$CONCLUSION"
+
+  evals:
+    name: Agent evals
+    needs:
+      - list
+      - eval
+    if: always()
+    runs-on: ubuntu-latest
+    timeout-minutes: 5
+    permissions:
+      actions: read # Needed to read the result of each eval job.
+    steps:
+      - name: Check the pass rate
+        env:
+          EVALS: ${{ needs.list.outputs.evals }}
+          LIST_RESULT: ${{ needs.list.result }}
+          EVALS_MIN_PASS_RATE: ${{ vars.EVALS_MIN_PASS_RATE }}
+          GH_TOKEN: ${{ github.token }}
+          REPOSITORY: ${{ github.repository }}
+          RUN_ID: ${{ github.run_id }}
+        run: |
+          if [[ "$LIST_RESULT" != "success" ]]; then
+            echo "::error::Listing the evals failed."
+            exit 1
+          fi
+          total=$(jq 'length' <<< "$EVALS")
+          if ((total == 0)); then
+            echo "No evals to run."
+            exit 0
+          fi
+          if [[ -z "$EVALS_MIN_PASS_RATE" ]]; then
+            echo "::error::Set the repository variable EVALS_MIN_PASS_RATE (0 to 100)."
+            exit 1
+          fi
+          passed=$(gh api "repos/$REPOSITORY/actions/runs/$RUN_ID/jobs" --paginate --jq '.jobs[] | select((.name | startswith("Eval (")) and .conclusion == "success") | .id' | wc -l)
+          rate=$((passed * 100 / total))
+          echo "Pass rate: $rate% ($passed of $total)"
+          if ((rate < EVALS_MIN_PASS_RATE)); then
+            echo "::error::The pass rate $rate% is below EVALS_MIN_PASS_RATE ($EVALS_MIN_PASS_RATE%)."
+            exit 1
+          fi

package/templates/base/.github/workflows/claude.yml

@@ -0,0 +1,39 @@
+name: Claude
+
+on:
+  pull_request_review_comment:
+    types: [created]
+  pull_request_review:
+    types: [submitted]
+
+permissions: {}
+
+concurrency:
+  group: ${{ github.workflow }}-${{ github.event.pull_request.number }}
+  cancel-in-progress: false
+
+jobs:
+  claude:
+    name: Address review comment
+    if: |
+      (github.event_name == 'pull_request_review_comment' && contains(github.event.comment.body, '@claude')) ||
+      (github.event_name == 'pull_request_review' && contains(github.event.review.body, '@claude'))
+    runs-on: ubuntu-latest
+    timeout-minutes: 60
+    permissions:
+      contents: write # Needed to push the fix.
+      pull-requests: write # Needed to reply on the pull request.
+      id-token: write # Needed by the action to authenticate.
+      actions: read # Needed to read CI results on pull requests.
+    steps:
+      - name: Checkout repository
+        uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7
+        with:
+          fetch-depth: 1
+          persist-credentials: false
+      - name: Address the comment
+        uses: anthropics/claude-code-action@61a9c274fa7110a66dfafc1bbbced03833eb25fe # v1.0.269
+        with:
+          anthropic_federation_rule_id: ${{ vars.ANTHROPIC_FEDERATION_RULE_ID }}
+          anthropic_organization_id: ${{ vars.ANTHROPIC_ORGANIZATION_ID }}
+          claude_args: --permission-mode acceptEdits

package/templates/base/.github/zizmor.yml

@@ -1,4 +1,4 @@
-# Owner: @your-org/your-team. Reason: Semgrep rejects the `$/` self-repository syntax, so local actions use `./`. Expires: 2027-04-29.
+# Owner: @your-org/your-team. Reason: Semgrep rejects the `$/` self-repository syntax, so local actions use `./`.
 rules:
   self-repository:
     disable: true

package/templates/base/REVIEW.md

@@ -0,0 +1,21 @@
+# Review instructions
+
+## Passes
+
+Run three passes and tag each finding with its pass:
+
+- Bugs: logic errors, broken edge cases, subtle regressions
+- Security: injection risks, authentication gaps, PII in logs
+- Compliance: the change matches spec.md, plan.md and our design principles
+
+## What Important means here
+
+Reserve Important for findings that would break behavior, leak data or breach a policy. Style and naming are nits.
+
+## Cap the nits
+
+Report at most five nits per review; summarize the rest as a count.
+
+## Do not report
+
+Generated files under src/gen/ and anything CI already enforces.

package/templates/base/SETUP.md

@@ -0,0 +1,108 @@
+# Setup
+
+This project follows Anthropic's [AI-native SDLC Playbook](https://claude.com/resources/articles/the-ai-native-sdlc-playbook) in Claude Code and Cursor. Do the steps below in order. Each step says who does it and how to check that it is done.
+
+## How a change flows
+
+1. **Plan:** an idea, a ticket, or an incident becomes `intent/<change>/intent.md` (`write-intent` skill). The product owner merges or closes it.
+2. **Design:** `spec.md` is written from the accepted intent with the policy skills loaded (`write-spec` skill). The product owner resolves concerns with the policy owners.
+3. **Build:** the engineer starts in plan mode, approves the plan, and commits it as `plan.md`. A tech lead approves higher-risk plans.
+4. **Test:** the session runs **Verifying your work** in `AGENTS.md`; `evals/` tests the agent configuration.
+5. **Review:** Claude Code Review and Bugbot review by `REVIEW.md`; `@claude` on a review comment makes Claude push a fix. A code owner approves; the agent never does.
+6. **Deploy:** a failed build gets a triage summary on the pull request; `agent-production-gate.sh` gates production.
+7. **Maintain:** each incident gets a post-mortem in `lessons/` and an eval; larger work becomes a new `intent.md`.
+
+## 1. First commit and push
+
+**Who:** an engineer.
+
+1. Install gitleaks and jq (see [CONTRIBUTING.md](CONTRIBUTING.md)).
+2. Replace the template's description and owner: `package.json#description`, `repository.url`, and `author`, and any template text that `README.md` → **After creating a project from this template** lists. Change `license` from `UNLICENSED` if the project is open source.
+3. Create an empty repository on GitHub. Make the first commit on `main` and push it there. The Git hooks allow only this first commit and push on `main`; work on branches after that.
+
+   ```sh
+   git add --all
+   git commit -m "chore(repo): start from template"
+   git remote add origin https://github.com/OWNER/REPOSITORY.git
+   git push --set-upstream origin main
+   ```
+
+**Check:** `git log --oneline origin/main` prints one commit.
+
+## 2. Owners
+
+**Who:** an engineer, with the product owner, a lead, and each policy owner.
+
+In `.github/CODEOWNERS`, add these lines in this order. GitHub uses the last matching line for each file ([code owners](https://docs.github.com/en/repositories/managing-your-repositorys-settings-and-features/customizing-your-repository/about-code-owners)), so the line for every file comes first:
+
+```text
+* @your-org/your-team
+/intent/ @the-product-owner
+/.agents/skills/write-intent/ @the-lead-who-signs-off-the-intent-template
+/.agents/skills/brand-policy/ @the-brand-policy-owner
+/.agents/skills/security-policy/ @the-security-policy-owner
+/.agents/skills/compliance-policy/ @the-compliance-policy-owner
+/.agents/skills/ux-policy/ @the-ux-policy-owner
+```
+
+Also replace the owner placeholder in `.github/zizmor.yml`.
+
+**Check:** on GitHub, open `.github/CODEOWNERS`; GitHub shows no errors in the file.
+
+## 3. GitHub repository settings
+
+**Who:** a repository admin.
+
+- **Actions → General → Workflow permissions:** select **Read repository contents and packages permissions**. Every workflow requests the extra permissions it needs.
+- **Advanced Security:** enable private vulnerability reporting, Dependabot alerts, Dependabot security updates, secret scanning, and push protection. `SECURITY.md` sends reporters to private vulnerability reporting.
+- **Secrets and variables → Actions:**
+  - the variables `ANTHROPIC_FEDERATION_RULE_ID` and `ANTHROPIC_ORGANIZATION_ID`, from step 4. They are identifiers, not secrets: `.github/workflows/claude.yml`, `.github/workflows/agent-evals.yml`, and the **Triage failed build** job in `ci.yml` exchange the workflow's OIDC token for short-lived Claude API access, so the repository stores no Claude token.
+  - the variable `EVALS_MIN_PASS_RATE`, from 0 to 100, once the team has decided it (step 6).
+- **Rules → Rulesets:** protect `main` with:
+  - squash merges only, a linear history, and no force pushes or deletion;
+  - the required checks `All Checks`, `Validate pull request title`, and `Agent evals`;
+  - a pull request before merging, with at least one approval, review from Code Owners, and stale approvals dismissed when new commits are pushed. Claude Code Review follows the severity, exclusion, and nit-cap rules in `REVIEW.md` only on a default branch protected this way ([customize Code Review](https://code.claude.com/docs/en/code-review-customize)).
+
+  Rulesets in a private repository need GitHub Pro, Team, or Enterprise; on GitHub Free, make the repository public or upgrade.
+
+- Create the `needs triage` label, which the issue forms apply: `gh label create "needs triage"`.
+
+**Check:** a test pull request shows the three required checks and asks for a code owner's review.
+
+## 4. Claude
+
+**Who:** an Owner of the Claude organization, with an owner of the GitHub organization.
+
+- **Code Review:** in [**Admin settings → Claude Code**](https://claude.ai/admin-settings/claude-code#code-review), turn on **Allow code review**, install the Claude GitHub App, and add this repository ([set up Code Review](https://code.claude.com/docs/en/code-review-setup)). It needs a Team or Enterprise plan ([availability](https://code.claude.com/docs/en/code-review#availability)). Keep **Review runs** at **After every push**, the default, so every push to a pull request gets a review. Reviews run on Anthropic's infrastructure, so the repository has no review workflow. The same app also serves `.github/workflows/claude.yml`.
+- **Workload identity federation:** in the [Claude Console](https://platform.claude.com), under **Settings → Workload identity**, register the issuer `https://token.actions.githubusercontent.com`, create a service account in the workspace the workflows should use, and create a federation rule for it that matches this repository's subject prefix, `repo:OWNER/REPOSITORY:` ([setup](https://github.com/anthropics/claude-code-action/blob/main/docs/setup.md), [workload identity federation](https://platform.claude.com/docs/en/manage-claude/workload-identity-federation)). Put the rule's `fdrl_...` ID and the organization ID in the repository variables of step 3. Usage is billed to the Console organization.
+- **Managed settings:** deploy the non-negotiable settings and hooks as [managed settings](https://code.claude.com/docs/en/settings), tailored from the playbook's worked example in `.claude/managed-settings.example.json`. Engineers cannot override them.
+- **Monitoring:** turn on the [OpenTelemetry export](https://code.claude.com/docs/en/monitoring-usage) that the playbook's indicators read.
+
+**Check:** the test pull request gets a **Claude Code Review** check run within a few minutes. A review comment that tags `@claude` starts the **Claude** workflow.
+
+## 5. Cursor
+
+**Who:** a Cursor team admin.
+
+- **Bugbot:** enable the repository at [Bugbot](https://cursor.com/automations/from-cursor/bugbot). Bugbot reviews pull requests by the files `.cursor/BUGBOT.md` links, including `.agents/review.md`.
+- **Sandbox:** set the team's sandbox policy ([Cursor sandbox](https://cursor.com/docs/reference/sandbox)), which repository and user settings cannot weaken.
+
+**Check:** the test pull request gets a Bugbot review.
+
+## 6. Team decisions
+
+**Who:** the people named in each item.
+
+- **Sources of truth (engineering lead):** for each artifact, name one system as the source of truth: this repository, an existing tool such as Jira, or, as the minimum, a link both ways (the record id in the file and the commit SHA in the record).
+- **Higher risk (engineering lead):** decide which changes count as higher risk. A tech lead or architect approves their specs and plans.
+- **Policies (each policy owner, with an engineer):** write the policy in `.agents/skills/<area>-policy/SKILL.md` from the owner's source of truth, then run `pnpm rules:sync`. Test that the skill triggers: ask for the relevant task in different ways and confirm the skill loads each time. The policy owner approves every later change as its code owner.
+- **Production gate (engineering leadership, with change management and compliance):** list the approvals that must survive. A person then changes `.agents/hooks/agent-production-gate.sh` to match this project's production deploy command and approval; agent settings deny the file to agents.
+- **Review (tech lead):** replace `src/gen/` in `.agents/review.md` with this project's generated paths, then run `pnpm rules:sync`, which renders it to `REVIEW.md` for Claude Code Review. Once a month, rate the review findings and tune `.agents/review.md`.
+- **Evals (platform engineer):** collect 20 to 50 real tasks in `evals/` (`evals/README.md`), and set `EVALS_MIN_PASS_RATE` (step 3).
+- **People without Git experience:** connect GitHub to Claude (claude.ai or Cowork), so Claude commits `intent.md` for them.
+
+## 7. Later, as the guardrails mature
+
+- Run the `write-spec` skill by hand first, then as an organization-level slash command, then as a job that commits `spec.md` as a pull request when an `intent.md` merges.
+- Make auto mode the default for routine work: a tight `spec.md`, a small blast radius, and code the tests already cover.
+- Replace `bands.yaml` with this project's metric, add a unit-tested detection script that reads it, and add the trigger that runs it.

package/templates/base/bands.yaml

@@ -0,0 +1,10 @@
+# Placeholder: the example from the AI-native SDLC Playbook. Replace it with this project's metric, and add a
+# version-controlled, unit-tested detection script that reads this file. Detection stays deterministic, with no
+# model involved.
+metric: ci_test_failure_rate
+baseline: rolling_30d
+rules: western_electric
+tiers:
+  1sigma: {action: log}
+  2sigma: {action: diagnose, tools: "Read,Grep,Bash(gh run view *)"}
+  3sigma: {action: propose, routes: [pull_request, runbook:rollback-deploy]}

package/templates/base/evals/README.md

@@ -0,0 +1,15 @@
+# Agent evals
+
+Each eval is one real task from recent work with its accepted outcome, written as `evals/<name>.json`: the prompt, plus the check that defines an acceptable result.
+
+```json
+{
+  "prompt": "<the task, as a person would ask it>",
+  "check": "<a shell command that exits 0 when the result is acceptable, for example: pnpm test>"
+}
+```
+
+- Collect 20 to 50 real tasks from recent work.
+- `.github/workflows/agent-evals.yml` runs the suite every night, and on every pull request that changes `CLAUDE.md`, `AGENTS.md`, `.mcp.json`, `.agents/`, `.claude/`, `.cursor/`, or `evals/`. `evals/check.sh` checks one eval's result.
+- Set the repository variable `EVALS_MIN_PASS_RATE`, from 0 to 100. When the pass rate falls below it, the `Agent evals` check fails and the pull request cannot merge.
+- Each production incident gets an eval, written by the team that owned the incident, and it stays in the suite.

package/templates/base/evals/check.sh

@@ -0,0 +1,17 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+eval_file=$1
+conclusion=$2
+
+if [[ $conclusion != success ]]; then
+  echo "FAIL $eval_file: Claude Code reported $conclusion"
+  exit 1
+fi
+
+if bash -c "$(jq -r '.check' "$eval_file")"; then
+  echo "PASS $eval_file"
+else
+  echo "FAIL $eval_file"
+  exit 1
+fi

package/templates/base/intent/README.md

@@ -0,0 +1,8 @@
+# Intent
+
+This folder is the intent home. Every change starts here as an `intent.md`, and its record stays here. Git history keeps the author, the time, and every revision of each file.
+
+- Each change has its own folder, `intent/<change>/`, where `<change>` is a short kebab-case name. The folder holds `intent.md` (Plan), then `spec.md` (Design), then `plan.md` (Build).
+- **Plan.** An idea, a ticket, or an incident becomes `intent.md`, written with the `write-intent` skill. The product owner reviews and corrects it before it is committed. Merging its pull request accepts it; closing the pull request rejects it.
+- **Design.** The `write-spec` skill turns the accepted `intent.md` into `spec.md`, committed alongside it. The product owner reviews the spec against the idea and resolves each area of concern with its policy owner. Accepting the spec starts the build.
+- **Build.** The engineer starts in plan mode with `intent.md` and `spec.md`, and commits the approved plan as `plan.md`. When implementation departs from the plan, `plan.md` changes in the same commit.

package/templates/base/lessons/README.md

@@ -0,0 +1,3 @@
+# Lessons
+
+Post-mortems, one version-controlled file per incident, named like `lessons/2026-06-checkout-cache.md`. Future investigations read them. When the fix ships, add an eval for the incident, as `evals/README.md` describes.

package/templates/base/scripts/sync-agent-rules.ts

@@ -1,4 +1,4 @@
-import {existsSync, readdirSync, readFileSync, writeFileSync} from "node:fs";
+import {existsSync, mkdirSync, readdirSync, readFileSync, writeFileSync} from "node:fs";
 import path from "node:path";
 
 type RuleConfig = {
@@ -6,6 +6,12 @@ type RuleConfig = {
   globs?: string[];
 };
 
+type SubagentConfig = {
+  description: string;
+  readonly?: boolean;
+  tools?: string[];
+};
+
 const sourceDirectory = ".agents/rules";
 const configPath = ".agents/rules.json";
 
@@ -85,9 +91,109 @@ for (const [file, content] of Object.entries(claudeExtras)) {
   expected.set(path.join(claudeDirectory, file), content);
 }
 
+const skillSourceDirectory = ".agents/skills";
+const skillDirectories = [".claude/skills", ".cursor/skills"];
+const subagentSourceDirectory = ".agents/agents";
+const subagentConfigPath = ".agents/agents.json";
+const claudeSubagentDirectory = ".claude/agents";
+const cursorSubagentDirectory = ".cursor/agents";
+
+/**
+ * List every file under a directory, as paths relative to it.
+ * @param directory Directory to read; a missing directory has no files.
+ * @returns Relative file paths.
+ */
+function listFiles(directory: string): string[] {
+  return existsSync(directory)
+    ? readdirSync(directory, {
+        recursive: true,
+        withFileTypes: true,
+      })
+        .filter(entry => entry.isFile())
+        .map(entry => path.relative(directory, path.join(entry.parentPath, entry.name)))
+    : [];
+}
+
+/**
+ * Render a subagent with the frontmatter fields its tool reads.
+ * @param name Subagent name.
+ * @param fields Frontmatter fields after `name` and `description`.
+ * @param subagent Subagent configuration.
+ * @param body Shared subagent body.
+ * @returns The subagent file content.
+ */
+function renderSubagent(
+  name: string,
+  fields: string[],
+  subagent: SubagentConfig,
+  body: string,
+): string {
+  return [
+    `---`,
+    `name: ${name}`,
+    `description: ${subagent.description}`,
+    ...fields,
+    `---`,
+    ``,
+    body,
+  ].join("\n");
+}
+
+for (const file of listFiles(skillSourceDirectory)) {
+  const content = readFileSync(path.join(skillSourceDirectory, file), "utf8");
+
+  for (const directory of skillDirectories) {
+    expected.set(path.join(directory, file), content);
+  }
+}
+
+const subagents = existsSync(subagentConfigPath)
+  ? (JSON.parse(readFileSync(subagentConfigPath, "utf8")) as Record<string, SubagentConfig>)
+  : {};
+
+for (const [name, subagent] of Object.entries(subagents)) {
+  const body = readFileSync(path.join(subagentSourceDirectory, `${name}.md`), "utf8");
+  const claudeFields = subagent.tools === undefined ? [] : [`tools: ${subagent.tools.join(", ")}`];
+  const cursorFields = subagent.readonly === undefined ? [] : [`readonly: ${subagent.readonly}`];
+
+  expected.set(
+    path.join(claudeSubagentDirectory, `${name}.md`),
+    renderSubagent(name, claudeFields, subagent, body),
+  );
+
+  expected.set(
+    path.join(cursorSubagentDirectory, `${name}.md`),
+    renderSubagent(name, cursorFields, subagent, body),
+  );
+}
+
+const sharedFiles: Record<string, string[]> = {
+  ".agents/mcp.json": [".mcp.json", ".cursor/mcp.json"],
+  ".agents/review.md": ["REVIEW.md"],
+};
+
+const sharedSources = Object.entries(sharedFiles).filter(([source]) => existsSync(source));
+
+for (const [source, targets] of sharedSources) {
+  const content = readFileSync(source, "utf8");
+
+  for (const target of targets) {
+    expected.set(target, content);
+  }
+}
+
 const orphans = [
   ...listNames(claudeDirectory, ".md").map(name => path.join(claudeDirectory, `${name}.md`)),
   ...listNames(cursorDirectory, ".mdc").map(name => path.join(cursorDirectory, `${name}.mdc`)),
+  ...skillDirectories.flatMap(directory =>
+    listFiles(directory).map(file => path.join(directory, file)),
+  ),
+  ...[claudeSubagentDirectory, cursorSubagentDirectory].flatMap(directory =>
+    listFiles(directory).map(file => path.join(directory, file)),
+  ),
+  ...Object.values(sharedFiles)
+    .flat()
+    .filter(file => existsSync(file)),
 ].filter(file => !expected.has(file));
 
 if (orphans.length > 0) {
@@ -104,6 +210,10 @@ const staleFiles = [...expected].filter(
 
 if (!isCheckOnly) {
   for (const [file, content] of staleFiles) {
+    mkdirSync(path.dirname(file), {
+      recursive: true,
+    });
+
     writeFileSync(file, content);
   }
 }

package/templates/nestjs/.agents/agents/verifier.md

@@ -0,0 +1 @@
+Start the app with `pnpm start:dev`. Exercise the changed behavior and the two nearest neighboring flows. Report what you ran, what you saw, and any behavior that does not match plan.md. Do not fix anything; report only.

package/templates/nestjs/.agents/rules.json

@@ -12,7 +12,25 @@
     "description": "Codebase hygiene: modify existing code instead of accumulating new code"
   },
   "constitution-changes": {
-    "description": "Constitution changes: change rules, hooks, and agent settings only through a dedicated issue"
+    "description": "Constitution changes: change rules, hooks, and agent settings only through a dedicated issue",
+    "globs": [
+      ".agents/rules/**",
+      ".agents/rules.json",
+      ".agents/hooks/**",
+      ".claude/settings.json",
+      ".claude/rules/**",
+      ".cursor/rules/**",
+      ".cursor/hooks/**",
+      ".cursor/hooks.json",
+      "scripts/sync-agent-rules.ts",
+      "scripts/check-agent-gates.ts",
+      ".husky/**",
+      ".commitlintrc.json",
+      ".prettierrc.json",
+      "eslint.config.ts",
+      ".lintstagedrc.json",
+      ".gitleaks.toml"
+    ]
   },
   "current-state-authority": {
     "description": "Current state: implement from user requirements and the working tree"
@@ -32,28 +50,24 @@
     "globs": ["**/*.test.ts"]
   },
   "diagnostics-and-error-handling": {
-    "description": "Diagnostics: fix runtime failures at the source and keep the root cause"
+    "description": "Diagnostics: fix runtime failures at the source and keep the root cause",
+    "globs": ["**/*.ts", "**/*.js"]
   },
   "evidence-before-claims": {
     "description": "Evidence: verify and cite a claim before stating or writing it"
   },
-  "git-workflow": {
-    "description": "Git workflow: trunk-based branches, commits, and pull requests"
-  },
   "no-suppression": {
     "description": "Findings: fix scanner and linter reports without inline suppressions"
   },
   "platform-and-library-first": {
     "description": "Platform and library first: use built-in features, then maintained libraries, then custom code"
   },
-  "script-driven-changes": {
-    "description": "Scripts: apply a repeated edit across many files with a script"
-  },
   "single-author-style": {
     "description": "Sibling style: match layout, naming, and composition in the same project"
   },
   "structured-logging": {
-    "description": "Logging: log through a logging library in structured, durable records"
+    "description": "Logging: log through a logging library in structured, durable records",
+    "globs": ["**/*.ts", "**/*.js"]
   },
   "typescript-first": {
     "description": "TypeScript-first: write source, tests, and scripts as .ts",

package/templates/nestjs/.claude/agents/verifier.md

@@ -0,0 +1,7 @@
+---
+name: verifier
+description: Runs the app and checks the change works before the session reports done
+tools: Bash, Read
+---
+
+Start the app with `pnpm start:dev`. Exercise the changed behavior and the two nearest neighboring flows. Report what you ran, what you saw, and any behavior that does not match plan.md. Do not fix anything; report only.

package/templates/nestjs/.claude/rules/constitution-changes.md

@@ -0,0 +1,25 @@
+---
+paths:
+  - ".agents/rules/**"
+  - ".agents/rules.json"
+  - ".agents/hooks/**"
+  - ".claude/settings.json"
+  - ".claude/rules/**"
+  - ".cursor/rules/**"
+  - ".cursor/hooks/**"
+  - ".cursor/hooks.json"
+  - "scripts/sync-agent-rules.ts"
+  - "scripts/check-agent-gates.ts"
+  - ".husky/**"
+  - ".commitlintrc.json"
+  - ".prettierrc.json"
+  - "eslint.config.ts"
+  - ".lintstagedrc.json"
+  - ".gitleaks.toml"
+---
+
+# Constitution Changes
+
+The constitution is the set of files that agent settings deny to agents: rules, hooks, lint, format, and commit configuration, and the agent settings themselves. It is company policy.
+
+A developer changes the constitution through a dedicated issue, never inside a feature pull request. When a task needs a constitution change, propose it to the user, reference that issue, and wait for it to merge before the task depends on it.

package/templates/nestjs/.claude/rules/diagnostics-and-error-handling.md

@@ -0,0 +1,13 @@
+---
+paths:
+  - "**/*.ts"
+  - "**/*.js"
+---
+
+# Diagnostics
+
+Resolve runtime failures at the source with the language's standard narrowing, validation, and error types. For missing third-party types, take upstream definitions or a narrow adapter in the established location.
+
+Surface errors at the caller or process boundary with diagnostic context. Handle an error to add context, recover, or translate it at an application boundary. Retain the root cause through the language's exception mechanism.
+
+Report unresolved type, declaration, or rule conflicts to the user. Findings follow `no-suppression.md`.

package/templates/nestjs/.claude/rules/structured-logging.md

@@ -0,0 +1,9 @@
+---
+paths:
+  - "**/*.ts"
+  - "**/*.js"
+---
+
+# Logging
+
+Application code logs through the stack's logging library or the framework's logger, never `console.*`. Write structured records, and send them to a store that keeps them longer than the host does.

package/templates/nestjs/.cursor/agents/verifier.md

@@ -0,0 +1,7 @@
+---
+name: verifier
+description: Runs the app and checks the change works before the session reports done
+readonly: true
+---
+
+Start the app with `pnpm start:dev`. Exercise the changed behavior and the two nearest neighboring flows. Report what you ran, what you saw, and any behavior that does not match plan.md. Do not fix anything; report only.

package/templates/{base → nestjs}/.cursor/rules/constitution-changes.mdc

@@ -1,6 +1,7 @@
 ---
 description: "Constitution changes: change rules, hooks, and agent settings only through a dedicated issue"
-alwaysApply: true
+globs: ".agents/rules/**,.agents/rules.json,.agents/hooks/**,.claude/settings.json,.claude/rules/**,.cursor/rules/**,.cursor/hooks/**,.cursor/hooks.json,scripts/sync-agent-rules.ts,scripts/check-agent-gates.ts,.husky/**,.commitlintrc.json,.prettierrc.json,eslint.config.ts,.lintstagedrc.json,.gitleaks.toml"
+alwaysApply: false
 ---
 
 # Constitution Changes

package/templates/{base → nestjs}/.cursor/rules/diagnostics-and-error-handling.mdc

@@ -1,6 +1,7 @@
 ---
 description: "Diagnostics: fix runtime failures at the source and keep the root cause"
-alwaysApply: true
+globs: "**/*.ts,**/*.js"
+alwaysApply: false
 ---
 
 # Diagnostics