github-delivery-os 1.2.1 → 1.2.2

package/.github/scripts/package.json

@@ -0,0 +1,3 @@
+{
+  "type": "commonjs"
+}

package/README.md

@@ -63,15 +63,15 @@ npx github-delivery-os uninstall --dry-run .      # Preview (no changes)
 
 **What gets installed:**
 
-| Workflow | Purpose |
-|----------|---------|
-| `sprint-child-creator` | Creates child issues when a sprint (title `SPRINT -`) is opened |
-| `auto-close-sprint` | Burn-down, sprint health, auto-close at 100% |
-| `notify-release-approver` | Pings approver when production release issue opens |
-| `authorize-deployment` | Dual approval (release approver + QA) |
-| `auto-assign-qa` | Assigns QA team to `qa` / `qa-request` issues |
-| `telegram-issues` | Telegram alerts for bugs, QA, sprints, releases |
-| `setup-labels` | One-time workflow to create required labels |
+| Workflow | Trigger | Purpose |
+|----------|---------|---------|
+| `sprint-child-creator` | Issue opened, title contains `SPRINT -` | Parses "Sprint Features (One Per Line)" and creates one child issue per line, each linked back with `Parent Sprint: #N` |
+| `auto-close-sprint` | Issue closed, body contains `Parent Sprint` | Recomputes the parent sprint's burn-down/health and rewrites its status section; auto-closes the sprint at 100% |
+| `notify-release-approver` | Issue opened, labeled `production` | Comments on the issue tagging the repo's `RELEASE_APPROVER` |
+| `authorize-deployment` | Comment posted on a `production`-labeled issue | Checks the commenter and keyword against `RELEASE_APPROVER`/`QA_APPROVER`; once both approve, adds `ready-for-deploy` |
+| `auto-assign-qa` | Issue opened/labeled `qa` or `qa-request` | Assigns the repo's configured `QA_ASSIGNEES` |
+| `telegram-issues` | Issue/comment/PR events | Sends a Telegram alert if `TELEGRAM_BOT_TOKEN`/`TELEGRAM_CHAT_ID` are configured |
+| `setup-labels` | Manual (`workflow_dispatch`) | One-time run that creates all labels Delivery OS needs |
 
 Workflows and templates are **copied directly** into your repo. No `workflow_call` or external references.
 
@@ -104,6 +104,230 @@ When you open an issue using the **Sprint Planning** template with a title like
 
 ---
 
+## Operating From Claude Code (`--with-skill`)
+
+Installing with `--with-skill` drops a `.claude/skills/delivery-ops/SKILL.md` skill into the repo, scoped to *this* repo's Delivery OS install. It lets anyone using [Claude Code](https://claude.com/claude-code) drive the workflows above by asking in plain language — e.g. "create a sprint for the checkout redesign" — instead of hand-building `gh issue create` calls and remembering each template's exact field names.
+
+Before doing anything, it checks the target repo: confirms Delivery OS is actually installed, that `Setup Labels` has been run, and that `RELEASE_APPROVER` / `QA_APPROVER` / `QA_ASSIGNEES` are configured — flagging (or offering to fix) gaps instead of silently creating an issue that does nothing. It also always shows the constructed title/body/labels or comment text for confirmation before creating or posting for real, since these are visible actions in the repo's activity, not a local preview.
+
+### Create a sprint
+1. Ask: *"Create a sprint called Sprint 14 for \<goal>, running \<start> to \<end>, with features: \<one per line>"*
+2. It opens an issue titled `SPRINT - Sprint 14`, labeled `sprint` + `planning`, with `### Sprint Name` / `Start` / `End` / `Goal` / `Features (One Per Line)` / `Approved` fields filled in.
+3. On open, `sprint-child-creator` splits each feature line into its own child issue, labeled `sprint-active` and linked back with `Parent Sprint: #N`.
+4. Close each child issue as work finishes — that's what advances the burn-down; `auto-close-sprint` recomputes it and rewrites the parent's `## 🚦 Sprint Status` section, auto-closing the sprint at 100%.
+
+### Request a production release
+1. Ask: *"Open a production release for \<project> v1.2.0, sprint #N, summary: \<summary>"*
+2. It opens an issue titled `PRODUCTION RELEASE - <project> - v1.2.0`, labeled `release` + `production` + `approval`, with the sprint reference, version, release summary, QA summary/links, and `Deployment Authorized: No`.
+3. On open, `notify-release-approver` comments tagging the repo's configured `RELEASE_APPROVER`.
+
+### Approve or decline a release
+1. Ask: *"Approve release #N"* or *"Decline release #N — \<reason>"*.
+2. It checks that the currently authenticated `gh` login matches the repo's `RELEASE_APPROVER` — if not, it stops and says so instead of posting a comment that would silently do nothing.
+3. It posts a comment starting with a recognized keyword (`approved`, `ok`, `go ahead` to approve; `declined`, `rejected`, `not approved` to decline) — `authorize-deployment` only reacts to that leading keyword from the exact configured approver. A later comment from the same approver overrides an earlier one.
+
+### Request QA
+1. Ask: *"Open a QA request for \<feature>, related to issue #N, testing \<what/where>"*
+2. It opens an issue titled `QA REQUEST - <feature>`, labeled `qa-request`, with the related task, what to test, environment/build link, and acceptance criteria.
+3. On open, `auto-assign-qa` assigns the repo's configured `QA_ASSIGNEES`.
+
+### Approve QA
+1. Ask: *"Mark QA #N as approved"* (or *"looks good"*).
+2. Same login check as release approval, but against `QA_APPROVER`.
+3. Posts a comment starting with `qa approved`, `approved`, `qa ok`, or `looks good`.
+
+### Report a bug
+1. Ask: *"File a bug: \<one-line summary>, severity \<level>, steps: \<...>"*
+2. It opens an issue titled `[BUG] <summary>`, labeled `bug` + `qa`, with platform, severity, build/version, steps to reproduce, expected vs. actual result, and test environment.
+
+### Track a task
+1. Ask: *"Create a task to \<summary>, owner \<name>, priority P1"*
+2. It opens an issue titled `TASK - <summary>`, labeled `task`, with owner, priority, status, acceptance criteria, and links. (No workflow trigger — this is plain tracking.)
+
+### Check status
+- *"What's the status of issue #N?"* → current labels and latest comments.
+- *"How's Sprint 14 doing?"* → reads the parent issue's `## 🚦 Sprint Status` section (progress %, time elapsed, health, burn-down bar).
+- *"What releases are waiting on approval?"* / *"What sprints are active?"* / *"What QA requests are open?"* → lists issues by label (`production`, `sprint`, `qa-request`) so you don't need an issue number in hand.
+
+See [How To](docs/how-to.md) for the underlying workflows this drives, field by field.
+
+### Example: filing a bug and a task, step by step
+
+Worked against `jkaweesi22/klero`, a repo with Delivery OS installed. The bug part of this was actually run — that issue really exists at [jkaweesi22/klero#1](https://github.com/jkaweesi22/klero/issues/1); the task part follows the identical steps but wasn't actually created, shown for the field shape only.
+
+**Filing the bug:**
+
+1. In Claude Code, inside (or pointed at, via `--repo`) the target repo, describe the bug in plain language:
+   > *File a bug on jkaweesi22/klero — the order request form submits with an empty phone number, severity high. Steps: fill in the form, leave phone blank, submit. Expected: should block submission. Actual: submits anyway, so there's no way to contact the customer. Tested on Chrome, desktop, production.*
+2. Claude pre-flights the repo — confirms Delivery OS is installed and the `bug`/`qa` labels exist.
+3. Claude shows the exact issue it's about to create before doing anything:
+   - Title: `[BUG] Order request form submits with empty phone number`
+   - Labels: `bug`, `qa`
+   - Body, field by field: `Platform(s) Affected` → Web, `Severity` → High, `Build / Version` → main (as deployed), `Bug Summary`, `Steps to Reproduce` (numbered), `Expected Result`, `Actual Result`, `Test Environment` → Chrome, desktop, production.
+4. Confirm ("yes") when asked to create it.
+5. Claude runs `gh issue create` and reports back the issue — [jkaweesi22/klero#1](https://github.com/jkaweesi22/klero/issues/1). Nothing else happens automatically; bug reports don't trigger a workflow, they're just labeled and tracked.
+
+**Filing the follow-up task:**
+
+1. Ask Claude to turn the bug into tracked work, referencing the bug's issue number:
+   > *Create a task to add phone number validation to the order form, owner @jkaweesi22, priority P1, status Backlog, acceptance: form blocks submission until a valid phone number is entered. Link it to #1.*
+2. Claude shows the constructed issue:
+   - Title: `TASK - Add phone number validation to order form`
+   - Labels: `task`
+   - Body: `Task Summary`, `Description` (references #1), `Owner` → @jkaweesi22, `Priority` → P1 - High, `Status` → Backlog, `Acceptance Criteria`, `Artifacts / Links` → Related bug: #1.
+3. Confirm ("yes") to create it.
+4. Claude runs `gh issue create`. Same as the bug — no workflow trigger, just labeled and tracked, now linked back to the bug it addresses.
+
+### Full example: shipping a feature end-to-end
+
+A realistic Claude Code session, run from inside the consumer repo (the skill defaults to it since it was installed with `--with-skill` there). `RELEASE_APPROVER`, `QA_APPROVER`, and `QA_ASSIGNEES` are already configured.
+
+```
+You: Create a sprint called "Sprint 14 - Checkout Revamp", running 2026-09-16 to
+     2026-09-30, goal is shipping the new checkout flow, features:
+     - Redesign cart summary
+     - Add saved payment methods
+     - Fix tax rounding bug
+
+Claude: This will create an issue in acme/storefront:
+
+          Title:  SPRINT - Sprint 14 - Checkout Revamp
+          Labels: sprint, planning
+          Body:
+            ### Sprint Name
+            Sprint 14 - Checkout Revamp
+            ### Sprint Start
+            2026-09-16
+            ### Sprint End
+            2026-09-30
+            ### Sprint Goal
+            Ship the new checkout flow
+            ### Sprint Features (One Per Line)
+            Redesign cart summary
+            Add saved payment methods
+            Fix tax rounding bug
+            ### Sprint Approved
+            Pending
+
+        Create this issue?
+
+You: yes
+
+Claude: Created #52. sprint-child-creator will fire on open and create one child
+        issue per feature — #53 "Redesign cart summary", #54 "Add saved payment
+        methods", #55 "Fix tax rounding bug" — each labeled sprint-active and
+        linked back with "Parent Sprint: #52".
+
+  [ ... engineers do the work, close #53 and #54 as they land ... ]
+
+You: How's Sprint 14 doing?
+
+Claude: Reading #52... ## 🚦 Sprint Status: 67% complete (2/3 closed), 20% of
+        sprint time elapsed, 🟢 on track.
+
+You: QA found a rounding issue in the tax calc — file a bug. Severity high,
+     repros on checkout with 3+ items, expected total matches line items,
+     actual is off by $0.01.
+
+Claude: This will create an issue in acme/storefront:
+
+          Title:  [BUG] Tax rounding off by $0.01 with 3+ items
+          Labels: bug, qa
+          Body: (Platform, Severity: High, Steps to Reproduce, Expected vs.
+                 Actual Result, Test Environment filled in from what you said)
+
+        Create this issue?
+
+You: yes
+
+Claude: Created #56.
+
+  [ ... #55 fixed, referencing #56 ... ]
+
+You: Open a QA request for the tax rounding fix, related to #55, test on
+     staging, acceptance: totals match to the cent for carts of 1-10 items.
+
+Claude: This will create an issue in acme/storefront:
+
+          Title:  QA REQUEST - Tax rounding fix
+          Labels: qa-request
+          Body: (Related Sprint Task Issue #55, What to Test, Environment +
+                 Build Link: staging, Acceptance Criteria filled in)
+
+        Create this issue?
+
+You: yes
+
+Claude: Created #57. auto-assign-qa will assign it to the configured
+        QA_ASSIGNEES.
+
+  [ ... QA tests it, comes back clean ... ]
+
+You: Mark QA #57 as approved, looks good.
+
+Claude: Checking gh auth status... authenticated as jane-qa, which matches this
+        repo's QA_APPROVER. Posting:
+
+          "looks good — verified on staging, totals match to the cent"
+
+        on #57.
+
+You: yes, post it
+
+Claude: Posted. Now close #55 to update the sprint burn-down?
+
+You: yes
+
+Claude: Closed #55. Sprint 14 is now 100% complete — auto-close-sprint closed
+        #52 and posted a completion comment.
+
+You: Open a production release for storefront v2.4.1, sprint #52, summary
+     "checkout revamp: new cart summary, saved payment methods, tax rounding
+     fix", QA evidence: #57.
+
+Claude: This will create an issue in acme/storefront:
+
+          Title:  PRODUCTION RELEASE - storefront - v2.4.1
+          Labels: release, production, approval
+          Body:
+            ### Sprint Reference (Sprint Planning Issue #)
+            #52
+            ### Version / Build Number
+            v2.4.1
+            ### Release Summary
+            Checkout revamp: new cart summary, saved payment methods, tax
+            rounding fix
+            ### QA Summary + Evidence Links
+            #57
+            ### Overall QA Recommendation
+            Approve for Production
+            ### Deployment Authorized
+            No
+
+        Create this issue?
+
+You: yes
+
+Claude: Created #58. notify-release-approver posted a comment tagging this
+        repo's RELEASE_APPROVER (john-lead).
+
+  [ ... some time later, as john-lead ... ]
+
+You: Approve release #58.
+
+Claude: Checking gh auth status... authenticated as john-lead, which matches
+        RELEASE_APPROVER. Posting "approved" on #58.
+
+You: yes
+
+Claude: Posted. authorize-deployment will add ready-for-deploy once both
+        approvers (release + QA) have a qualifying comment on record.
+```
+
+Each `yes` above is a real confirmation gate — Claude shows the exact issue/comment content before it creates or posts anything, since it's a visible action in the repo.
+
+---
+
 ## Documentation
 
 | Document | Description |

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "github-delivery-os",
-  "version": "1.2.1",
+  "version": "1.2.2",
   "description": "A GitHub-native Delivery Governance Framework for structured sprint execution, QA review, and collaborative production release control.",
   "main": "src/install.js",
   "bin": {
@@ -48,6 +48,7 @@
     ".github/scripts/authorize-deployment-verdict.js",
     ".github/scripts/auto-close-sprint.js",
     ".github/scripts/sprint-child-creator.js",
+    ".github/scripts/package.json",
     ".github/ISSUE_TEMPLATE",
     ".claude/skills/delivery-ops"
   ],

package/src/install.js

@@ -27,6 +27,17 @@ const WORKFLOWS = [
 // them explicitly in package.json's "files".
 const SCRIPTS = ['authorize-deployment-verdict', 'auto-close-sprint', 'sprint-child-creator'];
 
+// These scripts are CommonJS (`require`/`module.exports`). Node picks CJS vs.
+// ESM per-file by walking up to the nearest package.json — so a consumer repo
+// whose own root package.json has `"type": "module"` would otherwise make
+// Node treat these .js files as ES modules too, breaking `require()` at
+// runtime with "ReferenceError: module is not defined in ES module scope".
+// This override pins the .github/scripts subtree to CommonJS regardless of
+// the consumer's own type field. Always installed alongside SCRIPTS, same as
+// SCRIPTS is alongside WORKFLOWS — not itself require()'d by anything, but a
+// required dependency of every script that is.
+const SCRIPTS_PACKAGE_JSON = 'package.json';
+
 // 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).
@@ -240,6 +251,21 @@ function runInstall(options) {
     { overwrite, dryRun, relDir: '.github/scripts' }
   ));
 
+  // The CommonJS-pinning package.json (see SCRIPTS_PACKAGE_JSON above) —
+  // always installed alongside SCRIPTS, via the same helper, counted the
+  // same way (mirrors how scripts/install.sh reuses copy_managed_files for
+  // this exact file rather than hand-rolling the copy).
+  const { name: scriptsPkgName, ext: scriptsPkgExt } = path.parse(SCRIPTS_PACKAGE_JSON);
+  const scriptsPkgResult = copyManagedFiles(
+    [scriptsPkgName],
+    scriptsPkgExt,
+    scriptsSrc,
+    scriptsDest,
+    { overwrite, dryRun, relDir: '.github/scripts' }
+  );
+  scriptsCopied += scriptsPkgResult.copied;
+  scriptsSkipped += scriptsPkgResult.skipped;
+
   let templatesSkipped = 0;
   let skillSkipped = 0;
 
@@ -472,6 +498,19 @@ async function runStatus(options) {
     return !fs.existsSync(path.join(targetAbs, '.github', 'scripts', `${requiredScript}.js`));
   });
 
+  // A script can be present while the CommonJS-pinning package.json (see
+  // SCRIPTS_PACKAGE_JSON in src/install.js) is missing — e.g. an install from
+  // before this fix existed. That's fine in a repo whose own package.json
+  // has no "type" field or "type": "commonjs", but breaks with
+  // "ReferenceError: module is not defined in ES module scope" the moment
+  // the consumer repo's package.json has "type": "module". Flagged
+  // separately from brokenWorkflows since it's silent until that condition
+  // is hit, not an immediate break.
+  const scriptsRequiringPkgJson = installedWorkflows.some((wf) => REQUIRED_SCRIPT_BY_WORKFLOW[wf]);
+  const scriptsPkgJsonMissing =
+    scriptsRequiringPkgJson &&
+    !fs.existsSync(path.join(targetAbs, '.github', 'scripts', SCRIPTS_PACKAGE_JSON));
+
   if (installedWorkflows.length > 0 || installedTemplates.length > 0 || skillInstalled) {
     const manifest = readManifest(targetAbs);
     if (manifest && manifest.version) {
@@ -514,6 +553,15 @@ async function runStatus(options) {
     console.log('');
   }
 
+  if (scriptsPkgJsonMissing) {
+    console.log(`⚠️  .github/scripts/${SCRIPTS_PACKAGE_JSON} is missing.`);
+    console.log('  If this repo\'s own package.json has "type": "module", every workflow that');
+    console.log('  require()s a script under .github/scripts will fail with "module is not');
+    console.log('  defined in ES module scope" 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}`));
@@ -592,6 +640,19 @@ function runUninstall(options) {
     }
   }
 
+  // The CommonJS-pinning package.json travels with SCRIPTS — same
+  // unconditional removal.
+  const scriptsPkgDest = path.join(scriptsDest, SCRIPTS_PACKAGE_JSON);
+  if (fs.existsSync(scriptsPkgDest)) {
+    if (dryRun) {
+      console.log(`  [dry-run] Would remove: .github/scripts/${SCRIPTS_PACKAGE_JSON}`);
+    } else {
+      fs.unlinkSync(scriptsPkgDest);
+      console.log(`  Removed: .github/scripts/${SCRIPTS_PACKAGE_JSON}`);
+    }
+    scriptsRemoved++;
+  }
+
   if (withTemplates) {
     for (const t of TEMPLATES) {
       const dest = path.join(templatesDest, t);
@@ -634,7 +695,9 @@ function runUninstall(options) {
   // 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 anyScriptsRemain =
+    SCRIPTS.some((name) => fs.existsSync(path.join(scriptsDest, `${name}.js`))) ||
+    fs.existsSync(path.join(scriptsDest, SCRIPTS_PACKAGE_JSON));
   const skillRemains = fs.existsSync(skillPath(targetAbs));
   const nothingLeft = !anyWorkflowsRemain && !anyTemplatesRemain && !anyScriptsRemain && !skillRemains;
 
@@ -688,6 +751,7 @@ module.exports = {
     WORKFLOWS,
     TEMPLATES,
     SCRIPTS,
+    SCRIPTS_PACKAGE_JSON,
     REQUIRED_SCRIPT_BY_WORKFLOW,
   },
 };