@open-agent-toolkit/cli 0.0.10

package/assets/skills/oat-pjm-add-backlog-item/SKILL.md

@@ -0,0 +1,155 @@
+---
+name: oat-pjm-add-backlog-item
+version: 1.0.0
+description: Use when a new repo backlog item needs to be captured in the file-per-item backlog structure. Creates the item file, regenerates the index, and prompts for curated overview updates.
+disable-model-invocation: true
+user-invocable: true
+allowed-tools: Read, Write, Bash, Glob, Grep, AskUserQuestion
+---
+
+# Add Backlog Item
+
+Create a new file-backed backlog item under `.oat/repo/reference/backlog/items/` and refresh the generated backlog index.
+
+## Mode Assertion
+
+**OAT MODE: Repo Backlog Capture**
+
+**Purpose:** Capture backlog work in the canonical file-per-item structure with consistent frontmatter, generated IDs, and refreshed index state.
+
+## Progress Indicators (User-Facing)
+
+When executing this skill, provide lightweight progress feedback so the user can tell what’s happening after they confirm.
+
+- Print a phase banner once at start using horizontal separators, e.g.:
+
+  ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+  OAT ▸ ADD BACKLOG ITEM
+  ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+
+- Before multi-step work, print short step indicators, e.g.:
+  - `[1/4] Resolving item details…`
+  - `[2/4] Generating ID + populating template…`
+  - `[3/4] Regenerating backlog index…`
+  - `[4/4] Updating curated overview guidance…`
+
+## Process
+
+### Step 1: Resolve Inputs
+
+Collect the item details from the user or surrounding context:
+
+- Title
+- Description / context
+- Acceptance criteria
+- Optional labels, priority, scope, assignee, and related issue refs
+
+If the title is missing, ask the user.
+If the description is missing, ask for 1-3 sentences of context.
+
+### Step 2: Ensure Backlog Scaffold
+
+Before generating IDs or editing backlog files, run:
+
+```bash
+oat backlog init
+```
+
+This command is idempotent. Use it even in existing repos so the canonical backlog scaffold and exact managed index markers are present before `oat backlog regenerate-index` runs.
+
+Do not hand-create the managed marker block in `backlog/index.md`. The scaffold writes the exact markers required by the CLI:
+
+```md
+<!-- OAT BACKLOG-INDEX -->
+<!-- END OAT BACKLOG-INDEX -->
+```
+
+### Step 3: Prepare Paths and Filename
+
+1. Derive a kebab-case slug from the title.
+2. Set the output path:
+
+```bash
+ITEM_PATH=".oat/repo/reference/backlog/items/{slug}.md"
+```
+
+3. If the file already exists, ask the user whether to overwrite it or pick a different slug.
+
+### Step 4: Generate ID
+
+Run:
+
+```bash
+oat backlog generate-id "{slug}"
+```
+
+Use the returned `bl-XXXX` value as the backlog item ID.
+
+If the initial hash collides with an existing backlog item ID, the CLI should retry with a disambiguated seed until it returns an unused ID. If the command reports a duplicate or collision issue, do not continue writing the item until the generated ID is unique across `backlog/items/*.md`.
+
+### Step 5: Copy Template and Fill Frontmatter
+
+1. Use `.oat/templates/backlog-item.md` as the source template.
+2. Fill:
+   - `id`
+   - `title`
+   - `created`
+   - `updated`
+   - `status` (default `open`)
+   - `priority` (default `medium` unless the user says otherwise)
+   - `scope` (default `task` unless the user says otherwise)
+   - `labels`
+   - `assignee`
+   - `associated_issues`
+3. The agent should propose an initial `scope_estimate` based on the described work, then ask the user to confirm or adjust it.
+4. Write the item body with:
+   - `## Description`
+   - `## Acceptance Criteria`
+
+### Step 6: Write the Backlog Item
+
+Write the completed file to:
+
+```bash
+.oat/repo/reference/backlog/items/{slug}.md
+```
+
+Use the template field order from `.oat/templates/backlog-item.md`.
+
+### Step 7: Regenerate Managed Index
+
+Run:
+
+```bash
+oat backlog regenerate-index
+```
+
+This refreshes the managed table inside `.oat/repo/reference/backlog/index.md`.
+
+### Step 8: Update Curated Overview
+
+Read `.oat/repo/reference/backlog/index.md` and update the `## Curated Overview` section with a brief human-written note when helpful, for example:
+
+- New theme added to the backlog
+- Priority or sequencing implications
+- Linkage to an active OAT project
+
+Do not edit inside the managed marker section.
+
+### Step 9: Summarize to the User
+
+Report:
+
+- Item file path
+- Generated backlog ID
+- Confirmed scope estimate
+- Whether the managed index was regenerated
+- Any curated overview note that was added
+
+## Success Criteria
+
+- New item file exists under `.oat/repo/reference/backlog/items/`
+- Item includes populated frontmatter and both required body sections
+- `scope_estimate` was proposed and confirmed
+- `oat backlog regenerate-index` ran successfully
+- `.oat/repo/reference/backlog/index.md` remains valid, with managed section untouched except by regeneration

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

@@ -0,0 +1,171 @@
+---
+name: oat-pjm-review-backlog
+version: 1.0.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
+allowed-tools: Read, Write, Glob, Grep, Bash(git:*), AskUserQuestion, Task
+user-invocable: true
+---
+
+# Review Backlog
+
+Analyze the file-backed backlog under `.oat/repo/reference/backlog/` to produce a structured review with value-effort ratings, dependency graph, parallel work lanes, and a recommended execution sequence. Optionally cross-reference a roadmap to identify alignment gaps.
+
+## Mode Assertion
+
+**OAT MODE: Backlog Review**
+
+**Purpose:** Review active backlog item files, evaluate roadmap alignment, and recommend a practical execution order.
+
+## Progress Indicators (User-Facing)
+
+When executing this skill, provide lightweight progress feedback so the user can tell what’s happening after they confirm.
+
+- Print a phase banner once at start using horizontal separators, e.g.:
+
+  ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+  OAT ▸ REVIEW BACKLOG
+  ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+
+- 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…`
+
+## Arguments
+
+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`.
+
+## Process
+
+### Step 1: Locate Inputs
+
+**Backlog root:**
+
+1. If `backlog-root` is provided, use it directly.
+2. Otherwise, default to `.oat/repo/reference/backlog/`.
+3. Confirm these inputs exist:
+   - `backlog/index.md`
+   - `backlog/items/*.md`
+   - `backlog/completed.md`
+4. If multiple candidate roots are found, ask the user to pick.
+
+**Roadmap document (optional):**
+
+1. If `--roadmap` is provided, use it directly.
+2. Otherwise, look for `.oat/repo/reference/roadmap.md`.
+3. Ask the user whether to include roadmap alignment if a roadmap is available.
+
+**Output path:**
+
+1. If `--output` is provided, use it directly.
+2. Otherwise, default to `.oat/repo/reviews/backlog-and-roadmap-review.md`.
+
+### Step 2: Read and Catalog Backlog Items
+
+Read all active backlog item files from `backlog/items/*.md`.
+
+For each item, capture:
+
+- **ID**: Use the item frontmatter `id` when present; if missing, assign a stable sequential review ID (`B01`, `B02`, ...)
+- **Title**: Frontmatter `title`
+- **Priority**: Frontmatter `priority`
+- **Scope**: Frontmatter `scope`
+- **Status**: Frontmatter `status`
+- **Labels / assignee / linked issues**: Any relevant frontmatter context
+- **Notes/context**: Key details from `## Description` and `## Acceptance Criteria`
+
+Also read:
+
+- `backlog/index.md` for curated overview notes
+- `backlog/completed.md` for recent completions
+- `backlog/archived/*.md` only when historical context is needed for an active item
+
+### Step 3: Understand Codebase Context
+
+Before rating items, build enough context to assess effort accurately:
+
+1. Read relevant codebase areas referenced by backlog item files.
+2. Check existing CLI, skills, templates, and reference docs to understand reusable patterns.
+3. Note dependencies implied by current implementation state.
+
+Use the Explore agent for broad codebase exploration if needed. Use direct Read/Glob/Grep for targeted lookups.
+
+### Step 4: Rate Each Item
+
+For each active backlog item, assess:
+
+**Value** (High / Medium / Low):
+
+- **High**: Unblocks other items, significant workflow impact, or roadmap-critical
+- **Medium**: Improves consistency or quality but does not block other work
+- **Low**: Nice-to-have, speculative, or narrow audience
+
+**Effort** (High / Medium / Low):
+
+- **High**: > 3 days, broad or cross-cutting work
+- **Medium**: 1-3 days, moderate complexity, well-scoped
+- **Low**: < 1 day, isolated and straightforward
+
+**Quadrant** (derived):
+
+- **Quick Win**
+- **Strategic**
+- **Fill-in**
+- **Avoid / Defer**
+
+Provide a brief rationale for each rating.
+
+### Step 5: Map Dependencies and Parallel Lanes
+
+For each item, identify:
+
+- Hard dependencies
+- Soft dependencies
+- What it blocks
+
+Then group items into independent parallel lanes and organize them into recommended execution waves.
+
+### Step 6: Roadmap Alignment
+
+If a roadmap was provided:
+
+1. Map backlog item files to roadmap horizons or phases.
+2. Identify roadmap work with no backlog coverage.
+3. Identify backlog items not represented on the roadmap.
+4. Check whether roadmap status wording is consistent with active backlog reality.
+
+### Step 7: Write the Review Document
+
+Use the template at `.agents/skills/oat-pjm-review-backlog/references/backlog-review-template.md`.
+
+Ensure:
+
+- Every active backlog item file appears in the item catalog
+- Dependency graph and parallel lanes are explicit
+- Execution waves are actionable
+- Roadmap alignment is included when applicable
+
+### Step 8: Summarize for the User
+
+After writing the review, provide:
+
+- Total active items reviewed
+- Distribution across quadrants
+- Top 3 recommended next actions
+- Key risks or gaps discovered
+
+## Success Criteria
+
+- Every active backlog item file has a value-effort rating with rationale
+- Dependencies are explicitly mapped
+- Parallel lanes and execution waves are actionable
+- Roadmap alignment gaps are surfaced when roadmap input is present
+- Output document follows the review template structure

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

@@ -0,0 +1,172 @@
+# 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"}
+**Purpose:** Prioritize by value/effort, surface dependencies, and recommend an execution sequence
+
+---
+
+## 1. Executive Summary
+
+The backlog contains **{N} items** ({breakdown by section}) spanning {N} themes:
+
+| Theme        | Count | Key Observation     |
+| ------------ | ----- | ------------------- |
+| {Theme name} | {N}   | {Brief observation} |
+| ...          | ...   | ...                 |
+
+**Top-line recommendations:**
+
+1. {Most important recommendation}
+2. {Second recommendation}
+3. {Third recommendation}
+
+---
+
+## 2. Item Catalog
+
+### Rating Key
+
+| Rating     | Value                                                                          | Effort                                           |
+| ---------- | ------------------------------------------------------------------------------ | ------------------------------------------------ |
+| **High**   | Unblocks other items, daily workflow impact, or product milestone prerequisite | > 3 days, high complexity, or touches many files |
+| **Medium** | Improves quality/consistency but not blocking                                  | 1-3 days, moderate complexity                    |
+| **Low**    | Nice-to-have or future-facing                                                  | < 1 day, straightforward, isolated change        |
+
+### Priority Quadrants
+
+```
+                     High Value
+                        |
+         STRATEGIC      |      QUICK WIN
+        (plan carefully)|    (do first)
+                        |
+  High Effort ----------+---------- Low Effort
+                        |
+         AVOID /        |      FILL-IN
+         DEFER          |    (slot into gaps)
+                        |
+                     Low Value
+```
+
+---
+
+<!-- Repeat this block for each backlog item -->
+
+### {BNN} - {Item Title}
+
+> {One-line description of the item}
+
+| Dimension    | Rating                                        | Rationale                |
+| ------------ | --------------------------------------------- | ------------------------ |
+| **Value**    | **{High/Medium/Low}**                         | {Why this value rating}  |
+| **Effort**   | **{High/Medium/Low}**                         | {Why this effort rating} |
+| **Quadrant** | **{Quick Win / Strategic / Fill-in / Avoid}** |                          |
+
+- **Dependencies:** {What this item depends on, or "None"}
+- **Blocked by:** {Item IDs, or "Nothing"}
+- **Blocks:** {Item IDs this unblocks, or "Nothing"}
+
+---
+
+<!-- End of per-item block -->
+
+## 3. Dependency Graph
+
+```
+Legend:  ──▶  hard dependency (must complete first)
+         - -▶  soft dependency (beneficial but not required)
+
+{Render the full dependency graph here}
+
+{Group independent items at the bottom}
+{item} [independent]
+```
+
+---
+
+## 4. Parallel Lanes
+
+These are independent work streams that can be tackled concurrently without conflicts.
+
+### Lane {A}: {Lane Name}
+
+{Brief description of this work stream}
+
+```
+{Item sequence with arrows showing internal ordering}
+```
+
+**Total estimated effort:** {Low/Medium/High}
+**Cross-lane dependencies:** {Any connections to other lanes}
+
+<!-- Repeat for each lane -->
+
+---
+
+## 5. Recommended Execution Order
+
+### Wave {N}: {Wave Name}
+
+| Order | Item                | Effort         | Rationale |
+| ----- | ------------------- | -------------- | --------- |
+| {Na}  | **{BNN}** - {Title} | {Low/Med/High} | {Why now} |
+| ...   | ...                 | ...            | ...       |
+
+**Parallelism:** {Which items in this wave can run in parallel}
+
+<!-- Repeat for each wave -->
+
+### Deferred
+
+| Item                | Rationale      |
+| ------------------- | -------------- |
+| **{BNN}** - {Title} | {Why deferred} |
+
+---
+
+## 6. Roadmap Alignment
+
+<!-- Include this section only if a roadmap was provided -->
+
+### How backlog items map to roadmap phases
+
+| Roadmap Phase | Status   | Backlog Items   | Notes   |
+| ------------- | -------- | --------------- | ------- |
+| {Phase name}  | {Status} | {BNN, BNN, ...} | {Notes} |
+| ...           | ...      | ...             | ...     |
+
+### Gaps: Roadmap items without backlog coverage
+
+| Roadmap Item | Phase   | Recommendation                              |
+| ------------ | ------- | ------------------------------------------- |
+| {Item}       | {Phase} | {Add backlog item? Defer? Already covered?} |
+
+### Orphans: Backlog items not on the roadmap
+
+| Backlog Item        | Recommendation                               |
+| ------------------- | -------------------------------------------- |
+| **{BNN}** - {Title} | {Add to roadmap? Keep as standalone? Defer?} |
+
+---
+
+## 7. Observations & Recommendations
+
+### Strategic observations
+
+1. {Key insight about the backlog shape, sequencing, or priorities}
+2. {Second insight}
+3. ...
+
+### Risks
+
+| Risk               | Mitigation        |
+| ------------------ | ----------------- |
+| {Risk description} | {How to mitigate} |
+
+### Quick wins to tackle immediately
+
+1. **{BNN}** - {Title} ({effort}, {why it's a quick win})
+2. ...
+3. ...

package/assets/skills/oat-pjm-update-repo-reference/SKILL.md

@@ -0,0 +1,128 @@
+---
+name: oat-pjm-update-repo-reference
+version: 1.0.0
+description: Use when OAT implementation changes and the repo backlog, roadmap, and reference docs need to be synchronized with the file-per-item project-management structure.
+disable-model-invocation: true
+user-invocable: true
+allowed-tools: Read, Write, Bash, Glob, Grep, AskUserQuestion
+---
+
+# Update Repo Reference
+
+Keep this repo's OAT reference documentation consistent as implementation evolves, using the file-backed backlog structure under `.oat/repo/reference/backlog/`.
+
+## Mode Assertion
+
+**OAT MODE: Repo Reference Sync**
+
+**Purpose:** Update backlog, roadmap, completed history, and decision records so repo reference docs stay trustworthy after implementation changes.
+
+## Progress Indicators (User-Facing)
+
+When executing this skill, provide lightweight progress feedback so the user can tell what’s happening after they confirm.
+
+- Print a phase banner once at start using horizontal separators, e.g.:
+
+  ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+  OAT ▸ UPDATE REPO REFERENCE
+  ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+
+- Before multi-step work, print short step indicators, e.g.:
+  - `[1/4] Identifying changed OAT surfaces…`
+  - `[2/4] Updating canonical reference docs…`
+  - `[3/4] Regenerating managed backlog index…`
+  - `[4/4] Running reference sanity checks…`
+
+## Process
+
+### Step 1: Identify What Changed
+
+Write down a 1-3 bullet summary of the implementation change:
+
+- New or updated skills
+- New or updated templates
+- New or updated CLI commands
+- Repo-reference behavior changes
+- File moves, renames, or retirements
+
+### Step 2: Ensure Backlog Scaffold
+
+Before editing any backlog files or running backlog regeneration, run:
+
+```bash
+oat backlog init
+```
+
+This command is idempotent and ensures `.oat/repo/reference/backlog/index.md` exists with the exact managed markers required by the CLI:
+
+```md
+<!-- OAT BACKLOG-INDEX -->
+<!-- END OAT BACKLOG-INDEX -->
+```
+
+Do not hand-author or rename those managed markers.
+
+### Step 3: Mine Project Artifacts for Deferred Work and Decisions
+
+For recently completed or in-progress projects, read `discovery.md`, `spec.md`, `design.md`, and `implementation.md` as applicable.
+
+Promote notable findings into one of:
+
+- Backlog item files under `.oat/repo/reference/backlog/items/`
+- Completed summaries in `.oat/repo/reference/backlog/completed.md`
+- Decision record entries in `.oat/repo/reference/decision-record.md`
+- Roadmap updates in `.oat/repo/reference/roadmap.md`
+
+### Step 4: Update Canonical Reference Docs
+
+Update these files as applicable:
+
+1. `.oat/repo/reference/current-state.md`
+2. `.oat/repo/reference/roadmap.md`
+   - Use the `Now / Next / Later` structure when editing roadmap priorities.
+3. `.oat/repo/reference/backlog/index.md`
+   - Update only the `## Curated Overview` section by hand.
+   - Do not hand-edit the managed marker section.
+4. `.oat/repo/reference/backlog/items/*.md`
+   - Add or update active backlog items as file-backed records.
+5. `.oat/repo/reference/backlog/completed.md`
+   - Keep newest completed summaries first.
+6. `.oat/repo/reference/backlog/archived/*.md`
+   - Add rich historical item files only when a completed item needs preserved detail.
+7. `.oat/repo/reference/decision-record.md`
+
+If you modify backlog item files or the completed archive structure, run:
+
+```bash
+oat backlog regenerate-index
+```
+
+### Step 5: Sanity Checks
+
+Use the `Grep` tool for focused searches:
+
+- Search for stale legacy references with pattern `backlog\.md|backlog-completed\.md|deferred-phases\.md` across `.oat/repo/reference`, `docs/oat`, `.agents/skills`, and `AGENTS.md`.
+- Search for the new file-backed paths with pattern `\.oat/repo/reference/backlog/(index|completed|items|archived)` across the same locations.
+
+Confirm that:
+
+- Active work lives in `backlog/items/`
+- Human narrative updates stay in `backlog/index.md` curated section
+- Completed summaries live in `backlog/completed.md`
+- Roadmap wording matches the current `Now / Next / Later` structure
+
+### Step 6: Output
+
+Provide:
+
+- Files updated
+- What changed in each file
+- Whether `oat backlog regenerate-index` was run
+- Any intentionally deferred inconsistencies
+
+## Success Criteria
+
+- Repo reference docs reflect current OAT behavior
+- Backlog updates use the file-backed structure
+- Managed backlog index section is refreshed via CLI, not hand-edited
+- Stale references to retired backlog/deferred files are removed or called out