@ainova-systems/intelligence 0.11.0-rc.1

package/engine/docs/CONVENTIONS.md

@@ -0,0 +1,440 @@
+# intelligence-sync: Conventions
+
+## Choosing artifact type
+
+Three artifact types — each has a different intent and loading mechanism. Picking the right one is the first authoring decision.
+
+| Type | Intent | Loading | Content |
+|---|---|---|---|
+| **Rule** | LLM **respects** a constraint or convention in the background | Auto (path-scoped or always-on) | Required patterns, invariants, architecture, examples |
+| **Skill** | LLM **performs** a multi-step procedure on invocation | Explicit (`/skill-name`) | Numbered steps with verification |
+| **Agent** | LLM **adopts** a persona / domain expertise | Explicit (via agent picker) | Expertise scope, before-any-task checklist, build/verify |
+
+Plain rule of thumb:
+- "AI should consider X across any work in scope" → **rule**
+- "AI should execute a defined sequence of steps" → **skill**
+- "AI should think as an X-domain expert with these tools" → **agent**
+
+Common mistakes to avoid:
+- Conventions / standards embedded in an agent body → belongs in a **rule** (auto-loaded, shared across all agents working in scope)
+- A workflow embedded in a rule body → belongs in a **skill** (explicit invocation, not always-loaded context)
+- Expertise scope embedded in a skill body → belongs in an **agent** (persona reusable across many skills)
+
+## Source Structure
+
+```
+intelligence/                         # Umbrella — name NOT hardcoded (whatever holds config.yaml)
+├── config.yaml                       # Sync config + `sync_version` schema key (committed)
+├── rules/                            # Path-based rules (auto-loaded by context)
+│   ├── context.md                    # Always-loaded (no paths:)
+│   ├── backend.md                    # paths: ["src/backend/**"]
+│   └── frontend.md                   # paths: ["src/frontend/**"]
+├── agents/                           # Specialized agent definitions
+│   ├── backend-developer.md          # tier: heavy, access: full
+│   └── backend-code-reviewer.md      # tier: standard, access: readonly
+├── skills/                           # Reusable project skill commands
+│   ├── backend-add-endpoint/SKILL.md
+│   └── frontend-add-component/SKILL.md
+├── adapters/                         # OPTIONAL — project-owned adapters (survive updates)
+│   └── myide.sh                      # sync_to_myide(); overrides a built-in of the same name
+└── sync/                             # intelligence-sync MODULE (upstream-owned)
+    ├── INIT.md  docs/  scripts/(+VERSION)
+    ├── rules/intelligence-authoring.md    # authoring discipline for this layer
+    ├── agents/intelligence-architect.md   # designs and prunes this layer
+    ├── agents/intelligence-operator.md    # runs sync, update, adapter flows
+    └── skills/intelligence-*              # meta-skills
+```
+
+Everything project-authored lives at the umbrella level (`rules/ agents/ skills/ adapters/`); everything upstream-owned lives in the self-contained module `sync/`, updated independently via `sync/scripts/update.sh`. Additional modules (e.g. `domain/`) sit beside `sync/`. The umbrella folder name is derived at runtime as "the directory holding `config.yaml`" — never hardcoded. The `intelligence-` prefix is **reserved** for upstream artifacts; project rules, agents and skills must not use it (the updater prunes what matches it).
+
+The module ships three kinds of artifact, and `config.yaml` must list all three under `sources` for them to reach the IDEs — `<umbrella>/sync/rules`, `<umbrella>/sync/agents`, `<umbrella>/sync/skills`. INIT emits those entries on bootstrap; the `0.7.0` migration adds them to existing projects.
+
+### Layout tokens in engine-shipped artifacts
+
+An artifact shipped *by the engine* cannot write the umbrella's name down — the project chooses it (`intelligence/`, `Intelligence/`, a codename). So engine artifacts spell it with tokens, and every adapter expands them on the way out (`finalize_output_file` in `lib/common.sh`):
+
+| Token | Expands to | Example |
+|---|---|---|
+| `<umbrella>` | repo-relative umbrella dir | `Intelligence` |
+| `<module>` | repo-relative engine module | `Intelligence/sync` |
+
+Expansion covers frontmatter and body alike, so `paths: ["<umbrella>/**"]` reaches Claude's `paths:`, Cursor's `globs:` and Copilot's `applyTo:` already carrying the project's real folder name. Project-authored artifacts may use the tokens too, but they have no reason to — they can simply name their own folders.
+
+A custom adapter belongs in the umbrella's `adapters/`, never in the module's `sync/scripts/adapters/` — the module is replaced wholesale on every update, so an adapter written there disappears at the next one. See `docs/ADAPTERS.md`.
+
+Rule filenames, agent names, and skill names all share the same **domain prefix** (`backend-`, `frontend-`, `devops-`, `core-`, `tests-`, project codename, or monorepo component name). Pick the domain once from repo structure and reuse it — do not invent new domains without clear need.
+
+### Packs (remote sources)
+
+A `sources.{rules,agents,skills}` entry is normally a **local path** relative to the repo root. It may instead reference a **pack** — a remote git repo that `sync` shallow-clones and treats exactly like a local source directory — so a team can keep shared intelligence in one repo and pull it into many projects.
+
+A pack is **declared once** under `packs:` and referenced by name from as many sections as need it:
+
+```yaml
+packs:
+  shared-intel:
+    url: https://github.com/org/shared-intel.git
+    ref: v1.2.0                                    # the pin — one place, not one per section
+    mirror: "intelligence/external/shared-intel"   # optional; see below
+
+sources:
+  rules:
+    - "intelligence/rules"        # local
+    - "@shared-intel/rules"       # pack
+  skills:
+    - "@shared-intel/skills"      # same pack, same clone, same pin
+```
+
+Declaring the pack is what keeps the url and the ref in one place. Repeating them per section is how the two drift, and nothing catches it: rules pinned at one commit and skills at another is a config that looks fine and reads wrong.
+
+Reference format: `@<pack>[/<subpath>]`
+
+- `<pack>` — a key under `packs:`. It is a **reference handle, never a path component**, so it needs no sanitizing; it must simply contain no `/`.
+- `/<subpath>` — optional directory inside the pack repo holding the rules / agents / skills. Omit to use the repo root. The subpath is preserved in the mirror, so `@shared-intel/packs/core/rules` lands at `<mirror>/packs/core/rules`.
+- **An undeclared pack fails the run** (exit 1, naming the pack and listing the declared ones). This is deliberately unlike a missing local path, which only warns: the config claims to know that name, so a typo must not quietly drop a whole rule set.
+
+Pack fields:
+
+- `url:` — must carry an explicit scheme: `https://`, `http://`, `ssh://`, `git://`, or `file://`. Other transports (notably the command-executing `ext::` / `fd::`) are **rejected** with a warning and skipped.
+- `ref:` — optional tag, branch, or commit SHA. Omit for the default branch.
+- `mirror:` — optional; see [Mirroring a pack into the repo](#mirroring-a-pack-into-the-repo).
+
+#### Inline specs (`git+…`)
+
+A source entry may still carry the whole spec inline: `git+<url>[@<ref>][#<subpath>]`. This is an **anonymous pack** — it has no declared name and no mirror, so it is always transient and cannot be referenced from elsewhere. Declare the pack under `packs:` to pin it once or to commit it.
+
+The inline `@<ref>` is parsed as the segment after the last `@`, accepted as a ref only when it contains no `/` (so `ssh://git@host/...` userinfo is not mistaken for a ref). Branch names containing `/` (e.g. `feature/x`) can't be expressed this way — use `packs:` with a plain `ref:`, which has no such limit.
+
+Behavior and trust:
+
+- **Fresh every sync.** Each `sync` run clones into a run-scoped temp dir and removes it on exit, so branch refs always pick up the latest. Within one run the same `url@ref` is cloned only once, even when several entries (different subpaths) reference it.
+- **Reproducibility / supply chain.** A remote's content becomes rules, agents, and skills the LLM reads as project context. Pin to a tag or SHA so an upstream change can't silently alter behavior, and only reference repos you trust.
+- **Containment.** The clone can't be made to read outside itself: `..` in `#subpath` is refused, remote repos are checked out with `core.symlinks=false` (a hostile `skills -> /etc` link becomes an inert text file, not a path the copy step follows), and the resolved directory is verified to sit inside the clone.
+- **Line endings are the pack's, not the host's.** The clone pins `core.autocrlf=false` and `core.eol=lf`, so a pack that declares no `.gitattributes` still materializes the bytes it has stored. Without it, Git for Windows' `core.autocrlf=true` default would rewrite the checkout to CRLF and a `mirror:` — copied verbatim — would land CRLF in your repo, showing up as a whole-pack diff after every sync.
+- **Private repos** rely on ambient credentials (an SSH agent or git credential helper). `sync` runs git with `GIT_TERMINAL_PROMPT=0`, so a missing credential fails fast with a warning instead of hanging; local sources still sync.
+- **Best-effort.** A clone failure (offline, bad URL, missing subpath) warns on stderr and skips that one source — the rest of the sync proceeds and still reports `IS_STATUS=ok`.
+
+#### Mirroring a pack into the repo
+
+Without `mirror:` a pack exists only inside the run cache, so the only trace of an upstream change is a shifted diff in the *generated* output, mixed in with your own content. Give the pack a `mirror:` and it is additionally materialized there, which makes a version bump readable as an ordinary diff:
+
+```yaml
+packs:
+  shared-intel:
+    url: https://github.com/org/shared-intel.git
+    ref: v1.2.0
+    mirror: "intelligence/external/shared-intel"   # omit to keep the pack transient
+```
+
+```
+intelligence/external/
+└── shared-intel/          # the path you declared — nothing is derived
+    ├── .pack              # url + ref + resolved SHA, written by sync
+    ├── rules/             # only the subpaths your sources reference
+    └── skills/
+```
+
+Commit that directory — being able to review `git diff` after bumping a pin is the entire point. `<umbrella>/external/<pack>` is the recommended location, but the value is a plain path, so packs can live wherever suits the repo, one per pack.
+
+- **The directory is declared, never derived.** `mirror:` says exactly where the pack goes, so there is no name to sanitize and no collision to resolve.
+- **`.pack` is output, not config.** sync writes it; nothing reads it as configuration and it is not meant to be hand-edited. The pin lives in `config.yaml`.
+- **Only the referenced subpaths are copied**, so a pack's `README`, CI config and tests never enter your repo. A reference with no subpath copies the whole repo.
+- **`.git` is never copied.** A nested repository would be recorded as a gitlink, whose contents git does not track — precisely the state this avoids.
+- **Cleared once per run.** The first entry to touch a pack clears its mirror, so content left by a previous ref (or by a source entry you have since deleted) does not linger; later entries only replace their own subpath.
+- **Never destructive.** The `.pack` stamp marks the directory as sync's to manage: a non-empty directory *without* one is left alone (with a warning) rather than deleted, so a directory of your own at that path is safe. A stamped directory stays the pack's even after you edit its `url:` — a moved or renamed upstream refreshes the mirror, which is the whole point of committing it. To hand a mirror path back to the project, delete the directory. A mirror that resolves to the repo root, escapes the repo, or sits inside a configured `sources.*` directory is refused outright — `sync` exits 1 before anything is written.
+- Mirrored files have committed paths, so `AGENTS.md` and the Pi adapter link to them like any local source instead of naming them bare. A transient pack has no such path and is still named bare.
+
+## Agent Frontmatter
+
+```yaml
+---
+name: agent-name                     # Kebab-case identifier
+description: When to use this agent  # Shown in IDE agent picker
+tier: heavy|standard|light           # Model capability (tool-agnostic)
+access: full|readonly                # Tool permissions (tool-agnostic)
+skills:                              # Optional: linked skills
+  - skill-name-1
+  - skill-name-2
+---
+
+Agent instructions in markdown...
+```
+
+### An agent is thin — it never restates the rules
+
+Body sections: **Expertise** → **Boundaries** (where it stops) → **Build & Verify**. What belongs to the agent is its role, its limits, and how it proves the work is done.
+
+**Do not instruct an agent to read the rules.** They reach it 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 and opencode receive always-on rules inlined in `AGENTS.md`. A `Read intelligence/rules/<domain>.md before starting` line is duplication: it doubles the tokens and creates a second copy that drifts from the rule it copied. Point at a rule by name if you must; never restate it. The urge to copy a rule into an agent means the rule is in the wrong place — move it.
+
+### Tier Mappings
+
+| Tier | Claude | Cursor | Copilot / Codex | opencode | Use for |
+|------|--------|--------|-----------------|----------|---------|
+| heavy | opus | (default) | gpt-5.6-sol | claude-opus-4-8 | Developers, complex reasoning, migration |
+| standard | sonnet | fast | gpt-5.6-terra | claude-sonnet-5 | Reviewers, validators, analysis |
+| light | haiku | fast | gpt-5.6-luna | claude-haiku-4-5 | Simple lookups, formatting |
+
+The vocabulary is tool-agnostic on purpose: the source says `tier: heavy`, and each adapter resolves it through `get_model()`. Defaults move forward as vendors ship new models — pin one per IDE/tier under `models:` in `config.yaml` only when you must, and expect a drift report on every sync once the default overtakes the pin.
+
+### Access Mappings
+
+| Access | Claude | Cursor | Description |
+|--------|--------|--------|-------------|
+| full | (no `tools:` field - inherits every session tool, MCP servers included) | (default) | Full edit access |
+| readonly | tools: Read,Grep,Glob,Bash + disallowedTools: Write,Edit | readonly: true | Analysis only |
+
+## Rule Frontmatter
+
+```yaml
+---
+paths:                               # Optional: path-based activation
+  - "src/backend/**"                 # Glob patterns from repo root
+  - "config/**"
+---
+
+Rule content in markdown...
+```
+
+- **With paths:** Rule auto-loads when user edits matching files
+- **Without paths:** Rule applies always (context rules)
+
+### Sync Transformations (Rules)
+
+| Source | Claude | Cursor | Copilot | Codex / Pi / opencode / AGENTS.md |
+|--------|--------|--------|---------|------------------------|
+| `paths:` (scoped) | copied | `globs:` in `.mdc` | `applyTo:` in `.instructions.md` | listed in AGENTS.md; Pi also gets generated on-demand rule files + extension |
+| no `paths:` (always-on) | copied | skipped | skipped | inlined into AGENTS.md |
+| extension | `.md` | `.mdc` | `.instructions.md` | inline / generated extension / n/a |
+
+Always-on rule content is inlined once into AGENTS.md (which Cursor, Copilot, Codex, Pi, and opencode read natively); the per-IDE rule channels carry only path-scoped rules to preserve monorepo glob targeting without duplicating context. Claude Code does not read AGENTS.md, so its adapter receives the full rule set. opencode has no first-class path-scoped channel (users may opt in via `instructions:` globs in `opencode.json`), so the opencode adapter does not generate scoped-rule files.
+
+## Skill Frontmatter
+
+Skills follow the [Agent Skills open standard](https://agentskills.io) (adopted by Claude Code, Cursor, GitHub Copilot, OpenAI Codex, Pi, Gemini CLI, OpenCode, Goose, Junie, and 30+ others). Required fields: `name` + `description`.
+
+```yaml
+---
+name: <domain>-<verb>-<noun>         # e.g., backend-add-endpoint
+description: What the skill does     # Shown in IDE skill picker
+argument-hint: <arg1> [arg2]         # Optional: usage hint
+---
+
+# Skill Title
+
+## Steps
+1. First step...
+2. Second step...
+```
+
+Standard optional fields (`license`, `compatibility`, `metadata`, `allowed-tools`) and IDE-specific extensions (Claude's `disable-model-invocation`, `model`, `effort`, `agent`, `context: fork`, `hooks`, `paths`, `shell`) pass through unchanged — adapters do not strip them. The engine's own flow skills declare `agent:` (`intelligence-review-skills` → `intelligence-architect`, the four sync/update/adapter flows → `intelligence-operator`); the binding takes effect where a tool honors it, and a skill invoked directly runs on the session model unless it also sets `context: fork`, as `intelligence-sync` does — the flows that can need the user mid-run (update, adapter install/removal) deliberately do not. Each tool ignores fields it does not understand.
+
+**Limits that reject the skill outright** (it does not degrade — it disappears from the picker):
+
+| Field | Limit | Failure |
+|---|---|---|
+| `description` | 1024 chars | *"Skill description must be at most 1024 characters"* |
+| `name` | 64 chars | rejected at load |
+| `argument-hint` | must be a **string** | `argument-hint: [pr-number]` is a YAML flow *sequence* unquoted → *"argument-hint must be a string"* |
+
+Sync quotes `description` and `argument-hint` for every target on the way out, so an unquoted hint is fixed automatically; the length limits it can only warn about (`lint_frontmatter` prints the file, line and actual length) — shortening the text is the author's call.
+
+### Naming Conventions
+
+Skill names are `<domain>-<verb>-<noun>`. Both parts are required.
+
+**Domain prefix** (the scope — required, never omit):
+
+| Source | Domain |
+|--------|--------|
+| Single / root project | Project codename from `config.yaml` → `project.name` |
+| Backend service / API | `backend-` |
+| Frontend / web / UI | `frontend-` |
+| Infrastructure / IaC / CI/CD | `devops-` |
+| Shared library / common code | `core-` |
+| Test suites (e2e, integration) | `tests-` |
+| Monorepo named components | Component name (e.g., `billing-`, `auth-`) |
+| Tool-internal (intelligence-sync) | `intelligence-` |
+
+Reuse an existing domain whenever possible. Do not invent new domains without clear need.
+
+**Verb prefix** (the action):
+
+| Verb | Type | Description |
+|------|------|-------------|
+| `add-` | Append | Puts one new member into a set that already exists |
+| `create-` | Originate | Brings into existence the container nothing hosted before |
+| `update-` | Revise | Changes what is already there, selectively |
+| `run-` | Execution | Runs an operation (tests, sync, build) |
+| `review-` | Read-only | Analyzes code without changes |
+| `test-` | Testing | Manual or automated test verification |
+| `remove-` | Deletion | Safely removes an artifact |
+
+Agents follow the same domain prefix rule: `<domain>-<role>` (e.g., `backend-developer`, `frontend-code-reviewer`). Rule filenames use the domain without a verb: `<domain>.md` (e.g., `backend.md`).
+
+### How much a skill body carries
+
+A skill that does the work itself carries the detail: the patterns, the code, the examples. A skill that dispatches to other skills stays thin — it names them and adds only what it alone knows (the discovery, the order, the check between steps), and it never restates their content, because two copies of a procedure disagree at the first edit.
+
+Which of the two a skill is has nothing to do with its verb. An `add-` skill may dispatch, and a `create-` skill may do the work itself: the verb answers what already existed (Verb prefix, above), not how the skill is built inside.
+
+## Authoring Discipline
+
+### Writing description fields
+
+Each skill, rule, and agent has a `description` field in frontmatter. This field is loaded into every IDE's available-skills context. **Total description tokens across all artifacts compete for a shared budget** — with a large registry, longer descriptions push other skills out of reach.
+
+Two cases:
+
+| Case | Format | Length target |
+|---|---|---|
+| **Unique skill** (no siblings doing similar action) | Plain verb-noun phrase | 4-8 words |
+| **Skill with siblings** (multiple similar skills in registry) | verb-noun + distinct trigger phrase | 10-20 words, ~250 chars |
+
+Two different numbers, do not confuse them: **~250 chars is the house budget** (what keeps the shared registry affordable), while **1024 chars is a wall** — Claude Code and the Agent Skills standard reject a longer `description` outright and the artifact disappears from the picker. Sync warns at the wall (`lint_frontmatter`); staying near the budget is the author's job.
+
+Examples:
+
+```yaml
+# Unique skill — short is fine
+description: "Create new intelligence rule"
+
+# Sibling skill — needs distinguishing trigger
+description: "Run weekly check-up: retrospective + strategic analysis + next week planning"
+```
+
+When the registry grows past comfortable budget, prefer **curation** (merge duplicates, archive orphans via `intelligence-review-skills`) over truncating descriptions individually.
+
+### Size discipline — the backstop, not the goal
+
+The goal is **subtraction** (see the `intelligence-authoring` rule the engine ships): every line is loaded into someone's context out of a shared, finite budget, so the default answer to "should this be a rule?" is no. These caps are only the line past which something is definitely wrong.
+
+| Type | Hard cap | Over the cap |
+|---|---|---|
+| SKILL.md body | 1000 lines | Move detail into `references/<topic>.md` and point at it |
+| Reference file (`references/*.md`) | 500 lines | Add a table of contents past 300 lines |
+| Rule | 500 lines | Split by sub-scope, or move pattern detail to `references/` |
+| Agent | 200 lines | Refactor — agents stay thin; heavy content lives in skills and rules |
+
+**Ceilings, not quotas.** An artifact that says everything it needs to is finished, not underweight. Over the cap means it is doing two jobs, or the detail belongs behind a pointer: `Read references/<topic>.md when [condition].`
+
+Resource organization — **content lives inside the skill that uses it, by default**:
+
+```
+skill-name/
+├── SKILL.md (required)
+├── references/    — Detailed docs, loaded on demand
+├── scripts/       — Executable helpers for deterministic / repetitive steps
+└── assets/        — Files used in output (templates, fonts, icons)
+```
+
+Sync copies the whole directory, so a bundled helper travels with its skill into every tool. **Promote a helper out of the skill folder only when a second skill needs it** — then it lives beside the source groups (e.g. `<umbrella>/scripts/`) and every skill resolves it the same way. The dividing line is reuse, not repetition: a helper one skill runs a hundred times still belongs to that skill.
+
+### Writing principles
+
+Apply to skill bodies, rule bodies, and agent bodies — anywhere LLM-facing instructions are authored.
+
+**Use imperative form.** "Read the config file" works better than "You should read the config file."
+
+**Explain the WHY.** LLMs follow positive instructions better when reasoning is visible. "Use module boundaries — AI knows which imports are allowed without guessing" works better than "Use module boundaries (MUST)."
+
+**Reserve absolute language for true invariants.** ALL-CAPS MUSTs and NEVERs fit security, safety, output format — places where the constraint is non-negotiable. For judgment calls, write **decision rules** in positive form: "When X, do Y" instead of "NEVER do Z." If you find yourself writing ALWAYS or NEVER in all caps for a judgment call, that's a yellow flag — reframe and explain the reasoning.
+
+**Keep prompts lean.** Remove instructions that aren't pulling their weight. Padding wastes context and dilutes the instructions that matter.
+
+**Lead with positive defaults.** Rule body order: REQUIRED → Invariants → Architecture → Build & Test → Examples → Patterns to recognize and replace. The LLM acts on the positive instruction it reads first; anti-patterns sit at the end as reference documentation, not as instructions.
+
+**Bundle repeated patterns as scripts.** If the LLM reinvents the same helper on every invocation, encode it in `scripts/` and have the skill call it.
+
+## Generated Output
+
+| Target | Rules output | Skills location | Agents location | Git-ignored |
+|--------|--------------|-----------------|-----------------|-------------|
+| `agents` | inlined into `AGENTS.md` (always-on); listed (scoped) | n/a | listed in `AGENTS.md` | No (committed) |
+| Claude Code | `.claude/rules/` (full) | `.claude/skills/` | `.claude/agents/` | Yes |
+| Cursor | `.cursor/rules/*.mdc` (scoped only) | `.cursor/skills/` | `.cursor/agents/` | Yes |
+| GitHub Copilot | `.github/instructions/*.instructions.md` (scoped only) | `.github/skills/` | `.github/agents/` | Partial |
+| OpenAI Codex | none (reads `AGENTS.md`) | `.agents/skills/` | `.codex/agents/*.toml` | Yes |
+| Pi | `.pi/intelligence-sync/rules/*.md` + `.pi/extensions/intelligence-sync-rules.ts` (scoped only; always-on via `AGENTS.md`) | `.agents/skills/` | `.pi/prompts/intelligence-agent-*.md` | Partial |
+| opencode | none (always-on via `AGENTS.md`; users may opt in to scoped rules via `instructions:` globs in `opencode.json`) | `.agents/skills/` | `.opencode/agents/*.md` (mode: subagent) | Yes |
+
+Skill locations all comply with the Agent Skills open standard. Cursor reads from `.cursor/skills/` and `.agents/skills/`; Copilot reads from `.github/skills/`, `.claude/skills/`, and `.agents/skills/`; Codex, Pi, and opencode all read from `.agents/skills/`; Claude Code reads from `.claude/skills/`.
+
+**Rule routing rationale:** AGENTS.md is canonical for Cursor/Copilot/Codex/Pi/opencode (all read it natively), so always-on rule content is inlined there once and the per-IDE rule directories carry only path-scoped rules — no duplication. Claude Code does not read AGENTS.md, so its adapter receives the full rule set.
+
+`AGENTS.md` is always enabled and regenerated on every sync. The static header (`targets.agents.header` in `config.yaml`) is the only hand-authored part; everything below it is rebuilt from frontmatter — agents/skills tables, the rules list, and the inlined content of every always-on rule (those without `paths:`). Path-scoped rules are listed by name only so AGENTS.md does not balloon in monorepos.
+
+## Migration & Module Contract
+
+Structural changes to the module layout are handled by **versioned migrations**, not ad-hoc scripts or manual instructions. The model is designed for an *unbounded, uncoordinated* upgrade window — a project may sit on an old version indefinitely and still migrate safely whenever it finally runs.
+
+**Division of responsibility**
+
+- **Bash = deterministic, fail-closed core.** It performs only mechanically safe, reversible-until-committed steps and **never guesses**. Any state it cannot resolve safely is reported, not forced.
+- **`intelligence-update` skill = intelligent layer.** It detects project state, bootstraps the engine, runs bash, interprets the status, and resolves the cases bash refuses (asking the user when genuinely ambiguous).
+
+**The schema-version contract key.** The applied schema version is a managed, top-level scalar `sync_version` in `config.yaml` — *not* a dotfile, *not* `scripts/VERSION`. `config.yaml` is what most future breaking changes reshape, so the schema version lives with what it versions. **Invariant: this key is permanent and format-stable** — no migration may ever rename, move, or change its shape, so any engine (however old/new) can always read "what schema is this?" before parsing the rest. The bootstrap/INIT flow emits it for fresh projects (= engine `scripts/VERSION`) and must preserve it on re-bootstrap. `scripts/VERSION` = what the engine *is*; the key = what has been *applied*; the gap = pending breaking changes.
+
+**Every `migrate_to_<ver>` obeys this contract**
+
+1. **Version-named & ordered.** Suffix is the target version (`migrate_to_0_3_1`); listed in `MIGRATIONS=()` ascending, append-only — never reorder or rewrite shipped migrations.
+2. **Idempotent structural precondition is the correctness mechanism.** Each migration self-detects from the actual on-disk/config structure whether its change is already applied, and is a silent no-op if so. The dispatcher runs the whole chain in order; it does **not** gate on the version stamp — so a wrong/missing `sync_version` can never cause a needed migration to be skipped. Replaying any number of times never fails or duplicates.
+3. **Transactional / fail-closed.** Stage → **verify postcondition (sentinel)** → commit → only then delete the old state. A crash or partial input leaves the prior state intact; nothing is destroyed before the replacement is verified.
+4. **Version-compat guard.** A stale engine refuses to operate on a project whose `sync_version` is newer than it understands (`ahead-of-engine`). This is the *only* role of the stamp — a guard, never a gate.
+5. **Status hand-off is first-class.** "Cannot safely automate" is a normal outcome, reported via the contract below — not an error to paper over.
+
+**Breaking-change releases carry a `### Breaking` CHANGELOG subsection**, each item stating its post-condition. The `intelligence-update` skill reads the changelog across the version gap, surfaces these, and verifies each post-condition after applying. `sync.sh` is a pure synchronizer — it never migrates; it fails closed (`needs-update`) across an un-applied gap so a stale engine can't generate against a newer schema. `update.sh` (+ the skill) is the sole migrator.
+
+**bash ↔ skill status contract** (codes are public; never renumber)
+
+| `IS_STATUS` | exit | Meaning |
+|---|---|---|
+| `ok` | 0 | Up to date / nothing to do |
+| `migrated` | 0 | Migration performed this run |
+| `error` | 1 | Generic failure (detail in message) |
+| `config-missing` | 2 | No `config.yaml` — project not bootstrapped |
+| `ambiguous` | 3 | Conflicting state; skill/human-only (bash never emits it) |
+| `ahead-of-engine` | 4 | Project schema newer than this engine |
+| `aborted-incomplete` | 5 | Staged module incomplete; prior state left intact |
+| `needs-update` | 6 | Pending breaking changes — run the update flow first |
+
+Bash emits `IS_STATUS=<code> [IS_DETAIL=...]` on stdout and exits with the matching code; callers capture it with `cmd || rc=$?` (never `if ! cmd; then exit $?` — that loses the code). The skill branches on the code.
+
+**Module model.** The engine self-locates by its own path; it does not assume a folder name (`sync/` by convention). Each `<umbrella>/<module>/` is self-contained: its own `scripts/`(+`VERSION`), `skills/`, `INIT.md`, `docs/`. Modules update independently and never touch sibling modules or project content (`rules/`, `agents/`, non-meta `skills/`) nor `config.yaml` beyond the idempotent additive `sources.skills` line and the `sync_version` key.
+
+## .gitignore Pattern
+
+```
+# AI IDE tools (generated by intelligence-sync, local preferences)
+CLAUDE.md
+.cursorrules
+.agents/
+.codex/
+.pi/intelligence-sync/
+.pi/extensions/intelligence-sync-rules.ts
+.pi/prompts/intelligence-agent-*.md
+
+# opencode: the generated subagents and slash commands are owned by the adapter.
+# .opencode/opencode.json (and any other hand-authored config) stays tracked.
+.opencode/agents/
+.opencode/commands/
+
+# Claude Code: ignore everything except project-shared settings.
+.claude/*
+!.claude/settings.json
+
+# Cursor: same pattern.
+.cursor/*
+!.cursor/settings.json
+```
+
+The inverse pattern (`.claude/*` + `!.claude/settings.json`) ignores every generated subdir (`rules/`, `skills/`, `agents/`) plus any per-machine state Claude writes (`settings.local.json`, `*.lock`, `scheduled_tasks.*`, `sessions/`, `cache/`, etc.) without having to enumerate filenames Claude may add later. Only `.claude/settings.json` (project-shared bash allowlist, tool permissions) is tracked. Same logic for `.cursor/`. Pi and opencode are narrower: only the generated adapter-owned paths are ignored (`.pi/intelligence-sync/`, `.pi/extensions/intelligence-sync-rules.ts`, `.pi/prompts/intelligence-agent-*.md`, `.opencode/agents/`, `.opencode/commands/`), so `.pi/settings.json`, `.opencode/opencode.json`, and any hand-authored Pi extensions/prompts remain available for tracking. The opencode adapter additionally protects hand-authored slash commands by an emit-marker (`<!-- Generated by intelligence-sync. Do not edit manually. -->`): re-sync only deletes marker-bearing files in `.opencode/commands/`, so a project may track a hand-authored command alongside the generated ones (typically by un-ignoring it). If a project needs to track another file under `.claude/` or `.cursor/` (e.g., a hand-authored `.claude/commands/<name>.md`), add another `!<path>` line.
+
+## Project Entry Points
+
+| File | Role | Git status |
+|------|------|-----------|
+| `AGENTS.md` | Auto-generated canonical project doc for LLMs (do not edit manually) | Tracked |
+| `CLAUDE.md` | Local user preferences (gitignored) | Ignored |
+| `<umbrella>/config.yaml` | Sync config + `sync_version` schema-version contract key (committed) | Tracked |
+| `<umbrella>/{rules,agents,skills}/` | Project source of truth | Tracked |
+| `<umbrella>/sync/` | intelligence-sync module (engine+`scripts/VERSION`, meta-skills, INIT, docs) — vendored upstream-owned | Tracked |

package/engine/rules/intelligence-authoring.md

@@ -0,0 +1,114 @@
+---
+name: intelligence-authoring
+description: "Authoring discipline for the intelligence layer - subtraction first, rule vs skill vs agent, scoping, size"
+paths:
+  - "<umbrella>/**"
+---
+
+# 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.
+
+## Subtraction is the job
+
+**Every line here is loaded into someone's context, and that budget is shared and finite.** An always-on rule is loaded into *every* session, forever. A line you add is a line something else loses — and the loss is invisible, so nobody ever notices what it cost.
+
+So the default answer to "should this be a rule?" is **no**. Delete before you add. Merge before you split. The registry that gets trusted is the small one: a crowded one gets skimmed, and a skimmed rule is worse than a missing one, because it looks like coverage.
+
+Three ways to shorten, in order of what they are worth:
+
+1. **Make the rule unnecessary.** The best rule is a gate the model cannot skip. A rule that lists which command to run for which change is a *menu*, and a menu gets ordered from; the same decision expressed once, in a script the work has to pass through, cannot be forgotten, mis-remembered or skimmed past. **Ask this first, every time.**
+2. **Delete what the code already says.** A rule restating what a reader can see in the file is noise, and noise trains people to skim the lines that are not.
+3. **Cut the words, keep the reason.** Prose can shrink; the *why* cannot — an instruction without its reason does not survive contact with a judgement call.
+
+**Never solve a problem by adding an artifact when moving one, or removing one, would do.** A new rule is the most expensive answer available, and it is the one that feels cheapest to write.
+
+## Source of truth
+
+Edit the sources listed in `config.yaml` — the `rules/`, `agents/` and `skills/` directories it names — and `config.yaml` itself. 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 vendored engine. It owns its own rules, agents and meta-skills; `update.sh` replaces them wholesale, so a local edit there is lost at the next update. Fix it upstream instead.
+
+After any change: `<sync-cmd>`. A change that was not synced does not exist for any tool.
+
+## Pick the right artifact
+
+| Type | Intent | How it loads |
+|---|---|---|
+| **Rule** | The model **respects** a constraint while doing other work | Automatically — always-on, or path-scoped via `paths:` |
+| **Skill** | The model **performs** a defined procedure | Explicitly — `/skill-name` |
+| **Agent** | The model **adopts** a persona | Explicitly — via the agent picker |
+
+The mistakes that actually happen, in order of frequency:
+
+- A **checklist** written into an agent body → a checklist is a *procedure*; it belongs in a **skill**. This one keeps happening because a checklist *feels* like expertise. It is not: it changes with the task, a role does not. An agent is what it is for, what it optimises for, where it stops, and what it calls done.
+- A **convention** written into an agent body → it belongs in a **rule**, so every agent gets it, not just the one you happened to be editing.
+- A **workflow** written into a rule body → it belongs in a **skill**. A rule is loaded always; a procedure should be invoked.
+- **Expertise** written into a skill body → it belongs in an **agent**; the persona is reusable across skills.
+
+## Rules
+
+**Scope with `paths:`.** A rule without `paths:` is loaded into *every* session and inlined into `AGENTS.md` — the most expensive context real estate there is. Earn it. A rule that only matters when someone touches the frontend belongs scoped to the frontend.
+
+**Lead with the positive default, then the invariant.** The model acts on the first instruction it reads, and it follows whatever is named — negation ("never do X") draws attention to X. Reserve absolute language (NEVER, MUST) for true must-nots: safety, security, output format. A judgement call written as a NEVER only teaches the model that NEVERs are negotiable.
+
+**Derive from the code, not from prose that already exists.** Every REQUIRED and every invariant must be backed by something observed in the repository. Documentation is a claim, not evidence — read the file.
+
+**Describe the repository, not a machine.** The OS, the shell, the editor, a local dev stack, personal tooling — these are environment facts. They belong in a personal, gitignored `CLAUDE.md`. A rule is committed and read by everyone, so a shell-specific command or an absolute local path in it is simply wrong for whoever is on another platform.
+
+**Explain the why — but only a why you can back.** A reason the reader can check is what makes an instruction survive a judgement call. An invented reason is worse than none: it sounds like evidence.
+
+### Invariants
+
+- **Never state behaviour of a tool or engine you have not verified in its documentation or source.** This invariant exists because the claim *"Claude Code does not auto-load `.claude/rules/`"* was once written into this layer as fact. It is false — rules without `paths:` load at launch, path-scoped ones activate on matching files, and custom subagents inherit both (Claude Code docs: *Memory → Organize rules with `.claude/rules/`*, and *Subagents → What loads at startup*). An unverified claim about tooling is worse than a gap: nothing in the repository contradicts it, so it silently reshapes every decision downstream.
+- **Never write a current defect into a rule as if it were the design.** Known breakage belongs in one place that says so. Every other rule describes the project *as it is meant to work* — a workaround documented as procedure becomes permanent.
+- **Never link from one always-on rule to another.** Always-on rules are inlined verbatim into `AGENTS.md`, and the path-scoped channels carry only scoped rules, so a relative link is dead in at least one output. Name the rule instead; it loads on its own.
+
+## Agents
+
+An agent is **thin**: who it is, where it stops, how it verifies. Nothing else.
+
+- **Do not list rules for an agent to read.** They load on their own — Claude Code loads `.claude/rules/` into every custom subagent's startup context, and Cursor, Copilot, Codex, Pi and opencode receive always-on rules inlined in `AGENTS.md`. Naming a rule is fine; copying it is duplication that drifts.
+- **Point at a rule, do not restate it.** Wanting to copy a rule into an agent means the rule is in the wrong place — move it.
+- **Do carry** what is genuinely the agent's own: its boundaries ("if the app will not start, stop — do not hand-write the output"), its verification commands, its definition of done.
+
+## Skills
+
+A skill is a repeatable procedure someone invokes, and **it ends in a verification**. If there is nothing to verify at the end, or it will only ever run once, it is not a skill — it is a note, or just the work.
+
+### Naming
+
+`<domain>-<verb>-<noun>`. The domain prefix carries the weight: it clusters siblings and says which system the skill acts on. Take it from the set already in use; add a new domain deliberately, not by accident.
+
+The verb just names the action — `add-`, `run-`, `review-`, `extract-`, `plan-`, `validate-` all read fine. Prefer a verb already in use over a new synonym for the same thing. A stage that turns one thing into another reads naturally as `<domain>-to-<target>`.
+
+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 is pruned by the updater — rename it.
+
+### Shape
+
+- **A skill is executed, so it must not hardcode what can move.** Its steps are followed literally: a path, a command or a project name baked into a procedure breaks the moment the layout moves. Resolve them from a rule or from `config.yaml` instead. This does **not** apply to rules and agents — a rule's job is to *describe* the repository, so naming a path in prose is exactly right. Naming a path is description; baking one into a procedure is a defect waiting to fire.
+- **Keep everything the skill needs inside the skill's own folder.** The Agent Skills standard lets a skill ship `scripts/`, `references/` and `assets/` beside `SKILL.md`, and sync copies the whole directory, so a bundled helper travels with the skill to every tool. That is the default.
+- **Promote a helper out of the skill folder only when a second skill needs it** — then it belongs beside the source groups, and every skill resolves it the same way. The dividing line is reuse, not repetition: one skill's helper stays with that skill however often it runs.
+- **A helper is code.** It gets what code gets — a test, and a way to run it that does not assume one person's machine.
+
+## Size — the backstop, not the goal
+
+The goal is subtraction, above. These are only the line past which something is definitely wrong.
+
+| Type | Hard cap |
+|---|---|
+| Rule | 500 lines |
+| Agent | 200 lines |
+| `SKILL.md` | 1000 lines |
+
+**Ceilings, not quotas.** An artifact that says everything it needs to is finished, not underweight — nothing here is a reason to pad. Over the cap means the artifact is doing two jobs, or the detail belongs in `references/<topic>.md` with a pointer from the body.
+
+`description` fields compete for one shared budget across the whole registry: a long one pushes another artifact out of reach. Four to eight words when the name is unambiguous; longer only when a sibling does something similar and needs distinguishing. (The tools reject a `description` over 1024 characters outright — but that is a wall to stay far away from, not a target.)
+
+## 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`.
+
+A change to this layer is done when `<sync-cmd>` reports `IS_STATUS=ok` and the skill you invoked reports clean.

package/engine/scripts/VERSION

@@ -0,0 +1 @@
+0.11.0