@next-friday/create-app 9.2.1 → 9.3.0

package/package.json

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

package/templates/base/.agents/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 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
+- Compliance: the change matches spec.md, plan.md and the design principles that the policies in force state, each the project's own `.agents/skills/<area>-policy/SKILL.md` or else the `sdlc` plugin's default; flag a plan.md that has no `Accepted by:` line and a change that makes `AGENTS.md` outdated
 
 ## What Important means here
 

package/templates/base/.claude/settings.json

@@ -1,5 +1,16 @@
 {
   "$schema": "https://json.schemastore.org/claude-code-settings.json",
+  "extraKnownMarketplaces": {
+    "next-friday-plugins": {
+      "source": {
+        "source": "directory",
+        "path": "."
+      }
+    }
+  },
+  "enabledPlugins": {
+    "sdlc@next-friday-plugins": true
+  },
   "permissions": {
     "defaultMode": "plan",
     "allow": [

package/templates/base/.claude-plugin/marketplace.json

@@ -0,0 +1,16 @@
+{
+  "name": "next-friday-plugins",
+  "owner": {
+    "name": "Next Friday"
+  },
+  "metadata": {
+    "description": "Plugins that run the Next Friday software development loop."
+  },
+  "plugins": [
+    {
+      "name": "sdlc",
+      "source": "./plugins/sdlc/claude-code",
+      "description": "Runs the software development loop: a skill that matches a request to a playbook and takes it to the next human gate, a help skill, a verifier subagent, and the default policies."
+    }
+  ]
+}

package/templates/base/.cursor/hooks/load-project-plugins.sh

@@ -0,0 +1,3 @@
+#!/bin/sh
+set -eu
+jq -n --arg project "${CURSOR_PROJECT_DIR:?CURSOR_PROJECT_DIR is not set}" '{pluginPaths: [$project + "/plugins/sdlc/cursor"]}'

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

@@ -38,6 +38,12 @@
       {
         "command": ".agents/hooks/agent-format-after-edit.sh"
       }
+    ],
+    "workspaceOpen": [
+      {
+        "command": ".cursor/hooks/load-project-plugins.sh",
+        "timeout": 10
+      }
     ]
   }
 }

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

@@ -88,11 +88,12 @@ jobs:
           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.
+            /sdlc:sdlc-mode 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: |
+            --plugin-dir plugins/sdlc/claude-code
             --model claude-haiku-5-5
             --max-turns 15
             --allowedTools "${{ needs.detect.outputs.tools || 'Read,Grep,Glob' }}"
@@ -103,12 +104,13 @@ jobs:
           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.
+            /sdlc:sdlc-mode 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: |
+            --plugin-dir plugins/sdlc/claude-code
             --model claude-haiku-5-5
             --max-turns 25
             --permission-mode acceptEdits

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

@@ -91,9 +91,10 @@ jobs:
           anthropic_api_key: ${{ secrets.ANTHROPIC_API_KEY }}
           claude_code_oauth_token: ${{ secrets.CLAUDE_CODE_OAUTH_TOKEN }}
           prompt: |
-            /sdlc ${{ matrix.intent }}
+            /sdlc:sdlc-mode ${{ 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: |
+            --plugin-dir plugins/sdlc/claude-code
             --model claude-haiku-5-5
             --max-turns 30
             --permission-mode acceptEdits

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 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
+- Compliance: the change matches spec.md, plan.md and the design principles that the policies in force state, each the project's own `.agents/skills/<area>-policy/SKILL.md` or else the `sdlc` plugin's default; flag a plan.md that has no `Accepted by:` line and a change that makes `AGENTS.md` outdated
 
 ## What Important means here
 

package/templates/base/SETUP.md

@@ -4,7 +4,9 @@ This project runs an AI-native software development loop in Claude Code and Curs
 
 ## How a change flows
 
-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.
+Send a request with `/sdlc:sdlc-mode`. Only a person starts it; nothing routes work into it by itself. `/sdlc:sdlc-help` says how to keep `/sdlc:sdlc-mode` on for a session in Claude Code and Cursor, and `/sdlc:setup-sdlc` chooses the models and reports which steps below are done. `intent/README.md` and the playbooks in `plugins/sdlc/claude-code/skills/sdlc-mode/playbooks/` say who acts and who decides at each stage.
+
+The project holds the `sdlc` plugin itself, in `plugins/sdlc/claude-code/` and `plugins/sdlc/cursor/`, so there is nothing to install. In Claude Code, `.claude/settings.json` registers the project folder as the marketplace `next-friday-plugins` (`.claude-plugin/marketplace.json`) and enables `sdlc@next-friday-plugins`; it applies once a person has trusted the folder. In Cursor, the `workspaceOpen` hook in `.cursor/hooks.json` hands `plugins/sdlc/cursor` to Cursor when it opens the workspace. The copy is the plugin's version: to take a later one, change the `source` entry of `.claude-plugin/marketplace.json`.
 
 ## 1. First commit and push
 
@@ -32,7 +34,7 @@ In `.github/CODEOWNERS`, add these lines in this order. GitHub uses the last mat
 ```text
 * @your-org/your-team
 /intent/ @the-product-owner
-/.agents/skills/sdlc/ @the-lead-who-signs-off-the-intent-template
+/plugins/sdlc/ @the-lead-who-signs-off-the-intent-template
 /.agents/skills/brand-policy/ @the-brand-policy-owner
 /.agents/skills/security-policy/ @the-security-policy-owner
 /.agents/skills/compliance-policy/ @the-compliance-policy-owner
@@ -70,7 +72,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. 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.
+- **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).
 
 **Check:** the test pull request gets a **Claude Code Review** check run within a few minutes.
@@ -90,14 +92,14 @@ 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.
+- **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.
 - **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 turn on `Spec on intent merge` (step 8).
+- Send the intent's path with `/sdlc:sdlc-mode` 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.
 - Set the metric in `bands.yaml`, then turn on `Control band` (step 8).
 
@@ -107,13 +109,14 @@ Replace `security@example.com` in `SECURITY.md` with the contact the security po
 
 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.
+The jobs that send `/sdlc:sdlc-mode` load the plugin from `plugins/sdlc/claude-code` with `--plugin-dir`, because the folder of a CI job is not a trusted folder and `.claude/settings.json` applies only in a trusted one.
+
+- **`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:sdlc-mode 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.
+- **`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:sdlc-mode` 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`.
+On a machine, `pnpm loop:measure` reports the loop's measures. It is not part of `pnpm verify`.
 
 **Check:** with `CLAUDE_CI_ENABLED` unset, **Actions** shows these jobs as skipped.
 

package/templates/base/intent/README.md

@@ -3,7 +3,7 @@
 This folder is the intent home. Every change starts here as an `intent.md`, and its record stays here. Git history keeps the author, the time, and every revision of each file.
 
 - Each change has its own folder, `intent/<change>/`, where `<change>` is a short kebab-case name. The folder holds `intent.md` (Plan), then `spec.md` (Design), then `plan.md` (Build).
-- The playbooks in `.agents/skills/sdlc/playbooks/` say who writes and who accepts each file.
+- The playbooks in `plugins/sdlc/claude-code/skills/sdlc-mode/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/plugins/sdlc/claude-code/.claude-plugin/plugin.json

@@ -0,0 +1,7 @@
+{
+  "name": "sdlc",
+  "description": "Runs the software development loop: a skill that matches a request to a playbook and takes it to the next human gate, a help skill, a verifier subagent, and the default policies.",
+  "license": "MIT",
+  "homepage": "https://github.com/next-friday/next-friday-create-app/tree/main/plugins/sdlc",
+  "repository": "https://github.com/next-friday/next-friday-create-app"
+}

package/templates/base/plugins/sdlc/claude-code/agents/verifier.md

@@ -0,0 +1,7 @@
+---
+name: verifier
+description: Runs the app and checks the change works before the session reports done
+tools: Bash, Read
+---
+
+Run the checks the project's agent instructions name. Then exercise the changed behavior the way a user reaches it: start the app or run the code, and watch the result. Report what you ran, what you saw, and any behavior that does not match plan.md. Do not fix anything; report only.

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

@@ -0,0 +1,53 @@
+#!/bin/sh
+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_-')
+case $mode in
+  save)
+    text=$(printf '%s' "$input" | jq -r '.text // ""')
+    [ -n "$text" ] && [ -n "$conversation" ] || exit 0
+    mkdir -p "$state_directory" && printf '%s' "$text" > "$state_directory/$conversation"
+    exit 0
+    ;;
+  followup)
+    [ -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
+    ;;
+  *)
+    [ "$(printf '%s' "$input" | jq -r '.stop_hook_active // false')" = true ] && exit 0
+    reply=$(printf '%s' "$input" | jq -r '.last_assistant_message // ""')
+    ;;
+esac
+first=$(printf '%s\n' "$reply" | awk 'NF{print; exit}')
+case $first in '**Request:**'*) ;; *) exit 0 ;; esac
+
+last=$(printf '%s\n' "$reply" | awk 'NF{l=$0} END{print l}')
+request=$(printf '%s\n' "$reply" | grep -m1 '^\*\*Request:\*\*')
+outside_fences=$(printf '%s\n' "$reply" | awk '/^[[:space:]]*(```|~~~)/{f=!f; next} !f')
+outside_urls=$(printf '%s\n' "$outside_fences" | sed -E 's#https?://[^][:space:])>]*# #g')
+outside_code=$(printf '%s\n' "$outside_urls" | tr 'A-Z' 'a-z' \
+  | sed -E 's/`((#|(pr|pull request|issue)s?[[:space:]]+#?)[0-9]+)`/ \1 /g; s/`[^`]*`/ /g' \
+  | sed -E 's/(step|item|number|requirement|rule|point|option|case|line)s?[[:space:]]+#[0-9]+/ /g; s/#[0-9]{6,}/ /g')
+
+number=$(printf '%s\n' "$outside_code" \
+  | grep -Eo '(^|[^[:alnum:]_&#/])#[0-9]+([^[:alnum:]_]|$)|(^|[^[:alnum:]_])(pr|pull request|issue)s?[[:space:]]+#?[0-9]+([^[:alnum:]_.]|\.[^0-9]|\.?$)(of[[:space:]]+(the|this|that|a|an|my|our|your|these|those)[[:space:]])?' \
+  | grep -Ev '[[:space:]]of[[:space:]]' | head -1 | sed -E 's/^[^#[:alnum:]]//; s/[^[:alnum:]]$//')
+problems=
+[ -n "$number" ] && problems="Replace \"$number\" with the full URL of that pull request or issue, or with \"this pull request\". "
+case $last in
+  '**Status:**'*)
+    if printf '%s' "$request" | grep -Eq 'https?://' \
+      && ! printf '%s' "$last" | grep -Eiq 'Next:\**[[:space:]]*[<(]?https?://[^[:space:]]+[[:space:]]*$|no next page'; then
+      problems="${problems}End the **Status:** line with \`Next: <full URL of the page where the person acts next>\`, or say \"no next page\" when none waits. "
+    fi
+    ;;
+  *) problems="${problems}End the reply with a line that starts with **Status:**; nothing may follow it. " ;;
+esac
+
+[ -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

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

package/templates/base/{.agents → plugins/sdlc/claude-code}/skills/brand-policy/SKILL.md

@@ -5,8 +5,6 @@ description: Apply the organization's brand policy. Use whenever writing or revi
 
 # Brand policy
 
-Owner: the code owner of this folder in `.github/CODEOWNERS`.
-
 This is the default; the owner adds the brand's names, colours, typefaces, and tone of voice by editing this file.
 
 ## Rules
@@ -14,5 +12,5 @@ This is the default; the owner adds the brand's names, colours, typefaces, and t
 1. A change with no user-visible text, colour, typeface, logo, or message meets this policy; say "Does not apply" and why.
 2. The organization's name, product names, colours, typefaces, and logo files each have one declared source in the project. The spec names that source for every brand value the change shows. When the source does not exist yet, creating it is a requirement of the spec.
 3. No code, style, email, or message the user sees holds a brand value as a literal; each reads it from that source. Project metadata such as `package.json`, `README.md`, and `LICENSE` is outside this rule.
-4. Text the user reads uses one name for one thing and the same words for the same action on every screen, and shows no internal identifier or stack trace.
+4. Text the user reads uses one name for one thing and the same words for the same action on every screen.
 5. A brand value this file does not give, such as an exact colour or a tone of voice, is an area of concern. Never invent one.

package/templates/base/{.agents → plugins/sdlc/claude-code}/skills/compliance-policy/SKILL.md

@@ -5,8 +5,6 @@ description: Apply the organization's compliance policy. Use whenever writing or
 
 # Compliance policy
 
-Owner: the code owner of this folder in `.github/CODEOWNERS`.
-
 Standard: the eight basic principles of the [OECD Guidelines Governing the Protection of Privacy and Transborder Flows of Personal Data](https://legalinstruments.oecd.org/en/instruments/OECD-LEGAL-0188) (adopted 1980, revised 2013), paragraphs 7 to 14. This is the default and names no country's law; the owner adds the laws and contracts that bind the organization by editing this file. The points below summarize those paragraphs; the standard's text governs.
 
 ## Rules

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

@@ -0,0 +1,23 @@
+---
+name: sdlc-help
+description: Explains how this project's workflow runs and how to use /sdlc:sdlc-mode. It answers and starts no work. Run it with /sdlc:sdlc-help.
+disable-model-invocation: true
+---
+
+# SDLC help
+
+1. When the message asks for work rather than how, open no project file. The whole reply is two lines: this command starts no work; and the message to send instead, which is `/sdlc:sdlc-mode` followed by their own words.
+2. When the topic is unclear, ask one question with these choices: how the workflow runs and starting work, keeping `/sdlc:sdlc-mode` on for a session, fixing a defect in behaviour that already exists, who decides at each gate, a mistake the agent repeats, or company policy.
+3. Read the files the topic points to before you answer. When a file disagrees with the map below, the file is right.
+4. When the person asks about a playbook, a command, or a file that this project does not have, the whole reply is three lines: it does not exist; what exists instead, as one file path; and one message they can send next. Stop there. Do not explain the topic from other files.
+5. Otherwise answer, then give one message the person can send as is, with real words from their question and no blanks to fill in, then list the files the answer came from.
+6. Write the reply by the reply rules in `../sdlc-mode/SKILL.md`.
+
+## Map
+
+- **How the workflow runs, and starting work:** the table in `../sdlc-mode/SKILL.md`.
+- **Keeping `/sdlc:sdlc-mode` on for a session:** a person starts it; nothing routes work into it. How long an invoked skill's text stays in the conversation depends on the agent tool: a person sends `/sdlc:sdlc-mode` again to restore the full text, or uses the agent tool's own way to keep a command active for a session.
+- **Fixing a defect in behaviour that already exists:** `playbooks/fix.md` is the path with no intent and no spec, for a person's request: a plan an engineer accepts, then a failing test, the fix, and a pull request. A finding from a job always starts at intent. Every other change runs intent, spec, plan, then build.
+- **Who decides:** the steps marked **Gate** in the playbooks.
+- **A mistake the agent repeats:** the project's agent instructions.
+- **Company policy:** the policy files, each the project's `.agents/skills/<area>-policy/SKILL.md` when it exists and the plugin's default at `../<area>-policy/SKILL.md` otherwise.

package/templates/base/{.cursor/skills/sdlc → plugins/sdlc/claude-code/skills/sdlc-mode}/SKILL.md

@@ -1,6 +1,6 @@
 ---
-name: sdlc
-description: The front door for work in this project. Matches a request to a playbook and runs it to the next human gate. Run it with /sdlc.
+name: sdlc-mode
+description: The front door for work in this project. Matches a request to a playbook and runs it to the next human gate. Run it with /sdlc:sdlc-mode.
 disable-model-invocation: true
 ---
 
@@ -23,18 +23,29 @@ Do these steps in order.
    | A pull request to open for the current branch                                                                           | Follow [`playbooks/open-pr.md`](playbooks/open-pr.md).                                                                         |
    | Anything else                                                                                                           | Say which of the rows above is closest and why it does not fit, answer what you can as `playbooks/question.md` says, and stop. |
 
-   When a request both asks a question and reports a problem, use `question` and offer `plan` in one line. A problem reported with `/sdlc` is the person's ask for `plan`.
+   When a request both asks a question and reports a problem, use `question` and offer `plan` in one line. A problem reported with `/sdlc:sdlc-mode` is the person's ask for `plan`.
+
+   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 give, on the **Status** line, the message that would start it: `/sdlc:sdlc-mode` followed by their own words.
 
 2. **Open the task list** when the session offers a task-list tool. Its first items are the matched playbook's numbered steps, copied word for word, before any other task. A step you do not do stays in the list with `skip: <reason>`. Use `skip` only for a step you decide never to do. A step marked **Gate** is never skipped. When the session offers no such tool, the steps go in the reply instead, under **Steps**, and are never left out, except for `question`. When a playbook's **Next** line chains another playbook, add that playbook's steps when you start it.
-3. **Do the playbook's steps yourself,** stopping only as `.agents/rules/agent-owned-work.md` says. At a step marked **Gate**, wait for the person it names. When a playbook's **Next** line says an agent runs the next file "in the same turn", read that file and continue without asking; otherwise stop at the Gate. Mark each step done in the task list as you finish it.
+3. **Do the playbook's steps yourself,** stopping only at a step marked **Gate**, or before an action that cannot be undone. At a step marked **Gate**, wait for the person it names. When a playbook's **Next** line says an agent runs the next file "in the same turn", read that file and continue without asking; otherwise stop at the Gate. Mark each step done in the task list as you finish it.
 4. **Write the reply in the shape below.**
 
 ## Reply shape
 
-Write the reply as the **Write replies a person can check** convention in `AGENTS.md` says, even when the message also holds a command, a path, or English technical terms. Only paths, commands, and a draft file's own text stay as they are.
+Write replies a person can check. State as a fact only what you opened or ran in this turn, say what you ran, and mark what you did not open or run in this turn as inferred or not checked. Answer what was asked and stop: never hand the person a check you could run. Send nothing outside the session, such as a message to another session or a service, unless a task step says to.
+
+Name a pull request, an issue, a branch, a workflow run, or a file by its full URL on the host that holds it, never by a number or a bare name. The person often reads the reply on a phone: a URL opens the page with one tap, and a number opens nothing.
+
+When the person writes a number and a repository, build the URL before you write anything else: the repository's URL, then the host's path for the thing, such as `/pull/<number>` for a pull request or `/issues/<number>` for an issue. Use that URL where the person wrote the number, from the **Request** line on. After the first mention you may say "this pull request", with no number.
+
+For example, the person writes "who must approve pull request #7 of https://host.example/acme/shop":
+
+- **Request** line: "**Request:** Who must approve https://host.example/acme/shop/pull/7, and which page to open next."
+- **Status** line: "**Status:** Not checked yet who must approve this pull request. It waits for a code owner. Next: https://host.example/acme/shop/pull/7"
 
 ```markdown
-**Request:** <the goal, the problem it solves, and the smallest change you expect to meet it, in your own words. When you cannot name the smallest change yet, say what you must learn first. For a question, only the question.>
+**Request:** <the goal, the problem it solves, and the smallest change you expect to meet it, in your own words. When you cannot name the smallest change yet, say what you must learn first. For a question, only the question. Where the request holds a number, write the URL you built from it.>
 
 **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`.>
 
@@ -42,13 +53,13 @@ Write the reply as the **Write replies a person can check** convention in `AGENT
 
 <What the current step produces: the round of questions, or the whole draft. For a question or a request no row fits, the answer.>
 
-**Status:** <what is done, what comes next, and which gate it waits on and for whom.>
+**Status:** <what is done, what comes next, and which gate it waits on and for whom, all on this one line. When there is a page where the person acts next, the line ends with `Next: <its full URL>`, and nothing follows that URL.>
 ```
 
-A step that is not finished is `open`, including one at its Gate.
+The **Status** line is the last line of the reply.
 
-A reply that ends before a **Gate** step says which step stopped it and why. "Waiting for an instruction" is not a reason.
+A step that is not finished is `open`, including one at its Gate.
 
-When the evidence shows that the change cannot be made in this project, say so under **Request**. In the `plan` playbook, the first round then asks the one question that settles where the change belongs.
+A reply that ends before a **Gate** step says which step stopped it and why.
 
-"new task" starts again at step 1. "don't change anything" keeps the session on `question`.
+When the evidence shows that the change cannot be made in this project, say so under **Request**.

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

@@ -0,0 +1,46 @@
+# Build phase: plan, then implement
+
+This playbook turns a merged spec into a plan the engineer accepts, and then into working code.
+
+1. Find the change: the `intent/<change>/` folder whose `spec.md` or `plan.md` the request names. Its `spec.md` must be on the default branch beside its `intent.md`. In each case below, say only that, in two or three lines, and stop: write no file.
+   - The request names no change, or the folder has no `spec.md` on any branch: list each `intent/*/` on the default branch that has a `spec.md` and no `plan.md`, or say that there is none.
+   - The spec exists only on another branch: say that the spec is not merged yet, and name that branch.
+   - `intent/<change>/plan.md` is already on the default branch: say that the plan is merged, name the file, and say that the change is built only when each requirement of `spec.md` is checked against the tree.
+
+   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` exists on a branch that is not merged, check out that branch. When the request says the plan is accepted, go to step 6. Otherwise 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.
+4. Write the plan from the template below. Use exactly the template's headings. An engineer who has never seen this conversation must be able to implement the change from the plan alone.
+   - **Files that change:** every file, marked new, changed, or deleted, with one line on what it does afterwards.
+   - **Order of work:** numbered steps. Each ends with the check that proves it.
+   - **Risks:** what the change could break, which step is the riskiest, and each option you chose not to take and why.
+   - **Proof:** the tests and commands that show every requirement of the spec is met, by requirement number, and the test or review step for each policy requirement the spec cites.
+
+   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.** Ask whether an engineer could build from it, and for their GitHub handle when you cannot read it. Revise until they say yes. Change no code and commit nothing before that yes. In plan mode, approving the plan is that yes. When the spec classes the change as higher risk, say that a tech lead or an architect accepts the plan with the engineer.
+6. Create the branch as `playbooks/open-pr.md` says, unless step 2 checked one out. Set the plan's `Accepted by:` line, under its title, to the handle of the engineer who said yes in step 5 or whom the request names, and commit `intent/<change>/plan.md` before any other change. In that commit, set the spec's status line to `Status: accepted.`, because its pull request is merged.
+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.
+
+**Next:** `playbooks/open-pr.md`; an agent; in the same turn, as soon as step 8 passes.
+
+## Template
+
+```markdown
+# Plan: <title>
+
+Accepted by: @<engineer>.
+
+## Files that change
+
+## Order of work
+
+## Risks
+
+## Proof
+```

package/templates/base/{.cursor/skills/sdlc → plugins/sdlc/claude-code/skills/sdlc-mode}/playbooks/deploy.md

@@ -2,8 +2,8 @@
 
 1. Find the commit: the full SHA on the default branch that the request names, or the latest commit there. Read its CI run. When a check failed or is still running, say which one in two lines and stop. When you cannot read the CI run from this session, say so and carry on with the commit marked as not verified.
 2. Read how this project deploys: the deploy section of `README.md` and `.github/workflows/deploy.yml`, or the release workflow under `.github/workflows/` when the project releases that way. When the project has no deploy workflow, or deploying is switched off, say so in two lines and stop. When you cannot tell whether deploying is switched on, say so and carry on.
-3. Report where the commit is. For each environment, in the order the project promotes them, say whether this commit is deployed there, and give the deployment's link or the output that shows it. Read production only from the deploy workflow's run history, never with a command that names the production environment. Where you cannot read an environment, write "not read" and why.
-4. Promote the commit to an environment before production only when the request asks for that environment. Do it the way `README.md` says, one environment at a time, and read the health check after each. When a deployment fails, stop: report the failing step and its log, and promote no further. When the request names production, by any name such as `prod`, go to step 5. When it names an environment the project does not have, say so and list the ones it has.
-5. **Gate: the release manager authorizes production.** Never start a production deployment, run a command that names the production environment, or push a release tag. Report the commit's SHA, the environments it has passed, the checks' results, and the exact action the release manager takes to promote it. When the request is to return production to an earlier commit, and the project has `runbooks/rollback-deploy.md`, report that runbook's command with the earlier commit's SHA as that exact action; the release manager runs it. Then wait.
+3. Report where the commit is. For each environment, in the order the project promotes them, say whether this commit is deployed there, and give the deployment's link or the output that shows it. Where you cannot read an environment, write "not read" and why.
+4. Promote the commit to an environment before production only when the request asks for that environment. Do it the way `README.md` says, one environment at a time. When a deployment fails, stop: report the failing step and its log, and promote no further. When the request names production, by any name such as `prod`, go to step 5. When it names an environment the project does not have, say so and list the ones it has.
+5. **Gate: the release manager authorizes production.** Never start a production deployment, run a command that names the production environment, or push a release tag. Report the commit's SHA, the environments it has passed, the checks' results, and the exact action the release manager takes to promote it. Then wait.
 
-**Next:** `.agents/skills/sdlc/playbooks/maintain.md`; a job or a person; when monitoring or a ticket reports a finding in production.
+**Next:** `playbooks/maintain.md`; a job or a person; when monitoring or a ticket reports a finding in production.

package/templates/base/{.claude/skills/sdlc → plugins/sdlc/claude-code/skills/sdlc-mode}/playbooks/design.md

@@ -6,18 +6,18 @@ This playbook turns a merged intent into the requirements and design spec.
    - The request names no intent, or the file does not exist on any branch: list each `intent/*/intent.md` on the default branch that has no `spec.md`, or say that there is none.
    - The file exists only on another branch: say that the intent is not merged yet, and name that branch.
    - `spec.md` already exists: say so and name the file.
-2. Read the four policies, every time, before you write: `.agents/skills/brand-policy/SKILL.md`, `.agents/skills/security-policy/SKILL.md`, `.agents/skills/compliance-policy/SKILL.md`, and `.agents/skills/ux-policy/SKILL.md`. Then read the code and the docs the change touches.
+2. Read the four policies, every time, before you write: for each of `brand`, `security`, `compliance`, and `ux`, read the project's `.agents/skills/<area>-policy/SKILL.md` when it exists, and the plugin's default at `../../<area>-policy/SKILL.md`, relative to this playbook, otherwise. Then read the code and the docs the change touches.
 3. Write `intent/<change>/spec.md` from the template below. Use exactly the template's headings.
-   - **Request:** under the status line, quote the words of the request that started this spec. End the line with the template's "Skills at" sentence; its commit is the output of `git log -1 --format=%h -- .agents/skills`.
+   - **Request:** under the status line, quote the words of the request that started this spec.
    - **Requirements:** numbered. Each one states a result a test or a reader can check.
    - **Design:** how the change fits the existing code: the files that change, and what each one does afterwards.
    - **Policies:** one line for each of the four policies. State which rules of that policy the change must meet, each as a requirement number, or write "Does not apply" and why.
-   - **Areas of concern:** a policy rule the change cannot meet, two policies that contradict, or a decision the files do not settle. Give each one a number, the policy it comes from, and that policy's owner from `.github/CODEOWNERS`. When `.github/CODEOWNERS` names no owner for a policy's folder, write "no owner in `.github/CODEOWNERS`" in place of the owner. Add one area of concern that says so. Write "None" only when there are none.
+   - **Areas of concern:** a policy rule the change cannot meet, two policies that contradict, or a decision the files do not settle. Give each one a number and the policy it comes from. Write "None" only when there are none.
    - **Open questions:** each open question from `intent.md`, answered with its evidence or carried forward. Write "None" only when the intent has none.
-4. Commit `spec.md` on a new branch. In the same commit, set the intent's status line to `Status: accepted.`, because its pull request is merged. Push the branch, and open a pull request ready for review, as `AGENTS.md` says for branches and pull requests. Put the areas of concern first in the pull request's description, under the template's first heading. When you cannot open a pull request from this session, say so and give the pushed branch's name.
-5. **Gate: the product owner reviews the spec.** The product owner resolves each area of concern with its policy owner, then merges the pull request to accept the spec, or closes it to reject it. For a change the spec classes as higher risk, the product owner consults a tech lead before accepting. You do none of these. The spec stays `Status: draft.`: never write `Status: accepted.` in this pull request, because the plan's commit sets it. Report the pull request's URL, keep it green as `.agents/skills/sdlc/playbooks/review.md` says, and wait.
+4. Commit `spec.md` on a new branch. In the same commit, set the intent's status line to `Status: accepted.`, because its pull request is merged. Push the branch, 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.
+5. **Gate: the product owner reviews the spec.** The product owner resolves each area of concern with its policy owner, then merges the pull request to accept the spec, or closes it to reject it. For a change the spec classes as higher risk, the product owner consults a tech lead before accepting. You do none of these. The spec stays `Status: draft.`: never write `Status: accepted.` in this pull request, because the plan's commit sets it. Report the pull request's URL, keep it green as `playbooks/review.md` says, and wait.
 
-**Next:** `.agents/skills/sdlc/playbooks/build.md`; an engineer with an agent; when the product owner has merged the spec's pull request and the engineer sends `/sdlc build` with the spec's path.
+**Next:** `playbooks/build.md`; an engineer with an agent; when the product owner has merged the spec's pull request and the engineer sends `/sdlc:sdlc-mode build` with the spec's path.
 
 ## Template
 
@@ -26,7 +26,7 @@ This playbook turns a merged intent into the requirements and design spec.
 
 From `intent/<change>/intent.md`. Status: draft.
 
-Request: "<the words of the request that started this spec>". Skills at `<commit>`.
+Request: "<the words of the request that started this spec>".
 
 ## Requirements
 

package/templates/base/{.cursor/skills/sdlc → plugins/sdlc/claude-code/skills/sdlc-mode}/playbooks/fix.md

@@ -2,10 +2,10 @@
 
 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 `.agents/skills/sdlc/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.
 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 `.agents/skills/sdlc/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.
+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.
    - **Files that change:** every file, marked new, changed, or deleted, with one line on what it does afterwards.
    - **Order of work:** the cause and the evidence for it, then numbered steps. Each ends with the check that proves it.
    - **Risks:** what the fix could break, and each option you chose not to take and why.
@@ -14,10 +14,10 @@ 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.** Ask whether an engineer could fix the defect from it, and for their GitHub handle when you cannot read it. Revise until they say yes. Change no code and commit nothing before that yes. In plan mode, approving the plan is that yes.
-6. Create the branch `fix/<short-description>` as `AGENTS.md` says. Set the plan's `Accepted by:` line, under its title, to the handle of the engineer who said yes in step 5, and commit `intent/<short-description>/plan.md` as the first commit.
+6. Create the branch `fix/<short-description>` as `playbooks/open-pr.md` says. Set the plan's `Accepted by:` line, under its title, to the handle of the engineer who said yes in step 5, and commit `intent/<short-description>/plan.md` as the first commit.
 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. On a `fix/` branch, `.agents/hooks/agent-test-edit-gate.sh` blocks test edits once the failing test is committed. On a branch with another name, create `.git/bug-fix-in-progress` first, and delete it once the test passes.
-9. Run every check under **Verifying your work** in `AGENTS.md`. 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 `.agents/skills/sdlc/playbooks/open-pr.md`, and then `.agents/skills/sdlc/playbooks/review.md`.
+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`.
 
-**Next:** `.agents/skills/sdlc/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 9 passes.