github-delivery-os 1.4.0 → 1.5.0

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

@@ -21,7 +21,7 @@ Creating issues and comments in a repo is a visible, outward action — other co
 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.
+- **Labels set up?** `gh label list --repo <owner>/<repo>` — look for `production`, `qa`, `qa-request`, `sprint`, `sprint-child`, `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. (`sprint-active` instead of `sprint-child` means the repo is on a pre-1.5.0 install — still valid, just the older label name.)
 - **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
@@ -32,7 +32,7 @@ Before creating anything that depends on configuration, check the target repo ac
 
 This confirm-first default is for issues created **on explicit request** ("file a bug for this", "create a sprint"). The "Autonomous tracking" section below describes a *different* mode — noticing and filing work on its own during a session — and overrides this default there: act first, confirm after, per its own "Confirm only when unsure" rule. Don't apply both rules to the same action.
 
-**Sprint Planning** — triggers `sprint-child-creator` (one child issue per feature line, each labeled `sprint-active`, on open):
+**Sprint Planning** — triggers `sprint-child-creator` (one child issue per feature line, each labeled `sprint-child` — `sprint-active` on repos installed before 1.5.0 — on open):
 - Title **must contain** the literal string `SPRINT -`, e.g. `SPRINT - Sprint 14`
 - Labels: `sprint`, `planning`
 - Body:
@@ -163,7 +163,7 @@ Closing a sprint task (child) issue is what actually moves the burn-down — cre
 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.
+`auto-close-sprint` fires on close, re-reads every issue whose body contains `Parent Sprint: #<N>` (label-independent — see below), 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.
 
 ## Autonomous tracking (identify → file → update → close)
 
@@ -201,7 +201,7 @@ Don't rely on recalling an issue number from earlier in the conversation, and ne
 gh issue list --repo <owner>/<repo> --state open --search "<keywords from the work>"
 ```
 
-Narrow with `--label task` (or `bug`, `sprint-active`, `qa-request`) only once the category is known and the target repo actually has that label — don't assume `--label task` alone finds everything relevant.
+Narrow with `--label task` (or `bug`, `sprint-child`, `qa-request`) only once the category is known and the target repo actually has that label — don't assume `--label task` alone finds everything relevant. (Older repos may still use `sprint-active` instead of `sprint-child`; check `gh label list` first.)
 
 This is also what makes picking work back up in a *new* session possible without any local memory — the issue list itself is the state.
 
@@ -232,7 +232,7 @@ Given an SRS/PRD, or just a plain-language feature description, break it into a
 
 3. **Per phase, once confirmed:**
    - Create the Sprint Planning issue with the usual recipe (`SPRINT - <phase name>`, dates, goal). "Sprint Features (One Per Line)" is template-required, so it can't be left empty — put one line noting the real breakdown is in linked Task issues (e.g. `See linked Task issues for this phase's breakdown`). This means exactly one bare placeholder child gets auto-created.
-   - File one full Task issue per requirement (the usual Task recipe — Owner, Priority, Acceptance Criteria drawn from the spec text; ask only when the spec genuinely doesn't specify something, like priority). Include `Parent Sprint: #<sprint-number>` in the body (e.g. under Artifacts / Links) — that exact phrase is what `auto-close-sprint` actually scans for (`.github/workflows/auto-close-sprint.yml` filters on body content only, **not** the `sprint-active` label, deliberately — see its own comment on why label-scoping was tried and reverted). Add the `sprint-active` label anyway, for consistency with how the sprint's own children are found (see "Finding things" below), but know it plays no role in the burn-down count.
+   - File one full Task issue per requirement (the usual Task recipe — Owner, Priority, Acceptance Criteria drawn from the spec text; ask only when the spec genuinely doesn't specify something, like priority). Include `Parent Sprint: #<sprint-number>` in the body (e.g. under Artifacts / Links) — that exact phrase is what `auto-close-sprint` actually scans for (`.github/workflows/auto-close-sprint.yml` filters on body content only, **not** the `sprint-child` label, deliberately — see its own comment on why label-scoping was tried and reverted). Add the `sprint-child` label anyway, for consistency with how the sprint's own children are found (see "Finding things" below), but know it plays no role in the burn-down count.
    - Now that the real Task issues exist, close the one placeholder child: `gh issue close <N> --repo <owner>/<repo> --comment "Superseded by full Task issues for this phase — see #.., #.., #.."`, filling in the actual issue numbers just created. Otherwise the placeholder sits in the sprint's burn-down denominator as an item that can never represent real completed work, and the sprint can never legitimately reach 100%.
 
 4. **Report back everything created**, grouped by phase — sprint issue number, task issue numbers, and the placeholder-close.
@@ -245,4 +245,4 @@ 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
+- **A sprint's own children:** `gh issue list --repo <owner>/<repo> --label sprint-child --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. On a repo installed before 1.5.0 (or one that hasn't run the `gh label edit` migration — see `docs/consumer-setup.md`), use `--label sprint-active` instead, or drop `--label` entirely and rely on the body search alone if you're not sure which name applies.

package/.github/workflows/setup-labels.yml

@@ -26,7 +26,7 @@ jobs:
               { name: 'intake', color: '0E8A16' },
               { name: 'bug', color: 'D93F0B' },
               { name: 'sprint', color: '1D76DB' },
-              { name: 'sprint-active', color: '1D76DB' },
+              { name: 'sprint-child', color: '1D76DB', description: "Applied to a sprint's task-breakdown children on open; doesn't change when the sprint closes" },
               { name: 'planning', color: '5319E7' },
               { name: 'sprint-planning', color: '5319E7' },
               { name: 'task', color: '7057FF' },
@@ -40,13 +40,14 @@ jobs:
               { name: 'risk', color: 'B60205' },
             ];
             let created = 0;
-            for (const { name, color } of labels) {
+            for (const { name, color, description } of labels) {
               try {
                 await github.rest.issues.createLabel({
                   owner: context.repo.owner,
                   repo: context.repo.repo,
                   name,
                   color,
+                  ...(description ? { description } : {}),
                 });
                 console.log(`Created: ${name}`);
                 created++;

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

@@ -45,6 +45,6 @@ jobs:
                 repo: context.repo.repo,
                 title,
                 body: bodyContent,
-                labels: ['sprint-active']
+                labels: ['sprint-child']
               });
             }

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

@@ -77,7 +77,10 @@ jobs:
               fi
             fi
 
-            if [[ "${{ contains(github.event.issue.labels.*.name || fromJSON('[]'), 'sprint-active') }}" == "true" ]]; then
+            # sprint-active is the pre-1.5.0 label name; still checked here so
+            # issues created before a repo upgrades don't go silent on close.
+            if [[ "${{ contains(github.event.issue.labels.*.name || fromJSON('[]'), 'sprint-child') }}" == "true" ]] || \
+               [[ "${{ contains(github.event.issue.labels.*.name || fromJSON('[]'), 'sprint-active') }}" == "true" ]]; then
               if [ "$ACTION" = "opened" ]; then
                 MESSAGE="🟡🛠️ SPRINT TASK CREATED%0A$TITLE%0A$URL%0A---%0A👤 $ACTOR%0A🕒 $TIMESTAMP"
               elif [ "$ACTION" = "closed" ]; then
@@ -129,7 +132,8 @@ jobs:
             elif [[ "${{ contains(github.event.issue.labels.*.name || fromJSON('[]'), 'production') }}" == "true" ]]; then
               MESSAGE="💬🚀 RELEASE COMMENT%0A$TITLE%0A$URL%0A---%0A$COMMENT%0A---%0A👤 $ACTOR%0A🕒 $TIMESTAMP"
 
-            elif [[ "${{ contains(github.event.issue.labels.*.name || fromJSON('[]'), 'sprint-active') }}" == "true" ]]; then
+            elif [[ "${{ contains(github.event.issue.labels.*.name || fromJSON('[]'), 'sprint-child') }}" == "true" ]] || \
+                 [[ "${{ contains(github.event.issue.labels.*.name || fromJSON('[]'), 'sprint-active') }}" == "true" ]]; then
               MESSAGE="💬🛠️ SPRINT TASK COMMENT%0A$TITLE%0A$URL%0A---%0A$COMMENT%0A---%0A👤 $ACTOR%0A🕒 $TIMESTAMP"
             fi
           fi

package/README.md

@@ -4,350 +4,32 @@
 
 [![Socket Badge](https://badge.socket.dev/npm/package/github-delivery-os)](https://socket.dev/npm/package/github-delivery-os)
 
----
+Delivery OS embeds structured intake, sprint orchestration, QA governance, and collaborative release gates directly into your GitHub repos — replacing informal coordination (manual approvals, inconsistent sprint tracking, socially enforced releases) without replacing your CI/CD or disrupting how you already work.
 
-## Why This Exists
-
-Engineering teams often rely on informal coordination inside GitHub — manual approvals, inconsistent sprint tracking, reactive QA engagement, and socially enforced production releases.
-
-As teams scale, this creates:
-
-* Delivery ambiguity
-* QA bottlenecks
-* Unclear accountability
-* Release risk
-* Cross-team misalignment
-
-The **GitHub Delivery Operating System (Delivery OS)** embeds structured intake, sprint orchestration, QA governance, and collaborative release gates directly into engineering repositories — without replacing CI/CD pipelines or disrupting developer workflows.
-
----
-
-## Installation
-
-**One command** (recommended):
+## Install
 
 ```bash
 npx github-delivery-os install --with-templates .
 ```
 
-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:**
-
-```bash
-git clone https://github.com/Phaneroo/github-delivery-operating-system
-cd github-delivery-operating-system
-
-# New install or repo with existing workflows — adds only missing files (safe)
-./scripts/install.sh --with-templates /path/to/your-repo
-
-# Also create labels via gh CLI (requires gh auth)
-./scripts/install.sh --with-templates --with-labels /path/to/your-repo
-
-# Update Delivery OS (replace existing) — use --dry-run first to preview
-./scripts/install.sh --with-templates --overwrite /path/to/your-repo
-```
-
-**Note:** By default, existing files are **never overwritten**. Use `--overwrite` only when updating Delivery OS. See [Consumer Setup](docs/consumer-setup.md) for the full command guide.
-
-**Other commands:**
-```bash
-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).
-
-**Command variations — which one to run when:**
-
-| Command | When to run it |
-|---------|-----------------|
-| `npx github-delivery-os install --with-templates .` | First install of Delivery OS in a repo without Claude Code — workflows + issue templates. The default recommendation above. |
-| `npx github-delivery-os install --with-templates --with-labels .` | Same, plus creating all required labels immediately via `gh` CLI — skips the manual "Actions → Setup Labels → Run workflow" step. Needs `gh auth`. |
-| `npx github-delivery-os install --with-templates --with-skill .` | You (or your team) will operate this repo's Delivery OS from [Claude Code](https://claude.com/claude-code) — adds the `delivery-ops` skill so issues/comments/status checks can be done in plain language. |
-| `npx github-delivery-os install --with-templates --with-labels --with-skill .` | Everything at once — the fastest path to a fully working, Claude-Code-operable install in one command. |
-| `npx github-delivery-os install --with-templates --with-skill --dry-run .` | Preview any of the above combinations first — prints what would be created without writing anything. Combine with any other flags. |
-| `npx github-delivery-os install --with-templates --with-skill --overwrite .` | Updating an existing install to the latest release, or retroactively adding `--with-templates`/`--with-skill` to a repo that skipped them originally. **Only** command here that replaces existing files — everything above is always skip-existing/safe. |
-| `npx github-delivery-os status .` | Not sure what's currently installed, whether it's up to date, or whether a workflow is broken (e.g. a required script silently missing). Safe, read-only. |
-| `npx github-delivery-os uninstall --with-templates --with-skill .` | Removing Delivery OS entirely — workflows, scripts, templates, and the skill. Omit either flag to keep that part (both are kept by default). |
-
-**What gets installed:**
-
-| 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.
-
-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, check status, run autonomous task tracking (identify and file tasks/bugs, group them into phases via sprints, maintain a roadmap issue, and update/close issues as work progresses), and turn a spec (SRS/PRD) or a plain-language feature description into a full phase-and-task breakdown filed as real issues, 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)
-
-1. **Create labels:** Actions → Setup Labels → Run workflow
-2. **Configure variables:** Settings → Secrets and variables → Actions → Variables
-   - `RELEASE_APPROVER` — GitHub username
-   - `QA_APPROVER` — GitHub username
-   - `QA_ASSIGNEES` — Comma-separated usernames (e.g. `user1,user2`)
-3. **Optional:** Add `TELEGRAM_BOT_TOKEN` and `TELEGRAM_CHAT_ID` for alerts
-
----
-
-## Sprint Child Creation
-
-When you open an issue using the **Sprint Planning** template with a title like `SPRINT - Sprint 12`:
-
-1. Each line under "Sprint Features (One Per Line)" becomes a child issue
-2. Child issues link back with `Parent Sprint: #N`
-3. Closing child issues updates burn-down; sprint auto-closes at 100%
-
-**Required:** Install with `--with-templates` so the sprint form is available.
-
----
-
-## 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.
-
-It can also run the full lifecycle of a piece of work on its own: notice something worth tracking, classify it, file it, keep its status/comments in sync as work happens, and close it out — acting without asking when the outcome is clear (always posting a one-line notice in the conversation so nothing happens invisibly), and asking first only when the classification or "is this actually done" is genuinely ambiguous. A "phase" is just a Sprint Planning issue; a "roadmap" is one persistent issue Claude keeps rewritten with each phase's state — no new issue types or automation involved.
-
-### 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
-
-Illustrative walkthrough against `acme/storefront`, a repo with Delivery OS installed (same example repo used in the full walkthrough below).
-
-**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 acme/storefront — 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 — e.g. `acme/storefront#42`. 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 @alex, priority P1, status Backlog, acceptance: form blocks submission until a valid phone number is entered. Link it to #42.*
-2. Claude shows the constructed issue:
-   - Title: `TASK - Add phone number validation to order form`
-   - Labels: `task`
-   - Body: `Task Summary`, `Description` (references #42), `Owner` → @alex, `Priority` → P1 - High, `Status` → Backlog, `Acceptance Criteria`, `Artifacts / Links` → Related bug: #42.
-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:
+From your repo root. Add `--with-labels` to create labels via `gh` CLI, `--with-skill` for the [Claude Code](https://claude.com/claude-code) skill, `--dry-run` to preview first. See the [landing page](https://phaneroo.github.io/github-delivery-operating-system/#install) for every flag combination and when to use it, or [Consumer Setup](docs/consumer-setup.md) for the clone-and-run alternative, configuration, and troubleshooting.
 
-          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)
+## What you get
 
-        Create this issue?
+| | |
+|---|---|
+| **Sprint child creation** | One issue per feature line, automatic burn-down, auto-close at 100% |
+| **Dual approval gates** | Release approver + QA sign-off required before deploy |
+| **Auto-assign QA & Telegram alerts** | QA-labeled issues get assigned automatically; optional alerts for bugs, QA, sprints, releases |
+| **Claude Code skill** (`--with-skill`) | Operate it all in plain language — create/comment/check status, autonomous task tracking, and turning a spec into a full phase-and-task breakdown |
 
-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.
-
----
+Full workflow table, quick start, and Claude Code walkthroughs are on the [landing page](https://phaneroo.github.io/github-delivery-operating-system/).
 
 ## Documentation
 
 | Document | Description |
 |----------|-------------|
-| **[Landing page & quick start](https://phaneroo.github.io/github-delivery-operating-system/)** | Overview, one-command install, features |
+| **[Landing page & quick start](https://phaneroo.github.io/github-delivery-operating-system/)** | Overview, full command reference, workflows, Claude Code walkthroughs |
 | [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 |
@@ -355,8 +37,6 @@ Each `yes` above is a real confirmation gate — Claude shows the exact issue/co
 | [Architecture](docs/architecture.md) | Workflows, templates, data flow |
 | [Governance](docs/governance.md) | Lifecycle, approval gates, automation rules |
 
----
-
 ## License
 
 MIT License. See [LICENSE](LICENSE) for details.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "github-delivery-os",
-  "version": "1.4.0",
+  "version": "1.5.0",
   "description": "A GitHub-native Delivery Governance Framework for structured sprint execution, QA review, and collaborative production release control.",
   "main": "src/install.js",
   "bin": {

package/src/cli.js

@@ -1,6 +1,6 @@
 #!/usr/bin/env node
 
-const { program } = require('commander');
+const { program, Option } = require('commander');
 const path = require('path');
 const fs = require('fs');
 const { runInstall, runStatus, runUninstall } = require('./install');
@@ -21,8 +21,12 @@ program
   .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('-u, --update', 'Replace existing workflow/template files with the latest version')
+  .option('--no-update', 'Skip existing files (default)')
+  // Pre-1.5.0 names, kept working silently so existing scripts/CI calling
+  // `install --overwrite` don't break — --update is the documented name now.
+  .addOption(new Option('-o, --overwrite').hideHelp())
+  .addOption(new Option('--no-overwrite').hideHelp())
   .option('-d, --dry-run', 'Show what would happen without changing files')
   .action((target, options) => {
     const targetDir = target || '.';
@@ -31,7 +35,7 @@ program
       withTemplates: options.withTemplates ?? false,
       withLabels: options.withLabels ?? false,
       withSkill: options.withSkill ?? false,
-      overwrite: options.overwrite ?? false,
+      overwrite: options.update ?? options.overwrite ?? false,
       dryRun: options.dryRun ?? false,
     });
   });

package/src/install.js

@@ -51,7 +51,7 @@ const LABELS = [
   ['intake', '0E8A16'],
   ['bug', 'D93F0B'],
   ['sprint', '1D76DB'],
-  ['sprint-active', '1D76DB'],
+  ['sprint-child', '1D76DB', "Applied to a sprint's task-breakdown children on open; doesn't change when the sprint closes"],
   ['planning', '5319E7'],
   ['sprint-planning', '5319E7'],
   ['task', '7057FF'],
@@ -351,9 +351,11 @@ function runInstall(options) {
       }
 
       if (!labelsSkipReason) {
-        for (const [name, color] of LABELS) {
+        for (const [name, color, description] of LABELS) {
           try {
-            execFileSync('gh', ['label', 'create', name, '--color', color], {
+            const args = ['label', 'create', name, '--color', color];
+            if (description) args.push('--description', description);
+            execFileSync('gh', args, {
               cwd: targetAbs,
               stdio: 'pipe',
             });
@@ -406,11 +408,11 @@ function runInstall(options) {
     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('  version was not updated. Re-run with --update 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('  Delivery OS version was not updated. Re-run with --update to sync');
       console.log('  all files (and the recorded version) to the latest release.');
     }
     console.log('');
@@ -453,7 +455,7 @@ function runInstall(options) {
       console.log('Dry run complete. No files were changed.');
     } else {
       console.log('No new files created (existing files were skipped).');
-      console.log('To update: use --overwrite (run with --dry-run first to preview).');
+      console.log('To update: use --update (run with --dry-run first to preview).');
     }
   }
   console.log('');
@@ -464,11 +466,11 @@ function runInstall(options) {
 // installed actually gets touched this run (see the cleanInstall check
 // there) — so a repo with templates and/or the skill already on disk needs
 // --with-templates/--with-skill passed again on an update, not just
-// --overwrite, or the recorded version never advances and `status` keeps
+// --update, or the recorded version never advances and `status` keeps
 // suggesting the same command forever. Build the hint from what's actually
 // on disk so it's never wrong.
-function buildOverwriteCommand({ hasTemplates, hasSkill }) {
-  const flags = [hasTemplates ? '--with-templates' : null, hasSkill ? '--with-skill' : null, '--overwrite']
+function buildUpdateCommand({ hasTemplates, hasSkill }) {
+  const flags = [hasTemplates ? '--with-templates' : null, hasSkill ? '--with-skill' : null, '--update']
     .filter(Boolean)
     .join(' ');
   return `npx github-delivery-os@latest install ${flags} .`;
@@ -533,7 +535,7 @@ async function runStatus(options) {
     } else {
       console.log('Installed version: unknown (installed before version tracking was added)');
       console.log(
-        `  Run: ${buildOverwriteCommand({ hasTemplates: installedTemplates.length > 0, hasSkill: skillInstalled })}`
+        `  Run: ${buildUpdateCommand({ hasTemplates: installedTemplates.length > 0, hasSkill: skillInstalled })}`
       );
     }
 
@@ -546,7 +548,7 @@ async function runStatus(options) {
       } else if (manifest && manifest.version) {
         console.log(`⬆️  Update available: ${manifest.version} → ${latest}`);
         console.log(
-          `    Run: ${buildOverwriteCommand({ hasTemplates: installedTemplates.length > 0, hasSkill: skillInstalled })}`
+          `    Run: ${buildUpdateCommand({ hasTemplates: installedTemplates.length > 0, hasSkill: skillInstalled })}`
         );
       } else {
         console.log(`Latest published version: ${latest}`);
@@ -568,7 +570,7 @@ async function runStatus(options) {
     });
     console.log('  That workflow will fail with MODULE_NOT_FOUND the next time it runs.');
     console.log(
-      `  Fix: ${buildOverwriteCommand({ hasTemplates: installedTemplates.length > 0, hasSkill: skillInstalled })}`
+      `  Fix: ${buildUpdateCommand({ hasTemplates: installedTemplates.length > 0, hasSkill: skillInstalled })}`
     );
     console.log('');
   }
@@ -579,7 +581,7 @@ async function runStatus(options) {
     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: ${buildOverwriteCommand({ hasTemplates: installedTemplates.length > 0, hasSkill: skillInstalled })}`
+      `  Fix: ${buildUpdateCommand({ hasTemplates: installedTemplates.length > 0, hasSkill: skillInstalled })}`
     );
     console.log('');
   }
@@ -768,7 +770,7 @@ module.exports = {
     readManifest,
     writeManifest,
     fetchLatestVersion,
-    buildOverwriteCommand,
+    buildUpdateCommand,
     skillPath,
     SKILL_REL_PATH,
     WORKFLOWS,
@@ -776,5 +778,6 @@ module.exports = {
     SCRIPTS,
     SCRIPTS_PACKAGE_JSON,
     REQUIRED_SCRIPT_BY_WORKFLOW,
+    LABELS,
   },
 };