devflow-kit

DevFlow - Agentic Development Toolkit

A comprehensive collection of Claude Code commands and configurations designed to enhance developer workflows when working with AI coding assistants.

Installation

# Run with npx (recommended - no global install needed)
npx devflow-kit init

Installation Scopes

DevFlow supports two installation scopes:

User Scope (Default) - Install for all projects

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

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

🎯 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 debug skill also exists as a slash command (/debug) for manual control:

• Skill mode (auto): Activates when Claude detects errors or failures
• Command mode (manual): Use /debug when you want explicit control over the debugging 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
/brainstorm	Explore design decisions and architectural approaches	Before implementation, evaluating options
/design	Create detailed implementation plan with integration points	After brainstorming, ready for detailed design
/plan	Triage issues - implement now, defer to GitHub issue, or skip	After code-review or discussion, deciding what to tackle
/breakdown	Quickly break down discussion into actionable tasks	After planning discussion, quick task capture
/get-issue	Fetch GitHub issue details and create working branch	Starting work on a GitHub issue
/implement	Streamlined todo implementation, only stopping for design decisions	After planning, ready to implement todos
/debug	Systematic debugging workflow with hypothesis testing	When errors occur, tests fail, or investigating issues
/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
/pull-request	Create PR with comprehensive analysis and smart description	After commits, ready to create PR
/resolve-comments	Systematically address PR review feedback	After PR feedback, need to resolve comments
/release	Automated release workflow with version management and publishing	Creating a new release
/devlog	Development log for comprehensive session documentation	Ending a session

🤖 Sub-Agents

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 (surgical execution)
audit-complexity	Complexity	Code complexity and maintainability assessment
audit-dependencies	Dependencies	Dependency management and security analysis
audit-database	Database	Database design and optimization review
audit-documentation	Documentation	Docs-code alignment, API accuracy, comment quality
audit-typescript	TypeScript	Type safety enforcement and TypeScript code quality
brainstorm	Design Decisions	Explore architectural approaches and evaluate trade-offs
design	Implementation Planning	Detailed implementation design with integration points and edge cases
catch-up	Context Restoration	Project status and context restoration with validation
commit	Git Operations	Intelligent commit creation with safety checks
get-issue	GitHub Issues	Fetch issue details and create working branches
pull-request	PR Creation	Analyze commits/changes and generate comprehensive PR descriptions
release	Release Automation	Project-agnostic release workflow with version management
debug	Debugging	Systematic debugging with hypothesis testing and issue tracking

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:

# Explicit invocation
"Use the audit-security sub-agent to analyze this authentication code"

# 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 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.

Documentation Structure

DevFlow agents automatically create and maintain project documentation in the .docs/ directory with a consistent, predictable structure.

Directory Layout

.docs/
├── audits/{branch-slug}/       # Code review reports per branch
│   ├── {type}-report-{timestamp}.md
│   └── review-summary-{timestamp}.md
├── brainstorm/                 # Design explorations
│   └── {topic-slug}-{timestamp}.md
├── design/                     # Implementation plans
│   └── {topic-slug}-{timestamp}.md
├── debug/                      # Debug sessions
│   ├── debug-{timestamp}.md
│   └── KNOWLEDGE_BASE.md
├── releases/                   # Release notes
│   └── RELEASE_NOTES_v{version}.md
├── status/                     # Development logs
│   ├── {timestamp}.md
│   ├── compact/{timestamp}.md
│   └── INDEX.md
└── CATCH_UP.md                 # Latest summary

Naming Conventions

Timestamps: YYYY-MM-DD_HHMM (sortable, chronological)

• Example: 2025-11-14_2030

Branch slugs: Sanitized branch names (slashes replaced with dashes)

• feature/auth → feature-auth

Topic slugs: Lowercase, alphanumeric with dashes

• "JWT Authentication" → jwt-authentication

What Gets Created

• /catch-up → .docs/CATCH_UP.md (overwritten each run)
• /devlog → .docs/status/{timestamp}.md + compact version + INDEX
• /debug → .docs/debug/debug-{timestamp}.md + KNOWLEDGE_BASE
• /brainstorm → .docs/brainstorm/{topic}-{timestamp}.md
• /design → .docs/design/{topic}-{timestamp}.md
• /code-review → .docs/audits/{branch}/ (9 audit reports + summary)
• /release → .docs/releases/RELEASE_NOTES_v{version}.md

Version Control

Recommended .gitignore:

# Exclude ephemeral catch-up summaries
.docs/CATCH_UP.md

# Optional: Exclude debug sessions (team preference)
.docs/debug/

# Keep everything else for project history

The .docs/ structure provides a searchable history of decisions, designs, and debugging sessions.

Development Workflow

Starting a Session

• /catch-up - Review what was done previously
• Check statusline for current model, git state, duration
• Review recommended next actions

During Development

• Skills auto-activate - research skill triggers for unfamiliar features, pattern-check validates architecture
• Plan your work - /plan to triage issues, or /breakdown for quick task capture
• Implement efficiently - /implement flows through todos automatically
• Code with confidence - Skills catch anti-patterns and violations during implementation
• /code-review - Review changes before committing
• /commit - Create intelligent atomic commits

Creating Pull Requests

• /code-review - Comprehensive branch review
• /commit - Final commits with validation
• /pull-request - Create PR with smart description
• Wait for review feedback
• /resolve-comments - Address feedback systematically
• Repeat steps 4-5 until approved

Ending a Session

• /devlog - Document decisions and state
• /code-review - Review branch before creating PR
• /commit - Final commits with validation
• /pull-request - Create PR if ready

Creating a Release

• /code-review - Comprehensive branch review
• /release - Automated release workflow
  • Detects project type (Node.js, Rust, Python, Go, etc.)
  • Analyzes commits and suggests version bump
  • Generates changelog from git history
  • Builds and tests before publishing
  • Creates git tags and platform releases
• Verify package in registry

When Things Go Wrong

• Skills auto-activate - debug skill triggers on errors/failures with systematic approach
• Check git log and recent commits
• Revert changes using git
• Document lessons learned in .docs/debug/

CLI Commands

Command	Purpose	Options
npx devflow-kit init	Initialize DevFlow for Claude Code	--scope <user|local> - Installation scope (user: user-wide, local: project-only) --verbose - Show detailed installation output --skip-docs - Skip creating .docs/ structure
npx devflow-kit uninstall	Remove DevFlow from Claude Code	--scope <user|local> - Uninstall from specific scope only (default: auto-detect all) --keep-docs - Keep .docs/ directory

What npx devflow-kit init does:

User Scope (default):

• Installs commands to ~/.claude/commands/devflow/
• Installs sub-agents to ~/.claude/agents/devflow/
• Installs skills to ~/.claude/skills/
• 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/
• 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:

devflow init
/devlog      # Document your current project state
/catch-up    # Get oriented with the project

Advanced Usage

Custom Audit Rules

# Extend sub-agents for project-specific patterns
echo "Check for exposed API keys in config files" >> ~/.claude/agents/devflow/audit-security.md

Team Usage

# Share session documentation with team
/devlog
git add .docs/status/
git commit -m "Session status: completed user auth feature"

Integration Examples

# Skills auto-activate during development
"Add JWT authentication"  # research skill triggers for unfamiliar features
"Fix this error"          # debug skill activates and guides systematic approach

# Manual command invocation for structured workflows
/brainstorm user authentication  # Explore architectural approaches
/design JWT token system         # Create detailed implementation plan
/code-review                     # Review changes before committing
/commit                          # Create atomic commits
/release                         # Automated release workflow

Philosophy

Modern development increasingly involves AI agents that can read, write, and modify code autonomously. DevFlow provides:

• Trust but Verify - Tools to catch AI agent mistakes
• Context Preservation - Memory across long-term projects
• Quality Gates - Automated checks for AI changes
• Developer Empowerment - Enhance human judgment, not replace it

Building from Source

# 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)
    ├── skills/devflow/     # Skill source (installed flat to ~/.claude/skills/)
    ├── scripts/            # statusline.sh
    └── settings.json       # Claude Code settings

Support

• Check installed command documentation
• Review .docs/status/ for recent sessions
• Skills auto-activate for systematic troubleshooting
• Report issues at https://github.com/dean0x/devflow/issues

License

MIT