@open-agent-toolkit/cli 0.1.31 → 0.1.33

package/assets/skills/oat-brainstorm/references/dogfood-results.md

@@ -7,7 +7,7 @@
 > sessions while writing this document. The fold-back commit safety contract
 > in particular has **not** been exercised against real working-tree state.
 > The follow-up live-dogfood task is tracked as a backlog item — see
-> `.oat/repo/reference/backlog/items/live-dogfood-oat-brainstorm.md`
+> `.oat/repo/pjm/backlog/items/live-dogfood-oat-brainstorm.md`
 > ("Live dogfood for `oat-brainstorm` — fold-back commit safety + 9
 > destination families"). Treat the contents below as a contract spec for
 > what live dogfood will assert, not as a record of completed runs.
@@ -387,7 +387,7 @@ Same as Scenario 2 through Step 8.
      Scope:      m
      Priority:   p2
 
-   Confirm to write this to a new bl-XXXX file, or tell me what to change.
+   Confirm to write this to a new backlog item file, or tell me what to change.
    ```
 
    User confirms or revises field-by-field.
@@ -401,8 +401,8 @@ Same as Scenario 2 through Step 8.
 
 **Artifact produced**
 
-- `.oat/repo/reference/backlog/items/<slug>.md` (e.g.,
-  `bl-XXXX-provider-view-sync-drift.md`) with full payload.
+- `.oat/repo/pjm/backlog/items/<BL-YYMMDD-slug>.md` (e.g.,
+  `BL-260622-provider-view-sync-drift.md`) with full payload.
 - Backlog index regenerated.
 
 **Verifiable from skill content**

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

@@ -1,6 +1,6 @@
 ---
 name: oat-pjm-add-backlog-item
-version: 1.1.1
+version: 1.2.0
 description: Use when the user requests or confirms adding a new repo backlog item — e.g. "add a backlog item for X", "capture that as backlog", "track that follow-up", "file a backlog ticket", or confirms a previously offered backlog capture. Do NOT auto-invoke when a follow-up is mentioned. Creates the item file in the file-per-item backlog structure, regenerates the index, and prompts for curated overview updates.
 disable-model-invocation: false
 user-invocable: true
@@ -9,7 +9,7 @@ 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.
+Create a new file-backed backlog item under `.oat/repo/pjm/backlog/items/` and refresh the generated backlog index.
 
 ## Mode Assertion
 
@@ -64,29 +64,26 @@ Do not hand-create the managed marker block in `backlog/index.md`. The scaffold
 <!-- END OAT BACKLOG-INDEX -->
 ```
 
-### Step 3: Prepare Paths and Filename
+### Step 3: Generate ID
 
-1. Derive a kebab-case slug from the title.
-2. Set the output path:
+Run:
 
 ```bash
-ITEM_PATH=".oat/repo/reference/backlog/items/{slug}.md"
+oat backlog generate-id "{title}"
 ```
 
-3. If the file already exists, ask the user whether to overwrite it or pick a different slug.
+The CLI returns a deterministic `BL-YYMMDD-slug` value derived from the creation date and the title. It performs no scan, hash, counter, or random allocation.
 
-### Step 4: Generate ID
+If the command reports a same-day same-slug filename collision against an existing `items/<id>.md` or `archived/<id>.md`, do not overwrite the existing record. Disambiguate by using a more specific title and re-running `oat backlog generate-id`.
 
-Run:
+### Step 4: Prepare Output Path
+
+Set the output path using the returned ID so the filename stem equals the ID:
 
 ```bash
-oat backlog generate-id "{slug}"
+ITEM_PATH=".oat/repo/pjm/backlog/items/{id}.md"
 ```
 
-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.
@@ -108,10 +105,10 @@ If the initial hash collides with an existing backlog item ID, the CLI should re
 
 ### Step 6: Write the Backlog Item
 
-Write the completed file to:
+Write the completed file to the path resolved in Step 4:
 
 ```bash
-.oat/repo/reference/backlog/items/{slug}.md
+.oat/repo/pjm/backlog/items/{id}.md
 ```
 
 Use the template field order from `.oat/templates/backlog-item.md`.
@@ -124,11 +121,11 @@ Run:
 oat backlog regenerate-index
 ```
 
-This refreshes the managed table inside `.oat/repo/reference/backlog/index.md`.
+This refreshes the managed table inside `.oat/repo/pjm/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:
+Read `.oat/repo/pjm/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
@@ -148,8 +145,8 @@ Report:
 
 ## Success Criteria
 
-- New item file exists under `.oat/repo/reference/backlog/items/`
+- New item file exists under `.oat/repo/pjm/backlog/items/` with a `BL-YYMMDD-slug` filename matching its `id`
 - 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
+- `.oat/repo/pjm/backlog/index.md` remains valid, with managed section untouched except by regeneration

package/assets/skills/oat-pjm-decision/SKILL.md

@@ -0,0 +1,129 @@
+---
+name: oat-pjm-decision
+version: 1.0.0
+description: Use when the user requests or confirms recording a durable repo decision — e.g. "capture that as a decision", "write an ADR for X", "record this architectural choice", or confirms a previously offered decision capture. Creates a file-per-record decision under reference/decisions/ via `oat decision new` and refreshes the generated decision index. Do NOT auto-invoke for routine choices that do not warrant durable history.
+disable-model-invocation: false
+user-invocable: true
+allowed-tools: Read, Write, Bash, Glob, Grep, AskUserQuestion
+---
+
+# Record Repo Decision
+
+Capture a durable decision as a file-per-record entry under `.oat/repo/reference/decisions/` using the canonical `oat decision` command group, then refresh the generated decision index.
+
+## Mode Assertion
+
+**OAT MODE: Repo Decision Capture**
+
+**Purpose:** Record durable decision history as file-per-record decisions with deterministic IDs, preserved body prose, and a refreshed generated index — never by hand-editing a shared monolith.
+
+## 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 ▸ RECORD DECISION
+  ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+
+- Before multi-step work, print short step indicators, e.g.:
+  - `[1/4] Resolving decision details…`
+  - `[2/4] Ensuring decision scaffold…`
+  - `[3/4] Creating decision record…`
+  - `[4/4] Filling body and confirming index…`
+
+## Process
+
+### Step 1: Resolve Inputs
+
+Collect the decision details from the user or surrounding context:
+
+- Title (a short noun phrase, e.g. "Adopt date+slug backlog IDs")
+- Context (why the decision is needed; the forces at play)
+- Decision (what was chosen)
+- Consequences (trade-offs, follow-ups, what this enables or blocks)
+- Optional status: `proposed` (default), `accepted`, or `superseded`
+
+If the title is missing, ask the user.
+If context is missing, ask for 1-3 sentences describing the situation.
+
+### Step 2: Ensure Decision Scaffold
+
+Before creating records, ensure the canonical decision scaffold and exact managed index markers exist:
+
+```bash
+oat decision init
+```
+
+This command is idempotent. The scaffold writes `reference/decisions/index.md` with the exact markers required by the CLI:
+
+```md
+<!-- OAT DECISION-INDEX -->
+<!-- END OAT DECISION-INDEX -->
+```
+
+Do not hand-create or rename the managed marker block. Decisions default to `.oat/repo/reference/decisions/`; pass `--decisions-root <path>` only when an explicit override is required.
+
+### Step 3: Create the Decision Record
+
+Create the file-per-record decision with the canonical command:
+
+```bash
+oat decision new "<title>" --status <status> --context "<context>"
+```
+
+The CLI:
+
+- Generates a deterministic `DR-YYMMDD-slug` ID from the creation date and title.
+- Writes one record file whose filename stem equals the ID.
+- Strips template frontmatter and seeds the body from `.oat/templates/decision.md`.
+- Regenerates the managed decision index.
+
+The slug is **capped at 30 characters** at the last whole-word boundary, with trailing
+stop-words (`a, an, the, of, for, and, to, in, on, as, with`) trimmed. Choose a concise,
+meaningful title that stays readable within that 30-character budget.
+
+If the command reports a filename collision (same-day same-slug), use a more specific title to disambiguate rather than overwriting an existing record. Never hand-author a decision file or edit `index.md` inside the managed markers.
+
+### Step 4: Fill the Decision Body
+
+Open the created record at `.oat/repo/reference/decisions/<DR-YYMMDD-slug>.md` and complete the body sections that the template seeds as `TODO`:
+
+- `## Context`
+- `## Decision`
+- `## Consequences`
+
+Preserve the frontmatter (`id`, `title`, `date`, `status`, `legacy_id`). Do not change the `id` — the filename stem must keep matching it.
+
+### Step 5: Regenerate and Verify the Index
+
+If you edited the body only, the index already reflects the record. If you changed any indexed frontmatter field (`status` or `title`), regenerate the managed index:
+
+```bash
+oat decision regenerate-index
+```
+
+Confirm `.oat/repo/reference/decisions/index.md` lists the new record with columns `ID | Date | Status | Title | Legacy` and that the managed marker section was refreshed by the CLI, not by hand.
+
+### Step 6: Summarize to the User
+
+Report:
+
+- Decision record path and generated `DR-YYMMDD-slug` ID
+- Final status
+- Whether the managed decision index was regenerated
+- Any follow-up captured as a backlog item or roadmap note
+
+## Notes on Taxonomy
+
+- Durable decision history lives under `reference/decisions/`, not under `pjm/`.
+- Active operational planning (`current-state.md`, `roadmap.md`, `backlog/`) lives under `pjm/`.
+- Legacy `reference/decision-record.md` monoliths are migrated into file-per-record decisions with `oat decision migrate`; do not write new decisions back into a monolith.
+
+## Success Criteria
+
+- New decision file exists under `.oat/repo/reference/decisions/` with a `DR-YYMMDD-slug` filename matching its `id`
+- Body includes Context, Decision, and Consequences
+- The managed decision index was refreshed via `oat decision new`/`oat decision regenerate-index`, not hand-edited
+- No new decision content was written into a legacy `decision-record.md` monolith

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

@@ -1,6 +1,6 @@
 ---
 name: oat-pjm-review-backlog
-version: 1.2.0
+version: 1.3.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
@@ -10,7 +10,7 @@ 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.
+Analyze the file-backed backlog under `.oat/repo/pjm/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
 
@@ -20,12 +20,12 @@ Analyze the file-backed backlog under `.oat/repo/reference/backlog/` to produce
 
 ## Reference Format Convention
 
-Whenever a backlog item is referenced — in the written review document, in chat output, or in the inline summary at the end — it **must include both the ID and a human-readable title**. Bare IDs like `bl-281c` are not acceptable in user-facing output, because readers do not have a board lookup in front of them.
+Whenever a backlog item is referenced — in the written review document, in chat output, or in the inline summary at the end — it **must include both the ID and a human-readable title**. Bare IDs like `BL-260529-control-plane-state-read` are not acceptable in user-facing output, because readers do not have a board lookup in front of them.
 
 Use one of these formats:
 
-- **Inline / prose:** `` `bl-281c` (control-plane state-read migration) ``
-- **Tables / lists:** `**bl-281c** — Control-plane state-read migration`
+- **Inline / prose:** `` `BL-260529-control-plane-state-read` (control-plane state-read migration) ``
+- **Tables / lists:** `**BL-260529-control-plane-state-read** — Control-plane state-read migration`
 - **Compact lists where space is tight (e.g., dependency graphs):** an ID-only token is acceptable **only if** a legend in the same section maps every ID to its title.
 
 This convention applies equally to:
@@ -59,10 +59,10 @@ When executing this skill, provide lightweight progress feedback so the user can
 
 Parse from `$ARGUMENTS`:
 
-- **backlog-root**: (optional) Path to the backlog root directory. Defaults to `.oat/repo/reference/backlog/`.
+- **backlog-root**: (optional) Path to the backlog root directory. Defaults to `.oat/repo/pjm/backlog/`.
 - **--roadmap=\<path\>**: (optional) Path to a roadmap document for alignment analysis.
-- **--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.
+- **--output=\<path\>**: (optional) Where to write the living review. Defaults to `.oat/repo/pjm/backlog/reviews/backlog-and-roadmap-review.md`.
+- **--archive-dated**: (optional) Also write a dated snapshot alongside the living review at `.oat/repo/pjm/backlog/reviews/backlog-and-roadmap-review-YYYY-MM-DD.md`. Default: off.
 
 ## Process
 
@@ -71,7 +71,7 @@ Parse from `$ARGUMENTS`:
 **Backlog root:**
 
 1. If `backlog-root` is provided, use it directly.
-2. Otherwise, default to `.oat/repo/reference/backlog/`.
+2. Otherwise, default to `.oat/repo/pjm/backlog/`.
 3. Confirm these inputs exist:
    - `backlog/index.md`
    - `backlog/items/*.md`
@@ -81,18 +81,18 @@ Parse from `$ARGUMENTS`:
 **Roadmap document (optional):**
 
 1. If `--roadmap` is provided, use it directly.
-2. Otherwise, look for `.oat/repo/reference/roadmap.md`.
+2. Otherwise, look for `.oat/repo/pjm/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/reference/backlog/reviews/backlog-and-roadmap-review.md` (the living, single-file review co-located with the backlog).
+2. Otherwise, default to `.oat/repo/pjm/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/`.
+If `--archive-dated` is passed, also write a copy to `.oat/repo/pjm/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
 
@@ -172,7 +172,7 @@ 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/`.
+Write the **living** review to the resolved output path (default `.oat/repo/pjm/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:
 
@@ -190,7 +190,7 @@ After writing the review, provide:
 - Top 3 recommended next actions
 - Key risks or gaps discovered
 
-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.
+When listing specific items in this summary, follow the **Reference Format Convention** above — every backlog item must appear as `` `BL-YYMMDD-slug` (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)
 
@@ -204,7 +204,7 @@ 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 `.oat/repo/pjm/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`.
 
@@ -220,7 +220,7 @@ If the operator declines, stop after the summary. Do not silently write or modif
    - 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.
+4. **Write or update** `.oat/repo/pjm/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.
@@ -232,6 +232,6 @@ When referencing backlog items inside the priority-alignment doc, the **Referenc
 - 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/`
+- Living review is written to `.oat/repo/pjm/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,8 +1,8 @@
 # Backlog & Roadmap Review
 
 **Date:** {YYYY-MM-DD}
-**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"}
+**Scope:** {Description of what was reviewed, e.g., "All active items under `.oat/repo/pjm/backlog/items/`"}
+**Roadmap:** {Path to roadmap if included, e.g. `.oat/repo/pjm/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.

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

@@ -35,9 +35,9 @@ If the team doesn't find it useful, omit the column entirely.
 
 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} |
+| Item                                                          | Scope      | Notes                                        |
+| ------------------------------------------------------------- | ---------- | -------------------------------------------- |
+| [Item title](../items/{BL-YYMMDD-slug}.md) (`BL-YYMMDD-slug`) | {S/M/L/XL} | {Status, blocker if any, next concrete step} |
 
 ---
 
@@ -50,9 +50,9 @@ Items already started, in code review, or otherwise mid-flight. Close these out
 
 {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} |
+| Item                                                          | Scope      | {Optional column} | Parallel with                                  | Notes                                   |
+| ------------------------------------------------------------- | ---------- | ----------------- | ---------------------------------------------- | --------------------------------------- |
+| [Item title](../items/{BL-YYMMDD-slug}.md) (`BL-YYMMDD-slug`) | {S/M/L/XL} | {Low/Med/High}    | `BL-YYMMDD-other-slug`, `BL-YYMMDD-third-slug` | {One-line context — gotchas, decisions} |
 
 ---
 
@@ -60,10 +60,10 @@ Items already started, in code review, or otherwise mid-flight. Close these out
 
 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` |
-| {…}                   | {…}                        |
+| Can run together                            | Keep sequential                                       |
+| ------------------------------------------- | ----------------------------------------------------- |
+| `BL-YYMMDD-one-slug` ∥ `BL-YYMMDD-two-slug` | `BL-YYMMDD-first-slug` before `BL-YYMMDD-second-slug` |
+| {…}                                         | {…}                                                   |
 
 ---
 
@@ -71,9 +71,9 @@ Quick lookup for "can I start X while Y is in flight?"
 
 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}
+1. **{Close|Kick off|Defer}** [`BL-YYMMDD-first-slug`](../items/{BL-YYMMDD-first-slug}.md) — {one-line reason: why now, what it unblocks}
+2. **{Close|Kick off|Defer}** [`BL-YYMMDD-second-slug`](../items/{BL-YYMMDD-second-slug}.md) — {one-line reason}
+3. **{Close|Kick off|Defer}** [`BL-YYMMDD-third-slug`](../items/{BL-YYMMDD-third-slug}.md) — {one-line reason}
 
 ---
 

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

@@ -1,7 +1,7 @@
 ---
 name: oat-pjm-update-repo-reference
-version: 1.1.1
-description: Use when repo reference artifacts need updating — roadmap, decision records, backlog status, or completed history. Frequently invoked at project completion, often chained from `oat-project-document`, to ensure `.oat/repo/reference/` state reflects what shipped.
+version: 1.2.0
+description: Use when repo reference artifacts need updating — roadmap, decision records, backlog status, or completed history. Frequently invoked at project completion, often chained from `oat-project-document`, to ensure active `.oat/repo/pjm/` state and durable `.oat/repo/reference/` records reflect what shipped.
 disable-model-invocation: false
 user-invocable: true
 allowed-tools: Read, Write, Bash, Glob, Grep, AskUserQuestion
@@ -9,13 +9,13 @@ 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/`.
+Keep this repo's OAT reference documentation consistent as implementation evolves. Active operational state lives under `.oat/repo/pjm/` (current-state, roadmap, and the file-backed backlog); durable decision history lives under `.oat/repo/reference/decisions/`.
 
 ## 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.
+**Purpose:** Update backlog, roadmap, completed history, and decision records so active `pjm/` state and durable `reference/` records stay trustworthy after implementation changes.
 
 ## Progress Indicators (User-Facing)
 
@@ -53,7 +53,7 @@ Before editing any backlog files or running backlog regeneration, run:
 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:
+This command is idempotent and ensures `.oat/repo/pjm/backlog/index.md` exists with the exact managed markers required by the CLI:
 
 ```md
 <!-- OAT BACKLOG-INDEX -->
@@ -68,28 +68,35 @@ For recently completed or in-progress projects, read `discovery.md`, `spec.md`,
 
 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`
+- Backlog item files under `.oat/repo/pjm/backlog/items/`
+- Completed summaries in `.oat/repo/pjm/backlog/completed.md`
+- Decision records under `.oat/repo/reference/decisions/`, created with
+  `oat decision new "<title>"` (delegate to `oat-pjm-decision` for a guided
+  capture). Do not hand-author decision files or write into a legacy
+  `decision-record.md` monolith.
+- Roadmap updates in `.oat/repo/pjm/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`
+1. `.oat/repo/pjm/current-state.md`
+2. `.oat/repo/pjm/roadmap.md`
    - Use the `Now / Next / Later` structure when editing roadmap priorities.
-3. `.oat/repo/reference/backlog/index.md`
+3. `.oat/repo/pjm/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`
+4. `.oat/repo/pjm/backlog/items/*.md`
    - Add or update active backlog items as file-backed records.
-5. `.oat/repo/reference/backlog/completed.md`
+5. `.oat/repo/pjm/backlog/completed.md`
    - Keep newest completed summaries first.
-6. `.oat/repo/reference/backlog/archived/*.md`
+6. `.oat/repo/pjm/backlog/archived/*.md`
    - Add rich historical item files only when a completed item needs preserved detail.
-7. `.oat/repo/reference/decision-record.md`
+7. `.oat/repo/reference/decisions/`
+   - Create new decisions with `oat decision new` (see `oat-pjm-decision`); the
+     command writes one `DR-YYMMDD-slug` record and regenerates the managed
+     decision index. Do not hand-edit `reference/decisions/index.md` inside its
+     managed markers.
 
 If you modify backlog item files or the completed archive structure, run:
 
@@ -101,15 +108,16 @@ oat backlog regenerate-index
 
 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.
+- Search for stale legacy references with pattern `reference/backlog|reference/roadmap|reference/current-state|decision-record\.md` across `.oat/repo`, `docs/oat`, `.agents/skills`, and `AGENTS.md`. These indicate active state still pointing at the retired `reference/` operational layout (legacy/migration notes excepted).
+- Search for the active paths with pattern `\.oat/repo/pjm/backlog/(index|completed|items|archived)` and `\.oat/repo/reference/decisions/` 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
+- Active work lives in `pjm/backlog/items/`
+- Human narrative updates stay in `pjm/backlog/index.md` curated section
+- Completed summaries live in `pjm/backlog/completed.md`
+- Roadmap wording matches the current `Now / Next / Later` structure in `pjm/roadmap.md`
+- Decisions are file-per-record under `reference/decisions/`, created via `oat decision new`
 
 ### Step 6: Output
 
@@ -123,6 +131,7 @@ Provide:
 ## 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
+- Active backlog, roadmap, and current-state updates live under `pjm/`
+- Decision history is captured as file-per-record decisions under `reference/decisions/` via `oat decision new`, not in a legacy monolith
+- Managed backlog and decision index sections are refreshed via CLI, not hand-edited
+- Stale references to the retired `reference/` operational layout are removed or called out

package/assets/skills/oat-project-complete/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: oat-project-complete
-version: 1.4.9
+version: 1.5.0
 description: Use when all implementation work is finished and the project is ready to close. Marks the OAT project lifecycle as complete.
 disable-model-invocation: true
 user-invocable: true
@@ -329,7 +329,7 @@ When archiving, the project artifacts at `{PROJECT_PATH}/{plan,implementation,di
   - Use the **current/head branch** for the blob link (the same `{BRANCH}` value used by `oat-project-pr-final` Step 4 for every other reference). Step 8 creates the export on the current checkout and Step 10 commits + pushes it on the feature branch, so the link resolves immediately while the PR is open and continues to resolve after merge once the file lands on the base branch.
   - Anti-pattern: do **not** point this link at the base branch (`main` / resolved default branch). The export does not exist on the base branch until the PR merges, so a `blob/main/...` link 404s for the entire window the PR is open — the same class of broken link this whole step exists to prevent.
   - When `archive.summaryExportPath` is unset or `summary.md` is missing, omit this bullet rather than emit a broken link.
-- **Keep References bullets** that resolve independently of the archive: backlog item links under `.oat/repo/reference/backlog/`, decision-record links under `.oat/repo/reference/decisions/`, repo-reference docs, ticket URLs, and anything else under tracked paths outside the project directory.
+- **Keep References bullets** that resolve independently of the archive: backlog item links under `.oat/repo/pjm/backlog/`, decision record links under `.oat/repo/reference/decisions/`, repo-reference docs, ticket URLs, and anything else under tracked paths outside the project directory.
 - Apply the existing `localPaths`-based exclusion rule from `oat-project-pr-final` Step 4 on top of these rules — it already covers `.oat/**/pr` and `.oat/**/reviews/archived` and may catch additional patterns configured per repo.
 
 Anti-pattern: do not "rescue" a dropped artifact by linking to its archived path under `.oat/projects/archived/<name>/...`. That path is gitignored on every checkout and never reaches the remote.

package/assets/skills/oat-project-document/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: oat-project-document
-version: 1.4.1
+version: 1.5.0
 description: Use when the user requests or confirms documenting an active OAT project — e.g. "document the project", "update the docs", "run oat-project-document", or confirms a previously offered documentation run. Do NOT auto-invoke when implementation completes. Analyzes project artifacts, presents a documentation delta plan, and applies approved changes.
 argument-hint: '[project-path] [--auto]'
 disable-model-invocation: false
@@ -260,8 +260,9 @@ Scan the repository for all documentation and instruction surfaces.
    - Note directories for new apps/packages that lack a README
 
 4. **Reference files:**
-   - Check `.oat/repo/reference/` directory
-   - Read: `current-state.md`, `backlog/index.md`, `backlog/completed.md`, `roadmap.md`, `decision-record.md`, and relevant `backlog/items/*.md` files as needed (whichever exist)
+   - Check the active PJM layer under `.oat/repo/pjm/` and the durable layer under `.oat/repo/reference/`
+   - Read (whichever exist): `pjm/current-state.md`, `pjm/roadmap.md`, `pjm/backlog/index.md`, `pjm/backlog/completed.md`, relevant `pjm/backlog/items/*.md` files, and `reference/decisions/index.md` plus relevant `reference/decisions/*.md` records
+   - Legacy repos may still have `reference/current-state.md`, `reference/roadmap.md`, `reference/backlog/`, or a `reference/decision-record.md` monolith until they run `oat pjm migrate`; read those only as a fallback when the `pjm/` and `reference/decisions/` equivalents are absent
 
 **4b. Instruction surfaces (secondary — strong signals only):**
 

package/assets/skills/oat-project-import-plan/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: oat-project-import-plan
-version: 1.3.3
+version: 1.4.0
 description: Use when you have an external markdown plan to execute with OAT. Preserves the source plan and normalizes it into canonical plan.md format.
 argument-hint: '<path-to-plan.md> [--provider codex|cursor|claude] [--project <name>]'
 disable-model-invocation: true
@@ -115,7 +115,7 @@ Inputs:
 
 If source path is not provided, discover likely recent plans first. The discovery script checks both provider plan directories and this repository's external plan directory by default:
 
-- `.oat/repo/reference/external-plans/`
+- `.oat/repo/reference/external-plans/` — the durable destination for imported provider/external plans, as documented in the repo reference guide (`.oat/repo/reference/AGENTS.md`). External plans are durable reference material and stay under `reference/`, never under the active `pjm/` operational layer.
 
 ```bash
 bash .agents/skills/oat-project-import-plan/scripts/find-recent-provider-plans.sh --hours 24