Refactor installer scope and destination handling

Author: DevaanshPathak

.npmignore

@@ -0,0 +1,5 @@
+**/__pycache__/
+**/*.pyc
+.cursor/
+.github/
+tests/

CHANGELOG.md

@@ -4,6 +4,17 @@ All notable changes to this project are documented here.
 
 ## Unreleased
 
+### Changed
+
+- Refactored installation around explicit project/user scope, destination,
+  target, and item selection so `add <name>` installs only the requested
+  artifact and project installs never leak into user-level agent directories.
+- Made npm installs durable copies by default, aligned project-context files
+  with the selected agent architecture, and made target auto-detection fail
+  closed when no agent directory exists.
+- Consolidated validation and installer smoke tests into one cancellable CI
+  workflow; the Windows smoke job now runs only for installer-related changes.
+
 ### Added
 
 - Codex delegation guidance and a dependency-free delegation packet adapter.

CONTRIBUTING.md

@@ -34,6 +34,12 @@ python scripts/build_cursor_rules.py --skills-dir skills --out-dir .cursor/rules
 python scripts/list_content.py --format markdown
 ```
 
+Installer changes must also preserve the scope contract: project installs may
+write only below the selected project, user installs may write only below the
+selected home, and `add <name>` may install only that artifact. Add regression
+coverage in `tests/test_install.py` and `tests/test_cli.py` for changes to these
+boundaries.
+
 Commit frequent, scoped, coherent units of completed work. Use concise,
 professional imperative subjects that say what changed, such as `Add handoff
 template validation`; avoid vague or phase-based subjects. Push each completed

README.md

@@ -1,102 +1,191 @@
 # indium-agentkit
 
-`indium-agentkit` is a distribution scaffold for sharing AI coding-agent skills, subagents, and project context across Claude Code, Codex, Antigravity CLI (formerly Gemini CLI), OpenCode, and Cursor.
+`indium-agentkit` distributes portable AI coding-agent skills, subagents, and
+project context across Claude Code, Codex, Gemini CLI, Antigravity, OpenCode,
+and Cursor.
 
----
+## Quick start
 
-## ⚡ 1-Line Quick Installation (Install Whole Repo)
+Install the complete bundle into one agent inside the current project:
 
-To install **all 36 portable skills, 21 subagents, and Cursor rules** into any project repository in under 2 seconds:
+```bash
+npx @indium-ai-labs/agentkit install --target=codex
+```
+
+Install one skill instead of the complete bundle:
 
 ```bash
-# Auto-detect active IDE and install all skills & subagents
-npx @indium-ai-labs/agentkit install
+npx @indium-ai-labs/agentkit add systematic-debugging --target=codex
 ```
 
-### 🎯 Target Specific AI Editors & IDEs:
+Project scope is the default. These commands write only below the current
+project; they do not modify user-level agent directories. Choose a different
+project explicitly with `--project-dir`:
+
 ```bash
-# Antigravity IDE (.antigravity/skills & .antigravity/agents)
-npx @indium-ai-labs/agentkit install --target=antigravity
+npx @indium-ai-labs/agentkit install \
+  --project-dir=/path/to/project \
+  --target=claude
+```
+
+Use user scope only when you intentionally want content available across
+projects:
+
+```bash
+npx @indium-ai-labs/agentkit install --scope=user --target=codex
+```
+
+If `--target` is omitted, the CLI detects agent directories that already exist
+inside the chosen scope. It fails with guidance when no target is detected.
+Installing into every supported agent requires the explicit `--target=all`
+flag.
+
+## Installation model
 
-# OpenCode (.opencode/skills)
-npx @indium-ai-labs/agentkit install --target=opencode
+Four independent inputs control every installation:
 
-# Cursor IDE (.cursor/rules/*.mdc)
-npx @indium-ai-labs/agentkit install --target=cursor
+| Input | Meaning | Default |
+| --- | --- | --- |
+| Command | `install` for the bundle or `add <name>` for one artifact | required |
+| Scope | `project` or `user` | `project` |
+| Destination | Current project or `--project-dir=<path>` | current directory |
+| Target | One agent, a comma-separated list, auto-detection, or explicit `all` | `auto` |
 
-# Claude Code (.claude/skills & .claude/agents)
-npx @indium-ai-labs/agentkit install --target=claude
+The npm CLI creates durable copies by default because links into a temporary
+`npx` cache can break later. Use `--mode=link` only when you intentionally want
+the destination to follow a local agentkit checkout. Existing files that are
+not an exact copy or an agentkit link are reported and left untouched.
+
+Project-context files follow the selected architecture:
+
+| Target | Project content | Project context |
+| --- | --- | --- |
+| Claude Code | `.claude/skills`, `.claude/agents` | `CLAUDE.md` |
+| Codex | `.codex/skills` | `AGENTS.md` |
+| Gemini CLI | `.gemini/skills`, `.gemini/agents` | `AGENTS.md` |
+| Antigravity | `.antigravity/skills`, `.antigravity/agents` | `AGENTS.md` |
+| Cursor | generated `.cursor/rules/*.mdc` | `AGENTS.md` |
+| OpenCode | `.opencode/skills` | `AGENTS.md` |
+
+User-scoped installs write only to the selected tool directory beneath the
+user home and never create project-context files.
+
+### More examples
+
+```bash
+# Multiple explicit targets in one project
+npx @indium-ai-labs/agentkit install --target=codex,cursor
+
+# One Claude subagent in one project
+npx @indium-ai-labs/agentkit add reviewer --target=claude
+
+# Explicitly install everywhere in the user scope
+npx @indium-ai-labs/agentkit install --scope=user --target=all
+
+# Show every option and the active package version
+npx @indium-ai-labs/agentkit --help
 ```
 
----
+A selected subagent fails clearly when its target has no native subagent
+installation path. Portable skills remain usable without subagents.
+
+## Local checkout installers
+
+The Bash and PowerShell wrappers use links by default for repository
+development. Passing a project directory uses project scope only:
+
+```bash
+# macOS/Linux
+./scripts/install.sh /path/to/project codex
+
+# Windows PowerShell
+.\scripts\install.ps1 -ProjectDir C:\path\to\project -TargetIde codex
+```
+
+Their advanced options map to the canonical Python installer:
+
+```bash
+python scripts/install.py \
+  --scope project \
+  --project-dir /path/to/project \
+  --target cursor \
+  --item systematic-debugging \
+  --mode copy
+```
+
+Creating links on Windows requires Developer Mode or an Administrator shell.
+The installer reports a clear remediation message if link creation fails.
+
+Inspect exactly the boundary you installed:
+
+```bash
+python scripts/check_install.py \
+  --project /path/to/project \
+  --target codex \
+  --item systematic-debugging \
+  --mode copy
+```
 
 ## Architecture
 
 The repository uses two open, cross-agent formats:
 
-- `SKILL.md` is a task-triggered capability. Each skill has YAML frontmatter (`name` and `description`), a Markdown body, and optionally helper files next to it. Claude Code, Codex, OpenCode, and Gemini CLI/Antigravity discover this format natively.
-- `AGENTS.md` is always-loaded project context: architecture, conventions, commands, and working notes. Codex, Cursor, Gemini CLI/Antigravity, Copilot, Aider, Windsurf, and Zed read it natively. The root file governs this repository; `templates/AGENTS.md` is the neutral file installers link into consumer projects, along with `CLAUDE.md` for Claude Code.
+- `SKILL.md` is a task-triggered capability with `name` and `description` YAML
+  frontmatter plus a Markdown workflow. Claude Code, Codex, OpenCode, Gemini
+  CLI, and Antigravity discover it natively.
+- `AGENTS.md` is always-loaded project context. Codex, Cursor, Gemini CLI,
+  Antigravity, Copilot, Aider, Windsurf, and Zed read it natively. The root
+  file governs this repository; consumer projects receive the neutral
+  `templates/AGENTS.md`. Claude receives the same context as `CLAUDE.md`.
 
-Cursor does not natively discover `SKILL.md`. The included Python builder turns each `skills/*/SKILL.md` into `.cursor/rules/<skill-directory>.mdc`, carrying over the skill description and Markdown body and setting `alwaysApply: false`. Skills therefore have one source of truth while remaining available to Cursor.
+Cursor does not natively discover `SKILL.md`. The dependency-free builder
+converts each selected skill to `.cursor/rules/<name>.mdc`, preserving the
+description and Markdown body with `alwaysApply: false`.
 
-Subagents do not yet share a cross-tool schema. This repository uses Claude Code's format as the common denominator: YAML frontmatter containing `name`, `description`, `tools`, and `model`, followed by the subagent's Markdown prompt. Use [`templates/subagent.md`](templates/subagent.md) when authoring a new role; it is based on the repository's `agent-orchestrator` inspection structure and keeps safety, contracts, limits, and handoffs explicit.
+Subagents do not yet have a unified cross-tool schema. Agentkit uses Claude
+Code-compatible frontmatter (`name`, `description`, `tools`, and `model`) as
+the portable source shape. Use `templates/subagent.md` when authoring a role.
 
 ## Repository layout
 
 ```text
 indium-agentkit/
-├── README.md
-├── AGENTS.md
-├── templates/
-│   └── AGENTS.md
-├── skills/
-│   ├── author-agentkit-content/
-│   ├── plan-change/
-│   ├── safe-migration/
-│   ├── security-review/
-│   ├── ...
-│   └── verify-and-ship/
-├── agents/
-│   ├── explorer.md
-│   ├── migration-planner.md
-│   ├── security-reviewer.md
-│   ├── ...
-│   └── verifier.md
-├── scripts/
-│   ├── install.sh
-│   ├── install.ps1
-│   ├── build_cursor_rules.py
-│   ├── validate_content.py
-│   ├── check_install.py
-│   ├── scaffold_content.py
-│   └── list_content.py
-├── tests/
-├── .github/workflows/validate.yml
-├── docs/
-├── CATALOG.md
-├── CHANGELOG.md
-├── SECURITY.md
-├── CONTRIBUTING.md
-└── .gitignore
+|-- AGENTS.md
+|-- CATALOG.md
+|-- agents/
+|-- skills/
+|-- templates/
+|   `-- AGENTS.md
+|-- scripts/
+|   |-- cli.js
+|   |-- install.py
+|   |-- install.sh
+|   |-- install.ps1
+|   `-- build_cursor_rules.py
+|-- tests/
+`-- .github/workflows/validate.yml
 ```
 
-## Validation
+## Adding content
 
-Validate content and run the dependency-free test suite before publishing:
+Create skills at `skills/<name>/SKILL.md` and subagents at
+`agents/<name>.md`. Follow `CONTRIBUTING.md`, regenerate `CATALOG.md`, and keep
+skills executable by a single agent even when delegation can accelerate them.
+
+## Validation
 
 ```bash
+python scripts/generate_catalog.py
+python scripts/diff_catalog.py
 python scripts/validate_content.py
 python scripts/validate_handoff.py --templates-dir templates/handoffs
 python -m unittest discover -s tests -v
+python scripts/build_cursor_rules.py --skills-dir skills --out-dir .cursor/rules
 ```
 
-GitHub Actions runs the same checks on pushes and pull requests.
-
-## Tools and compatibility
-
-Use `python scripts/check_install.py --project /path/to/project` to inspect an installation, `scripts/scaffold_content.py` to create valid starter content, and `scripts/list_content.py --format json` to consume the catalog programmatically. For Codex delegation, use `scripts/codex_delegate.py` to produce a structured packet from an `agents/<name>.md` role.
-See [compatibility details](docs/compatibility.md), [security guidance](SECURITY.md), and [release guidance](docs/releasing.md).
-
-## Status
+CI uses one workflow run per event. Superseded runs are cancelled, Bash smoke
+coverage shares the Linux validation job, and the higher-cost Windows smoke job
+runs only when installer-related files change.
 
-The current bundle contains thirty-six portable skills, twenty-one read-only specialists, and two scoped implementation subagents. See `CATALOG.md` for the generated inventory.
+See `CATALOG.md` for the generated inventory, `docs/compatibility.md` for the
+support matrix, and `SECURITY.md` for distribution guidance.

docs/compatibility.md

@@ -2,14 +2,21 @@
 
 | Capability | Claude Code | Codex | Gemini CLI / Antigravity | Cursor |
 | --- | --- | --- | --- | --- |
-| `AGENTS.md` project context | Via linked `CLAUDE.md` | Native | Native | Native |
+| Project context | `CLAUDE.md` | `AGENTS.md` | `AGENTS.md` | `AGENTS.md` |
 | `SKILL.md` skills | Native | Native | Native | Generated `.mdc` rules |
-| Claude-style subagents | Native | Adapt manually | Adapt manually | Adapt manually |
-| Per-item installation | `~/.claude/` | `~/.codex/` | `~/.gemini/`, `~/.antigravity/` | Project `.cursor/rules/` |
+| Claude-style subagents | Native | Delegation adapter | Distributed role files | Adapt manually |
+| Project installation | `.claude/` | `.codex/` | `.gemini/`, `.antigravity/` | `.cursor/rules/` |
+| User installation | `~/.claude/` | `~/.codex/` | `~/.gemini/`, `~/.antigravity/` | `~/.cursor/rules/` |
 
 Skills must remain usable by one agent because only Claude Code consumes the
 subagent files directly. A skill may recommend delegation as an optional
 acceleration path, but its core workflow must not depend on it.
 
+Installation scope and target are independent. Project scope never writes to
+the user home, and user scope never creates project files. `add <name>` installs
+only that artifact; `install` installs the bundle. The npm CLI uses copies by
+default, while local checkout wrappers use links by default.
+
 Run `python scripts/build_cursor_rules.py --skills-dir skills --out-dir
-<project>/.cursor/rules` after adding or changing a skill for Cursor.
+<project>/.cursor/rules --skill <name>` to convert one skill for Cursor, or omit
+`--skill` to convert the complete skill collection.

package.json

@@ -1,6 +1,6 @@
 {
   "name": "@indium-ai-labs/agentkit",
-  "version": "1.0.2",
+  "version": "1.1.0",
   "description": "Portable AI coding-agent skills, subagents, and project-context templates.",
   "main": "scripts/cli.js",
   "bin": {
@@ -19,8 +19,8 @@
     "README.md"
   ],
   "scripts": {
-    "test": "python3 -m unittest discover -s tests -v",
-    "lint": "python3 scripts/validate_content.py"
+    "test": "python -m unittest discover -s tests -v",
+    "lint": "python scripts/validate_content.py"
   },
   "keywords": [
     "ai",

scripts/.npmignore

@@ -0,0 +1,2 @@
+__pycache__/
+*.pyc

scripts/build_cursor_rules.py

@@ -73,14 +73,18 @@ def convert_skill(skill_file: Path, out_dir: Path) -> Path:
 
 def parse_args() -> argparse.Namespace:
     parser = argparse.ArgumentParser(
-        description="Convert skills/*/SKILL.md files to Cursor .mdc rules."
+        description="Convert skills/*/SKILL.md files to Cursor .mdc rules.",
+        allow_abbrev=False,
     )
     parser.add_argument(
         "--skills-dir", type=Path, required=True, help="Directory containing skills"
     )
     parser.add_argument(
         "--out-dir", type=Path, required=True, help="Directory for generated .mdc files"
     )
+    parser.add_argument(
+        "--skill", help="Convert only the skill whose directory has this name"
+    )
     return parser.parse_args()
 
 
@@ -94,6 +98,15 @@ def main() -> int:
         return 2
 
     skill_files = sorted(skills_dir.glob("*/SKILL.md"))
+    if args.skill:
+        skill_files = [
+            skill_file
+            for skill_file in skill_files
+            if skill_file.parent.name == args.skill
+        ]
+        if not skill_files:
+            print(f"error: skill not found: {args.skill}", file=sys.stderr)
+            return 2
     if not skill_files:
         print("no skills found")
         return 0