@next-friday/create-app 9.1.1 → 9.2.1

package/templates/base/.github/workflows/control-band.yml

@@ -0,0 +1,115 @@
+name: Control band
+
+on:
+  schedule:
+    - cron: "0 6 * * *"
+
+permissions: {}
+
+concurrency:
+  group: ${{ github.workflow }}
+  cancel-in-progress: false
+
+jobs:
+  detect:
+    name: Detect the tier
+    if: vars.CLAUDE_CI_ENABLED == 'true'
+    runs-on: ubuntu-latest
+    timeout-minutes: 15
+    permissions:
+      actions: read # Needed by a metric command that reads workflow runs.
+      contents: read
+    outputs:
+      action: ${{ steps.tier.outputs.action }}
+      report: ${{ steps.tier.outputs.report }}
+      routes: ${{ steps.tier.outputs.routes }}
+      tools: ${{ steps.tier.outputs.tools }}
+      values: ${{ steps.tier.outputs.values }}
+    steps:
+      - name: Checkout repository
+        uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7
+        with:
+          persist-credentials: false
+      - name: Set up Node.js and pnpm
+        uses: pnpm/setup@fbda4c85fc2e1e08721cd8763afea8f48d60f024 # v3.0.0
+        with:
+          cache: true
+          require-lockfile: true
+      - name: Measure the metric
+        env:
+          GH_TOKEN: ${{ github.token }}
+          METRIC_COMMAND: ${{ vars.CONTROL_BAND_METRIC_COMMAND }}
+        run: |
+          [[ -n "$METRIC_COMMAND" ]] || { echo "::error::Set the CONTROL_BAND_METRIC_COMMAND repository variable to a command that writes metric-values.json"; exit 1; }
+          bash -euo pipefail -c "$METRIC_COMMAND"
+          [[ -f metric-values.json ]] || { echo "::error::CONTROL_BAND_METRIC_COMMAND did not write metric-values.json"; exit 1; }
+      - name: Detect the tier
+        id: tier
+        run: |
+          report="$(pnpm --silent bands:check metric-values.json)"
+          {
+            echo "report=$report"
+            echo "action=$(jq --raw-output '.action // "none"' <<< "$report")"
+            echo "routes=$(jq --compact-output '.routes // []' <<< "$report")"
+            echo "tools=$(jq --raw-output '.tools // ""' <<< "$report")"
+            echo "values=$(jq --compact-output . metric-values.json)"
+          } >> "$GITHUB_OUTPUT"
+
+  respond:
+    name: Respond to the finding
+    needs: detect
+    if: vars.CLAUDE_CI_ENABLED == 'true' && (needs.detect.outputs.action == 'diagnose' || needs.detect.outputs.action == 'propose')
+    runs-on: ubuntu-latest
+    timeout-minutes: 20
+    permissions:
+      actions: read # Needed by the tier's tools that read workflow runs.
+      contents: write # Needed to push the intent branch; the agent has no route to push main.
+      id-token: write # Needed to authenticate the Claude GitHub App with the workflow's OIDC token.
+      pull-requests: write # Needed to open the intent pull request.
+    steps:
+      - name: Require a Claude credential
+        env:
+          ANTHROPIC_API_KEY: ${{ secrets.ANTHROPIC_API_KEY }}
+          CLAUDE_CODE_OAUTH_TOKEN: ${{ secrets.CLAUDE_CODE_OAUTH_TOKEN }}
+        run: |
+          [[ -n "$ANTHROPIC_API_KEY" || -n "$CLAUDE_CODE_OAUTH_TOKEN" ]] || { echo "::error::Set the CLAUDE_CODE_OAUTH_TOKEN or ANTHROPIC_API_KEY repository secret"; exit 1; }
+      - name: Checkout repository
+        uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7
+        with:
+          fetch-depth: 0
+          persist-credentials: false
+      - name: Create the intent branch
+        if: contains(fromJSON(needs.detect.outputs.routes), 'pull_request')
+        run: git switch --create "docs/band-finding-$GITHUB_RUN_ID"
+      - name: Diagnose
+        if: ${{ !contains(fromJSON(needs.detect.outputs.routes), 'pull_request') }}
+        uses: anthropics/claude-code-action@61a9c274fa7110a66dfafc1bbbced03833eb25fe # v1.0.269
+        with:
+          anthropic_api_key: ${{ secrets.ANTHROPIC_API_KEY }}
+          claude_code_oauth_token: ${{ secrets.CLAUDE_CODE_OAUTH_TOKEN }}
+          prompt: |
+            /sdlc A scheduled job found a control band deviation in production. No one can answer questions.
+            Detection report: ${{ needs.detect.outputs.report }}
+            Metric values, oldest first: ${{ needs.detect.outputs.values }}
+            The values come from the command in the CONTROL_BAND_METRIC_COMMAND repository variable. Run: ${{ github.server_url }}/${{ github.repository }}/actions/runs/${{ github.run_id }}
+          claude_args: |
+            --model claude-haiku-5-5
+            --max-turns 15
+            --allowedTools "${{ needs.detect.outputs.tools || 'Read,Grep,Glob' }}"
+      - name: Write the intent
+        if: contains(fromJSON(needs.detect.outputs.routes), 'pull_request')
+        uses: anthropics/claude-code-action@61a9c274fa7110a66dfafc1bbbced03833eb25fe # v1.0.269
+        with:
+          anthropic_api_key: ${{ secrets.ANTHROPIC_API_KEY }}
+          claude_code_oauth_token: ${{ secrets.CLAUDE_CODE_OAUTH_TOKEN }}
+          prompt: |
+            /sdlc A scheduled job found a control band deviation in production. No one can answer questions.
+            Detection report: ${{ needs.detect.outputs.report }}
+            Metric values, oldest first: ${{ needs.detect.outputs.values }}
+            The values come from the command in the CONTROL_BAND_METRIC_COMMAND repository variable. Run: ${{ github.server_url }}/${{ github.repository }}/actions/runs/${{ github.run_id }}
+            The branch docs/band-finding-${{ github.run_id }} exists and is checked out. Commit intent.md on it, push it with git push --set-upstream origin docs/band-finding-${{ github.run_id }}, open the pull request, and stop at the service owner's gate. A route other than pull_request is a runbook: name its command in the intent and do not run it.
+          claude_args: |
+            --model claude-haiku-5-5
+            --max-turns 25
+            --permission-mode acceptEdits
+            --allowedTools "${{ needs.detect.outputs.tools || 'Read,Grep,Glob' }},Write,Edit,Bash(git add *),Bash(git commit *),Bash(git status *),Bash(git log *),Bash(git push --set-upstream origin docs/band-finding-${{ github.run_id }}),Bash(gh pr create *)"

package/templates/base/.github/workflows/dependency-review.yml

@@ -12,6 +12,7 @@ concurrency:
 jobs:
   dependency-review:
     name: Dependency Review
+    if: github.event.repository.visibility == 'public' || vars.CODE_SCANNING == 'true'
     runs-on: ubuntu-latest
     timeout-minutes: 10
     permissions:

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

@@ -51,6 +51,7 @@ jobs:
           persist-credentials: false
       - name: Require the commit on main with passing CI and a deployment to the previous environment
         if: github.event_name == 'workflow_dispatch'
+        shell: bash
         env:
           GH_TOKEN: ${{ github.token }}
           REPOSITORY: ${{ github.repository }}
@@ -116,11 +117,12 @@ jobs:
         run: railway up --ci --service "$RAILWAY_SERVICE" --environment "$RAILWAY_ENVIRONMENT"
       - name: Require a healthy deployment
         run: |
+          health_url="${APP_URL%/}/health"
           for _ in $(seq 30); do
-            if curl --silent --fail --output /dev/null "$APP_URL/health"; then
+            if curl --silent --fail --output /dev/null "$health_url"; then
               exit 0
             fi
             sleep 10
           done
-          echo "::error::$APP_URL/health did not respond"
+          echo "::error::$health_url did not respond"
           exit 1

package/templates/base/.github/workflows/osv-scanner.yml

@@ -5,11 +5,6 @@ on:
   push:
     branches:
       - main
-    paths-ignore:
-      - "**/*.md"
-      - ".agents/**"
-      - ".claude/**"
-      - ".cursor/**"
   schedule:
     - cron: "37 2 * * 1"
 

package/templates/base/.github/workflows/pr-triage.yml

@@ -1,4 +1,4 @@
-name: PR Labeler
+name: PR Triage
 
 on:
   pull_request_target:

package/templates/base/.github/workflows/secret-scan.yml

@@ -43,8 +43,11 @@ jobs:
           tar --extract --gzip --file "$archive" gitleaks
       - name: Scan history with repository rules
         run: |
+          config=.gitleaks.toml
           log_opts=()
           if [[ -n "$PR_BASE_SHA" ]]; then
+            config="$RUNNER_TEMP/gitleaks.toml"
+            git show "${PR_BASE_SHA}:.gitleaks.toml" > "$config"
             log_opts=(--log-opts="${PR_BASE_SHA}..${PR_HEAD_SHA}")
           fi
-          ./gitleaks git --redact --config .gitleaks.toml --no-banner "${log_opts[@]}" .
+          ./gitleaks git --redact --config "$config" --no-banner "${log_opts[@]}" .

package/templates/base/.github/workflows/spec-on-intent-merge.yml

@@ -0,0 +1,108 @@
+name: Spec on intent merge
+
+on:
+  push:
+    branches:
+      - main
+    paths:
+      - intent/*/intent.md
+
+permissions: {}
+
+concurrency:
+  group: ${{ github.workflow }}
+  cancel-in-progress: false
+
+jobs:
+  find:
+    name: Find merged intents
+    if: vars.CLAUDE_CI_ENABLED == 'true'
+    runs-on: ubuntu-latest
+    timeout-minutes: 5
+    permissions:
+      contents: read
+    outputs:
+      intents: ${{ steps.find.outputs.intents }}
+    steps:
+      - name: Checkout repository
+        uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7
+        with:
+          fetch-depth: 0
+          persist-credentials: false
+      - name: List merged intents without a spec
+        id: find
+        env:
+          BEFORE: ${{ github.event.before }}
+          AFTER: ${{ github.sha }}
+        run: |
+          if [[ "$BEFORE" =~ ^0+$ ]]; then
+            changed="$(git ls-tree -r --name-only "$AFTER")"
+          else
+            changed="$(git diff --name-only --diff-filter=AM "$BEFORE" "$AFTER")"
+          fi
+          : > intents.txt
+          while IFS= read -r path; do
+            [[ "$path" =~ ^intent/[A-Za-z0-9._-]+/intent\.md$ ]] || continue
+            grep --extended-regexp --quiet 'Status: (draft|accepted)\.$' "$path" || continue
+            [[ ! -e "$(dirname "$path")/spec.md" ]] || continue
+            echo "$path" >> intents.txt
+          done <<< "$changed"
+          echo "intents=$(jq --raw-input --null-input --compact-output '[inputs]' < intents.txt)" >> "$GITHUB_OUTPUT"
+
+  spec:
+    name: Write the spec for ${{ matrix.intent }}
+    needs: find
+    if: vars.CLAUDE_CI_ENABLED == 'true' && needs.find.outputs.intents != '[]'
+    runs-on: ubuntu-latest
+    timeout-minutes: 20
+    permissions:
+      contents: write # Needed to push the spec branch; the agent has no route to push main.
+      id-token: write # Needed to authenticate the Claude GitHub App with the workflow's OIDC token.
+      pull-requests: write # Needed to open the pull request.
+    strategy:
+      fail-fast: false
+      max-parallel: 1
+      matrix:
+        intent: ${{ fromJSON(needs.find.outputs.intents) }}
+    env:
+      INTENT: ${{ matrix.intent }}
+    steps:
+      - name: Require a Claude credential
+        env:
+          ANTHROPIC_API_KEY: ${{ secrets.ANTHROPIC_API_KEY }}
+          CLAUDE_CODE_OAUTH_TOKEN: ${{ secrets.CLAUDE_CODE_OAUTH_TOKEN }}
+        run: |
+          [[ -n "$ANTHROPIC_API_KEY" || -n "$CLAUDE_CODE_OAUTH_TOKEN" ]] || { echo "::error::Set the CLAUDE_CODE_OAUTH_TOKEN or ANTHROPIC_API_KEY repository secret"; exit 1; }
+      - name: Checkout repository
+        uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7
+        with:
+          fetch-depth: 0
+          persist-credentials: false
+      - name: Create the spec branch
+        id: branch
+        run: |
+          change="${INTENT#intent/}"
+          change="${change%/intent.md}"
+          git switch --create "docs/spec-$change"
+          echo "name=docs/spec-$change" >> "$GITHUB_OUTPUT"
+      - name: Write the spec
+        uses: anthropics/claude-code-action@61a9c274fa7110a66dfafc1bbbced03833eb25fe # v1.0.269
+        with:
+          anthropic_api_key: ${{ secrets.ANTHROPIC_API_KEY }}
+          claude_code_oauth_token: ${{ secrets.CLAUDE_CODE_OAUTH_TOKEN }}
+          prompt: |
+            /sdlc ${{ matrix.intent }}
+            The branch ${{ steps.branch.outputs.name }} exists and is checked out. Commit spec.md on it, push it with git push --set-upstream origin ${{ steps.branch.outputs.name }}, open the pull request, and stop at the product owner's gate.
+          claude_args: |
+            --model claude-haiku-5-5
+            --max-turns 30
+            --permission-mode acceptEdits
+            --allowedTools "Read,Write,Edit,Glob,Grep,Bash(git add *),Bash(git commit *),Bash(git status *),Bash(git log *),Bash(git push --set-upstream origin ${{ steps.branch.outputs.name }}),Bash(gh pr create *)"
+      - name: Require the pull request
+        env:
+          BRANCH: ${{ steps.branch.outputs.name }}
+          GH_TOKEN: ${{ github.token }}
+          REPOSITORY: ${{ github.repository }}
+        run: |
+          count="$(gh pr list --repo "$REPOSITORY" --head "$BRANCH" --state open --json number --jq length)"
+          [[ "$count" -gt 0 ]] || { echo "::error::No pull request was opened from $BRANCH"; exit 1; }

package/templates/base/.github/workflows/validate-pr-title.yml

@@ -8,8 +8,7 @@ on:
       - reopened
       - synchronize
 
-permissions:
-  pull-requests: read # Needed to read the pull request title for semantic validation.
+permissions: {}
 
 concurrency:
   group: ${{ github.workflow }}-${{ github.event.pull_request.number || github.run_id }}
@@ -21,6 +20,8 @@ jobs:
     if: github.event.pull_request.user.login != 'dependabot[bot]'
     runs-on: ubuntu-latest
     timeout-minutes: 10
+    permissions:
+      pull-requests: read # Needed to read the pull request title for semantic validation.
     steps:
       - name: Validate pull request title
         uses: amannn/action-semantic-pull-request@48f256284bd46cdaab1048c3721360e808335d50 # v6.1.1

package/templates/base/.husky/pre-push

@@ -2,18 +2,11 @@
 set -e
 
 # The first push of a new repository creates main on the remote, so it is the only push allowed there.
-while read -r local_ref _ remote_ref remote_oid; do
+while read -r _ _ remote_ref remote_oid; do
   if [ "$remote_ref" = refs/heads/main ] && [ -n "$(printf '%s' "$remote_oid" | tr -d 0)" ]; then
     echo "pre-push: do not push to main. Push your branch and open a pull request." >&2
     exit 1
   fi
-  branch="${remote_ref#refs/heads/}"
-  if [ "$branch" != "$remote_ref" ] && [ -z "$(printf '%s' "$remote_oid" | tr -d 0)" ] \
-    && { git rev-parse --verify --quiet "refs/remotes/$1/$branch" > /dev/null \
-      || [ "$(git config "branch.${local_ref#refs/heads/}.merge" || true)" = "$remote_ref" ]; }; then
-    echo "pre-push: $branch no longer exists on $1. Push the work to a new branch from the latest $1/main and open a pull request. To reuse the name, run git fetch --prune and git branch --unset-upstream first." >&2
-    exit 1
-  fi
 done
 
 pnpm check || {

package/templates/base/REVIEW.md

@@ -6,7 +6,7 @@ Run three passes and tag each finding with its pass:
 
 - Bugs: logic errors, broken edge cases, subtle regressions
 - Security: injection risks, authentication gaps, PII in logs
-- Compliance: the change matches spec.md, plan.md and our design principles; flag a plan.md that has no `Accepted by:` line
+- Compliance: the change matches spec.md, plan.md and the design principles that the four policies in `.agents/skills/` state; flag a plan.md that has no `Accepted by:` line and a change that makes `AGENTS.md` outdated
 
 ## What Important means here
 
@@ -18,4 +18,4 @@ Report at most five nits per review; summarize the rest as a count.
 
 ## Do not report
 
-Generated files under src/gen/ and anything CI already enforces.
+Generated files, such as `pnpm-lock.yaml`, and anything CI already enforces.

package/templates/base/SETUP.md

@@ -4,7 +4,7 @@ This project runs an AI-native software development loop in Claude Code and Curs
 
 ## How a change flows
 
-Send a request with `/sdlc`. `intent/README.md` and the playbooks in `.agents/skills/sdlc/playbooks/` say who acts and who decides at each stage.
+Send a request with `/sdlc`. Only a person starts it; nothing routes work into it by itself. `.agents/skills/sdlc-help/SKILL.md` says how to keep `/sdlc` on for a session in Claude Code and Cursor. `intent/README.md` and the playbooks in `.agents/skills/sdlc/playbooks/` say who acts and who decides at each stage.
 
 ## 1. First commit and push
 
@@ -12,7 +12,7 @@ Send a request with `/sdlc`. `intent/README.md` and the playbooks in `.agents/sk
 
 1. Install gitleaks and jq (see [CONTRIBUTING.md](CONTRIBUTING.md)).
 2. Replace the template's description and owner: `package.json#description`, `repository.url`, and `author`, and any template text that `README.md` → **After creating a project from this template** lists. Change `license` from `UNLICENSED` if the project is open source.
-3. Create an empty repository on GitHub. Make the first commit on `main` and push it there. The Git hooks allow only this first commit and push on `main`; work on branches after that.
+3. Create an empty repository on GitHub. If the project is not a Git repository yet, run `git init --initial-branch=main`. Make the first commit on `main` and push it there. The Git hooks allow only this first commit and push on `main`; work on branches after that.
 
    ```sh
    git add --all
@@ -39,7 +39,7 @@ In `.github/CODEOWNERS`, add these lines in this order. GitHub uses the last mat
 /.agents/skills/ux-policy/ @the-ux-policy-owner
 ```
 
-Also replace the owner placeholder in `.github/zizmor.yml`.
+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`.
 
 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.
 
@@ -60,6 +60,7 @@ 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.
 - 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.
@@ -68,7 +69,7 @@ Replace `security@example.com` in `SECURITY.md` with the contact the security po
 
 **Who:** an Owner of the Claude organization, with an owner of the GitHub organization.
 
-- **Code Review:** in [**Admin settings → Claude Code**](https://claude.ai/admin-settings/claude-code#code-review), turn on **Allow code review**, install the Claude GitHub App, and add this repository ([set up Code Review](https://code.claude.com/docs/en/code-review-setup)). It needs a Team or Enterprise plan ([availability](https://code.claude.com/docs/en/code-review#availability)). Keep **Review runs** at **After every push**, the default, so every push to a pull request gets a review. Reviews run on Anthropic's infrastructure, so the repository has no review workflow.
+- **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.
 - **Monitoring:** turn on the [OpenTelemetry export](https://code.claude.com/docs/en/monitoring-usage).
 
@@ -90,12 +91,47 @@ 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):** each `.agents/skills/<area>-policy/SKILL.md` ships a default (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, replace or add the organization's own rules, then run `pnpm rules:sync`. Test that the skill triggers: ask for the relevant task in different ways and confirm the skill loads each time. The policy owner approves every later change as its code owner.
-- **Production gate (engineering leadership, with change management and compliance):** 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`.
-- **Review (tech lead):** replace `src/gen/` in `.agents/review.md` with this project's generated paths, then run `pnpm rules:sync`, which renders it to `REVIEW.md` for Claude Code Review. Once a month, rate the review findings and tune `.agents/review.md`.
+- **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.
+- **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.
 
 ## 7. Later, as the guardrails mature
 
-- Send the intent's path with `/sdlc` by hand first. Then build a job that runs it when an `intent.md` merges; this project ships no such job. The job runs this in the repository: `claude -p "/sdlc intent/<change>/intent.md" --permission-mode acceptEdits --allowedTools "Bash(git switch:*)" "Bash(git add:*)" "Bash(git commit:*)" "Bash(git status:*)" "Bash(git log:*)" "Read" "Write" "Edit" "Glob" "Grep"`. Without `--permission-mode acceptEdits` the session stays in plan mode and writes nothing. The job then pushes the branch and opens the pull request with its own token; the product owner's first step is the review.
+- Send the intent's path with `/sdlc` by hand first. Then turn on `Spec on intent merge` (step 8).
 - Make auto mode the default for routine work: a tight `spec.md`, a small blast radius, and code the tests already cover.
-- Replace `bands.yaml` with this project's metric, add a unit-tested detection script that reads it, and add the trigger that runs it.
+- Set the metric in `bands.yaml`, then turn on `Control band` (step 8).
+
+## 8. Claude in CI
+
+**Who:** a repository admin.
+
+Each workflow below stays off until the repository variable `CLAUDE_CI_ENABLED` is `true`; until then nothing runs, on a schedule or otherwise, and nothing calls a model. When it is on, each needs one secret: `CLAUDE_CODE_OAUTH_TOKEN`, a Claude subscription token from `claude setup-token`, or `ANTHROPIC_API_KEY`, an API key. Either works; with neither set the job fails and says so. The jobs run the small model with a turn cap. Jobs that write install the Claude GitHub App from step 4 on the repository, and every change they make arrives as a pull request.
+
+- **`Agent evals`:** runs `pnpm evals:run` when a pull request changes `AGENTS.md`, `CLAUDE.md`, `.agents`, `.claude`, or `.cursor`, and every night. The job fails below the pass threshold, and it needs `claude` on the `PATH` of the job.
+- **`Spec on intent merge`:** when an `intent.md` reaches `main` with `Status: draft.` or `Status: accepted.` and no `spec.md` beside it, which is how the product owner accepts it, runs `/sdlc intent/<change>/intent.md`, so that `spec.md` arrives as a pull request for the product owner.
+- **`Claude fix loop`:** when a person with write access comments `@claude` on a line of a pull request from this repository, Claude addresses the comment and pushes to that branch. It cannot approve or merge.
+- **`triage` job of `Verify`:** when a pull request from this repository fails a check, reads the failed logs with the `Read` tool only and posts a three-line summary.
+- **`Control band`:** every day, runs the command in the repository variable `CONTROL_BAND_METRIC_COMMAND`, which writes `metric-values.json` as `{"baseline": [...], "recent": [...]}`, then `pnpm bands:check metric-values.json`. A tier whose action is `diagnose` or `propose` runs `/sdlc` with the finding, and the `pull_request` route opens an intent pull request. It never acts on production.
+
+On a machine, `pnpm evals:run` runs the evals with the developer's own Claude login, and `pnpm loop:measure` reports the loop's measures. Neither is part of `pnpm verify`.
+
+**Check:** with `CLAUDE_CI_ENABLED` unset, **Actions** shows these jobs as skipped.
+
+## References
+
+- [Set up Claude Code for your organization](https://code.claude.com/docs/en/admin-setup)
+- [Settings reference and precedence](https://code.claude.com/docs/en/settings)
+- [Server-managed settings](https://code.claude.com/docs/en/server-managed-settings)
+- [Permissions](https://code.claude.com/docs/en/permissions)
+- [Sandboxing](https://code.claude.com/docs/en/sandboxing)
+- [Hooks guide](https://code.claude.com/docs/en/hooks-guide)
+- [Hooks reference](https://code.claude.com/docs/en/hooks)
+- [Skills](https://code.claude.com/docs/en/skills)
+- [Plugins and private marketplaces](https://code.claude.com/docs/en/plugin-marketplaces)
+- [Managed MCP](https://code.claude.com/docs/en/managed-mcp)
+- [Enterprise deployment overview](https://code.claude.com/docs/en/third-party-integrations)
+- [Enterprise network configuration](https://code.claude.com/docs/en/network-config)
+- [Monitoring with OpenTelemetry](https://code.claude.com/docs/en/monitoring-usage)
+- [Analytics dashboard](https://code.claude.com/docs/en/analytics)
+- [Compliance API](https://platform.claude.com/docs/en/manage-claude/compliance-api)
+- [Security model](https://code.claude.com/docs/en/security)

package/templates/base/bands.yaml

@@ -1,9 +1,9 @@
-# Example. Replace it with this project's metric, and add a version-controlled, unit-tested detection script that
-# reads this file. Detection stays deterministic, with no model involved.
+# Detection settings for one metric: the tiers' actions, tools, and routes. `pnpm bands:check <file>` reads this file.
+# The metric is this project's to set. Tiers are sample standard deviations from the baseline's mean.
 metric: ci_test_failure_rate
 baseline: rolling_30d
 rules: western_electric
 tiers:
   1sigma: {action: log}
   2sigma: {action: diagnose, tools: "Read,Grep,Bash(gh run view *)"}
-  3sigma: {action: propose, routes: [pull_request, runbook:rollback-deploy]}
+  3sigma: {action: propose, routes: [pull_request]}

package/templates/base/intent/README.md

@@ -4,6 +4,7 @@ This folder is the intent home. Every change starts here as an `intent.md`, and
 
 - Each change has its own folder, `intent/<change>/`, where `<change>` is a short kebab-case name. The folder holds `intent.md` (Plan), then `spec.md` (Design), then `plan.md` (Build).
 - The playbooks in `.agents/skills/sdlc/playbooks/` say who writes and who accepts each file.
+- A change is `done` when the tree meets every numbered requirement of its `spec.md`. The agent sets `Status: done.` in `intent.md` and `spec.md` in the pull request that meets the last requirement, and the code owner's approval of that pull request accepts it.
 
 ## Which file holds what
 

package/templates/base/knip.json

@@ -1,3 +1,4 @@
 {
-  "$schema": "https://unpkg.com/knip@6/schema.json"
+  "$schema": "https://unpkg.com/knip@6/schema.json",
+  "ignoreDependencies": ["@swc/core"]
 }

package/templates/base/pnpm-workspace.yaml

@@ -1,6 +1,7 @@
 engineStrict: true
 savePrefix: ""
 allowBuilds:
+  "@swc/core": false
   esbuild: true
   unrs-resolver: true
 overrides:
@@ -13,31 +14,9 @@ overrides:
   "minimatch@<11.0.1": ^11.0.1
 minimumReleaseAgeExclude:
   - "@next-friday/commitlint-config-friday@4.0.0"
-  - "@next-friday/eslint-config-friday@5.0.0"
   - "@next-friday/eslint-config-friday@5.1.0"
   - "@next-friday/prettier-config-friday@4.0.0"
   - "@next-friday/eslint-plugin-friday@1.1.3"
-packageExtensions:
-  payload:
-    peerDependenciesMeta:
-      graphql:
-        optional: true
-  "@payloadcms/next":
-    peerDependenciesMeta:
-      graphql:
-        optional: true
-  "@payloadcms/graphql":
-    peerDependenciesMeta:
-      graphql:
-        optional: true
-  graphql-http:
-    peerDependenciesMeta:
-      graphql:
-        optional: true
-  graphql-scalars:
-    peerDependenciesMeta:
-      graphql:
-        optional: true
 peerDependencyRules:
   ignoreMissing:
     - graphql

package/templates/base/runbooks/rollback-deploy.md

@@ -0,0 +1,27 @@
+# Roll back a deployment
+
+Returns production to the commit it ran before the current one.
+
+**Who runs it:** a release manager. It is a production action: the `prod` environment's required reviewers approve the run, and an agent reports the command but never runs it.
+
+## Command
+
+```sh
+gh workflow run deploy.yml --ref main --field environment=prod --field commit_sha=<previous commit SHA>
+```
+
+`.github/workflows/deploy.yml` accepts any commit that is on `main`, has a successful CI run on `main`, and has a successful deployment to `uat`. A commit that ran in production before meets all three. The workflow checks out that commit, deploys it with `railway up`, and waits for `/health`.
+
+Find the previous commit SHA in the deploy workflow's run history: the second most recent successful run titled `Deploy <SHA> to prod`.
+
+```sh
+gh run list --workflow deploy.yml --branch main --status success --json displayTitle --jq '[.[] | select(.displayTitle | endswith(" to prod"))][1].displayTitle | split(" ")[1]'
+```
+
+## Rehearse
+
+Run the same command with `environment=uat` and the commit SHA that `uat` ran before its current one, then check that `/health` answers on the `uat` URL. The `uat` run needs a successful `dev` deployment of that commit. Rehearse after each change to `deploy.yml`, and on a regular schedule.
+
+## After the rollback
+
+Check that `/health` answers on the production URL, then open an intent for the fault that caused the rollback.