@ainova-systems/intelligence 0.18.0 → 0.19.0

package/engine/sync.sh

@@ -102,6 +102,15 @@ echo ""
 load_targets_cache "$CONFIG_FILE"
 load_yaml_lists "$CONFIG_FILE" rules agents skills ignore submodules
 
+# A package reference that resolves to nothing is left out of every list, so
+# nothing renders from it — but it is a manifest error, not a directory that
+# does not exist yet, and it is named rather than skipped in silence.
+while IFS=$'\037' read -r section src state _dir alias holders; do
+    [ -n "$section" ] || continue
+    source_reference_problem_var "$state" "$alias" "$holders"
+    echo "WARNING: sources.$section '$src' $IS_SOURCE_PROBLEM — skipped; 'intelligence status --check' reports it" >&2
+done <<< "${IS_YL_UNRESOLVED:-}"
+
 # Lint frontmatter across all source files (rules, agents, skills).
 # Catches issues like unquoted colons that strict YAML consumers reject.
 LINT_FILES=()

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ainova-systems/intelligence",
-  "version": "0.18.0",
+  "version": "0.19.0",
   "description": "Build, version and distribute AI agent intelligence across your organization — one CLI, versioned Intelligence Packages, and a sync engine for Claude Code, Cursor, Copilot, Codex, Pi and OpenCode.",
   "bin": {
     "intelligence": "bin/intelligence.js"

package/packages/sync/references/adapters.md

@@ -70,8 +70,9 @@ sync_to_mytool() {
 }
 ```
 
-The contract accepts the configured repo-relative output path and emits only
-records through these helpers:
+The contract accepts the configured repo-relative output path and, as an optional
+second argument, the absolute path of `intelligence.yaml`. It emits only records
+through these helpers:
 
 | Record | Meaning |
 |---|---|
@@ -83,6 +84,17 @@ records through these helpers:
 | `adapter_contract_preserve <path>` | Settings or state preserved in place and included in the initial backup |
 | `adapter_contract_ignore <pattern>` | Exact `.gitignore` pattern managed on enable/init |
 | `adapter_contract_include <pattern>` | Exact negated `.gitignore` pattern managed on enable/init |
+| `adapter_contract_unignore <pattern>` | Exact `.gitignore` pattern removed from the CLI-managed block on enable/init |
+
+The manifest argument is for Git policy only: a target field may decide whether
+generated output is ignored, as `targets.copilot.commit_output` does. Ownership
+records never depend on it. The engine and the sync cache read ownership alone
+and pass no manifest, so a contract given none declares its default policy;
+init, enable and `status --check` pass it. `unignore` is how a configuration
+withdraws a default `ignore` an earlier init or enable already wrote: the CLI
+removes that exact line below its `# Intelligence generated state and tool
+output` header, never a line the project wrote above it, and `status --check`
+reports one still present.
 
 All paths are repository-relative. The CLI refuses missing, malformed, unsafe,
 or unsupported contracts before enabling or syncing an adapter. `owned` and
@@ -108,7 +120,14 @@ reads are not part of any contract.
 For an existing `.vscodeignore`, `.npmignore`, or `.dockerignore`, enable/init
 also excludes the configured adapter output plus its `owned`, `managed`, and
 `legacy` paths from published or build artifacts. This packaging policy is
-separate from the narrower Git policy expressed by `ignore` and `include`.
+separate from the narrower Git policy expressed by `ignore`, `include` and
+`unignore`.
+
+The Copilot adapter ignores its four generated directories — `instructions/`,
+`prompts/`, `agents/` and `skills/` under its output — like Cursor and Claude
+Code ignore theirs, and never `.github/` itself. `targets.copilot.commit_output:
+true` keeps them tracked for Copilot on github.com; the setting is defined in
+[Generated output and version control](conventions.md#generated-output-and-version-control).
 
 The engine calls:
 
@@ -120,7 +139,7 @@ The engine has already loaded `engine/lib/common.sh` before it sources the adapt
 
 ## Source model
 
-`sources.rules`, `sources.agents` and `sources.skills` contain repo-relative directory paths. Packages have already been resolved, fetched and pinned by the CLI, so package content appears as an ordinary path under `.intelligence/packages/`. Adapters never perform network access or parse `packages:`.
+`sources.rules`, `sources.agents` and `sources.skills` contain repo-relative directory paths. Packages have already been resolved, fetched and pinned by the CLI, so package content appears as an ordinary path under `.intelligence/packages/`. The manifest may name a package's directory by the package's full name or alias instead; `read_yaml_list` and `load_yaml_list` hand an adapter the store path either way, and leave out a reference that names nothing, so an adapter reads every source the same way. Adapters never perform network access or parse `packages:`.
 
 Iterate a source section in manifest order:
 
@@ -146,7 +165,7 @@ Use the engine library instead of copying parsers or file-handling logic.
 | Function | Purpose |
 |---|---|
 | `resolve_source_dir(repo_root, source)` | Resolve a manifest source to its local directory. |
-| `read_yaml_list(config, section)` | Stream entries from `sources.<section>`. |
+| `read_yaml_list(config, section)` | Stream entries from `sources.<section>`, package references as their store paths. |
 | `load_yaml_list(config, section)` | Same list into `IS_YAML_LIST`, cached — no subprocess on repeat reads. |
 | `get_frontmatter_value(key, file)` | Read a scalar from the first frontmatter block. |
 | `frontmatter_index(keys, file...)` | Read several frontmatter scalars for many files in one pass (`\x1f`-separated rows; special key `paths#` counts `paths:` lines). |
@@ -155,8 +174,10 @@ Use the engine library instead of copying parsers or file-handling logic.
 | `get_model(config, tool, tier)` | Resolve a `frontier`, `heavy`, `standard` or `light` model, including manifest overrides. |
 | `get_model_default(tool, tier)` | Read the built-in model default. |
 | `load_model_tiers(config, tool)` / `resolve_model_var(tier)` | Resolve the four standard tiers once, then map per file without subprocesses. |
-| `copy_skill_bundle(src, dest)` | Copy `SKILL.md` and all resources safely, normalize Markdown and quote free-text frontmatter. |
+| `map_effort(tool, effort)` / `map_effort_var(tool, effort)` | The level a tool's native effort field receives for a neutral `effort:` (`IS_EFFORT`); empty when the value is absent or off the scale, or the tool has no field. |
+| `copy_skill_bundle(src, dest)` | Copy `SKILL.md` and all resources safely, normalize Markdown, quote free-text frontmatter, and keep a valid `effort:` as written, as the shared skills tree does. |
 | `copy_skill_bundle_dirs(dest_root, src...)` | Batch form: copy every skill directory into `dest_root/<name>` with one copy and one finalize pass. |
+| `copy_skill_bundle_dirs_for(tool, dest_root, src...)` | The batch form for a tree one tool reads: `SKILL.md`'s `effort:` becomes that tool's level, or is removed when it has none. |
 | `sync_open_skill_dirs(root, config, dest)` | Own and populate a shared Agent Skills directory such as `.agents/skills/`, deriving Codex's `agents/openai.yaml` for a skill with `disable-model-invocation: true`. |
 | `finalize_output_file(file)` | Expand layout tokens and normalize line endings; required for every emitted text file. |
 | `finalize_output_files(file...)` / `finalize_copy_files(dest, src...)` | Batch forms: finalize in place, or copy-and-finalize into a directory, in one process. |
@@ -164,7 +185,7 @@ Use the engine library instead of copying parsers or file-handling logic.
 | `get_target_field(config, target, field)` | Read another field from the target configuration. |
 | `repo_rel_link(root, path)` | Produce a stable repo-relative link for a committed output. |
 
-`lint_frontmatter` is run across all inputs by the engine before adapters execute (batched as `lint_frontmatter_files`). It warns about common YAML hazards; adapters should not duplicate that pass.
+`lint_frontmatter` is run across all inputs by the engine before adapters execute (batched as `lint_frontmatter_files`). It warns about common YAML hazards and about an `effort:` off the neutral scale, naming the source once; adapters should not duplicate that pass, and render such a value as absent without a second warning.
 
 Prefer the batched forms inside per-file loops: a process spawn costs tens of milliseconds on Git Bash for Windows, so one-awk-per-file adapters turn large projects into minutes of process creation. The built-in adapters are the reference for the pattern.
 
@@ -216,7 +237,7 @@ Skills follow the [Agent Skills standard](https://agentskills.io). Copy each ski
 copy_skill_bundle "$source_skill_dir" "$output_dir/skills/$skill_name"
 ```
 
-Do not use plain `cp` for skill bundles. `copy_skill_bundle` preserves non-Markdown assets, avoids materializing symlink targets, normalizes Markdown, expands layout tokens and quotes `description` and `argument-hint` where strict YAML readers require strings.
+Do not use plain `cp` for skill bundles. `copy_skill_bundle` preserves non-Markdown assets, avoids materializing symlink targets, normalizes Markdown, expands layout tokens and quotes `description` and `argument-hint` where strict YAML readers require strings. It renders `effort:` as the shared tree does; a tree only one tool reads uses `copy_skill_bundle_dirs_for <tool>`, so the copy carries that tool's level or no effort at all.
 
 Antigravity, Codex, Pi and OpenCode share `.agents/skills/`. Any adapter writing that open-standard directory must call `sync_open_skill_dirs`; it is the single lifecycle owner for immediate skill subdirectories.
 
@@ -229,11 +250,20 @@ Source agents use tool-neutral fields:
 name: backend-developer
 description: "Implements backend features"
 tier: heavy
+effort: high
 access: full
 ---
 ```
 
-Map `tier` through `get_model`, not a hardcoded model name. Transform `access: full|readonly` into the target tool's native permission model. Preserve the body as the agent's instructions.
+Map `tier` through `get_model`, not a hardcoded model name. Map `effort` through `map_effort_var` and emit the tool's own effort key only when it returns a level; never derive an effort from the tier, and never copy the source `effort:` line into a tool without a field. Transform `access: full|readonly` into the target tool's native permission model. Preserve the body as the agent's instructions.
+
+| Built-in | `effort:` rendering | Evidence, checked 2026-10-07 |
+|---|---|---|
+| `claude` | `effort:` in agents and skills; `ultra` becomes `max` | [Subagents](https://code.claude.com/docs/en/sub-agents) and [skills](https://code.claude.com/docs/en/skills) accept `low`, `medium`, `high`, `xhigh`, `max`; [model configuration](https://code.claude.com/docs/en/model-config) falls back to the highest level the active model supports at or below the one set |
+| `codex` | `model_reasoning_effort` in `.codex/agents/*.toml`, every level; no per-skill effort | The [configuration reference](https://learn.chatgpt.com/docs/config-file/config-reference) lists `low`, `medium`, `high`, `xhigh`, `max`, `ultra`, with availability depending on the model |
+| `copilot`, `cursor` | none, in agents or in their own skill copies | No per-agent effort field is rendered, so the tool's own setting applies |
+| `opencode`, `antigravity`, `pi` | none in agents | Same; their skills come from the shared tree |
+| shared `.agents/skills/` | a valid level as written | The open-standard tree several tools read keeps the neutral value |
 
 Built-ins currently emit Claude and Cursor Markdown, Copilot `.agent.md`, Codex TOML, Pi prompt templates and OpenCode Markdown subagents. Read the closest built-in adapter before implementing a new transformation.
 

package/packages/sync/references/conventions.md

@@ -71,6 +71,8 @@ sources:
     - "intelligence/skills"
 ```
 
+A package's directory may also be named by the package instead of its store path: `@ainova-systems/sync/rules` names folder `rules` of the package `packages:` declares as `@ainova-systems/sync`, and `sync:rules` names it through the alias that package declares (`intelligence package alias @ainova-systems/sync sync`). Both render exactly as the store path, and both are installed package content like it: edit that content in its source repository. The CLI writes store paths and never rewrites a reference a person wrote; an `@scope/name/...` entry for a package `packages:` does not declare is an ordinary project path.
+
 Missing project-owned source directories are skipped, so a package-only project need not create empty `rules/`, `agents/` or `skills/` directories. Source order matters: later files with the same artifact name overwrite earlier ones. Package sources are wired before project sources so the project can override a package artifact deliberately.
 
 Project-owned entries are managed with `intelligence source add|remove|list` rather than by hand — it validates the path against the way the engine resolves it and prints the resulting order. `add` appends by default; `--before <entry>` / `--after <entry>` place content that should behave like a package ahead of the project's own directories.
@@ -192,9 +194,25 @@ Do not instruct an agent to read rules or restate their content. Claude loads it
 | `standard` | `sonnet` | `inherit` | `gpt-6.1-sol` | `anthropic/claude-sonnet-5-5` | `flash` | review, validation, analysis |
 | `light` | `sonnet` | `inherit` | `gpt-6-luna` | `anthropic/claude-sonnet-5-5` | `flash` | lookups and simple formatting |
 
-Codex also receives a reasoning effort per tier — `xhigh`, `high`, `medium`, `low` — which is what separates `frontier` from `heavy` in Codex. Copilot has no effort field, so its `frontier` and `heavy` agents are identical. Claude's Haiku 4.5 is retiring with no successor announced, so `light` shares `standard`'s Sonnet in Claude and OpenCode; Cursor and Antigravity have fewer native levels than there are tiers, so several tiers share one value there too.
+A tier selects the model only and never sets a reasoning effort — that is `effort:`, below. Where two tiers share a model they therefore render identical agents: `frontier` and `heavy` in Codex and Copilot. Claude's Haiku 4.5 is retiring with no successor announced, so `light` shares `standard`'s Sonnet in Claude and OpenCode; Cursor and Antigravity have fewer native levels than there are tiers, so several tiers share one value there too.
+
+The vocabulary is tool-neutral. Adapters resolve it through `get_model()`. Override a default under `models.<tool>.<tier>` in `intelligence.yaml` only when the project needs a pin; sync reports drift when that override differs from the current default. Another tier name works only where `models.<tool>.<tier>` defines it; elsewhere — a typo, as a rule — the agent renders with an empty `model` and sync warns once per tool and tier.
+
+### Effort mappings
+
+`effort:` asks for a reasoning effort, independently of the model `tier` selects. The scale, lowest first, is `low`, `medium`, `high`, `xhigh`, `max`, `ultra`, matched exactly. Write it only where an agent or skill needs a level other than the tool's own setting: without it, no tool receives an effort.
+
+| `effort:` | Claude agents and skills (`effort:`) | Codex agents (`model_reasoning_effort`) | Copilot, Cursor, OpenCode, Antigravity and Pi agents |
+|---|---|---|---|
+| `low`, `medium`, `high`, `xhigh`, `max` | the same level | the same level | not emitted |
+| `ultra` | `max` | `ultra` | not emitted |
+| absent, empty or off the scale | not emitted | not emitted | not emitted |
+
+A level a tool lacks becomes the nearest lower level it has. Which levels a particular model supports is left to the tool: a manifest can override the model, and Claude Code itself falls back to the highest level the active model supports at or below the one requested. Tools without a per-agent effort field keep their own setting.
 
-The vocabulary is tool-neutral. Adapters resolve it through `get_model()`. Override a default under `models.<tool>.<tier>` in `intelligence.yaml` only when the project needs a pin; sync reports drift when that override differs from the current default.
+A value off the scale — `hiigh`, `High` — never fails a sync. Sync prints a `WARNING:` line naming the file, the value and the allowed levels — `sync --compact` and `init` show it too — and renders the artifact as if `effort:` were absent, because packages arrive from many sources and one author's typo must not block another team. An empty `effort:` is simply absent.
+
+Skills take the same field. `.claude/skills/` receives Claude's level, the shared `.agents/skills/` tree keeps a valid level as written, and Copilot's and Cursor's skill copies carry none; an empty or off-scale value is removed from every copy. Codex has no per-skill effort.
 
 ### Access mappings
 
@@ -252,9 +270,9 @@ argument-hint: "<route-name>"
 4. Report the changed route and verification.
 ```
 
-Standard optional fields (`license`, `compatibility`, `metadata`, `allowed-tools`) and tool extensions pass through unchanged. A tool ignores fields it does not understand.
+Standard optional fields (`license`, `compatibility`, `metadata`, `allowed-tools`) and tool extensions pass through unchanged. A tool ignores fields it does not understand. `effort:` is the exception: sync renders it per tool, as [Effort mappings](#effort-mappings) describes.
 
-`disable-model-invocation: true` makes a skill one only the owner starts, as a slash command: use it for a procedure that changes versions, the lock or generated outputs, where an agent selecting it unasked is the failure. Claude Code, Cursor and Copilot read the field itself; Codex does not, so sync writes `agents/openai.yaml` with `allow_implicit_invocation: false` beside the skill in `.agents/skills/`. Keep the source to the field — a skill that ships its own `agents/openai.yaml` keeps it unchanged.
+`disable-model-invocation: true` makes a skill one only the owner starts, as a slash command: use it for a procedure that changes versions, the lock or generated outputs, where an agent selecting it unasked is the failure. Claude Code, Cursor and Copilot read the field itself; Codex does not, so sync writes `agents/openai.yaml` with `allow_implicit_invocation: false` beside the skill in `.agents/skills/`. Keep the source to the field. A skill that ships its own `agents/openai.yaml` keeps everything else in it: sync adds the policy when the file sets none, and refuses one that sets it otherwise or not as a plain `allow_implicit_invocation: false` directly under `policy:`.
 
 These limits reject a skill instead of degrading it:
 
@@ -328,7 +346,7 @@ Every line enters a finite context budget. Prefer subtraction, consolidation and
 
 `AGENTS.md` is regenerated by the `agents` adapter. Its optional static header is `targets.agents.header` in `intelligence.yaml`; generated rule, agent and skill sections follow it. Commit `AGENTS.md` when it is the project's shared canonical context.
 
-By default, commit the manifest, lock, project-owned content, `AGENTS.md`, and shared `.github/` output. Ignore the restorable package store and tool output owned by enabled adapters. `intelligence init` and `intelligence adapter enable` add these patterns without ignoring shared tool roots or settings:
+By default, commit the manifest, lock, project-owned content and `AGENTS.md`. Ignore the restorable package store and tool output owned by enabled adapters. `intelligence init` and `intelligence adapter enable` add these patterns without ignoring shared tool roots or settings, and re-running `intelligence init` in an existing project applies a policy that changed since it last ran:
 
 ```gitignore
 # CLI-managed package store
@@ -363,9 +381,26 @@ GEMINI.md
 # Generated OpenCode agents. Commands share a directory with hand-authored
 # files, so they remain tracked unless the project chooses exact file ignores.
 .opencode/agents/
+
+# Generated Copilot content and its legacy root file. `.github/` also holds
+# workflows, templates and hand-written files, so only these are ignored.
+.github/instructions/
+.github/prompts/
+.github/agents/
+.github/skills/
+.github/copilot-instructions.md
 ```
 
-Copilot output lives under `.github/` and is committed with other repository-level GitHub configuration. Do not ignore `.github/` wholesale. `AGENTS.md` is also committed so every clone has the shared tool-neutral entry point before sync.
+Copilot output follows the same policy as Cursor and Claude Code: Copilot in the editor reads the generated files from disk after sync, so they are not committed. `.github/copilot-instructions.md` is treated like `CLAUDE.md` and `.cursorrules`: onboarding migrates it into project rules, and a copy left behind makes Copilot ignore `AGENTS.md`. Never ignore `.github/` wholesale. Copilot on github.com — code review and the coding agent — reads the repository instead of a sync; a project that wants it to see the rules, agents and skills sets `commit_output: true` on its Copilot target and runs `intelligence init`, which takes these five patterns back out of the CLI-managed block (lines above its header stay the project's own):
+
+```yaml
+targets:
+  copilot: { enabled: true, output: ".github", commit_output: true }
+```
+
+`commit_output` accepts `true` or `false`; omitting it means `false`, and any other value makes sync refuse. Turning it off again restores the patterns on the next `intelligence init`.
+
+`AGENTS.md` stays committed by default: it is the tool-neutral fallback every tool reads, and a fresh clone has it only when it is committed, before anyone has synced.
 
 Git tracking and release packaging are separate policies. When a project
 already has `.vscodeignore`, `.npmignore`, or `.dockerignore`, the CLI appends a
@@ -377,9 +412,11 @@ files are not created.
 An ignore rule does not untrack a file already in Git. After init or adapter
 enable, the CLI reports each affected tracked path that remains in the
 worktree with an exact `git rm --cached -- '<path>'` command; this preserves
-the local file while removing it from the index. Legacy root entry points
-quarantined into the initial backup are ordinary worktree deletions to review
-and stage, not candidates for `git rm --cached`.
+the local file while removing it from the index. A project that committed its
+Copilot output while the policy kept it tracked gets these commands for each
+generated file the first time `intelligence init` adds the Copilot patterns.
+Legacy root entry points quarantined into the initial backup are ordinary
+worktree deletions to review and stage, not candidates for `git rm --cached`.
 
 Before release, inspect the packager's actual file list. An npm `files`
 allowlist can force inclusion despite `.npmignore`, and a Dockerfile-specific

package/packages/sync/references/onboarding-migration.md

@@ -50,7 +50,7 @@ Migrate meaning, not tool syntax:
 | Root `AGENTS.md`, `CLAUDE.md`, `.cursorrules`, Copilot root instructions | Split verified guidance by topic into rules; keep local machine preferences in a gitignored root file only when no adapter representation exists |
 | `.claude/rules/*.md` | Rule; preserve valid `paths:` |
 | `.cursor/rules/*.mdc` | Rule; rename `globs:` to `paths:` and remove `alwaysApply:` |
-| Claude/Cursor/Copilot agents | Agent; map native model/readonly/tool fields back to `tier:` and `access:` |
+| Claude/Cursor/Copilot agents, Codex `.codex/agents/*.toml` | Agent; map native model/readonly/tool fields back to `tier:` and `access:`, and a native effort level (`effort:`, `model_reasoning_effort`) back to `effort:` |
 | Claude/Cursor/Copilot skills or commands | Skill when the procedure is repeated, multi-step, stable, and verifiable; otherwise a rule or no artifact |
 | Pi/OpenCode/Codex prompt artifacts | Rule, agent, or skill according to responsibility, after removing tool-specific wrappers |
 
@@ -78,8 +78,8 @@ the enabled adapters. Treat CLI-reported tracked ignored paths that still exist
 locally as unresolved until the user approves the exact `git rm --cached`
 commands. A quarantined tracked legacy path is already a worktree deletion;
 review and stage that deletion normally instead of using `git rm --cached`. Preserve
-`AGENTS.md`, `.github/`, shared settings, and unrelated files under shared tool
-roots in Git, while excluding development-only Intelligence content from
+`AGENTS.md`, hand-written `.github/` files, shared settings, and unrelated files
+under shared tool roots in Git, while excluding development-only Intelligence content from
 published artifacts. Inspect the packager's actual file list before release;
 do not infer package or Docker context contents from Git status.
 

package/packages/sync/skills/intelligence-learn-from-repository/SKILL.md

@@ -100,8 +100,9 @@ explains itself well.
     `IS_STATUS=ok`, a clean final check, and no `onboarding is pending` header
     after accepted migration.
 11. Report what was created, updated, removed, or deliberately kept. Remind the
-    user to commit source, manifest, lock, `AGENTS.md`, and shared `.github/`
-    changes. Keep or remove the initial backup only by separate user approval.
+    user to commit source, manifest, lock and `AGENTS.md` changes, plus Copilot's
+    `.github/` output only when `targets.copilot.commit_output` is `true`. Keep or
+    remove the initial backup only by separate user approval.
 
 ## Later learning
 

package/packages/sync/skills/intelligence-review-context/SKILL.md

@@ -16,7 +16,8 @@ go through `intelligence-update-context`; this skill owns their review criteria.
 1. Read `<manifest>` and enumerate its configured rule, agent, and skill sources.
    Read the `intelligence-authoring` rule and
    `<module>/references/conventions.md`. Review project-owned sources; an installed
-   package finding belongs upstream. In a package's own repository, review its
+   package finding — an entry naming a package's directory, however spelled —
+   belongs upstream. In a package's own repository, review its
    authoritative source tree. Do not audit generated output prose. Its byte count
    is the metadata-only exception.
 2. Record source line and byte counts, and git history when available: first

package/packages/sync/skills/intelligence-update-context/SKILL.md

@@ -15,8 +15,10 @@ the same procedure. Updating the layer can create a new artifact.
 
 1. Read `<manifest>` and resolve its `sources.rules`, `sources.agents`, and
    `sources.skills` directories. `<content-dir>` names the project's content
-   directory; `<module>` is installed package content. Read the
-   `intelligence-authoring` rule and `<module>/references/conventions.md`.
+   directory; `<module>` is installed package content, and so is every entry
+   naming a package's directory by store path, full name or alias. Read the
+   `intelligence-authoring` rule and `<module>/references/conventions.md`, which
+   defines those spellings.
    Edit project-owned sources, never installed packages or generated output.
    When working in a package's own repository, use its authoritative source tree.
 

package/packages/sync/skills/intelligence-update-context/references/agents.md

@@ -8,7 +8,10 @@
    difficulty justifies the most capable and most expensive model. Check the
    target's actual permission mapping when external read tools are required.
    If native read-only restrictions exclude those tools, use `full` only with a
-   clear read-only boundary in the body.
+   clear read-only boundary in the body. The tier selects the model only: add
+   `effort:` (`low`, `medium`, `high`, `xhigh`, `max`, `ultra`) only when the
+   role needs a reasoning effort other than the tool's own setting, as the
+   authoring conventions' effort mappings describe.
 3. Keep the body thin: Expertise, Boundaries, and Build & Verify. Carry its own
    completion criteria and limitations. Reference constraints by name instead
    of copying rules, and put reusable procedures in skills.
@@ -27,7 +30,8 @@ skills:
 ```
 
 Quote free-text YAML strings and escape embedded quotes; malformed scalars can
-prevent discovery. Verify every skill binding resolves, the tier and access use
-the supported vocabulary, and the body defines a role rather than a checklist.
+prevent discovery. Verify every skill binding resolves, the tier, effort and
+access use the supported vocabulary, and the body defines a role rather than a
+checklist; sync warns about an effort it does not recognize and ignores it.
 Apply the agent size and description limits from the authoring conventions,
 then return to the shared sync and verification steps.

package/packages/sync/skills/intelligence-update-context/references/skills.md

@@ -26,7 +26,9 @@ agent: <existing-agent>
 ---
 ```
 
-Omit optional fields that do not apply. Add the skill to its matching agent's
+Omit optional fields that do not apply. Add `effort:` only when the procedure
+needs a reasoning effort other than the session's, using the scale in the
+authoring conventions' effort mappings. Add the skill to its matching agent's
 `skills:` list when that agent is project-owned; propose an upstream change for
 a package-owned agent instead of editing the installed copy. Verify bindings,
 relative resource links, executable steps, and final success criteria. Apply the