@ainova-systems/intelligence 0.11.0-rc.7 → 0.11.0-rc.8

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

@@ -1,165 +1,43 @@
 ---
 name: intelligence-update
-description: "Update or migrate intelligence-sync: discover engine, read changelog, run migration chain, verify"
-argument-hint: "[--yes]"
+description: "Interpret an update plan and verify breaking post-conditions"
+argument-hint: "[@scope/name]"
 agent: intelligence-operator
 ---
 
-# Update intelligence-sync
+# Update intelligence
 
-You are the **intelligent driver** of an update. The bash engine is
-deterministic and fail-closed — it never guesses; on any state it cannot
-resolve it prints `IS_STATUS=<code>` and stops. Your job: discover the engine,
-understand what is changing (read the CHANGELOG across the version gap), run
-the migration chain, branch on the status, and **verify afterward**. Ask the
-user only when genuinely ambiguous.
-
-Trigger: the user says something like *"update / migrate intelligence-sync"*.
-They never run shell commands by hand — you do.
-
-## Key facts
-
-- **Umbrella** = whatever directory holds `config.yaml` (`intelligence/`,
-  `Intelligence/`, …). Never assume the name — find it.
-- **Engine = a module discovered by ROLE, not by name**: a directory under
-  the umbrella whose `scripts/sync.sh` **and** `scripts/VERSION` both exist
-  (conventionally `sync/`, but never assume the folder name).
-- **Applied schema version** is the frozen contract key
-  `sync_version` in `config.yaml` (a permanent top-level scalar;
-  absent ⇒ pre-0.3.1). **Engine version** is `<module>/scripts/VERSION`.
-  The gap between them is the set of breaking changes to apply.
-- Pre-0.3.1 projects have the engine flat at `<umbrella>/scripts/` and **no**
-  `sync_version` key. Their frozen `update.sh` fails closed
-  against the modular upstream (changes nothing) — you bootstrap the first hop.
-- The `intelligence-` skill prefix is **reserved** for upstream meta-skills.
+The CLI owns planning and application. This skill interprets the plan, reads
+the changelog across an engine-version gap, obtains approval, and verifies the
+result.
 
 ## Steps
 
-### 0. Vendored setups only
-If the project has a root `intelligence.yaml` (a CLI setup), **stop** — this
-flow is vendored-only. There the engine ships inside the CLI package: run
-`npm i -g @ainova-systems/intelligence@latest`, then `intelligence upgrade`,
-and verify with `intelligence doctor`.
-
-### 1. Locate the umbrella & discover the engine
-Find the dir containing `config.yaml` → `<umbrella>`. Then find the engine by
-role: search `<umbrella>` (one level deep) for a directory `<M>` with both
-`<M>/scripts/sync.sh` and `<M>/scripts/VERSION`.
-
-- Several candidates → pick the one with the highest `scripts/VERSION`.
-- A module engine exists → use it; **never** fall back to a flat
-  `<umbrella>/scripts/` even if present (that's stale legacy).
-- No module engine, only flat `<umbrella>/scripts/` (or nothing) → this is a
-  pre-0.3.1 / un-bootstrapped project; go to step 2's bootstrap.
-- No `config.yaml` at all → not bootstrapped; point the user at upstream
-  `INIT.md` and stop.
-
-### 2. Fetch upstream (read-only) — do NOT write into the project yet
-Clone upstream into a temp dir (default
-`https://github.com/ainova-systems/intelligence-sync`, or the user's
-`REPO_URL`/fork). The upstream module is always `intelligence/sync/`.
-
-```
-git clone --depth=1 <repo> <tmp>
-```
-
-**Make no changes to the project before step 3's confirmation.** In
-particular do not copy anything into `<umbrella>/sync` yet — that would
-modify (and could downgrade) an already-modular project even if the user then
-declines. The temp clone is only for reading the CHANGELOG and as the source
-for the eventual write.
-
-### 3. Understand what is changing (changelog-aware)
-Determine the project's current version = the `sync_version`
-value in `config.yaml`, or `0.0.0` if the key is absent (pre-0.3.1). The
-engine version = `<tmp>/intelligence/sync/scripts/VERSION`.
-
-Read `<tmp>/CHANGELOG.md`. For every release in the range
-**`current < release <= engine`** (inclusive of the target release — its
-entry holds the destination's breaking post-conditions), read its entry. Pay
-special attention to any **`### Breaking`** subsection (the
-machine-distinguishable marker). Build a short list of breaking items, new
-migrations, and anything to verify afterward. Surface it to the user; without
-`--yes`, let them confirm before any write.
-
-### 3a. Ensure the engine to run (only now, post-confirmation)
-- **Modular project** (a module engine was discovered in step 1): run *its*
-  `update.sh` — at the discovered module dir, whatever its name. `update.sh`
-  re-clones upstream internally, shows the diff, and is authoritative; do not
-  hand-copy over the module.
-- **No module engine** (pre-0.3.1 flat or un-bootstrapped): only here create
-  the module from the temp clone, and only after confirmation:
-  ```
-  mkdir -p <umbrella>/sync
-  cp -r <tmp>/intelligence/sync/. <umbrella>/sync/
-  ```
-  then run `<umbrella>/sync/scripts/update.sh`.
-
-### 4. Run the engine
-Run the `update.sh` of the engine determined in 3a — the **discovered module
-dir** for a modular project (whatever its name), or the just-created
-`<umbrella>/sync` for the legacy bootstrap path:
-
-```
-bash <engine-module>/scripts/update.sh --yes   # omit --yes to confirm the diff
-```
-Capture stdout; find the last `IS_STATUS=<code> [IS_DETAIL=...]` line.
-
-### 5. Branch on `IS_STATUS`
-
-| Code | Meaning | Action |
-|---|---|---|
-| `ok` | Already current | Go to step 6. |
-| `migrated` | Migration chain applied | Go to step 6; note the relocation/changes. |
-| `aborted-incomplete` | Staged module incomplete; legacy intact (safe) | Re-run step 2–4 once (clone hiccup). Persists → show output, stop, don't hand-fix. |
-| `ahead-of-engine` | Project schema newer than this engine | Do **not** downgrade. Point `REPO_URL` at the correct/newer upstream, or accept it's already ahead. Stop. |
-| `needs-update` | Pending breaking changes (sync refused) | Expected pre-migration; proceed — `update.sh` is the migrator. If it persists *after* update, investigate. |
-| `config-missing` | No `config.yaml` | Not bootstrapped — direct user to `<umbrella>/sync/INIT.md`. Stop. |
-| `error` | Engine couldn't proceed | Show message; check `REPO_URL`. Stop. |
-| *(no status)* | Engine crashed before contract | Show full output; don't modify the tree. Stop. |
-
-On any failure code, first re-read the upstream `CHANGELOG.md` entries for `current < release <= engine` (esp. `### Breaking`) — the breaking change usually explains the error and what the user must do — before retrying or escalating.
-
-Genuinely **ambiguous** tree (e.g. both a legacy flat `<umbrella>/scripts/`
-and a populated module, no clear `sync_version`): inspect both,
-summarize the difference, ask the user which is authoritative, apply their
-choice. Never guess.
-
-### 6. Verify (always, after `ok`/`migrated`)
-
-Structural — always:
-- No `intelligence-*` directory directly under `<umbrella>/skills/`
-  (meta-skills live only in the module's `skills/`).
-- Project content intact: `<umbrella>/{rules,agents}/` and any
-  non-`intelligence-` skills untouched.
-- `config.yaml` has `sync_version` equal to the engine
-  `scripts/VERSION`, and `sources.skills` includes the module skills path
-  exactly once.
-
-Changelog-driven — per release crossed:
-- For each **`### Breaking`** item in the crossed range, verify its stated
-  post-condition actually holds (e.g. a removed/renamed file is gone, a
-  config-schema change is reflected). If a breaking item has no verifiable
-  post-condition, state that you could not auto-verify it.
-
-Then regenerate IDE outputs:
-```
-bash <umbrella>/sync/scripts/sync.sh
-```
-Relay any model-drift report. Finally summarize: versions before→after, the
-breaking changes applied, verification result, anything the user must act on.
-Clean up the temp clone.
-
-## Notes
-
-- Everything is **idempotent**. Re-running on a current project is a safe
-  no-op (`IS_STATUS=ok`).
-- Correctness rests on the engine's idempotent structural preconditions, not
-  on the version stamp — a missing/wrong `sync_version` cannot
-  cause a needed migration to be skipped; it only weakens the
-  `ahead-of-engine` guard until re-stamped.
-- Never touch `config.yaml` beyond what the engine does (the idempotent
-  `sources.skills` line and the `sync_version` key). Never
-  move/delete project skills, rules, or agents.
-- Sibling modules beside the engine module are independent — only operate on
-  the discovered engine module.
+1. Run `intelligence update --preview` (or
+   `intelligence update $ARGUMENTS --preview` for one named package). Use its
+   CLI, project, and package sections as the complete plan; do not re-resolve
+   versions independently.
+
+2. If the CLI or project engine version would change, read the authoritative
+   `CHANGELOG.md` at `https://github.com/ainova-systems/intelligence` for every
+   release in **`current < release <= target`**. If it is unavailable, stop
+   before changing versions. Turn every crossed `### Breaking` item into a
+   post-condition to verify.
+
+3. Show the plan and breaking checklist to the user. The command without a
+   mode also shows the plan and prompts; after approval, use `--apply` for an
+   unambiguous non-interactive execution.
+
+4. If the plan reports a newer global CLI, run exactly the npm command it
+   prints after approval, then rerun `intelligence update --preview` with the
+   new executable. Apply the resulting plan with `intelligence update --apply`,
+   or `intelligence update $ARGUMENTS --apply` when one package was requested.
+
+5. An applied update that renders must finish with `IS_STATUS=ok`; preserve and
+   stop on any other status. Then run `intelligence status --check`. Do not run
+   a duplicate sync after `update --apply`. Verify every crossed breaking
+   post-condition directly and report any item that cannot be machine-verified.
+
+Report versions before and after, the applied plan, post-condition results,
+and any remaining action. On a refusal, preserve the full error and stop
+instead of invoking hidden lifecycle operations.

package/packages/sync/docs/ADAPTERS.md

@@ -1,214 +0,0 @@
-# intelligence-sync: Writing a New Adapter
-
-## Overview
-
-An adapter transforms source prompts (from `intelligence/`) into an IDE-specific format. Each adapter is a single bash file, discovered by filename.
-
-## Where adapters live
-
-`sync.sh` scans two directories, in this order:
-
-| Location | Owner | Survives `update.sh`? |
-|---|---|---|
-| `intelligence/sync/scripts/adapters/` | **upstream** — the built-ins shipped with the engine | No — the engine replaces this directory wholesale on every update |
-| `intelligence/adapters/` (beside `config.yaml`) | **the project** | Yes — updates never touch project content |
-
-Write custom adapters in the project's `intelligence/adapters/`. A file placed in the engine's own `adapters/` is deleted by the next `update.sh`, silently and without a diff to notice. A project adapter whose name matches a built-in **overrides** it (sync prints a `NOTE:` line saying so) — an escape hatch for patching a built-in without forking the engine. An adapter that would serve every project is worth contributing upstream instead.
-
-The umbrella folder is not hardcoded anywhere — `intelligence/` above means "whatever directory holds `config.yaml`".
-
-## Quick Start
-
-1. Copy `intelligence/sync/scripts/adapters/_template.sh` to `intelligence/adapters/<name>.sh`
-2. Replace `<name>` placeholders with your adapter name
-3. Implement the `sync_to_<name>()` function
-4. Add target to `config.yaml`:
-   ```yaml
-   targets:
-     <name>: { enabled: true, output: ".<name>" }
-   ```
-5. Run `bash intelligence/sync/scripts/sync.sh <name>` to test
-
-## Adapter Contract
-
-### Required Function
-
-```bash
-sync_to_<name>(repo_root, config_file, output_dir)
-```
-
-This is called by `sync.sh` for each enabled target.
-
-Parameters:
-- `repo_root` -- absolute path to the project root
-- `config_file` -- absolute path to `config.yaml`
-- `output_dir` -- absolute path to output directory (e.g., `/project/.cursor`)
-
-### Available Library Functions
-
-Source `lib/common.sh` for these utilities:
-
-| Function | Description |
-|----------|-------------|
-| `finalize_output_file(file)` | **Call this on every file you write.** Expands layout tokens (`<umbrella>`, `<module>`) and converts CRLF to LF |
-| `normalize_file_to_lf(file)` | LF conversion only — for intermediate files that are not adapter output |
-| `lint_frontmatter(file)` | Warn about unquoted colons, leading tabs, and literal double quotes inside unquoted values (stderr) |
-| `get_frontmatter_value(key, file)` | Extract YAML frontmatter value |
-| `has_frontmatter(file)` | Check for `---` header |
-| `has_paths(file)` | Check for `paths:` field |
-| `get_model(config, ide, tier)` | Resolve model from `models:` override or default |
-| `get_model_default(ide, tier)` | Hardcoded default for `<ide>:<tier>` |
-| `map_access_to_claude_tools(access)` | Tool string for access level |
-| `map_access_to_claude_disallowed(access)` | Disallowed tools string |
-| `read_yaml_list(config, section)` | Read list from `config.yaml` |
-| `resolve_source_dir(repo_root, src)` | Map a source entry to a local dir — `"$repo_root/$src"` for a path, or a shallow clone for a pack reference (`@<name>[/<subpath>]`) or an inline `git+<url>` spec |
-| `source_is_local_path(src)` | True (0) if a source entry is a plain repo-relative path — i.e. neither of the two below. Use this, not a negated `source_is_remote`, whenever a token is about to be pattern-matched against a real directory |
-| `source_is_pack(src)` | True (0) if a source entry references a pack declared under `packs:` (`@<name>`) |
-| `source_is_remote(src)` | True (0) if a source entry is an inline remote `git+` spec |
-| `get_target_field(config, target, field)` | Read a field from a target's config block |
-
-### Transformation Patterns
-
-Each adapter handles three prompt types. Here's how the built-in adapters approach each:
-
-**Rules:**
-
-intelligence-sync routes rule content based on **scope** (always-on vs path-scoped) and on which channels each IDE actually reads, to avoid duplicating content into multiple places.
-
-| Source | `agents` (AGENTS.md) | `claude` | `cursor` | `copilot` | `codex` | `pi` | `opencode` |
-|--------|----------------------|----------|----------|-----------|---------|------|------------|
-| Always-on (no `paths:`) | inlined as canonical | copied as-is | skipped (Cursor reads AGENTS.md) | skipped (Copilot reads AGENTS.md) | skipped (Codex reads AGENTS.md) | skipped (Pi reads AGENTS.md) | skipped (opencode reads AGENTS.md) |
-| Path-scoped (with `paths:`) | listed by name only | copied as-is | `paths:` → `globs:` in `.mdc` | `paths:` → `applyTo:` in `.instructions.md` | not supported by Codex | copied to `.pi/intelligence-sync/rules/` + surfaced by generated extension | not supported (opencode has no native scoping; users may opt in via `instructions:` globs in `opencode.json`) |
-| Listing | full table in AGENTS.md | n/a | n/a | n/a | n/a | extension prompt snippet | n/a |
-
-**Skills:**
-
-Skills follow the [Agent Skills open standard](https://agentskills.io). All supported tools read `SKILL.md` directly — no semantic transformation needed. Skill directories are copied **in full** via `copy_skill_bundle` in `lib/common.sh`: bundled resources (`references/`, `scripts/`, `assets/`) ship alongside `SKILL.md`, because skill bodies point at them by relative path and a copy without them is broken at runtime. Markdown files are LF-normalized; everything else is copied byte-for-byte.
-
-`copy_skill_bundle` also quotes free-text `SKILL.md` frontmatter (`description`, `argument-hint`) for **every** target, not just the strict-YAML ones: `argument-hint: [pr-number]` is a YAML flow *sequence* unquoted, and Claude Code rejects the skill with "argument-hint must be a string" — it vanishes from the picker with no other signal. Adapters must therefore copy skills through this helper rather than plain `cp`.
-
-| Pattern | Used by | Output location |
-|---------|---------|-----------------|
-| Copy skill dirs in full (SKILL.md + bundled resources) | Claude, Cursor, Copilot, Codex, Pi, opencode | `.claude/skills/`, `.cursor/skills/`, `.github/skills/`, `.agents/skills/` (shared by Codex, Pi, opencode) |
-
-**Agents:**
-
-| Pattern | Used by |
-|---------|---------|
-| Transform frontmatter | Claude (`tier`→`model` via `get_model`, `access`→`tools`/`disallowedTools`), Cursor (`tier`→`model` via `get_model`, `access: readonly`→`readonly: true`) |
-| Transform to `.agent.md` | Copilot (`tier`→`model`, `access: readonly`→restricted `tools` array) |
-| Transform to `.toml` | Codex (`name`, `description`, `model`, `model_reasoning_effort` from tier, `sandbox_mode` from access, `developer_instructions`) |
-| Transform to prompt template | Pi (`.pi/prompts/intelligence-agent-<name>.md`; `readonly` becomes prompt guidance, `full` stays implicit) |
-| Transform to markdown subagent | opencode (`.opencode/agents/<name>.md`; `mode: subagent`, `model` from tier via `get_model`, `permission.edit`/`permission.bash` from access) |
-
-Model names come from `get_model(config_file, ide, tier)` in `lib/common.sh`. Defaults are baked into `get_model_default()`; users override per-IDE/tier under `models:` in `config.yaml`. Sync prints a drift report when an override no longer matches the current default.
-
-### Layout tokens (required)
-
-The engine ships artifacts of its own — the `intelligence-authoring` rule and the `intelligence-architect` agent — and they cannot hardcode the umbrella's folder name, because the project chooses it. They write `<umbrella>` and `<module>` instead, and **every adapter must expand them by calling `finalize_output_file` on each file it writes** (it also does the LF normalization that `normalize_file_to_lf` used to do):
-
-| Token | Expands to |
-|---|---|
-| `<umbrella>` | repo-relative umbrella dir (e.g. `Intelligence`) |
-| `<module>` | repo-relative engine module (e.g. `Intelligence/sync`; CLI setup: `.intelligence/packages/@ainova-systems/sync`) |
-| `<manifest>` | the project's config file name — vendored: `config.yaml`, CLI setup: `intelligence.yaml` (`IS_MANIFEST_NAME`) |
-| `<sync-cmd>` | the sync invocation — vendored: `bash <module>/scripts/sync.sh`, CLI setup: `intelligence sync` (`IS_SYNC_CMD`) |
-
-Values are exported by `sync.sh` (`IS_UMBRELLA_REL`, `IS_MODULE_REL`; `IS_SYNC_CMD` comes from the CLI in CLI mode), derived from the detected layout. Expansion covers frontmatter and body, so `paths: ["<umbrella>/**"]` reaches Claude's `paths:`, Cursor's `globs:` and Copilot's `applyTo:` carrying the project's real folder name. A file written without `finalize_output_file` ships a literal `<umbrella>` into an IDE — CI fails the build if any generated output still contains a token.
-
-### Cleanup Contract
-
-Every adapter MUST follow these rules to stay safe alongside others:
-
-1. **Clean only adapter-owned subpaths.** Never `rm -rf "$output_dir"` — users hand-author siblings (`.claude/settings.json`, `.cursor/settings.json`, `.pi/settings.json`, `.opencode/opencode.json`, `.github/workflows/`, project-specific commands and extensions). Mirror `claude.sh` (deletes only `rules/`, `agents/`, and per-skill subdirs), `pi.sh` (deletes only `.pi/intelligence-sync/`, the named extension file, and `intelligence-agent-*.md` prompt files), or `opencode.sh` (deletes only `.opencode/agents/` wholesale, and inside `.opencode/commands/` only files that carry the `<!-- Generated by intelligence-sync. Do not edit manually. -->` marker — hand-authored sibling commands survive).
-2. **The cleanup block defines what the adapter owns.** It is the same set `/intelligence-uninstall-adapter` removes when the target is turned off: whatever `sync_to_<name>()` deletes on every re-sync, and nothing more. Keep it obvious in the source — an uninstall reads it.
-3. **Use shared helpers for shared dirs.** `.agents/skills/` is read by Codex, Pi, opencode, and any tool implementing the [Agent Skills open standard](https://agentskills.io). All adapters writing there must call `sync_open_skill_dirs`, which owns the full lifecycle (clean per-skill subfolders, recreate the dir, populate). Do NOT duplicate the clean / `mkdir -p` in the adapter — calling sites become divergent and one adapter inevitably drifts. It is also *shared*: an uninstall removes it only when no other open-standard target remains enabled.
-4. **Document owned paths in `.gitignore`.** Each adapter's INIT.md `.gitignore` block lists exactly the paths it writes — no broader. This lets users keep hand-authored content under the same root tracked.
-5. **The output path is validated before you run.** `sync.sh` calls `validate_output_path` for every adapter (including `agents`): the resolved output must stay inside the repo, and must not be the repo root, the intelligence source tree, or any configured source. `..` is canonicalized away first, so a config line cannot walk out of the repository. Adapters never need to re-check this — but they must not write outside the `output_dir` they are handed.
-
-## Example: Minimal Adapter
-
-```bash
-#!/bin/bash
-source "$(dirname "$0")/../lib/common.sh"
-
-sync_to_myide() {
-    local repo_root="$1"
-    local config_file="$2"
-    local output_dir="$3"
-
-    echo "=== MyIDE ==="
-    mkdir -p "$output_dir/rules"
-
-    # Copy rules, strip frontmatter
-    while IFS= read -r src; do
-        [ -z "$src" ] && continue
-        # resolve_source_dir maps a source entry to a local dir: "$repo_root/$src"
-        # for a local path, or a shallow clone for a pack reference (`@<name>`)
-        # or an inline `git+<url>` spec. A pack's url/ref/mirror are read from
-        # config.yaml, which it takes from $IS_CONFIG_FILE (exported by sync.sh)
-        # unless you pass the config as a third argument.
-        local dir
-        dir="$(resolve_source_dir "$repo_root" "$src")"
-        [ -d "$dir" ] || continue
-        for f in "$dir"/*.md; do
-            [ -f "$f" ] || continue
-            awk '
-                BEGIN { in_fm=0; past_fm=0 }
-                { sub(/\r$/, "") }
-                /^---$/ {
-                    if (!past_fm) { in_fm = !in_fm; if (!in_fm) { past_fm=1 }; next }
-                }
-                past_fm || !in_fm { print }
-            ' "$f" > "$output_dir/rules/$(basename "$f")"
-            # Every written file goes through finalize_output_file: it expands
-            # the <umbrella> / <module> layout tokens and normalizes CRLF -> LF.
-            finalize_output_file "$output_dir/rules/$(basename "$f")"
-        done
-    done < <(read_yaml_list "$config_file" "rules")
-}
-```
-
-## Testing
-
-Test your adapter by creating a temporary project with `config.yaml` and running:
-
-```bash
-REPO_ROOT=/path/to/test/project bash intelligence/sync/scripts/sync.sh <name>
-```
-
-Verify the output directory contains correctly transformed files. The sync entry point also runs `lint_frontmatter` over every source file before adapters fire — unquoted YAML colons and leading tabs surface as warnings on stderr.
-
-## Distributing changes
-
-When you ship a new adapter, downstream projects pick it up by running:
-
-```bash
-bash intelligence/sync/scripts/update.sh
-```
-
-`update.sh` clones the upstream repo into a `mktemp -d` directory, shows the diff for `intelligence/sync/scripts/` and `intelligence/sync/INIT.md`, and prompts before overwriting. Project content (`config.yaml`, `rules/`, `agents/`, `skills/`, `adapters/`) is never touched. Pass `--yes` for non-interactive runs; set `REPO_URL=<fork>` to use a fork.
-
-This is exactly why a project's own adapter belongs in `intelligence/adapters/` and not in the engine's `scripts/adapters/`: the first is project content, the second is overwritten by the command above.
-
-## Built-in Adapters Reference
-
-| Adapter | Output | Rules | Skills | Agents |
-|---------|--------|-------|--------|--------|
-| `agents.sh` | `AGENTS.md` (committed) | Always-on inlined; scoped listed | Listed in table | Listed in table |
-| `claude.sh` | `.claude/` | Copy as-is (Claude does not read AGENTS.md) | SKILL.md dirs | tier/access → model/tools |
-| `cursor.sh` | `.cursor/` | Scoped only → `.mdc` + globs | Copy as-is | tier → model |
-| `copilot.sh` | `.github/` | Scoped only → `.instructions.md` | SKILL.md dirs | `.agent.md` |
-| `codex.sh` | `.codex/` + `.agents/skills/` | None (AGENTS.md handles) | SKILL.md dirs in `.agents/skills/` | `.toml` in `.codex/agents/` |
-| `pi.sh` | `.pi/` + `.agents/skills/` | Scoped rules copied + listed by generated extension; always-on via AGENTS.md | SKILL.md dirs in `.agents/skills/` | prompt templates in `.pi/prompts/` |
-| `opencode.sh` | `.opencode/` + `.agents/skills/` | None (AGENTS.md handles always-on; opencode has no native scoping) | SKILL.md dirs in `.agents/skills/`; one slash command per skill in `.opencode/commands/<name>.md` (marker-protected) | markdown subagents in `.opencode/agents/` |
-
-### Notes on `agents.sh`
-
-Unlike IDE adapters, `agents.sh` emits a single committed markdown file intended for humans and generic LLM tooling. It reads a static `header` block from `config.yaml` (under `targets.agents.header`) and appends auto-generated tables (agents, skills) and a list of rules derived from frontmatter. The output carries a "do not edit manually" marker and is regenerated on every sync.
-
-#### Why AGENTS.md inlines always-on rules
-
-AGENTS.md is the canonical project doc — Cursor, Copilot, Codex, Pi, and opencode read it natively. Always-on rule content is inlined automatically so all five tools see the same context from one source. Path-scoped rules are NOT inlined (would balloon AGENTS.md in monorepos); they live in tool-specific channels with native scoping (`.cursor/rules/*.mdc` with `globs:`, `.github/instructions/*.instructions.md` with `applyTo:`) or, for Pi, in generated on-demand rule files surfaced by a small extension. opencode has no first-class path-scoped channel; users who need scoped rules can opt into them via `instructions:` globs in `opencode.json`.
-
-Claude Code does not read AGENTS.md natively (per [open feature request](https://github.com/anthropics/claude-code/issues/6235)) — its adapter copies all rules into `.claude/rules/`. There is no duplication because Claude does not consume AGENTS.md.