feat: Installation scope support (user/local) with code quality improvements

.gitignore

@@ -36,4 +36,7 @@ config/local-*
 commands/local-*
 
 # Installation logs
-install.log
+install.log
+# DevFlow local scope installation (use --scope local)
+.claude/
+.devflow/

CHANGELOG.md

@@ -5,6 +5,66 @@ All notable changes to DevFlow will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [0.5.0] - 2025-10-24
+
+### Added
+
+#### Installation Scope Support
+- **Two-tier installation strategy** - Choose between user-wide and project-specific installation
+  - **User scope** (default): Install to `~/.claude/` for all projects
+  - **Local scope**: Install to `<git-root>/.claude/` for current project only
+  - Interactive prompt with clear descriptions when `--scope` flag not provided
+  - CLI flag: `devflow init --scope <user|local>`
+  - Automatic .gitignore updates for local scope (excludes `.claude/` and `.devflow/`)
+  - Perfect for team projects where DevFlow should be project-specific
+
+#### Smart Uninstall with Scope Detection
+- **Auto-detection of installed scopes** - Intelligently finds and removes DevFlow installations
+  - Automatically detects which scopes have DevFlow installed (user and/or local)
+  - Default behavior: Remove from all detected scopes
+  - Manual override: `--scope <user|local>` to target specific scope
+  - Clear feedback showing which scopes are being uninstalled
+  - Graceful handling when no installation found
+
+### Changed
+
+#### Code Quality Improvements
+- **Extracted shared utilities** - Eliminated code duplication between init and uninstall commands
+  - Created `src/cli/utils/paths.ts` for path resolution functions
+  - Created `src/cli/utils/git.ts` for git repository operations
+  - Reduced duplication by ~65 lines
+  - Single source of truth for path and git logic
+
+#### Performance Optimizations
+- **Eliminated redundant git detection** - Cache git root result for reuse
+  - Previously called `git rev-parse` twice during installation
+  - Now cached once and reused throughout installation process
+  - Faster installation, especially in large repositories
+
+### Fixed
+
+#### CI/CD Compatibility
+- **TTY detection for interactive prompts** - Prevents hanging in non-interactive environments
+  - Detects when running in CI/CD pipelines, Docker containers, or automated scripts
+  - Falls back to default scope (user) when no TTY available
+  - Clear messaging when non-interactive environment detected
+  - Explicit instructions for CI/CD usage: `devflow init --scope <user|local>`
+
+#### Security Hardening
+- **Environment variable path validation** - Prevents malicious path overrides
+  - Validates `CLAUDE_CODE_DIR` and `DEVFLOW_DIR` are absolute paths
+  - Warns when paths point outside user's home directory
+  - Prevents path traversal attacks via environment variables
+  - Security-first approach to custom path configuration
+
+### Documentation
+- **Installation Scopes section** in README with clear use cases
+- **Updated CLI commands table** with scope options for init and uninstall
+- **Migration guide** for existing users (scope defaults to user for compatibility)
+- **.gitignore patterns** documented for local scope installations
+
+---
+
 ## [0.4.0] - 2025-10-21
 
 ### Added
@@ -357,6 +417,7 @@ devflow init
 
 ---
 
+[0.5.0]: https://github.com/dean0x/devflow/releases/tag/v0.5.0
 [0.4.0]: https://github.com/dean0x/devflow/releases/tag/v0.4.0
 [0.3.3]: https://github.com/dean0x/devflow/releases/tag/v0.3.3
 [0.3.2]: https://github.com/dean0x/devflow/releases/tag/v0.3.2

README.md

@@ -9,6 +9,29 @@ A comprehensive collection of Claude Code commands and configurations designed t
 npx devflow-kit init
 ```
 
+### Installation Scopes
+
+DevFlow supports two installation scopes:
+
+**User Scope (Default)** - Install for all projects
+```bash
+npx devflow-kit init --scope user
+# Or interactively: npx devflow-kit init (prompts for scope)
+```
+- Installs to `~/.claude/` and `~/.devflow/`
+- Available across all projects
+- Recommended for personal use
+
+**Local Scope** - Install for current project only
+```bash
+npx devflow-kit init --scope local
+```
+- Installs to `<git-root>/.claude/` and `<git-root>/.devflow/`
+- Only available in the current project
+- Recommended for team projects where DevFlow should be project-specific
+- Requires a git repository (run `git init` first)
+- Add `.claude/` and `.devflow/` to `.gitignore` (done automatically)
+
 That's it! DevFlow is now installed and ready to use in Claude Code.
 
 ## What's Included
@@ -154,10 +177,12 @@ Covers patterns for all major languages and operating systems.
 
 | Command | Purpose | Options |
 |---------|---------|---------|
-| `devflow init` | Initialize DevFlow for Claude Code | `--skip-docs` - Skip creating `.docs/` structure |
-| `devflow uninstall` | Remove DevFlow from Claude Code | `--keep-docs` - Keep `.docs/` directory |
+| `devflow init` | Initialize DevFlow for Claude Code | `--scope <user\|local>` - Installation scope (user: user-wide, local: project-only)<br>`--skip-docs` - Skip creating `.docs/` structure |
+| `devflow uninstall` | Remove DevFlow from Claude Code | `--scope <user\|local>` - Uninstall from specific scope only (default: auto-detect all)<br>`--keep-docs` - Keep `.docs/` directory |
 
 **What `devflow init` does:**
+
+**User Scope** (default):
 - Installs commands to `~/.claude/commands/devflow/`
 - Installs sub-agents to `~/.claude/agents/devflow/`
 - Installs skills to `~/.claude/skills/devflow/`
@@ -166,6 +191,16 @@ Covers patterns for all major languages and operating systems.
 - Creates `.claudeignore` at git repository root
 - Creates `.docs/` structure for project documentation
 
+**Local Scope** (`--scope local`):
+- Installs commands to `<git-root>/.claude/commands/devflow/`
+- Installs sub-agents to `<git-root>/.claude/agents/devflow/`
+- Installs skills to `<git-root>/.claude/skills/devflow/`
+- Installs scripts to `<git-root>/.devflow/scripts/`
+- Creates `<git-root>/.claude/settings.json` (statusline and model)
+- Creates `.claudeignore` at git repository root
+- Creates `.docs/` structure for project documentation
+- Adds `.claude/` and `.devflow/` to `.gitignore`
+
 **First Run:**
 ```bash
 devflow init

package.json

@@ -1,6 +1,6 @@
 {
   "name": "devflow-kit",
-  "version": "0.4.0",
+  "version": "0.5.0",
   "description": "Agentic Development Toolkit for Claude Code - Enhance AI-assisted development with intelligent commands and workflows",
   "main": "dist/index.js",
   "type": "module",