@next-friday/create-app 9.0.0 → 9.1.1

package/templates/base/scripts/check-intent.ts

@@ -0,0 +1,391 @@
+import {existsSync, readFileSync} from "node:fs";
+
+type Problem = {
+  line: number;
+  message: string;
+};
+
+type Heading = {
+  line: number;
+  text: string;
+};
+
+type SelfTestCase = {
+  expectedMessagePart?: string;
+  name: string;
+  text: string;
+};
+
+const problemHeading = "## Problem";
+const constraintsHeading = "## Constraints";
+const openQuestionsHeading = "## Open questions";
+
+const requiredHeadings = [
+  problemHeading,
+  "## Proposed outcome",
+  "## Affected users and systems",
+  constraintsHeading,
+  openQuestionsHeading,
+];
+
+const titlePattern = /^# Intent: \S/;
+const statusPattern = /Status: (?:draft|accepted|rejected)\.$/;
+
+/**
+ * Blank every line of a fenced code block, keeping line numbers.
+ * @param text Intent content with LF line endings.
+ * @returns The content with fenced lines emptied.
+ */
+function maskFencedBlocks(text: string): string {
+  let isFenced = false;
+
+  return text
+    .split("\n")
+    .map(line => {
+      const isFence = /^\s*(?:```|~~~)/.test(line);
+      const isMasked = isFenced || isFence;
+
+      isFenced = isFence ? !isFenced : isFenced;
+
+      return isMasked ? "" : line;
+    })
+    .join("\n");
+}
+
+/**
+ * Find a first line that is not `# Intent: <title>`.
+ * @param lines Intent lines.
+ * @returns At most one problem.
+ */
+function findTitleProblems(lines: string[]): Problem[] {
+  return titlePattern.test(lines.at(0) ?? "")
+    ? []
+    : [
+        {
+          message:
+            'line 1 must be "# Intent: <title>" with a non-empty title; write the change\'s name after "# Intent: "',
+          line: 1,
+        },
+      ];
+}
+
+/**
+ * Find a missing or malformed author line.
+ * @param lines Intent lines.
+ * @returns At most one problem.
+ */
+function findAuthorProblems(lines: string[]): Problem[] {
+  const authorLines = lines
+    .map((text, index) => ({
+      line: index + 1,
+      text: text.trimEnd(),
+    }))
+    .filter(({text}) => text.startsWith("Author: "));
+
+  if (authorLines.length > 1) {
+    return [
+      {
+        message: 'only one author line is allowed; remove the extra "Author: " line',
+        line: authorLines.at(1)?.line ?? 1,
+      },
+    ];
+  }
+
+  const authorLine = authorLines.at(0);
+
+  return authorLine !== undefined && statusPattern.test(authorLine.text)
+    ? []
+    : [
+        {
+          message:
+            'an author line must start with "Author: " and end with "Status: draft.", "Status: accepted." or "Status: rejected."; write "Author: <name> (<team>). Status: draft."',
+          line: authorLine?.line ?? 1,
+        },
+      ];
+}
+
+/**
+ * Quote each heading and join them for a message.
+ * @param headings Heading texts.
+ * @returns The quoted list, or "none" when there is no heading.
+ */
+function quoteHeadings(headings: string[]): string {
+  return headings.length === 0 ? "none" : headings.map(heading => `"${heading}"`).join(", ");
+}
+
+/**
+ * Find level-2 headings that differ from the template's, in count, spelling, or order.
+ * @param headings The level-2 headings with their line numbers.
+ * @returns At most one problem.
+ */
+function findHeadingProblems(headings: Heading[]): Problem[] {
+  const texts = headings.map(({text}) => text);
+  const expected = quoteHeadings(requiredHeadings);
+
+  return texts.join("\n") === requiredHeadings.join("\n")
+    ? []
+    : [
+        {
+          line: headings.at(0)?.line ?? 1,
+          message: `the level-2 headings must be exactly, in order: ${expected}; found ${quoteHeadings(texts)}`,
+        },
+      ];
+}
+
+/**
+ * Find sections without text.
+ * @param lines Intent lines.
+ * @param headings The level-2 headings with their line numbers.
+ * @returns One problem per empty section.
+ */
+function findEmptySectionProblems(lines: string[], headings: Heading[]): Problem[] {
+  return headings
+    .filter(({line}, index) => {
+      const end = headings.at(index + 1)?.line ?? lines.length + 1;
+
+      return (
+        lines
+          .slice(line, end - 1)
+          .join("\n")
+          .trim() === ""
+      );
+    })
+    .map(({line, text}) => ({
+      line,
+      message: `the section "${text}" is empty; write its text or its open question`,
+    }));
+}
+
+/**
+ * Find a Problem section that holds no digit outside fenced code blocks.
+ * @param lines Intent lines.
+ * @param maskedLines Intent lines with fenced code blocks emptied.
+ * @param headings The level-2 headings with their line numbers.
+ * @returns At most one problem.
+ */
+function findProblemNumberProblems(
+  lines: string[],
+  maskedLines: string[],
+  headings: Heading[],
+): Problem[] {
+  const index = headings.findIndex(({text}) => text === problemHeading);
+  const start = headings.at(index)?.line;
+
+  if (start === undefined) {
+    return [];
+  }
+
+  const end = headings.at(index + 1)?.line ?? lines.length + 1;
+  const body = lines.slice(start, end - 1).join("\n");
+  const unfencedBody = maskedLines.slice(start, end - 1).join("\n");
+
+  return body.trim() === "" || /\d/.test(unfencedBody)
+    ? []
+    : [
+        {
+          line: start,
+          message: `the section "${problemHeading}" has no number; state the measured value, its source, and the time`,
+        },
+      ];
+}
+
+/**
+ * Check one intent against the template in `.agents/skills/sdlc/playbooks/plan.md`.
+ * @param text Intent content.
+ * @returns Every problem found.
+ */
+function checkIntent(text: string): Problem[] {
+  const lines = text
+    .replace(/^\u{FEFF}/u, "")
+    .replaceAll("\r\n", "\n")
+    .split("\n");
+
+  const maskedLines = maskFencedBlocks(lines.join("\n")).split("\n");
+
+  const headings = maskedLines
+    .map((line, index) => ({
+      line: index + 1,
+      text: line.trimEnd(),
+    }))
+    .filter(({text: heading}) => heading.startsWith("## "));
+
+  return [
+    ...findTitleProblems(maskedLines),
+    ...findAuthorProblems(maskedLines),
+    ...findHeadingProblems(headings),
+    ...findEmptySectionProblems(lines, headings),
+    ...findProblemNumberProblems(lines, maskedLines, headings),
+  ];
+}
+
+const titleLine = "# Intent: Health check answers 200";
+const authorLine = "Author: maintain job (alert 1). Status: draft.";
+const problemText = "GET /health returned 500 on 12 of 12 requests, from the alert log.";
+const constraintsSection = `${constraintsHeading}\n\nNone.\n\n`;
+const headingsPart = "level-2 headings";
+const authorPart = "author line";
+const statusDraft = "Status: draft.";
+
+const validIntent = [
+  titleLine,
+  "",
+  authorLine,
+  "",
+  problemHeading,
+  "",
+  problemText,
+  "",
+  "## Proposed outcome",
+  "",
+  "GET /health answers 200.",
+  "",
+  "## Affected users and systems",
+  "",
+  "The load balancer.",
+  "",
+  constraintsHeading,
+  "",
+  "None.",
+  "",
+  openQuestionsHeading,
+  "",
+  "Which commit broke it?",
+  "",
+].join("\n");
+
+const selfTestCases: SelfTestCase[] = [
+  {
+    text: validIntent,
+    name: "a complete intent",
+  },
+  {
+    name: "CRLF line endings",
+    text: validIntent.replaceAll("\n", "\r\n"),
+  },
+  {
+    name: "headings inside a fenced block are ignored",
+    text: validIntent.replace("None.", "```\n## Extra\n```"),
+  },
+  {
+    expectedMessagePart: "line 1",
+    name: "title is missing",
+    text: validIntent.replace(titleLine, "# Health check"),
+  },
+  {
+    expectedMessagePart: "line 1",
+    name: "title is empty",
+    text: validIntent.replace(titleLine, "# Intent: "),
+  },
+  {
+    expectedMessagePart: authorPart,
+    name: "author line is missing",
+    text: validIntent.replace(`${authorLine}\n`, ""),
+  },
+  {
+    expectedMessagePart: authorPart,
+    name: "status is not a known value",
+    text: validIntent.replace(statusDraft, "Status: open."),
+  },
+  {
+    expectedMessagePart: authorPart,
+    name: "status has no final period",
+    text: validIntent.replace(statusDraft, "Status: draft"),
+  },
+  {
+    expectedMessagePart: headingsPart,
+    name: "a heading is missing",
+    text: validIntent.replace(constraintsSection, ""),
+  },
+  {
+    expectedMessagePart: headingsPart,
+    name: "a heading is misspelled",
+    text: validIntent.replace(constraintsHeading, "## Constraint"),
+  },
+  {
+    expectedMessagePart: headingsPart,
+    name: "headings are out of order",
+    text: [
+      validIntent.split("\n## ", 1).at(0),
+      ...validIntent.split("\n## ").slice(1).toReversed(),
+    ].join("\n## "),
+  },
+  {
+    expectedMessagePart: headingsPart,
+    name: "an extra heading",
+    text: `${validIntent}\n## Extra\n\nText.\n`,
+  },
+  {
+    name: "a BOM before the title",
+    text: `\u{FEFF}${validIntent}`,
+  },
+  {
+    expectedMessagePart: authorPart,
+    name: "status is not at the end of the author line",
+    text: validIntent.replace(statusDraft, "Status: draft. Reviewed."),
+  },
+  {
+    expectedMessagePart: authorPart,
+    name: "a second author line",
+    text: `${validIntent}\nAuthor: second. Status: draft.\n`,
+  },
+  {
+    expectedMessagePart: "is empty",
+    name: "a section is empty",
+    text: validIntent.replace("None.", ""),
+  },
+  {
+    expectedMessagePart: "has no number",
+    name: "problem has no digit",
+    text: validIntent.replace(problemText, "GET /health fails."),
+  },
+  {
+    expectedMessagePart: "has no number",
+    name: "problem has a digit only inside a fenced block",
+    text: validIntent.replace(problemText, "GET /health fails.\n\n```\n500\n```"),
+  },
+];
+
+const selfTestFailures = selfTestCases
+  .filter(({expectedMessagePart, text}) => {
+    const messages = checkIntent(text).map(problem => problem.message);
+
+    return expectedMessagePart === undefined
+      ? messages.length > 0
+      : messages.length !== 1 || !messages.at(0)?.includes(expectedMessagePart);
+  })
+  .map(({name}) => name);
+
+const intentPaths = process.argv.slice(2);
+
+if (selfTestFailures.length > 0) {
+  const failureLines = selfTestFailures.map(name => `- ${name}`);
+
+  process.stderr.write(`Intent self-tests failed:\n${failureLines.join("\n")}\n`);
+  process.exitCode = 1;
+} else if (intentPaths.length === 0) {
+  process.stdout.write(`Ran ${selfTestCases.length} intent self-tests.\n`);
+} else {
+  const missingLines = intentPaths
+    .filter(intentPath => !existsSync(intentPath))
+    .map(
+      intentPath =>
+        `${intentPath}:1: the file does not exist; pass the path of an existing intent.md`,
+    );
+
+  const checkedLines = intentPaths
+    .filter(intentPath => existsSync(intentPath))
+    .flatMap(intentPath =>
+      checkIntent(readFileSync(intentPath, "utf8")).map(
+        ({line, message}) => `${intentPath}:${line}: ${message}`,
+      ),
+    );
+
+  const problemLines = [...missingLines, ...checkedLines];
+
+  if (problemLines.length > 0) {
+    process.stderr.write(`${problemLines.join("\n")}\n`);
+    process.exitCode = 1;
+  } else {
+    process.stdout.write(`Checked ${intentPaths.length} intents.\n`);
+  }
+}

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

@@ -81,6 +81,8 @@ jobs:
         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 lint
         run: pnpm lint:check
       - name: Check formatting

package/templates/nestjs/AGENTS.md

@@ -21,7 +21,6 @@ NestJS HTTP API in TypeScript on pnpm and Node.js `>=24.15.0 <25`.
 - 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
 
@@ -30,24 +29,17 @@ If a test fails, fix the code, not the test.
 
 ## Conventions
 
-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.
-7. **Start work only when a person asks or a trigger runs it, and stop only at the human gates, before an irreversible action, or for a decision only a person can make.** A question or a statement gets an answer, not a file, a commit, or a pull request. When a message reports a problem without asking for work, answer in a few lines and end with the message that would start the work: `/sdlc` followed by their own words. Once a task starts, carry it to the next gate without asking; `.agents/rules/agent-owned-work.md` lists the gates.
-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. Drive it until it is green and waits only on code owner approval, as `.agents/skills/sdlc/playbooks/review.md` describes. Rebase and `git push --force-with-lease` only branches you own. 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.
+1. **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.
+2. **Read configuration from environment variables and fail when one is missing**, as `parsePort` does. Document each variable in `.env.example`.
+3. **Log through Nest's `Logger`.** It goes to the `ConsoleLogger` set in `src/main.ts`.
+4. **Start from the accepted spec, in plan mode** (Cursor: Plan Mode). Give the plan the change's `intent/<change>/intent.md` and `spec.md`. Commit the approved plan as `intent/<change>/plan.md` with an `Accepted by:` line naming the engineer, as `.agents/skills/sdlc/playbooks/build.md` describes.
+5. **Start a bug fix with a failing test.** Reproduce the bug as a test, confirm it fails for the reason you expect, and commit it. Then create `.git/bug-fix-in-progress`, so `.agents/hooks/agent-test-edit-gate.sh` blocks test edits, make the test pass without editing it, and delete `.git/bug-fix-in-progress`.
+6. **Do not start work a person did not ask for.** When a message reports a problem without asking for work, answer in a few lines and end with the message that would start it: `/sdlc` followed by their own words.
+7. **Branch from the latest `origin/main`, and open the pull request ready for review.** Name the branch `<type>/<short-description>` and fill the body from `.github/pull_request_template.md`. `.github/workflows/ci.yml` runs full verification only on a pull request that is not a draft. Never merge a pull request: a person merges it with `--squash` after code owner approval, bottom-up for a stack of pull requests.
+8. **Write replies a person can check.** Reply in the language the person wrote in. Write paths from the project root, such as `README.md:12`, never from the machine's root. State as a fact only what you opened or ran in this turn, and say what you ran; mark anything else as inferred or not checked. Answer what was asked and stop: leave out tools, services, and steps the request does not need, and never hand the person a check you could run. Send nothing outside the session, such as a message to another session or a service, unless a task step says to.
 
 ## Things Claude gets wrong
 
 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 also blocks merging or approving a pull request, approving a deployment, and gh aliases, and asks the person before an irreversible git command such as a force push or a hard reset. It is a convenience, not a security boundary: CI and code-owner review are the boundary.
-- **Production gate**: `.agents/hooks/agent-production-gate.sh` blocks a shell command that deploys to `prod` (`gh workflow run` or a workflow dispatch with `environment=prod`), a Railway CLI command that names `prod` with `-e`, `--environment`, or `railway environment`, and a release tag push, 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. It is a convenience, not a security boundary: the `prod` environment's required reviewers and Railway credentials are the boundary.
-
-## Related documentation
-
-- [README.md](README.md): scripts, container, deploy
-- [CONTRIBUTING.md](CONTRIBUTING.md): prerequisites, Git hooks, pull requests
+- **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.

package/templates/nestjs/CONTRIBUTING.md

@@ -50,6 +50,7 @@ We use trunk-based development. `main` is the only long-lived branch, and every
 - Branch from `main` and merge back within a day or two. Do not create `develop` or release branches.
 - Merge unfinished work behind a feature flag or keep it unreachable instead of holding a long-lived branch.
 - Pull requests are squash-merged, so the pull request title becomes the commit on `main`.
+- After a pull request that only reformats code merges, the next pull request lists its commit on `main` in `.git-blame-ignore-revs` at the repository root, creating the file the first time, with a `#` comment that names the change, as [GitHub Docs](https://docs.github.com/en/repositories/working-with-files/using-files/viewing-and-understanding-files) shows. GitHub then hides that commit in the blame view.
 - Write commit messages in the format that `@next-friday/commitlint-config-friday` defines. Pull request titles use `<type>(<scope>): <subject>`, which `.github/workflows/validate-pr-title.yml` checks.
 - Keep each pull request focused on one cohesive change.
 - Describe observable endpoint, request or response, or configuration effects.

package/templates/nestjs/package.json

@@ -23,6 +23,7 @@
     "format:check": "prettier --check --cache . && editorconfig-checker",
     "gates:check": "node scripts/check-agent-gates.ts",
     "human-gates:check": "node scripts/check-human-gates.ts",
+    "intent:check": "node scripts/check-intent.ts",
     "knip": "knip",
     "lint": "eslint . --fix --cache --max-warnings=0 --no-inline-config",
     "lint:check": "eslint . --cache --max-warnings=0 --no-inline-config",
@@ -44,7 +45,7 @@
     "test:watch": "vitest",
     "typecheck": "tsc --noEmit -p tsconfig.json",
     "verify": "pnpm verify:static && pnpm test:coverage && pnpm build",
-    "verify:static": "pnpm suppressions:check && pnpm rules:check && pnpm gates:check && pnpm human-gates:check && pnpm lint:check && pnpm format:check && pnpm sort-package-json:check && pnpm peers:check && pnpm typecheck && pnpm knip && pnpm depcruise"
+    "verify:static": "pnpm suppressions:check && pnpm rules:check && pnpm gates:check && pnpm human-gates:check && pnpm intent:check && pnpm lint:check && pnpm format:check && pnpm sort-package-json:check && pnpm peers:check && pnpm typecheck && pnpm knip && pnpm depcruise"
   },
   "dependencies": {
     "@nestjs/common": "12.3.2",

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

@@ -81,6 +81,8 @@ jobs:
         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 lint
         run: pnpm lint:check
       - name: Check formatting

package/templates/nextjs/AGENTS.md

@@ -21,7 +21,6 @@ Next.js App Router web app with React and Tailwind CSS, in TypeScript on pnpm an
 - 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
 
@@ -30,28 +29,21 @@ If a test fails, fix the code, not the test.
 
 ## Conventions
 
-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 `app/**/*.test.{ts,tsx}` and Playwright end-to-end tests in `test/` as `*.e2e.test.ts`.** Vitest collects only the first pattern.
-3. **Component tests need a DOM test environment, and Vitest runs in Node.js.** Add that environment with the first component test.
-4. **Read configuration from environment variables and fail when one is missing.** Document each variable in `.env.example`.
-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.
-7. **Start work only when a person asks or a trigger runs it, and stop only at the human gates, before an irreversible action, or for a decision only a person can make.** A question or a statement gets an answer, not a file, a commit, or a pull request. When a message reports a problem without asking for work, answer in a few lines and end with the message that would start the work: `/sdlc` followed by their own words. Once a task starts, carry it to the next gate without asking; `.agents/rules/agent-owned-work.md` lists the gates.
-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. Drive it until it is green and waits only on code owner approval, as `.agents/skills/sdlc/playbooks/review.md` describes. Rebase and `git push --force-with-lease` only branches you own. 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.
+1. **Put unit tests next to the code as `app/**/*.test.{ts,tsx}` and Playwright end-to-end tests in `test/` as `*.e2e.test.ts`.** Vitest collects only the first pattern.
+2. **Component tests need a DOM test environment, and Vitest runs in Node.js.** Add that environment with the first component test.
+3. **Read configuration from environment variables and fail when one is missing.** Document each variable in `.env.example`.
+4. **Start from the accepted spec, in plan mode** (Cursor: Plan Mode). Give the plan the change's `intent/<change>/intent.md` and `spec.md`. Commit the approved plan as `intent/<change>/plan.md` with an `Accepted by:` line naming the engineer, as `.agents/skills/sdlc/playbooks/build.md` describes.
+5. **Start a bug fix with a failing test.** Reproduce the bug as a test, confirm it fails for the reason you expect, and commit it. Then create `.git/bug-fix-in-progress`, so `.agents/hooks/agent-test-edit-gate.sh` blocks test edits, make the test pass without editing it, and delete `.git/bug-fix-in-progress`.
+6. **Do not start work a person did not ask for.** When a message reports a problem without asking for work, answer in a few lines and end with the message that would start it: `/sdlc` followed by their own words.
+7. **Branch from the latest `origin/main`, and open the pull request ready for review.** Name the branch `<type>/<short-description>` and fill the body from `.github/pull_request_template.md`. `.github/workflows/ci.yml` runs full verification only on a pull request that is not a draft. Never merge a pull request: a person merges it with `--squash` after code owner approval, bottom-up for a stack of pull requests.
+8. **Write replies a person can check.** Reply in the language the person wrote in. Write paths from the project root, such as `README.md:12`, never from the machine's root. State as a fact only what you opened or ran in this turn, and say what you ran; mark anything else as inferred or not checked. Answer what was asked and stop: leave out tools, services, and steps the request does not need, and never hand the person a check you could run. Send nothing outside the session, such as a message to another session or a service, unless a task step says to.
 
 ## Things Claude gets wrong
 
 When Claude makes a mistake twice, add the correction here.
 
 - **First end-to-end run**: run `pnpm exec playwright install chromium` once. `pnpm test:e2e` starts the development server unless one is already running.
-- **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 also blocks merging or approving a pull request, approving a deployment, and gh aliases, and asks the person before an irreversible git command such as a force push or a hard reset. It is a convenience, not a security boundary: CI and code-owner review are the boundary.
-- **Production gate**: `.agents/hooks/agent-production-gate.sh` blocks a shell command that deploys to `prod` (`gh workflow run` or a workflow dispatch with `environment=prod`), a Railway CLI command that names `prod` with `-e`, `--environment`, or `railway environment`, and a release tag push, 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. It is a convenience, not a security boundary: the `prod` environment's required reviewers and Railway credentials are the boundary.
-
-## Related documentation
-
-- [README.md](README.md): scripts, container, deploy
-- [CONTRIBUTING.md](CONTRIBUTING.md): prerequisites, Git hooks, pull requests
+- **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.
 
 <!-- BEGIN:nextjs-agent-rules -->
 

package/templates/nextjs/CONTRIBUTING.md

@@ -50,6 +50,7 @@ We use trunk-based development. `main` is the only long-lived branch, and every
 - Branch from `main` and merge back within a day or two. Do not create `develop` or release branches.
 - Merge unfinished work behind a feature flag or keep it unreachable instead of holding a long-lived branch.
 - Pull requests are squash-merged, so the pull request title becomes the commit on `main`.
+- After a pull request that only reformats code merges, the next pull request lists its commit on `main` in `.git-blame-ignore-revs` at the repository root, creating the file the first time, with a `#` comment that names the change, as [GitHub Docs](https://docs.github.com/en/repositories/working-with-files/using-files/viewing-and-understanding-files) shows. GitHub then hides that commit in the blame view.
 - Write commit messages in the format that `@next-friday/commitlint-config-friday` defines. Pull request titles use `<type>(<scope>): <subject>`, which `.github/workflows/validate-pr-title.yml` checks.
 - Keep each pull request focused on one cohesive change.
 - Describe observable page, route, content, or configuration effects.

package/templates/nextjs/package.json

@@ -20,6 +20,7 @@
     "format:check": "prettier --check --cache . && editorconfig-checker",
     "gates:check": "node scripts/check-agent-gates.ts",
     "human-gates:check": "node scripts/check-human-gates.ts",
+    "intent:check": "node scripts/check-intent.ts",
     "knip": "knip",
     "lint": "eslint . --fix --cache --max-warnings=0 --no-inline-config",
     "lint:check": "eslint . --cache --max-warnings=0 --no-inline-config",
@@ -38,7 +39,7 @@
     "test:watch": "vitest",
     "typecheck": "next typegen && tsc --noEmit -p tsconfig.json",
     "verify": "pnpm verify:static && pnpm test:coverage && pnpm build",
-    "verify:static": "pnpm suppressions:check && pnpm rules:check && pnpm gates:check && pnpm human-gates:check && pnpm lint:check && pnpm format:check && pnpm sort-package-json:check && pnpm peers:check && pnpm typecheck && pnpm knip && pnpm depcruise"
+    "verify:static": "pnpm suppressions:check && pnpm rules:check && pnpm gates:check && pnpm human-gates:check && pnpm intent:check && pnpm lint:check && pnpm format:check && pnpm sort-package-json:check && pnpm peers:check && pnpm typecheck && pnpm knip && pnpm depcruise"
   },
   "dependencies": {
     "next": "16.4.3",

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

@@ -81,6 +81,8 @@ jobs:
         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 lint
         run: pnpm lint:check
       - name: Check formatting