Revival generator: reusable workflow opens tracking issue + phase sub-issues in the module repo

.github/workflows/revival-start.yml

@@ -0,0 +1,71 @@
+# Reusable workflow: start a module revival.
+#
+# Call it from the module repo so the issues land there, where contributors look.
+# Drop this caller into the module repo as .github/workflows/revival-start.yml, then run it
+# from the Actions tab (or `gh workflow run revival-start.yml -f steward=<login>`):
+#
+#   name: Start module revival
+#   on:
+#     workflow_dispatch:
+#       inputs:
+#         steward:
+#           description: "GitHub login of the Steward"
+#           required: false
+#   permissions:
+#     issues: write
+#     contents: read
+#   jobs:
+#     start:
+#       uses: PowerShellOrg/.github/.github/workflows/revival-start.yml@main
+#       with:
+#         steward: ${{ inputs.steward }}
+#
+# Opens one "[REVIVAL] <Module>" tracking issue plus six phase sub-issues from
+# docs/revival/*.md in PowerShellOrg/.github. Idempotent: re-running finds the existing
+# tracking issue and stops. Runs on the caller's GITHUB_TOKEN; no secrets.
+
+name: Start module revival (reusable)
+
+on:
+  workflow_call:
+    inputs:
+      module:
+        description: "Module name for titles. Defaults to the calling repo's name."
+        type: string
+        required: false
+      steward:
+        description: "GitHub login of the Steward (assigned to every issue)"
+        type: string
+        required: false
+      source_ref:
+        description: "Branch or tag of PowerShellOrg/.github to read docs/revival from"
+        type: string
+        required: false
+        default: main
+    outputs:
+      tracking_issue:
+        description: "Number of the tracking issue (new or existing)"
+        value: ${{ jobs.create.outputs.tracking_issue }}
+
+permissions:
+  issues: write
+  contents: read
+
+jobs:
+  create:
+    runs-on: ubuntu-latest
+    outputs:
+      tracking_issue: ${{ steps.run.outputs.tracking_issue }}
+    steps:
+      - uses: actions/checkout@v5
+        with:
+          repository: PowerShellOrg/.github
+          ref: ${{ inputs.source_ref }}
+      - id: run
+        uses: actions/github-script@v8
+        env:
+          INPUTS: ${{ toJSON(inputs) }}
+        with:
+          script: |
+            const run = require('./scripts/create-revival.js');
+            await run({ github, context, core, inputs: JSON.parse(process.env.INPUTS) });

docs/revival/labels.yml

@@ -0,0 +1,79 @@
+# PowerShellOrg module-revival label manifest
+# Lives at PowerShellOrg/.github/docs/revival/labels.yml (PR #16). First applied to BuildHelpers 2026-09-17.
+#
+# Convention: colon-space, lowercase. No emoji. No "/", "&", or apostrophes in names —
+# they break label-sync tooling (vscode-powershell carries both "Area-Build & Release"
+# and "Area-Build  Release" from exactly this).
+#
+# One colour per facet. Only priority gets a gradient, and it lives in an Issue Field,
+# not here.
+#
+# NOT in this file, deliberately:
+#   type:     -> native org Issue Types (Task / Bug / Feature) — already enabled
+#   priority: -> org Issue Field "Priority" — Urgent / High / Medium / Low
+#   effort:   -> dropped. Every human-estimated effort facet measured is dead or dying
+#   skill:    -> dropped. Zero of 15 large repos surveyed track it
+
+# ---------------------------------------------------------------------------
+# Discovery — EXACT strings GitHub indexes. Do not prefix, TitleCase, or emoji these.
+# "good first issue" populates the repo Contribute page and feeds GitHub's
+# approachability algorithm. Getting these wrong makes a revival invisible to the
+# contributor funnel it exists to attract.
+# ---------------------------------------------------------------------------
+- name: "good first issue"
+  color: "7057ff"
+  description: "Newcomer-ready: solution explained, code identified, ready to test"
+- name: "help wanted"
+  color: "008672"
+  description: "Maintainer welcomes a PR on this"
+
+# The revival-start workflow creates this if missing; listed so the colour matches.
+- name: "revival"
+  color: "5319e7"
+  description: "Module revival tracking"
+
+# ---------------------------------------------------------------------------
+# area: — what part of the project. Multi-valued. The four below are universal;
+# the Steward adds module-specific ones (see the recipe in the playbook).
+# ---------------------------------------------------------------------------
+- name: "area: build"
+  color: "0052cc"
+  description: "CI, psake, packaging, release pipeline"
+- name: "area: tests"
+  color: "0052cc"
+  description: "Pester tests and test infrastructure"
+- name: "area: docs"
+  color: "0052cc"
+  description: "README, help text, examples, CONTRIBUTING"
+- name: "area: triage"
+  color: "0052cc"
+  description: "Issue and PR triage, backlog cleanup"
+
+# ---------------------------------------------------------------------------
+# status: — transient lifecycle state, often written by bots. Not a taxonomy.
+# ---------------------------------------------------------------------------
+- name: "status: needs-repro"
+  color: "bfc7d1"
+  description: "Awaiting reproduction steps or clarification from the reporter"
+- name: "status: stale"
+  color: "bfc7d1"
+  description: "No recent activity; candidate for closing"
+
+# ---------------------------------------------------------------------------
+# PRUNE — delete these on transfer. Each is superseded, not merely unfashionable.
+#   bug, enhancement       -> native Issue Types (Bug, Feature)
+#   documentation          -> area: docs
+#   duplicate              -> native close reason "Duplicate"
+#   wontfix, invalid       -> native close reason "Not planned"
+#   question               -> GitHub Discussions (the playbook already routes these there)
+# Prune only after checking usage; a label with real history may be worth migrating
+# rather than deleting.
+# ---------------------------------------------------------------------------
+prune:
+  - "bug"
+  - "enhancement"
+  - "documentation"
+  - "duplicate"
+  - "wontfix"
+  - "invalid"
+  - "question"

docs/revival/phase-0.md

@@ -0,0 +1,26 @@
+---
+title: "[REVIVAL] {{module}} - Phase 0: Inventory"
+labels: revival
+type: Task
+role: Steward (PSGallery items: Org Admin)
+---
+
+Reference: [Playbook - Phase 0](https://github.com/PowerShellOrg/.github/blob/main/docs/revival-playbook.md#phase-0-take-inventory-week-1)
+
+## Transfer and access
+
+- [ ] Repo lives at `github.com/PowerShellOrg/{{module}}`
+- [ ] Repo marked `status-incoming`
+- [ ] Steward and maintainers have Write
+- [ ] Branch protection on the default branch
+- [ ] Default branch is `main`
+- [ ] Labels match [`labels.yml`](https://github.com/PowerShellOrg/.github/blob/main/docs/revival/labels.yml)
+
+## PSGallery (Org Admin)
+
+- [ ] Package ownership transferred to the PowerShellOrg PSGallery account
+- [ ] Scoped API key created: `PowerShellOrg-{{module}}-<YYYY-MM>`, 365-day expiry
+- [ ] `PSGALLERY_API_KEY` secret set on the repo
+- [ ] Rotation reminder on the Org Admin's tracking issue
+
+Baseline metrics are in the tracking issue; fill in the PSGallery rows there.

docs/revival/phase-1.md

@@ -0,0 +1,16 @@
+---
+title: "[REVIVAL] {{module}} - Phase 1: Issue triage"
+labels: revival
+type: Task
+role: Steward
+---
+
+Reference: [Playbook - Phase 1](https://github.com/PowerShellOrg/.github/blob/main/docs/revival-playbook.md#phase-1-issue-triage-weeks-1-4)
+(per-issue procedure and comment templates)
+
+Goal: every open issue is typed, acknowledged, and either closed or has a clear next step.
+An issue with no Issue Type is untriaged.
+
+- [ ] Every open issue has an Issue Type
+- [ ] Every open issue is either closed, waiting on the reporter (`status: needs-repro`), or has a next step
+- [ ] Pre-adoption issues with no activity in 2 years are closed with the [stale comment](https://github.com/PowerShellOrg/.github/blob/main/docs/revival-playbook.md#comment-templates)

docs/revival/phase-2.md

@@ -0,0 +1,14 @@
+---
+title: "[REVIVAL] {{module}} - Phase 2: PR triage"
+labels: revival
+type: Task
+role: Steward
+---
+
+Reference: [Playbook - Phase 2](https://github.com/PowerShellOrg/.github/blob/main/docs/revival-playbook.md#phase-2-pr-triage-weeks-1-4-parallel-with-phase-1)
+(decision tree, take-over and close templates)
+
+Goal: no PR sits without a decision. Runs alongside Phase 1.
+
+- [ ] No open PR is older than 30 days without a maintainer comment
+- [ ] Every open PR is merged, closed with a note, or actively under review

docs/revival/phase-3.md

@@ -0,0 +1,51 @@
+---
+title: "[REVIVAL] {{module}} - Phase 3: Build modernization"
+labels: revival
+type: Task
+role: Steward
+---
+
+Reference: [Playbook - Phase 3](https://github.com/PowerShellOrg/.github/blob/main/docs/revival-playbook.md#phase-3-build-modernization-weeks-2-6)
+(standard stack, CI and release YAML)
+
+Goal: the repo builds with the standard stack and CI is green on all platforms.
+Work in order; each step is its own PR.
+
+## 3a Pester
+
+- [ ] Tests exist and use Pester 5
+- [ ] `Invoke-Pester` passes locally
+
+## 3b psake
+
+- [ ] `psakeFile.ps1` defines `Init`, `Clean`, `Build`, `Test`, `Analyze`, `Publish`
+- [ ] `Invoke-psake ?` lists them
+- [ ] `Invoke-psake Test` passes
+
+## 3c PowerShellBuild
+
+- [ ] Build references PowerShellBuild for shared task logic
+- [ ] `Test-ModuleManifest` passes
+- [ ] `Invoke-psake Build` stages a clean module in `output/`
+
+## 3d PSScriptAnalyzer
+
+- [ ] `Invoke-psake Analyze` runs the org ruleset
+- [ ] Zero warnings, or each suppression carries a justifying comment
+
+## 3e CI
+
+- [ ] `.github/workflows/ci.yml` calls the org reusable workflow
+- [ ] CI green on `main` across Win/PS5.1, Win/PS7, Linux/PS7, macOS/PS7
+- [ ] Branch protection requires the CI check
+
+## 3f Release workflow
+
+- [ ] `.github/workflows/release.yml` calls the org reusable workflow
+- [ ] A pre-release tag (`v*-beta.1`) ran the workflow end to end
+
+## 3g Coverage
+
+- [ ] Coverage report generated
+- [ ] Baseline percentage recorded in the tracking issue
+- [ ] Critical public functions have tests; gaps filed as issues

docs/revival/phase-4.md

@@ -0,0 +1,27 @@
+---
+title: "[REVIVAL] {{module}} - Phase 4: First clean release"
+labels: revival
+type: Task
+role: Steward
+---
+
+Reference: [Playbook - Phase 4](https://github.com/PowerShellOrg/.github/blob/main/docs/revival-playbook.md#phase-4-first-clean-release-weeks-4-8)
+(release steps)
+
+Goal: a release under the PowerShellOrg banner you are proud to put your name on.
+
+## Release gate
+
+- [ ] `CHANGELOG.md` covers everything since the last release
+- [ ] Version bumped: patch / minor / major as the changes warrant
+- [ ] CI green and PSScriptAnalyzer clean
+- [ ] Manifest accurate: description, author or org, copyright, tags, URLs
+- [ ] `README.md` current: install, working examples, badges
+- [ ] Open critical bugs fixed or deferred with a written reason
+- [ ] Release PR reviewed by one other maintainer (or Steward if solo)
+
+## Exit
+
+- [ ] Release on PSGallery under PowerShellOrg
+- [ ] GitHub Release with human-readable notes
+- [ ] PSGallery package description says PowerShellOrg

docs/revival/phase-5.md

@@ -0,0 +1,16 @@
+---
+title: "[REVIVAL] {{module}} - Phase 5: Transition to active"
+labels: revival
+type: Task
+role: Steward
+---
+
+Reference: [Playbook - Phase 5](https://github.com/PowerShellOrg/.github/blob/main/docs/revival-playbook.md#phase-5-ongoing-maintenance-and-transition-to-active)
+(cadence table, graduation criteria)
+
+Closing this closes the revival. Ongoing cadence and graduation are in the playbook.
+
+- [ ] Repo marked `status-active` (was `status-incoming`)
+- [ ] `README.md` status badge updated
+- [ ] Org Admin notified
+- [ ] Announced in the Council channel

docs/revival/tracking.md

@@ -0,0 +1,34 @@
+---
+title: "[REVIVAL] {{module}}"
+labels: revival
+type: Task
+---
+
+# {{module}} revival
+
+Tracking issue for bringing **{{module}}** from `status-incoming` to `status-active`.
+Steward: {{steward}}. Repo: {{repo_url}}.
+
+Each phase is a sub-issue below. Phases overlap; pace to the state of the repo, not the
+week numbers. Reference material (comment templates, decision tree, YAML, release steps) is in
+the [Revival Playbook](https://github.com/PowerShellOrg/.github/blob/main/docs/revival-playbook.md).
+
+## Baseline (captured at transfer)
+
+| Metric | Value |
+|---|---|
+| Transfer date | {{today}} |
+| Last commit | {{last_push}} |
+| Open issues | {{open_issues}} |
+| Open PRs | {{open_prs}} |
+| Stars / forks | {{stars}} / {{forks}} |
+| Existing CI | {{ci}} |
+| Last PSGallery release | _fill in: version and date_ |
+| PSGallery downloads | _fill in_ |
+
+These numbers go in the first release announcement.
+
+## Working with an AI assistant
+
+Point it at the playbook and this issue. It drafts; you post. Comments on other people's
+issues, PR closes, and merges are yours to click.