feat: Add user-scope support via --user flag

[gricha]

Add a --user flag to all CLI commands (init, install, add, remove, update, sync, list) enabling personal skills and MCP servers managed at ~/.agents/ that follow users across projects.

The core change introduces a ScopeRoot abstraction (src/scope.ts) that encapsulates resolved paths for either project or user scope. MCP and hook writers are refactored from hardcoded project-relative paths to accept resolver callbacks, enabling user-scope MCP configs written to agent-specific absolute paths (~/.claude.json, ~/.cursor/mcp.json, etc.).

Key differences in user scope:

• Skills live at ~/.agents/skills/ with a single ~/.claude/skills/ symlink
• MCP configs written to absolute user-level paths per agent
• Gitignore management skipped (~/.agents/ is not a git repo)
• Hook management skipped (no user-scope hook paths defined)
• Adopted orphans use path:skills/ prefix instead of path:.agents/skills/

New files:

• src/scope.ts — ScopeRoot interface and resolveScope()
• src/agents/paths.ts — user-scope MCP target paths, userMcpResolver(), USER_SKILLS_PARENT

Refactored:

• src/agents/mcp-writer.ts — accepts McpTargetResolver callback
• src/agents/hook-writer.ts — accepts HookTargetResolver callback
• All 7 CLI commands — projectRoot: string → scope: ScopeRoot
• src/cli/index.ts — extracts --user flag before command dispatch

[sentry-warden]

🟠 [5BT-PRY] TOCTOU race condition in symlink migration (src/cli/commands/init.ts:72) (medium confidence)

The migrateDirectory function in symlinks/manager.ts checks if a destination exists with lstat, then renames files. An attacker could exploit the gap between the check and rename to create a symlink at the destination, causing files to be written to an attacker-controlled location.

_{Identified by Warden via find-bugs}

[sentry-warden]

🟠 [YTL-4BZ] Potential path traversal via DOTAGENTS_HOME environment variable (src/agents/types.ts:28) (medium confidence)

The DOTAGENTS_HOME environment variable is used directly without validation in resolveScope(). A malicious environment value could cause the tool to write configs to arbitrary locations. While intended for testing, if exposed in production contexts, this could be exploited.

🟠 [Q9Q-AKF] TOCTOU race condition in symlink handling (src/agents/types.ts:28) (medium confidence)

The ensureSkillsSymlink function has a time-of-check-to-time-of-use (TOCTOU) race condition. Between lstat() checking the path type and the subsequent unlink()/symlink() operations, an attacker with local access could swap the target, potentially causing symlinks to be created pointing to unintended locations.

_{Identified by Warden via find-bugs}

[cursor]

Cursor Bugbot has reviewed your changes and found 2 potential issues.

^{Bugbot Autofix is OFF. To automatically fix reported issues with Cloud Agents, enable Autofix in the Cursor dashboard.}

[cursor]

isInPlaceSkill overly broad match breaks project-scope gitignore

Low Severity

The isInPlaceSkill function now matches path:skills/ sources regardless of scope, but that prefix is only valid for user scope. In project scope, a path:skills/foo source resolves to <project>/skills/foo (copied into .agents/skills/foo), yet isInPlaceSkill returns true, causing the skill to be excluded from the managed gitignore list. The skill ends up tracked by git when it shouldn't be.

Additional Locations (2)

• src/cli/commands/sync.ts#L19-L22
• src/cli/commands/update.ts#L17-L20

 

[cursor]

Identical isInPlaceSkill function duplicated across three files

Low Severity

isInPlaceSkill is defined identically in install.ts, sync.ts, and update.ts. This PR extended the condition in all three copies to add the path:skills/ prefix. Having the same logic replicated increases the risk of inconsistent future updates — if the detection heuristic changes, all three sites must be updated in lockstep.

Additional Locations (2)

• src/cli/commands/sync.ts#L18-L22
• src/cli/commands/update.ts#L16-L20