github-delivery-os 1.1.0 → 1.2.1

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/scripts/authorize-deployment-verdict.js

@@ -0,0 +1,55 @@
+'use strict';
+
+// Pure verdict-computation logic for authorize-deployment.yml, extracted out
+// of the inline actions/github-script step so it can be unit tested directly
+// (see test/authorize-deployment-verdict.test.js) instead of only verified
+// by hand whenever it changes. Has no dependency on the `github`/`context`
+// globals actions/github-script injects — everything it needs is passed in.
+
+// Anchored to comment start + word boundary so keywords must lead the
+// comment (matches the documented convention) and can't match inside a
+// larger word (e.g. "ok" no longer matches "okay", "reject" no longer
+// matches "rejection") or as a substring anywhere in unrelated prose.
+const DECLINE_RE = /^(declined|rejected|reject|not approved)\b/i;
+const APPROVE_RE = /^(approved|approve|ok|go ahead)\b/i;
+const QA_APPROVE_RE = /^(qa approved|approved|qa ok|looks good)\b/i;
+
+const normalize = (s) => (s || '').toLowerCase();
+
+/**
+ * Walks comments in chronological order and keeps the LATEST verdict from
+ * each approver, rather than stopping at the first decline seen. This lets a
+ * release approver re-approve after an earlier decline (e.g. once fixes
+ * land) instead of being permanently stuck as declined.
+ *
+ * @param {Array<{ user?: { login?: string | null } | null, body?: string | null }>} comments
+ *   Chronological (oldest first), matching the order github.paginate(listComments) returns.
+ * @param {string} releaseApprover
+ * @param {string} qaApprover
+ * @returns {{ releaseVerdict: 'approved' | 'declined' | null, qaApproved: boolean }}
+ */
+function computeVerdict(comments, releaseApprover, qaApprover) {
+  let releaseVerdict = null;
+  let qaApproved = false;
+
+  for (const comment of comments) {
+    const login = comment.user && comment.user.login;
+    const body = (comment.body || '').trim();
+
+    if (normalize(login) === normalize(releaseApprover)) {
+      if (DECLINE_RE.test(body)) {
+        releaseVerdict = 'declined';
+      } else if (APPROVE_RE.test(body)) {
+        releaseVerdict = 'approved';
+      }
+    }
+
+    if (normalize(login) === normalize(qaApprover) && QA_APPROVE_RE.test(body)) {
+      qaApproved = true;
+    }
+  }
+
+  return { releaseVerdict, qaApproved };
+}
+
+module.exports = { computeVerdict, DECLINE_RE, APPROVE_RE, QA_APPROVE_RE };

package/.github/scripts/auto-close-sprint.js

@@ -0,0 +1,124 @@
+'use strict';
+
+// Pure burn-down/health computation for auto-close-sprint.yml, extracted so
+// it can be unit tested directly (see test/auto-close-sprint.test.js)
+// instead of only verified by hand.
+
+/**
+ * @param {string} body - a child issue's body
+ * @returns {number | null} the parent sprint issue number, or null if this
+ *   issue isn't a sprint child (no "Parent Sprint: #N" line).
+ */
+function parseParentSprintNumber(body) {
+  const match = (body || '').match(/Parent Sprint:\s*#(\d+)/);
+  return match ? parseInt(match[1], 10) : null;
+}
+
+/**
+ * Parses sprint dates out of a sprint issue's body, supporting both the
+ * combined "Sprint Dates: X to Y" format and the separate "Sprint Start" /
+ * "Sprint End" field format (the sprint_planning.yml template).
+ *
+ * @param {string} sprintBody - the sprint (parent) issue's body
+ * @returns {{ startDate: Date, endDate: Date } | null} null if neither
+ *   format matched.
+ */
+function parseSprintDates(sprintBody) {
+  const body = sprintBody || '';
+
+  const rangeMatch = body.match(/Sprint Dates[\s\S]*?(\d{4}-\d{2}-\d{2})\s*to\s*(\d{4}-\d{2}-\d{2})/i);
+  if (rangeMatch) {
+    return { startDate: new Date(rangeMatch[1]), endDate: new Date(rangeMatch[2]) };
+  }
+
+  const startMatch = body.match(/Sprint Start[\s\S]*?(\d{4}-\d{2}-\d{2})/i);
+  const endMatch = body.match(/Sprint End[\s\S]*?(\d{4}-\d{2}-\d{2})/i);
+  if (startMatch && endMatch) {
+    return { startDate: new Date(startMatch[1]), endDate: new Date(endMatch[1]) };
+  }
+
+  return null;
+}
+
+/**
+ * @param {Date} startDate
+ * @param {Date} endDate
+ * @param {Date} now
+ * @returns {number} percent of the sprint's duration elapsed as of `now`,
+ *   clamped to [0, 100]. Returns 100 for a zero-or-negative-length sprint
+ *   (Start >= End — a data-entry mistake) or an unparseable date (e.g. an
+ *   out-of-range "2026-13-05" typo, which regex-matches the YYYY-MM-DD
+ *   shape but produces an Invalid Date) instead of dividing by zero or NaN:
+ *   that NaN would otherwise flow into the posted burn-down as "Time
+ *   Elapsed: NaN%", and every NaN comparison in computeHealthEmoji is
+ *   false, so it'd silently default to the green/no-warning branch instead
+ *   of flagging the broken dates. `!(totalDuration > 0)` (rather than
+ *   `totalDuration <= 0`) catches NaN too, since every comparison against
+ *   NaN is false — `NaN <= 0` is false, but so is `NaN > 0`, and negating
+ *   that is true.
+ */
+function computeTimePercent(startDate, endDate, now) {
+  const totalDuration = endDate - startDate;
+  if (!(totalDuration > 0)) return 100;
+  const elapsed = now - startDate;
+  return Math.max(0, Math.min(100, Math.round((elapsed / totalDuration) * 100)));
+}
+
+/**
+ * @param {Array<{ state: string }>} children
+ * @returns {{ progressPercent: number, closedCount: number, totalCount: number }}
+ */
+function computeProgress(children) {
+  const totalCount = children.length;
+  const closedCount = children.filter((i) => i.state === 'closed').length;
+  const progressPercent = totalCount === 0 ? 0 : Math.round((closedCount / totalCount) * 100);
+  return { progressPercent, closedCount, totalCount };
+}
+
+/**
+ * Sprint health relative to time elapsed: red if progress trails time by
+ * more than 10 points, yellow if behind at all, green otherwise.
+ *
+ * @returns {'🟢' | '🟡' | '🔴'}
+ */
+function computeHealthEmoji(progressPercent, timePercent) {
+  if (progressPercent < timePercent - 10) return '🔴';
+  if (progressPercent < timePercent) return '🟡';
+  return '🟢';
+}
+
+/**
+ * @returns {string} a block-character progress bar, e.g. "████░░░░░░░░░░░░░░░░".
+ */
+function renderBurnDown(progressPercent, totalBars = 20) {
+  const filledBars = Math.round((progressPercent / 100) * totalBars);
+  return '█'.repeat(filledBars) + '░'.repeat(totalBars - filledBars);
+}
+
+/**
+ * Replaces any previous "## 🚦 Sprint Status" block in the sprint body with
+ * a freshly rendered one (appended at the end).
+ */
+function updateSprintBody(sprintBody, { progressPercent, timePercent, healthEmoji, burnDown }) {
+  let updatedBody = (sprintBody || '').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---`;
+
+  return updatedBody;
+}
+
+module.exports = {
+  parseParentSprintNumber,
+  parseSprintDates,
+  computeTimePercent,
+  computeProgress,
+  computeHealthEmoji,
+  renderBurnDown,
+  updateSprintBody,
+};

package/.github/scripts/sprint-child-creator.js

@@ -0,0 +1,34 @@
+'use strict';
+
+// Pure parsing logic for sprint-child-creator.yml, extracted so it can be
+// unit tested directly (see test/sprint-child-creator.test.js) instead of
+// only verified by hand.
+
+/**
+ * Extracts the feature list from a sprint-planning issue body's
+ * "### Sprint Features" section (one feature per line, up to the next
+ * heading or end of body).
+ *
+ * @param {string} body - the sprint issue's body
+ * @returns {string[]} feature titles, in the order they appear. Empty if
+ *   there's no Sprint Features section, or it has no non-blank lines.
+ */
+function parseFeatures(body) {
+  const featuresMatch = (body || '').match(/### Sprint Features[\s\S]*?(?=###|$)/);
+  if (!featuresMatch) return [];
+
+  return featuresMatch[0]
+    .split('\n')
+    .map((line) => line.trim())
+    .filter((line) => line && !line.startsWith('###'));
+}
+
+/**
+ * @param {number} parentNumber - the sprint (parent) issue number
+ * @returns {string} body to use for each generated child issue
+ */
+function buildChildBody(parentNumber) {
+  return `Parent Sprint: #${parentNumber}\n\n---\n*Created by Delivery OS Sprint Child Creator*`;
+}
+
+module.exports = { parseFeatures, buildChildBody };

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

@@ -58,19 +58,40 @@ jobs:
 
             const { releaseVerdict, qaApproved } = computeVerdict(comments, releaseApprover, qaApprover);
 
-            const currentLabels = (context.payload.issue.labels || []).map((l) => l.name);
+            // Nothing to act on this run (most comments on a production issue
+            // are routine discussion, not a verdict-changing approval/decline)
+            // — return before the live label fetch below, which only matters
+            // once we actually have a verdict to check against current state.
+            const hasActionableVerdict =
+              releaseVerdict === "declined" || (releaseVerdict === "approved" && qaApproved);
+            if (!hasActionableVerdict) return;
+
+            // Fetch labels live rather than trusting context.payload.issue.labels:
+            // that's a snapshot fixed at the triggering event's delivery time.
+            // Two comments posted seconds apart queue under the concurrency
+            // group above and run sequentially, but each was still delivered
+            // (and its label snapshot captured) before either job actually ran
+            // — serializing execution order doesn't refresh an already-stale
+            // snapshot. A live re-fetch is what actually lets the second
+            // (queued) run see what the first one just did.
+            const { data: liveIssue } = await github.rest.issues.get({ owner, repo, issue_number: issueNumber });
+            const currentLabels = (liveIssue.labels || []).map((l) => (typeof l === "string" ? l : l.name));
             const alreadyDeclined = currentLabels.includes("declined");
             const alreadyReady = currentLabels.includes("ready-for-deploy");
 
             if (releaseVerdict === "declined") {
               if (alreadyDeclined) return; // avoid re-posting on every later comment
 
-              await github.rest.issues.addLabels({
-                owner,
-                repo,
-                issue_number: issueNumber,
-                labels: ["declined"]
-              });
+              try {
+                await github.rest.issues.addLabels({
+                  owner,
+                  repo,
+                  issue_number: issueNumber,
+                  labels: ["declined"]
+                });
+              } catch (e) {
+                console.log(`Failed to add 'declined' label: ${e.message || e}`);
+              }
 
               try {
                 await github.rest.issues.removeLabel({
@@ -103,12 +124,16 @@ jobs:
                 });
               } catch (e) {}
 
-              await github.rest.issues.addLabels({
-                owner,
-                repo,
-                issue_number: issueNumber,
-                labels: ["ready-for-deploy"]
-              });
+              try {
+                await github.rest.issues.addLabels({
+                  owner,
+                  repo,
+                  issue_number: issueNumber,
+                  labels: ["ready-for-deploy"]
+                });
+              } catch (e) {
+                console.log(`Failed to add 'ready-for-deploy' label: ${e.message || e}`);
+              }
 
               await github.rest.issues.createComment({
                 owner,

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

@@ -70,17 +70,23 @@ jobs:
 
             // 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.
+            // issues than that, skewing the burn-down.
+            //
+            // Deliberately NOT scoped to labels: "sprint-active" (an earlier
+            // version of this workflow did that, for cost — cheaper in repos
+            // with a lot of unrelated issue history). That's wrong: a child
+            // issue relabeled away from sprint-active during triage (e.g. to
+            // "bug") while still open would silently drop out of BOTH the
+            // numerator and denominator of the progress calculation instead
+            // of just being excluded from the closed count — the sprint could
+            // report inflated progress, or even reach a false 100% and
+            // auto-close, while that untracked child is still open. Matches
+            // docs/governance.md's documented trigger ("body has Parent
+            // Sprint"), which is body-content-based, not label-based.
             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
             });
 

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

@@ -103,14 +103,20 @@ jobs:
             # 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
+            # Anchored to the start of a line + word boundary (\b), matching the
+            # same keyword set and convention as authorize-deployment.yml's real
+            # DECLINE_RE/APPROVE_RE, so this alert can't fire for a comment that
+            # workflow wouldn't actually treat as a decline/approval (e.g. "not
+            # approved" mid-sentence, or "okay, I'll look at this tomorrow" —
+            # "ok" without \b would otherwise match as a false approval).
+            if [[ "${ACTOR,,}" == "${RELEASE_APPROVER,,}" ]] && echo "$COMMENT_BODY" | grep -iqE "^(declined|rejected|reject|not approved)\b"; then
               MESSAGE="🔴🛑 RELEASE DECLINED%0A$TITLE%0A$URL%0A---%0A👤 $ACTOR%0A🕒 $TIMESTAMP"
 
-            elif [[ "${ACTOR,,}" == "${RELEASE_APPROVER,,}" ]] && echo "$COMMENT_BODY" | grep -iq "^approved"; then
+            # Matches authorize-deployment.yml's full APPROVE_RE keyword set
+            # (approved|approve|ok|go ahead), not just "approved" — it used to
+            # miss "ok"/"go ahead"/"approve", so a release could be approved
+            # for real with no Telegram alert sent for it.
+            elif [[ "${ACTOR,,}" == "${RELEASE_APPROVER,,}" ]] && echo "$COMMENT_BODY" | grep -iqE "^(approved|approve|ok|go ahead)\b"; 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:**
 
@@ -77,6 +77,8 @@ Workflows and templates are **copied directly** into your repo. No `workflow_cal
 
 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)

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "github-delivery-os",
-  "version": "1.1.0",
+  "version": "1.2.1",
   "description": "A GitHub-native Delivery Governance Framework for structured sprint execution, QA review, and collaborative production release control.",
   "main": "src/install.js",
   "bin": {
@@ -38,8 +38,18 @@
   "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/scripts/authorize-deployment-verdict.js",
+    ".github/scripts/auto-close-sprint.js",
+    ".github/scripts/sprint-child-creator.js",
+    ".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,
     });
@@ -46,11 +48,13 @@ 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,
     });
   });

package/src/install.js

@@ -4,7 +4,12 @@ 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',
@@ -15,6 +20,22 @@ const WORKFLOWS = [
   'setup-labels',
 ];
 
+// Pure logic some of the workflows above require() at runtime from
+// .github/scripts/<name>.js (see .github/workflows/authorize-deployment.yml
+// etc.) — these are required dependencies of those workflows, not optional,
+// so they're always copied alongside them, the same as WORKFLOWS. Also list
+// them explicitly in package.json's "files".
+const SCRIPTS = ['authorize-deployment-verdict', 'auto-close-sprint', 'sprint-child-creator'];
+
+// Which workflow requires which script, so `status` can flag a workflow
+// that's present but whose required script is missing (an install that will
+// fail with MODULE_NOT_FOUND the next time that workflow actually runs).
+const REQUIRED_SCRIPT_BY_WORKFLOW = {
+  'authorize-deployment': 'authorize-deployment-verdict',
+  'auto-close-sprint': 'auto-close-sprint',
+  'sprint-child-creator': 'sprint-child-creator',
+};
+
 const LABELS = [
   ['intake', '0E8A16'],
   ['bug', 'D93F0B'],
@@ -37,6 +58,10 @@ 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'));
@@ -92,6 +117,44 @@ function fetchLatestVersion(timeoutMs = 3000) {
   });
 }
 
+// Copies each `${name}${ext}` from srcDir to destDir for a fixed list of
+// expected filenames — the shared logic behind copying WORKFLOWS and SCRIPTS
+// (both: a required, always-on set of individually-named files, as opposed
+// to templates, which copies whatever's found in a directory, or the skill,
+// a single optional file). `label` is what's printed for each entry, e.g.
+// `.github/scripts/auto-close-sprint.js` — pass names already including
+// their directory prefix so log lines are self-explanatory on their own.
+function copyManagedFiles(names, ext, srcDir, destDir, { overwrite, dryRun, relDir }) {
+  let copied = 0;
+  let skipped = 0;
+
+  for (const name of names) {
+    const src = path.join(srcDir, `${name}${ext}`);
+    const dest = path.join(destDir, `${name}${ext}`);
+    const label = `${relDir}/${name}${ext}`;
+
+    if (!fs.existsSync(src)) {
+      console.log(`  Warning: source not found: ${label}`);
+      skipped++; // missing source must block a "clean install" claim, not just warn
+      continue;
+    }
+
+    if (fs.existsSync(dest) && !overwrite) {
+      console.log(`  Skipped (exists): ${label}`);
+      skipped++;
+    } else if (dryRun) {
+      console.log(`  [dry-run] Would create: ${label}`);
+      copied++;
+    } else {
+      fs.copyFileSync(src, dest);
+      console.log(`  Created: ${label}`);
+      copied++;
+    }
+  }
+
+  return { copied, skipped };
+}
+
 function getPackageRoot() {
   // When installed via npm, __dirname is node_modules/github-delivery-os/src
   const possibleRoots = [
@@ -112,6 +175,7 @@ function runInstall(options) {
     targetDir = '.',
     withTemplates = false,
     withLabels = false,
+    withSkill = false,
     overwrite = false,
     dryRun = false,
   } = options;
@@ -119,6 +183,8 @@ function runInstall(options) {
   const pkgRoot = getPackageRoot();
   const workflowsSrc = path.join(pkgRoot, '.github', 'workflows');
   const templatesSrc = path.join(pkgRoot, '.github', 'ISSUE_TEMPLATE');
+  const scriptsSrc = path.join(pkgRoot, '.github', 'scripts');
+  const skillSrc = path.join(pkgRoot, SKILL_REL_PATH);
   const targetAbs = path.resolve(process.cwd(), targetDir);
 
   console.log('=== GitHub Delivery Operating System ===');
@@ -140,39 +206,42 @@ function runInstall(options) {
   // Ensure target structure
   const workflowsDest = path.join(targetAbs, '.github', 'workflows');
   const templatesDest = path.join(targetAbs, '.github', 'ISSUE_TEMPLATE');
+  const scriptsDest = path.join(targetAbs, '.github', 'scripts');
 
   if (!dryRun) {
     fs.mkdirSync(workflowsDest, { recursive: true });
     fs.mkdirSync(templatesDest, { recursive: true });
+    fs.mkdirSync(scriptsDest, { recursive: true });
   }
 
   let workflowsCopied = 0;
   let templatesCopied = 0;
-  let workflowsSkipped = 0;
-  let templatesSkipped = 0;
+  let scriptsCopied = 0;
+  let skillCopied = 0;
+  let workflowsSkipped;
+  let scriptsSkipped;
+
+  // Copy workflows (always on — not optional)
+  ({ copied: workflowsCopied, skipped: workflowsSkipped } = copyManagedFiles(
+    WORKFLOWS,
+    '.yml',
+    workflowsSrc,
+    workflowsDest,
+    { overwrite, dryRun, relDir: '.github/workflows' }
+  ));
+
+  // Copy the scripts the workflows above require() at runtime — required,
+  // not optional, so (unlike templates/skill) this always runs too.
+  ({ copied: scriptsCopied, skipped: scriptsSkipped } = copyManagedFiles(
+    SCRIPTS,
+    '.js',
+    scriptsSrc,
+    scriptsDest,
+    { overwrite, dryRun, relDir: '.github/scripts' }
+  ));
 
-  // Copy workflows
-  for (const wf of WORKFLOWS) {
-    const src = path.join(workflowsSrc, `${wf}.yml`);
-    const dest = path.join(workflowsDest, `${wf}.yml`);
-
-    if (!fs.existsSync(src)) {
-      console.log(`  Warning: source not found: ${wf}.yml`);
-      continue;
-    }
-
-    if (fs.existsSync(dest) && !overwrite) {
-      console.log(`  Skipped (exists): ${wf}.yml`);
-      workflowsSkipped++;
-    } else if (dryRun) {
-      console.log(`  [dry-run] Would create: ${wf}.yml`);
-      workflowsCopied++;
-    } else {
-      fs.copyFileSync(src, dest);
-      console.log(`  Created: ${wf}.yml`);
-      workflowsCopied++;
-    }
-  }
+  let templatesSkipped = 0;
+  let skillSkipped = 0;
 
   // Copy templates
   if (withTemplates && fs.existsSync(templatesSrc)) {
@@ -197,6 +266,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 = '';
@@ -259,12 +347,28 @@ 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);
+  // drift. Only claim a version when the on-disk files actually match it.
+  //
+  // Two ways this can go wrong, both of which must block the claim:
+  //  1. A skip-mode install left older content on disk for something that
+  //     WAS requested this run (tracked by the *Skipped counters below).
+  //  2. An --overwrite run touches only what was explicitly requested
+  //     (workflows + scripts always; templates/skill only if their flags
+  //     were passed) — templates or skill already on disk from an earlier
+  //     install, but not requested this run, are left untouched and stale,
+  //     even though --overwrite makes every *Skipped counter read 0. Naively
+  //     trusting `overwrite` alone would then claim the whole install is
+  //     current when part of it demonstrably wasn't touched.
+  const templatesPresentButNotTouched =
+    !withTemplates && TEMPLATES.some((t) => fs.existsSync(path.join(templatesDest, t)));
+  const skillPresentButNotTouched = !withSkill && fs.existsSync(skillPath(targetAbs));
+  const cleanInstall =
+    workflowsSkipped === 0 &&
+    templatesSkipped === 0 &&
+    scriptsSkipped === 0 &&
+    skillSkipped === 0 &&
+    !templatesPresentButNotTouched &&
+    !skillPresentButNotTouched;
   if (!dryRun && cleanInstall) {
     const pkgVersion = require(path.join(pkgRoot, 'package.json')).version;
     writeManifest(targetAbs, pkgVersion);
@@ -273,18 +377,29 @@ function runInstall(options) {
   // Summary
   console.log('');
   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.');
+    if (templatesPresentButNotTouched || skillPresentButNotTouched) {
+      console.log('  Note: previously-installed templates and/or the Claude Code skill exist');
+      console.log('  on disk but were not requested this run, so the recorded Delivery OS');
+      console.log('  version was not updated. Re-run with --overwrite plus --with-templates');
+      console.log('  and/or --with-skill to bring everything (and the recorded version) in sync.');
+    } else {
+      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 || labelsCreated > 0) {
+  if (workflowsCopied > 0 || templatesCopied > 0 || scriptsCopied > 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 (scriptsCopied > 0) console.log(`Would install ${scriptsCopied} supporting script(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 (scriptsCopied > 0) console.log(`Installed ${scriptsCopied} supporting script(s).`);
+      if (skillCopied > 0) console.log('Added the Claude Code delivery-ops skill.');
       if (labelsCreated > 0) console.log(`Created ${labelsCreated} label(s).`);
     }
     console.log('');
@@ -296,8 +411,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.');
@@ -338,8 +459,20 @@ async function runStatus(options) {
   const installedTemplates = TEMPLATES.filter((t) =>
     fs.existsSync(path.join(templatesDest, t))
   );
+  const skillInstalled = fs.existsSync(skillPath(targetAbs));
+
+  // A workflow can be present while the script it require()s at runtime is
+  // not — e.g. an install from before this check existed, or a manual
+  // partial copy. That workflow will fail (MODULE_NOT_FOUND) the next time
+  // it actually runs, silently, since nothing here executes the workflow
+  // itself to notice.
+  const brokenWorkflows = installedWorkflows.filter((wf) => {
+    const requiredScript = REQUIRED_SCRIPT_BY_WORKFLOW[wf];
+    if (!requiredScript) return false;
+    return !fs.existsSync(path.join(targetAbs, '.github', 'scripts', `${requiredScript}.js`));
+  });
 
-  if (installedWorkflows.length > 0 || installedTemplates.length > 0) {
+  if (installedWorkflows.length > 0 || installedTemplates.length > 0 || skillInstalled) {
     const manifest = readManifest(targetAbs);
     if (manifest && manifest.version) {
       const installedOn = manifest.installedAt ? ` (installed ${manifest.installedAt.slice(0, 10)})` : '';
@@ -370,6 +503,17 @@ async function runStatus(options) {
     installedWorkflows.forEach((wf) => console.log(`  ✓ ${wf}.yml`));
     console.log('');
   }
+
+  if (brokenWorkflows.length > 0) {
+    console.log('⚠️  Broken install detected:');
+    brokenWorkflows.forEach((wf) => {
+      console.log(`  ${wf}.yml requires .github/scripts/${REQUIRED_SCRIPT_BY_WORKFLOW[wf]}.js, which is missing.`);
+    });
+    console.log('  That workflow will fail with MODULE_NOT_FOUND the next time it runs.');
+    console.log('  Fix: npx github-delivery-os@latest install --overwrite .');
+    console.log('');
+  }
+
   if (installedTemplates.length > 0) {
     console.log('Templates:');
     installedTemplates.forEach((t) => console.log(`  ✓ ${t}`));
@@ -383,21 +527,33 @@ async function runStatus(options) {
     console.log('');
   }
 
-  if (installedWorkflows.length === 0 && installedTemplates.length === 0) {
+  if (installedWorkflows.length > 0 || installedTemplates.length > 0 || skillInstalled) {
+    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 && !skillInstalled) {
     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');
+  const scriptsDest = path.join(targetAbs, '.github', 'scripts');
 
   console.log('=== GitHub Delivery Operating System — Uninstall ===');
   console.log(`Target: ${targetAbs}`);
@@ -406,6 +562,7 @@ function runUninstall(options) {
 
   let workflowsRemoved = 0;
   let templatesRemoved = 0;
+  let scriptsRemoved = 0;
 
   for (const wf of WORKFLOWS) {
     const dest = path.join(workflowsDest, `${wf}.yml`);
@@ -420,6 +577,21 @@ function runUninstall(options) {
     }
   }
 
+  // Scripts are a required dependency of the workflows above, not optional,
+  // so (like workflows) they're always removed, not gated behind a flag.
+  for (const name of SCRIPTS) {
+    const dest = path.join(scriptsDest, `${name}.js`);
+    if (fs.existsSync(dest)) {
+      if (dryRun) {
+        console.log(`  [dry-run] Would remove: .github/scripts/${name}.js`);
+      } else {
+        fs.unlinkSync(dest);
+        console.log(`  Removed: .github/scripts/${name}.js`);
+      }
+      scriptsRemoved++;
+    }
+  }
+
   if (withTemplates) {
     for (const t of TEMPLATES) {
       const dest = path.join(templatesDest, t);
@@ -435,11 +607,39 @@ function runUninstall(options) {
     }
   }
 
-  // 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.
+  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 — but only once nothing Delivery-OS-
+  // related actually remains. Templates and the skill are kept by default
+  // (only removed with their own flags), and if they're still on disk, the
+  // manifest's version is still meaningful for them — deleting it would make
+  // a later `status` report "unknown version" for files that are, in fact,
+  // still fully present and version-tracked.
+  const anyWorkflowsRemain = WORKFLOWS.some((wf) => fs.existsSync(path.join(workflowsDest, `${wf}.yml`)));
+  const anyTemplatesRemain = TEMPLATES.some((t) => fs.existsSync(path.join(templatesDest, t)));
+  // Scripts are removed unconditionally just above, so this is normally
+  // always false by the time we get here — included anyway for the same
+  // reason the other three are checked explicitly rather than assumed:
+  // defensive completeness against a future change (e.g. a failed unlink,
+  // or script removal ever becoming flag-gated like templates/skill).
+  const anyScriptsRemain = SCRIPTS.some((name) => fs.existsSync(path.join(scriptsDest, `${name}.js`)));
+  const skillRemains = fs.existsSync(skillPath(targetAbs));
+  const nothingLeft = !anyWorkflowsRemain && !anyTemplatesRemain && !anyScriptsRemain && !skillRemains;
+
   const manifestDest = manifestPath(targetAbs);
-  if (fs.existsSync(manifestDest)) {
+  if (nothingLeft && fs.existsSync(manifestDest)) {
     if (dryRun) {
       console.log('  [dry-run] Would remove: delivery-os.json');
     } else {
@@ -449,14 +649,22 @@ function runUninstall(options) {
   }
 
   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.');
+      }
+      if (!nothingLeft) {
+        console.log('delivery-os.json was kept — something Delivery-OS-related is still on disk.');
+      }
     }
   } else {
     console.log('No Delivery OS files found to remove.');
@@ -470,5 +678,16 @@ module.exports = {
   runStatus,
   runUninstall,
   // Exposed for tests only — not part of the CLI's public API.
-  __test__: { manifestPath, readManifest, writeManifest, fetchLatestVersion, WORKFLOWS, TEMPLATES },
+  __test__: {
+    manifestPath,
+    readManifest,
+    writeManifest,
+    fetchLatestVersion,
+    skillPath,
+    SKILL_REL_PATH,
+    WORKFLOWS,
+    TEMPLATES,
+    SCRIPTS,
+    REQUIRED_SCRIPT_BY_WORKFLOW,
+  },
 };

package/.github/workflows/ci.yml

@@ -1,23 +0,0 @@
-name: CI
-
-on:
-  push:
-    branches: [main]
-  pull_request:
-
-jobs:
-  test:
-    runs-on: ubuntu-latest
-    steps:
-      - uses: actions/checkout@v6
-
-      - name: Set up Node.js
-        uses: actions/setup-node@v4
-        with:
-          node-version: '20'
-
-      - name: Install dependencies
-        run: npm ci
-
-      - name: Run tests
-        run: npm test

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,38 +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: Set up Node.js
-        uses: actions/setup-node@v4
-        with:
-          node-version: '20'
-
-      - name: Install dependencies
-        run: npm ci
-
-      - name: Run tests
-        run: npm test
-
-      - name: Create Release
-        uses: softprops/action-gh-release@v2
-        with:
-          generate_release_notes: true
-        env:
-          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}