Add Skills Support and Command→Agent→Skill Architecture (#15)

* feat: add skills infrastructure and 7 new auto-activate skills

Introduce model-invoked skills that automatically enforce quality
patterns without manual invocation. Skills activate based on context
and provide proactive quality gates during implementation.

Skills added:
- pattern-check: Enforce Result types, DI, immutability, pure functions
- test-design: Detect test quality issues (complex setup, difficult mocking)
- code-smell: Catch fake solutions, unlabeled workarounds, magic values
- research: Auto-trigger pre-implementation planning for unfamiliar features
- debug: Systematic debugging with hypothesis testing and root cause analysis
- input-validation: Enforce boundary validation (parse-don't-validate, SQL injection)
- error-handling: Ensure Result type consistency and exception boundaries

This shifts quality enforcement from reactive (code review) to proactive
(during implementation), catching violations before they're committed.

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude <noreply@anthropic.com>

* refactor: migrate research and debug to skills-only

Remove /research and /debug commands in favor of skills-based approach.
These workflows work better as auto-activating skills rather than
manual commands:

- research skill auto-triggers when unfamiliar features are requested
- debug skill activates when errors occur or tests fail

This reduces friction (no need to remember to invoke commands) and
ensures best practices are always applied.

Breaking change: /research and /debug commands removed. Users should
rely on automatic skill activation instead.

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude <noreply@anthropic.com>

* feat: add skills installation and display to CLI

Update init command to:
- Install skills to ~/.claude/skills/devflow/
- Clean old skills directory on reinstall
- Display installed skills in output with auto-activate annotation
- Update component list to include skills

Installation now shows both commands (user-invoked) and skills
(model-invoked) to clarify the distinction.

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude <noreply@anthropic.com>

* docs: add comprehensive skills documentation to README

Add skills section explaining:
- What skills are and how they differ from commands
- Auto-activation triggers for each skill
- How skills enforce quality proactively
- Updated workflows showing skill integration
- Skills installation path

Reorganize command list to clarify user-invoked vs model-invoked
capabilities. Update examples to show skills auto-activating during
development.

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude <noreply@anthropic.com>

* docs: add skills development guide to CLAUDE.md

Add comprehensive guide for developing skills:
- Skill structure and YAML frontmatter requirements
- When to use skills vs commands
- Skill activation testing procedures
- Integration with project philosophy
- Examples of current skills

Update architecture overview to include skills as fourth main
component alongside CLI, commands, and sub-agents.

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude <noreply@anthropic.com>

* fix: fix uninstall bug and refactor CLI to namespace pattern

BREAKING FIX: uninstall command now properly removes skills directory

Previously, 'devflow uninstall' was NOT removing the skills directory,
leaving orphaned files in ~/.claude/skills/devflow/. This occurred because
we were manually managing each directory separately, making it easy to
forget new additions.

Refactored both init.ts and uninstall.ts to use a namespace pattern with
a single source of truth for all DevFlow directories:

- commands/devflow
- agents/devflow
- skills/devflow
- scripts

This ensures:
- Uninstall properly removes ALL DevFlow namespaces
- Adding new directories in the future requires only one line change
- Impossible to forget a directory (DRY principle)
- Consistent behavior between init and uninstall

Updated CLI output to clearly distinguish between commands (manual) and
skills (auto-activate) for better user understanding.

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude <noreply@anthropic.com>

* feat: restore research and debug commands for dual-mode pattern

Restored /research and /debug as explicit commands in addition to skills.

This implements a "dual-mode" pattern where research and debug exist as:
1. Commands (manual, user-invoked): /research, /debug
   - Explicit control when user wants deep analysis
   - Launches sub-agent with separate context
   - Full workflow with documentation tracking

2. Skills (auto, model-invoked): research skill, debug skill
   - Proactive assistance during implementation
   - Inline guidance and enforcement
   - Context-aware activation

This gives users maximum flexibility:
- Explicit control when they want it
- Automatic assistance when they need it

Updated init.ts to clearly show both modes in installation output
with "(manual)" and "(auto)" labels for clarity.

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude <noreply@anthropic.com>

* fix: add input validation for execSync to prevent command injection

- Isolate stderr with stdio configuration
- Validate git root path for injection patterns (newlines, semicolons, &&)
- Ensure returned path is absolute
- Prevent command injection vulnerability (HIGH-1 from code review)

Addresses security concern in init.ts where execSync was called without
proper input validation on the returned git root path.

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude <noreply@anthropic.com>

* feat: implement command→agent→skill architecture pattern

Implement clean separation following DevFlow philosophy:
- Commands: Orchestrate workflows (launch agents)
- Agents: Execute intensive analysis (separate context)
- Skills: Guide decisions (lightweight dispatchers)

Changes:
- Created debug agent (12k lines) for systematic debugging
- Simplified /debug command: 228 → 56 lines (launches agent)
- Simplified debug skill: 484 → 119 lines (auto-dispatcher)
- Simplified research skill: 381 → 135 lines (auto-dispatcher)
- Total skill reduction: 3026 → 2415 lines (611 lines saved)

Architecture Benefits:
- Main session stays clean (skills are lightweight)
- Heavy analysis offloaded to agents (separate context)
- Auto-activation preserves autonomy (skills dispatch agents)
- Context-efficient while maximizing AI quality

Skills now:
1. Detect when heavy work needed
2. Auto-launch appropriate agent
3. Summarize agent results
4. Keep main session focused

This ensures comprehensive research/debugging happens in isolated
context while main session remains clean and focused on implementation.

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude <noreply@anthropic.com>

* feat: refactor /devlog to orchestrator pattern with project-state agent

Complete separation of session context from codebase analysis:

**Command Changes (devlog.md):**
- Before: 369 lines with Bash, Read, Grep, Glob, Write, TodoWrite, Task
- After: 409 lines with Task, Write, TodoWrite only
- Removed: All inline git/find/grep operations
- Architecture: Session context (inline) + Project state (agent)

**New Agent (project-state.md):**
- 465 lines of comprehensive codebase analysis
- Handles: Git history, file changes, TODO scanning, docs structure
- Returns: Structured data for status documentation
- Tools: Bash, Read, Grep, Glob

**Workflow:**
1. Command captures session-local context (conversation, todos)
2. Command launches project-state agent (separate context)
3. Agent analyzes codebase (git, files, TODOs, docs, tech stack)
4. Command synthesizes agent data + session context
5. Command writes comprehensive status documents

**Benefits:**
- Main session: Zero heavy bash/grep work
- Agent context: All codebase analysis isolated
- Clean separation: Session vs project state
- Follows orchestrator pattern: Commands launch agents

**Philosophy Applied:**
- Commands → Orchestrate workflows
- Agents → Execute intensive analysis
- Main session stays clean and focused

This completes the orchestrator pattern refactoring for all major
commands that were doing heavy codebase analysis inline.

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude <noreply@anthropic.com>

* feat: add /implement command for smart interactive implementation

Create intelligent implementation orchestrator that guides users through
todo implementation with continuous interaction and quality enforcement.

**Command**: /implement (507 lines)
**Type**: Smart Interactive Orchestrator
**Tools**: TodoWrite, Read, Write, Edit, AskUserQuestion, Bash, Grep, Glob

**Workflow**:
1. Load current todos from TodoWrite
2. Interactive triage (remove, defer, prioritize)
3. For each todo in priority:
   - Analyze complexity (Simple/Medium/Complex)
   - Seek clarification only when needed (AskUserQuestion)
   - Share implementation plan
   - Implement following existing patterns
   - Skills auto-validate (pattern-check, test-design, etc.)
   - Mark complete, move to next
4. Comprehensive session summary

**Key Features**:
- **Smart Triage**: User controls what to implement vs defer
- **One Question at a Time**: Only asks when genuinely unclear
- **Pattern-Driven**: Finds and follows existing code patterns
- **Quality by Default**: Existing skills enforce patterns automatically
- **Transparent Progress**: Shows plan before implementing
- **Continuous Interaction**: Can pause for decisions/clarification

**Philosophy**: Pair programming with AI
- User decides priorities and provides clarification
- AI implements with user guidance
- Quality enforced through existing skills
- No need for separate implementation agent

**Usage**:
User: /implement
→ Triage todos
→ Implement iteratively with guidance
→ Summary and recommendations

This completes the implementation workflow:
/plan-next-steps → /implement → /code-review → /commit

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude <noreply@anthropic.com>

* docs: fix critical documentation gaps from code review

Addresses all 4 critical documentation issues identified in comprehensive
code review (.docs/audits/feat-add-skills-support/comprehensive-review.md):

1. Add missing commands to table:
   - /implement - Smart interactive implementation orchestrator
   - /debug - Systematic debugging workflow
   - /research - Pre-implementation research and approach analysis

2. Add auto-activation warning:
   - Clear statement that skills cannot be manually invoked
   - Prevents user confusion about skill invocation

3. Document dual-mode pattern:
   - Explains research/debug exist as both skill (auto) and command (manual)
   - Clarifies when to use each mode
   - Provides best of both worlds: automatic assistance + manual control

4. Skills path verification:
   - Confirmed already documented in CLAUDE.md:425
   - No changes needed

Impact: Resolves all blocking documentation issues from code review.
Estimated time saved in user confusion: significant.

Related: PR #15, comprehensive review 2025-10-21_2111

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude <noreply@anthropic.com>

* chore: bump version to 0.4.0

Release 0.4.0 with 12 commits since v0.3.3
- Skills infrastructure with 7 auto-activating skills
- /implement command for guided implementation
- Command→Agent→Skill dual-mode architecture
- Security and bug fixes

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude <noreply@anthropic.com>

---------

Co-authored-by: Dean Sharon <deanshrn@gmain.com>
Co-authored-by: Claude <noreply@anthropic.com>

Author: 3 people

CHANGELOG.md

@@ -5,6 +5,75 @@ 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.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 +357,7 @@ devflow init
 
 ---
 
+[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

CLAUDE.md

@@ -13,11 +13,12 @@ When working on DevFlow code, understand that this toolkit is designed to enhanc
 
 ## Architecture Overview
 
-DevFlow consists of three main components:
+DevFlow consists of four main components:
 
 1. **CLI Tool** (`src/cli/`) - TypeScript-based installer and manager
-2. **Claude Code Commands** (`src/claude/commands/`) - Markdown-based slash commands
-3. **Sub-Agents** (`src/claude/agents/`) - Specialized AI assistants for focused tasks
+2. **Claude Code Commands** (`src/claude/commands/`) - Markdown-based slash commands (user-invoked)
+3. **Skills** (`src/claude/skills/`) - Auto-activate quality enforcement (model-invoked)
+4. **Sub-Agents** (`src/claude/agents/`) - Specialized AI assistants for focused tasks
 
 ## Development Environment
 
@@ -120,6 +121,88 @@ Brief description of what the command does.
 3. Test with explicit invocation
 4. Document in README.md for users
 
+## Adding New Skills
+
+### Skill Structure
+
+Skills are **model-invoked** capabilities that auto-activate based on context. They enforce quality without requiring manual invocation.
+
+1. Create skill directory in `src/claude/skills/devflow/skill-name/`
+2. Create `SKILL.md` with YAML frontmatter:
+
+```markdown
+---
+name: skill-name
+description: When and why to use this skill (critical for auto-activation)
+allowed-tools: Read, Grep, Glob, AskUserQuestion
+---
+
+# Skill Name
+
+## Purpose
+What this skill enforces and why
+
+## When This Skill Activates
+Be specific about trigger conditions
+
+## Pattern Validation Process
+Detailed checks and enforcement logic
+
+## Violation Report Format
+How to report issues found
+
+## Success Criteria
+What passes validation
+```
+
+3. Follow existing skill patterns:
+   - **Focused enforcement** - One skill, one responsibility
+   - **Clear activation triggers** - Specific context patterns
+   - **Actionable reports** - File/line references, severity, fixes
+   - **Read-only tools** - Most skills should not modify code
+   - **Philosophy alignment** - Enforce project principles
+
+4. Test skill activation:
+   - Write code that should trigger the skill
+   - Verify skill activates automatically
+   - Check violation reports are clear
+   - Ensure fixes are actionable
+
+5. Document in README.md for users
+
+### Skill vs Command Decision
+
+**Use a Skill when:**
+- Should activate automatically based on context
+- Enforces patterns/quality (proactive)
+- Detects violations during implementation
+- Read-only analysis and reporting
+
+**Use a Command when:**
+- Requires explicit user decision
+- Performs state changes (commits, releases)
+- User controls timing (devlog, catch-up)
+- Orchestrates complex workflows
+
+**Both (Skill + Command):**
+- Common workflow that benefits from both auto and manual modes
+- Example: research (auto when unfamiliar, manual when user wants deep dive)
+
+### Current Skills
+
+**Philosophy Enforcers:**
+- `pattern-check` - Result types, DI, immutability, pure functions
+- `test-design` - Test quality red flags (complex setup, difficult mocking)
+- `code-smell` - Fake solutions, unlabeled workarounds, magic values
+
+**Workflow Automation:**
+- `research` - Pre-implementation planning and integration strategy
+- `debug` - Systematic debugging with hypothesis testing
+
+**Safety Validators:**
+- `input-validation` - Boundary validation, SQL injection prevention
+- `error-handling` - Result type consistency, exception boundaries
+
 ## CLI Development
 
 ### Building and Testing
@@ -331,13 +414,15 @@ src/
 └── claude/                   # Claude Code assets
     ├── agents/devflow/         # Sub-agent definitions
     ├── commands/devflow/       # Slash command definitions
+    ├── skills/devflow/         # Auto-activate skill definitions
     ├── scripts/                # Supporting scripts
     └── settings.json           # Claude Code settings
 ```
 
 ### Installation Paths
 - Commands: `~/.claude/commands/devflow/`
 - Agents: `~/.claude/agents/devflow/`
+- Skills: `~/.claude/skills/devflow/`
 - Scripts: `~/.devflow/scripts/`
 - Settings: `~/.claude/settings.json`
 

README.md

@@ -13,15 +13,44 @@ 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 +124,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,10 +145,10 @@ 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
 
@@ -131,6 +160,7 @@ Covers patterns for all major languages and operating systems.
 **What `devflow init` does:**
 - 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
@@ -161,11 +191,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 +235,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 +244,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.json

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