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

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

@@ -0,0 +1,79 @@
+# Migrating Existing AI Instructions
+
+Read this reference only when repository onboarding finds pre-existing AI
+instructions, an `<content-dir>/_backup/` created by `intelligence init`, or a
+Git diff showing that the first sync replaced tracked tool output.
+
+## Inventory and recovery
+
+When `<content-dir>/_backup/manifest.tsv` contains
+`state<TAB>initial-onboarding`, it is the authoritative inventory from before
+the first generated write. Read each `target` and `path` record before looking
+at current adapter output. If `path<TAB>AGENTS.md` is present, the backed-up
+file is the original custom project contract; keep following it while deciding
+how to migrate its durable guidance.
+
+Treat these as migration inputs, not as current generated output:
+
+- root `AGENTS.md`, `CLAUDE.md`, `.cursorrules`, and
+  `.github/copilot-instructions.md`;
+- Claude and Cursor rules, agents, skills, and commands;
+- Copilot instructions, prompts, agents, and skills;
+- Codex/Open Agent Skills, Pi rules/prompts, and OpenCode agents/commands;
+- scripts or documentation that describe an older sync path.
+
+Prefer the copy under `<content-dir>/_backup/`. If it is absent and the first
+sync changed tracked files, inspect their pre-sync content read-only through
+Git (`git diff` and `git show HEAD:<path>`). Never restore old content directly
+into an adapter output directory.
+
+Build one conflict report before proposing changes:
+
+- `MIGRATE`: instruction-bearing files whose useful content needs a
+  project-owned destination;
+- `PRESERVE`: settings and unrelated shared files the adapters do not own;
+- `REPLACE`: adapter-owned paths that sync regenerates;
+- `STALE`: references to removed paths or commands requiring a decision.
+
+Always preserve `.claude/settings.json`, `.claude/settings.local.json`,
+`.cursor/settings.json`, Git metadata, workflows, and non-AI repository files.
+
+## Reverse mappings
+
+Migrate meaning, not tool syntax:
+
+| Existing format | Project-owned destination |
+|---|---|
+| Root `AGENTS.md`, `CLAUDE.md`, `.cursorrules`, Copilot root instructions | Split verified guidance by topic into rules; keep local machine preferences in a gitignored root file only when no adapter representation exists |
+| `.claude/rules/*.md` | Rule; preserve valid `paths:` |
+| `.cursor/rules/*.mdc` | Rule; rename `globs:` to `paths:` and remove `alwaysApply:` |
+| Claude/Cursor/Copilot agents | Agent; map native model/readonly/tool fields back to `tier:` and `access:` |
+| Claude/Cursor/Copilot skills or commands | Skill when the procedure is repeated, multi-step, stable, and verifiable; otherwise a rule or no artifact |
+| Pi/OpenCode/Codex prompt artifacts | Rule, agent, or skill according to responsibility, after removing tool-specific wrappers |
+
+Verify every retained claim against repository code or executable
+configuration. Do not preserve stale instructions merely because they existed.
+Prefer updating an existing project-owned artifact to creating a sibling.
+
+## Apply and cleanup
+
+Obtain approval per `CREATE`, `UPDATE`, `REMOVE`, or `KEEP` proposal. Apply
+project-owned source changes first, then run `intelligence sync` and
+`intelligence status --check`. Inspect the enabled targets to prove the
+migrated guidance arrived before removing old root instructions or tool files.
+
+For every removed or renamed path, search all tracked files with `git ls-files`
+and report remaining references with file and line number. Apply an unambiguous
+replacement directly; ask about narrative or otherwise ambiguous references.
+
+The CLI owns generated-output `.gitignore` entries and its blocks in existing
+`.vscodeignore`, `.npmignore`, and `.dockerignore` files. Verify them against
+the enabled adapters. Treat CLI-reported tracked ignored paths as unresolved
+until the user approves the exact `git rm --cached` commands. Preserve
+`AGENTS.md`, `.github/`, shared settings, and unrelated files under shared tool
+roots in Git, while excluding development-only Intelligence content from
+published artifacts. Inspect the packager's actual file list before release;
+do not infer package or Docker context contents from Git status.
+
+Keep `<content-dir>/_backup/` until the user separately approves its removal
+after migration and reference checks pass. The backup remains gitignored.

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

@@ -22,17 +22,24 @@ rules, agents, and skills.
    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
+3. Run `intelligence adapter create $ARGUMENTS`, then keep
+   `adapter_contract_$ARGUMENTS()` aligned with every path the adapter writes
+   and 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.
+   the configured output, make reruns idempotent, distinguish exclusive
+   `owned` paths from marker-based/shared `managed` paths, and declare exact
+   legacy, preserved, dependency, ignore, and include records when applicable.
 
 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.
 
+   The CLI derives generated-output ignores from the adapter contract. Do not
+   edit `.gitignore` manually; correct the contract when policy is wrong, and
+   never ignore a shared output root.
+
 5. Require `IS_STATUS=ok`, inspect generated files against the researched
-   format, run the tool's validator when one exists, and finish with
+   format, deliberately fail a later test adapter to prove transactional
+   rollback when contributing a built-in, 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

@@ -1,12 +1,29 @@
 ---
 name: intelligence-learn-from-context
-description: "Capture session lessons and apply to intelligence/ after approval"
-argument-hint: <optional-lesson-statement>
+description: "Capture one approved lesson from a session in an established Intelligence project"
 ---
 
 # Learn from Context
 
-Use after a session where a meaningful preference, working pattern, or recurring friction emerged that should persist into future sessions. Runs in two phases — analyze (read-only) then apply (after user approval).
+Use after repository onboarding is complete and a meaningful preference,
+working pattern, or recurring friction emerged during the current session and
+should persist. It runs analyze (read-only), then apply after approval. This
+skill extends an established project; it does not perform first-run repository
+analysis or migrate legacy instructions.
+
+## Onboarding gate
+
+1. Locate `<manifest>`, `<content-dir>`, and `<module>`, then run
+   `intelligence status --check`.
+2. If setup is missing or inconsistent, stop and ask the user to repair it with
+   `intelligence init`; then use `/intelligence-learn-from-repository`. Do not
+   reproduce CLI mechanics.
+3. If the generated header says onboarding is pending, or preserved legacy
+   evidence still has unresolved instructions, stop and route to
+   `/intelligence-learn-from-repository`. A retained
+   `<content-dir>/_backup/manifest.tsv` or converted legacy config alone does
+   not mean onboarding is incomplete; those may remain as intentionally kept
+   evidence after the transitional header and conflicts are resolved.
 
 ## Principle: positive framing
 
@@ -60,10 +77,12 @@ Present the proposal list to the user. User accepts or rejects per item. Only ac
    - `UPDATE` existing artifact → edit the file directly, applying the proposed change
    - `ARCHIVE` → move to `<content-dir>/_archive/` and update cross-references that point at it
 
-8. **Run `/intelligence-sync`** once all accepted items are applied.
+8. Run `intelligence sync` once all accepted items are applied. Require
+   `IS_STATUS=ok`, then run `intelligence status --check`.
 
 ## Related skills
 
+- `intelligence-learn-from-repository` — first-run onboarding and legacy instruction migration; use it before this skill
 - `intelligence-extract-skill` — when the lesson is a multi-step workflow to be made reusable
 - `intelligence-review-skills` — broader audit across existing intelligence/ artifacts
 - `intelligence-add-rule`, `intelligence-add-skill`, `intelligence-add-agent` — each authors one artifact; Phase B delegates to them

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

@@ -1,55 +1,107 @@
 ---
 name: intelligence-learn-from-repository
-description: "Tailor Intelligence to an initialized repository"
+description: "Recover and complete first-time Intelligence repository onboarding"
 ---
 
 # Learn from Repository
 
-Use after `intelligence init` creates or converts a project. The CLI owns the
-mechanical setup; this skill adds only repository-specific judgement.
+Use once after `intelligence init` creates or converts a project. This is the
+only skill that owns initial backup migration, interrupted-setup recovery, and
+the first repository-specific Intelligence layer. The CLI owns deterministic
+mechanics; this skill supplies repository judgement.
 
-## Analyze
+## Recover or verify setup
 
-1. Run `intelligence status --check`. If setup is missing or incomplete, stop
-   and ask the user to run `intelligence init`; do not reproduce CLI mechanics.
-2. Read `<manifest>` and resolve `<content-dir>` and the configured source
-   directories. Load `<module>/references/conventions.md` and the bundled
+1. Locate `<manifest>`, `<content-dir>`, and `<module>`. If first sync failed
+   before the slash command was installed, these instructions can be opened
+   directly from
+   `.intelligence/packages/@ainova-systems/sync/skills/intelligence-learn-from-repository/SKILL.md`.
+2. Inspect `<content-dir>/_backup/manifest.tsv`. A
+   `state<TAB>initial-onboarding` record identifies the byte-preserved state
+   from before Intelligence first wrote adapter output. Read every `path`
+   record and treat it as migration input, never generated output. A
+   `.intelligence/backup/config.yaml` file identifies a converted legacy
+   Intelligence Sync project; use the converted sources and that config as
+   migration evidence.
+3. Run `intelligence status --check`. If the project is missing, inconsistent,
+   or its first sync failed, run `intelligence init --preview`, show the exact
+   repair plan, and request approval. After approval run
+   `intelligence init --apply`. Do not reproduce manifest, package, adapter,
+   backup, or ignore-file mechanics manually.
+4. Run `intelligence sync`. Sync is transactional: a failure restores every
+   adapter-owned path. Resolve the reported cause and retry. Do not begin
+   semantic migration until `IS_STATUS=ok` and `intelligence status --check`
+   is clean.
+
+## Analyze repository evidence
+
+5. Read `<manifest>` and resolve the configured source directories. Load
+   `<module>/references/conventions.md` and the bundled
    `intelligence-add-rule`, `intelligence-add-skill`, and
-   `intelligence-add-agent` skills before proposing authored content.
-3. Inspect repository evidence: its README and contributor instructions,
-   language and package manifests, build and test entry points, source layout,
-   CI, existing agent instructions, and existing project-owned rules, agents,
-   and skills. Treat documentation as a claim and verify important behavior in
-   code or executable configuration.
-4. Inventory what initialization already preserved or installed. Do not
+   `intelligence-add-agent` skills before proposing authored content. When
+   preserved or legacy instructions exist, also read
+   `<module>/references/onboarding-migration.md` and use its inventory,
+   reverse-mapping, packaging-safety, and stale-reference procedures.
+6. Inspect the README and contributor instructions, language and package
+   manifests, build and test entry points, source layout, CI, existing agent
+   instructions, and project-owned rules, agents, and skills. Detect
+   submodules and treat them as separate repositories unless the user includes
+   them. Treat documentation as a claim and verify important behavior in code
+   or executable configuration.
+7. Inventory what initialization preserved or installed. Compare project-owned
+   rules, agents, and skills with every configured package source. Do not
    recreate package-owned content, duplicate existing instructions, or convert
-   generated target output into source content.
-5. Propose the smallest useful project-owned layer. Prefer updating an existing
-   artifact over creating a sibling. Each proposal must state:
-   - `CREATE`, `UPDATE`, or `KEEP`;
+   generated target output into source content. When a project artifact is
+   materially covered by package content, propose `REMOVE` or a smaller
+   `UPDATE`; require a content comparison, not merely a matching name.
+
+   Treat committed legacy root instructions such as `.cursorrules` and an
+   instruction-bearing `CLAUDE.md` as migration sources, not permanent parallel
+   entry points. Propose moving still-valid guidance into project-owned rules
+   and removing the legacy file after generated output is verified. Keep one
+   only for genuinely local, gitignored configuration an adapter cannot
+   represent. `AGENTS.md` remains the shared root instruction entry point.
+
+   Review `.gitignore` and every existing `.vscodeignore`, `.npmignore`, and
+   `.dockerignore` against the CLI-managed policy. Detect tracked files which
+   still bypass newly added Git ignore rules. Treat missing managed patterns as
+   setup corrections, preserve unrelated entries, and verify actual package or
+   build contents before release.
+8. Propose the smallest useful project-owned layer. Prefer updating an existing
+   artifact over creating a sibling. Each proposal states:
+   - `CREATE`, `UPDATE`, `REMOVE`, or `KEEP`;
    - the source path;
-   - the repository evidence supporting it;
-   - the concise content or responsibility it would add.
+   - repository evidence;
+   - the concise content or responsibility it adds.
 
-Analysis is read-only. Present the proposal and request approval per change.
-It is valid to recommend no new artifacts when the repository already explains
-itself well.
+   When `targets.agents.header` is absent or generic, also propose a concise
+   manifest header with the project name, verified stack summary, and link to
+   its canonical context rule. Keep it to 3-5 lines. Replacing any
+   `onboarding is pending` backup pointer is part of completion.
+
+Analysis is read-only. Present the proposal and request approval per change. It
+is valid to recommend no authored artifacts when the repository already
+explains itself well.
 
 ## Apply after approval
 
-6. Apply only accepted proposals. Delegate new artifacts to
+9. Apply only accepted proposals. Delegate new artifacts to
    `intelligence-add-rule`, `intelligence-add-skill`, or
    `intelligence-add-agent`; update an existing project-owned artifact directly
-   when that is the smaller change. Never edit installed package content or
-   generated tool output.
-7. Run `intelligence sync`, then `intelligence status --check`. Completion
-   requires `IS_STATUS=ok` and a clean consistency check.
-8. Report what was created, updated, or deliberately left unchanged. Remind the
-   user to review and commit generated and source changes according to project
-   policy.
-
-## Related skill
-
-Use `intelligence-learn-from-context` later to preserve a lesson learned during
-a working session. This skill learns the repository's existing structure and
-workflow during onboarding.
+   when smaller, and edit an accepted manifest header directly. Never edit
+   installed package content or generated tool output.
+10. Run `intelligence sync`, then `intelligence status --check`. Inspect the
+    relevant generated `AGENTS.md`, Cursor rules, Claude rules, and any
+    packaging/build file list affected by ignore policy. Only then remove each
+    separately approved legacy root instruction file and rerun the consistency
+    check. Completion requires `IS_STATUS=ok`, a clean final check, and no
+    `onboarding is pending` header after accepted migration.
+11. Report what was created, updated, removed, or deliberately kept. Remind the
+    user to commit source, manifest, lock, `AGENTS.md`, and shared `.github/`
+    changes. Keep or remove the initial backup only by separate user approval.
+
+## Later learning
+
+After onboarding is complete, use `/intelligence-learn-from-context` to capture
+a durable lesson from a working session. It does not repeat repository
+onboarding.

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

@@ -82,5 +82,5 @@ The user accepts items individually; bulk-accept for low-impact tweaks is fine.
 
 ## Related skills
 
-- `intelligence-learn-from-context` — single-lesson capture; this skill's apply phase delegates to its Phase B
+- `intelligence-learn-from-context` — single-session lesson capture; this skill delegates accepted edits to its Phase B
 - `intelligence-extract-skill` — when the audit surfaces a workflow that should become a skill

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

@@ -8,7 +8,7 @@ context: fork
 # Sync intelligence
 
 1. Run `intelligence sync` (or `intelligence sync <adapter>` when one adapter
-   was requested). For v2, this command first aligns project schema/content
+   was requested). For Intelligence projects, this command first aligns project schema/content
    with the installed CLI and restores a missing package store strictly from
    `intelligence.lock`.
 2. Require final `IS_STATUS=ok`; relay per-adapter counts and any model-drift