github-delivery-os 1.0.0

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

@@ -0,0 +1,61 @@
+# Run once: Actions → Setup Labels → Run workflow
+# Uses built-in GITHUB_TOKEN — no personal token or gh CLI needed.
+# Labels must match scripts/install.sh --with-labels (same order and colors).
+
+name: Setup Labels
+
+on:
+  workflow_dispatch:
+
+permissions:
+  contents: read
+  issues: write
+
+jobs:
+  create-labels:
+    runs-on: ubuntu-latest
+    permissions:
+      contents: read
+      issues: write
+    steps:
+      - name: Create labels
+        uses: actions/github-script@v7
+        with:
+          script: |
+            const labels = [
+              { name: 'intake', color: '0E8A16' },
+              { name: 'bug', color: 'D93F0B' },
+              { name: 'sprint', color: '1D76DB' },
+              { name: 'sprint-active', color: '1D76DB' },
+              { name: 'planning', color: '5319E7' },
+              { name: 'sprint-planning', color: '5319E7' },
+              { name: 'task', color: '7057FF' },
+              { name: 'qa', color: 'FBCA04' },
+              { name: 'qa-request', color: 'FBCA04' },
+              { name: 'production', color: 'D93F0B' },
+              { name: 'release', color: 'B60205' },
+              { name: 'approval', color: '0E8A16' },
+              { name: 'ready-for-deploy', color: '0E8A16' },
+              { name: 'declined', color: 'B60205' },
+              { name: 'risk', color: 'B60205' },
+            ];
+            let created = 0;
+            for (const { name, color } of labels) {
+              try {
+                await github.rest.issues.createLabel({
+                  owner: context.repo.owner,
+                  repo: context.repo.repo,
+                  name,
+                  color,
+                });
+                console.log(`Created: ${name}`);
+                created++;
+              } catch (e) {
+                if (e.message?.includes('already exists')) {
+                  console.log(`Exists: ${name}`);
+                } else {
+                  console.log(`Failed: ${name} - ${e.message}`);
+                }
+              }
+            }
+            console.log(`\nCreated ${created} label(s).`);

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

@@ -0,0 +1,44 @@
+name: Sprint Child Issue Creator
+
+on:
+  issues:
+    types: [opened]
+
+permissions:
+  issues: write
+
+jobs:
+  create-child-issues:
+    if: contains(github.event.issue.title, 'SPRINT -')
+    runs-on: ubuntu-latest
+    permissions:
+      issues: write
+
+    steps:
+      - name: Create Child Issues
+        uses: actions/github-script@v7
+        with:
+          script: |
+            const issue = context.payload.issue;
+            const body = issue.body || "";
+            const parentNumber = issue.number;
+
+            const featuresMatch = body.match(/### Sprint Features[\s\S]*?(?=###|$)/);
+            if (!featuresMatch) return;
+
+            const features = featuresMatch[0]
+              .split('\n')
+              .map(line => line.trim())
+              .filter(line => line && !line.startsWith('###'));
+
+            const bodyContent = `Parent Sprint: #${parentNumber}\n\n---\n*Created by Delivery OS Sprint Child Creator*`;
+
+            for (const title of features) {
+              await github.rest.issues.create({
+                owner: context.repo.owner,
+                repo: context.repo.repo,
+                title,
+                body: bodyContent,
+                labels: ['sprint-active']
+              });
+            }

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

@@ -0,0 +1,135 @@
+name: GitHub → Telegram Alerts
+
+on:
+  issues:
+    types: [opened, closed, reopened]
+
+  issue_comment:
+    types: [created]
+
+  pull_request:
+    types: [closed]
+
+permissions:
+  contents: read
+
+jobs:
+  notify:
+    runs-on: ubuntu-latest
+    steps:
+      - name: Send Telegram Alert
+        shell: bash
+        env:
+          TELEGRAM_BOT_TOKEN: ${{ secrets.TELEGRAM_BOT_TOKEN }}
+          TELEGRAM_CHAT_ID: ${{ secrets.TELEGRAM_CHAT_ID }}
+          RELEASE_APPROVER: ${{ vars.RELEASE_APPROVER || 'release-approver' }}
+          EVENT_NAME: ${{ github.event_name }}
+          EVENT_ACTION: ${{ github.event.action }}
+          ACTOR: ${{ github.actor }}
+          ISSUE_TITLE: ${{ github.event.issue.title }}
+          ISSUE_URL: ${{ github.event.issue.html_url }}
+          COMMENT_BODY: ${{ github.event.comment.body }}
+          PR_MERGED: ${{ github.event.pull_request.merged }}
+          PR_BASE: ${{ github.event.pull_request.base.ref }}
+          PR_TITLE: ${{ github.event.pull_request.title }}
+          PR_URL: ${{ github.event.pull_request.html_url }}
+        run: |
+          EVENT="${EVENT_NAME}"
+          ACTION="${EVENT_ACTION}"
+          TIMESTAMP=$(TZ=Africa/Nairobi date +"%Y-%m-%d %-I:%M %p EAT")
+          MESSAGE=""
+
+          if [ -z "$TELEGRAM_BOT_TOKEN" ] || [ -z "$TELEGRAM_CHAT_ID" ]; then
+            echo "Telegram secrets not configured. Skipping."
+            exit 0
+          fi
+
+          if [ "$EVENT" = "issues" ]; then
+
+            TITLE="${ISSUE_TITLE}"
+            URL="${ISSUE_URL}"
+
+            if [[ "${{ contains(github.event.issue.labels.*.name || fromJSON('[]'), 'bug') }}" == "true" ]]; then
+              if [ "$ACTION" = "opened" ]; then
+                MESSAGE="🟢🪲 BUG OPENED%0A$TITLE%0A$URL%0A---%0A👤 $ACTOR%0A🕒 $TIMESTAMP"
+              elif [ "$ACTION" = "reopened" ]; then
+                MESSAGE="🟡♻️ BUG REOPENED%0A$TITLE%0A$URL%0A---%0A👤 $ACTOR%0A🕒 $TIMESTAMP"
+              elif [ "$ACTION" = "closed" ]; then
+                MESSAGE="🟣✅ BUG CLOSED%0A$TITLE%0A$URL%0A---%0A👤 $ACTOR%0A🕒 $TIMESTAMP"
+              fi
+            fi
+
+            if [[ "${{ contains(github.event.issue.labels.*.name || fromJSON('[]'), 'qa') }}" == "true" ]] || \
+               [[ "${{ contains(github.event.issue.labels.*.name || fromJSON('[]'), 'qa-request') }}" == "true" ]]; then
+              if [ "$ACTION" = "opened" ]; then
+                MESSAGE="🔵🧪 QA REQUEST OPENED%0A$TITLE%0A$URL%0A---%0A👤 $ACTOR%0A🕒 $TIMESTAMP"
+              elif [ "$ACTION" = "reopened" ]; then
+                MESSAGE="🟠🔁 QA REQUEST REOPENED%0A$TITLE%0A$URL%0A---%0A👤 $ACTOR%0A🕒 $TIMESTAMP"
+              elif [ "$ACTION" = "closed" ]; then
+                MESSAGE="🟢✅ QA REQUEST CLOSED%0A$TITLE%0A$URL%0A---%0A👤 $ACTOR%0A🕒 $TIMESTAMP"
+              fi
+            fi
+
+            if [[ "${{ contains(github.event.issue.labels.*.name || fromJSON('[]'), 'sprint') }}" == "true" ]] && \
+               [[ "${{ contains(github.event.issue.labels.*.name || fromJSON('[]'), 'planning') }}" == "true" ]]; then
+              if [ "$ACTION" = "opened" ]; then
+                MESSAGE="🟣📋 SPRINT CREATED%0A$TITLE%0A$URL%0A---%0A👤 $ACTOR%0A🕒 $TIMESTAMP"
+              fi
+            fi
+
+            if [[ "${{ 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
+                MESSAGE="🟢✅ SPRINT TASK COMPLETED%0A$TITLE%0A$URL%0A---%0A👤 $ACTOR%0A🕒 $TIMESTAMP"
+              fi
+            fi
+
+            if [[ "${{ contains(github.event.issue.labels.*.name || fromJSON('[]'), 'production') }}" == "true" ]]; then
+              if [ "$ACTION" = "opened" ]; then
+                MESSAGE="🚀📦 PRODUCTION RELEASE CREATED%0A$TITLE%0A$URL%0A---%0A👤 $ACTOR%0A🕒 $TIMESTAMP"
+              elif [ "$ACTION" = "closed" ]; then
+                MESSAGE="🟣🚀 RELEASE CLOSED%0A$TITLE%0A$URL%0A---%0A👤 $ACTOR%0A🕒 $TIMESTAMP"
+              fi
+            fi
+          fi
+
+          if [ "$EVENT" = "issue_comment" ]; then
+
+            TITLE="${ISSUE_TITLE}"
+            URL="${ISSUE_URL}"
+            COMMENT=$(echo "$COMMENT_BODY" | head -c 300)
+
+            if [[ "$ACTOR" == "$RELEASE_APPROVER" ]] && echo "$COMMENT_BODY" | grep -iq "declined\|reject\|not approved"; then
+              MESSAGE="🔴🛑 RELEASE DECLINED%0A$TITLE%0A$URL%0A---%0A👤 $ACTOR%0A🕒 $TIMESTAMP"
+
+            elif [[ "$ACTOR" == "$RELEASE_APPROVER" ]] && echo "$COMMENT_BODY" | grep -iq "^approved"; then
+              MESSAGE="🟢🛡️ RELEASE APPROVED%0A$TITLE%0A$URL%0A---%0A👤 $ACTOR%0A🕒 $TIMESTAMP"
+
+            elif [[ "${{ contains(github.event.issue.labels.*.name || fromJSON('[]'), 'bug') }}" == "true" ]]; then
+              MESSAGE="💬🪲 BUG COMMENT%0A$TITLE%0A$URL%0A---%0A$COMMENT%0A---%0A👤 $ACTOR%0A🕒 $TIMESTAMP"
+
+            elif [[ "${{ contains(github.event.issue.labels.*.name || fromJSON('[]'), 'qa') }}" == "true" ]] || \
+                 [[ "${{ contains(github.event.issue.labels.*.name || fromJSON('[]'), 'qa-request') }}" == "true" ]]; then
+              MESSAGE="💬🧪 QA COMMENT%0A$TITLE%0A$URL%0A---%0A$COMMENT%0A---%0A👤 $ACTOR%0A🕒 $TIMESTAMP"
+
+            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
+              MESSAGE="💬🛠️ SPRINT TASK COMMENT%0A$TITLE%0A$URL%0A---%0A$COMMENT%0A---%0A👤 $ACTOR%0A🕒 $TIMESTAMP"
+            fi
+          fi
+
+          if [ "$EVENT" = "pull_request" ]; then
+
+            if [ "$PR_MERGED" = "true" ] && [ "$PR_BASE" = "main" ]; then
+              MESSAGE="🟢🔀 PR MERGED TO MAIN%0A${PR_TITLE}%0A${PR_URL}%0A---%0A👤 $ACTOR%0A🕒 $TIMESTAMP"
+            fi
+          fi
+
+          if [ -n "$MESSAGE" ]; then
+            curl -s -X POST "https://api.telegram.org/bot${TELEGRAM_BOT_TOKEN}/sendMessage" \
+              -d chat_id="${TELEGRAM_CHAT_ID}" \
+              -d text="${MESSAGE}"
+          fi

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 GitHub Delivery Operating System Contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,104 @@
+# GitHub Delivery Operating System
+
+> A GitHub-native Delivery Governance Framework for structured sprint execution, QA review, and collaborative production release control.
+
+---
+
+## 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):
+
+```bash
+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.
+
+**Alternative — clone and run script:**
+
+```bash
+git clone https://github.com/jkaweesi22/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.
+
+**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 |
+
+Workflows and templates are **copied directly** into your repo. No `workflow_call` or external references.
+
+---
+
+## 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.
+
+---
+
+## Documentation
+
+| Document | Description |
+|----------|-------------|
+| **[Landing page & quick start](https://jkaweesi22.github.io/github-delivery-operating-system/)** | Overview, one-command install, features |
+| [Consumer Setup](docs/consumer-setup.md) | Installation, configuration, variables, labels, Telegram, uninstall |
+| [How To](docs/how-to.md) | Create sprints, request releases, approve, report bugs, QA requests |
+| [Architecture](docs/architecture.md) | Workflows, templates, data flow |
+| [Governance](docs/governance.md) | Lifecycle, approval gates, automation rules |
+
+---
+
+## License
+
+MIT License. See [LICENSE](LICENSE) for details.

package/bin/delivery-os.js

@@ -0,0 +1,3 @@
+#!/usr/bin/env node
+
+require('../src/cli');

package/package.json

@@ -0,0 +1,44 @@
+{
+  "name": "github-delivery-os",
+  "version": "1.0.0",
+  "description": "A GitHub-native Delivery Governance Framework for structured sprint execution, QA review, and collaborative production release control.",
+  "main": "src/install.js",
+  "bin": {
+    "delivery-os": "./bin/delivery-os.js"
+  },
+  "scripts": {
+    "install:local": "node bin/delivery-os.js install --with-templates ."
+  },
+  "keywords": [
+    "github",
+    "delivery",
+    "sprint",
+    "qa",
+    "release",
+    "governance",
+    "workflows",
+    "automation"
+  ],
+  "author": "",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/jkaweesi22/github-delivery-operating-system"
+  },
+  "homepage": "https://jkaweesi22.github.io/github-delivery-operating-system/",
+  "bugs": {
+    "url": "https://github.com/jkaweesi22/github-delivery-operating-system/issues"
+  },
+  "files": [
+    "bin",
+    "src",
+    ".github/workflows",
+    ".github/ISSUE_TEMPLATE"
+  ],
+  "engines": {
+    "node": ">=14.0.0"
+  },
+  "dependencies": {
+    "commander": "^11.1.0"
+  }
+}

package/src/cli.js

@@ -0,0 +1,42 @@
+#!/usr/bin/env node
+
+const { program } = require('commander');
+const path = require('path');
+const fs = require('fs');
+const { runInstall } = require('./install');
+
+const pkgPath = path.join(__dirname, '..', 'package.json');
+const version = fs.existsSync(pkgPath)
+  ? require(pkgPath).version
+  : '1.0.0';
+
+program
+  .name('delivery-os')
+  .description('GitHub Delivery Operating System — structured sprint execution, QA review, and production release control')
+  .version(version);
+
+program
+  .command('install [target]')
+  .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('-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')
+  .action((target, options) => {
+    const targetDir = target || '.';
+    runInstall({
+      targetDir,
+      withTemplates: options.withTemplates ?? false,
+      withLabels: options.withLabels ?? false,
+      overwrite: options.overwrite ?? false,
+      dryRun: options.dryRun ?? false,
+    });
+  });
+
+program.parse();
+
+// Show help if no command
+if (!process.argv.slice(2).length) {
+  program.outputHelp();
+}