github-delivery-os 1.0.3 → 1.2.0

package/.claude/skills/delivery-ops/SKILL.md

@@ -0,0 +1,172 @@
+---
+name: delivery-ops
+description: Operate a repo that has GitHub Delivery OS installed — create sprint/production-release/QA-request/bug issues that actually trigger its automation, comment as an approver in phrasing its workflows recognize, and check status (labels, latest comments, burn-down). Targets a specific repo via --repo; defaults to the current repo if this skill was installed into it and none is named. Use when asked to create a sprint, request a release, approve/decline a release, check release or sprint status, or demo/test Delivery OS against a given repo.
+---
+
+# Operate Delivery OS
+
+This drives the actual product — the workflows Delivery OS installs into a consumer repo — as a user of that repo would, not the tooling that ships the `github-delivery-os` package itself (that's the separate `release` skill). Use it to create issues that correctly trigger the installed automation, comment in a way the automation actually recognizes, and check what state something is in.
+
+## Which repo?
+
+Every command below takes `--repo <owner>/<name>` explicitly — never assume based on the working directory alone. Two ways this gets decided:
+
+- **This skill was installed via `npx github-delivery-os install --with-skill`, into a specific repo's own `.claude/skills/`.** In that case the current working directory *is* the repo Delivery OS is installed in, so it's a reasonable default target if the user doesn't name a different one — just confirm that's what they mean before acting.
+- **This skill is installed generically** (copied into `~/.claude/skills/`, available across every project). Here there's no natural default — the working directory could be anything. Ask which repo if it isn't named.
+
+Creating issues and comments in a repo is a visible, outward action — other collaborators see it. Confirm the target repo and intent before creating anything real, the same as any other action that shows up in someone else's GitHub activity.
+
+## Pre-flight check
+
+Before creating anything that depends on configuration, check the target repo actually has Delivery OS installed and configured — a silent no-op (nothing happens because a variable is unset) is more confusing than an upfront "this won't do much yet":
+
+- **Installed?** `gh api repos/<owner>/<repo>/contents/.github/workflows/authorize-deployment.yml --silent` (404 = not installed — suggest `npx github-delivery-os status .` or `install --with-templates` in that repo).
+- **Labels set up?** `gh label list --repo <owner>/<repo>` — look for `production`, `qa`, `qa-request`, `sprint`, `sprint-active`, `planning`, `declined`, `ready-for-deploy`. Missing labels mean `Setup Labels` hasn't been run there yet — offer to fix it directly rather than just reporting the gap: `gh workflow run setup-labels.yml --repo <owner>/<repo>` (it's a `workflow_dispatch` trigger, so this actually creates them on the spot). Confirm with the user first since it's a real change to their repo.
+- **Repo variables set?** `gh variable list --repo <owner>/<repo>` — look for `RELEASE_APPROVER`, `QA_APPROVER`, `QA_ASSIGNEES`. If unset, say so plainly: the issue will still get created, but `notify-release-approver` will ping the literal placeholder `release-approver`/`qa-approver`, not a real person. Setting these requires repo admin access (`gh variable set NAME --repo <owner>/<repo> --body <value>`) — don't set them without being asked to, since they name a real person as approver.
+
+## Creating issues
+
+`gh issue create` does not render GitHub's Issue Forms (the `.github/ISSUE_TEMPLATE/*.yml` files) — those only exist in the web UI. So the body has to be hand-built to match what a form submission would actually produce: `### <Field Label>` headings with the answer beneath each, because that heading text is exactly what the workflows regex-parse. Labels have to be passed explicitly too, since the template's auto-applied labels are also bypassed.
+
+**Show the constructed title, body, and labels before actually creating the issue** — this is a real, visible action in someone else's repo, not a preview in this conversation. Get confirmation on the content, not just the target repo, before calling `gh issue create`.
+
+**Sprint Planning** — triggers `sprint-child-creator` (one child issue per feature line, each labeled `sprint-active`, on open):
+- Title **must contain** the literal string `SPRINT -`, e.g. `SPRINT - Sprint 14`
+- Labels: `sprint`, `planning`
+- Body:
+  ```
+  ### Sprint Name
+
+  <name>
+
+  ### Sprint Start
+
+  YYYY-MM-DD
+
+  ### Sprint End
+
+  YYYY-MM-DD
+
+  ### Sprint Goal
+
+  <goal>
+
+  ### Sprint Features (One Per Line)
+
+  <feature one>
+  <feature two>
+  <feature three>
+
+  ### Sprint Approved
+
+  Pending
+  ```
+  One feature per line, no bullets/numbering (matches the template's own instruction — `sprint-child-creator`'s parser just splits on newlines).
+
+**Production Release** — triggers `notify-release-approver` on open (posts a comment tagging `RELEASE_APPROVER`), and later `authorize-deployment` on comments:
+- Title: `PRODUCTION RELEASE - <project> - vX.X.X`
+- Labels: `release`, `production`, `approval`
+- Body:
+  ```
+  ### Sprint Reference (Sprint Planning Issue #)
+
+  #<N>
+
+  ### Version / Build Number
+
+  vX.X.X
+
+  ### Release Summary
+
+  <summary>
+
+  ### QA Summary + Evidence Links
+
+  <links, or "None yet">
+
+  ### Overall QA Recommendation
+
+  Approve for Production
+
+  ### Deployment Authorized
+
+  No
+  ```
+  (`qa_recommendation` drives the "QA Recommendation" line `notify-release-approver` puts in its comment — use `Approve for Production`, `Reject Release`, or `Conditional Approval` verbatim, those are the three strings it checks for.)
+
+**QA Request** — triggers `auto-assign-qa` (assigns `QA_ASSIGNEES`) on open:
+- Title: `QA REQUEST - <feature/issue>`
+- Labels: `qa-request`
+- Body:
+  ```
+  ### Related Sprint Task Issue (#)
+
+  #<N>
+
+  ### What to Test
+
+  <what to test>
+
+  ### Environment + Build Link
+
+  <build link>
+
+  ### Acceptance Criteria
+
+  <criteria>
+
+  ### QA Outcome
+
+  Pending
+  ```
+
+**Bug Report**:
+- Title: `[BUG] <one-line summary>`
+- Labels: `bug`, `qa`
+- Body: mirror `bug_report.yml`'s fields (`Platform(s) Affected`, `Severity`, `Build / Version`, `Bug Summary`, `Steps to Reproduce`, `Expected Result`, `Actual Result`, `Test Environment`) as `### <label>` / answer pairs.
+
+**Task** — no automation trigger, just structured tracking:
+- Title: `TASK - <one-line summary>`
+- Labels: `task`
+- Body: mirror `task.yml`'s fields (`Task Summary`, `Description`, `Owner`, `Priority` — `P0 - Critical` / `P1 - High` / `P2 - Medium` / `P3 - Low`, `Status` — `Backlog` / `In Progress` / `Blocked` / `Ready for Review` / `Done`, `Acceptance Criteria`, `Artifacts / Links`) as `### <label>` / answer pairs.
+
+## Commenting as an approver
+
+`authorize-deployment` only registers a comment if **both** of these hold:
+- It's posted by the exact GitHub login configured in the repo's `RELEASE_APPROVER` or `QA_APPROVER` variable. `gh issue comment` posts as whichever account `gh auth status` shows — if that's not the configured approver, the comment is just a comment, nothing fires.
+- The comment **leads with** one of the recognized keywords (case-insensitive; anything after the keyword is fine, but the keyword itself has to be at the start):
+  - Release approve: `approved`, `approve`, `ok`, `go ahead`
+  - Release decline: `declined`, `rejected`, `reject`, `not approved`
+  - QA approve: `qa approved`, `approved`, `qa ok`, `looks good`
+
+A later qualifying comment from the same approver overrides an earlier one — a decline can be superseded by a later approval once fixes land, and vice versa.
+
+**Before posting, check that the authenticated login actually matches the approver you're commenting as** — `gh auth status` (or `gh api user --jq .login`) against the `RELEASE_APPROVER`/`QA_APPROVER` value from the pre-flight check. If they don't match, say so and stop: the comment would still post, look successful, and do nothing — a silent no-op that's easy to miss without this check, since `gh issue comment` succeeds either way.
+
+```
+gh issue comment <number> --repo <owner>/<repo> --body "Approved, ship it"
+```
+
+## Checking status
+
+- **Latest comment(s):** `gh issue view <number> --repo <owner>/<repo> --comments`
+- **Current labels:** `gh issue view <number> --repo <owner>/<repo> --json labels`
+- **Sprint burn-down:** read the sprint (parent) issue's body — `gh issue view <sprint-number> --repo <owner>/<repo> --json body` — and look for the `## 🚦 Sprint Status` section `auto-close-sprint` maintains (progress %, time elapsed %, health emoji, burn-down bar). It only exists after at least one child issue has closed.
+
+## Advancing a sprint
+
+Closing a sprint task (child) issue is what actually moves the burn-down — creating the sprint only creates the children, nothing updates until they close:
+
+```
+gh issue close <number> --repo <owner>/<repo>
+```
+
+`auto-close-sprint` fires on close, re-reads every `sprint-active` issue whose body contains `Parent Sprint: #<N>`, recomputes progress, and rewrites the sprint issue's `## 🚦 Sprint Status` section. At 100% it also closes the sprint issue itself and posts a completion comment. Re-check the sprint issue's body afterward to see the update — it happens as a side effect of closing the child, not as a response visible on the child issue itself.
+
+## Finding things
+
+When there's no issue number in hand yet:
+- **Production releases awaiting a decision:** `gh issue list --repo <owner>/<repo> --label production --state open`
+- **Active sprints:** `gh issue list --repo <owner>/<repo> --label sprint --state open` (title contains `SPRINT -`)
+- **Open QA requests:** `gh issue list --repo <owner>/<repo> --label qa-request --state open`
+- **A sprint's own children:** `gh issue list --repo <owner>/<repo> --label sprint-active --search "\"Parent Sprint: #<N>\" in:body"` — the exact-phrase quotes matter, otherwise the search matches "Parent", "Sprint", and the number as separate free-text terms instead of the literal phrase

package/.github/workflows/authorize-deployment.yml

@@ -6,6 +6,7 @@ on:
 
 permissions:
   issues: write
+  contents: read
 
 jobs:
   authorize:
@@ -13,8 +14,22 @@ jobs:
     runs-on: ubuntu-latest
     permissions:
       issues: write
+      contents: read # needed for actions/checkout, so the verdict script can be required from the repo
+    # Serialize per-issue: two comments posted seconds apart (e.g. a decline
+    # immediately corrected with an approval) can trigger overlapping runs.
+    # Both would recompute the same final verdict correctly, but each reads
+    # its "already posted?" check from the stale label snapshot on its own
+    # triggering event, so without this they could both post a status
+    # comment. Scoped per issue (not per repo) so unrelated releases still
+    # process concurrently.
+    concurrency:
+      group: authorize-deployment-${{ github.event.issue.number }}
+      cancel-in-progress: false
 
     steps:
+      - name: Checkout
+        uses: actions/checkout@v6
+
       - name: Check Dual Approval (Flexible + Decline)
         uses: actions/github-script@v7
         env:
@@ -22,81 +37,79 @@ jobs:
           QA_APPROVER: ${{ vars.QA_APPROVER || 'qa-approver' }}
         with:
           script: |
+            // Pure verdict logic lives in a real, unit-tested module (see
+            // .github/scripts/authorize-deployment-verdict.js and
+            // test/authorize-deployment-verdict.test.js) rather than inline here,
+            // so it isn't only verified by hand whenever it changes.
+            const { computeVerdict } = require(`${process.env.GITHUB_WORKSPACE}/.github/scripts/authorize-deployment-verdict.js`);
+
             const issueNumber = context.issue.number;
             const owner = context.repo.owner;
             const repo = context.repo.repo;
             const releaseApprover = process.env.RELEASE_APPROVER;
             const qaApprover = process.env.QA_APPROVER;
 
-            const comments = await github.rest.issues.listComments({
+            const comments = await github.paginate(github.rest.issues.listComments, {
               owner,
               repo,
-              issue_number: issueNumber
+              issue_number: issueNumber,
+              per_page: 100
             });
 
-            let releaseApproved = false;
-            let qaApproved = false;
-
-            for (const comment of comments.data) {
-              const body = (comment.body || "").trim().toLowerCase();
+            const { releaseVerdict, qaApproved } = computeVerdict(comments, releaseApprover, qaApprover);
 
-              if (
-                comment.user.login === releaseApprover &&
-                /(declined|reject|not approved)/i.test(body)
-              ) {
+            const currentLabels = (context.payload.issue.labels || []).map((l) => l.name);
+            const alreadyDeclined = currentLabels.includes("declined");
+            const alreadyReady = currentLabels.includes("ready-for-deploy");
 
-                await github.rest.issues.addLabels({
-                  owner,
-                  repo,
-                  issue_number: issueNumber,
-                  labels: ["declined"]
-                });
+            if (releaseVerdict === "declined") {
+              if (alreadyDeclined) return; // avoid re-posting on every later comment
 
-                try {
-                  await github.rest.issues.removeLabel({
-                    owner,
-                    repo,
-                    issue_number: issueNumber,
-                    name: "ready-for-deploy"
-                  });
-                } catch (e) {}
+              await github.rest.issues.addLabels({
+                owner,
+                repo,
+                issue_number: issueNumber,
+                labels: ["declined"]
+              });
 
-                await github.rest.issues.createComment({
+              try {
+                await github.rest.issues.removeLabel({
                   owner,
                   repo,
                   issue_number: issueNumber,
-                  body: "🔴 **Release Declined**\n\nThis release requires additional fixes before production deployment."
+                  name: "ready-for-deploy"
                 });
+              } catch (e) {}
+
+              await github.rest.issues.createComment({
+                owner,
+                repo,
+                issue_number: issueNumber,
+                body: "🔴 **Release Declined**\n\nThis release requires additional fixes before production deployment."
+              });
 
-                return;
-              }
-
-              if (
-                comment.user.login === releaseApprover &&
-                /^(approved|approve|ok|go ahead)/i.test(body)
-              ) {
-                releaseApproved = true;
-              }
-
-              if (
-                comment.user.login === qaApprover &&
-                /(qa approved|approved|qa ok|looks good)/i.test(body)
-              ) {
-                qaApproved = true;
-              }
+              return;
             }
 
-            if (releaseApproved && qaApproved) {
+            if (releaseVerdict === "approved" && qaApproved) {
+              if (alreadyReady) return; // avoid re-posting on every later comment
 
               try {
-                await github.rest.issues.addLabels({
+                await github.rest.issues.removeLabel({
                   owner,
                   repo,
                   issue_number: issueNumber,
-                  labels: ["ready-for-deploy"]
+                  name: "declined"
                 });
               } catch (e) {}
 
+              await github.rest.issues.addLabels({
+                owner,
+                repo,
+                issue_number: issueNumber,
+                labels: ["ready-for-deploy"]
+              });
+
               await github.rest.issues.createComment({
                 owner,
                 repo,

package/.github/workflows/auto-assign-qa.yml

@@ -19,7 +19,7 @@ jobs:
     steps:
       # pozil/auto-assign-issue does not support 'labels' input; labels come from issue template (qa_request.yml)
       - name: Assign QA team to QA submission issues
-        uses: pozil/auto-assign-issue@v1
+        uses: pozil/auto-assign-issue@d11e715efc663fe323c3d8d4d3cbbfdddd539baf # v1
         with:
           assignees: ${{ vars.QA_ASSIGNEES }}
           repo-token: ${{ secrets.GITHUB_TOKEN }}

package/.github/workflows/auto-close-sprint.yml

@@ -6,14 +6,25 @@ on:
 
 permissions:
   issues: write
+  contents: read
 
 jobs:
   update-sprint:
     runs-on: ubuntu-latest
     permissions:
       issues: write
+      contents: read # needed for actions/checkout, so the burn-down script can be required from the repo
+    # Serialize runs: closing several child issues in quick succession triggers
+    # concurrent runs that each read-modify-write the same sprint issue body,
+    # which can race and drop an update (or double-fire the 100% auto-close).
+    concurrency:
+      group: auto-close-sprint-${{ github.repository }}
+      cancel-in-progress: false
 
     steps:
+      - name: Checkout
+        uses: actions/checkout@v6
+
       - name: Update sprint health, burn-down, and auto-close
         uses: actions/github-script@v7
         env:
@@ -21,13 +32,25 @@ jobs:
           TELEGRAM_CHAT_ID: ${{ secrets.TELEGRAM_CHAT_ID }}
         with:
           script: |
+            // Pure burn-down/health logic lives in a real, unit-tested module
+            // (see .github/scripts/auto-close-sprint.js and
+            // test/auto-close-sprint.test.js) rather than inline here, so
+            // it isn't only verified by hand whenever it changes.
+            const {
+              parseParentSprintNumber,
+              parseSprintDates,
+              computeTimePercent,
+              computeProgress,
+              computeHealthEmoji,
+              renderBurnDown,
+              updateSprintBody,
+            } = require(`${process.env.GITHUB_WORKSPACE}/.github/scripts/auto-close-sprint.js`);
+
             const issue = context.payload.issue;
             const body = issue.body || "";
 
-            const parentMatch = body.match(/Parent Sprint:\s*#(\d+)/);
-            if (!parentMatch) return;
-
-            const sprintNumber = parseInt(parentMatch[1]);
+            const sprintNumber = parseParentSprintNumber(body);
+            if (!sprintNumber) return;
 
             const sprintIssue = await github.rest.issues.get({
               owner: context.repo.owner,
@@ -37,31 +60,27 @@ jobs:
 
             const sprintBody = sprintIssue.data.body || "";
 
-            let startDate, endDate;
-            const dateMatch1 = sprintBody.match(/Sprint Dates[\s\S]*?(\d{4}-\d{2}-\d{2})\s*to\s*(\d{4}-\d{2}-\d{2})/i);
-            const dateMatch2a = sprintBody.match(/Sprint Start[\s\S]*?(\d{4}-\d{2}-\d{2})/i);
-            const dateMatch2b = sprintBody.match(/Sprint End[\s\S]*?(\d{4}-\d{2}-\d{2})/i);
-            if (dateMatch1) {
-              startDate = new Date(dateMatch1[1]);
-              endDate = new Date(dateMatch1[2]);
-            } else if (dateMatch2a && dateMatch2b) {
-              startDate = new Date(dateMatch2a[1]);
-              endDate = new Date(dateMatch2b[1]);
-            }
-            if (!startDate || !endDate) {
+            const dates = parseSprintDates(sprintBody);
+            if (!dates) {
               console.log("Sprint dates not found.");
               return;
             }
-            const now = new Date();
-
-            const totalDuration = endDate - startDate;
-            const elapsed = now - startDate;
-            const timePercent = Math.max(0, Math.min(100, Math.round((elapsed / totalDuration) * 100)));
 
-            const { data: allIssues } = await github.rest.issues.listForRepo({
+            const timePercent = computeTimePercent(dates.startDate, dates.endDate, new Date());
+
+            // Paginate: a plain listForRepo call caps at one page (100 issues) and
+            // would silently undercount children in repos with more open+closed
+            // issues than that, skewing the burn-down. Scoped to `sprint-active`
+            // (the label every child issue gets on creation) instead of every
+            // issue in the repo, so this stays cheap in repos with a lot of
+            // unrelated issue history — this workflow now runs serialized per
+            // repo, so an unscoped full-repo fetch on every child close would
+            // add up fast.
+            const allIssues = await github.paginate(github.rest.issues.listForRepo, {
               owner: context.repo.owner,
               repo: context.repo.repo,
               state: "all",
+              labels: "sprint-active",
               per_page: 100
             });
 
@@ -69,31 +88,10 @@ jobs:
               i.body && i.body.includes(`Parent Sprint: #${sprintNumber}`)
             );
 
-            const closedChildren = children.filter(i => i.state === "closed");
-
-            const progressPercent = children.length === 0
-              ? 0
-              : Math.round((closedChildren.length / children.length) * 100);
-
-            let healthEmoji = "🟢";
-            if (progressPercent < timePercent - 10) healthEmoji = "🔴";
-            else if (progressPercent < timePercent) healthEmoji = "🟡";
-
-            const totalBars = 20;
-            const filledBars = Math.round((progressPercent / 100) * totalBars);
-            const burnDown =
-              "█".repeat(filledBars) + "░".repeat(totalBars - filledBars);
-
-            let updatedBody = sprintBody;
-            updatedBody = updatedBody.replace(/## 🚦 Sprint Status[\s\S]*?---/g, "");
-
-            updatedBody +=
-              `\n\n---\n\n## 🚦 Sprint Status\n\n` +
-              `Progress: **${progressPercent}%**\n` +
-              `Time Elapsed: **${timePercent}%**\n\n` +
-              `Health: ${healthEmoji}\n\n` +
-              `### 📉 Burn-down\n` +
-              `\`${burnDown}\` ${progressPercent}%\n\n---`;
+            const { progressPercent } = computeProgress(children);
+            const healthEmoji = computeHealthEmoji(progressPercent, timePercent);
+            const burnDown = renderBurnDown(progressPercent);
+            const updatedBody = updateSprintBody(sprintBody, { progressPercent, timePercent, healthEmoji, burnDown });
 
             await github.rest.issues.update({
               owner: context.repo.owner,

package/.github/workflows/sprint-child-creator.yml

@@ -6,6 +6,7 @@ on:
 
 permissions:
   issues: write
+  contents: read
 
 jobs:
   create-child-issues:
@@ -13,25 +14,30 @@ jobs:
     runs-on: ubuntu-latest
     permissions:
       issues: write
+      contents: read # needed for actions/checkout, so the parser script can be required from the repo
 
     steps:
+      - name: Checkout
+        uses: actions/checkout@v6
+
       - name: Create Child Issues
         uses: actions/github-script@v7
         with:
           script: |
+            // Pure parsing logic lives in a real, unit-tested module (see
+            // .github/scripts/sprint-child-creator.js and
+            // test/sprint-child-creator.test.js) rather than inline here, so
+            // it isn't only verified by hand whenever it changes.
+            const { parseFeatures, buildChildBody } = require(`${process.env.GITHUB_WORKSPACE}/.github/scripts/sprint-child-creator.js`);
+
             const issue = context.payload.issue;
             const body = issue.body || "";
             const parentNumber = issue.number;
 
-            const featuresMatch = body.match(/### Sprint Features[\s\S]*?(?=###|$)/);
-            if (!featuresMatch) return;
-
-            const features = featuresMatch[0]
-              .split('\n')
-              .map(line => line.trim())
-              .filter(line => line && !line.startsWith('###'));
+            const features = parseFeatures(body);
+            if (features.length === 0) return;
 
-            const bodyContent = `Parent Sprint: #${parentNumber}\n\n---\n*Created by Delivery OS Sprint Child Creator*`;
+            const bodyContent = buildChildBody(parentNumber);
 
             for (const title of features) {
               await github.rest.issues.create({

package/.github/workflows/telegram-issues.yml

@@ -100,10 +100,17 @@ jobs:
             URL="${ISSUE_URL}"
             COMMENT=$(echo "$COMMENT_BODY" | head -c 300)
 
-            if [[ "$ACTOR" == "$RELEASE_APPROVER" ]] && echo "$COMMENT_BODY" | grep -iq "declined\|reject\|not approved"; then
+            # Case-insensitive actor comparison: GitHub logins are case-insensitive,
+            # but a plain bash == is not, so a RELEASE_APPROVER var with different
+            # casing than the actual login would otherwise never match here.
+            # Anchored to the start of a line, matching the same keyword set and
+            # convention as authorize-deployment.yml's DECLINE_RE, so this alert
+            # can't fire for a comment that workflow wouldn't actually treat as a
+            # decline (e.g. "not approved" appearing mid-sentence).
+            if [[ "${ACTOR,,}" == "${RELEASE_APPROVER,,}" ]] && echo "$COMMENT_BODY" | grep -iqE "^(declined|rejected|reject|not approved)"; then
               MESSAGE="🔴🛑 RELEASE DECLINED%0A$TITLE%0A$URL%0A---%0A👤 $ACTOR%0A🕒 $TIMESTAMP"
 
-            elif [[ "$ACTOR" == "$RELEASE_APPROVER" ]] && echo "$COMMENT_BODY" | grep -iq "^approved"; then
+            elif [[ "${ACTOR,,}" == "${RELEASE_APPROVER,,}" ]] && echo "$COMMENT_BODY" | grep -iq "^approved"; then
               MESSAGE="🟢🛡️ RELEASE APPROVED%0A$TITLE%0A$URL%0A---%0A👤 $ACTOR%0A🕒 $TIMESTAMP"
 
             elif [[ "${{ contains(github.event.issue.labels.*.name || fromJSON('[]'), 'bug') }}" == "true" ]]; then

package/README.md

@@ -30,7 +30,7 @@ The **GitHub Delivery Operating System (Delivery OS)** embeds structured intake,
 npx github-delivery-os install --with-templates .
 ```
 
-From your repo root. Add `--with-labels` to create labels via `gh` CLI (requires `gh auth`). Use `--dry-run` to preview first.
+From your repo root. Add `--with-labels` to create labels via `gh` CLI (requires `gh auth`). Add `--with-skill` to also drop in a [Claude Code](https://claude.com/claude-code) skill for operating this repo's Delivery OS from Claude Code — creating sprint/release/QA issues, commenting as an approver, checking status. Use `--dry-run` to preview first.
 
 **Alternative — clone and run script:**
 
@@ -52,12 +52,15 @@ cd github-delivery-operating-system
 
 **Other commands:**
 ```bash
-npx github-delivery-os status .                    # Show what's installed
+npx github-delivery-os status .                    # Show what's installed + installed version
+npx github-delivery-os status --offline .          # Same, without checking npm for updates
 npx github-delivery-os uninstall .                 # Remove workflows
 npx github-delivery-os uninstall --with-templates .  # Remove workflows + templates
 npx github-delivery-os uninstall --dry-run .      # Preview (no changes)
 ```
 
+`status` also checks npm for a newer release and tells you if you're behind (e.g. `⬆️ Update available: 1.0.3 → 1.1.0`), along with the exact command to update. That check is silent and non-fatal if you're offline — use `--offline` to skip it outright (e.g. in CI).
+
 **What gets installed:**
 
 | Workflow | Purpose |
@@ -72,6 +75,10 @@ npx github-delivery-os uninstall --dry-run .      # Preview (no changes)
 
 Workflows and templates are **copied directly** into your repo. No `workflow_call` or external references.
 
+Installing via `npx github-delivery-os` (not the `scripts/install.sh` clone path) also writes `.github/delivery-os.json`, a small manifest recording the installed version — this is what powers the update check in `status`. It's only written when the files it describes are actually current (a fresh install, or `--overwrite`); a skip-mode install over existing files leaves it untouched rather than claiming a version that isn't really on disk. `uninstall` removes it.
+
+With `--with-skill`, a `.claude/skills/delivery-ops/SKILL.md` file is also written — a Claude Code skill scoped to this repo, so anyone working here with Claude Code can create issues that correctly trigger the workflows above, comment as an approver, and check status without knowing the underlying `gh` commands or issue-body formats by heart. It's opt-in and retroactive: `--with-skill` on any later `install` call adds it if it isn't there yet.
+
 ---
 
 ## Quick Start (After Install)
@@ -102,6 +109,8 @@ When you open an issue using the **Sprint Planning** template with a title like
 | Document | Description |
 |----------|-------------|
 | **[Landing page & quick start](https://phaneroo.github.io/github-delivery-operating-system/)** | Overview, one-command install, features |
+| [PRFAQ](docs/PRFAQ.md) | Product overview and FAQs for all audiences (npm launch, install, governance) |
+| [Press release (npm)](docs/press-release.md) | Formal announcement: Delivery OS on npm |
 | [Consumer Setup](docs/consumer-setup.md) | Installation, configuration, variables, labels, Telegram, uninstall |
 | [How To](docs/how-to.md) | Create sprints, request releases, approve, report bugs, QA requests |
 | [Architecture](docs/architecture.md) | Workflows, templates, data flow |

package/package.json

@@ -1,13 +1,14 @@
 {
   "name": "github-delivery-os",
-  "version": "1.0.3",
+  "version": "1.2.0",
   "description": "A GitHub-native Delivery Governance Framework for structured sprint execution, QA review, and collaborative production release control.",
   "main": "src/install.js",
   "bin": {
     "delivery-os": "./bin/delivery-os.js"
   },
   "scripts": {
-    "install:local": "node bin/delivery-os.js install --with-templates ."
+    "install:local": "node bin/delivery-os.js install --with-templates .",
+    "test": "node test/run.js"
   },
   "keywords": [
     "github",
@@ -37,8 +38,15 @@
   "files": [
     "bin",
     "src",
-    ".github/workflows",
-    ".github/ISSUE_TEMPLATE"
+    ".github/workflows/sprint-child-creator.yml",
+    ".github/workflows/auto-close-sprint.yml",
+    ".github/workflows/notify-release-approver.yml",
+    ".github/workflows/authorize-deployment.yml",
+    ".github/workflows/auto-assign-qa.yml",
+    ".github/workflows/telegram-issues.yml",
+    ".github/workflows/setup-labels.yml",
+    ".github/ISSUE_TEMPLATE",
+    ".claude/skills/delivery-ops"
   ],
   "engines": {
     "node": ">=14.0.0"

package/src/cli.js

@@ -20,6 +20,7 @@ program
   .description('Install workflows and templates into a repository')
   .option('-t, --with-templates', 'Copy issue templates (sprint, task, bug, QA, production release)')
   .option('-l, --with-labels', 'Create labels via gh CLI (requires gh auth)')
+  .option('-s, --with-skill', 'Add the delivery-ops Claude Code skill (.claude/skills/delivery-ops/SKILL.md)')
   .option('-o, --overwrite', 'Replace existing workflow/template files')
   .option('--no-overwrite', 'Skip existing files (default)')
   .option('-d, --dry-run', 'Show what would happen without changing files')
@@ -29,6 +30,7 @@ program
       targetDir,
       withTemplates: options.withTemplates ?? false,
       withLabels: options.withLabels ?? false,
+      withSkill: options.withSkill ?? false,
       overwrite: options.overwrite ?? false,
       dryRun: options.dryRun ?? false,
     });
@@ -37,24 +39,33 @@ program
 program
   .command('status [target]')
   .description('Show which workflows and templates are installed')
-  .action((target) => {
-    runStatus({ targetDir: target || '.' });
+  .option('--offline', 'Skip checking npm for the latest published version')
+  .action(async (target, options) => {
+    await runStatus({ targetDir: target || '.', checkUpdates: !options.offline });
   });
 
 program
   .command('uninstall [target]')
   .description('Remove Delivery OS workflows (and optionally templates)')
   .option('-t, --with-templates', 'Also remove issue templates')
+  .option('-s, --with-skill', 'Also remove the delivery-ops Claude Code skill')
   .option('-d, --dry-run', 'Show what would be removed without deleting')
   .action((target, options) => {
     runUninstall({
       targetDir: target || '.',
       withTemplates: options.withTemplates ?? false,
+      withSkill: options.withSkill ?? false,
       dryRun: options.dryRun ?? false,
     });
   });
 
-program.parse();
+// parseAsync (not parse) because the `status` action is async — with plain
+// parse(), an error thrown inside it becomes an unhandled rejection that
+// Node <15 does not treat as fatal, so a real failure could exit 0.
+program.parseAsync().catch((err) => {
+  console.error(err && err.message ? err.message : err);
+  process.exitCode = 1;
+});
 
 // Show help if no command
 if (!process.argv.slice(2).length) {

package/src/install.js

@@ -1,7 +1,15 @@
 const path = require('path');
 const fs = require('fs');
+const https = require('https');
 const { execFileSync } = require('child_process');
 
+const MANIFEST_FILE = 'delivery-os.json'; // written to .github/delivery-os.json in the target repo
+const SKILL_REL_PATH = path.join('.claude', 'skills', 'delivery-ops', 'SKILL.md'); // opt-in via --with-skill
+
+// If you add/remove/rename an entry here, also update package.json's "files"
+// array — it lists these paths explicitly (not the whole .github/workflows
+// directory) so this package's own maintainer workflows (ci.yml, release.yml,
+// pages.yml) don't get bundled into what ships to consumers.
 const WORKFLOWS = [
   'sprint-child-creator',
   'auto-close-sprint',
@@ -30,6 +38,69 @@ const LABELS = [
   ['risk', 'B60205'],
 ];
 
+function manifestPath(targetAbs) {
+  return path.join(targetAbs, '.github', MANIFEST_FILE);
+}
+
+function skillPath(targetAbs) {
+  return path.join(targetAbs, SKILL_REL_PATH);
+}
+
+function readManifest(targetAbs) {
+  try {
+    return JSON.parse(fs.readFileSync(manifestPath(targetAbs), 'utf8'));
+  } catch {
+    return null;
+  }
+}
+
+function writeManifest(targetAbs, version) {
+  const dest = manifestPath(targetAbs);
+  fs.mkdirSync(path.dirname(dest), { recursive: true });
+  fs.writeFileSync(
+    dest,
+    JSON.stringify({ version, installedAt: new Date().toISOString() }, null, 2) + '\n'
+  );
+}
+
+// Best-effort check against the npm registry. Never throws or rejects —
+// resolves null on any failure (offline, registry down, timeout) so callers
+// can treat "unknown" and "couldn't check" identically with no extra
+// error-handling of their own.
+function fetchLatestVersion(timeoutMs = 3000) {
+  return new Promise((resolve) => {
+    let settled = false;
+    const done = (value) => {
+      if (!settled) {
+        settled = true;
+        resolve(value);
+      }
+    };
+    const req = https.get(
+      'https://registry.npmjs.org/github-delivery-os/latest',
+      { headers: { 'User-Agent': 'github-delivery-os-cli' } },
+      (res) => {
+        if (res.statusCode !== 200) {
+          res.resume();
+          done(null);
+          return;
+        }
+        let data = '';
+        res.on('data', (chunk) => (data += chunk));
+        res.on('end', () => {
+          try {
+            done(JSON.parse(data).version || null);
+          } catch {
+            done(null);
+          }
+        });
+      }
+    );
+    req.setTimeout(timeoutMs, () => req.destroy());
+    req.on('error', () => done(null));
+  });
+}
+
 function getPackageRoot() {
   // When installed via npm, __dirname is node_modules/github-delivery-os/src
   const possibleRoots = [
@@ -50,6 +121,7 @@ function runInstall(options) {
     targetDir = '.',
     withTemplates = false,
     withLabels = false,
+    withSkill = false,
     overwrite = false,
     dryRun = false,
   } = options;
@@ -57,6 +129,7 @@ function runInstall(options) {
   const pkgRoot = getPackageRoot();
   const workflowsSrc = path.join(pkgRoot, '.github', 'workflows');
   const templatesSrc = path.join(pkgRoot, '.github', 'ISSUE_TEMPLATE');
+  const skillSrc = path.join(pkgRoot, SKILL_REL_PATH);
   const targetAbs = path.resolve(process.cwd(), targetDir);
 
   console.log('=== GitHub Delivery Operating System ===');
@@ -86,6 +159,10 @@ function runInstall(options) {
 
   let workflowsCopied = 0;
   let templatesCopied = 0;
+  let skillCopied = 0;
+  let workflowsSkipped = 0;
+  let templatesSkipped = 0;
+  let skillSkipped = 0;
 
   // Copy workflows
   for (const wf of WORKFLOWS) {
@@ -99,6 +176,7 @@ function runInstall(options) {
 
     if (fs.existsSync(dest) && !overwrite) {
       console.log(`  Skipped (exists): ${wf}.yml`);
+      workflowsSkipped++;
     } else if (dryRun) {
       console.log(`  [dry-run] Would create: ${wf}.yml`);
       workflowsCopied++;
@@ -120,6 +198,7 @@ function runInstall(options) {
 
       if (fs.existsSync(dest) && !overwrite) {
         console.log(`  Skipped (exists): ${name}`);
+        templatesSkipped++;
       } else if (dryRun) {
         console.log(`  [dry-run] Would create template: ${name}`);
         templatesCopied++;
@@ -131,6 +210,25 @@ function runInstall(options) {
     }
   }
 
+  // Copy the delivery-ops Claude Code skill (opt-in — most consumer repos
+  // aren't using Claude Code, so this is never written unless asked for)
+  if (withSkill && fs.existsSync(skillSrc)) {
+    const skillDest = skillPath(targetAbs);
+
+    if (fs.existsSync(skillDest) && !overwrite) {
+      console.log(`  Skipped (exists): ${SKILL_REL_PATH}`);
+      skillSkipped++;
+    } else if (dryRun) {
+      console.log(`  [dry-run] Would create: ${SKILL_REL_PATH}`);
+      skillCopied++;
+    } else {
+      fs.mkdirSync(path.dirname(skillDest), { recursive: true });
+      fs.copyFileSync(skillSrc, skillDest);
+      console.log(`  Created: ${SKILL_REL_PATH}`);
+      skillCopied++;
+    }
+  }
+
   // Create labels via gh
   let labelsCreated = 0;
   let labelsSkipReason = '';
@@ -192,15 +290,35 @@ function runInstall(options) {
     }
   }
 
+  // Record what got installed so `status` can report a version and detect
+  // drift. Only claim a version when the on-disk files actually match it: an
+  // overwrite, or a fresh install where nothing had to be skipped. A partial
+  // skip-mode install would leave older file content on disk, so don't
+  // overwrite a previously recorded (possibly accurate, possibly newer)
+  // version with a number that isn't actually true on disk yet.
+  const cleanInstall = overwrite || (workflowsSkipped === 0 && templatesSkipped === 0 && skillSkipped === 0);
+  if (!dryRun && cleanInstall) {
+    const pkgVersion = require(path.join(pkgRoot, 'package.json')).version;
+    writeManifest(targetAbs, pkgVersion);
+  }
+
   // Summary
   console.log('');
-  if (workflowsCopied > 0 || templatesCopied > 0 || labelsCreated > 0) {
+  if (!dryRun && !cleanInstall) {
+    console.log('  Note: some files already existed and were skipped, so the recorded');
+    console.log('  Delivery OS version was not updated. Re-run with --overwrite to sync');
+    console.log('  all files (and the recorded version) to the latest release.');
+    console.log('');
+  }
+  if (workflowsCopied > 0 || templatesCopied > 0 || skillCopied > 0 || labelsCreated > 0) {
     if (dryRun) {
       if (workflowsCopied > 0) console.log(`Would install ${workflowsCopied} workflow(s).`);
       if (templatesCopied > 0) console.log(`Would copy ${templatesCopied} issue template(s).`);
+      if (skillCopied > 0) console.log('Would add the Claude Code delivery-ops skill.');
     } else {
       if (workflowsCopied > 0) console.log(`Installed ${workflowsCopied} workflow(s).`);
       if (templatesCopied > 0) console.log(`Copied ${templatesCopied} issue template(s).`);
+      if (skillCopied > 0) console.log('Added the Claude Code delivery-ops skill.');
       if (labelsCreated > 0) console.log(`Created ${labelsCreated} label(s).`);
     }
     console.log('');
@@ -212,8 +330,14 @@ function runInstall(options) {
     console.log('     - QA_APPROVER: GitHub username of QA approver');
     console.log('     - QA_ASSIGNEES: Comma-separated usernames for QA assignment');
     console.log('  3. Add secrets (optional, for Telegram): TELEGRAM_BOT_TOKEN, TELEGRAM_CHAT_ID');
+    let nextStep = 4;
     if (!withTemplates) {
-      console.log('  4. Copy templates: re-run with --with-templates');
+      console.log(`  ${nextStep}. Copy templates: re-run with --with-templates`);
+      nextStep++;
+    }
+    if (!withSkill) {
+      console.log(`  ${nextStep}. Add the Claude Code delivery-ops skill (optional, for Claude Code users): re-run with --with-skill`);
+      nextStep++;
     }
     console.log('');
     console.log('See https://phaneroo.github.io/github-delivery-operating-system/ for full docs.');
@@ -238,8 +362,8 @@ const TEMPLATES = [
   'bug_report.yml',
 ];
 
-function runStatus(options) {
-  const { targetDir = '.' } = options;
+async function runStatus(options) {
+  const { targetDir = '.', checkUpdates = true } = options;
   const targetAbs = path.resolve(process.cwd(), targetDir);
   const workflowsDest = path.join(targetAbs, '.github', 'workflows');
   const templatesDest = path.join(targetAbs, '.github', 'ISSUE_TEMPLATE');
@@ -254,6 +378,33 @@ function runStatus(options) {
   const installedTemplates = TEMPLATES.filter((t) =>
     fs.existsSync(path.join(templatesDest, t))
   );
+  const skillInstalled = fs.existsSync(skillPath(targetAbs));
+
+  if (installedWorkflows.length > 0 || installedTemplates.length > 0) {
+    const manifest = readManifest(targetAbs);
+    if (manifest && manifest.version) {
+      const installedOn = manifest.installedAt ? ` (installed ${manifest.installedAt.slice(0, 10)})` : '';
+      console.log(`Installed version: ${manifest.version}${installedOn}`);
+    } else {
+      console.log('Installed version: unknown (installed before version tracking was added)');
+      console.log('  Run install with --overwrite to record the current version.');
+    }
+
+    if (checkUpdates) {
+      const latest = await fetchLatestVersion();
+      if (!latest) {
+        console.log('  (Could not check npm for the latest version — offline or registry unreachable.)');
+      } else if (manifest && manifest.version === latest) {
+        console.log(`✓ Up to date (latest is ${latest})`);
+      } else if (manifest && manifest.version) {
+        console.log(`⬆️  Update available: ${manifest.version} → ${latest}`);
+        console.log('    Run: npx github-delivery-os@latest install --overwrite .');
+      } else {
+        console.log(`Latest published version: ${latest}`);
+      }
+    }
+    console.log('');
+  }
 
   if (installedWorkflows.length > 0) {
     console.log('Workflows:');
@@ -273,18 +424,29 @@ function runStatus(options) {
     console.log('');
   }
 
+  if (installedWorkflows.length > 0 || installedTemplates.length > 0) {
+    console.log('Claude Code skill:');
+    console.log(
+      skillInstalled
+        ? '  ✓ delivery-ops'
+        : '  ○ delivery-ops (not installed — re-run install with --with-skill)'
+    );
+    console.log('');
+  }
+
   if (installedWorkflows.length === 0 && installedTemplates.length === 0) {
     console.log('Delivery OS is not installed in this repository.');
     console.log('Run: npx github-delivery-os install --with-templates .');
   } else {
-    const total = installedWorkflows.length + installedTemplates.length;
-    console.log(`Summary: ${installedWorkflows.length}/${WORKFLOWS.length} workflows, ${installedTemplates.length}/${TEMPLATES.length} templates`);
+    console.log(
+      `Summary: ${installedWorkflows.length}/${WORKFLOWS.length} workflows, ${installedTemplates.length}/${TEMPLATES.length} templates, skill: ${skillInstalled ? 'yes' : 'no'}`
+    );
   }
   console.log('');
 }
 
 function runUninstall(options) {
-  const { targetDir = '.', withTemplates = false, dryRun = false } = options;
+  const { targetDir = '.', withTemplates = false, withSkill = false, dryRun = false } = options;
   const targetAbs = path.resolve(process.cwd(), targetDir);
   const workflowsDest = path.join(targetAbs, '.github', 'workflows');
   const templatesDest = path.join(targetAbs, '.github', 'ISSUE_TEMPLATE');
@@ -325,15 +487,47 @@ function runUninstall(options) {
     }
   }
 
+  let skillRemoved = 0;
+  if (withSkill) {
+    const skillDest = skillPath(targetAbs);
+    if (fs.existsSync(skillDest)) {
+      if (dryRun) {
+        console.log(`  [dry-run] Would remove: ${SKILL_REL_PATH}`);
+      } else {
+        fs.unlinkSync(skillDest);
+        console.log(`  Removed: ${SKILL_REL_PATH}`);
+      }
+      skillRemoved++;
+    }
+  }
+
+  // Remove the version manifest too — it has no meaning once Delivery OS is
+  // gone, and leaving it behind would make a later install/status think a
+  // stale version is still installed.
+  const manifestDest = manifestPath(targetAbs);
+  if (fs.existsSync(manifestDest)) {
+    if (dryRun) {
+      console.log('  [dry-run] Would remove: delivery-os.json');
+    } else {
+      fs.unlinkSync(manifestDest);
+      console.log('  Removed: delivery-os.json');
+    }
+  }
+
   console.log('');
-  if (workflowsRemoved > 0 || templatesRemoved > 0) {
+  if (workflowsRemoved > 0 || templatesRemoved > 0 || skillRemoved > 0) {
+    const templateNote = withTemplates ? `, ${templatesRemoved} template(s)` : '';
+    const skillNote = withSkill ? `, ${skillRemoved} skill file(s)` : '';
     if (dryRun) {
-      console.log(`Would remove ${workflowsRemoved} workflow(s)${withTemplates ? `, ${templatesRemoved} template(s)` : ''}.`);
+      console.log(`Would remove ${workflowsRemoved} workflow(s)${templateNote}${skillNote}.`);
     } else {
-      console.log(`Removed ${workflowsRemoved} workflow(s)${withTemplates ? `, ${templatesRemoved} template(s)` : ''}.`);
+      console.log(`Removed ${workflowsRemoved} workflow(s)${templateNote}${skillNote}.`);
       if (!withTemplates) {
         console.log('Templates were kept. Re-run with --with-templates to remove them.');
       }
+      if (!withSkill) {
+        console.log('Claude Code skill (if installed) was kept. Re-run with --with-skill to remove it.');
+      }
     }
   } else {
     console.log('No Delivery OS files found to remove.');
@@ -342,4 +536,19 @@ function runUninstall(options) {
   console.log('=== Uninstall complete ===');
 }
 
-module.exports = { runInstall, runStatus, runUninstall };
+module.exports = {
+  runInstall,
+  runStatus,
+  runUninstall,
+  // Exposed for tests only — not part of the CLI's public API.
+  __test__: {
+    manifestPath,
+    readManifest,
+    writeManifest,
+    fetchLatestVersion,
+    skillPath,
+    SKILL_REL_PATH,
+    WORKFLOWS,
+    TEMPLATES,
+  },
+};

package/.github/workflows/pages.yml

@@ -1,46 +0,0 @@
-# Deploy docs/ to GitHub Pages
-# Requires: Settings → Pages → Source: GitHub Actions
-
-name: Deploy to GitHub Pages
-
-on:
-  push:
-    branches: [main]
-  workflow_dispatch:
-
-permissions:
-  contents: read
-  pages: write
-  id-token: write
-
-concurrency:
-  group: pages
-  cancel-in-progress: false
-
-env:
-  FORCE_JAVASCRIPT_ACTIONS_TO_NODE24: true
-
-jobs:
-  deploy:
-    runs-on: ubuntu-latest
-    environment:
-      name: github-pages
-      url: ${{ steps.deployment.outputs.page_url }}
-    steps:
-      - name: Opt into Node.js 24
-        run: echo "FORCE_JAVASCRIPT_ACTIONS_TO_NODE24=true" >> $GITHUB_ENV
-
-      - name: Checkout
-        uses: actions/checkout@v6
-
-      - name: Setup Pages
-        uses: actions/configure-pages@v5
-
-      - name: Upload artifact
-        uses: actions/upload-pages-artifact@v4
-        with:
-          path: ./docs
-
-      - name: Deploy to GitHub Pages
-        id: deployment
-        uses: actions/deploy-pages@v4

package/.github/workflows/release.yml

@@ -1,27 +0,0 @@
-# Create GitHub release when a version tag is pushed
-# Usage: git tag v1.0.2 && git push origin v1.0.2
-
-name: Release
-
-on:
-  push:
-    tags:
-      - 'v*'
-
-permissions:
-  contents: write
-
-jobs:
-  release:
-    runs-on: ubuntu-latest
-    steps:
-      - uses: actions/checkout@v6
-        with:
-          fetch-depth: 0
-
-      - name: Create Release
-        uses: softprops/action-gh-release@v2
-        with:
-          generate_release_notes: true
-        env:
-          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}