@next-friday/create-app 2.1.9 → 3.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/.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/.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/nestjs/.github/workflows/ci.yml

@@ -166,6 +166,50 @@ jobs:
       environment: dev
       commit_sha: ${{ github.sha }}
 
+  triage:
+    name: Triage failed build
+    needs:
+      - checks
+      - image
+    if: failure() && 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 to Anthropic with the workflow's OIDC token.
+      pull-requests: write # Needed to post the summary on the pull request.
+    steps:
+      - 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 "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_federation_rule_id: ${{ vars.ANTHROPIC_FEDERATION_RULE_ID }}
+          anthropic_organization_id: ${{ vars.ANTHROPIC_ORGANIZATION_ID }}
+          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: >-
+            --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/nestjs/AGENTS.md

@@ -14,19 +14,32 @@ NestJS HTTP API in TypeScript on pnpm and Node.js `>=24.15.0 <25`.
 | Every check                 | `pnpm verify`                                       |
 | Render rules after a change | `pnpm rules:sync`                                   |
 
-## How it fits together
+## 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`)
+
+Run all three before reporting any task complete, and paste the output. `pnpm verify` runs all three.
+If a test fails, fix the code, not the test.
+
+## Architecture
 
 - `src/main.ts` creates the app from `AppModule` on `parsePort(process.env.PORT)` with Nest's `ConsoleLogger`, which writes JSON lines when `NODE_ENV` is `production`.
 - `AppModule` imports `HealthModule`, whose Terminus controller serves `/health`. Add a feature as its own module and import it in `AppModule`.
 
-## Mandatory rules
+## Conventions
 
-1. **Follow `.agents/rules/`.** `.agents/rules.json` gives each rule's scope; Claude Code and Cursor load them. After changing either, run `pnpm rules:sync`; `pnpm check` fails on stale copies.
+1. **Follow `.agents/rules/`.** `.agents/rules.json` gives each rule's scope; Claude Code and Cursor load them. After changing either, or a skill or subagent in `.agents/skills/` or `.agents/agents/`, run `pnpm rules:sync`; `pnpm check` fails on stale copies.
 2. **Put unit tests next to the code as `src/**/*.test.ts` and end-to-end tests in `test/` as `*.e2e.test.ts`.** `vitest.config.ts` and `vitest.e2e.config.ts` collect only those patterns.
 3. **Read configuration from environment variables and fail when one is missing**, as `parsePort` does. Document each variable in `.env.example`.
 4. **Log through Nest's `Logger`.** It goes to the `ConsoleLogger` set in `src/main.ts`.
+5. **Start from the accepted spec, in plan mode.** Claude Code starts every session in plan mode (`.claude/settings.json`); in Cursor, switch to Plan Mode before the first edit. Give the plan the change's `intent/<change>/intent.md` and `spec.md`, and have it name the files that change, the order of the work, and the tests that prove it. Commit the approved plan as `intent/<change>/plan.md`. When implementation departs from the plan, update `plan.md` in the same commit.
+6. **Start a bug fix with a failing test.** Reproduce the bug as a test, run it, and confirm it fails for the reason you expect. Commit that test. Then create `.git/bug-fix-in-progress`, so `.agents/hooks/agent-test-edit-gate.sh` blocks test edits, and make the test pass without editing it. Delete `.git/bug-fix-in-progress` when the fix is done.
+
+## Things Claude gets wrong
 
-## Known pitfalls
+When Claude makes a mistake twice, add the correction here.
 
 - **Agent shell gate**: `.agents/hooks/agent-shell-gate.sh` blocks a shell command that writes to a protected path such as `.agents`, `.cursor`, `.claude/rules`, or `.husky`. It is a convenience, not a security boundary: CI and code-owner review are the boundary.
 

package/templates/nestjs/README.md

@@ -14,22 +14,7 @@ The server listens on the port set by `PORT` in `.env`, which the CLI created fr
 
 ## After creating a project from this template
 
-1. Install gitleaks and jq (see [CONTRIBUTING.md](CONTRIBUTING.md)). Make the first commit on `main` and push it. 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 push --set-upstream origin main
-   ```
-
-2. Add your team as the owner of every file in `.github/CODEOWNERS`, and replace the owner placeholder in `.github/zizmor.yml`.
-3. Replace the template's description and owner: `package.json#description`, `repository.url`, and `author`. Change `license` from `UNLICENSED` if the project is open source.
-4. In the repository settings:
-   - **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.
-   - **Cursor Bugbot:** enable the repository at [Bugbot](https://cursor.com/automations/from-cursor/bugbot). Bugbot reviews pull requests against the rules linked from `.cursor/BUGBOT.md`.
-   - **Rules → Rulesets:** protect `main` with squash merges only, a linear history, no force pushes or deletion, and the required checks `All Checks` and `Validate pull request title`. 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"`.
+Follow [SETUP.md](SETUP.md) in order. It sets up the repository, the reviews, and the AI-native SDLC.
 
 ## Scripts
 

package/templates/nextjs/.agents/agents/verifier.md

@@ -0,0 +1 @@
+Start the app with `pnpm 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/nextjs/.agents/mcp.json

@@ -0,0 +1,8 @@
+{
+  "mcpServers": {
+    "playwright": {
+      "command": "npx",
+      "args": ["@playwright/mcp@0.0.83"]
+    }
+  }
+}