@open-agent-toolkit/cli 0.1.18 → 0.1.19

package/assets/public-package-versions.json

@@ -1,6 +1,6 @@
 {
-  "cli": "0.1.18",
-  "docs-config": "0.1.18",
-  "docs-theme": "0.1.18",
-  "docs-transforms": "0.1.18"
+  "cli": "0.1.19",
+  "docs-config": "0.1.19",
+  "docs-theme": "0.1.19",
+  "docs-transforms": "0.1.19"
 }

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

@@ -1,6 +1,6 @@
 ---
 name: oat-agent-instructions-apply
-version: 1.6.1
+version: 1.6.2
 description: Run when you have an agent instructions analysis artifact and want to generate or update instruction files. Creates a branch, generates files from templates, and optionally opens a PR.
 disable-model-invocation: true
 user-invocable: true
@@ -217,6 +217,7 @@ recommendation so plan review and generation stay aligned to the same pack file.
 1. **AGENTS.md first** — the canonical, provider-agnostic file
 2. **CLAUDE.md** — if claude provider is active, ensure `@AGENTS.md` import exists
 3. **Glob-scoped rules** — author once in canonical format at `.agents/rules/{name}.md` with YAML frontmatter (`description`, `globs`, `activation`)
+   - `activation` MUST be one of `always`, `glob`, `agent-requested`, `manual` — any other value (e.g. `auto`) is rejected by `oat sync`. Use `glob` (with `globs`) for file-targeted rules; see `frontmatter/canonical-rule.md` for the full activation matrix.
    - Provider-specific rule files are generated by `oat sync --scope project`
    - Do not hand-author `.claude/rules/*.md`, `.cursor/rules/*.mdc`, or `.github/instructions/*.instructions.md`
 4. **Copilot shim** — if copilot provider is active, generate `.github/copilot-instructions.md` from `frontmatter/copilot-shim.md` template
@@ -320,7 +321,7 @@ For each approved recommendation, in the order from Step 2:
    - `Claim Corrections` replaces stale claims in updated files
 6. For glob-scoped rules:
    - Write the canonical markdown once to `.agents/rules/{name}.md`
-   - Include canonical rule frontmatter (`description`, `globs`, `activation`) instead of provider-specific wrappers
+   - Include canonical rule frontmatter (`description`, `globs`, `activation`) instead of provider-specific wrappers. `activation` must be one of `always`, `glob`, `agent-requested`, `manual` (not `auto`); use `glob` with `globs` for file-targeted rules. See `references/instruction-file-templates/frontmatter/canonical-rule.md`.
    - After writing canonical rules, run `oat sync --scope project` to generate provider-specific rule files
    - Verify the generated provider files exist for each active provider instead of maintaining them by hand
    - Verify each generated provider file is trackable with `git check-ignore`; if any generated file is ignored,
@@ -503,5 +504,6 @@ Apply complete.
 - Bundled Cursor-specific format reference: `references/docs/cursor-rules-files.md`
 - Analysis artifact: `.oat/repo/analysis/agent-instructions-*.md`
 - Templates: `references/instruction-file-templates/`
+- Canonical rule frontmatter reference: `references/instruction-file-templates/frontmatter/canonical-rule.md`
 - Apply plan template: `references/apply-plan-template.md`
 - Tracking script: `.oat/scripts/resolve-tracking.sh`

package/assets/skills/oat-agent-instructions-apply/references/instruction-file-templates/frontmatter/canonical-rule.md

@@ -0,0 +1,93 @@
+# Canonical Rule Frontmatter
+
+Canonical glob-scoped rules live at `.agents/rules/{name}.md`. This is the **single source you author** — `oat sync --scope project` reads it and generates the provider-specific rule files (`.claude/rules/*.md`, `.cursor/rules/*.mdc`, `.github/instructions/*.instructions.md`). Do not hand-author those provider files.
+
+The canonical frontmatter is provider-agnostic and uses three fields: `description`, `globs`, and `activation`.
+
+## Frontmatter Fields
+
+| Field         | Required    | Type     | Description                                                                            |
+| ------------- | ----------- | -------- | -------------------------------------------------------------------------------------- |
+| `activation`  | **Yes**     | enum     | One of `always`, `glob`, `agent-requested`, `manual`. See matrix below.                |
+| `globs`       | Conditional | string[] | Glob patterns the rule targets. **Required when `activation: glob`.**                  |
+| `description` | Conditional | string   | Short purpose. **Required when `activation: agent-requested`**; recommended otherwise. |
+
+> The `activation` value is validated. The only accepted values are
+> `always`, `glob`, `agent-requested`, and `manual`. Any other value
+> (e.g. `auto`) is rejected by `oat sync --scope project`.
+
+## Activation Matrix
+
+| `activation`      | When to use                                                      | Required companion fields |
+| ----------------- | ---------------------------------------------------------------- | ------------------------- |
+| `glob`            | Rule applies to files matching specific patterns                 | `globs`                   |
+| `always`          | Repo-wide rule that should be in every session                   | —                         |
+| `agent-requested` | Agent decides relevance from the description (no file targeting) | `description`             |
+| `manual`          | Opt-in only — user explicitly invokes the rule                   | —                         |
+
+Selection rule of thumb: if the recommendation targets file patterns, use `activation: glob` with `globs`. Use `always` only for genuinely repo-wide guidance, `agent-requested` for description-driven rules with no glob, and `manual` for opt-in references.
+
+## Examples
+
+### Glob-scoped (most common)
+
+```yaml
+---
+description: 'Firebase handler trigger/registration conventions'
+activation: glob
+globs:
+  - 'src/functions/**/*.ts'
+---
+# {Rule Title}
+
+{ Rule body — identical to glob-scoped-rule.md template body }
+```
+
+### Always-on
+
+```yaml
+---
+description: 'Repo-wide security non-negotiables'
+activation: always
+---
+# {Rule Title}
+
+{ Rule body }
+```
+
+### Agent-requested (no globs)
+
+```yaml
+---
+description: 'Patreon integration gotchas — apply when touching billing flows'
+activation: agent-requested
+---
+# {Rule Title}
+
+{ Rule body }
+```
+
+### Manual (opt-in)
+
+```yaml
+---
+description: 'One-off migration playbook'
+activation: manual
+---
+# {Rule Title}
+
+{ Rule body }
+```
+
+## How It Maps to Providers
+
+`oat sync --scope project` translates each canonical `activation` to the equivalent provider frontmatter:
+
+| Canonical         | Claude (`.claude/rules/*.md`) | Cursor (`.cursor/rules/*.mdc`)       | Copilot (`.github/instructions/*`) |
+| ----------------- | ----------------------------- | ------------------------------------ | ---------------------------------- |
+| `glob`            | `paths`                       | `alwaysApply: false` + `globs`       | `applyTo`                          |
+| `always`          | no frontmatter (always-on)    | `alwaysApply: true`                  | repo-wide `applyTo` / shim         |
+| `agent-requested` | degrades to always-on         | `alwaysApply: false` + `description` | degrades to always-on              |
+| `manual`          | omitted / opt-in              | no frontmatter                       | omitted                            |
+
+See the per-provider frontmatter docs in this directory (`claude-rule.md`, `cursor-rule.md`, `copilot-instruction.md`) for the generated output formats, and `references/docs/rules-files.md` for the full cross-provider deep dive.

package/package.json

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