github-delivery-os 1.2.2 → 1.3.1

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, and check status (labels, latest comments, burn-down). 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, 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), 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.
 ---
 
 # Operate Delivery OS
@@ -30,6 +30,8 @@ Before creating anything that depends on configuration, check the target repo ac
 
 **Show the constructed title, body, and labels before actually creating the issue** — this is a real, visible action in someone else's repo, not a preview in this conversation. Get confirmation on the content, not just the target repo, before calling `gh issue create`.
 
+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):
 - Title **must contain** the literal string `SPRINT -`, e.g. `SPRINT - Sprint 14`
 - Labels: `sprint`, `planning`
@@ -163,6 +165,61 @@ 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.
 
+## Autonomous tracking (identify → file → update → close)
+
+Beyond filing one issue on request, this skill can run a piece of work's whole lifecycle: notice it, classify it, file it, keep it in sync as work happens, and close it out. GitHub issues are the only source of truth — there is no local state, and nothing here persists across sessions except what's written back to the repo.
+
+### Confirm only when unsure
+
+Don't ask before every action — that defeats the point. Act, then say so in one line of the conversation ("Filed #23: TASK - ...", "Updated #17 to In Progress", "Closed #17 — acceptance criteria met"). Every GitHub-visible action gets that line, regardless of confidence, so nothing happens invisibly even when nothing was asked first.
+
+Ask first only when something is genuinely ambiguous:
+- Unclear whether this is actually a new item or an update to an existing open issue
+- Unclear which category it is (Task vs. Bug vs. part of a Sprint)
+- Unclear whether it's actually done (e.g. a PR opened but CI hasn't run, or the acceptance criteria are only partly met)
+
+A clear-cut case — an obvious bug just reproduced, a PR that visibly closes an issue's acceptance criteria — doesn't need a question, just the confirmation line afterward.
+
+### Classifying a candidate
+
+- Bug reproduced or reported while working → **Bug Report**
+- Scoped, actionable follow-up (including things deliberately deferred, like [Phaneroo/github-delivery-operating-system#12](https://github.com/Phaneroo/github-delivery-operating-system/issues/12)) → **Task**
+- A batch of related work with a start/end date → **Sprint** (see "Phases" below)
+- Something that blocks a release or needs sign-off → **Production Release** / **QA Request** (rare mid-session; only when it's actually that, not just "important")
+
+### Phases = Sprints, roadmap = one tracking issue
+
+No new issue type needed — reuse what's already documented above:
+- **A phase is a Sprint Planning issue.** Group Task issues under it exactly the way `sprint-child-creator` does: each child's body contains `Parent Sprint: #<N>`. This keeps the existing burn-down and auto-close automation working even though Claude, not a human, opened the children.
+- **A roadmap is one persistent issue** that lists phases/sprints and their state. Title it `ROADMAP - <project/area>`. No labels or automation attach to it — Claude keeps its body current with `gh issue edit --body-file`, the same rewrite pattern `auto-close-sprint` uses for a sprint's `## 🚦 Sprint Status` section, just done by Claude on request or after a phase's state changes rather than by a workflow.
+
+### Reconcile by querying, never by remembering
+
+Don't rely on recalling an issue number from earlier in the conversation, and never assume it's still accurate after a gap. Before updating or closing something, requery — by keyword search, not just by label, since a filed issue may carry no label at all (labels like `task`/`bug` only exist once `Setup Labels` has been run for that repo; see the pre-flight check) or may be a Bug/Sprint-child/QA item instead of a Task:
+
+```
+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.
+
+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.
+
+### Keeping a Task issue in sync
+
+The `### Status` field in the Task template body is the thing to keep current:
+- `Backlog` → `In Progress` when work actually starts on it
+- → `Ready for Review` when a PR opens against it
+- → `Done` right before closing
+
+To edit just that field: `gh issue view <number> --repo <owner>/<repo> --json body -q .body`, replace the line under `### Status` with the new value, then `gh issue edit <number> --repo <owner>/<repo> --body-file <file>`. Post a comment alongside any status change that isn't self-explanatory from the status alone (blocked and why, PR link, what shipped) — `gh issue comment <number> --repo <owner>/<repo> --body "<update>"`.
+
+Close with `gh issue close <number> --repo <owner>/<repo> --comment "<summary of what was done>"` once the acceptance criteria are actually met — quote which ones, don't just say "done."
+
+### Known limitation
+
+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.
+
 ## Finding things
 
 When there's no issue number in hand yet:

package/README.md

@@ -61,6 +61,19 @@ 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 |
@@ -77,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, and check status 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, 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.
 
 ---
 
@@ -110,6 +123,8 @@ Installing with `--with-skill` drops a `.claude/skills/delivery-ops/SKILL.md` sk
 
 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.
@@ -153,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.2.2",
+  "version": "1.3.1",
   "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,