DevSteps VS Code Extension

Never Code Alone. Team Up With Your AI.

⚠️ Pre-Release Version 0.7.0-next.4

This is an experimental pre-release for early testing. Features may change, and stability is not guaranteed. Install the stable release for production use.

What's New in 0.7.0-next.4:

🗂️ Items Directory Migration: Git-inspired object store architecture (.devsteps/items/)
📝 Improved Git Workflow: Enhanced documentation and merge strategies
🧪 Test Configuration: Non-blocking test execution for better CI/CD integration

Known Issues:

Auto-migration triggers on first run (one-time operation, 686 files)
Some test failures expected during migration (fixed in next iteration)

Feedback Welcome! Report issues or suggestions at GitHub Issues

AI-First Development Workflow System integrated directly into VS Code. Structure your development process with traceable work items, visualize project health with an interactive dashboard, and integrate with AI agents via the Model Context Protocol (MCP).

✨ Features

Dual-Mode Display: Flat or hierarchical view of work items
Advanced Filtering: Filter by status, priority, type, or tags
Multi-Field Sorting: Sort by status, priority, updated date, title, type, or ID
Color-Coded Badges: Visual status indicators (draft, done, in-progress, blocked)
Quick Actions: Context menus for common operations

📊 Interactive Dashboard

Project Statistics: Real-time counts by type, status, priority, Eisenhower quadrant
Eisenhower Matrix: 4-quadrant view (Urgent/Important categorization)
Sprint Burndown Chart: Track progress with ideal vs actual burndown
Traceability Graph: Force-directed visualization of item relationships
Activity Timeline: Recent updates at a glance
Performance Optimized: Handles 10K+ items with <2s load time

🔗 Traceability & Relationships

Navigate parent-child relationships (epic → story → task)
View implementation links, dependencies, test coverage
Visual graph showing connected items

🤖 AI Integration (MCP)

Model Context Protocol (MCP) support for AI agents
Export project context for AI-assisted development
Seamless integration with GitHub Copilot

📦 Installation

Pre-Release Installation (Current - 0.7.0-next.4)

From VS Code Marketplace:

Search for "DevSteps" in Extensions view
Click "Switch to Pre-Release" button
Install version 0.7.0-next.4

Install MCP Server (@next):

npm install -g @schnick371/devsteps-mcp-server@next

CLI (@next - Optional):

npm install -g @schnick371/devsteps-cli@next

Stable Release (Recommended for Production)

Search for "DevSteps" in the VS Code Extensions view and install the stable release.

MCP Server (Stable):

npm install -g @schnick371/devsteps-mcp-server

⚙️ Prerequisites

Required:

Node.js ≥ 18.0 (includes npm and npx)
VS Code ≥ 1.99.0 (March 2025 or later for MCP support)

Why Node.js?

DevSteps uses the Model Context Protocol (MCP) to integrate with AI assistants like GitHub Copilot. The MCP server requires Node.js to run.

Installing Node.js

Windows

Option 1: Official Installer (Recommended)

Download from nodejs.org
Run installer (installs Node.js, npm, and npx)
Restart VS Code after installation

Option 2: winget (Windows Package Manager)

winget install OpenJS.NodeJS

macOS

Option 1: Official Installer

Download from nodejs.org
Run .pkg installer
Restart VS Code after installation

Option 2: Homebrew (Recommended for developers)

brew install node

Linux

Debian/Ubuntu:

sudo apt update
sudo apt install nodejs npm

Fedora/RHEL:

sudo dnf install nodejs npm

Arch Linux:

sudo pacman -S nodejs npm

Other distributions: See nodejs.org/download

Verify Installation

After installing Node.js, verify the installation:

node --version   # Should show v18.0.0 or higher
npm --version    # Should show npm version
npx --version    # Should show npx version

Check DevSteps Prerequisites

DevSteps includes a built-in prerequisites checker:

Open Command Palette (Cmd/Ctrl+Shift+P)
Run DevSteps: Check Prerequisites
Review results in Output Channel

The command will show:

✅ Node.js, npm, npx detected versions and paths
⚠️ Missing components with installation instructions
🔧 Selected MCP server strategy (npx or node)

🚀 Getting Started

Initialize a DevSteps Project

Pre-Release (@next):

# Install CLI
npm install -g @schnick371/devsteps-cli@next

# Initialize project
devsteps init my-project --methodology scrum

# Add your first work item
devsteps add epic "Build Amazing Product"

Stable:

npm install -g @schnick371/devsteps-cli
devsteps init my-project

Use in VS Code

Open workspace with DevSteps project (.devsteps/ directory present)
DevSteps icon appears in Activity Bar (left sidebar)
TreeView: View/filter/sort work items
Dashboard: Click 📊 button in TreeView toolbar for visualizations

🎯 Key Commands

Command	Description
`DevSteps: Show Dashboard`	Open interactive project dashboard
`DevSteps: Refresh Work Items`	Reload items from disk
`DevSteps: Change View Mode`	Toggle flat/hierarchical view
`DevSteps: Filter by Status`	Show only items with specific status
`DevSteps: Sort Items`	Change sorting criteria

⚙️ Configuration

No configuration required! Extension auto-detects DevSteps projects.

Optional Settings (future releases):

devsteps.dashboard.traceabilityMaxNodes: Max nodes in traceability graph (default: 50)
devsteps.treeView.defaultView: Initial view mode (default: "flat")

🎨 Visual Design

DevSteps extension follows VS Code theme colors automatically:

Light themes → Clean, professional appearance
Dark themes → Eye-friendly, modern aesthetic
High contrast themes → Fully accessible

📈 Performance

Optimized for Large Projects:

Dashboard: <500ms for 1K items, <2s for 10K items
TreeView: Instant filtering/sorting
Memory: <50MB for 10K items (within VS Code guidelines)

🔧 Troubleshooting

MCP Server Not Starting?

Symptom: "DevSteps MCP Server requires Node.js" error or MCP tools not working in Copilot

Solutions:

Run Prerequisites Check
- Command Palette → DevSteps: Check Prerequisites
- Review Output Channel for detailed diagnostics
Install Node.js (if missing)
- See Prerequisites section above
- Restart VS Code after installation
Verify PATH Configuration
- Open terminal in VS Code
- Run node --version and npx --version
- If commands not found: Node.js not in PATH
- Fix: Reinstall Node.js or add to PATH manually
Check MCP Server Status
- Command Palette → DevSteps: Show MCP Server Status
- Shows runtime strategy (npx/node) and detected versions

Common Causes:

Node.js not installed
Node.js installed but VS Code terminal doesn't see it (PATH issue)
VS Code started before Node.js installation (restart needed)

Extension Not Activating?

Ensure .devsteps/ directory exists in workspace root OR
Extension activates even without project (for MCP tools)
Check VS Code version (requires 1.99.0+, March 2025 or later)
Reload window: Cmd/Ctrl+Shift+P → Developer: Reload Window

Dashboard Not Loading?

Check DevTools console: Help → Toggle Developer Tools
Verify .devsteps/index.json file exists and is valid JSON
Try DevSteps: Show Dashboard command again

TreeView Empty?

Run DevSteps: Refresh Work Items command
Ensure work items exist (devsteps list in terminal)
Check .devsteps/*.json files for corruption

Copilot Can't Use DevSteps Tools?

Verify MCP server is running (status bar shows "DevSteps MCP")
Check prerequisites (DevSteps: Check Prerequisites)
Try asking Copilot: "@devsteps #mcp_devsteps_devsteps-list"
If still not working: Restart VS Code

"npx: command not found" Error?

This means npx is not installed or not in PATH.

Fix:

Install Node.js (includes npx): See Prerequisites
Restart VS Code
Run DevSteps: Check Prerequisites to verify

Alternative: Extension will automatically fall back to bundled MCP server if npx unavailable

🐛 Known Issues (Pre-Release 0.7.0-next.4)

Migration-Related:

[ ] Auto-migration runs on first startup (expected, one-time operation)
[ ] Test failures during migration (addressed in next iteration)

Performance:

[ ] Graph force simulation may lag with 100+ highly-connected nodes (optimization in progress)
[ ] Large project initial load may take 3-5s (caching planned for future release)

How to Report Issues: Please include:

Pre-Release version (0.7.0-next.4)
VS Code version
Steps to reproduce
Expected vs actual behavior

Report at: GitHub Issues

📝 Release Notes

0.7.0-next.4 (Pre-Release - December 2025)

⚠️ Experimental Features - Testing Only

Major Changes:

✅ Items Directory Migration (STORY-079): Restructured .devsteps/ to git-inspired object store
- Old: .devsteps/epics/, .devsteps/stories/ (flat)
- New: .devsteps/items/epics/, .devsteps/items/stories/ (nested)
- Auto-migration: Detects old structure and migrates on first run
✅ Git Workflow Improvements: Enhanced merge strategies and documentation
✅ Test Configuration: Non-blocking test execution for CI/CD pipelines

Migration Notes:

First startup: Auto-migration runs (one-time, ~686 files)
No backward compatibility during transition
Backup recommended before installing pre-release

What to Test:

Items directory structure after migration
Dashboard loading with new directory layout
TreeView functionality with nested items
MCP server integration with new paths

Feedback Channels:

GitHub Issues: Bug reports, feature requests
GitHub Discussions: Questions, suggestions

0.4.0 (Stable Release)

Major Features:

✅ Interactive WebView Dashboard with 5 visualization sections
✅ Advanced TreeView filtering and sorting
✅ Color-coded status badges (FileDecorationProvider)
✅ Performance optimizations (5-10× faster dashboard)
✅ Traceability graph node limiting (handles 1K+ items)