github-delivery-os 1.3.0 → 1.4.0

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

@@ -1,6 +1,6 @@
 ---
 name: delivery-ops
-description: Operate a repo that has GitHub Delivery OS installed — create sprint/production-release/QA-request/bug issues that actually trigger its automation, comment as an approver in phrasing its workflows recognize, check status (labels, latest comments, burn-down), and run autonomous task tracking (identify tasks/bugs, group them into phases via sprints, maintain a roadmap issue, update status, comment, and close as work progresses). Targets a specific repo via --repo; defaults to the current repo if this skill was installed into it and none is named. Use when asked to create a sprint, request a release, approve/decline a release, check release or sprint status, track/file a task or bug found during work, plan or check a roadmap/phase, or demo/test Delivery OS against a given repo.
+description: Operate a repo that has GitHub Delivery OS installed — create sprint/production-release/QA-request/bug issues that actually trigger its automation, comment as an approver in phrasing its workflows recognize, check status (labels, latest comments, burn-down), run autonomous task tracking (identify tasks/bugs, group them into phases via sprints, maintain a roadmap issue, update status, comment, and close 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. Targets a specific repo via --repo; defaults to the current repo if this skill was installed into it and none is named. Use when asked to create a sprint, request a release, approve/decline a release, check release or sprint status, track/file a task or bug found during work, plan or check a roadmap/phase, break a spec/SRS/feature into phases and tasks, or demo/test Delivery OS against a given repo.
 ---
 
 # Operate Delivery OS
@@ -220,6 +220,25 @@ Close with `gh issue close <number> --repo <owner>/<repo> --comment "<summary of
 
 This only tracks what happens while a Claude session is actively working — nothing reconciles state that changes in the background (a human merges a PR or closes an issue manually with no session running). That gap is tracked as its own deferred item rather than solved here: [Phaneroo/github-delivery-operating-system#12](https://github.com/Phaneroo/github-delivery-operating-system/issues/12). Mitigate it by always reconciling via `gh issue list` at the start of relevant work (see above) rather than trusting anything remembered from earlier.
 
+## Turning a spec or feature into phases and tasks
+
+Given an SRS/PRD, or just a plain-language feature description, break it into a real phase/task breakdown filed as actual issues — not a document, GitHub itself.
+
+**Why this doesn't just lean on `sprint-child-creator`:** that automation (see "Sprint Planning" under "Creating issues") turns a Sprint issue's feature list into child issues automatically, but each child is bare — just a title and `Parent Sprint: #N`, nothing else (`.github/scripts/sprint-child-creator.js` only ever builds that one-line body). A spec implies real per-item detail — acceptance criteria, priority, sometimes an owner — that the auto-created children can't carry. So this recipe works *around* that automation for the actual task content, while still linking into it enough for burn-down tracking to work.
+
+1. **Read the spec and decompose it.** Identify discrete requirements/features. Group them into phases by logical sequencing or dependency, not just document order — each phase becomes one Sprint.
+
+2. **Show the full plan before creating anything.** All phases, each with its Sprint Goal and the requirements that become Task issues under it. This creates many issues at once — always confirm first here, regardless of the "confirm only when unsure" default elsewhere in autonomous tracking; the blast radius is too large to skip.
+
+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.
+   - 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.
+
+For a single small feature that doesn't warrant phase-level sequencing, skip the Sprint wrapper entirely — just file standalone Task issues (cross-referencing each other via "Related: #N" where relevant) using the normal Task recipe.
+
 ## Finding things
 
 When there's no issue number in hand yet:

package/README.md

@@ -90,7 +90,7 @@ Workflows and templates are **copied directly** into your repo. No `workflow_cal
 
 Installing via `npx github-delivery-os` (not the `scripts/install.sh` clone path) also writes `.github/delivery-os.json`, a small manifest recording the installed version — this is what powers the update check in `status`. It's only written when the files it describes are actually current (a fresh install, or `--overwrite`); a skip-mode install over existing files leaves it untouched rather than claiming a version that isn't really on disk. `uninstall` removes it.
 
-With `--with-skill`, a `.claude/skills/delivery-ops/SKILL.md` file is also written — a Claude Code skill scoped to this repo, so anyone working here with Claude Code can create issues that correctly trigger the workflows above, comment as an approver, check status, and 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) 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.
+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.
 
 ---
 
@@ -168,28 +168,28 @@ See [How To](docs/how-to.md) for the underlying workflows this drives, field by
 
 ### 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.
+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 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.*
+   > *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 — [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.
+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 @jkaweesi22, priority P1, status Backlog, acceptance: form blocks submission until a valid phone number is entered. Link it to #1.*
+   > *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 #1), `Owner` → @jkaweesi22, `Priority` → P1 - High, `Status` → Backlog, `Acceptance Criteria`, `Artifacts / Links` → Related bug: #1.
+   - 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.
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "github-delivery-os",
-  "version": "1.3.0",
+  "version": "1.4.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/install.js

@@ -460,6 +460,20 @@ function runInstall(options) {
   console.log('=== Installation complete ===');
 }
 
+// runInstall only records a new manifest version when everything already
+// 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
+// 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']
+    .filter(Boolean)
+    .join(' ');
+  return `npx github-delivery-os@latest install ${flags} .`;
+}
+
 const TEMPLATES = [
   'config.yml',
   'sprint_planning.yml',
@@ -518,7 +532,9 @@ async function runStatus(options) {
       console.log(`Installed version: ${manifest.version}${installedOn}`);
     } else {
       console.log('Installed version: unknown (installed before version tracking was added)');
-      console.log('  Run install with --overwrite to record the current version.');
+      console.log(
+        `  Run: ${buildOverwriteCommand({ hasTemplates: installedTemplates.length > 0, hasSkill: skillInstalled })}`
+      );
     }
 
     if (checkUpdates) {
@@ -529,7 +545,9 @@ async function runStatus(options) {
         console.log(`✓ Up to date (latest is ${latest})`);
       } else if (manifest && manifest.version) {
         console.log(`⬆️  Update available: ${manifest.version} → ${latest}`);
-        console.log('    Run: npx github-delivery-os@latest install --overwrite .');
+        console.log(
+          `    Run: ${buildOverwriteCommand({ hasTemplates: installedTemplates.length > 0, hasSkill: skillInstalled })}`
+        );
       } else {
         console.log(`Latest published version: ${latest}`);
       }
@@ -549,7 +567,9 @@ async function runStatus(options) {
       console.log(`  ${wf}.yml requires .github/scripts/${REQUIRED_SCRIPT_BY_WORKFLOW[wf]}.js, which is missing.`);
     });
     console.log('  That workflow will fail with MODULE_NOT_FOUND the next time it runs.');
-    console.log('  Fix: npx github-delivery-os@latest install --overwrite .');
+    console.log(
+      `  Fix: ${buildOverwriteCommand({ hasTemplates: installedTemplates.length > 0, hasSkill: skillInstalled })}`
+    );
     console.log('');
   }
 
@@ -558,7 +578,9 @@ async function runStatus(options) {
     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(
+      `  Fix: ${buildOverwriteCommand({ hasTemplates: installedTemplates.length > 0, hasSkill: skillInstalled })}`
+    );
     console.log('');
   }
 
@@ -746,6 +768,7 @@ module.exports = {
     readManifest,
     writeManifest,
     fetchLatestVersion,
+    buildOverwriteCommand,
     skillPath,
     SKILL_REL_PATH,
     WORKFLOWS,