devflow-kit 0.3.3 → 0.5.0

package/CHANGELOG.md

@@ -5,6 +5,135 @@ 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
+
+#### Skills Infrastructure
+- **Auto-activating skills system** - Intelligent context-aware capabilities that activate when relevant
+  - Skills replace standalone commands with intelligent activation patterns
+  - 7 new skills: research, debug, devlog, test-generation, api-integration, data-migration, refactoring-assistant
+  - Skills displayed on devflow init with clear descriptions
+  - Installed to `~/.claude/skills/devflow/` directory
+  - Automatic activation based on conversation context
+
+#### Smart Interactive Commands
+- **/implement command** - Orchestrator for guided feature implementation
+  - Interactive workflow for planning, research, and execution
+  - Integrates with project-state agent for context gathering
+  - Guides through research, design, implementation, and testing phases
+  - Prevents blind coding by requiring user approval at each stage
+
+#### Command→Agent→Skill Architecture
+- **Dual-mode pattern** - Commands for explicit invocation, skills for auto-activation
+  - Commands: `/research`, `/debug` for explicit user requests
+  - Skills: Auto-activated versions when conversation context matches
+  - Clear separation of concerns and activation modes
+  - Documented pattern for extending DevFlow functionality
+
+#### Enhanced /devlog Command
+- **Orchestrator pattern** - Refactored to use project-state agent
+  - Delegates project analysis to specialized agent
+  - Cleaner separation of orchestration vs analysis logic
+  - More maintainable and extensible architecture
+  - Comprehensive session documentation with context gathering
+
+### Changed
+- **Skills-first approach** - research and debug migrated to dual-mode (command + skill)
+  - Commands remain for explicit invocation
+  - Skills provide automatic activation based on context
+  - No loss of functionality, enhanced discoverability
+
+### Fixed
+- **Security vulnerability** - Added input validation for execSync to prevent command injection
+  - Validates all user input before shell execution
+  - Proper escaping and sanitization
+  - Security hardening in CLI commands
+
+- **Uninstall bug** - Fixed cleanup issue and refactored CLI to namespace pattern
+  - Proper cleanup of all installed assets
+  - Consistent namespace pattern across CLI
+  - Improved error handling and user feedback
+
+### Documentation
+- **Comprehensive skills guide** - Added to README and CLAUDE.md
+  - Detailed explanation of skills infrastructure
+  - How to create new skills
+  - When to use skills vs commands
+  - Auto-activation patterns and best practices
+
+- **Development guide updates** - Enhanced CLAUDE.md for contributors
+  - Skills development patterns
+  - Command→Agent→Skill architecture explanation
+  - Testing guidelines for dual-mode functionality
+
+- **Documentation gap fixes** - Addressed critical gaps from code review
+  - Improved clarity and completeness
+  - Fixed missing examples and use cases
+  - Better organization and navigation
+
+---
+
 ## [0.3.3] - 2025-10-19
 
 ### Fixed
@@ -288,6 +417,8 @@ 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
 [0.3.1]: https://github.com/dean0x/devflow/releases/tag/v0.3.1

package/README.md

@@ -9,19 +9,71 @@ 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
 
-### 📊 Slash Commands
+### 🎯 Skills (Auto-Activate)
+
+**Skills are model-invoked** - Claude automatically activates them based on context, enforcing quality without manual invocation.
+
+| Skill | Purpose | Auto-Triggers When |
+|-------|---------|---------------------|
+| `pattern-check` | Architectural pattern validation (Result types, DI, immutability) | Code changes are made, new functions added |
+| `test-design` | Test quality enforcement (setup complexity, mocking, behavior vs implementation) | Tests are written or modified |
+| `code-smell` | Anti-pattern detection (fake solutions, unlabeled workarounds, magic values) | Features are implemented, code is reviewed |
+| `research` | Pre-implementation planning, documentation study, integration strategy | Unfamiliar features requested, architectural decisions needed |
+| `debug` | Systematic debugging with hypothesis testing and root cause analysis | Errors occur, tests fail, performance issues detected |
+| `input-validation` | Boundary validation enforcement (parse-don't-validate, SQL injection prevention) | API endpoints created, external data handled |
+| `error-handling` | Result type consistency and exception boundary enforcement | Error handling code written, functions that can fail |
+
+**How Skills Work:**
+- **Proactive enforcement** - Catch issues during implementation, not after
+- **No manual invocation** - Model decides when skills are relevant
+- **Quality gates** - Block anti-patterns automatically
+- **Context-aware** - Activate based on what you're doing
+
+**IMPORTANT**: Skills are **automatically activated** by Claude based on context. They cannot be manually invoked like slash commands.
+
+**Dual-Mode Pattern**: The `research` and `debug` skills also exist as slash commands (`/research`, `/debug`) for manual control:
+- **Skill mode** (auto): Activates when Claude detects unfamiliar features or errors
+- **Command mode** (manual): Use `/research` or `/debug` when you want explicit control over the workflow
+
+This gives you the best of both worlds: automatic assistance when needed, manual control when preferred.
+
+### 📊 Slash Commands (User-Invoked)
 
 | Command | Purpose | When to Use |
 |---------|---------|-------------|
 | `/catch-up` | Smart summaries for starting new sessions with status validation | Starting a session |
-| `/research [topic]` | Comprehensive pre-implementation research and planning | Before implementing features |
 | `/devlog` | Development log for comprehensive session documentation | Ending a session |
 | `/plan-next-steps` | Extract actionable next steps from current discussion | After planning discussion |
-| `/debug [issue]` | Systematic debugging with issue-specific investigation | When troubleshooting |
+| `/implement` | Smart interactive implementation orchestrator with todo triage | After planning, ready to implement todos |
+| `/debug` | Systematic debugging workflow with hypothesis testing | When errors occur, tests fail, or investigating issues |
+| `/research` | Pre-implementation research and approach analysis | Before implementing unfamiliar features or integrations |
 | `/code-review` | Comprehensive code review using specialized sub-agents | Before committing or creating PR |
 | `/commit` | Intelligent atomic commit creation with safety checks | When ready to commit |
 | `/release` | Automated release workflow with version management and publishing | Creating a new release |
@@ -95,10 +147,10 @@ Covers patterns for all major languages and operating systems.
 3. Review recommended next actions
 
 ### During Development
-1. `/research [topic]` - Research implementation approaches before coding
-2. `/code-review` - Review changes before committing
-3. `/commit` - Create intelligent atomic commits
-4. Invoke audit sub-agents as needed
+1. **Skills auto-activate** - `research` skill triggers for unfamiliar features, `pattern-check` validates architecture
+2. **Code with confidence** - Skills catch anti-patterns and violations during implementation
+3. `/code-review` - Review changes before committing
+4. `/commit` - Create intelligent atomic commits
 
 ### Ending a Session
 1. `/devlog` - Document decisions and state
@@ -116,26 +168,39 @@ Covers patterns for all major languages and operating systems.
 3. Verify package in registry
 
 ### When Things Go Wrong
-1. Check git log and recent commits
-2. `/debug [issue description]` - Structured debugging
+1. **Skills auto-activate** - `debug` skill triggers on errors/failures with systematic approach
+2. Check git log and recent commits
 3. Revert changes using git
-4. Document lessons learned
+4. Document lessons learned in `.docs/debug/`
 
 ## CLI Commands
 
 | 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/`
 - Installs scripts to `~/.devflow/scripts/`
 - Updates `~/.claude/settings.json` (statusline and model)
 - 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
@@ -161,11 +226,14 @@ git commit -m "Session status: completed user auth feature"
 
 ### Integration Examples
 ```bash
-/research "add JWT authentication"  # Research before implementing
+# Skills auto-activate during development
+"Add JWT authentication"  # research skill triggers automatically
+"Fix this error"          # debug skill activates and guides systematic approach
+
+# Manual command invocation
 /code-review   # Review changes (uncommitted or full branch)
 /commit        # Create atomic commits
 /release       # Automated release workflow
-/debug "TypeError in auth module"  # Debug specific issue
 ```
 
 ## Philosophy
@@ -202,6 +270,7 @@ src/
 └── claude/                # Claude Code configuration
     ├── agents/devflow/     # Sub-agent definitions (.md)
     ├── commands/devflow/   # Slash command definitions (.md)
+    ├── skills/devflow/     # Auto-activate skill definitions (.md)
     ├── scripts/            # statusline.sh
     └── settings.json       # Claude Code settings
 ```
@@ -210,7 +279,7 @@ src/
 
 - Check installed command documentation
 - Review `.docs/status/` for recent sessions
-- Use `/debug [issue]` for systematic troubleshooting
+- Skills auto-activate for systematic troubleshooting
 - Report issues at https://github.com/dean0x/devflow/issues
 
 ## License

package/dist/commands/init.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"init.d.ts","sourceRoot":"","sources":["../../src/cli/commands/init.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AA+DpC,eAAO,MAAM,WAAW,SAidpB,CAAC"}
+{"version":3,"file":"init.d.ts","sourceRoot":"","sources":["../../src/cli/commands/init.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AA6BpC,eAAO,MAAM,WAAW,SA+fpB,CAAC"}