@open-agent-toolkit/cli 0.2.38 → 0.2.39

package/assets/bundle-metadata.json

@@ -1,4 +1,4 @@
 {
   "schemaVersion": 1,
-  "oatVersion": "0.2.38"
+  "oatVersion": "0.2.39"
 }

package/assets/docs/cli-utilities/tool-packs.md

@@ -71,6 +71,19 @@ oat tools install utility
 oat tools install workflows
 ```
 
+The two packs do not need to share a scope. For example, a repository can keep
+the lifecycle adapter at project scope while reusing the utility contracts from
+user scope:
+
+```bash
+oat tools install workflows --scope project
+oat tools install utility --scope user
+```
+
+Lifecycle skills resolve each required sibling independently from the loaded
+scope, then user scope, then project scope. This makes mixed-scope placement a
+supported execution path rather than relying on one frozen skills root.
+
 The packs remain independently installable. If the workflows adapter is
 present without the utility contracts, it fails closed and reports the missing
 dependency instead of inventing a fallback route. Non-project analytical

package/assets/docs/contributing/skills.md

@@ -24,6 +24,33 @@ Skill behavior is defined by frontmatter plus the process contract in each `SKIL
 - Define a pre-work capability and authorization gate for skills that delegate to subagents, workers, or reviewers.
 - Keep output obligations explicit so downstream skills and users know what changed.
 
+## Portable sibling-skill reads
+
+Executable instructions must not assume the skill is running from a repository
+checkout. Before a skill or one of its operational reference files reads a
+sibling `SKILL.md`, resolve a `${SKILLS_ROOT}` in this order:
+
+1. Derive `${SKILL_DIR}/..` from the directory containing the currently loaded
+   `SKILL.md`, when the provider exposes that path.
+2. Try the user-scope root at `${HOME}/.agents/skills`.
+3. Fall back to the project-scope root at `<repo-root>/.agents/skills`.
+
+Probe each candidate for `<sibling>/SKILL.md` and use the first match. If none
+exists, name the missing sibling, give an actionable install or update command,
+and stop that workflow branch instead of improvising the sibling's process.
+
+When a caller needs multiple sibling skills, resolve and bind each sibling
+independently. Do not freeze one `${SKILLS_ROOT}` and assume every dependency is
+installed there: a workflows adapter may be at project scope while its utility
+contracts are at user scope. A missing-sibling recovery must name the owning
+pack and intended scope, using `oat tools install <pack> --scope <user|project>`
+or `oat tools update --pack <pack> --scope <user|project>` as appropriate.
+
+Do not use a bare `.agents/skills/<sibling>/SKILL.md`, `./.agents/...`, or
+`../.agents/...` path for an executable read. Historical examples may retain
+those spellings only when they are non-executable and explicitly baselined by
+the bundled-docs contract test.
+
 ## Contract components
 
 - Mode assertion (purpose, blocked/allowed activities)
@@ -120,6 +147,8 @@ dispatch contract owns capability and authorization checks, live catalog
 evidence, authorized routes, launch acceptance, recovery, and the neutral
 dispatch record. Keep model/effort/reasoning/service-tier axes explicit and do
 not collapse the selection and mechanics references into one provider matrix.
+Before each launch, disclose the resolved dependency sources and effective
+runtime target; never present a bundled recommendation as the selected target.
 
 Keep project lifecycle policy out of that general layer. A lifecycle caller
 loads `oat-project-dispatch-subagents` to resolve project, phase/task, gate,

package/assets/public-package-versions.json

@@ -1,6 +1,6 @@
 {
-  "cli": "0.2.38",
-  "docs-config": "0.2.38",
-  "docs-theme": "0.2.38",
-  "docs-transforms": "0.2.38"
+  "cli": "0.2.39",
+  "docs-config": "0.2.39",
+  "docs-theme": "0.2.39",
+  "docs-transforms": "0.2.39"
 }

package/assets/skills/oat-brainstorm/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: oat-brainstorm
-version: 1.3.0
+version: 1.3.1
 description: Use when the user explicitly invokes the `brainstorm` verb, including `/oat-brainstorm`, "let's brainstorm", "brainstorm this", "can we brainstorm X", or "help me brainstorm X". For ambiguous exploratory phrasing ("I've been thinking", "what if", "help me think through"), do NOT auto-enter; respond conversationally and offer mode only after ≥2 sustained exploratory turns. Do NOT use for review, debug, PR, status, implementation, or active-workflow questions.
 disable-model-invocation: false
 user-invocable: true
@@ -411,7 +411,14 @@ read, in order:
 
 Probe each candidate for `<name>/SKILL.md` and treat the first match as
 `${SKILLS_ROOT}`. If no candidate resolves, tell the user the chained skill is
-not installed and stop that branch instead of improvising its process.
+not installed and name its pack: `ideas` for `oat-idea-*`,
+`project-management` for `oat-pjm-*`, and `workflows` for `oat-project-*`.
+At the intended scope, run `oat tools install <pack> --scope <user|project>` or
+`oat tools update --pack <pack> --scope <user|project>`, then stop that branch
+instead of improvising its process.
+Operational handoffs in `references/destinations.md` inherit this resolver;
+resolve `${SKILLS_ROOT}` with this contract before executing any sibling read
+specified there.
 
 #### 9a — Inline only
 

package/assets/skills/oat-brainstorm/references/destinations.md

@@ -76,7 +76,7 @@ Always honor an explicit user-supplied path over the suggestion. Brainstorm docs
 **Required template fields:** same set as "Capture as new idea" (capture-as-new-idea path runs silently first), then summary input is whatever was synthesized. Template: `.oat/templates/ideas/idea-summary.md` (consumed via `oat-idea-summarize`).
 **Optional template fields:** none — the summary is rendered from the synthesized payload.
 **Confirmation pattern:** `none` at this layer (the downstream `oat-idea-summarize` surfaces the summary for accept/refine review).
-**Handoff target:** capture-as-new-idea path silently (skill reads `.agents/skills/oat-idea-new/SKILL.md` and runs Steps 3-7), then immediately reads `.agents/skills/oat-idea-summarize/SKILL.md` and runs it end-to-end. The `oat-idea-summarize` skill's own accept/refine review serves as the user gate.
+**Handoff target:** capture-as-new-idea path silently (skill reads `${SKILLS_ROOT}/oat-idea-new/SKILL.md`, resolving `${SKILLS_ROOT}` through the owning `oat-brainstorm` contract, and runs Steps 3-7), then immediately resolves `${SKILLS_ROOT}` again, reads `${SKILLS_ROOT}/oat-idea-summarize/SKILL.md`, and runs it end-to-end. The `oat-idea-summarize` skill's own accept/refine review serves as the user gate.
 **If user wants to keep brainstorming after this is offered:** return to flow with destination = summarize-idea-directly. Skill may probe for chosen direction since the summary will read better with one.
 
 ---

package/assets/skills/oat-idea-ideate/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: oat-idea-ideate
-version: 1.2.1
+version: 1.2.2
 description: Use when continuing an existing tracked idea or expanding an explicit scratchpad seed from {IDEAS_ROOT}/scratchpad.md. Do NOT use to start a brand-new, destinationless brainstorm; use oat-brainstorm for that.
 argument-hint: '[--global]'
 disable-model-invocation: true
@@ -67,6 +67,23 @@ If you catch yourself:
 
 ## Process
 
+### Resolve `${SKILLS_ROOT}` for chained idea skills
+
+Before reading a sibling skill, resolve the skills root in this order:
+
+1. Derive it from the directory containing this loaded `SKILL.md`:
+   `${SKILL_DIR}/..`. If the provider exposes the loaded skill path, treat its
+   directory as `${SKILL_DIR}`.
+2. Otherwise try the user-scope root first: `${HOME}/.agents/skills`.
+3. Fall back to the project-scope root: `<repo-root>/.agents/skills`.
+
+Probe each candidate for `<name>/SKILL.md` and treat the first match as
+`${SKILLS_ROOT}`. If no candidate resolves, tell the user that the required
+sibling skill `<name>` is not installed. At the scope containing this loaded
+skill, run `oat tools install ideas --scope <user|project>` or, when the pack is
+already installed there, `oat tools update --pack ideas --scope <user|project>`.
+Then stop the current branch instead of improvising its process.
+
 ### Step 0: Resolve Ideas Level
 
 Determine whether to operate at project level or user (global) level.
@@ -117,7 +134,7 @@ IDEA_PATH=$(oat config get activeIdea 2>/dev/null || true)
   - Existing ideas (with state: brainstorming/summarized)
   - Scratchpad entries marked as "not yet started"
 - If user picks an existing idea → run `oat config set activeIdea "{idea-path}"` and proceed to Step 2
-- If user picks a scratchpad entry → scaffold the idea inline by reading the **`oat-idea-new`** skill (`.agents/skills/oat-idea-new/SKILL.md`) and executing its Steps 3-7 (Initialize Ideas Directory, Scaffold Discovery Document, Update Backlog, Check Scratchpad, Set Active Idea Pointer). Then proceed to Step 2 with the new idea.
+- If user picks a scratchpad entry → scaffold the idea inline by reading the **`oat-idea-new`** skill at `${SKILLS_ROOT}/oat-idea-new/SKILL.md` (resolve `${SKILLS_ROOT}` as above) and executing its Steps 3-7 (Initialize Ideas Directory, Scaffold Discovery Document, Update Backlog, Check Scratchpad, Set Active Idea Pointer). Then proceed to Step 2 with the new idea.
 - If no ideas and no scratchpad entries exist → tell the user: "No ideas found. Run the `oat-idea-new` skill to create one, or run the `oat-idea-scratchpad` skill to capture a quick idea seed." Then stop.
 
 ### Step 2: Load Discovery Document

package/assets/skills/oat-idea-new/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: oat-idea-new
-version: 1.2.0
+version: 1.2.1
 description: Use when starting ideation for a new concept or problem. Creates an idea directory for lightweight capture and handoff to ongoing ideation.
 argument-hint: '<idea-name> [--global]'
 disable-model-invocation: true
@@ -30,6 +30,23 @@ Create a new idea directory, scaffold a discovery document, verify setup, and ha
 
 ## Process
 
+### Resolve `${SKILLS_ROOT}` for chained idea skills
+
+Before reading a sibling skill, resolve the skills root in this order:
+
+1. Derive it from the directory containing this loaded `SKILL.md`:
+   `${SKILL_DIR}/..`. If the provider exposes the loaded skill path, treat its
+   directory as `${SKILL_DIR}`.
+2. Otherwise try the user-scope root first: `${HOME}/.agents/skills`.
+3. Fall back to the project-scope root: `<repo-root>/.agents/skills`.
+
+Probe each candidate for `<name>/SKILL.md` and treat the first match as
+`${SKILLS_ROOT}`. If no candidate resolves, tell the user that the required
+sibling skill `<name>` is not installed. At the scope containing this loaded
+skill, run `oat tools install ideas --scope <user|project>` or, when the pack is
+already installed there, `oat tools update --pack ideas --scope <user|project>`.
+Then stop the current branch instead of improvising its process.
+
 ### Step 0: Resolve Ideas Level
 
 Determine whether to operate at project level or user (global) level.
@@ -140,7 +157,7 @@ Active:    config activeIdea (set)
 Starting brainstorming...
 ```
 
-Then immediately invoke the **`oat-idea-ideate`** skill (located at `.agents/skills/oat-idea-ideate/SKILL.md`) to begin the first brainstorming session. Read that skill file and follow its process from Step 1. The ideate skill owns all conversational brainstorming behavior — do not duplicate it here.
+Then immediately invoke the **`oat-idea-ideate`** skill by reading `${SKILLS_ROOT}/oat-idea-ideate/SKILL.md` (resolve `${SKILLS_ROOT}` as above) to begin the first brainstorming session. Follow its process from Step 1. The ideate skill owns all conversational brainstorming behavior — do not duplicate it here.
 
 ## Success Criteria
 

package/assets/skills/oat-idea-summarize/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: oat-idea-summarize
-version: 1.2.0
+version: 1.2.1
 description: Use when an idea is mature enough to move from brainstorming into the backlog. Generates a summary document and adds the idea to the backlog.
 argument-hint: '[--global]'
 disable-model-invocation: true
@@ -34,6 +34,23 @@ Read the brainstorming discovery document, synthesize a clean summary, and updat
 
 ## Process
 
+### Resolve `${SKILLS_ROOT}` for chained idea skills
+
+Before reading a sibling skill, resolve the skills root in this order:
+
+1. Derive it from the directory containing this loaded `SKILL.md`:
+   `${SKILL_DIR}/..`. If the provider exposes the loaded skill path, treat its
+   directory as `${SKILL_DIR}`.
+2. Otherwise try the user-scope root first: `${HOME}/.agents/skills`.
+3. Fall back to the project-scope root: `<repo-root>/.agents/skills`.
+
+Probe each candidate for `<name>/SKILL.md` and treat the first match as
+`${SKILLS_ROOT}`. If no candidate resolves, tell the user that the required
+sibling skill `<name>` is not installed. At the scope containing this loaded
+skill, run `oat tools install ideas --scope <user|project>` or, when the pack is
+already installed there, `oat tools update --pack ideas --scope <user|project>`.
+Then stop the current branch instead of improvising its process.
+
 ### Step 0: Resolve Ideas Level
 
 Determine whether to operate at project level or user (global) level.
@@ -81,7 +98,7 @@ Read `{IDEAS_ROOT}/$IDEA_NAME/discovery.md`.
 **If mostly empty:**
 
 - Warn: "This idea hasn't been explored much yet. Consider running the `oat-idea-ideate` skill first to flesh it out."
-- Ask: continue with summarization anyway, or brainstorm more? If user chooses to brainstorm, read the **`oat-idea-ideate`** skill (`.agents/skills/oat-idea-ideate/SKILL.md`) and follow its process from Step 4.
+- Ask: continue with summarization anyway, or brainstorm more? If user chooses to brainstorm, read the **`oat-idea-ideate`** skill at `${SKILLS_ROOT}/oat-idea-ideate/SKILL.md` (resolve `${SKILLS_ROOT}` as above) and follow its process from Step 4.
 
 ### Step 3: Generate Summary
 
@@ -114,7 +131,7 @@ Display the generated summary to the user. Ask:
 - **Refine** — edit the summary (make changes, then re-confirm)
 - **Continue brainstorming** — discard summary and resume brainstorming
 
-If user chooses to continue brainstorming, do not update state or backlog. Read the **`oat-idea-ideate`** skill (`.agents/skills/oat-idea-ideate/SKILL.md`) and follow its process from Step 4 (Start New Session) to resume the conversation.
+If user chooses to continue brainstorming, do not update state or backlog. Read the **`oat-idea-ideate`** skill at `${SKILLS_ROOT}/oat-idea-ideate/SKILL.md` (resolve `${SKILLS_ROOT}` as above) and follow its process from Step 4 (Start New Session) to resume the conversation.
 
 ### Step 5: Update Discovery State
 

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

@@ -1,6 +1,6 @@
 ---
 name: oat-project-implement
-version: 2.2.5
+version: 2.2.6
 description: Use when plan.md is ready for execution. Dispatches one phase implementer per phase, owns independent phase review and bounded fix routing, and supports plan-declared worktree-isolated parallel phases.
 oat_gateable: true
 argument-hint: '[--retry-limit <N>] [--dry-run]'
@@ -19,23 +19,24 @@ Execute the implementation plan task-by-task with full state tracking.
 
 ## Shared Subagent Dispatch Contract
 
-Before resolving or launching a phase implementer, optional child, fix, or
-reviewer, read `.agents/skills/oat-project-dispatch-subagents/SKILL.md`, then
-`.agents/skills/oat-dispatch-subagents/SKILL.md`. The former resolves lifecycle
-scope; the latter owns provider-neutral selection, recovery, and evidence.
-Display structured resolver notices before every implementation, fix, or
-reviewer launch. Runtime disclosure uses the effective resolved target, never
-the bundled recommendation version. This explicit load is mandatory, and
-correctness must not require a provider restart or hot reload.
-
-Read
-`.agents/skills/subagent-orchestration/references/model-selection-principles.md`.
+Before launch, independently probe each required `<name>/SKILL.md` in order:
+`${SKILL_DIR}/..` from this loaded skill, `${HOME}/.agents/skills`, then
+`<repo-root>/.agents/skills`. Bind each first match to its own root:
+`${PROJECT_DISPATCH_SKILLS_ROOT}` for `oat-project-dispatch-subagents`,
+`${DISPATCH_SKILLS_ROOT}` for `oat-dispatch-subagents`, and
+`${ORCHESTRATION_SKILLS_ROOT}` for `subagent-orchestration`; never ambient
+discovery. On a miss, name it, stop every implementation, fix, or reviewer
+dispatch, and give its intended-scope recovery command:
+
+- `oat-project-dispatch-subagents`: `oat tools install workflows --scope <user|project>` or `oat tools update --pack workflows --scope <user|project>`.
+- `oat-dispatch-subagents` or `subagent-orchestration`: `oat tools install utility --scope <user|project>` or `oat tools update --pack utility --scope <user|project>`.
+
+Read `${PROJECT_DISPATCH_SKILLS_ROOT}/oat-project-dispatch-subagents/SKILL.md`, then `${DISPATCH_SKILLS_ROOT}/oat-dispatch-subagents/SKILL.md`; both are mandatory in order. Display structured resolver notices before every implementation, fix, or reviewer launch. Runtime disclosure uses the effective resolved target, never the bundled recommendation version. Correctness must not require restart or hot reload.
+Read `${ORCHESTRATION_SKILLS_ROOT}/subagent-orchestration/references/model-selection-principles.md`.
 After resolving `ACTIVE_PROVIDER`, read exactly one active-provider selection
-reference from `.agents/skills/subagent-orchestration/references/` and the
-matching mechanics reference from
-`.agents/skills/oat-dispatch-subagents/references/` (`provider-cursor.md`,
-`provider-codex.md`, or `provider-claude.md`). Do not merge provider guidance
-or mechanics.
+reference there: the named `provider-cursor.md`, `provider-codex.md`, or
+`provider-claude.md` match. Then read the matching mechanics reference from
+`${DISPATCH_SKILLS_ROOT}/oat-dispatch-subagents/references/`. Do not merge them.
 
 ## Project Log Append Points
 

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

@@ -1,6 +1,6 @@
 ---
 name: oat-project-plan-writing
-version: 1.2.18
+version: 1.2.19
 description: Use when authoring or mutating plan.md in any OAT workflow. Defines canonical format invariants — stable task IDs, required sections, review table rules, and resume guardrails.
 disable-model-invocation: true
 user-invocable: false
@@ -25,20 +25,41 @@ This is a sub-phase indicator; the calling skill owns the top-level banner.
 
 ## Shared Subagent Dispatch Contract
 
-Before every artifact self-review dispatch, read and follow
-`.agents/skills/oat-project-dispatch-subagents/SKILL.md`, which then requires
-`.agents/skills/oat-dispatch-subagents/SKILL.md`. This explicit two-skill load
-is mandatory; do not rely on ambient skill discovery. Planning self-review
+Before every artifact self-review dispatch, resolve `${SKILLS_ROOT}` for each
+required sibling skill in this order:
+
+1. Derive it from the directory containing this loaded `SKILL.md`:
+   `${SKILL_DIR}/..`. If the provider exposes the loaded skill path, treat its
+   directory as `${SKILL_DIR}`.
+2. Otherwise try the user-scope root first: `${HOME}/.agents/skills`.
+3. Fall back to the project-scope root: `<repo-root>/.agents/skills`.
+
+Probe each candidate for `<name>/SKILL.md` and treat the first match as
+`${SKILLS_ROOT}`. If no candidate resolves, tell the user which required
+dispatch skill is not installed. For `oat-project-dispatch-subagents`, run
+`oat tools install workflows --scope <user|project>` or
+`oat tools update --pack workflows --scope <user|project>` at its intended
+scope. For `oat-dispatch-subagents` or `subagent-orchestration`, run
+`oat tools install utility --scope <user|project>` or
+`oat tools update --pack utility --scope <user|project>` at its intended scope.
+Stop before the artifact self-review dispatch. Do not fall back to ambient skill
+discovery.
+
+Resolve, read, and follow
+`${SKILLS_ROOT}/oat-project-dispatch-subagents/SKILL.md`, then resolve and read
+`${SKILLS_ROOT}/oat-dispatch-subagents/SKILL.md`. Both reads are mandatory and
+must remain in this order. Planning self-review
 inherits the planning parent by default. The shared contracts own any
 catalog-aware exception, launch acceptance boundary, and dispatch record; this
 skill continues to own plan readiness and review disposition.
 
 Read
-`.agents/skills/subagent-orchestration/references/model-selection-principles.md`.
+`${SKILLS_ROOT}/subagent-orchestration/references/model-selection-principles.md`
+(resolve `${SKILLS_ROOT}` for `subagent-orchestration` first).
 After resolving the review provider, read exactly one active-provider selection
-reference from `.agents/skills/subagent-orchestration/references/` and the
+reference from `${SKILLS_ROOT}/subagent-orchestration/references/` and the
 matching mechanics reference from
-`.agents/skills/oat-dispatch-subagents/references/` (`provider-cursor.md`,
+`${SKILLS_ROOT}/oat-dispatch-subagents/references/` (`provider-cursor.md`,
 `provider-codex.md`, or `provider-claude.md`). Do not merge provider guidance
 or mechanics.
 

package/package.json

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