@next-friday/create-app 9.5.1 → 9.7.0

package/README.md

@@ -31,7 +31,7 @@ Every stack is built from [`templates/base`](templates/base), which holds the sh
 - **Code quality:** TypeScript, ESLint and Prettier with the Next Friday configs, Vitest with coverage, fast-check, Knip, dependency-cruiser, editorconfig-checker, and sort-package-json.
 - **Git hooks:** Husky runs gitleaks, `pnpm rules:check`, and lint-staged before each commit, commitlint on each message, and `pnpm check` before each push. After the first commit, commits to `main` are blocked, and local merges into `main` always are; pushes to `main` are blocked once it exists on the remote.
 - **CI:** GitHub Actions run the static checks, tests with patch coverage, the build, end-to-end tests for Next.js and Payload, a container build and vulnerability scan, Semgrep, OSV-Scanner, CodeQL, dependency review, OpenSSF Scorecard, gitleaks, TruffleHog, zizmor, and pull request title validation. Dependabot keeps dependencies current.
-- **Deployment:** a `Dockerfile` that runs as the `node` user, and a Railway workflow that promotes one commit through `dev`, `uat`, and `prod`.
+- **Deployment:** a `Dockerfile` that runs as the `node` user. With `--deploy railway`, also a Railway workflow that promotes one commit through `dev`, `uat`, and `prod`.
 - **Agent rules:** `CLAUDE.md` imports `AGENTS.md`. Shared rules live in `.agents/rules`, with hooks that enforce them in Claude Code and Cursor.
 
 ## Requirements
@@ -44,17 +44,18 @@ Every stack is built from [`templates/base`](templates/base), which holds the sh
 ## Options
 
 ```text
-pnpm create @next-friday/app [name] [--stack nodejs|nestjs|nextjs|payload|turborepo]
+pnpm create @next-friday/app [name] [--stack nodejs|nestjs|nextjs|payload|turborepo] [--deploy none|railway]
 ```
 
-| Option           | Description                                                                   |
-| :--------------- | :---------------------------------------------------------------------------- |
-| `name`           | Project directory and package name. Asked when left out.                      |
-| `--stack`        | `nodejs`, `nestjs`, `nextjs`, `payload`, or `turborepo`. Asked when left out. |
-| `--skip-git`     | Do not run `git init`.                                                        |
-| `--skip-install` | Do not run `pnpm install`.                                                    |
-| `-v, --version`  | Print the version.                                                            |
-| `-h, --help`     | Print the usage.                                                              |
+| Option           | Description                                                                               |
+| :--------------- | :---------------------------------------------------------------------------------------- |
+| `name`           | Project directory and package name. Asked when left out.                                  |
+| `--stack`        | `nodejs`, `nestjs`, `nextjs`, `payload`, or `turborepo`. Asked when left out.             |
+| `--deploy`       | Deploy target: `none` or `railway`. The default is `none`, which adds no deploy workflow. |
+| `--skip-git`     | Do not run `git init`.                                                                    |
+| `--skip-install` | Do not run `pnpm install`.                                                                |
+| `-v, --version`  | Print the version.                                                                        |
+| `-h, --help`     | Print the usage.                                                                          |
 
 The name must:
 

package/dist/main.mjs

@@ -117,6 +117,16 @@ function validateProjectName(name, cwd) {
 function ownEntries(directory) {
 	return readdirSync(directory).filter((entry) => entry !== ".git");
 }
+// src/deploy-targets.ts
+const deployTargets = ["none", "railway"];
+/**
+* Check whether a string names a supported deploy target.
+* @param value - Deploy target from the command line.
+* @returns Whether `value` is a supported deploy target.
+*/
+function isDeployTarget(value) {
+	return deployTargets.some((target) => target === value);
+}
 // src/stacks.ts
 const stacks = [
 	{
@@ -173,10 +183,11 @@ function templateName(stack) {
 	return `next-friday-template-${stack}`;
 }
 // src/arguments.ts
-const usage = `Usage: pnpm create @next-friday/app [name] [--stack ${stacks.map((stack) => stack.id).join("|")}]
+const usage = `Usage: pnpm create @next-friday/app [name] [--stack ${stacks.map((stack) => stack.id).join("|")}] [--deploy ${deployTargets.join("|")}]
 
   name            Project directory and package name, or . for the current directory. Asked when left out.
   --stack         Template stack. Asked when left out.
+  --deploy        Deploy target: ${deployTargets.join(" or ")}. The default is none.
   --skip-git      Do not run git init.
   --skip-install  Do not run pnpm install.
   -v, --version   Show the version.
@@ -192,6 +203,10 @@ function parseCliArguments(cliArguments) {
 		allowPositionals: true,
 		options: {
 			stack: { type: "string" },
+			deploy: {
+				type: "string",
+				default: "none"
+			},
 			"skip-git": {
 				type: "boolean",
 				default: false
@@ -212,23 +227,33 @@ function parseCliArguments(cliArguments) {
 			}
 		}
 	});
-	const { help, stack, version } = values;
+	const { deploy, help, stack, version } = values;
 	const isInformational = help || version;
 	if (!isInformational && positionals.length > 1) throw new Error(`Pass one project name, not ${positionals.length}: ${positionals.join(" ")}.`);
 	const [name] = positionals;
-	if (!isInformational && stack !== void 0 && !isStackId(stack)) {
-		const ids = stacks.map((supported) => supported.id).join(", ");
-		throw new Error(`Unknown stack "${stack}". Use one of: ${ids}.`);
-	}
+	if (!isInformational) assertKnownChoices(stack, deploy);
 	return {
 		help,
 		name,
 		version,
+		deploy: isDeployTarget(deploy) ? deploy : "none",
 		stack: stack !== void 0 && isStackId(stack) ? stack : void 0,
 		skipGit: values["skip-git"],
 		skipInstall: values["skip-install"]
 	};
 }
+/**
+* Throw when the stack or the deploy target is not one the CLI supports.
+* @param stack - Stack from the command line, or `undefined` when left out.
+* @param deploy - Deploy target from the command line.
+*/
+function assertKnownChoices(stack, deploy) {
+	if (stack !== void 0 && !isStackId(stack)) {
+		const ids = stacks.map((supported) => supported.id).join(", ");
+		throw new Error(`Unknown stack "${stack}". Use one of: ${ids}.`);
+	}
+	if (!isDeployTarget(deploy)) throw new Error(`Unknown deploy target "${deploy}". Use one of: ${deployTargets.join(", ")}.`);
+}
 // src/rename.ts
 /**
 * Replace the template name with the project name in every text file.
@@ -245,6 +270,45 @@ async function renameProject(directory, from, to) {
 		await writeFile(file, text.replaceAll(from, () => to));
 	}));
 }
+// src/deploy-sections.ts
+const marker = /^\s*(?:#|\/\/|<!--)\s*deploy:(?<name>[a-z]+)\s*(?:-->\s*)?$/u;
+const endName = "end";
+/**
+* Keep the sections of a template file marked for the chosen deploy target and remove the others.
+* A section starts at a comment line that holds `deploy:<target>` and ends at one that holds `deploy:end`.
+* Every marker line is removed, with a blank line that directly follows it.
+* @param content - Text of a copied template file.
+* @param target - Chosen deploy target.
+* @returns The text for the chosen deploy target.
+*/
+function resolveDeploySections(content, target) {
+	const kept = [];
+	let section;
+	let isAfterMarker = false;
+	for (const line of content.split("\n")) {
+		const name = marker.exec(line)?.groups?.name;
+		if (name === void 0) {
+			if (!(isAfterMarker && line.trim() === "") && (section ?? target) === target) kept.push(line);
+		} else section = sectionAfterMarker(name, section);
+		isAfterMarker = name !== void 0;
+	}
+	if (section !== void 0) throw new Error(`The deploy:${section} section has no deploy:end marker.`);
+	return kept.join("\n");
+}
+/**
+* Give the section a marker line leaves open, or throw when the marker is out of place.
+* @param name - Deploy target the marker names, or `end`.
+* @param section - Deploy target of the section the marker sits in, or `undefined` outside a section.
+* @returns The deploy target of the section now open, or `undefined` after an end marker.
+*/
+function sectionAfterMarker(name, section) {
+	if (name === endName) {
+		if (section === void 0) throw new Error("A deploy:end marker has no deploy target section to close.");
+		return;
+	}
+	if (section !== void 0) throw new Error(`A deploy:${name} marker starts inside the deploy:${section} section.`);
+	return name;
+}
 // src/create.ts
 const templatesDirectory = fileURLToPath(new URL("../templates", import.meta.url));
 const interruptSignals = [
@@ -276,7 +340,7 @@ async function create(cliArguments) {
 		const target = path.resolve(cwd, name);
 		const directory = existsSync(target) ? realpathSync(target) : target;
 		log.step(`Copying the ${stack} template.`);
-		await writeProject(stack, directory, manifestName);
+		await writeProject(stack, options.deploy, directory, manifestName);
 		log.success(`Created ${manifestName} from the ${stack} template.`);
 		const { git, isInstalled } = setUpProject(directory, options);
 		outro(nextSteps(name, stack, git, isInstalled));
@@ -294,10 +358,11 @@ async function create(cliArguments) {
 * Copy, rename, and write `.env`, removing what was written when a step fails or Ctrl+C, SIGTERM, or SIGHUP arrives.
 * An interrupt waits for the running step, so the removal does not race the copy.
 * @param stack - Supported stack id.
+* @param deploy - Supported deploy target.
 * @param directory - Project directory.
 * @param manifestName - Package name for `package.json`.
 */
-async function writeProject(stack, directory, manifestName) {
+async function writeProject(stack, deploy, directory, manifestName) {
 	const kept = existsSync(directory) ? readdirSync(directory) : void 0;
 	let isInterrupted = false;
 	const interrupt = () => {
@@ -305,7 +370,7 @@ async function writeProject(stack, directory, manifestName) {
 	};
 	for (const signal of interruptSignals) process.on(signal, interrupt);
 	try {
-		await copyTemplate(stack, directory);
+		await copyTemplate(stack, deploy, directory);
 		await renameProject(directory, templateName(stack), manifestName);
 		await writeEnvironmentFile(directory);
 		if (isInterrupted) throw new CancelledError();
@@ -382,19 +447,49 @@ function existingGit(directory) {
 	return existsSync(path.join(directory, ".git")) ? "existing" : void 0;
 }
 /**
-* Copy the shared template files, then the stack's files, into the project directory.
+* Copy the shared template files, the stack's files, and the deploy target's files into the project directory.
 * npm leaves `.gitignore` out of published packages, so the template keeps it as `_gitignore`.
 * @param stack - Supported stack id.
+* @param deploy - Supported deploy target.
 * @param directory - Project directory.
 */
-async function copyTemplate(stack, directory) {
-	for (const template of ["base", stack]) if (!existsSync(path.join(templatesDirectory, template))) throw new Error(`The ${template} template is missing from ${templatesDirectory}. Reinstall @next-friday/create-app.`);
-	await cp(path.join(templatesDirectory, "base"), directory, { recursive: true });
-	await cp(path.join(templatesDirectory, stack), directory, { recursive: true });
+async function copyTemplate(stack, deploy, directory) {
+	const deployLayer = deploy === "none" ? void 0 : `deploy-${deploy}`;
+	const required = [
+		"base",
+		stack,
+		...deployLayer === void 0 ? [] : [`${deployLayer}/base`]
+	];
+	for (const template of required) if (!existsSync(path.join(templatesDirectory, template))) throw new Error(`The ${template} template is missing from ${templatesDirectory}. Reinstall @next-friday/create-app.`);
+	const copyLayer = async (layer) => {
+		await cp(path.join(templatesDirectory, layer), directory, { recursive: true });
+	};
+	await copyLayer("base");
+	await copyLayer(stack);
+	if (deployLayer !== void 0) {
+		await copyLayer(`${deployLayer}/base`);
+		if (existsSync(path.join(templatesDirectory, deployLayer, stack))) await copyLayer(`${deployLayer}/${stack}`);
+	}
 	await rename(path.join(directory, "_gitignore"), path.join(directory, ".gitignore"));
+	await resolveDeployTarget(directory, deploy);
 	await markScriptsExecutable(directory);
 }
 /**
+* Resolve the deploy target sections of every copied file that holds a marker.
+* @param directory - Project directory.
+* @param deploy - Supported deploy target.
+*/
+async function resolveDeployTarget(directory, deploy) {
+	const files = await listProjectFiles(directory);
+	await Promise.all(files.map(async (file) => {
+		const content = await readFile(file);
+		if (!content.includes("deploy:")) return;
+		const template = content.toString();
+		const resolved = resolveDeploySections(template, deploy);
+		if (resolved !== template) await writeFile(file, resolved);
+	}));
+}
+/**
 * Make every file that starts with a shebang executable. `pnpm pack` drops the executable bit,
 * and the Git and agent hooks run these scripts directly.
 * @param directory - Project directory.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@next-friday/create-app",
-  "version": "9.5.1",
+  "version": "9.7.0",
   "description": "Create a Next Friday project from a template.",
   "keywords": [
     "create",

package/templates/base/SETUP.md

@@ -43,6 +43,8 @@ In `.github/CODEOWNERS`, add these lines in this order. GitHub uses the last mat
 
 Replace every owner above with a GitHub user or team that has write access to the repository. Also replace the owner placeholder in `.github/zizmor.yml`.
 
+Code owners need: write access to the repository for each owner; for a team, a visible team that itself has write access; and, in a private repository, GitHub Pro, Team, or Enterprise ([code owners](https://docs.github.com/en/repositories/managing-your-repositorys-settings-and-features/customizing-your-repository/about-code-owners)). Until the ruleset of step 3 requires their review, a code owner is asked for a review and a pull request merges without it.
+
 Replace `security@example.com` in `SECURITY.md` with the contact the security policy owner names, such as the security email of the company or of the client.
 
 **Check:** on GitHub, open `.github/CODEOWNERS`; GitHub shows no errors in the file. `grep example.com SECURITY.md` prints nothing.
@@ -62,7 +64,10 @@ Replace `security@example.com` in `SECURITY.md` with the contact the security po
 
   Rulesets in a private repository need GitHub Pro, Team, or Enterprise; on GitHub Free, make the repository public or upgrade.
 
-- **Secrets and variables → Actions → Variables:** in a private repository, set `CODE_SCANNING` to `true` to run CodeQL, Scorecard, and Dependency Review, which need GitHub Code Security there; public repositories run them without it. Set `DEPLOY_ENABLED` to `true` when each push to `main` that passes CI should deploy to `dev`; the README's deploy section sets up the environments.
+- **Secrets and variables → Actions → Variables:** in a private repository, set `CODE_SCANNING` to `true` to run CodeQL, Scorecard, and Dependency Review, which need GitHub Code Security there; public repositories run them without it. Set `CONTAINER_IMAGE` to `false` to skip the job that builds and scans the container image, for a project that ships no image.
+<!-- deploy:railway -->
+- **Secrets and variables → Actions → Variables:** set `DEPLOY_ENABLED` to `true` when each push to `main` that passes CI should deploy to `dev`; the README's deploy section sets up the environments.
+<!-- deploy:end -->
 - Create the `needs triage` label, which the issue forms apply: `gh label create "needs triage"`.
 
 **Check:** a test pull request shows the two required checks and asks for a code owner's review.
@@ -73,7 +78,7 @@ Replace `security@example.com` in `SECURITY.md` with the contact the security po
 
 - **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. Anyone with write access can also comment `@claude review` on a pull request to start a review ([comment commands](https://code.claude.com/docs/en/code-review-pull-requests#comment-commands)).
 - **Managed settings:** deploy the non-negotiable settings and hooks as [managed settings](https://code.claude.com/docs/en/settings), tailored from the example in `.claude/managed-settings.example.json`. Engineers cannot override them. When `strictKnownMarketplaces` is set, as in the example, add the marketplace `next-friday-plugins` of this project to it, or Claude Code does not register the project's plugin.
-- **Monitoring:** turn on the [OpenTelemetry export](https://code.claude.com/docs/en/monitoring-usage).
+- **Monitoring:** turn on the [OpenTelemetry export](https://code.claude.com/docs/en/monitoring-usage). It needs an OpenTelemetry collector or backend that the organization runs, and its endpoint. Set `CLAUDE_CODE_ENABLE_TELEMETRY`, the exporters, and `OTEL_EXPORTER_OTLP_ENDPOINT` in managed settings, or each engineer sets them in a shell or in `~/.claude/settings.json`: Claude Code ignores these variables in the repository's `.claude/settings.json`, so the project cannot turn the export on.
 
 **Check:** the test pull request gets a **Claude Code Review** check run within a few minutes.
 
@@ -92,7 +97,12 @@ Replace `security@example.com` in `SECURITY.md` with the contact the security po
 - **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):** the plugin ships a default for each area, `plugins/sdlc/claude-code/skills/<area>-policy/SKILL.md` (security: OWASP ASVS 5.0.0 Level 1; UX: WCAG 2.2 Level AA; compliance: the OECD privacy principles; brand: one declared source for every brand value). Review it. To replace a default, add the organization's own rules in `.agents/skills/<area>-policy/SKILL.md` in the project: that file wins over the plugin's default, and the `CODEOWNERS` line of step 2 for that area makes the policy owner its code owner. Do not edit the plugin's copy. Then run `pnpm rules:sync`, which renders the project's own policy skill for Claude Code and Cursor. Test that the skill triggers: ask for the relevant task in different ways and confirm the skill loads each time.
+<!-- deploy:railway -->
 - **Production gate (engineering leadership, with change management and compliance):** name the release managers and add them as required reviewers on the `prod` environment, as the README's deploy section describes. `.agents/hooks/agent-production-gate.sh` blocks an agent's shell commands that dispatch a `prod` deploy, run a Railway command with `prod` as its environment, or push a release tag. It does not read MCP tools. A release manager whose own agent session must do one of these starts the agent with `RELEASE_APPROVAL` set to the approval record, for example `RELEASE_APPROVAL=CHG-123 claude`. The value lifts the gate only when it matches the extended regular expression on the first line of `.agents/release-approval-form`, shipped as `^[A-Z]+-[0-9]+$`; set that line to the form of your organization's approval records. Each gate hook appends its decisions to `.agents/logs/gate-decisions.jsonl`, which git ignores: the time, the hook, the decision, the session, and the reason for a block, and, when the production gate is lifted, the approval value and the Git user name. A record holds no command text and no path.
+<!-- deploy:end -->
+<!-- deploy:none -->
+- **Production gate (engineering leadership, with change management and compliance):** name the release managers and add them as required reviewers on the `prod` environment, as the README's deploy section describes. `.agents/hooks/agent-production-gate.sh` blocks an agent's shell commands that dispatch a `prod` deploy or push a release tag. It does not read MCP tools. A release manager whose own agent session must do one of these starts the agent with `RELEASE_APPROVAL` set to the approval record, for example `RELEASE_APPROVAL=CHG-123 claude`. The value lifts the gate only when it matches the extended regular expression on the first line of `.agents/release-approval-form`, shipped as `^[A-Z]+-[0-9]+$`; set that line to the form of your organization's approval records. Each gate hook appends its decisions to `.agents/logs/gate-decisions.jsonl`, which git ignores: the time, the hook, the decision, the session, and the reason for a block, and, when the production gate is lifted, the approval value and the Git user name. A record holds no command text and no path.
+<!-- deploy:end -->
 - **Review (tech lead):** `.agents/review.md` names this stack's generated files to skip; add a path when the project gains a generated file, 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`.
 - **People without Git experience:** connect GitHub to Claude (claude.ai or Cowork), so Claude commits `intent.md` for them.
 

package/templates/base/plugins/sdlc/claude-code/hooks/check-reply-shape.sh

@@ -3,8 +3,44 @@ command -v jq > /dev/null || exit 0
 mode=${1:-}
 input=$(cat)
 state_directory=${TMPDIR:-/tmp}/sdlc-reply-shape
-conversation=$(printf '%s' "$input" | jq -r '.conversation_id // ""' | tr -cd 'A-Za-z0-9_-')
+conversation=$(printf '%s' "$input" | jq -r '.conversation_id // .session_id // ""')
+conversation=${conversation:+$(printf '%s' "$conversation" | cksum | tr ' ' '-')}
+project=$(printf '%s' "$input" | jq -r '.cwd // .workspace_roots[0] // ""')
+snapshot_file=$state_directory/$conversation.files
+
+# A copy of the index and a scratch object store keep the project's own Git data unwritten.
+snapshot() {
+  [ -n "$project" ] && [ -n "$conversation" ] || return 1
+  repository=$(git -C "$project" rev-parse --show-toplevel 2> /dev/null) || return 1
+  index=$(git -C "$repository" rev-parse --git-path index) || return 1
+  objects=$(git -C "$repository" rev-parse --git-path objects) || return 1
+  case $index in /*) ;; *) index=$repository/$index ;; esac
+  case $objects in /*) ;; *) objects=$repository/$objects ;; esac
+  scratch=$state_directory/$conversation.git
+  rm -rf "$scratch"
+  mkdir -p "$scratch/objects" || return 1
+  cp "$index" "$scratch/index" 2> /dev/null
+  content=$(
+    export GIT_INDEX_FILE="$scratch/index" GIT_OBJECT_DIRECTORY="$scratch/objects" GIT_ALTERNATE_OBJECT_DIRECTORIES="$objects"
+    git -C "$repository" add -A -- ':(top)' ':(top,exclude)intent' 2> /dev/null
+    git -C "$repository" ls-files -s -- ':(top)' ':(top,exclude)intent' | cksum
+  )
+  rm -rf "$scratch"
+  printf '%s|%s' "$repository" "$content"
+}
+
+changed_since_snapshot() {
+  current=$(snapshot) || return 1
+  previous=$(cat "$snapshot_file" 2> /dev/null)
+  printf '%s' "$current" > "$snapshot_file"
+  [ "${previous%|*}" = "${current%|*}" ] && [ "$previous" != "$current" ]
+}
+
 case $mode in
+  snapshot)
+    changed_since_snapshot
+    exit 0
+    ;;
   save)
     text=$(printf '%s' "$input" | jq -r '.text // ""')
     [ -n "$text" ] && [ -n "$conversation" ] || exit 0
@@ -12,12 +48,16 @@ case $mode in
     exit 0
     ;;
   followup)
+    changed=false
+    changed_since_snapshot && changed=true
     [ -n "$conversation" ] && [ -f "$state_directory/$conversation" ] || exit 0
     reply=$(cat "$state_directory/$conversation")
     rm -f "$state_directory/$conversation"
     [ "$(printf '%s' "$input" | jq -r '"\(.status // "") \(.loop_count // "")"')" = 'completed 0' ] || exit 0
     ;;
   *)
+    changed=false
+    changed_since_snapshot && changed=true
     [ "$(printf '%s' "$input" | jq -r '.stop_hook_active // false')" = true ] && exit 0
     reply=$(printf '%s' "$input" | jq -r '.last_assistant_message // ""')
     ;;
@@ -48,6 +88,10 @@ case $last in
   *) problems="${problems}End the reply with a line that starts with **Status:**; nothing may follow it. " ;;
 esac
 
+if [ "$changed" = true ] && ! printf '%s\n' "$outside_fences" | grep -q '^\*\*Checks:\*\*'; then
+  problems="${problems}A file outside intent/ changed in this turn and the reply has no **Checks:** section. Run the checks the project names and add **Checks:** with each command and the lines of its output that show the result, or with each check that could not run and why. "
+fi
+
 [ -z "$problems" ] && exit 0
 jq -n --arg mode "$mode" --arg reason "${problems}Send the whole reply again." \
   'if $mode == "followup" then {followup_message:$reason} else {decision:"block",reason:$reason} end'

package/templates/base/plugins/sdlc/claude-code/hooks/hooks.json

@@ -1,5 +1,16 @@
 {
   "hooks": {
+    "UserPromptSubmit": [
+      {
+        "hooks": [
+          {
+            "timeout": 10,
+            "type": "command",
+            "command": "sh \"${CLAUDE_PLUGIN_ROOT}/hooks/check-reply-shape.sh\" snapshot"
+          }
+        ]
+      }
+    ],
     "Stop": [
       {
         "hooks": [

package/templates/base/plugins/sdlc/claude-code/skills/sdlc-mode/SKILL.md

@@ -49,7 +49,7 @@ For example, the person writes "who must approve pull request #7 of https://host
 
 **Steps:** <only when the session has no task-list tool, and never for the `question` playbook. One line for each numbered step of the playbook: `1. <the step, copied word for word>: done | open | skip: <reason>`. When the turn ran more than one playbook, one list for each, under its file name on a line of its own, such as `playbooks/build.md`.>
 
-**Checks:** <only when a step ran checks, and never for the `question` playbook. Each command, then the lines of its output that show the result, copied from the output.>
+**Checks:** <when a step ran checks, and always when the turn changed a file outside `intent/`, whichever playbook ran. Otherwise never for the `question` playbook. Each command, then the lines of its output that show the result, copied from the output. For a check that could not run, the check and why.>
 
 <What the current step produces: the round of questions, or the whole draft. For a question or a request no row fits, the answer.>
 

package/templates/base/plugins/sdlc/claude-code/skills/sdlc-mode/playbooks/maintain.md

@@ -13,6 +13,6 @@ This playbook starts from a finding such as an alert, a monitoring ticket, a fai
    - Start a subagent that has not seen the diagnosis, give it only the finding, the logs and files you read, and `intent.md`, and have it try to disprove the **Problem** section from the evidence. When you cannot start a subagent, read the evidence again from the first line as if someone else wrote the intent.
    - When a claim does not survive, move it under **Open questions**, and say in the pull request that the confidence check failed and on which claim.
 5. Commit `intent.md` on a new branch, push it, and open a pull request ready for review, as the opening paragraph of `playbooks/open-pr.md` says for branches and pull requests. When you cannot open a pull request from this session, say so and give the pushed branch's name.
-6. **Gate: the service owner triages the finding.** The service owner merges the pull request to fix the finding now, leaves it open to schedule it, or closes it to dismiss it. A dismissal tunes the bands: the service owner adjusts `bands.yaml` so the same noise raises fewer findings. The service owner asks the product owner to decide a product-facing finding. You do none of these. Report the pull request's URL, keep it green as `playbooks/review.md` says, and wait.
+6. **Gate: the service owner triages the finding.** The service owner merges the pull request to fix the finding now, comments on it with when the finding is scheduled and leaves it open, or closes it to dismiss it. An open pull request with no such comment is undecided: say so, and never report it as scheduled. A dismissal tunes the bands: the service owner adjusts `bands.yaml` so the same noise raises fewer findings. The service owner asks the product owner to decide a product-facing finding. You do none of these. Report the pull request's URL, keep it green as `playbooks/review.md` says, and wait.
 
 **Next:** `playbooks/design.md`; an agent; when the service owner has merged the intent's pull request and a person or a job sends `/sdlc:sdlc-mode` with the intent's path.

package/templates/base/plugins/sdlc/claude-code/skills/sdlc-mode/playbooks/review.md

@@ -1,6 +1,6 @@
 # Review phase: review the pull request and drive it to green
 
-1. Find what to review: the pull request this session just opened, or the pull request or branch the request names. When there is no pull request, or this session cannot reach its host, review the branch's diff against the default branch and put the findings in your reply in place of a comment.
+1. Find what to review: the pull request this session just opened, or the pull request or branch the request names. When there is no pull request, or this session cannot reach its host, review the branch's diff against the default branch and put the findings in your reply in place of a comment. When a pull request exists and this session cannot post on it, the findings are not in the pull request's history: the **Status** line says that the findings are not on the pull request and that a person posts them there, step 3 stays `open`, and you do not report the review as done.
 2. Review with a fresh context. Start a subagent that has not seen the work. Give it only the diff, `REVIEW.md`, the change's `intent/<change>/spec.md` and `plan.md`, and the four policy files in force, found as `playbooks/design.md` step 2 says. When you cannot start a subagent, read the diff again from the first line as if someone else wrote it. The review runs each pass in `REVIEW.md` and reports each finding with its pass, **Important** or **Nit**, `path:line`, and the evidence. A change that is not a fix, an intent, or a spec, and has no `spec.md` or no `plan.md`, is itself a finding.
 3. Post the findings as one comment on the pull request, most severe first. Write "No findings" when there are none. A finding does not decide the merge. When a finding flags a mistake that an earlier review of this project flagged too, its correction goes into the project's agent instructions as part of this review: in the push of step 4, or, on a pull request or a branch this session did not create, as the exact line in this comment.
 4. On a pull request or a branch that this session did not create, change nothing and push nothing. Skip the rest of this step, and in step 5 only read and answer. Otherwise, fix every Important finding. Run the checks the project's agent instructions name, and push. Answer each finding you do not fix with the reason.

package/templates/base/plugins/sdlc/claude-code/skills/setup-sdlc/SKILL.md

@@ -46,6 +46,8 @@ Do these steps in order. Run again with the same answers, the skill writes the s
    - `2. Owners: not done. .github/CODEOWNERS still holds the placeholder.`
    - `3. Repository settings: a person checks this. They live on the host, not in the repository.`
 
+   Report code owners, the ruleset of the default branch, and the OpenTelemetry export each on a line of its own, with what `SETUP.md` says the step needs, such as `Ruleset of main: a person checks this. It needs a repository admin, and in a private repository GitHub Pro, Team, or Enterprise.` A step that is not done fails no check.
+
 7. **Do the `not done` steps an agent can do:** a step whose whole work is editing a file of the repository with values the repository or the request already gives. Do not redo a `done` step. Do not edit a file the project's rules or agent settings reserve for a person, such as rules, hooks, lint, format, and commit configuration, and the agent settings themselves; list it with the exact new text and the file it goes in. Commit nothing. After each step, run its **Check** again and report the result.
 8. **List the steps a person does outside the repository,** each with who does it, from `SETUP.md`, and the full URL of the page where it is done when `SETUP.md` or the repository names one.
 9. **Write the reply** by the reply rules in `../sdlc-mode/SKILL.md`. After them, in this order: the budget line and the four role lines as written; each step of `SETUP.md` with its state; what you did; what a person does.

package/templates/base/plugins/sdlc/cursor/hooks/check-reply-shape.sh

@@ -3,8 +3,44 @@ command -v jq > /dev/null || exit 0
 mode=${1:-}
 input=$(cat)
 state_directory=${TMPDIR:-/tmp}/sdlc-reply-shape
-conversation=$(printf '%s' "$input" | jq -r '.conversation_id // ""' | tr -cd 'A-Za-z0-9_-')
+conversation=$(printf '%s' "$input" | jq -r '.conversation_id // .session_id // ""')
+conversation=${conversation:+$(printf '%s' "$conversation" | cksum | tr ' ' '-')}
+project=$(printf '%s' "$input" | jq -r '.cwd // .workspace_roots[0] // ""')
+snapshot_file=$state_directory/$conversation.files
+
+# A copy of the index and a scratch object store keep the project's own Git data unwritten.
+snapshot() {
+  [ -n "$project" ] && [ -n "$conversation" ] || return 1
+  repository=$(git -C "$project" rev-parse --show-toplevel 2> /dev/null) || return 1
+  index=$(git -C "$repository" rev-parse --git-path index) || return 1
+  objects=$(git -C "$repository" rev-parse --git-path objects) || return 1
+  case $index in /*) ;; *) index=$repository/$index ;; esac
+  case $objects in /*) ;; *) objects=$repository/$objects ;; esac
+  scratch=$state_directory/$conversation.git
+  rm -rf "$scratch"
+  mkdir -p "$scratch/objects" || return 1
+  cp "$index" "$scratch/index" 2> /dev/null
+  content=$(
+    export GIT_INDEX_FILE="$scratch/index" GIT_OBJECT_DIRECTORY="$scratch/objects" GIT_ALTERNATE_OBJECT_DIRECTORIES="$objects"
+    git -C "$repository" add -A -- ':(top)' ':(top,exclude)intent' 2> /dev/null
+    git -C "$repository" ls-files -s -- ':(top)' ':(top,exclude)intent' | cksum
+  )
+  rm -rf "$scratch"
+  printf '%s|%s' "$repository" "$content"
+}
+
+changed_since_snapshot() {
+  current=$(snapshot) || return 1
+  previous=$(cat "$snapshot_file" 2> /dev/null)
+  printf '%s' "$current" > "$snapshot_file"
+  [ "${previous%|*}" = "${current%|*}" ] && [ "$previous" != "$current" ]
+}
+
 case $mode in
+  snapshot)
+    changed_since_snapshot
+    exit 0
+    ;;
   save)
     text=$(printf '%s' "$input" | jq -r '.text // ""')
     [ -n "$text" ] && [ -n "$conversation" ] || exit 0
@@ -12,12 +48,16 @@ case $mode in
     exit 0
     ;;
   followup)
+    changed=false
+    changed_since_snapshot && changed=true
     [ -n "$conversation" ] && [ -f "$state_directory/$conversation" ] || exit 0
     reply=$(cat "$state_directory/$conversation")
     rm -f "$state_directory/$conversation"
     [ "$(printf '%s' "$input" | jq -r '"\(.status // "") \(.loop_count // "")"')" = 'completed 0' ] || exit 0
     ;;
   *)
+    changed=false
+    changed_since_snapshot && changed=true
     [ "$(printf '%s' "$input" | jq -r '.stop_hook_active // false')" = true ] && exit 0
     reply=$(printf '%s' "$input" | jq -r '.last_assistant_message // ""')
     ;;
@@ -48,6 +88,10 @@ case $last in
   *) problems="${problems}End the reply with a line that starts with **Status:**; nothing may follow it. " ;;
 esac
 
+if [ "$changed" = true ] && ! printf '%s\n' "$outside_fences" | grep -q '^\*\*Checks:\*\*'; then
+  problems="${problems}A file outside intent/ changed in this turn and the reply has no **Checks:** section. Run the checks the project names and add **Checks:** with each command and the lines of its output that show the result, or with each check that could not run and why. "
+fi
+
 [ -z "$problems" ] && exit 0
 jq -n --arg mode "$mode" --arg reason "${problems}Send the whole reply again." \
   'if $mode == "followup" then {followup_message:$reason} else {decision:"block",reason:$reason} end'

package/templates/base/plugins/sdlc/cursor/hooks/hooks.json

@@ -1,6 +1,11 @@
 {
   "version": 1,
   "hooks": {
+    "beforeSubmitPrompt": [
+      {
+        "command": "sh \"${CURSOR_PLUGIN_ROOT}/hooks/check-reply-shape.sh\" snapshot"
+      }
+    ],
     "afterAgentResponse": [
       {
         "command": "sh \"${CURSOR_PLUGIN_ROOT}/hooks/check-reply-shape.sh\" save"

package/templates/base/plugins/sdlc/cursor/skills/sdlc-mode/SKILL.md

@@ -49,7 +49,7 @@ For example, the person writes "who must approve pull request #7 of https://host
 
 **Steps:** <only when the session has no task-list tool, and never for the `question` playbook. One line for each numbered step of the playbook: `1. <the step, copied word for word>: done | open | skip: <reason>`. When the turn ran more than one playbook, one list for each, under its file name on a line of its own, such as `playbooks/build.md`.>
 
-**Checks:** <only when a step ran checks, and never for the `question` playbook. Each command, then the lines of its output that show the result, copied from the output.>
+**Checks:** <when a step ran checks, and always when the turn changed a file outside `intent/`, whichever playbook ran. Otherwise never for the `question` playbook. Each command, then the lines of its output that show the result, copied from the output. For a check that could not run, the check and why.>
 
 <What the current step produces: the round of questions, or the whole draft. For a question or a request no row fits, the answer.>
 

package/templates/base/plugins/sdlc/cursor/skills/sdlc-mode/playbooks/maintain.md

@@ -13,6 +13,6 @@ This playbook starts from a finding such as an alert, a monitoring ticket, a fai
    - Start a subagent that has not seen the diagnosis, give it only the finding, the logs and files you read, and `intent.md`, and have it try to disprove the **Problem** section from the evidence. When you cannot start a subagent, read the evidence again from the first line as if someone else wrote the intent.
    - When a claim does not survive, move it under **Open questions**, and say in the pull request that the confidence check failed and on which claim.
 5. Commit `intent.md` on a new branch, push it, and open a pull request ready for review, as the opening paragraph of `playbooks/open-pr.md` says for branches and pull requests. When you cannot open a pull request from this session, say so and give the pushed branch's name.
-6. **Gate: the service owner triages the finding.** The service owner merges the pull request to fix the finding now, leaves it open to schedule it, or closes it to dismiss it. A dismissal tunes the bands: the service owner adjusts `bands.yaml` so the same noise raises fewer findings. The service owner asks the product owner to decide a product-facing finding. You do none of these. Report the pull request's URL, keep it green as `playbooks/review.md` says, and wait.
+6. **Gate: the service owner triages the finding.** The service owner merges the pull request to fix the finding now, comments on it with when the finding is scheduled and leaves it open, or closes it to dismiss it. An open pull request with no such comment is undecided: say so, and never report it as scheduled. A dismissal tunes the bands: the service owner adjusts `bands.yaml` so the same noise raises fewer findings. The service owner asks the product owner to decide a product-facing finding. You do none of these. Report the pull request's URL, keep it green as `playbooks/review.md` says, and wait.
 
 **Next:** `playbooks/design.md`; an agent; when the service owner has merged the intent's pull request and a person or a job sends `/sdlc:sdlc-mode` with the intent's path.

package/templates/base/plugins/sdlc/cursor/skills/sdlc-mode/playbooks/review.md

@@ -1,6 +1,6 @@
 # Review phase: review the pull request and drive it to green
 
-1. Find what to review: the pull request this session just opened, or the pull request or branch the request names. When there is no pull request, or this session cannot reach its host, review the branch's diff against the default branch and put the findings in your reply in place of a comment.
+1. Find what to review: the pull request this session just opened, or the pull request or branch the request names. When there is no pull request, or this session cannot reach its host, review the branch's diff against the default branch and put the findings in your reply in place of a comment. When a pull request exists and this session cannot post on it, the findings are not in the pull request's history: the **Status** line says that the findings are not on the pull request and that a person posts them there, step 3 stays `open`, and you do not report the review as done.
 2. Review with a fresh context. Start a subagent that has not seen the work. Give it only the diff, `REVIEW.md`, the change's `intent/<change>/spec.md` and `plan.md`, and the four policy files in force, found as `playbooks/design.md` step 2 says. When you cannot start a subagent, read the diff again from the first line as if someone else wrote it. The review runs each pass in `REVIEW.md` and reports each finding with its pass, **Important** or **Nit**, `path:line`, and the evidence. A change that is not a fix, an intent, or a spec, and has no `spec.md` or no `plan.md`, is itself a finding.
 3. Post the findings as one comment on the pull request, most severe first. Write "No findings" when there are none. A finding does not decide the merge. When a finding flags a mistake that an earlier review of this project flagged too, its correction goes into the project's agent instructions as part of this review: in the push of step 4, or, on a pull request or a branch this session did not create, as the exact line in this comment.
 4. On a pull request or a branch that this session did not create, change nothing and push nothing. Skip the rest of this step, and in step 5 only read and answer. Otherwise, fix every Important finding. Run the checks the project's agent instructions name, and push. Answer each finding you do not fix with the reason.

package/templates/base/plugins/sdlc/cursor/skills/setup-sdlc/SKILL.md

@@ -46,6 +46,8 @@ Do these steps in order. Run again with the same answers, the skill writes the s
    - `2. Owners: not done. .github/CODEOWNERS still holds the placeholder.`
    - `3. Repository settings: a person checks this. They live on the host, not in the repository.`
 
+   Report code owners, the ruleset of the default branch, and the OpenTelemetry export each on a line of its own, with what `SETUP.md` says the step needs, such as `Ruleset of main: a person checks this. It needs a repository admin, and in a private repository GitHub Pro, Team, or Enterprise.` A step that is not done fails no check.
+
 7. **Do the `not done` steps an agent can do:** a step whose whole work is editing a file of the repository with values the repository or the request already gives. Do not redo a `done` step. Do not edit a file the project's rules or agent settings reserve for a person, such as rules, hooks, lint, format, and commit configuration, and the agent settings themselves; list it with the exact new text and the file it goes in. Commit nothing. After each step, run its **Check** again and report the result.
 8. **List the steps a person does outside the repository,** each with who does it, from `SETUP.md`, and the full URL of the page where it is done when `SETUP.md` or the repository names one.
 9. **Write the reply** by the reply rules in `../sdlc-mode/SKILL.md`. After them, in this order: the budget line and the four role lines as written; each step of `SETUP.md` with its state; what you did; what a person does.

package/templates/deploy-railway/turborepo/turbo.json

@@ -0,0 +1,66 @@
+{
+  "$schema": "https://turborepo.dev/schema.json",
+  "futureFlags": {
+    "affectedUsingTaskInputs": true
+  },
+  "globalDependencies": [
+    ".dockerignore",
+    ".env",
+    "package.json",
+    "pnpm-workspace.yaml",
+    "railway.json"
+  ],
+  "globalPassThroughEnv": [
+    "APP_URL",
+    "CI",
+    "DATABASE_URL",
+    "NEXT_TELEMETRY_DISABLED",
+    "PAYLOAD_SECRET"
+  ],
+  "tasks": {
+    "build": {
+      "dependsOn": ["^build"],
+      "inputs": ["$TURBO_DEFAULT$", "!README.md"],
+      "outputs": [".next/**", "!.next/cache/**", "!.next/dev/**"]
+    },
+    "depcruise": {
+      "inputs": ["$TURBO_DEFAULT$", "!README.md"]
+    },
+    "dev": {
+      "cache": false,
+      "persistent": true,
+      "inputs": ["$TURBO_DEFAULT$", "!README.md"]
+    },
+    "start": {
+      "cache": false,
+      "persistent": true,
+      "inputs": ["$TURBO_DEFAULT$", "!README.md"]
+    },
+    "test": {
+      "inputs": ["$TURBO_DEFAULT$", "!README.md"]
+    },
+    "test:changed": {
+      "cache": false,
+      "inputs": ["$TURBO_DEFAULT$", "!README.md"]
+    },
+    "test:coverage": {
+      "inputs": ["$TURBO_DEFAULT$", "!README.md"],
+      "outputs": ["coverage/**"]
+    },
+    "test:e2e": {
+      "cache": false,
+      "dependsOn": ["build"],
+      "inputs": ["$TURBO_DEFAULT$", "!README.md"]
+    },
+    "test:watch": {
+      "cache": false,
+      "persistent": true,
+      "inputs": ["$TURBO_DEFAULT$", "!README.md"]
+    },
+    "typecheck": {
+      "dependsOn": ["^typecheck"],
+      "inputs": ["$TURBO_DEFAULT$", "!README.md"],
+      "outputs": [".next/types/**", "next-env.d.ts"]
+    }
+  }
+}

package/templates/nestjs/AGENTS.md

@@ -45,7 +45,12 @@ The `verifier` subagent starts the app with `pnpm start:dev`. It exercises the c
 
 When Claude makes a mistake twice, add the correction here.
 
+<!-- deploy:railway -->
 - **Production gate**: `.agents/hooks/agent-production-gate.sh` blocks a shell command that deploys to `prod`, runs a Railway CLI command that names `prod`, or pushes a release tag, unless a release manager started the session with `RELEASE_APPROVAL` set. Any value lifts the gate except an empty value, `0`, `false`, and `no`, in any letter case. Report what is ready to promote instead. When a gated command appears only inside a message, write the text to a file with your file-editing tool, not a shell heredoc, and pass it with `git commit -F <file>` or `gh pr create --body-file <file>`. The gate reads only shell commands, so an MCP tool or a Railway command without `-e` or `--environment` passes it.
+<!-- deploy:end -->
+<!-- deploy:none -->
+- **Production gate**: `.agents/hooks/agent-production-gate.sh` blocks a shell command that deploys to `prod` or pushes a release tag, unless a release manager started the session with `RELEASE_APPROVAL` set. Any value lifts the gate except an empty value, `0`, `false`, and `no`, in any letter case. Report what is ready to promote instead. When a gated command appears only inside a message, write the text to a file with your file-editing tool, not a shell heredoc, and pass it with `git commit -F <file>` or `gh pr create --body-file <file>`. The gate reads only shell commands, so an MCP tool passes it.
+<!-- deploy:end -->
 - **Issues**: open an issue only to hand work to another person, never to give a pull request a number to close. A pull request closes an issue that already exists with `Closes #<issue>`.
 - **What belongs in the repository**: files, commit messages, and pull requests hold the change, its reason, and the checks. Write no date, log, history, mistake count, token figure, or session note into a file.
 - **Sourced requirements**: add a requirement to an intent, spec, or plan only when a person decided it or a named source says it. This includes a requirement a review bot suggests. When no person decided it and no source says it, leave it out and answer the thread with that.

package/templates/nestjs/Dockerfile

@@ -1,4 +1,4 @@
-# Runs on any OCI platform (Railway, Fly.io, Cloud Run). The platform sets `PORT`.
+# Runs on any OCI container platform. The platform sets `PORT`.
 FROM \
   node:24.22.1-alpine@sha256:06d7adf3e0ef61a13f1d28682726366f97a15aa1888c934d3ecec86c33918b53 \
   AS base

package/templates/nestjs/README.md

@@ -34,13 +34,15 @@ CI also runs the build, the end-to-end tests, the container image scan, and the
 
 ## Container
 
-The `Dockerfile` builds a production image that runs as a non-root user (UID 1000). The platform must set `PORT`; Railway sets it automatically. The build needs `pnpm-lock.yaml`, so run `pnpm install` once before the first `docker build`.
+The `Dockerfile` builds a production image that runs as a non-root user (UID 1000). The platform must set `PORT`. The build needs `pnpm-lock.yaml`, so run `pnpm install` once before the first `docker build`.
 
 ```sh
 docker build -t app .
 docker run --env PORT=3000 --publish 3000:3000 app
 ```
 
+<!-- deploy:railway -->
+
 ## Deploy
 
 `.github/workflows/deploy.yml` deploys the `Dockerfile` to Railway and promotes one commit through `dev`, `uat`, and `prod`. `railway.json` sets the Railway health check to `/health`. The workflow stays off until you configure it:
@@ -56,6 +58,18 @@ docker run --env PORT=3000 --publish 3000:3000 app
 3. Set the repository variable `DEPLOY_ENABLED` to `true`. Each push to `main` that passes CI then deploys to `dev`.
 4. Promote with **Actions → Deploy → Run workflow**, giving the environment and the full commit SHA. The workflow requires a successful CI run on `main` for that commit and a successful deployment to the previous environment, then waits for `/health`.
 
-Remove the workflow, `railway.json`, and the `deploy-dev` job in `ci.yml` if the project deploys elsewhere.
+<!-- deploy:end -->
+
+<!-- deploy:none -->
+
+## Deploy
+
+The project has no deploy step yet. A deploy step needs:
+
+- a workflow under `.github/workflows/` that deploys;
+- the `prod` environment under **Settings → Environments**, with the release managers as its required reviewers;
+- the image the `Dockerfile` builds.
+
+<!-- deploy:end -->
 
 See [CONTRIBUTING.md](CONTRIBUTING.md) for the contribution workflow.

package/templates/nextjs/AGENTS.md

@@ -46,7 +46,12 @@ The `verifier` subagent starts the app with `pnpm dev`. It exercises the changed
 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.
+<!-- deploy:railway -->
 - **Production gate**: `.agents/hooks/agent-production-gate.sh` blocks a shell command that deploys to `prod`, runs a Railway CLI command that names `prod`, or pushes a release tag, unless a release manager started the session with `RELEASE_APPROVAL` set. Any value lifts the gate except an empty value, `0`, `false`, and `no`, in any letter case. Report what is ready to promote instead. When a gated command appears only inside a message, write the text to a file with your file-editing tool, not a shell heredoc, and pass it with `git commit -F <file>` or `gh pr create --body-file <file>`. The gate reads only shell commands, so an MCP tool or a Railway command without `-e` or `--environment` passes it.
+<!-- deploy:end -->
+<!-- deploy:none -->
+- **Production gate**: `.agents/hooks/agent-production-gate.sh` blocks a shell command that deploys to `prod` or pushes a release tag, unless a release manager started the session with `RELEASE_APPROVAL` set. Any value lifts the gate except an empty value, `0`, `false`, and `no`, in any letter case. Report what is ready to promote instead. When a gated command appears only inside a message, write the text to a file with your file-editing tool, not a shell heredoc, and pass it with `git commit -F <file>` or `gh pr create --body-file <file>`. The gate reads only shell commands, so an MCP tool passes it.
+<!-- deploy:end -->
 - **Issues**: open an issue only to hand work to another person, never to give a pull request a number to close. A pull request closes an issue that already exists with `Closes #<issue>`.
 - **What belongs in the repository**: files, commit messages, and pull requests hold the change, its reason, and the checks. Write no date, log, history, mistake count, token figure, or session note into a file.
 - **Sourced requirements**: add a requirement to an intent, spec, or plan only when a person decided it or a named source says it. This includes a requirement a review bot suggests. When no person decided it and no source says it, leave it out and answer the thread with that.

package/templates/nextjs/Dockerfile

@@ -1,4 +1,4 @@
-# Runs on any OCI platform (Railway, Fly.io, Cloud Run). On Vercel, deploy without it. The platform sets `PORT`.
+# Runs on any OCI container platform. A platform that builds Next.js itself deploys without it. The platform sets `PORT`.
 FROM \
   node:24.22.1-alpine@sha256:06d7adf3e0ef61a13f1d28682726366f97a15aa1888c934d3ecec86c33918b53 \
   AS build

package/templates/nextjs/README.md

@@ -32,7 +32,7 @@ CI also runs the build, the end-to-end tests, the container image scan, and the
 
 ## Container
 
-The `Dockerfile` builds a standalone production image that runs as the `node` user, for platforms such as Railway. The server listens on `PORT`, or 3000 when it is unset.
+The `Dockerfile` builds a standalone production image that runs as the `node` user for a container platform. The server listens on `PORT`, or 3000 when it is unset.
 
 ```sh
 docker build -t app .
@@ -41,6 +41,8 @@ docker run --publish 3000:3000 app
 
 On Vercel, deploy without the image; the Next.js preset takes precedence over the `Dockerfile`.
 
+<!-- deploy:railway -->
+
 ## Deploy
 
 `.github/workflows/deploy.yml` deploys the `Dockerfile` to Railway and promotes one commit through `dev`, `uat`, and `prod`. `railway.json` sets the Railway health check to `/health`. The workflow stays off until you configure it:
@@ -56,6 +58,18 @@ On Vercel, deploy without the image; the Next.js preset takes precedence over th
 3. Set the repository variable `DEPLOY_ENABLED` to `true`. Each push to `main` that passes CI then deploys to `dev`.
 4. Promote with **Actions → Deploy → Run workflow**, giving the environment and the full commit SHA. The workflow requires a successful CI run on `main` for that commit and a successful deployment to the previous environment, then waits for `/health`.
 
-Remove the workflow, `railway.json`, and the `deploy-dev` job in `ci.yml` if the project deploys elsewhere.
+<!-- deploy:end -->
+
+<!-- deploy:none -->
+
+## Deploy
+
+The project has no deploy step yet. A deploy step needs:
+
+- a workflow under `.github/workflows/` that deploys;
+- the `prod` environment under **Settings → Environments**, with the release managers as its required reviewers;
+- the image the `Dockerfile` builds.
+
+<!-- deploy:end -->
 
 See [CONTRIBUTING.md](CONTRIBUTING.md) for the contribution workflow.

package/templates/nodejs/AGENTS.md

@@ -44,7 +44,12 @@ The `verifier` subagent starts the app with `pnpm start:dev`. It exercises the c
 
 When Claude makes a mistake twice, add the correction here.
 
+<!-- deploy:railway -->
 - **Production gate**: `.agents/hooks/agent-production-gate.sh` blocks a shell command that deploys to `prod`, runs a Railway CLI command that names `prod`, or pushes a release tag, unless a release manager started the session with `RELEASE_APPROVAL` set. Any value lifts the gate except an empty value, `0`, `false`, and `no`, in any letter case. Report what is ready to promote instead. When a gated command appears only inside a message, write the text to a file with your file-editing tool, not a shell heredoc, and pass it with `git commit -F <file>` or `gh pr create --body-file <file>`. The gate reads only shell commands, so an MCP tool or a Railway command without `-e` or `--environment` passes it.
+<!-- deploy:end -->
+<!-- deploy:none -->
+- **Production gate**: `.agents/hooks/agent-production-gate.sh` blocks a shell command that deploys to `prod` or pushes a release tag, unless a release manager started the session with `RELEASE_APPROVAL` set. Any value lifts the gate except an empty value, `0`, `false`, and `no`, in any letter case. Report what is ready to promote instead. When a gated command appears only inside a message, write the text to a file with your file-editing tool, not a shell heredoc, and pass it with `git commit -F <file>` or `gh pr create --body-file <file>`. The gate reads only shell commands, so an MCP tool passes it.
+<!-- deploy:end -->
 - **Issues**: open an issue only to hand work to another person, never to give a pull request a number to close. A pull request closes an issue that already exists with `Closes #<issue>`.
 - **What belongs in the repository**: files, commit messages, and pull requests hold the change, its reason, and the checks. Write no date, log, history, mistake count, token figure, or session note into a file.
 - **Sourced requirements**: add a requirement to an intent, spec, or plan only when a person decided it or a named source says it. This includes a requirement a review bot suggests. When no person decided it and no source says it, leave it out and answer the thread with that.

package/templates/nodejs/Dockerfile

@@ -1,4 +1,4 @@
-# Runs on any OCI platform (Railway, Fly.io, Cloud Run). The platform sets `PORT`.
+# Runs on any OCI container platform. The platform sets `PORT`.
 FROM \
   node:24.22.1-alpine@sha256:06d7adf3e0ef61a13f1d28682726366f97a15aa1888c934d3ecec86c33918b53 \
   AS base

package/templates/nodejs/README.md

@@ -32,13 +32,15 @@ CI also runs the build, the container image scan, and the security scans, includ
 
 ## Container
 
-The `Dockerfile` builds a production image that runs as a non-root user (UID 1000). The platform must set `PORT`; Railway sets it automatically. The build needs `pnpm-lock.yaml`, so run `pnpm install` once before the first `docker build`.
+The `Dockerfile` builds a production image that runs as a non-root user (UID 1000). The platform must set `PORT`. The build needs `pnpm-lock.yaml`, so run `pnpm install` once before the first `docker build`.
 
 ```sh
 docker build -t app .
 docker run --env PORT=3000 --publish 3000:3000 app
 ```
 
+<!-- deploy:railway -->
+
 ## Deploy
 
 `.github/workflows/deploy.yml` deploys the `Dockerfile` to Railway and promotes one commit through `dev`, `uat`, and `prod`. `railway.json` sets the Railway health check to `/health`. The workflow stays off until you configure it:
@@ -54,6 +56,18 @@ docker run --env PORT=3000 --publish 3000:3000 app
 3. Set the repository variable `DEPLOY_ENABLED` to `true`. Each push to `main` that passes CI then deploys to `dev`.
 4. Promote with **Actions → Deploy → Run workflow**, giving the environment and the full commit SHA. The workflow requires a successful CI run on `main` for that commit and a successful deployment to the previous environment, then waits for `/health`.
 
-Remove the workflow, `railway.json`, and the `deploy-dev` job in `ci.yml` if the project deploys elsewhere.
+<!-- deploy:end -->
+
+<!-- deploy:none -->
+
+## Deploy
+
+The project has no deploy step yet. A deploy step needs:
+
+- a workflow under `.github/workflows/` that deploys;
+- the `prod` environment under **Settings → Environments**, with the release managers as its required reviewers;
+- the image the `Dockerfile` builds.
+
+<!-- deploy:end -->
 
 See [CONTRIBUTING.md](CONTRIBUTING.md) for the contribution workflow.

package/templates/payload/AGENTS.md

@@ -49,7 +49,12 @@ The `verifier` subagent starts the app with `pnpm dev`, which needs a PostgreSQL
 When Claude makes a mistake twice, add the correction here.
 
 - **Database for `pnpm dev` and end-to-end tests**: both need a PostgreSQL database in `DATABASE_URL` and `PAYLOAD_SECRET` in `.env`; the README lists every variable. Run `pnpm exec playwright install chromium` once before the first `pnpm test:e2e`.
+<!-- deploy:railway -->
 - **Production gate**: `.agents/hooks/agent-production-gate.sh` blocks a shell command that deploys to `prod`, runs a Railway CLI command that names `prod`, or pushes a release tag, unless a release manager started the session with `RELEASE_APPROVAL` set. Any value lifts the gate except an empty value, `0`, `false`, and `no`, in any letter case. Report what is ready to promote instead. When a gated command appears only inside a message, write the text to a file with your file-editing tool, not a shell heredoc, and pass it with `git commit -F <file>` or `gh pr create --body-file <file>`. The gate reads only shell commands, so an MCP tool or a Railway command without `-e` or `--environment` passes it.
+<!-- deploy:end -->
+<!-- deploy:none -->
+- **Production gate**: `.agents/hooks/agent-production-gate.sh` blocks a shell command that deploys to `prod` or pushes a release tag, unless a release manager started the session with `RELEASE_APPROVAL` set. Any value lifts the gate except an empty value, `0`, `false`, and `no`, in any letter case. Report what is ready to promote instead. When a gated command appears only inside a message, write the text to a file with your file-editing tool, not a shell heredoc, and pass it with `git commit -F <file>` or `gh pr create --body-file <file>`. The gate reads only shell commands, so an MCP tool passes it.
+<!-- deploy:end -->
 - **Issues**: open an issue only to hand work to another person, never to give a pull request a number to close. A pull request closes an issue that already exists with `Closes #<issue>`.
 - **What belongs in the repository**: files, commit messages, and pull requests hold the change, its reason, and the checks. Write no date, log, history, mistake count, token figure, or session note into a file.
 - **Sourced requirements**: add a requirement to an intent, spec, or plan only when a person decided it or a named source says it. This includes a requirement a review bot suggests. When no person decided it and no source says it, leave it out and answer the thread with that.

package/templates/payload/Dockerfile

@@ -1,4 +1,4 @@
-# Runs on any OCI platform (Railway, Fly.io, Cloud Run). On Vercel, deploy without it. The platform sets `PORT`.
+# Runs on any OCI container platform. A platform that builds Next.js itself deploys without it. The platform sets `PORT`.
 FROM \
   node:24.22.1-alpine@sha256:06d7adf3e0ef61a13f1d28682726366f97a15aa1888c934d3ecec86c33918b53 \
   AS build

package/templates/payload/README.md

@@ -48,7 +48,7 @@ CI also runs the build, the end-to-end tests, the container image scan, and the
 
 ## Container
 
-The `Dockerfile` builds a standalone production image that runs as the `node` user, for platforms such as Railway. The server listens on `PORT`, or 3000 when it is unset, and needs `DATABASE_URL`, `PAYLOAD_SECRET`, and `APP_URL`, the public URL that Payload accepts cookie-authenticated and cross-origin requests from.
+The `Dockerfile` builds a standalone production image that runs as the `node` user for a container platform. The server listens on `PORT`, or 3000 when it is unset, and needs `DATABASE_URL`, `PAYLOAD_SECRET`, and `APP_URL`, the public URL that Payload accepts cookie-authenticated and cross-origin requests from.
 
 ```sh
 docker build -t app .
@@ -61,6 +61,8 @@ The config sets no `email` adapter, so Payload writes every email, including pas
 
 On Vercel, deploy without the image; the Next.js preset takes precedence over the `Dockerfile`.
 
+<!-- deploy:railway -->
+
 ## Deploy
 
 `.github/workflows/deploy.yml` deploys the `Dockerfile` to Railway and promotes one commit through `dev`, `uat`, and `prod`. `railway.json` sets the Railway health check to `/health`. The workflow stays off until you configure it:
@@ -82,6 +84,18 @@ On Vercel, deploy without the image; the Next.js preset takes precedence over th
 3. Set the repository variable `DEPLOY_ENABLED` to `true`. Each push to `main` that passes CI then deploys to `dev`.
 4. Promote with **Actions → Deploy → Run workflow**, giving the environment and the full commit SHA. The workflow requires a successful CI run on `main` for that commit and a successful deployment to the previous environment, then waits for `/health`.
 
-Remove the workflow, `railway.json`, and the `deploy-dev` job in `ci.yml` if the project deploys elsewhere.
+<!-- deploy:end -->
+
+<!-- deploy:none -->
+
+## Deploy
+
+The project has no deploy step yet. A deploy step needs:
+
+- a workflow under `.github/workflows/` that deploys;
+- the `prod` environment under **Settings → Environments**, with the release managers as its required reviewers;
+- the image the `Dockerfile` builds.
+
+<!-- deploy:end -->
 
 See [CONTRIBUTING.md](CONTRIBUTING.md) for the contribution workflow.

package/templates/turborepo/AGENTS.md

@@ -52,7 +52,12 @@ When Claude makes a mistake twice, add the correction here.
 
 - **Next.js docs live per app**: this Next.js version differs from your training data. Read the guide in `apps/app/node_modules/next/dist/docs/` or `apps/backoffice/node_modules/next/dist/docs/` before writing Next.js code; the workspace root has no `next` package.
 - **Database for `pnpm dev` and end-to-end tests**: the backoffice needs a PostgreSQL database in `DATABASE_URL` and `PAYLOAD_SECRET` in `.env`; the README lists every variable. Run `pnpm --filter ./apps/app exec playwright install chromium` once before the first `pnpm test:e2e`.
+<!-- deploy:railway -->
 - **Production gate**: `.agents/hooks/agent-production-gate.sh` blocks a shell command that deploys to `prod`, runs a Railway CLI command that names `prod`, or pushes a release tag, unless a release manager started the session with `RELEASE_APPROVAL` set. Any value lifts the gate except an empty value, `0`, `false`, and `no`, in any letter case. Report what is ready to promote instead. When a gated command appears only inside a message, write the text to a file with your file-editing tool, not a shell heredoc, and pass it with `git commit -F <file>` or `gh pr create --body-file <file>`. The gate reads only shell commands, so an MCP tool or a Railway command without `-e` or `--environment` passes it.
+<!-- deploy:end -->
+<!-- deploy:none -->
+- **Production gate**: `.agents/hooks/agent-production-gate.sh` blocks a shell command that deploys to `prod` or pushes a release tag, unless a release manager started the session with `RELEASE_APPROVAL` set. Any value lifts the gate except an empty value, `0`, `false`, and `no`, in any letter case. Report what is ready to promote instead. When a gated command appears only inside a message, write the text to a file with your file-editing tool, not a shell heredoc, and pass it with `git commit -F <file>` or `gh pr create --body-file <file>`. The gate reads only shell commands, so an MCP tool passes it.
+<!-- deploy:end -->
 - **Issues**: open an issue only to hand work to another person, never to give a pull request a number to close. A pull request closes an issue that already exists with `Closes #<issue>`.
 - **What belongs in the repository**: files, commit messages, and pull requests hold the change, its reason, and the checks. Write no date, log, history, mistake count, token figure, or session note into a file.
 - **Sourced requirements**: add a requirement to an intent, spec, or plan only when a person decided it or a named source says it. This includes a requirement a review bot suggests. When no person decided it and no source says it, leave it out and answer the thread with that.

package/templates/turborepo/README.md

@@ -61,6 +61,8 @@ Uploaded images, up to 10 MB each, are written to the backoffice container files
 
 On Vercel, deploy an app without its image. The Next.js preset takes precedence over the Dockerfile.
 
+<!-- deploy:railway -->
+
 ## Deploy
 
 `.github/workflows/deploy.yml` deploys both apps and promotes one commit through `dev`, `uat`, and `prod`. `railway.json` sets the Railway health check to `/health`. Create one Railway service per app, with that service's Dockerfile path set to `apps/app/Dockerfile` or `apps/backoffice/Dockerfile`. The workflow stays off until you configure it:
@@ -84,7 +86,19 @@ On Vercel, deploy an app without its image. The Next.js preset takes precedence
 3. Set the repository variable `DEPLOY_ENABLED` to `true`. Each push to `main` that passes CI then deploys to `dev`. The workflow compares the commit with the commit of the last successful deploy to that environment, found from the successful `deploy.yml` and `ci.yml` runs on `main`, and runs `railway up` only for services whose packages changed. A promotion through `uat` or `prod` uses the same comparison against the commit last deployed there, so several commits still ship every changed service. The first deploy to an environment ships both services.
 4. Promote with **Actions → Deploy → Run workflow**, giving the environment and the full commit SHA. The workflow requires a successful CI run on `main` for that commit and a successful deployment to the previous environment, then waits for `/health` on each service it uploaded.
 
-Remove the workflow, `railway.json`, and the `deploy-dev` job in `ci.yml` if the project deploys elsewhere.
+<!-- deploy:end -->
+
+<!-- deploy:none -->
+
+## Deploy
+
+The project has no deploy step yet. A deploy step needs:
+
+- a workflow under `.github/workflows/` that deploys;
+- the `prod` environment under **Settings → Environments**, with the release managers as its required reviewers;
+- the image the `Dockerfile` builds.
+
+<!-- deploy:end -->
 
 ## Mobile app
 
@@ -94,6 +108,6 @@ To add an Expo app, create it under `apps/mobile`:
 2. Use `@expo/fingerprint` with `expo-github-action/fingerprint` so a pull request requests a native build only when the native layer changed ([Expo fingerprint](https://docs.expo.dev/versions/latest/sdk/fingerprint/)).
 3. Keep a single `react-native` version in the workspace. Duplicate React Native versions in one monorepo are not supported ([Expo: Monorepos](https://docs.expo.dev/guides/monorepos/)).
 
-EAS Build and Submit replace Railway for that app. CI `--affected` already includes `apps/*` and `packages/*`, so an Expo app is skipped when it did not change.
+EAS Build and Submit deploy that app, in place of the project's deploy step. CI `--affected` already includes `apps/*` and `packages/*`, so an Expo app is skipped when it did not change.
 
 See [CONTRIBUTING.md](CONTRIBUTING.md) for the contribution workflow.

package/templates/turborepo/apps/app/Dockerfile

@@ -1,4 +1,4 @@
-# Runs on any OCI platform (Railway, Fly.io, Cloud Run). On Vercel, deploy without it. The platform sets `PORT`.
+# Runs on any OCI container platform. A platform that builds Next.js itself deploys without it. The platform sets `PORT`.
 FROM \
   node:24.22.1-alpine@sha256:06d7adf3e0ef61a13f1d28682726366f97a15aa1888c934d3ecec86c33918b53 \
   AS build

package/templates/turborepo/apps/backoffice/Dockerfile

@@ -1,4 +1,4 @@
-# Runs on any OCI platform (Railway, Fly.io, Cloud Run). On Vercel, deploy without it. The platform sets `PORT`.
+# Runs on any OCI container platform. A platform that builds Next.js itself deploys without it. The platform sets `PORT`.
 FROM \
   node:24.22.1-alpine@sha256:06d7adf3e0ef61a13f1d28682726366f97a15aa1888c934d3ecec86c33918b53 \
   AS build

package/templates/turborepo/turbo.json

@@ -3,13 +3,7 @@
   "futureFlags": {
     "affectedUsingTaskInputs": true
   },
-  "globalDependencies": [
-    ".dockerignore",
-    ".env",
-    "package.json",
-    "pnpm-workspace.yaml",
-    "railway.json"
-  ],
+  "globalDependencies": [".dockerignore", ".env", "package.json", "pnpm-workspace.yaml"],
   "globalPassThroughEnv": [
     "APP_URL",
     "CI",