@next-friday/create-app 9.4.0 → 9.5.0

package/package.json

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

package/templates/base/.agents/release-approval-form

@@ -0,0 +1 @@
+^[A-Z]+-[0-9]+$

package/templates/base/SETUP.md

@@ -92,7 +92,7 @@ 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.
-- **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`. Any value lifts the gate except an empty value, `0`, `false`, and `no`, in any letter case.
+- **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, and the reason for a block, and, when the production gate is lifted, the approval value and the Git user name.
 - **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/skills/sdlc-mode/playbooks/build.md

@@ -9,7 +9,7 @@ This playbook turns a merged spec into a plan the engineer accepts, and then int
 
    When the request is a bug fix with no spec, none of these cases applies: follow `playbooks/fix.md` instead.
 
-2. When `intent/<change>/plan.md` is on the default branch, the engineer accepted it by merging its pull request: go to step 6. When it exists only on a branch that is not merged, check out that branch, show that plan, and go to step 5.
+2. When `intent/<change>/plan.md` is on the default branch, the engineer accepted it by merging its pull request: go to step 7. When it exists only on a branch that is not merged, check out that branch, show that plan, and go to step 5.
 3. Read `intent.md`, `spec.md`, the four policies, found as `playbooks/design.md` step 2 says, and the code the change touches. Start from the accepted spec, in the agent tool's plan mode when it has one, and give the plan the change's `intent.md` and `spec.md`. Then interview the engineer until they have said four things: the files the change touches, the order of the work, the tests that prove it, and each option they rule out.
    - **When all four are already said, in the request or in the files, go to step 4 in the same turn.**
    - **When one is missing, ask and stop.** Write no plan in that turn. Ask in rounds, as step 3 of `playbooks/plan.md` does: numbered questions, each with a recommended answer or "No recommendation". Wait for the answers, and build the next round on them.
@@ -21,13 +21,14 @@ This playbook turns a merged spec into a plan the engineer accepts, and then int
 
    Show the whole plan and name the file only as `intent/<change>/plan.md`. In plan mode you cannot write the file. Show the plan as the plan.
 
-5. **Gate: the engineer accepts the plan.** Commit `intent/<change>/plan.md` on a new branch, with the `Accepted by:` line as the template has it. In that commit, set the spec's status line to `Status: accepted.`, because its pull request is merged. Push the branch and open a pull request that changes no file outside `intent/`, as the opening paragraph of `playbooks/open-pr.md` says for branches and pull requests. Revise the plan as the engineer asks; each revision is a commit on that branch. The engineer merges that pull request to accept the plan, or closes it to reject it. You never merge it, and you change no file outside `intent/` before it is merged. In plan mode, the engineer's approval lets you write the file and open this pull request; it is not the acceptance. When the spec classes the change as higher risk, say that a tech lead or an architect approves that pull request before it is merged. Report the pull request's URL, keep it green as `playbooks/review.md` says, and wait.
-6. When the plan's pull request is merged, create a new branch as `playbooks/open-pr.md` says. In its first commit, set the plan's `Accepted by:` line, under its title, to the account that merged that pull request, read from the host. When that pull request has an approving review from a second person, add `Also accepted by: @<handle>.` on the next line. When you cannot read the host, write the handle the engineer gives. Never write a handle the host or the engineer did not give.
-7. Implement the plan in its order. After each step, run the check that proves it and fix what fails. For a bug fix, follow `playbooks/fix.md` steps 7 and 8: commit the failing test on a `fix/` branch, and the gate then blocks test edits. When the work departs from the plan, change `plan.md` in the same commit. When the change meets the last requirement of `spec.md`, set `Status: done.` in `intent.md` and `spec.md`.
-8. Run every check the project's agent instructions name and keep the output. Every check must pass: fix the code, and never skip, delete, or weaken a test. Then run the `verifier` subagent and fix what it reports. Start it on the model that `.agents/sdlc-models.md` names after `verify:`, at the effort on that line when the session can set one; when you cannot start a subagent, do what `../../../agents/verifier.md`, relative to this playbook, says yourself. For UI work, when the session has a browser tool, also close the loop with a visual check: start the app, give the browser tool the page and the mock the spec or the request names, screenshot, compare, and adjust, and repeat until it matches; two or three rounds is normal. When a check cannot run in this session, say which one and why, and never report it as passed.
-9. Go on in the same turn, without asking: follow `playbooks/open-pr.md`, and then `playbooks/review.md`. Pushing the branch and opening the pull request are part of this task.
+5. Commit `intent/<change>/plan.md` on a new branch, unless step 2 checked one out, with the `Accepted by:` line as the template has it. In that commit, set the spec's status line to `Status: accepted.`, because its pull request is merged; when an area of concern of that spec has no `Decision:` line, add it there with the decision you propose, as `playbooks/design.md` step 3 says. Push the branch and open a pull request that changes no file outside `intent/`, as the opening paragraph of `playbooks/open-pr.md` says for branches and pull requests. When the branch already has a pull request, update that one. In plan mode, the engineer's approval lets you write the file and do this step; it is not the acceptance.
+6. **Gate: the engineer accepts the plan.** The engineer merges that pull request to accept the plan, or closes it to reject it. You never merge it, and you change no file outside `intent/` before it is merged. Revise the plan as the engineer asks; each revision is a commit on that branch. When the spec classes the change as higher risk, say that a tech lead or an architect approves that pull request before it is merged. Report the pull request's URL, or the pushed branch's name when you could not open one, keep it green as `playbooks/review.md` says, and wait.
+7. When the plan's pull request is merged, create a new branch as `playbooks/open-pr.md` says. In its first commit, set the plan's `Accepted by:` line, under its title, to the account that merged that pull request, read from the host. When that pull request has an approving review from a second person, add `Also accepted by: @<handle>.` on the next line. When you cannot read the host, confirm with `git fetch` that the plan is on the default branch, and write the handle the engineer gives; ask for it when they gave none. Never write a handle the host or the engineer did not give.
+8. Implement the plan in its order. After each step, run the check that proves it and fix what fails. For a bug fix, follow `playbooks/fix.md` steps 8 and 9: commit the failing test on a `fix/` branch, and the gate then blocks test edits. When the work departs from the plan, change `plan.md` in the same commit. When the change meets the last requirement of `spec.md`, set `Status: done.` in `intent.md` and `spec.md`.
+9. Run every check the project's agent instructions name and keep the output. Every check must pass: fix the code, and never skip, delete, or weaken a test. Then run the `verifier` subagent and fix what it reports. Start it on the model that `.agents/sdlc-models.md` names after `verify:`, at the effort on that line when the session can set one; when you cannot start a subagent, do what `../../../agents/verifier.md`, relative to this playbook, says yourself. For UI work, when the session has a browser tool, also close the loop with a visual check: start the app, give the browser tool the page and the mock the spec or the request names, screenshot, compare, and adjust, and repeat until it matches; two or three rounds is normal. When a check cannot run in this session, say which one and why, and never report it as passed.
+10. Go on in the same turn, without asking: follow `playbooks/open-pr.md`, and then `playbooks/review.md`. Pushing the branch and opening the pull request are part of this task.
 
-**Next:** `playbooks/open-pr.md`; an agent; in the same turn, as soon as step 8 passes.
+**Next:** `playbooks/open-pr.md`; an agent; in the same turn, as soon as step 9 passes.
 
 ## Template
 

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

@@ -2,7 +2,7 @@
 
 This playbook takes a defect in behaviour that already exists to a pull request. It has no intent and no spec: its plan is the only file it adds under `intent/`.
 
-1. Decide that the request qualifies. It qualifies only when the request is a defect in behaviour that already exists, and the fix adds no new behaviour and no new dependency and changes no schema and no public interface. When a condition fails, say which one in two lines and follow `playbooks/plan.md` instead.
+1. Decide that the request qualifies. It qualifies only when the request is a defect in behaviour that already exists, and the fix adds no new behaviour and no new dependency and changes no schema and no public interface. When a condition fails, say which one in two lines and follow `playbooks/plan.md` instead. When `intent/<short-description>/plan.md` for this defect is already on the default branch, the engineer accepted it by merging its pull request: go to step 7.
 2. Reproduce the defect yourself by running the code, and keep the output. Ask the person only when you can name the specific reason you cannot reach it, such as a credential or a service this session cannot use.
 3. Find the cause from what running the code shows. List the candidate causes, rule each out with a command or an observation, and never guess. Name the one cause the evidence leaves. When it leaves none, or more than one, say so and ask for what is missing.
 4. Write the plan from the template in `playbooks/build.md`. The title is `# Plan: <title> (fix)`. Use exactly the template's four headings, and keep the plan short. Name the file `intent/<short-description>/plan.md`; the folder holds only this file.
@@ -13,11 +13,12 @@ This playbook takes a defect in behaviour that already exists to a pull request.
 
    Show the whole plan and name the file only as `intent/<short-description>/plan.md`. In plan mode you cannot write the file. Show the plan as the plan.
 
-5. **Gate: the engineer accepts the plan.** Commit `intent/<short-description>/plan.md` on a new branch, with the `Accepted by:` line as the template has it, push it, and open a pull request that changes no file outside `intent/`, as the opening paragraph of `playbooks/open-pr.md` says for branches and pull requests. Revise the plan as the engineer asks; each revision is a commit on that branch. The engineer merges that pull request to accept the plan, or closes it to reject it. You never merge it, and you change no file outside `intent/` before it is merged. In plan mode, the engineer's approval lets you write the file and open this pull request; it is not the acceptance. Report the pull request's URL, keep it green as `playbooks/review.md` says, and wait.
-6. When the plan's pull request is merged, create the branch `fix/<short-description>` as `playbooks/open-pr.md` says. In its first commit, set the plan's `Accepted by:` line, under its title, to the account that merged that pull request, read from the host. When you cannot read the host, write the handle the engineer gives. Never write a handle the host or the engineer did not give.
-7. Reproduce the defect as a test. Run it and check that it fails for the reason the cause gives. Commit the failing test before any fix.
-8. Make the test pass without editing it.
-9. Run every check the project's agent instructions name. Keep the output. When one fails, fix the code, and never skip, delete, or weaken a test. When a check cannot run in this session, say which one and why, and never report it as passed.
-10. Go on in the same turn, without asking. Follow `playbooks/open-pr.md`, and then `playbooks/review.md`.
+5. Commit `intent/<short-description>/plan.md` on a new branch, with the `Accepted by:` line as the template has it, push it, and open a pull request that changes no file outside `intent/`, as the opening paragraph of `playbooks/open-pr.md` says for branches and pull requests. In plan mode, the engineer's approval lets you write the file and do this step; it is not the acceptance.
+6. **Gate: the engineer accepts the plan.** The engineer merges that pull request to accept the plan, or closes it to reject it. You never merge it, and you change no file outside `intent/` before it is merged. Revise the plan as the engineer asks; each revision is a commit on that branch. Report the pull request's URL, or the pushed branch's name when you could not open one, keep it green as `playbooks/review.md` says, and wait.
+7. When the plan's pull request is merged, create the branch `fix/<short-description>` as `playbooks/open-pr.md` says. In its first commit, set the plan's `Accepted by:` line, under its title, to the account that merged that pull request, read from the host. When you cannot read the host, confirm with `git fetch` that the plan is on the default branch, and write the handle the engineer gives; ask for it when they gave none. Never write a handle the host or the engineer did not give.
+8. Reproduce the defect as a test. Run it and check that it fails for the reason the cause gives. Commit the failing test before any fix.
+9. Make the test pass without editing it.
+10. Run every check the project's agent instructions name. Keep the output. When one fails, fix the code, and never skip, delete, or weaken a test. When a check cannot run in this session, say which one and why, and never report it as passed.
+11. Go on in the same turn, without asking. Follow `playbooks/open-pr.md`, and then `playbooks/review.md`.
 
-**Next:** `playbooks/open-pr.md`; an agent; in the same turn, as soon as step 9 passes.
+**Next:** `playbooks/open-pr.md`; an agent; in the same turn, as soon as step 10 passes.

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

@@ -9,7 +9,7 @@ This playbook turns a merged spec into a plan the engineer accepts, and then int
 
    When the request is a bug fix with no spec, none of these cases applies: follow `playbooks/fix.md` instead.
 
-2. When `intent/<change>/plan.md` is on the default branch, the engineer accepted it by merging its pull request: go to step 6. When it exists only on a branch that is not merged, check out that branch, show that plan, and go to step 5.
+2. When `intent/<change>/plan.md` is on the default branch, the engineer accepted it by merging its pull request: go to step 7. When it exists only on a branch that is not merged, check out that branch, show that plan, and go to step 5.
 3. Read `intent.md`, `spec.md`, the four policies, found as `playbooks/design.md` step 2 says, and the code the change touches. Start from the accepted spec, in the agent tool's plan mode when it has one, and give the plan the change's `intent.md` and `spec.md`. Then interview the engineer until they have said four things: the files the change touches, the order of the work, the tests that prove it, and each option they rule out.
    - **When all four are already said, in the request or in the files, go to step 4 in the same turn.**
    - **When one is missing, ask and stop.** Write no plan in that turn. Ask in rounds, as step 3 of `playbooks/plan.md` does: numbered questions, each with a recommended answer or "No recommendation". Wait for the answers, and build the next round on them.
@@ -21,13 +21,14 @@ This playbook turns a merged spec into a plan the engineer accepts, and then int
 
    Show the whole plan and name the file only as `intent/<change>/plan.md`. In plan mode you cannot write the file. Show the plan as the plan.
 
-5. **Gate: the engineer accepts the plan.** Commit `intent/<change>/plan.md` on a new branch, with the `Accepted by:` line as the template has it. In that commit, set the spec's status line to `Status: accepted.`, because its pull request is merged. Push the branch and open a pull request that changes no file outside `intent/`, as the opening paragraph of `playbooks/open-pr.md` says for branches and pull requests. Revise the plan as the engineer asks; each revision is a commit on that branch. The engineer merges that pull request to accept the plan, or closes it to reject it. You never merge it, and you change no file outside `intent/` before it is merged. In plan mode, the engineer's approval lets you write the file and open this pull request; it is not the acceptance. When the spec classes the change as higher risk, say that a tech lead or an architect approves that pull request before it is merged. Report the pull request's URL, keep it green as `playbooks/review.md` says, and wait.
-6. When the plan's pull request is merged, create a new branch as `playbooks/open-pr.md` says. In its first commit, set the plan's `Accepted by:` line, under its title, to the account that merged that pull request, read from the host. When that pull request has an approving review from a second person, add `Also accepted by: @<handle>.` on the next line. When you cannot read the host, write the handle the engineer gives. Never write a handle the host or the engineer did not give.
-7. Implement the plan in its order. After each step, run the check that proves it and fix what fails. For a bug fix, follow `playbooks/fix.md` steps 7 and 8: commit the failing test on a `fix/` branch, and the gate then blocks test edits. When the work departs from the plan, change `plan.md` in the same commit. When the change meets the last requirement of `spec.md`, set `Status: done.` in `intent.md` and `spec.md`.
-8. Run every check the project's agent instructions name and keep the output. Every check must pass: fix the code, and never skip, delete, or weaken a test. Then run the `verifier` subagent and fix what it reports. Start it on the model that `.agents/sdlc-models.md` names after `verify:`, at the effort on that line when the session can set one; when you cannot start a subagent, do what `../../../agents/verifier.md`, relative to this playbook, says yourself. For UI work, when the session has a browser tool, also close the loop with a visual check: start the app, give the browser tool the page and the mock the spec or the request names, screenshot, compare, and adjust, and repeat until it matches; two or three rounds is normal. When a check cannot run in this session, say which one and why, and never report it as passed.
-9. Go on in the same turn, without asking: follow `playbooks/open-pr.md`, and then `playbooks/review.md`. Pushing the branch and opening the pull request are part of this task.
+5. Commit `intent/<change>/plan.md` on a new branch, unless step 2 checked one out, with the `Accepted by:` line as the template has it. In that commit, set the spec's status line to `Status: accepted.`, because its pull request is merged; when an area of concern of that spec has no `Decision:` line, add it there with the decision you propose, as `playbooks/design.md` step 3 says. Push the branch and open a pull request that changes no file outside `intent/`, as the opening paragraph of `playbooks/open-pr.md` says for branches and pull requests. When the branch already has a pull request, update that one. In plan mode, the engineer's approval lets you write the file and do this step; it is not the acceptance.
+6. **Gate: the engineer accepts the plan.** The engineer merges that pull request to accept the plan, or closes it to reject it. You never merge it, and you change no file outside `intent/` before it is merged. Revise the plan as the engineer asks; each revision is a commit on that branch. When the spec classes the change as higher risk, say that a tech lead or an architect approves that pull request before it is merged. Report the pull request's URL, or the pushed branch's name when you could not open one, keep it green as `playbooks/review.md` says, and wait.
+7. When the plan's pull request is merged, create a new branch as `playbooks/open-pr.md` says. In its first commit, set the plan's `Accepted by:` line, under its title, to the account that merged that pull request, read from the host. When that pull request has an approving review from a second person, add `Also accepted by: @<handle>.` on the next line. When you cannot read the host, confirm with `git fetch` that the plan is on the default branch, and write the handle the engineer gives; ask for it when they gave none. Never write a handle the host or the engineer did not give.
+8. Implement the plan in its order. After each step, run the check that proves it and fix what fails. For a bug fix, follow `playbooks/fix.md` steps 8 and 9: commit the failing test on a `fix/` branch, and the gate then blocks test edits. When the work departs from the plan, change `plan.md` in the same commit. When the change meets the last requirement of `spec.md`, set `Status: done.` in `intent.md` and `spec.md`.
+9. Run every check the project's agent instructions name and keep the output. Every check must pass: fix the code, and never skip, delete, or weaken a test. Then run the `verifier` subagent and fix what it reports. Start it on the model that `.agents/sdlc-models.md` names after `verify:`, at the effort on that line when the session can set one; when you cannot start a subagent, do what `../../../agents/verifier.md`, relative to this playbook, says yourself. For UI work, when the session has a browser tool, also close the loop with a visual check: start the app, give the browser tool the page and the mock the spec or the request names, screenshot, compare, and adjust, and repeat until it matches; two or three rounds is normal. When a check cannot run in this session, say which one and why, and never report it as passed.
+10. Go on in the same turn, without asking: follow `playbooks/open-pr.md`, and then `playbooks/review.md`. Pushing the branch and opening the pull request are part of this task.
 
-**Next:** `playbooks/open-pr.md`; an agent; in the same turn, as soon as step 8 passes.
+**Next:** `playbooks/open-pr.md`; an agent; in the same turn, as soon as step 9 passes.
 
 ## Template
 

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

@@ -2,7 +2,7 @@
 
 This playbook takes a defect in behaviour that already exists to a pull request. It has no intent and no spec: its plan is the only file it adds under `intent/`.
 
-1. Decide that the request qualifies. It qualifies only when the request is a defect in behaviour that already exists, and the fix adds no new behaviour and no new dependency and changes no schema and no public interface. When a condition fails, say which one in two lines and follow `playbooks/plan.md` instead.
+1. Decide that the request qualifies. It qualifies only when the request is a defect in behaviour that already exists, and the fix adds no new behaviour and no new dependency and changes no schema and no public interface. When a condition fails, say which one in two lines and follow `playbooks/plan.md` instead. When `intent/<short-description>/plan.md` for this defect is already on the default branch, the engineer accepted it by merging its pull request: go to step 7.
 2. Reproduce the defect yourself by running the code, and keep the output. Ask the person only when you can name the specific reason you cannot reach it, such as a credential or a service this session cannot use.
 3. Find the cause from what running the code shows. List the candidate causes, rule each out with a command or an observation, and never guess. Name the one cause the evidence leaves. When it leaves none, or more than one, say so and ask for what is missing.
 4. Write the plan from the template in `playbooks/build.md`. The title is `# Plan: <title> (fix)`. Use exactly the template's four headings, and keep the plan short. Name the file `intent/<short-description>/plan.md`; the folder holds only this file.
@@ -13,11 +13,12 @@ This playbook takes a defect in behaviour that already exists to a pull request.
 
    Show the whole plan and name the file only as `intent/<short-description>/plan.md`. In plan mode you cannot write the file. Show the plan as the plan.
 
-5. **Gate: the engineer accepts the plan.** Commit `intent/<short-description>/plan.md` on a new branch, with the `Accepted by:` line as the template has it, push it, and open a pull request that changes no file outside `intent/`, as the opening paragraph of `playbooks/open-pr.md` says for branches and pull requests. Revise the plan as the engineer asks; each revision is a commit on that branch. The engineer merges that pull request to accept the plan, or closes it to reject it. You never merge it, and you change no file outside `intent/` before it is merged. In plan mode, the engineer's approval lets you write the file and open this pull request; it is not the acceptance. Report the pull request's URL, keep it green as `playbooks/review.md` says, and wait.
-6. When the plan's pull request is merged, create the branch `fix/<short-description>` as `playbooks/open-pr.md` says. In its first commit, set the plan's `Accepted by:` line, under its title, to the account that merged that pull request, read from the host. When you cannot read the host, write the handle the engineer gives. Never write a handle the host or the engineer did not give.
-7. Reproduce the defect as a test. Run it and check that it fails for the reason the cause gives. Commit the failing test before any fix.
-8. Make the test pass without editing it.
-9. Run every check the project's agent instructions name. Keep the output. When one fails, fix the code, and never skip, delete, or weaken a test. When a check cannot run in this session, say which one and why, and never report it as passed.
-10. Go on in the same turn, without asking. Follow `playbooks/open-pr.md`, and then `playbooks/review.md`.
+5. Commit `intent/<short-description>/plan.md` on a new branch, with the `Accepted by:` line as the template has it, push it, and open a pull request that changes no file outside `intent/`, as the opening paragraph of `playbooks/open-pr.md` says for branches and pull requests. In plan mode, the engineer's approval lets you write the file and do this step; it is not the acceptance.
+6. **Gate: the engineer accepts the plan.** The engineer merges that pull request to accept the plan, or closes it to reject it. You never merge it, and you change no file outside `intent/` before it is merged. Revise the plan as the engineer asks; each revision is a commit on that branch. Report the pull request's URL, or the pushed branch's name when you could not open one, keep it green as `playbooks/review.md` says, and wait.
+7. When the plan's pull request is merged, create the branch `fix/<short-description>` as `playbooks/open-pr.md` says. In its first commit, set the plan's `Accepted by:` line, under its title, to the account that merged that pull request, read from the host. When you cannot read the host, confirm with `git fetch` that the plan is on the default branch, and write the handle the engineer gives; ask for it when they gave none. Never write a handle the host or the engineer did not give.
+8. Reproduce the defect as a test. Run it and check that it fails for the reason the cause gives. Commit the failing test before any fix.
+9. Make the test pass without editing it.
+10. Run every check the project's agent instructions name. Keep the output. When one fails, fix the code, and never skip, delete, or weaken a test. When a check cannot run in this session, say which one and why, and never report it as passed.
+11. Go on in the same turn, without asking. Follow `playbooks/open-pr.md`, and then `playbooks/review.md`.
 
-**Next:** `playbooks/open-pr.md`; an agent; in the same turn, as soon as step 9 passes.
+**Next:** `playbooks/open-pr.md`; an agent; in the same turn, as soon as step 10 passes.

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

@@ -94,8 +94,8 @@ const alsoAcceptedByPrefix = "Also accepted by: ";
 const hostTokenVariable = "GH_TOKEN";
 const hostRepositoryPath = "repos/{owner}/{repo}";
 const authorPrefix = "Author: ";
-const authorPattern = /^Author: @[\dA-Za-z][\dA-Za-z-]*[ .]/;
-const alsoAcceptedByPattern = /^Also accepted by: @([\dA-Za-z][\dA-Za-z-]*)\.$/;
+const authorPattern = /^Author: @[\dA-Za-z][\w-]*[ .]/;
+const alsoAcceptedByPattern = /^Also accepted by: @([\dA-Za-z][\w-]*)\.$/;
 
 type BranchChanges = {
   changedPaths: string[];
@@ -195,28 +195,25 @@ function findAuthorProblems(intentText: string): string[] {
  * Ask the host who merged the pull request that last changed a plan on the default branch, and who approved it.
  * @param mergeBase The commit this branch left the default branch at.
  * @param planPath Path of the plan.
- * @returns The merging account and the approving accounts, or undefined when the host cannot be read.
+ * @returns The merging account and the approving accounts, or undefined when no host token is set.
+ * @throws {Error} When a token is set and git or the host's tool fails.
  */
 function readPlanMerge(mergeBase: string, planPath: string): PlanMerge | undefined {
   if (process.env[hostTokenVariable] === undefined || process.env[hostTokenVariable] === "") {
     return undefined;
   }
 
-  try {
-    const commit = runGit(["log", "-1", "--format=%H", mergeBase, "--", planPath]);
-    const pullRequest = runHost(`${hostRepositoryPath}/commits/${commit}/pulls`, ".[0].number");
-    const pullRequestPath = `${hostRepositoryPath}/pulls/${pullRequest}`;
-    const mergedBy = runHost(pullRequestPath, ".merged_by.login");
-    const approvedFilter = '.[] | select(.state == "APPROVED") | .user.login';
-    const approvers = runHost(`${pullRequestPath}/reviews`, approvedFilter);
+  const commit = runGit(["log", "-1", "--format=%H", mergeBase, "--", planPath]);
+  const pullRequest = runHost(`${hostRepositoryPath}/commits/${commit}/pulls`, ".[0].number");
+  const pullRequestPath = `${hostRepositoryPath}/pulls/${pullRequest}`;
+  const mergedBy = runHost(pullRequestPath, ".merged_by.login");
+  const approvedFilter = '.[] | select(.state == "APPROVED") | .user.login';
+  const approvers = runHost(`${pullRequestPath}/reviews`, approvedFilter);
 
-    return {
-      mergedBy,
-      approvers: approvers.split("\n").filter(approver => approver !== ""),
-    };
-  } catch {
-    return undefined;
-  }
+  return {
+    mergedBy,
+    approvers: approvers.split("\n").filter(approver => approver !== ""),
+  };
 }
 
 /**
@@ -249,7 +246,7 @@ const intentFileName = "intent.md";
 const proofHeading = "## Proof";
 const requirementsHeading = "## Requirements";
 const acceptancePlaceholder = "@<engineer>";
-const acceptedByPattern = /^Accepted by: @[\dA-Za-z][\dA-Za-z-]*\.$/;
+const acceptedByPattern = /^Accepted by: @[\dA-Za-z][\w-]*\.$/;
 const requiredHeadings = ["## Files that change", "## Order of work", "## Risks", proofHeading];
 
 /**

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

@@ -62,6 +62,9 @@ jobs:
     if: needs.changes.outputs.full_verification == 'true'
     runs-on: ubuntu-latest
     timeout-minutes: 20
+    permissions:
+      contents: read
+      pull-requests: read # Needed by plan:check to read who merged the plan's pull request.
     steps:
       - name: Checkout repository
         uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7
@@ -78,6 +81,8 @@ jobs:
       - name: Check agent gates
         run: pnpm gates:check
       - name: Check plans
+        env:
+          GH_TOKEN: ${{ github.token }} # plan:check reads who merged the plan's pull request.
         run: pnpm plan:check
       - name: Check bands
         run: pnpm bands:check

package/templates/nestjs/AGENTS.md

@@ -34,7 +34,7 @@ The `verifier` subagent starts the app with `pnpm start:dev`. It exercises the c
 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 `playbooks/build.md` of the `sdlc-mode` skill in `plugins/sdlc/claude-code/` describes.
+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`. The plan, `intent/<change>/plan.md`, gets a pull request of its own, and the engineer accepts it by merging that pull request, as `playbooks/build.md` of the `sdlc-mode` skill in `plugins/sdlc/claude-code/` describes.
 5. **Start a bug fix with a failing test.** A bug fix has no intent and no spec; its plan, `intent/<short-description>/plan.md`, is accepted by an engineer before any code changes. Reproduce the bug as a test, confirm it fails for the reason you expect, and commit it on a `fix/` branch. Then `.agents/hooks/agent-test-edit-gate.sh` blocks test edits by itself: make the test pass without editing it. On a branch with another name, create `.git/bug-fix-in-progress` first, and delete it once the test passes.
 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:sdlc-mode` 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.

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

@@ -62,6 +62,9 @@ jobs:
     if: needs.changes.outputs.full_verification == 'true'
     runs-on: ubuntu-latest
     timeout-minutes: 20
+    permissions:
+      contents: read
+      pull-requests: read # Needed by plan:check to read who merged the plan's pull request.
     steps:
       - name: Checkout repository
         uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7
@@ -78,6 +81,8 @@ jobs:
       - name: Check agent gates
         run: pnpm gates:check
       - name: Check plans
+        env:
+          GH_TOKEN: ${{ github.token }} # plan:check reads who merged the plan's pull request.
         run: pnpm plan:check
       - name: Check bands
         run: pnpm bands:check

package/templates/nextjs/AGENTS.md

@@ -34,7 +34,7 @@ The `verifier` subagent starts the app with `pnpm dev`. It exercises the changed
 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 `playbooks/build.md` of the `sdlc-mode` skill in `plugins/sdlc/claude-code/` describes.
+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`. The plan, `intent/<change>/plan.md`, gets a pull request of its own, and the engineer accepts it by merging that pull request, as `playbooks/build.md` of the `sdlc-mode` skill in `plugins/sdlc/claude-code/` describes.
 5. **Start a bug fix with a failing test.** A bug fix has no intent and no spec; its plan, `intent/<short-description>/plan.md`, is accepted by an engineer before any code changes. Reproduce the bug as a test, confirm it fails for the reason you expect, and commit it on a `fix/` branch. Then `.agents/hooks/agent-test-edit-gate.sh` blocks test edits by itself: make the test pass without editing it. On a branch with another name, create `.git/bug-fix-in-progress` first, and delete it once the test passes.
 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:sdlc-mode` 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.

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

@@ -62,6 +62,9 @@ jobs:
     if: needs.changes.outputs.full_verification == 'true'
     runs-on: ubuntu-latest
     timeout-minutes: 20
+    permissions:
+      contents: read
+      pull-requests: read # Needed by plan:check to read who merged the plan's pull request.
     steps:
       - name: Checkout repository
         uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7
@@ -78,6 +81,8 @@ jobs:
       - name: Check agent gates
         run: pnpm gates:check
       - name: Check plans
+        env:
+          GH_TOKEN: ${{ github.token }} # plan:check reads who merged the plan's pull request.
         run: pnpm plan:check
       - name: Check bands
         run: pnpm bands:check

package/templates/nodejs/AGENTS.md

@@ -33,7 +33,7 @@ The `verifier` subagent starts the app with `pnpm start:dev`. It exercises the c
 
 1. **Put tests next to the code as `src/**/*.test.ts`.** Vitest collects only that pattern.
 2. **Read configuration from environment variables and fail when one is missing**, as `parsePort` does. Document each variable in `.env.example`; `pnpm start` and `pnpm start:dev` load `.env`.
-3. **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 `playbooks/build.md` of the `sdlc-mode` skill in `plugins/sdlc/claude-code/` describes.
+3. **Start from the accepted spec, in plan mode** (Cursor: Plan Mode). Give the plan the change's `intent/<change>/intent.md` and `spec.md`. The plan, `intent/<change>/plan.md`, gets a pull request of its own, and the engineer accepts it by merging that pull request, as `playbooks/build.md` of the `sdlc-mode` skill in `plugins/sdlc/claude-code/` describes.
 4. **Start a bug fix with a failing test.** A bug fix has no intent and no spec; its plan, `intent/<short-description>/plan.md`, is accepted by an engineer before any code changes. Reproduce the bug as a test, confirm it fails for the reason you expect, and commit it on a `fix/` branch. Then `.agents/hooks/agent-test-edit-gate.sh` blocks test edits by itself: make the test pass without editing it. On a branch with another name, create `.git/bug-fix-in-progress` first, and delete it once the test passes.
 5. **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:sdlc-mode` followed by their own words.
 6. **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.

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

@@ -79,6 +79,9 @@ jobs:
       DATABASE_URL: postgres://postgres:postgres@localhost:5432/payload
       PAYLOAD_SECRET: ci-only-secret
       APP_URL: http://localhost:3000
+    permissions:
+      contents: read
+      pull-requests: read # Needed by plan:check to read who merged the plan's pull request.
     steps:
       - name: Checkout repository
         uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7
@@ -95,6 +98,8 @@ jobs:
       - name: Check agent gates
         run: pnpm gates:check
       - name: Check plans
+        env:
+          GH_TOKEN: ${{ github.token }} # plan:check reads who merged the plan's pull request.
         run: pnpm plan:check
       - name: Check bands
         run: pnpm bands:check

package/templates/payload/AGENTS.md

@@ -37,7 +37,7 @@ The `verifier` subagent starts the app with `pnpm dev`, which needs a PostgreSQL
 2. **Put unit tests next to the code as `src/**/*.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 through `requireEnvironment` in `src/environment.ts`.** Document each variable in `.env.example`.
-5. **Start from the accepted spec, in plan mode** (Cursor: Plan Mode). Give the plan the change's `intent/<change>/intent.md` and `spec.md`. Commit the approved plan as `intent/<change>/plan.md` with an `Accepted by:` line naming the engineer, as `playbooks/build.md` of the `sdlc-mode` skill in `plugins/sdlc/claude-code/` describes.
+5. **Start from the accepted spec, in plan mode** (Cursor: Plan Mode). Give the plan the change's `intent/<change>/intent.md` and `spec.md`. The plan, `intent/<change>/plan.md`, gets a pull request of its own, and the engineer accepts it by merging that pull request, as `playbooks/build.md` of the `sdlc-mode` skill in `plugins/sdlc/claude-code/` describes.
 6. **Start a bug fix with a failing test.** A bug fix has no intent and no spec; its plan, `intent/<short-description>/plan.md`, is accepted by an engineer before any code changes. Reproduce the bug as a test, confirm it fails for the reason you expect, and commit it on a `fix/` branch. Then `.agents/hooks/agent-test-edit-gate.sh` blocks test edits by itself: make the test pass without editing it. On a branch with another name, create `.git/bug-fix-in-progress` first, and delete it once the test passes.
 7. **Do not start work a person did not ask for.** When a message reports a problem without asking for work, answer in a few lines and end with the message that would start it: `/sdlc:sdlc-mode` followed by their own words.
 8. **Branch from the latest `origin/main`, and open the pull request ready for review.** Name the branch `<type>/<short-description>` and fill the body from `.github/pull_request_template.md`. `.github/workflows/ci.yml` runs full verification only on a pull request that is not a draft. Never merge a pull request: a person merges it with `--squash` after code owner approval, bottom-up for a stack of pull requests.

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

@@ -104,6 +104,7 @@ jobs:
     permissions:
       contents: read
       id-token: write # Needed to exchange GitHub OIDC for a Turborepo Remote Cache token.
+      pull-requests: read # Needed by plan:check to read who merged the plan's pull request.
     services:
       postgres:
         image: postgres:17.11-alpine@sha256:266d3c257594e195b309ae9d1805e54c788f1d7b375f56bf6c367aac6c917e7b
@@ -156,6 +157,8 @@ jobs:
       - name: Check agent gates
         run: pnpm gates:check
       - name: Check plans
+        env:
+          GH_TOKEN: ${{ github.token }} # plan:check reads who merged the plan's pull request.
         run: pnpm plan:check
       - name: Check bands
         run: pnpm bands:check

package/templates/turborepo/AGENTS.md

@@ -39,7 +39,7 @@ The `verifier` subagent starts the app with `pnpm dev`, which needs a PostgreSQL
 2. **Put unit tests next to the code and Playwright end-to-end tests in `apps/app/test/` and `apps/backoffice/test/` as `*.e2e.test.ts`.** Vitest collects `apps/app/app/**/*.test.{ts,tsx}` and `apps/backoffice/src/**/*.test.{ts,tsx}`.
 3. **Component tests need a DOM test environment, and Vitest runs in Node.js.** Add that environment with the first component test.
 4. **Read backoffice configuration through `requireEnvironment` in `apps/backoffice/src/environment.ts`.** Document each variable in `.env.example`.
-5. **Start from the accepted spec, in plan mode** (Cursor: Plan Mode). Give the plan the change's `intent/<change>/intent.md` and `spec.md`. Commit the approved plan as `intent/<change>/plan.md` with an `Accepted by:` line naming the engineer, as `playbooks/build.md` of the `sdlc-mode` skill in `plugins/sdlc/claude-code/` describes.
+5. **Start from the accepted spec, in plan mode** (Cursor: Plan Mode). Give the plan the change's `intent/<change>/intent.md` and `spec.md`. The plan, `intent/<change>/plan.md`, gets a pull request of its own, and the engineer accepts it by merging that pull request, as `playbooks/build.md` of the `sdlc-mode` skill in `plugins/sdlc/claude-code/` describes.
 6. **Start a bug fix with a failing test.** A bug fix has no intent and no spec; its plan, `intent/<short-description>/plan.md`, is accepted by an engineer before any code changes. Reproduce the bug as a test, confirm it fails for the reason you expect, and commit it on a `fix/` branch. Then `.agents/hooks/agent-test-edit-gate.sh` blocks test edits by itself: make the test pass without editing it. On a branch with another name, create `.git/bug-fix-in-progress` first, and delete it once the test passes.
 7. **Do not start work a person did not ask for.** When a message reports a problem without asking for work, answer in a few lines and end with the message that would start it: `/sdlc:sdlc-mode` followed by their own words.
 8. **Branch from the latest `origin/main`, and open the pull request ready for review.** Name the branch `<type>/<short-description>` and fill the body from `.github/pull_request_template.md`. `.github/workflows/ci.yml` runs full verification only on a pull request that is not a draft. Never merge a pull request: a person merges it with `--squash` after code owner approval, bottom-up for a stack of pull requests.