@invariant.guru/cli 0.5.5 → 0.5.6

package/README.md

@@ -1,6 +1,6 @@
 # Invariant CLI
 
-A package manager for AI coding-agent context. Install, compose, and sync reusable agents, skills, commands, rules, contexts, and instructions into `.claude/`, `.cursor/`, and other CLI target folders.
+A package manager for AI coding-agent context. Install, compose, and sync reusable agents, skills, commands, rules, contexts, and instructions. Every item is stored **once** in `.agents/` — the [Agent Skills](https://agentskills.io) standard most harnesses read natively — and each CLI target gets a view of it rather than its own copy.
 
 ## Requirements
 
@@ -42,7 +42,7 @@ invariant init claude cursor        # multiple targets
 invariant init --name my-project
 ```
 
-Supported targets: `claude`, `codex`, `cursor`, `windsurf`, `aider`, `copilot`.
+Supported targets: `claude`, `codex`, `cursor`, `aider`, `copilot`.
 
 ### 2. `invariant install` — pull a package
 
@@ -119,13 +119,20 @@ invariant add skill:nest-clean-architecture/implement-command \
 
 Check what landed with `invariant inspect nest-clean-architecture`, or use `invariant add-interactive` for a checkbox tree of every installed item.
 
-### 4. `invariant sync` — write the files
+### 4. `invariant sync` — reconcile and write the files
 
-`sync` renders the active set into each configured target: `CLAUDE.md`, `.claude/agents/`, `.claude/skills/<name>/SKILL.md`, `.claude/commands/`, `.claude/rules/`, and the equivalents for other targets.
+`sync` brings the whole tree back in line with `invariant.json`: it rebuilds
+canonical items that went missing, materializes every active item for every
+configured target, prunes what is no longer active, and regenerates the context
+files (`CLAUDE.md`, `AGENTS.md`, …).
+
+Add a target to `invariant.json`, run `sync`, and that target is set up — no need
+to re-run `add`.
 
 ```bash
 invariant sync
 invariant sync --target claude
+invariant sync --check          # CI gate: exits 1 when the tree is stale
 ```
 
 `add`, `install`, and `add-interactive` all accept `-s, --sync` to do this in one shot:
@@ -179,6 +186,8 @@ invariant init --hybrid
 |--------|-------------|
 | `-n, --name <name>` | Project name (defaults to directory name) |
 | `--hybrid` | Initialize as hybrid mode — project *and* package in one directory |
+| `--copy` | Copy items into each target folder instead of linking them to `.agents/` |
+| `--canonical-dir <dir>` | Canonical store location (default `.agents`) |
 
 ### `invariant install [packages...]`
 
@@ -306,7 +315,9 @@ invariant sync --target cursor
 
 | Option | Description |
 |--------|-------------|
-| `-t, --target <target>` | Sync only to a specific target (`claude`, `codex`, `cursor`, `windsurf`, `aider`, `copilot`) |
+| `-t, --target <target>` | Sync only to a specific target (`claude`, `codex`, `cursor`, `aider`, `copilot`). Skips pruning — the other targets are out of scope |
+| `--check` | Report drift without writing anything; exits `1` when out of sync |
+| `--force` | Replace target files that were hand-edited away from the canonical item |
 
 ### `invariant inspect [package]`
 
@@ -523,10 +534,62 @@ After `init` + `install` + `sync`:
 │   ├── instructions/        # rendered instructions
 │   ├── sessions/            # `invariant plan` output
 │   └── codegraph/           # `invariant scan` output
+├── .agents/                 # canonical store — the only physical copy
+│   ├── skills/<name>/SKILL.md
+│   ├── agents/<name>.md
+│   ├── commands/<name>.md
+│   └── rules/<name>.md
 ├── CLAUDE.md                # generated by `invariant sync`
-└── .claude/
-    ├── agents/<name>.md
-    ├── skills/<name>/SKILL.md
+└── .claude/                 # symlinks into .agents/
+    ├── agents/<name>.md  ->  ../../.agents/agents/<name>.md
+    ├── skills/<name>     ->  ../../.agents/skills/<name>
     ├── commands/<name>.md
     └── rules/<name>.md
 ```
+
+### One copy, many views
+
+`.agents/` holds the single physical copy of every activated item. What each
+target gets depends on how it reads skills:
+
+| Target | Skills | Agents / commands / rules |
+|---|---|---|
+| `claude` | symlink into `.agents/` | symlink into `.agents/` |
+| `codex` | reads `.agents/skills/` — nothing written | embedded in `AGENTS.md` |
+| `cursor` | reads `.agents/skills/` — nothing written | `.cursor/rules/<name>.mdc` |
+| `copilot` | reads `.agents/skills/` — nothing written | `.github/instructions/<name>.instructions.md` |
+| `aider` | embedded in `CONVENTIONS.md` | embedded in `CONVENTIONS.md` |
+
+Two consequences worth knowing:
+
+- Targets that speak the standard get **no invariant-written skill files**, so
+  they never read the same skill twice.
+- Hand-written items you put in `.claude/skills/` yourself are never touched —
+  invariant only manages what is listed in `invariant.json → active`, plus links
+  that resolve into `.agents/`. A target file you edit by hand is kept, with a
+  warning, until you pass `--force`.
+
+On hosts without symlink support the CLI falls back to a Windows junction, then
+to a physical copy, and says which one it used. `invariant init --copy` (or
+`"materialization": { "mode": "copy" }`) opts out of linking entirely.
+
+### Version control
+
+`.agents/` and the target folders are **generated** — they are rebuilt by
+`invariant add` and `invariant sync`, the way `node_modules` is rebuilt by a
+package manager. `init` and `sync` keep them out of git via a delimited block:
+
+```gitignore
+# --- invariant (generated, do not edit) ---
+.agents/
+.claude/agents/
+.claude/skills/
+.claude/commands/
+.claude/rules/
+CLAUDE.md
+# --- end invariant ---
+```
+
+Only paths invariant owns outright are listed, so a folder you share with it
+(`.cursor/rules/`, which also holds your own rules) is left alone. Commit
+`invariant.json`, run `invariant sync` after a clone.