@open-agent-toolkit/cli 0.1.10 → 0.1.11

package/assets/public-package-versions.json

@@ -1,6 +1,6 @@
 {
-  "cli": "0.1.10",
-  "docs-config": "0.1.10",
-  "docs-theme": "0.1.10",
-  "docs-transforms": "0.1.10"
+  "cli": "0.1.11",
+  "docs-config": "0.1.11",
+  "docs-theme": "0.1.11",
+  "docs-transforms": "0.1.11"
 }

package/assets/skills/oat-pjm-review-backlog/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: oat-pjm-review-backlog
-version: 1.1.0
+version: 1.2.0
 description: Use when prioritizing the file-backed repo backlog or evaluating roadmap alignment. Produces value-effort ratings, dependency mapping, and execution recommendations.
 argument-hint: '[backlog-root] [--roadmap=<path>] [--output=<path>]'
 disable-model-invocation: true
@@ -48,11 +48,12 @@ When executing this skill, provide lightweight progress feedback so the user can
   ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
 
 - Before multi-step work, print short step indicators, e.g.:
-  - `[1/5] Resolving backlog inputs…`
-  - `[2/5] Cataloging backlog items…`
-  - `[3/5] Reading codebase context…`
-  - `[4/5] Writing review document…`
-  - `[5/5] Summarizing recommendations…`
+  - `[1/6] Resolving backlog inputs…`
+  - `[2/6] Cataloging backlog items…`
+  - `[3/6] Reading codebase context…`
+  - `[4/6] Writing review document…`
+  - `[5/6] Summarizing recommendations…`
+  - `[6/6] (Optional) Priority-alignment walkthrough…` — only print after the operator accepts the offer in Step 9
 
 ## Arguments
 
@@ -60,7 +61,8 @@ Parse from `$ARGUMENTS`:
 
 - **backlog-root**: (optional) Path to the backlog root directory. Defaults to `.oat/repo/reference/backlog/`.
 - **--roadmap=\<path\>**: (optional) Path to a roadmap document for alignment analysis.
-- **--output=\<path\>**: (optional) Where to write the review. Defaults to `.oat/repo/reviews/backlog-and-roadmap-review.md`.
+- **--output=\<path\>**: (optional) Where to write the living review. Defaults to `.oat/repo/reference/backlog/reviews/backlog-and-roadmap-review.md`.
+- **--archive-dated**: (optional) Also write a dated snapshot alongside the living review at `.oat/repo/reference/backlog/reviews/backlog-and-roadmap-review-YYYY-MM-DD.md`. Default: off.
 
 ## Process
 
@@ -85,7 +87,12 @@ Parse from `$ARGUMENTS`:
 **Output path:**
 
 1. If `--output` is provided, use it directly.
-2. Otherwise, default to `.oat/repo/reviews/backlog-and-roadmap-review.md`.
+2. Otherwise, default to `.oat/repo/reference/backlog/reviews/backlog-and-roadmap-review.md` (the living, single-file review co-located with the backlog).
+3. If the `backlog/reviews/` directory does not exist yet, create it before writing. Do not fall back to `.oat/repo/reviews/` — backlog review artifacts now live under the file-backed backlog, not the repo-wide reviews directory.
+
+**Dated snapshot (optional):**
+
+If `--archive-dated` is passed, also write a copy to `.oat/repo/reference/backlog/reviews/backlog-and-roadmap-review-YYYY-MM-DD.md` in the **same directory** as the living review. Do not write dated snapshots to `.oat/repo/reviews/`.
 
 ### Step 2: Read and Catalog Backlog Items
 
@@ -165,6 +172,8 @@ If a roadmap was provided:
 
 Use the template at `.agents/skills/oat-pjm-review-backlog/references/backlog-review-template.md`.
 
+Write the **living** review to the resolved output path (default `.oat/repo/reference/backlog/reviews/backlog-and-roadmap-review.md`). If `--archive-dated` was passed, also write a dated snapshot alongside it (`backlog-and-roadmap-review-YYYY-MM-DD.md` in the same directory). Never split living and dated outputs across different directories — they must live together under `backlog/reviews/`.
+
 Ensure:
 
 - Every active backlog item file appears in the item catalog
@@ -183,6 +192,39 @@ After writing the review, provide:
 
 When listing specific items in this summary, follow the **Reference Format Convention** above — every backlog item must appear as `` `bl-XXXX` (human-readable title) `` (or the bold-with-em-dash variant in tables). Do not emit bare IDs.
 
+### Step 9: Offer Priority Alignment Walkthrough (Optional, Collaborative)
+
+The full review answers "what's in the backlog and how is each item rated." Operators still have to mentally extract "what should I actually do next, and in what order, with what parallelism." `priority-alignment.md` is the one-page execution companion that makes that extraction explicit.
+
+This step is **optional** and **collaborative** — it requires operator context (recent ships, capacity, calendar, ongoing initiatives) that the skill alone does not have. Do not produce or refresh `priority-alignment.md` without operator participation.
+
+**Decision: should we run the walkthrough?**
+
+After the summary, ask the operator:
+
+> Want to walk through the review together and produce a one-page execution view at `backlog/reviews/priority-alignment.md`? It captures phased order, parallelism, and a recommended kickoff stack — a faster reference than the full review.
+
+If `.oat/repo/reference/backlog/reviews/priority-alignment.md` already exists, frame it as an **update** to the existing document rather than a fresh create. Read the existing file first so the walkthrough builds on it.
+
+If the operator declines, stop after the summary. Do not silently write or modify `priority-alignment.md`.
+
+**If the operator accepts, run the walkthrough:**
+
+1. **Propose a phase breakdown** based on the review's quadrants and dependency graph:
+   - "Finishing / in flight" — items already started or in code review
+   - One or more execution phases that group items by initiative, parallel lane, or sequencing constraint
+   - Surface the natural parallelism boundaries from Step 5 as parallel tracks within a phase
+2. **Solicit operator context** that the review alone cannot capture:
+   - What just shipped or changed since the last alignment? (Goes in the **Status** line and **Changelog**.)
+   - What's the operator's capacity / appetite for parallel work this cycle?
+   - Are there calendar constraints (freezes, releases, time off) that affect ordering?
+   - Does the operator want an optional axis like "planning investment" or "design effort" as a column? (Some repos find this useful; many don't. Default: omit unless operator opts in.)
+3. **Iterate on phase names, ordering, and the kickoff stack** until the operator is satisfied. Phase names should reflect the repo's actual initiatives, not generic placeholders.
+4. **Write or update** `.oat/repo/reference/backlog/reviews/priority-alignment.md` using the template at `.agents/skills/oat-pjm-review-backlog/references/priority-alignment-template.md`. Add a new Changelog entry summarizing what shifted in this pass.
+5. **Confirm the result** with the operator: file path, top-of-doc Status line, and the kickoff stack.
+
+When referencing backlog items inside the priority-alignment doc, the **Reference Format Convention** still applies — link to the item file and pair the ID with a human-readable title.
+
 ## Success Criteria
 
 - Every active backlog item file has a value-effort rating with rationale
@@ -190,4 +232,6 @@ When listing specific items in this summary, follow the **Reference Format Conve
 - Parallel lanes and execution waves are actionable
 - Roadmap alignment gaps are surfaced when roadmap input is present
 - Output document follows the review template structure
+- Living review is written to `.oat/repo/reference/backlog/reviews/backlog-and-roadmap-review.md` (unless `--output` is explicitly overridden); dated snapshots, when emitted, live in the same `backlog/reviews/` directory and never under `.oat/repo/reviews/`
+- The operator is offered (but never forced into) a collaborative walkthrough that produces or updates `backlog/reviews/priority-alignment.md`; if the operator accepts, the file is written using the priority-alignment template and includes a Changelog entry for this pass; if the operator declines, no file is created or modified
 - Every user-facing reference to a backlog item pairs the ID with a human-readable title (per the Reference Format Convention)

package/assets/skills/oat-pjm-review-backlog/references/backlog-review-template.md

@@ -1,10 +1,12 @@
 # Backlog & Roadmap Review
 
 **Date:** {YYYY-MM-DD}
-**Scope:** {Description of what was reviewed, e.g., "All items in backlog.md (Inbox + Planned)"}
-**Roadmap:** {Path to roadmap if included, or "N/A"}
+**Scope:** {Description of what was reviewed, e.g., "All active items under `.oat/repo/reference/backlog/items/`"}
+**Roadmap:** {Path to roadmap if included, e.g. `.oat/repo/reference/roadmap.md`, or "N/A"}
 **Purpose:** Prioritize by value/effort, surface dependencies, and recommend an execution sequence
 
+> If a one-page execution companion exists in this directory, see [`priority-alignment.md`](./priority-alignment.md) — produced via the optional walkthrough at the end of `oat-pjm-review-backlog`. It is the short, ordered "what to do next" view of this full review.
+
 ---
 
 ## 1. Executive Summary

package/assets/skills/oat-pjm-review-backlog/references/priority-alignment-template.md

@@ -0,0 +1,86 @@
+# Backlog Priority Alignment
+
+**Date:** {YYYY-MM-DD}
+**Status:** {Active|Stale} — {one-line snapshot of what just shipped or shifted since the previous alignment, e.g. "Post-PR #XX ship of feature Y; new high-priority item Z promoted"}.
+
+One-page execution guide: recommended order, scope, parallelism, and (optionally) planning investment. For the full value/effort catalog, dependency graph, and quadrant tables, see [backlog-and-roadmap-review.md](./backlog-and-roadmap-review.md).
+
+> This document is produced or refreshed via the optional walkthrough at the end of `oat-pjm-review-backlog`. It is **not** auto-generated — phase shape, parallelism, and the kickoff stack reflect operator judgment captured during the walkthrough.
+
+## Related sources
+
+| Document                                                         | Role                                                                  |
+| ---------------------------------------------------------------- | --------------------------------------------------------------------- |
+| [roadmap.md](../../roadmap.md)                                   | Authoritative Now / Next / Later execution order                      |
+| [current-state.md](../../current-state.md)                       | Shipped capabilities and selected active backlog (if maintained)      |
+| [backlog/index.md](../index.md)                                  | Curated overview + generated item table                               |
+| [backlog/items/](../items/)                                      | Executable backlog records (one file per item)                        |
+| [backlog-and-roadmap-review.md](./backlog-and-roadmap-review.md) | Full `oat-pjm-review-backlog` artifact (catalog, dependencies, waves) |
+| Dated snapshots                                                  | `backlog-and-roadmap-review-YYYY-MM-DD.md` in this directory          |
+
+<!--
+Optional axis: some teams find a "planning investment" or "design effort" column
+useful — it separates discovery/design time from total build time. If you use it,
+define the term inline here so readers don't have to guess. Example:
+
+> **Planning investment** = discovery/design likely needed *before* implementation
+> pays off — not total build time.
+
+If the team doesn't find it useful, omit the column entirely.
+-->
+
+---
+
+## Finishing / in flight
+
+Items already started, in code review, or otherwise mid-flight. Close these out before — or alongside — the next phase.
+
+| Item                                             | Scope      | Notes                                        |
+| ------------------------------------------------ | ---------- | -------------------------------------------- |
+| [Item title](../items/{filename}.md) (`bl-XXXX`) | {S/M/L/XL} | {Status, blocker if any, next concrete step} |
+
+---
+
+<!-- Repeat one section per execution phase. Use repo-specific phase names —
+     organize by initiative, parallel lane, or sequencing constraint, not by
+     generic "Phase 1 / Phase 2". The point of named phases is that operators
+     can talk about them ("the synthesis phase", "the docs IA push"). -->
+
+## Phase {N} — {Repo-specific name}
+
+{One short paragraph: what this phase represents, how many tracks can run in parallel inside it, any kickoff constraints (e.g. "weekly pair is one combined kickoff").}
+
+| Item                                             | Scope      | {Optional column} | Parallel with        | Notes                                   |
+| ------------------------------------------------ | ---------- | ----------------- | -------------------- | --------------------------------------- |
+| [Item title](../items/{filename}.md) (`bl-XXXX`) | {S/M/L/XL} | {Low/Med/High}    | `bl-YYYY`, `bl-ZZZZ` | {One-line context — gotchas, decisions} |
+
+---
+
+## Parallelism cheat sheet
+
+Quick lookup for "can I start X while Y is in flight?"
+
+| Can run together      | Keep sequential            |
+| --------------------- | -------------------------- |
+| `bl-XXXX` ∥ `bl-YYYY` | `bl-AAAA` before `bl-BBBB` |
+| {…}                   | {…}                        |
+
+---
+
+## Suggested next kickoff stack
+
+Three concrete actions for the next development cycle. Not a ranked list of everything — just what to do _first_.
+
+1. **{Close|Kick off|Defer}** [`bl-XXXX`](../items/{filename}.md) — {one-line reason: why now, what it unblocks}
+2. **{Close|Kick off|Defer}** [`bl-YYYY`](../items/{filename}.md) — {one-line reason}
+3. **{Close|Kick off|Defer}** [`bl-ZZZZ`](../items/{filename}.md) — {one-line reason}
+
+---
+
+## Changelog
+
+Append a new row each time this file is refreshed via the `oat-pjm-review-backlog` walkthrough. Keep entries short — what shifted and why.
+
+| Date         | Update                                                                             |
+| ------------ | ---------------------------------------------------------------------------------- |
+| {YYYY-MM-DD} | {What changed this pass: promotions/demotions, new high-pri items, phase reshapes} |

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@open-agent-toolkit/cli",
-  "version": "0.1.10",
+  "version": "0.1.11",
   "private": false,
   "description": "Open Agent Toolkit CLI",
   "homepage": "https://github.com/voxmedia/open-agent-toolkit/tree/main/packages/cli",
@@ -33,7 +33,7 @@
     "ora": "^9.0.0",
     "yaml": "2.8.2",
     "zod": "^3.25.76",
-    "@open-agent-toolkit/control-plane": "0.1.10"
+    "@open-agent-toolkit/control-plane": "0.1.11"
   },
   "devDependencies": {
     "@types/node": "^22.10.0",