@open-agent-toolkit/cli 0.1.3 → 0.1.4

package/assets/public-package-versions.json

@@ -1,6 +1,6 @@
 {
-  "cli": "0.1.3",
-  "docs-config": "0.1.3",
-  "docs-theme": "0.1.3",
-  "docs-transforms": "0.1.3"
+  "cli": "0.1.4",
+  "docs-config": "0.1.4",
+  "docs-theme": "0.1.4",
+  "docs-transforms": "0.1.4"
 }

package/assets/skills/oat-agent-instructions-analyze/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: oat-agent-instructions-analyze
-version: 1.9.0
+version: 1.10.0
 description: Run when you need to evaluate agent instruction file coverage, quality, and drift. Produces a severity-rated analysis artifact. Run before oat-agent-instructions-apply to identify what needs improvement.
 disable-model-invocation: true
 user-invocable: true
@@ -294,7 +294,7 @@ Any discrepancy that would cause agents to follow the wrong pattern should be fl
 
 ### Step 4: Assess Coverage Gaps
 
-Walk the directory tree and evaluate each directory against `references/directory-assessment-criteria.md`.
+Walk the directory tree and evaluate **each directory against `references/directory-assessment-criteria.md`, per-directory and at every depth**. The walk descends into subdirectories recursively — it is not limited to top-level apps and packages. A nested domain subdirectory such as `packages/<pkg>/src/<domain>/` is in scope and is assessed with the same primary indicators as a top-level package; the size of a directory's parent never gates whether that directory is evaluated.
 
 Before general coverage-gap analysis, assess **provider baseline gaps** for every active provider.
 These checks are mandatory even when the missing file does not appear in the discovered inventory.

package/assets/skills/oat-agent-instructions-analyze/references/directory-assessment-criteria.md

@@ -2,6 +2,8 @@
 
 When does a directory need its own instruction file? Use these criteria to identify coverage gaps during analysis. The full guidance lives in `docs/agent-instruction.md` — this is a distilled, actionable checklist.
 
+Apply these criteria **per directory, at every depth** — not just to top-level apps and packages. A nested subdirectory such as `packages/<pkg>/src/<domain>/` is assessed with exactly the same indicators as a top-level package. The size of a directory's parent never gates whether that directory is evaluated.
+
 ## Primary Indicators (any one = likely needs instructions)
 
 ### 1. Has Own Build Configuration
@@ -26,32 +28,45 @@ When does a directory need its own instruction file? Use these criteria to ident
 
 - Represents a bounded context or module with domain-specific business logic
 - Has its own data models, terminology, or invariants
-- Example: `packages/billing/`, `services/auth/`, `lib/search-engine/`
-- **Signal strength:** Moderate — depends on complexity
+- Has non-obvious conventions an agent would otherwise miss — patterns that diverge from the parent's defaults
+- **Applies at any depth.** A top-level package and a nested domain subdirectory are assessed the same way: `packages/billing/`, `services/auth/`, `lib/search-engine/`, **and** `packages/<pkg>/src/<domain>/` (for example, a `bigquery-sync/` or `payment-reconciliation/` subdirectory inside an otherwise modest package).
+- **Signal strength:** Strong — this is the primary trigger for a nested instruction file. A bounded domain with its own models, terminology, invariants, and non-obvious conventions warrants a file **at any depth, regardless of how large or small its parent is**. Domain specificity, not parent size, decides this.
 
-### 5. Significant Codebase (>10 source files)
+### 5. Significant Codebase
 
-- Contains more than ~10 source files with specialized conventions
+- Contains a substantial body of code (loosely, 10+ source files) with specialized conventions
 - Has patterns or conventions that differ from the rest of the repo
-- **Signal strength:** Moderate — larger directories benefit more from explicit guidance
+- **Signal strength:** Moderate — a larger directory benefits more from explicit guidance, but only when it has conventions of its own
+- **File count is never sufficient on its own.** A directory with many files that all mirror the parent's conventions is not a trigger — there is nothing distinct to capture. This indicator only fires alongside genuinely divergent, non-obvious conventions. Treat the "10+" figure as a loose illustration of "non-trivial", not a precise threshold.
+
+## Nested Instruction Files (Progressive Specificity)
+
+Instruction files form a hierarchy. A root `AGENTS.md` carries repo-wide conventions; deeper files carry progressively more specific guidance for the subtree they scope. **Deeper = more specific, never broader.**
+
+A nested instruction file **inherits everything from its ancestors** and contains **only the domain-specific delta** — the conventions, models, terminology, and invariants that are true for that subtree and are not already captured (or are contradicted) above it. A child file must **not repeat** the parent: no copied conventions, no restated repo-wide rules. See `references/docs/agent-instruction.md` §13 ("Scoped Files (When and How)") for the full progressive-disclosure model.
+
+Because a nested file is small and additive — it adds a thin delta rather than a full document — **the cost of adding one is low**. The decision bar is therefore qualitative, not size-based:
 
-## Large Directory Decomposition
+> Would an agent working only from the nearest existing (ancestor) instruction file get something wrong, or miss something, in this directory's domain?
 
-When a directory meets 1+ primary indicators and contains **more than 50 source files**, assess its major
-subdirectories starting at depth 1-2 before writing a single broad recommendation.
+If yes, the directory is a coverage-gap candidate. If no — the ancestor file already covers everything an agent needs here — it is not, regardless of how many files the directory contains.
 
-If the first pass still leaves a sub-area that is large or clearly heterogeneous, keep decomposing deeper until the
-distinct conventions are visible or the analysis stops yielding materially different guidance.
+**Worked example.** A package has ~29 source files overall and a root-level `AGENTS.md` describing the package's general conventions. Inside it, `src/bigquery-sync/` holds ~15 files implementing BigQuery sync: it has its own data models, its own terminology (sync cursors, watermark tables, backfill windows), and non-obvious invariants (ordering guarantees, idempotency keys, partition-boundary handling) that appear nowhere else in the package. The parent package is well under any "large" bar, so an app/package-only or size-gated reading would conclude "no nested file warranted." That conclusion is wrong: an agent editing `src/bigquery-sync/` from the package-level `AGENTS.md` alone would miss the sync invariants and likely introduce a correctness bug. `src/bigquery-sync/` is a legitimate coverage-gap candidate — it meets Indicator 4 — and should be surfaced with a scoped `AGENTS.md` recommendation that captures only the sync-specific delta.
 
-Check whether subdirectories differ by:
+## Decomposing Broad Recommendations
 
-- tech stack or runtime (for example, embedded React client vs Node server code)
+When an area you would recommend a single instruction file for actually spans **distinct sub-areas**, decompose the recommendation: assess and recommend per sub-area instead of writing one broad, vague file. The trigger for decomposition is **heterogeneity**, not file count.
+
+Decompose when the area's subdirectories differ by:
+
+- tech stack or runtime (for example, an embedded React client vs Node server code)
 - dominant file-type patterns (for example, resolvers vs repositories vs jobs)
 - build or tooling configuration (separate tsconfigs, bundlers, framework configs)
 - domain boundary or API surface
 
-Record distinct sub-areas in the coverage gap assessment. A scoped `AGENTS.md` recommendation for a large directory
-should enumerate the major sub-areas and their conventions, not just report the total file count.
+When you find heterogeneity, assess its major subdirectories starting at depth 1–2 before writing a single broad recommendation. If the first pass still leaves a sub-area that is clearly heterogeneous, keep decomposing deeper until the distinct conventions are visible or the analysis stops yielding materially different guidance. A homogeneous area — even a large one — needs only one recommendation; there are no distinct sub-areas to split out.
+
+Record distinct sub-areas in the coverage gap assessment. A scoped `AGENTS.md` recommendation for a heterogeneous area should enumerate the major sub-areas and their conventions, not just report a total file count.
 
 ## Secondary Indicators (strengthen the case but not sufficient alone)
 
@@ -81,13 +96,15 @@ For each directory meeting 1+ primary indicators:
 **Severity mapping:**
 
 - **High:** Primary indicators 1-3 (own build, different stack, public API) — these are clear gaps
-- **Medium:** Primary indicators 4-5 (domain boundary, large codebase) — beneficial but not urgent
+- **Medium:** Primary indicators 4-5 (domain boundary, significant codebase) — beneficial but not urgent
 
 ## Exclusions
 
 Do NOT flag these as needing instructions:
 
 - `node_modules/`, `dist/`, `build/`, `.git/` — generated/external
-- Directories with <5 source files and no build config — too small to warrant overhead
+- Directories that merely follow their parent's conventions with nothing distinct to capture — regardless of size. If an agent working from the nearest ancestor instruction file would already do the right thing here, a nested file would only repeat the parent.
 - Test directories that follow the same patterns as their parent — covered by parent instructions
 - Directories already covered by a parent's scoped rules (e.g., Cursor rule with `globs: packages/cli/**`)
+
+**Anti-sprawl:** Do not recommend an instruction file for a directory just because it contains many files. File count alone is never a trigger. If those files all follow the parent's conventions — no distinct domain, no divergent patterns, nothing an agent would get wrong from the ancestor file — the directory is excluded no matter how large it is. The positive trigger is always distinct, non-obvious conventions worth capturing, not size.

package/assets/skills/oat-worktree-bootstrap-auto/SKILL.md

@@ -1,9 +1,9 @@
 ---
 name: oat-worktree-bootstrap-auto
-version: 1.3.0
+version: 1.4.0
 description: Use when an orchestrator/subagent needs autonomous worktree bootstrap. Non-interactive companion to oat-worktree-bootstrap.
 argument-hint: '<branch-name> [--base <ref>] [--path <root>] [--baseline-policy <strict|allow-failing>]'
-disable-model-invocation: true
+disable-model-invocation: false
 user-invocable: false
 allowed-tools: Read, Write, Bash, Glob, Grep
 ---
@@ -12,6 +12,8 @@ allowed-tools: Read, Write, Bash, Glob, Grep
 
 Non-interactive worktree bootstrap for orchestrator and subagent execution flows. Creates or reuses a worktree, runs baseline checks, and reports structured status — all without user prompts.
 
+This skill is **model-invocable** (`disable-model-invocation: false`): orchestrators such as `oat-project-implement` invoke it programmatically when a parallel phase group needs autonomous worktree bootstrap. It is **not** user-invocable (`user-invocable: false`) — it has no interactive surface and is never offered as a slash command.
+
 > ⚠️ **When not to substitute.** This skill is the **only** supported mechanism for orchestrator-driven worktree creation in OAT skills. Host-native isolation primitives — Claude Code's `Agent({ isolation: "worktree" })`, Cursor's worktree-isolated agent invocations, and equivalents in other hosts — are **not** substitutes. They may use the primary repo's checkout (often `main`) as the base regardless of the caller's current branch, silently producing a worktree at the wrong base. OAT orchestrators dispatching mid-run from a feature branch MUST go through this skill with an explicit `--base` so the resulting worktree contains the orchestrator's prior commits.
 
 ## Relationship to oat-worktree-bootstrap

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@open-agent-toolkit/cli",
-  "version": "0.1.3",
+  "version": "0.1.4",
   "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.3"
+    "@open-agent-toolkit/control-plane": "0.1.4"
   },
   "devDependencies": {
     "@types/node": "^22.10.0",