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

package/packages/sync/references/conventions.md

@@ -0,0 +1,385 @@
+# Intelligence Authoring Conventions
+
+Intelligence stores project-owned AI rules, agents and skills as tool-neutral Markdown. The CLI installs shared packages, and the sync engine renders each enabled target's native files.
+
+## Choose the right artifact
+
+| Type | Intent | Loading | Content |
+|---|---|---|---|
+| **Rule** | The model respects a constraint or convention | Automatic: always-on or path-scoped | Required patterns, invariants, architecture and examples |
+| **Skill** | The model performs a procedure | Explicit invocation | Ordered steps, decisions and verification |
+| **Agent** | The model adopts a role or expertise boundary | Explicit selection or skill binding | Expertise, boundaries and build/verify behavior |
+
+Use these tests:
+
+- “The model should consider this during every task in scope” → rule.
+- “The model should execute these steps” → skill.
+- “The model should reason as this specialist” → agent.
+
+Do not bury conventions in agents, workflows in rules or reusable expertise in skills. Each misplaced concern either fails to load when needed or consumes context when it is not needed.
+
+## v2 project structure
+
+```text
+project/
+├── intelligence.yaml       # root manifest and schema_version contract
+├── intelligence.lock       # resolved packages; commit it
+├── intelligence/           # project-owned content; name is configurable
+│   ├── rules/
+│   │   ├── context.md
+│   │   └── backend.md
+│   ├── agents/
+│   │   └── backend-developer.md
+│   ├── skills/
+│   │   └── backend-add-endpoint/
+│   │       └── SKILL.md
+│   └── adapters/           # optional project adapters
+│       └── mytool.sh
+├── .intelligence/          # CLI-managed package store; gitignored
+│   └── packages/
+│       └── @scope/name/
+├── AGENTS.md               # generated canonical context; normally committed
+└── .claude/ .cursor/ ...   # generated tool-native output
+```
+
+The content directory defaults to `intelligence/`. A project may set `project.intelligence_dir` in `intelligence.yaml`; never infer or hardcode the default when the manifest is available.
+
+Project-authored rules, agents, skills and adapters live in the content directory. Installed package content lives under `.intelligence/packages/` and is replaced by CLI lifecycle/package operations; edit it only in its source repository. The executable engine remains with the installed CLI, outside the project.
+
+The `intelligence-` name prefix is reserved for artifacts shipped by `@ainova-systems/sync`. Project artifacts use their project or domain prefix.
+
+## Manifest, packages and sources
+
+The engine consumes ordinary local source paths:
+
+```yaml
+project:
+  name: payments
+  intelligence_dir: "intelligence"  # optional; this is the default
+
+schema_version: "0.11.0"
+
+sources:
+  rules:
+    - ".intelligence/packages/@ainova-systems/sync/rules"
+    - "intelligence/rules"
+  agents:
+    - ".intelligence/packages/@ainova-systems/sync/agents"
+    - "intelligence/agents"
+  skills:
+    - ".intelligence/packages/@ainova-systems/sync/skills"
+    - "intelligence/skills"
+```
+
+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.
+
+The CLI owns package and registry blocks:
+
+```yaml
+packages:
+  "@acme/backend":
+    version: "^1.2.0"
+
+registries:
+  - "https://github.com/acme/intelligence-registry.git"
+```
+
+Do not put Git URLs or remote tokens directly in `sources:`. Use:
+
+```bash
+intelligence package add @acme/backend
+intelligence package add github:acme/backend-intelligence
+intelligence package add 'git+https://git.example.com/acme/backend.git@main#package'
+```
+
+Registries are an ordered trust list and the only resolver for a package name. There is no built-in catalog and no `@org/name` → GitHub guessing. An explicit `github:` or `git+` spec bypasses registry lookup. In every case the manifest stores only requested `version` or `ref`; resolved URL/path and SHA live in the lock.
+
+Stable Git tags provide package versions. Semver ranges select the highest matching stable tag; a `ref:` pin names a branch or commit and does not move during `intelligence update`. One package name has one version per project.
+
+Commit `intelligence.lock`. It records requested versions, source URLs and paths, resolved refs and commit SHAs. After cloning, `intelligence sync` restores a missing store strictly from that lock before rendering; manifest/lock or SHA drift is refused. Re-run `package add` when deliberately changing a source.
+
+`@ainova-systems/sync` is ordinary package content exact-pinned to the bundled engine version. `intelligence init` installs it unless `--bare` is used. Lifecycle preflight keeps that pin and `schema_version` aligned with the installed CLI; package-range updates never move it independently.
+
+## Layout tokens
+
+Package-owned artifacts cannot assume the project's content-directory name or their installed package path. They use tokens expanded by every adapter through `finalize_output_file`:
+
+| Token | v2 expansion |
+|---|---|
+| `<content-dir>` | Repo-relative content directory, usually `intelligence` |
+| `<module>` | Installed sync package, usually `.intelligence/packages/@ainova-systems/sync` |
+| `<manifest>` | `intelligence.yaml` |
+| `<sync-cmd>` | `intelligence sync` |
+
+Expansion applies to frontmatter and bodies. Thus `paths: ["<content-dir>/**"]` reaches every native scoped-rule format with the project's real directory name.
+
+Project-authored artifacts normally use their known project paths directly. Tokens are useful only when the same artifact must work under different content-directory or package-store locations.
+
+## Naming
+
+Rule filenames, agent names and skill names share a domain prefix such as `backend-`, `frontend-`, `devops-`, `core-`, `tests-`, a project codename or a monorepo component. Pick the domain from repository structure and reuse it.
+
+- Skills: `<domain>-<verb>-<noun>`, for example `backend-add-endpoint`.
+- Agents: `<domain>-<role>`, for example `backend-code-reviewer`.
+- Rules: `<domain>.md`, for example `backend.md`.
+
+Common skill verbs:
+
+| Verb | Meaning |
+|---|---|
+| `add-` | Add one member to an existing set |
+| `create-` | Create a new container or top-level artifact |
+| `update-` | Revise existing state selectively |
+| `run-` | Execute an operation |
+| `review-` | Perform read-only analysis |
+| `test-` | Verify behavior |
+| `remove-` | Remove an artifact safely |
+
+The verb describes the outcome, not whether the skill implements the work or delegates to another command or skill.
+
+## Agent conventions
+
+```yaml
+---
+name: backend-developer
+description: "Implements backend features"
+tier: heavy
+access: full
+skills:
+  - backend-add-endpoint
+---
+
+# Backend developer
+
+Agent instructions in Markdown.
+```
+
+An agent stays thin: **Expertise** → **Boundaries** → **Build & Verify**. Its role, limits and proof of completion belong here; reusable constraints belong in rules and reusable procedures belong in skills.
+
+Do not instruct an agent to read rules or restate their content. Claude loads its generated rules for its subagents, while Cursor, Copilot, Codex, Pi and OpenCode receive always-on rules through `AGENTS.md`. Duplicating a rule in an agent spends context twice and creates a copy that drifts.
+
+### Tier mappings
+
+| Tier | Claude | Cursor | Copilot / Codex | OpenCode | Typical use |
+|---|---|---|---|---|---|
+| `heavy` | `opus` | `inherit` | `gpt-5.6-sol` | `anthropic/claude-opus-4-8` | implementation, complex reasoning, migration |
+| `standard` | `sonnet` | `inherit` | `gpt-5.6-terra` | `anthropic/claude-sonnet-5` | review, validation, analysis |
+| `light` | `haiku` | `fast` | `gpt-5.6-luna` | `anthropic/claude-haiku-4-5-20251001` | lookups and simple formatting |
+
+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.
+
+### Access mappings
+
+`access: full` inherits ordinary tool permissions. `access: readonly` is transformed into the target's native restriction: for example Claude receives read/search/bash tools with writes disallowed, Cursor receives `readonly: true`, and Codex receives a read-only sandbox.
+
+Use only `full` or `readonly` in source agents. Tool-specific permission syntax belongs in adapters.
+
+## Rule conventions
+
+```yaml
+---
+paths:
+  - "src/backend/**"
+  - "config/**"
+description: "Backend conventions"
+---
+
+# Backend conventions
+
+Rule content in Markdown.
+```
+
+`paths:` is optional:
+
+- With `paths:`, the rule is scoped to matching repository files.
+- Without `paths:`, the rule is always-on project context.
+
+### Routing
+
+| Source rule | Claude | Cursor | Copilot | Codex / Pi / OpenCode / `AGENTS.md` |
+|---|---|---|---|---|
+| Scoped | copied with `paths:` | `.mdc` with `globs:` | `.instructions.md` with `applyTo:` | listed in `AGENTS.md`; Pi also gets on-demand files and an extension |
+| Always-on | copied | omitted | omitted | inlined once into `AGENTS.md` |
+
+Cursor, Copilot, Codex, Pi and OpenCode consume `AGENTS.md`, so always-on rules are not duplicated in their tool-specific channels. Claude does not consume `AGENTS.md`, so it receives the full rule set. OpenCode and Codex have no generated path-scoped rule channel; OpenCode users may configure `instructions:` globs themselves.
+
+Keep always-on rules small. Put narrow framework or component guidance behind `paths:` so unrelated tasks do not pay its context cost.
+
+## Skill conventions
+
+Skills follow the [Agent Skills standard](https://agentskills.io). Required fields are `name` and `description`.
+
+```yaml
+---
+name: backend-add-endpoint
+description: "Add a backend endpoint"
+argument-hint: "<route-name>"
+---
+
+# Add a backend endpoint
+
+1. Inspect the existing route pattern.
+2. Implement the endpoint.
+3. Run focused tests.
+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.
+
+These limits reject a skill instead of degrading it:
+
+| Field | Limit | Failure mode |
+|---|---|---|
+| `name` | 64 characters | Rejected at load |
+| `description` | 1024 characters | Rejected at load |
+| `argument-hint` | Must be a string | An unquoted `[value]` is parsed as a YAML sequence |
+
+Sync quotes free-text `description` and `argument-hint` values in generated copies. `lint_frontmatter` warns when a name or description exceeds its hard limit, but the author must shorten it.
+
+### Description budget
+
+Descriptions share the tool's available-artifact context budget.
+
+| Case | Format | Target |
+|---|---|---|
+| Unique skill | Plain verb–noun phrase | 4–8 words |
+| Similar sibling skills | Verb–noun plus a distinguishing trigger | 10–20 words, roughly 250 characters or less |
+
+The 1024-character limit is a rejection wall, not a writing target. Curate duplicate and orphaned artifacts before compressing every description into ambiguity.
+
+### Skill body and resources
+
+A skill that performs work carries the decisions and verification needed for that work. A skill that dispatches to deterministic CLI behavior stays thin: it chooses the command, interprets status and adds only judgment that the program cannot provide.
+
+Keep on-demand detail beside the skill:
+
+```text
+skill-name/
+├── SKILL.md
+├── references/    # detailed material loaded only when needed
+├── scripts/       # deterministic or repetitive helpers
+└── assets/        # templates and output resources
+```
+
+The engine copies the complete skill directory. Promote a helper outside the skill only when multiple skills share it.
+
+Size limits are backstops, not quotas:
+
+| Artifact | Hard cap | Response |
+|---|---|---|
+| `SKILL.md` body | 1000 lines | Move detail to `references/` |
+| Reference file | 500 lines | Add a contents list past 300; split if still oversized |
+| Rule | 500 lines | Split by scope or move examples behind a skill reference |
+| Agent | 200 lines | Move procedures and constraints into skills/rules |
+
+## Writing discipline
+
+- Use imperative form: “Read the manifest,” not “You should read the manifest.”
+- Explain why a decision rule exists so the model can apply it to adjacent cases.
+- Reserve absolute language for genuine safety, security and output-format invariants.
+- Lead with the positive behavior; keep anti-patterns after the actionable guidance.
+- Remove instructions that repeat tool defaults, repository facts already discoverable from files, or another artifact.
+- Turn repeated deterministic work into a script or CLI command and let the skill interpret it.
+
+Every line enters a finite context budget. Prefer subtraction, consolidation and precise scope over exhaustive prose.
+
+## Generated output
+
+| Target | Rules | Skills | Agents |
+|---|---|---|---|
+| `agents` | Always-on inlined; scoped listed in `AGENTS.md` | Listed | Listed |
+| Claude | `.claude/rules/` | `.claude/skills/` | `.claude/agents/` |
+| Cursor | scoped `.cursor/rules/*.mdc` | `.cursor/skills/` | `.cursor/agents/` |
+| Copilot | scoped `.github/instructions/*.instructions.md` | `.github/skills/` | `.github/agents/` |
+| Codex | `AGENTS.md` only | `.agents/skills/` | `.codex/agents/*.toml` |
+| Pi | `AGENTS.md` plus scoped `.pi/intelligence-sync/rules/` | `.agents/skills/` | `.pi/prompts/intelligence-agent-*.md` |
+| OpenCode | `AGENTS.md` only | `.agents/skills/` plus slash commands | `.opencode/agents/*.md` |
+
+`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.
+
+Generated IDE output may be gitignored when every collaborator can reproduce it with `intelligence sync`. Use narrow ownership patterns so hand-authored tool settings remain trackable:
+
+```gitignore
+# CLI-managed package store
+.intelligence/
+
+# Generated Claude and Cursor content; settings remain trackable
+.claude/rules/
+.claude/agents/
+.claude/skills/
+.cursor/rules/
+.cursor/agents/
+.cursor/skills/
+
+# Generated open-standard and Codex content
+.agents/
+.codex/agents/
+
+# Generated Pi content
+.pi/intelligence-sync/
+.pi/extensions/intelligence-sync-rules.ts
+.pi/prompts/intelligence-agent-*.md
+
+# Generated OpenCode agents. Its commands directory may also contain
+# hand-authored files, so choose per-project ignores there.
+.opencode/agents/
+```
+
+Copilot output lives under `.github/`; choose whether to commit it with other repository-level GitHub configuration. Do not ignore `.github/` wholesale.
+
+## Project-owned adapters
+
+Create a project adapter with:
+
+```bash
+intelligence adapter create mytool
+# implement <content-dir>/adapters/mytool.sh
+intelligence adapter enable mytool
+```
+
+Project adapters survive CLI upgrades and may override a built-in by name. `intelligence adapter enable mytool` runs a full sync so shared context stays current. `intelligence adapter disable mytool` keeps generated output for explicit, adapter-aware cleanup; a disabled project adapter can then be deleted with `intelligence adapter remove mytool`. See `adapters.md` for the function, ownership and safety contracts.
+
+## Schema and command boundaries
+
+The permanent applied-schema key is the top-level scalar `schema_version` in `intelligence.yaml`. It is not a dotfile and not the CLI package version. Do not rename, move or reshape this key: every engine must be able to decide compatibility before parsing the rest of the manifest.
+
+The public lifecycle is deliberately compact:
+
+- `intelligence init [--preview|--apply]` is universal: it creates a new setup, aligns an existing v2 project, or plans/applies conversion of an eligible v1 project.
+- `intelligence sync [adapter]` first aligns an existing v2 project with the installed CLI, restores a missing store strictly from `intelligence.lock`, then renders. In CI it refuses an upgrade that would change tracked files and points to a local `intelligence init --apply` plus review/commit.
+- `intelligence update [@scope/name] [--preview|--apply]` is the only update surface. It prints the CLI/project/package plan; default mode prompts, `--preview` never writes, and `--apply` does not prompt. It never moves `ref:` pins.
+- `intelligence package add|remove|list|search` owns package inventory.
+- `intelligence adapter list|create|enable|disable|remove` owns adapter inventory and target state.
+- `intelligence status [--check]` reports state; `--check` runs deep consistency checks.
+
+Implement v2 schema changes as idempotent structural checks. Stage and verify replacement state before deleting or replacing prior state. A stale engine refuses a manifest whose `schema_version` is newer; normal v2 entry points close a behind-project gap through lifecycle preflight.
+
+Breaking changelog entries use a `### Breaking` checklist of verifiable post-conditions. The update skill reads every release across the version gap, chooses the package/CLI/project command sequence and verifies those conditions after the deterministic command completes.
+
+### Engine status contract
+
+The engine emits one machine-readable line, `IS_STATUS=<code> [IS_DETAIL=...]`, and exits with a stable code:
+
+| `IS_STATUS` | Exit | Meaning |
+|---|---:|---|
+| `ok` | 0 | Sync or operation completed |
+| `migrated` | 0 | Initialization converted an older layout |
+| `error` | 1 | Generic failure |
+| `config-missing` | 2 | Required manifest is absent |
+| `ambiguous` | 3 | Conflicting state requiring agent/human judgment; reserved |
+| `ahead-of-engine` | 4 | Manifest schema is newer than the engine |
+| `aborted-incomplete` | 5 | Staged replacement was incomplete; prior state remains |
+| `needs-update` | 6 | Project schema is behind the engine; rerun through a public lifecycle command |
+
+Callers capture the real code with `command || rc=$?`. Do not use `if ! command; then rc=$?`; inside that branch `$?` is the status of the negation.
+
+## Project entry points
+
+| Path | Role | Git status |
+|---|---|---|
+| `intelligence.yaml` | Manifest and schema contract | Tracked |
+| `intelligence.lock` | Resolved package state | Tracked |
+| `<content-dir>/{rules,agents,skills,adapters}/` | Project source of truth | Tracked |
+| `.intelligence/` | Restorable package store | Ignored |
+| `AGENTS.md` | Generated canonical project context | Normally tracked |
+| Tool output directories | Generated native content | Project policy; use narrow ignores |

package/packages/sync/rules/intelligence-authoring.md

@@ -2,12 +2,12 @@
 name: intelligence-authoring
 description: "Authoring discipline for the intelligence layer - subtraction first, rule vs skill vs agent, scoping, size"
 paths:
-  - "<umbrella>/**"
+  - "<content-dir>/**"
 ---
 
 # Authoring the intelligence layer
 
-Applies when writing or changing anything under `<umbrella>/`. The mechanics — frontmatter fields, tier and access vocabulary, how each tool is fed — live in `<module>/docs/CONVENTIONS.md`. This rule is the judgement that sits on top of them.
+Applies when writing or changing anything under `<content-dir>/`. The mechanics — frontmatter fields, tier and access vocabulary, how each tool is fed — live in `<module>/references/conventions.md`. This rule is the judgement that sits on top of them.
 
 ## Subtraction is the job
 
@@ -25,9 +25,9 @@ Three ways to shorten, in order of what they are worth:
 
 ## Source of truth
 
-Edit the sources listed in `<manifest>` — the `rules/`, `agents/` and `skills/` directories it names — and `<manifest>` itself. A source that arrived from the engine or an installed package is not yours to edit either — it is replaced on the next update or install; change it in its own repository. Everything else is derived: `.claude/`, `.cursor/`, `.github/{instructions,agents,skills}/`, `.codex/`, `.agents/skills/`, `.pi/`, `.opencode/` and `AGENTS.md` are **generated output**, and a hand edit there survives exactly until the next sync.
+Edit the project-owned sources listed in `<manifest>` — the `rules/`, `agents/` and `skills/` directories it names — and `<manifest>` itself. An installed package source is replaced by CLI lifecycle/package operations; change it in its own repository. Everything else is derived: `.claude/`, `.cursor/`, `.github/{instructions,agents,skills}/`, `.codex/`, `.agents/skills/`, `.pi/`, `.opencode/` and `AGENTS.md` are **generated output**, and a hand edit there survives exactly until the next sync.
 
-`<module>/` is the engine's own content. It owns its own rules, agents and meta-skills, and every engine update replaces it wholesale, so a local edit there is lost. Fix it upstream instead.
+`<module>/` is the installed sync package's content. Package operations replace it, so a local edit there is lost. Fix it upstream instead.
 
 After any change: `<sync-cmd>`. A change that was not synced does not exist for any tool.
 
@@ -84,7 +84,7 @@ The verb just names the action — `add-`, `run-`, `review-`, `extract-`, `plan-
 
 Two verbs are told apart by what already exists. **`add-` puts one new member into a set that is already there** — a field on an existing type, a record among records, a component in the inventory the project keeps — so the noun names the member, and the number of files it takes to land is not the point. **`create-` brings the container itself into existence**, where nothing hosted it before. Neither verb describes how a skill is factored inside, so splitting a skill's internals never renames it.
 
-`intelligence-` is **reserved** for the engine's own artifacts. A project skill carrying that prefix collides with engine ownership — everything under the prefix is the engine's to replace or remove on update — rename it.
+`intelligence-` is **reserved** for the sync package's own artifacts. A project skill carrying that prefix collides with package-owned meta-skills in generated outputs — rename it.
 
 ### Shape
 
@@ -109,6 +109,6 @@ The goal is subtraction, above. These are only the line past which something is
 
 ## Verifying a change to this layer
 
-The per-artifact checks are a procedure, not a constraint to hold in mind while doing other work — so they live in the meta-skills, not here. Invoke the one that matches what you are doing: `intelligence-add-rule`, `intelligence-add-agent`, `intelligence-add-skill`, `intelligence-extract-skill`, `intelligence-review-skills`, `intelligence-learn-from-context`, `intelligence-sync`, `intelligence-update`, `intelligence-install-adapter`, `intelligence-uninstall-adapter`.
+The per-artifact checks are a procedure, not a constraint to hold in mind while doing other work — so they live in the meta-skills, not here. Invoke the one that matches what you are doing: `intelligence-add-rule`, `intelligence-add-agent`, `intelligence-add-skill`, `intelligence-extract-skill`, `intelligence-review-skills`, `intelligence-learn-from-repository`, `intelligence-learn-from-context`, `intelligence-sync`, `intelligence-update`, `intelligence-install-adapter`, `intelligence-uninstall-adapter`.
 
 A change to this layer is done when `<sync-cmd>` reports `IS_STATUS=ok` and the skill you invoked reports clean.

package/packages/sync/skills/intelligence-add-agent/SKILL.md

@@ -9,7 +9,7 @@ argument-hint: <domain> [description]
 ## Steps
 
 1. **Determine domain prefix** (the scope is required):
-   - **Reuse the existing domain when one fits**: list `<umbrella>/agents/` and `<umbrella>/skills/`. If a domain prefix is already established for the target area (`backend-`, `frontend-`, `devops-`), use it. Introduce a new domain only when the scope is materially different from all existing ones.
+   - **Reuse the existing domain when one fits**: list `<content-dir>/agents/` and `<content-dir>/skills/`. If a domain prefix is already established for the target area (`backend-`, `frontend-`, `devops-`), use it. Introduce a new domain only when the scope is materially different from all existing ones.
    - **When no existing domain fits**, derive from repo structure:
      - Single / root project → use the project codename from `<manifest>` → `project.name`
      - Backend service / API component → `backend-`
@@ -21,7 +21,7 @@ argument-hint: <domain> [description]
    - If the repo is a monorepo with named components (e.g., `apps/billing`, `services/auth`), prefer the component name as the domain (`billing-`, `auth-`).
    - **Every agent needs a domain prefix.** If the scope is unclear, ask the user before proceeding.
 
-2. **Check existing agents**: Read `<umbrella>/agents/` to avoid duplicates. If an agent for this domain exists, ask user whether to update it instead.
+2. **Check existing agents**: Read `<content-dir>/agents/` to avoid duplicates. If an agent for this domain exists, ask user whether to update it instead.
 
 3. **Determine tier and access**:
    - Developer agents: `tier: heavy`, `access: full`
@@ -36,7 +36,7 @@ argument-hint: <domain> [description]
    - Build and test commands
    - Key conventions and forbidden patterns
 
-5. **Create agent**: Write `<umbrella>/agents/<domain>-<role>.md` (create the directory if missing) with frontmatter:
+5. **Create agent**: Write `<content-dir>/agents/<domain>-<role>.md` (create the directory if missing) with frontmatter:
    ```yaml
    ---
    name: <domain>-<role>
@@ -52,11 +52,11 @@ argument-hint: <domain> [description]
 
 6. **Write body** with sections: **Expertise** -> **Boundaries** -> **Build & Verify**
    - An agent is **thin**: who it is, where it stops, how it verifies. Everything else already reaches it.
-   - **Do not tell the agent to read the rules.** Rules load on their own: Claude Code loads `.claude/rules/` into every custom subagent's startup context alongside `CLAUDE.md` (*Subagents → What loads at startup*), and Cursor / Copilot / Codex / Pi / opencode receive always-on rules inlined in `AGENTS.md`. A `Read <umbrella>/rules/<domain>.md before starting` line duplicates content the agent already has — double the tokens, and a second copy that drifts from the rule it copied.
+   - **Do not tell the agent to read the rules.** Rules load on their own: Claude Code loads `.claude/rules/` into every custom subagent's startup context alongside `CLAUDE.md` (*Subagents → What loads at startup*), and Cursor / Copilot / Codex / Pi / opencode receive always-on rules inlined in `AGENTS.md`. A `Read <content-dir>/rules/<domain>.md before starting` line duplicates content the agent already has — double the tokens, and a second copy that drifts from the rule it copied.
    - **Point at a rule, never restate it.** If you want to copy a rule into the agent, the rule is in the wrong place — move it, do not clone it.
    - **Do carry** what is genuinely the agent's own: its boundaries ("if the app is not running, stop — do not hand-write the output"), its verification commands, its definition of done.
    - All content must come from actual codebase analysis.
 
-7. **Link existing skills**: Find skills in `<umbrella>/skills/` matching this domain prefix and add them to the agent's `skills:` frontmatter.
+7. **Link existing skills**: Find skills in `<content-dir>/skills/` matching this domain prefix and add them to the agent's `skills:` frontmatter.
 
 8. **Run `/intelligence-sync`** to distribute to all enabled IDE targets.

package/packages/sync/skills/intelligence-add-rule/SKILL.md

@@ -9,7 +9,7 @@ argument-hint: <name> [paths-glob]
 ## Steps
 
 1. **Determine rule name from domain** (the scope is required):
-   - **Reuse the existing domain when one fits**: list `<umbrella>/rules/`. If a rule file covers the target area (e.g., `backend.md`, `frontend.md`), extend it. Introduce a new domain only when the scope is materially different from all existing rules.
+   - **Reuse the existing domain when one fits**: list `<content-dir>/rules/`. If a rule file covers the target area (e.g., `backend.md`, `frontend.md`), extend it. Introduce a new domain only when the scope is materially different from all existing rules.
    - **When no existing rule fits**, derive the filename from repo structure:
      - Single / root project → use the project codename from `<manifest>` → `project.name` (e.g., `<codename>.md`)
      - Backend service / API component → `backend.md`
@@ -21,7 +21,7 @@ argument-hint: <name> [paths-glob]
    - If the repo is a monorepo with named components (e.g., `apps/billing`, `services/auth`), prefer the component name as the rule name (`billing.md`, `auth.md`).
    - **Rule filenames match the domain used by skills/agents.** If the scope is unclear, ask the user before proceeding.
 
-2. **Check existing rules**: Read `<umbrella>/rules/` to detect overlapping scope — favor extending an existing rule over creating a new one.
+2. **Check existing rules**: Read `<content-dir>/rules/` to detect overlapping scope — favor extending an existing rule over creating a new one.
 
 3. **Determine scope**:
    - If paths glob provided — scoped rule with `paths:` frontmatter
@@ -34,7 +34,7 @@ argument-hint: <name> [paths-glob]
    - Build and test commands specific to this scope
    - Anti-patterns observed in code, each paired with the positive replacement that should adopt instead
 
-5. **Create rule**: Write `<umbrella>/rules/<name>.md` (create the directory if it does not exist — the sources list already covers it):
+5. **Create rule**: Write `<content-dir>/rules/<name>.md` (create the directory if it does not exist — the sources list already covers it):
    ```yaml
    ---
    paths:

package/packages/sync/skills/intelligence-add-skill/SKILL.md

@@ -9,7 +9,7 @@ argument-hint: <domain> <verb-noun> [description]
 ## Steps
 
 1. **Determine domain prefix** (the scope is required):
-   - **Reuse the existing domain when one fits**: list `<umbrella>/skills/` and `<umbrella>/agents/`. If a domain prefix is already established for the target area (`backend-`, `frontend-`, `devops-`), use it. Introduce a new domain only when the scope is materially different from all existing ones.
+   - **Reuse the existing domain when one fits**: list `<content-dir>/skills/` and `<content-dir>/agents/`. If a domain prefix is already established for the target area (`backend-`, `frontend-`, `devops-`), use it. Introduce a new domain only when the scope is materially different from all existing ones.
    - **When no existing domain fits**, derive from repo structure:
      - Single / root project → use the project codename from `<manifest>` → `project.name`
      - Backend service / API component → `backend-`
@@ -28,13 +28,13 @@ argument-hint: <domain> <verb-noun> [description]
    - `run-` — executes an operation (tests, build, sync)
    - `review-` — read-only analysis
 
-3. **Check for existing agent**: Find an agent in `<umbrella>/agents/` matching the domain
+3. **Check for existing agent**: Find an agent in `<content-dir>/agents/` matching the domain
    - If found — this skill will be linked to that agent
    - If not — ask user whether to create a new agent via `/intelligence-add-agent` first
 
 4. **Analyze codebase patterns**: Read existing implementations to extract the repeatable steps this skill should automate. Each step must come from actual code patterns, not generic knowledge.
 
-5. **Create skill**: Write `<umbrella>/skills/<full-name>/SKILL.md` (create the directory if missing — no config edit needed) with frontmatter:
+5. **Create skill**: Write `<content-dir>/skills/<full-name>/SKILL.md` (create the directory if missing — no config edit needed) with frontmatter:
    ```yaml
    ---
    name: <full-name>

package/packages/sync/skills/intelligence-extract-skill/SKILL.md

@@ -26,7 +26,7 @@ Both end at the same artifact format. Extract starts from observed behavior, so
    - Behavioral preference / constraint / pattern to default to → **rule** (use `intelligence-learn-from-context` for single preferences from session)
    - Knowledge area / persona / expertise scope → **agent**
 
-4. **Determine domain prefix** (for skill / agent): reuse the existing domain when one fits — list `<umbrella>/skills/` and `<umbrella>/agents/`. Derive from repo structure only when no existing domain matches.
+4. **Determine domain prefix** (for skill / agent): reuse the existing domain when one fits — list `<content-dir>/skills/` and `<content-dir>/agents/`. Derive from repo structure only when no existing domain matches.
 
 5. **Determine naming** (for skill): `<domain>-<verb>-<noun>` with convention verbs — `add-` (one new member of a set that already exists), `create-` (the container itself, where nothing hosted it), `update-` (revise what is there), `run-` (execute), `review-` (read-only analysis).
 
@@ -38,7 +38,7 @@ Both end at the same artifact format. Extract starts from observed behavior, so
 
 ## Authoring guidance
 
-Follow the **Authoring Discipline** section in `<module>/docs/CONVENTIONS.md` when writing the artifact body — size budgets (<500 lines for SKILL.md body), imperative form, explain WHY, reserve absolute language for true invariants, lead with positive defaults.
+Follow the **Authoring Discipline** section in `<module>/references/conventions.md` when writing the artifact body — size budgets (<500 lines for SKILL.md body), imperative form, explain WHY, reserve absolute language for true invariants, lead with positive defaults.
 
 ## Related skills
 

package/packages/sync/skills/intelligence-install-adapter/SKILL.md

@@ -1,31 +1,38 @@
 ---
 name: intelligence-install-adapter
-description: "Enable IDE adapter for intelligence-sync"
-argument-hint: <target-name>
+description: "Research, implement, and enable a tool adapter"
+argument-hint: <adapter-name>
 agent: intelligence-operator
 ---
 
-# Install Adapter
+# Install an adapter
 
-The project's config is `<manifest>`; the content dir is `<umbrella>/` (never assume the name or casing); the engine's own files live under `<module>/` — these paths are localized to this project at sync time.
+The CLI owns adapter inventory, scaffolding, target state, and sync. This skill
+owns the judgement a program cannot infer: how the target tool represents
+rules, agents, and skills.
 
 ## Steps
 
-1. Check whether target `$ARGUMENTS` is already enabled in `<manifest>` — if yes, report and stop.
-
-2. **Locate the adapter.** The sync discovers adapters in two places:
-   - **Built-in**: `<module>/scripts/adapters/$ARGUMENTS.sh` — upstream-owned. Every engine update replaces that whole directory.
-   - **Project-owned**: `<umbrella>/adapters/$ARGUMENTS.sh` — updates never touch it. A project adapter of the same name overrides the built-in.
-
-   If neither exists, research the tool's prompt format (web search for its rules / agents / skills file layout), then copy `<module>/scripts/adapters/_template.sh` to **`<umbrella>/adapters/$ARGUMENTS.sh`** and implement `sync_to_$ARGUMENTS()`. Author it there, never inside the engine's `scripts/adapters/` — a file written there is deleted by the next engine update. Adapter contract: `<module>/docs/ADAPTERS.md`. An adapter that would serve every project is worth contributing upstream.
-
-3. Update `<manifest>`:
-   - Target exists with `enabled: false` → flip to `enabled: true`.
-   - Target missing → add it under `targets:` with its `output:` path.
-   - If the target reads always-on rules from `AGENTS.md` (`cursor`, `copilot`, `codex`, `pi`, `opencode`), `targets.agents` must be enabled too — sync fails closed otherwise.
-
-4. Add the adapter's generated paths to `.gitignore` (the paths it writes, not the whole output root — a shared root like `.github/` or `.claude/` also holds tracked, hand-authored files).
-
-5. Run `/intelligence-sync` to generate the output.
-
-6. Report: adapter enabled, files generated, output location.
+1. Run `intelligence adapter list`. If `$ARGUMENTS` already exists, enable it
+   with `intelligence adapter enable $ARGUMENTS`; that command also runs a full
+   sync. Continue at verification.
+
+2. For a missing adapter, research the tool's current authoritative
+   documentation: discovery paths, frontmatter/schema, scoping, naming,
+   agents, skills, and whether it reads `AGENTS.md`. Record links and separate
+   verified behavior from assumptions.
+
+3. Run `intelligence adapter create $ARGUMENTS`, then implement
+   `sync_to_$ARGUMENTS()` in the scaffolded project adapter. Follow
+   `<module>/references/adapters.md` and the closest built-in. Keep writes beneath
+   the configured output, make reruns idempotent, and make owned cleanup paths
+   explicit. Ignore only those owned paths; shared roots remain trackable.
+
+4. Run `bash -n` on the project adapter, then
+   `intelligence adapter enable $ARGUMENTS`. If the CLI says the adapter
+   requires `agents`, enable that adapter first.
+
+5. Require `IS_STATUS=ok`, inspect generated files against the researched
+   format, run the tool's validator when one exists, and finish with
+   `intelligence status --check`. Report evidence, output paths, and any
+   unsupported artifact type.

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

@@ -21,7 +21,7 @@ The original negative pattern stays in the rule body as an illustrative example
 
 ## Phase A — Analyze (read-only)
 
-1. **Read authoring conventions first.** The paths below are localized to this project at sync time: `<umbrella>/` is the content dir, `<module>/` the engine's own files, `<manifest>` the config. The meta-skills live in `<module>/skills/`, not directly under the umbrella. Load `<module>/skills/intelligence-add-rule/SKILL.md`, `<module>/skills/intelligence-add-skill/SKILL.md`, `<module>/skills/intelligence-add-agent/SKILL.md`, and `<module>/docs/CONVENTIONS.md` (Authoring Discipline section). This skill writes nothing on its own — it delegates to the add-* skills, which carry the authoring conventions.
+1. **Read authoring conventions first.** The paths below are localized to this project at sync time: `<content-dir>/` is the project content directory, `<module>/` the installed sync package, and `<manifest>` the root manifest. The meta-skills live in `<module>/skills/`, not directly under the content directory. Load `<module>/skills/intelligence-add-rule/SKILL.md`, `<module>/skills/intelligence-add-skill/SKILL.md`, `<module>/skills/intelligence-add-agent/SKILL.md`, and `<module>/references/conventions.md` (Authoring Discipline section). This skill writes nothing on its own — it delegates to the add-* skills, which carry the authoring conventions.
 
 2. **Capture the lesson** from session context or user input. Strip session-specific detail, keep the underlying pattern.
 
@@ -32,7 +32,7 @@ The original negative pattern stays in the rule body as an illustrative example
    Confirm the translation with the user if removing the negation changes meaning.
 
 4. **Route to the right artifact type**:
-   - Behavioral preference, tone, communication style → **rule** (`<umbrella>/rules/<name>.md`)
+   - Behavioral preference, tone, communication style → **rule** (`<content-dir>/rules/<name>.md`)
    - Multi-step repeatable workflow → use `intelligence-extract-skill` instead
    - Knowledge scope / persona / expertise area → **agent**
    - Project-specific context tied to a path → scoped rule with `paths:` frontmatter
@@ -58,7 +58,7 @@ Present the proposal list to the user. User accepts or rejects per item. Only ac
    - `CREATE` skill → call `intelligence-add-skill`
    - `CREATE` agent → call `intelligence-add-agent`
    - `UPDATE` existing artifact → edit the file directly, applying the proposed change
-   - `ARCHIVE` → move to `<umbrella>/_archive/` and update cross-references that point at it
+   - `ARCHIVE` → move to `<content-dir>/_archive/` and update cross-references that point at it
 
 8. **Run `/intelligence-sync`** once all accepted items are applied.