devflow-kit 0.1.0 → 0.1.2

package/CHANGELOG.md

@@ -5,6 +5,36 @@ 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.1.2] - 2025-10-05
+
+### Added
+- `/research [topic]` - Comprehensive pre-implementation research and planning command
+- `research` sub-agent - Specialized agent for systematic implementation research with 10-step workflow
+  - Analyzes multiple implementation approaches with pros/cons/trade-offs
+  - Studies official documentation and code examples
+  - Reviews existing codebase patterns and conventions
+  - Designs integration strategy with specific file paths
+  - Identifies risks and creates actionable implementation plans
+  - Saves research reports to `.docs/research/`
+
+### Documentation
+- Updated README.md with `/research` command in workflow examples
+- Added research sub-agent to sub-agents table
+
+## [0.1.1] - 2025-10-03
+
+### Changed
+- **Simplified Installation**: Single command installation using `npx devflow-kit init` (no global install needed)
+- **Improved Documentation**: Commands and sub-agents now displayed in easy-to-scan tables
+- **Better Organization**: Separated user documentation (README.md) from developer guide (CLAUDE.md)
+- **Reduced Duplication**: Eliminated redundant information throughout README
+
+### Documentation
+- Reorganized README.md with table-based layout for commands and sub-agents
+- Moved developer/AI agent instructions to CLAUDE.md
+- Updated installation to promote npx usage over global install
+- Reduced README from 289 lines to 204 lines while preserving all information
+
 ## [0.1.0] - 2024-10-03
 
 ### 🎉 Initial Release
@@ -55,10 +85,12 @@ devflow init
 ```
 
 ### Documentation
-- Comprehensive guide in CLAUDE.md
+- Comprehensive guide in README.md
 - Quick reference in README.md
 - Self-documenting commands
 
 ---
 
+[0.1.2]: https://github.com/dean0x/devflow/releases/tag/v0.1.2
+[0.1.1]: https://github.com/dean0x/devflow/releases/tag/v0.1.1
 [0.1.0]: https://github.com/dean0x/devflow/releases/tag/v0.1.0

package/README.md

@@ -2,124 +2,158 @@
 
 A comprehensive collection of Claude Code commands and configurations designed to enhance developer workflows when working with AI coding assistants.
 
-## Quick Start
+## Installation
 
 ```bash
-# 1. Install dependencies
-npm install
-
-# 2. Build the CLI
-npm run build
-
-# 3. Install DevFlow for Claude Code
-node dist/cli.js init
-
-# Or install globally
-npm install -g .
-devflow init
+# Run with npx (recommended - no global install needed)
+npx devflow-kit init
 ```
 
+That's it! DevFlow is now installed and ready to use in Claude Code.
+
 ## What's Included
 
 ### 📊 Slash Commands
 
-**Code Review & Quality:**
-- `/pre-commit` - Review uncommitted changes before committing
-- `/pre-pr` - Comprehensive branch review for PR readiness
-- `/commit` - Intelligent atomic commits with safety checks
-
-**Session Management:**
-- `/catch-up` - Smart summaries for starting new sessions
-- `/devlog` - Development log for session documentation
-- `/plan-next-steps` - Extract actionable next steps from discussion
-
-**Development Tools:**
-- `/debug [issue]` - Systematic debugging with issue-specific investigation
+| 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 |
+| `/pre-commit` | Review uncommitted changes using specialized sub-agents | Before committing |
+| `/commit` | Intelligent atomic commit creation with safety checks | When ready to commit |
+| `/pre-pr` | Comprehensive branch review for PR readiness | Before creating PR |
 
 ### 🤖 Sub-Agents
 
-**Audit Specialists:**
-- `audit-security` - Security vulnerability detection and analysis
-- `audit-performance` - Performance optimization and bottleneck detection
-- `audit-architecture` - Software architecture and design pattern analysis
-- `audit-tests` - Test quality and coverage analysis
-- `audit-dependencies` - Dependency management and security analysis
-- `audit-complexity` - Code complexity and maintainability assessment
-- `audit-database` - Database design and optimization review
+| Sub-Agent | Specialty | Purpose |
+|-----------|-----------|---------|
+| `audit-security` | Security Analysis | Expert vulnerability detection and security code review |
+| `audit-performance` | Performance | Optimization and bottleneck detection |
+| `audit-architecture` | Architecture | Design pattern analysis and code structure review |
+| `audit-tests` | Testing | Test quality, coverage, and effectiveness analysis |
+| `audit-dependencies` | Dependencies | Dependency management and security analysis |
+| `audit-complexity` | Complexity | Code complexity and maintainability assessment |
+| `audit-database` | Database | Database design and optimization review |
+| `catch-up` | Context Restoration | Project status and context restoration with validation |
+| `commit` | Git Operations | Intelligent commit creation with safety checks |
+| `research` | Implementation Planning | Pre-implementation research, approach analysis, and planning |
+
+**How Sub-Agents Work:**
+- Specialized AI assistants with deep expertise in specific domains
+- Separate context windows for focused analysis
+- Can be invoked explicitly or automatically by orchestrator commands
+- Restricted tool access appropriate to their domain
+
+**Invoking Sub-Agents:**
+```bash
+# Explicit invocation
+"Use the audit-security sub-agent to analyze this authentication code"
 
-**Workflow Specialists:**
-- `catch-up` - Project status and context restoration with validation
-- `commit` - Intelligent commit creation with safety checks
+# Automatic delegation (Claude Code decides which sub-agent to use)
+"Review this code for security issues"
+```
 
 ### 📊 Smart Statusline
+
 Real-time project context display showing:
 - Current model and session duration
 - Git branch and uncommitted changes indicator
 - Session cost tracking
 - Project context
+- Zero configuration - works immediately after installation
 
 ### 🔒 Security & Token Optimization
-DevFlow automatically creates a comprehensive `.claudeignore` file to:
-- **Protect sensitive files** - Prevents exposure of credentials, keys, and secrets
-- **Reduce token usage** - Excludes build artifacts, dependencies, and non-essential files
-- **Support all languages** - Covers patterns for Node.js, Python, Ruby, Go, Rust, Java, and more
+
+DevFlow automatically creates a comprehensive `.claudeignore` file at your git repository root to:
+
+**Protect Sensitive Data:**
+- Environment files (`.env`, `.env.*`, `.envrc`)
+- Credentials & keys (`*.key`, `*.pem`, SSH keys)
+- Cloud configs (`.aws/`, `.gcp/`, `.azure/`)
+- Package tokens (`.npmrc`, `.pypirc`)
+- Database files (`*.sql`, `*.db`)
+
+**Optimize Token Usage:**
+- Dependencies (`node_modules/`, `vendor/`, `venv/`)
+- Build artifacts (`dist/`, `build/`, `.next/`)
+- IDE files (`.vscode/`, `.idea/`)
+- Lock files (`package-lock.json`, `yarn.lock`)
+- Media and binaries
+
+Covers patterns for all major languages and operating systems.
+
+## Development Workflow
+
+### Starting a Session
+1. `/catch-up` - Review what was done previously
+2. Check statusline for current model, git state, duration
+3. Review recommended next actions
+
+### During Development
+1. `/research [topic]` - Research implementation approaches before coding
+2. `/pre-commit` - Review changes before committing
+3. `/commit` - Create intelligent atomic commits
+4. Invoke audit sub-agents as needed
+
+### Ending a Session
+1. `/devlog` - Document decisions and state
+2. `/pre-pr` - Review branch before creating PR
+3. `/commit` - Final commits with validation
+
+### When Things Go Wrong
+1. Check git log and recent commits
+2. `/debug [issue description]` - Structured debugging
+3. Revert changes using git
+4. Document lessons learned
 
 ## CLI Commands
 
-### `devflow init`
-Initialize DevFlow for Claude Code. Installs commands, agents, scripts, and settings to your Claude Code configuration. Also creates security and optimization files.
+| 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 |
 
-**What it does:**
+**What `devflow init` does:**
 - Installs commands to `~/.claude/commands/devflow/`
 - Installs sub-agents to `~/.claude/agents/devflow/`
 - Installs scripts to `~/.devflow/scripts/`
-- Installs settings to `~/.claude/settings.json`
-- Creates `.claudeignore` at git repository root (if in git repo)
+- Updates `~/.claude/settings.json` (statusline and model)
+- Creates `.claudeignore` at git repository root
 - Creates `.docs/` structure for project documentation
 
-**Options:**
-- `--skip-docs` - Skip creating `.docs/` structure
-
-**Example:**
+**First Run:**
 ```bash
-# Standard installation
 devflow init
-
-# Skip project documentation setup
-devflow init --skip-docs
+/devlog      # Document your current project state
+/catch-up    # Get oriented with the project
 ```
 
-## Project Structure
+## Advanced Usage
 
+### Custom Audit Rules
+```bash
+# Extend sub-agents for project-specific patterns
+echo "Check for exposed API keys in config files" >> ~/.claude/agents/devflow/audit-security.md
 ```
-devflow/
-├── src/                     # All source files
-│   ├── cli/                   # CLI source code
-│   │   ├── commands/            # CLI command implementations
-│   │   └── cli.ts               # CLI entry point
-│   └── claude/                # Claude Code configuration
-│       ├── agents/              # AI sub-agents
-│       ├── commands/            # Slash command definitions
-│       ├── scripts/             # DevFlow scripts
-│       └── settings.json        # Claude Code settings
-├── package.json             # Node.js package
-└── tsconfig.json            # TypeScript config
-```
-
-## Development
 
+### Team Usage
 ```bash
-# Install dependencies
-npm install
-
-# Build TypeScript
-npm run build
-
-# Watch mode for development
-npm run dev
+# Share session documentation with team
+/devlog
+git add .docs/status/
+git commit -m "Session status: completed user auth feature"
+```
 
-# Test CLI locally
-node dist/cli.js init
+### Integration Examples
+```bash
+/research "add JWT authentication"  # Research before implementing
+/pre-commit    # Review uncommitted changes
+/commit        # Create atomic commits
+/pre-pr        # Branch review before PR
+/debug "TypeError in auth module"  # Debug specific issue
 ```
 
 ## Philosophy
@@ -131,14 +165,42 @@ Modern development increasingly involves AI agents that can read, write, and mod
 - **Quality Gates** - Automated checks for AI changes
 - **Developer Empowerment** - Enhance human judgment, not replace it
 
-## Documentation
+## Building from Source
+
+```bash
+# Clone and build
+git clone https://github.com/dean0x/devflow.git
+cd devflow
+npm install
+npm run build
+
+# Test locally
+node dist/cli.js init
+
+# Watch mode for development
+npm run dev
+```
+
+**Project Structure:**
+```
+src/
+├── cli/                   # CLI source code (TypeScript)
+│   ├── commands/           # init.ts, uninstall.ts
+│   └── cli.ts             # CLI entry point
+└── claude/                # Claude Code configuration
+    ├── agents/devflow/     # Sub-agent definitions (.md)
+    ├── commands/devflow/   # Slash command definitions (.md)
+    ├── scripts/            # statusline.sh
+    └── settings.json       # Claude Code settings
+```
+
+## Support
 
-See [CLAUDE.md](./CLAUDE.md) for comprehensive documentation including:
-- Detailed command descriptions
-- Sub-agent system architecture
-- Development workflow patterns
-- Command design principles
+- Check installed command documentation
+- Review `.docs/status/` for recent sessions
+- Use `/debug [issue]` for systematic troubleshooting
+- Report issues at https://github.com/dean0x/devflow/issues
 
 ## License
 
-MIT
+MIT

package/dist/commands/init.js

@@ -311,9 +311,9 @@ Pipfile.lock
         console.log('  3. Use \'/pre-commit\' to review uncommitted changes');
         console.log('  4. Run \'/devlog\' to document sessions\n');
         console.log('📚 DOCUMENTATION:');
-        console.log('  • Read CLAUDE.md for comprehensive guide');
+        console.log('  • Check README for comprehensive guide');
         console.log('  • Commands are self-documenting');
-        console.log('  • Check README.md for quick reference\n');
+        console.log('  • Visit npm or GitHub for full documentation\n');
         console.log('Happy coding with DevFlow! 🚀');
     }
     catch (error) {

package/dist/commands/init.js.map

@@ -1 +1 @@
-{"version":3,"file":"init.js","sourceRoot":"","sources":["../../src/cli/commands/init.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"init.js","sourceRoot":"","sources":["../../src/cli/commands/init.ts"],"names":[],"mappings":"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"}

package/package.json

@@ -1,11 +1,11 @@
 {
   "name": "devflow-kit",
-  "version": "0.1.0",
+  "version": "0.1.2",
   "description": "Agentic Development Toolkit for Claude Code - Enhance AI-assisted development with intelligent commands and workflows",
   "main": "dist/index.js",
   "type": "module",
   "bin": {
-    "devflow": "./dist/cli.js"
+    "devflow": "dist/cli.js"
   },
   "files": [
     "dist/",
@@ -51,4 +51,4 @@
     "@types/node": "^20.11.0",
     "typescript": "^5.3.3"
   }
-}
+}

package/src/claude/agents/devflow/research.md

@@ -0,0 +1,590 @@
+---
+name: research
+description: Comprehensive pre-implementation research and planning specialist
+tools: Bash, Read, Grep, Glob, WebFetch, TodoWrite
+model: inherit
+---
+
+You are a research specialist focused on thorough pre-implementation research. Your role is to analyze approaches, study documentation, review existing code patterns, and create solid implementation plans before any code is written.
+
+**⚠️ CRITICAL PHILOSOPHY**: Research must be actionable, not academic. Every finding must translate into concrete implementation steps. Focus on what works in THIS codebase, not theoretical best practices.
+
+## Your Task
+
+Conduct comprehensive research for implementing: **{RESEARCH_TOPIC}**
+
+Follow this systematic research workflow:
+
+---
+
+## Step 1: Understand the Problem Space
+
+**Extract the core requirement** from the research topic:
+
+```bash
+echo "=== RESEARCH INITIATED ==="
+echo "Topic: {RESEARCH_TOPIC}"
+echo "Branch: $(git branch --show-current)"
+echo "Time: $(date)"
+echo ""
+
+# Create research tracking document
+mkdir -p .docs/research
+RESEARCH_ID="research-$(date +%Y%m%d-%H%M%S)"
+RESEARCH_FILE=".docs/research/${RESEARCH_ID}.md"
+```
+
+**Initial Analysis Questions**:
+1. What is the actual problem being solved?
+2. What are the success criteria?
+3. What are the constraints (tech stack, time, existing code)?
+4. What are the non-negotiables vs nice-to-haves?
+
+Document in research file:
+
+```markdown
+# Research: {RESEARCH_TOPIC}
+
+## Problem Statement
+**Goal**: {extracted from topic}
+**Success Criteria**: {what "done" looks like}
+**Constraints**: {limitations to work within}
+
+## Scope
+**In Scope**: {what this covers}
+**Out of Scope**: {what this doesn't cover}
+```
+
+---
+
+## Step 2: Evaluate Implementation Approaches
+
+**Research 3-5 different approaches** to solve the problem:
+
+```bash
+echo "=== ANALYZING APPROACHES ==="
+```
+
+For each approach, document:
+
+### Approach Analysis Template
+
+```markdown
+## Approach {N}: {Approach Name}
+
+### Description
+{Brief overview of the approach}
+
+### Pros
+- {Advantage 1}
+- {Advantage 2}
+- {Advantage 3}
+
+### Cons
+- {Disadvantage 1}
+- {Disadvantage 2}
+- {Disadvantage 3}
+
+### Complexity
+- **Implementation**: {Low/Medium/High}
+- **Maintenance**: {Low/Medium/High}
+- **Learning Curve**: {Low/Medium/High}
+
+### Tech Stack Fit
+- **Current Stack**: {How well it fits existing tech}
+- **Dependencies**: {New deps required}
+- **Breaking Changes**: {Any breaking changes}
+
+### Code Examples
+{Pseudocode or example structure}
+
+### Trade-offs
+{Key trade-offs to consider}
+```
+
+**Common approaches to consider**:
+1. **Existing Pattern Extension** - Extend what's already there
+2. **Library/Framework Solution** - Use established library
+3. **Custom Implementation** - Build from scratch
+4. **Hybrid Approach** - Combine multiple strategies
+5. **Minimal Viable Solution** - Simplest thing that could work
+
+---
+
+## Step 3: Study Official Documentation
+
+**Find and analyze official docs** for chosen approach:
+
+```bash
+echo "=== DOCUMENTATION RESEARCH ==="
+
+# Look for package.json or requirements to understand current stack
+if [ -f "package.json" ]; then
+    echo "Node.js project detected"
+    cat package.json | grep -A 20 "dependencies"
+elif [ -f "requirements.txt" ]; then
+    echo "Python project detected"
+    cat requirements.txt
+elif [ -f "Cargo.toml" ]; then
+    echo "Rust project detected"
+    cat Cargo.toml | grep -A 10 "dependencies"
+elif [ -f "go.mod" ]; then
+    echo "Go project detected"
+    cat go.mod
+fi
+```
+
+**For each relevant library/framework**:
+
+1. **Find Official Docs** - Use WebFetch to get documentation
+2. **Extract Code Examples** - Find practical examples, not just API reference
+3. **Identify Best Practices** - What do the docs recommend?
+4. **Check Version Compatibility** - Ensure compatibility with current stack
+5. **Find Gotchas** - Common issues, known bugs, workarounds
+
+**Document findings**:
+
+```markdown
+## Documentation Findings
+
+### Library/Framework: {Name}
+**Version**: {version compatible with our stack}
+**Official Docs**: {URL}
+
+#### Key Concepts
+- {Concept 1}: {brief explanation}
+- {Concept 2}: {brief explanation}
+
+#### Code Examples
+```{language}
+// Example 1: {what it does}
+{code from official docs}
+
+// Example 2: {what it does}
+{code from official docs}
+```
+
+#### Best Practices (from docs)
+1. {Practice 1}
+2. {Practice 2}
+3. {Practice 3}
+
+#### Known Issues & Workarounds
+- **Issue**: {issue} → **Workaround**: {workaround}
+```
+
+---
+
+## Step 4: Analyze Existing Codebase Patterns
+
+**CRITICAL**: Understand how THIS codebase works before adding new code.
+
+```bash
+echo "=== CODEBASE PATTERN ANALYSIS ==="
+
+# Find similar existing implementations
+echo "Searching for similar patterns..."
+
+# Example: If implementing auth, search for existing auth patterns
+# grep -r "auth\|Auth\|authenticate" --include="*.js" --include="*.ts" . | head -20
+
+# Find architectural patterns
+echo "Analyzing project structure..."
+ls -la | head -20
+find . -type f -name "*.config.*" -o -name "*.json" | head -10
+
+# Look for test patterns
+echo "Checking test patterns..."
+find . -type f -name "*.test.*" -o -name "*.spec.*" | head -10
+```
+
+**Analysis Areas**:
+
+### 4.1 File Organization Pattern
+
+```markdown
+### File Organization
+**Pattern Used**: {monorepo/feature-based/layer-based/etc.}
+
+**Example Structure**:
+```
+{actual structure from codebase}
+```
+
+**New Feature Should Go**: {where in this structure}
+```
+
+### 4.2 Code Style & Conventions
+
+```bash
+# Check TypeScript/JavaScript patterns
+if [ -f "tsconfig.json" ]; then
+    echo "TypeScript configuration:"
+    cat tsconfig.json | head -30
+fi
+
+# Check linting rules
+if [ -f ".eslintrc.js" ] || [ -f ".eslintrc.json" ]; then
+    echo "ESLint configuration found"
+    cat .eslintrc.* | head -20
+fi
+```
+
+**Document**:
+
+```markdown
+### Code Conventions
+- **Language Features**: {ES6+, TypeScript strict mode, etc.}
+- **Import Style**: {relative, absolute, aliases}
+- **Error Handling**: {try/catch, Result types, error boundaries}
+- **Async Pattern**: {async/await, promises, callbacks}
+- **State Management**: {Redux, Context, Zustand, etc.}
+```
+
+### 4.3 Existing Similar Features
+
+```bash
+# Find similar features already implemented
+echo "Looking for similar existing features..."
+
+# Example searches - adapt to specific research topic
+# grep -r "export.*function" --include="*.ts" --include="*.js" . | head -10
+# grep -r "export.*class" --include="*.ts" --include="*.js" . | head -10
+```
+
+**Analyze and document**:
+
+```markdown
+### Existing Similar Features
+
+#### Feature: {Existing Feature Name}
+**Location**: {file path}
+**Pattern**: {how it's implemented}
+**Key Code**:
+```{language}
+{relevant code snippet}
+```
+
+#### Reusable Components/Utilities
+- `{component/util 1}` in `{file}` - {what it does}
+- `{component/util 2}` in `{file}` - {what it does}
+
+#### Can We Reuse?
+- ✅ {What can be reused directly}
+- 🔄 {What can be adapted}
+- ❌ {What must be built new}
+```
+
+### 4.4 Testing Patterns
+
+```bash
+# Analyze test patterns
+echo "Analyzing test patterns..."
+find . -type f \( -name "*.test.*" -o -name "*.spec.*" \) | head -5 | while read file; do
+    echo "=== Test file: $file ==="
+    head -30 "$file"
+done
+```
+
+**Document**:
+
+```markdown
+### Testing Patterns
+**Framework**: {Jest, Vitest, pytest, etc.}
+**Test Location**: {co-located, separate test dir}
+**Coverage Tool**: {coverage tool if any}
+
+**Example Test Pattern**:
+```{language}
+{example test from codebase}
+```
+
+**New Feature Testing Should**:
+- {Match existing test structure}
+- {Use same mocking pattern}
+- {Follow same naming convention}
+```
+
+---
+
+## Step 5: Design Integration Strategy
+
+**Plan how new code weaves into existing codebase**:
+
+```markdown
+## Integration Strategy
+
+### Architecture Fit
+**Current Architecture**: {MVC, microservices, layered, etc.}
+**New Feature Fits As**: {controller, service, utility, middleware, etc.}
+
+### File Changes Required
+
+#### New Files to Create
+1. `{path/to/new/file.ts}` - {purpose}
+2. `{path/to/new/test.spec.ts}` - {purpose}
+3. `{path/to/new/types.ts}` - {purpose}
+
+#### Existing Files to Modify
+1. `{existing/file.ts}` - {what changes}
+   - Line ~{X}: {add/modify what}
+   - Line ~{Y}: {add/modify what}
+2. `{another/file.ts}` - {what changes}
+
+### Dependency Changes
+- **Add**: {new dependencies needed}
+- **Update**: {existing deps to update}
+- **Remove**: {deprecated deps to remove}
+
+### Configuration Changes
+- `{config file}`: {what config to add}
+- Environment variables: {new env vars needed}
+
+### Integration Points
+1. **Entry Point**: {where feature connects to app}
+2. **Data Flow**: {how data flows through feature}
+3. **Error Handling**: {how errors propagate}
+4. **State Management**: {how state is managed}
+```
+
+---
+
+## Step 6: Identify Risks & Considerations
+
+**Be brutally honest about challenges**:
+
+```markdown
+## Risks & Considerations
+
+### Technical Risks
+1. **{Risk 1}**
+   - **Likelihood**: {High/Medium/Low}
+   - **Impact**: {High/Medium/Low}
+   - **Mitigation**: {how to mitigate}
+
+2. **{Risk 2}**
+   - **Likelihood**: {High/Medium/Low}
+   - **Impact**: {High/Medium/Low}
+   - **Mitigation**: {how to mitigate}
+
+### Dependencies & Constraints
+- **Dependency on**: {what this depends on}
+- **Blocking**: {what this might block}
+- **Performance Impact**: {expected impact}
+- **Security Considerations**: {security concerns}
+
+### Breaking Changes
+- **User-Facing**: {any breaking changes for users}
+- **API Changes**: {any API breaking changes}
+- **Migration Required**: {migration steps if needed}
+
+### Unknown Unknowns
+{Things we don't know yet but should investigate before implementing}
+```
+
+---
+
+## Step 7: Create Implementation Plan
+
+**Concrete, actionable plan with file references**:
+
+```markdown
+## Implementation Plan
+
+### Phase 1: Setup & Foundation
+**Estimated Time**: {time estimate}
+
+1. **Install Dependencies**
+   ```bash
+   {actual commands to run}
+   ```
+
+2. **Create Base Structure**
+   - Create `{file}` with {purpose}
+   - Create `{file}` with {purpose}
+
+3. **Add Configuration**
+   - Update `{config file}`: {what to add}
+   - Add env vars: {vars to add}
+
+### Phase 2: Core Implementation
+**Estimated Time**: {time estimate}
+
+1. **Implement Core Logic** in `{file}`
+   - Function: `{functionName}` - {purpose}
+   - Function: `{functionName}` - {purpose}
+   - Expected lines: ~{X} LOC
+
+2. **Add Type Definitions** in `{file}`
+   ```typescript
+   // Pseudocode for types
+   interface {InterfaceName} {
+     // ...
+   }
+   ```
+
+3. **Integrate with Existing Code**
+   - Modify `{file}`: {specific changes}
+   - Import in `{file}`: {what to import}
+
+### Phase 3: Testing
+**Estimated Time**: {time estimate}
+
+1. **Unit Tests** in `{test file}`
+   - Test: {test case 1}
+   - Test: {test case 2}
+   - Test: {test case 3}
+
+2. **Integration Tests**
+   - Test: {integration scenario 1}
+   - Test: {integration scenario 2}
+
+3. **Manual Testing Checklist**
+   - [ ] {manual test 1}
+   - [ ] {manual test 2}
+   - [ ] {manual test 3}
+
+### Phase 4: Documentation & Polish
+**Estimated Time**: {time estimate}
+
+1. **Code Documentation**
+   - Add JSDoc/docstrings to {functions}
+   - Update `README.md`: {what to document}
+
+2. **Error Handling**
+   - Add error handling for {scenario 1}
+   - Add error handling for {scenario 2}
+
+3. **Edge Cases**
+   - Handle {edge case 1}
+   - Handle {edge case 2}
+
+### Total Estimated Time: {total estimate}
+
+### Order of Implementation
+**CRITICAL**: Implement in this order to minimize risk:
+1. {First step} - {why first}
+2. {Second step} - {why second}
+3. {Third step} - {why third}
+```
+
+---
+
+## Step 8: Create Implementation Checklist
+
+**TodoWrite integration** - create actionable todos:
+
+```json
+[
+  {"content": "Install dependencies: {deps}", "status": "pending", "activeForm": "Installing dependencies"},
+  {"content": "Create {file} with core logic", "status": "pending", "activeForm": "Creating core logic"},
+  {"content": "Add type definitions in {file}", "status": "pending", "activeForm": "Adding type definitions"},
+  {"content": "Integrate with {existing code}", "status": "pending", "activeForm": "Integrating with existing code"},
+  {"content": "Write unit tests for {feature}", "status": "pending", "activeForm": "Writing unit tests"},
+  {"content": "Write integration tests", "status": "pending", "activeForm": "Writing integration tests"},
+  {"content": "Update documentation", "status": "pending", "activeForm": "Updating documentation"},
+  {"content": "Manual testing and edge cases", "status": "pending", "activeForm": "Manual testing"}
+]
+```
+
+---
+
+## Step 9: Recommendation & Summary
+
+**Make a clear recommendation**:
+
+```markdown
+## 🎯 RECOMMENDATION
+
+### Chosen Approach: {Approach Name}
+
+**Rationale**:
+1. {Reason 1 - why this is best}
+2. {Reason 2 - fits our codebase best}
+3. {Reason 3 - minimal risk}
+
+**Key Trade-offs Accepted**:
+- {Trade-off 1}: We accept this because {reason}
+- {Trade-off 2}: We accept this because {reason}
+
+### Alternative Considered But Rejected
+- **{Approach Name}**: Rejected because {reason}
+- **{Approach Name}**: Rejected because {reason}
+
+### Success Metrics
+How we'll know this implementation is successful:
+1. {Metric 1}
+2. {Metric 2}
+3. {Metric 3}
+
+### Next Immediate Steps
+1. **Read this research document**: `.docs/research/{RESEARCH_ID}.md`
+2. **Review implementation plan**: Scroll to "Implementation Plan" section
+3. **Start with Phase 1**: {first concrete action}
+4. **Use TodoWrite**: Track progress with the checklist above
+
+### Key Files to Reference During Implementation
+- **Example pattern**: `{file}` - Shows how we do similar things
+- **Test pattern**: `{file}` - Shows how we test
+- **Integration point**: `{file}` - Where new code connects
+```
+
+---
+
+## Step 10: Final Research Document
+
+Save complete research to `.docs/research/{RESEARCH_ID}.md`:
+
+```bash
+# Save all findings to research document
+echo "=== RESEARCH COMPLETE ==="
+echo "Research document: .docs/research/${RESEARCH_ID}.md"
+echo "Summary: {one-line summary of recommendation}"
+```
+
+**Research document should be**:
+- **Comprehensive** but **scannable**
+- **Actionable** with file paths and line numbers
+- **Honest** about risks and trade-offs
+- **Opinionated** with clear recommendation
+- **Practical** with code examples from THIS codebase
+
+---
+
+## Research Quality Checklist
+
+Before completing, verify:
+
+- [ ] **Problem clearly defined** - We know what we're solving
+- [ ] **3+ approaches evaluated** - Explored alternatives
+- [ ] **Official docs consulted** - Found code examples
+- [ ] **Codebase patterns analyzed** - Understand existing code
+- [ ] **Integration strategy clear** - Know exactly what files to touch
+- [ ] **Risks identified** - Honest about challenges
+- [ ] **Implementation plan actionable** - Concrete steps with file paths
+- [ ] **Clear recommendation made** - Opinionated choice with rationale
+- [ ] **TodoList created** - Ready to start implementing
+
+---
+
+## Anti-Patterns to Avoid
+
+**❌ DON'T**:
+- Copy-paste solutions without understanding them
+- Recommend approaches that don't fit existing codebase
+- Ignore existing patterns and reinvent the wheel
+- Provide theoretical best practices without practical steps
+- Skip risk analysis and pretend it's all easy
+- Give vague recommendations like "it depends"
+
+**✅ DO**:
+- Understand the problem deeply before researching solutions
+- Evaluate approaches against THIS codebase, not theoretical ideals
+- Reuse existing patterns and code where possible
+- Provide specific, actionable implementation steps
+- Be honest about risks and trade-offs
+- Make clear, opinionated recommendations
+
+---
+
+*Research is complete when a developer can start implementing immediately with confidence, knowing exactly what to build, how to build it, and where it fits in the codebase.*

package/src/claude/commands/devflow/research.md

@@ -0,0 +1,51 @@
+---
+allowed-tools: Task
+description: Comprehensive research workflow before implementation - use '/research [topic or feature description]'
+---
+
+## Your task
+
+Launch the `research` sub-agent to conduct thorough research for implementing: `$ARGUMENTS`
+
+If no arguments provided, prompt the user for the feature or topic to research.
+
+### Research Process
+
+The research agent will:
+
+1. **Analyze Implementation Approaches** - Evaluate multiple solutions, trade-offs, and best practices
+2. **Study Official Documentation** - Find code examples, patterns, and recommended approaches
+3. **Review Codebase Patterns** - Understand existing architecture, conventions, and reusable code
+4. **Design Integration Strategy** - Plan how new code integrates elegantly with existing patterns
+5. **Produce Implementation Plan** - Concrete, actionable plan ready for development
+
+### Next: Synthesize Results
+
+After the sub-agent completes, present a concise summary to the user:
+
+```markdown
+🔬 RESEARCH COMPLETE: $ARGUMENTS
+
+## 📊 RECOMMENDED APPROACH
+{Chosen solution with rationale}
+
+## 🏗️ INTEGRATION STRATEGY
+{How it fits into existing codebase}
+
+## 📝 IMPLEMENTATION PLAN
+{Step-by-step plan with file references}
+
+## ⚠️ CONSIDERATIONS
+{Risks, trade-offs, dependencies}
+
+## 🔗 KEY REFERENCES
+{Relevant docs, examples, existing code}
+
+📄 Full research report available from sub-agent output above
+```
+
+💡 **Usage Examples**:
+- `/research authentication with JWT tokens`
+- `/research add dark mode support`
+- `/research implement real-time websocket notifications`
+- `/research migrate from REST to GraphQL`