SpecDriven Agent - VS Code Extension

A fully autonomous AI development agent integrated with GitHub Copilot. Interactive 6-command workflow with deep analysis, super memory, and zero hallucinations.

🌟 v3.1 - Interactive Multi-Step Workflow

6 commands for guided project development.

🚀 Building New Apps (Interactive Flow)

🔬 For Existing Code

📖 Usage Examples

Start a New Project

@specdriven /start Build a task management app where teams can create projects, assign tasks, and track progress with kanban boards

The AI will:

1. ✅ Understand your requirements
2. ✅ Identify features, user types, data models
3. ✅ Ask clarifying questions
4. ✅ Guide you through next steps

Generate Specification

@specdriven /spec

Or add more requirements:

@specdriven /spec Add payment processing with Stripe

Create Technical Plan

@specdriven /plan Use React with TypeScript and PostgreSQL

Build Everything

@specdriven /confirm

The AI generates all code files automatically!

Analyze Existing Code

@specdriven /analyze

Analyzes every line of code and generates comprehensive documentation.

🧠 Key Features

• 🤖 Interactive Workflow: 6 commands guide you step-by-step
• 💬 Conversational: Just chat naturally, AI remembers context
• 🔬 Deep Analysis: Line-by-line code reverse engineering
• 🧠 Super Memory: Full context across entire session
• ❌ Zero Hallucination: Only facts from actual code
• 📁 Local Storage: All docs in .specify/ folder
• ⚡ Multi-Operational: Handles large codebases in batches

🚀 Getting Started

Prerequisites

• VS Code 1.107.0 or higher
• GitHub Copilot subscription (for chat participant features)

Installation

1. Install the extension from the VS Code Marketplace (or package .vsix)
2. Open a workspace folder in VS Code
3. The .specify directory will be automatically created

Quick Start - Just Describe What You Want!

Option 1: Describe a new app

@specdriven Build a Barcode Scanner system with login, add items to cart, checkout, payment processing, and receipt generation. Use Vite with vanilla HTML/CSS/JS and SQLite.

The AI will automatically create:

• spec.md - Detailed specification
• plan.md - Technical implementation plan
• tasks.md - Task breakdown
• Complete project folder with all code files!

Option 2: Analyze existing code

@specdriven analyze this project and create specifications

Option 3: Sync after changes

@specdriven sync my changes

Traditional Step-by-Step (Optional)

If you prefer more control:

1. Define Your Project Principles

   @specdriven /constitution This project follows TDD strictly. We prefer functional programming patterns and minimal dependencies.
   

2. Create a Feature Specification

   @specdriven /specify Build a Barcode Scanner system with login, add items to cart, checkout, payment processing, and receipt generation.
   

3. Generate Implementation Plan

   @specdriven /plan Use Vite with vanilla HTML, CSS, and JavaScript. Store data in SQLite. Keep it simple with minimal libraries.
   

4. Break Down Into Tasks

   @specdriven /tasks
   

5. 🤖 Fully Autonomous Implementation

   @specdriven /implement
   

   The AI agent will:

   • ✅ Automatically analyze all specification documents
   • ✅ Generate complete project structure specification
   • ✅ Create detailed file-by-file implementation plan
   • ✅ List all files that will be created
   • ✅ Wait for your confirmation to create the project folder

   Then say: "create the project" or "create all files"

   The agent will:

   • ✅ Create new project folder in your workspace
   • ✅ Generate all files with production-ready code
   • ✅ Include comprehensive test suite
   • ✅ Ready to run immediately: npm install && npm run dev

6. 🚀 Project Auto-Creation

   The AI will automatically:

   • Create project folder named after your feature
   • Generate 10-20+ complete files with working code
   • Include all configuration, frontend, backend files
   • Add comprehensive test suite (unit, integration, E2E)
   • Create README with setup instructions
   • Open the new project automatically

🎯 Autonomous AI Implementation

The /implement command is now fully autonomous:

Completely Automated Implementation:

1. 🧠 AI Auto-Analysis

   • Automatically reads all specification documents
   • Understands requirements and complexity
   • Selects optimal tech stack without user input

2. 🚀 AI Auto-Generation

   • Automatically generates complete project structure
   • Creates 10-20+ production-ready files
   • No user confirmation needed
   • No option selection required

3. 📁 Automatic Project Creation

   • Creates new project folder in workspace
   • Writes all files with complete working code
   • Includes comprehensive test suite
   • Opens project automatically
   • Ready to run: npm install && npm run dev

What The AI Agent Does Autonomously:

1. 📖 Reads All Documents

   • Constitution (project principles)
   • Spec.md (requirements)
   • Plan.md (technical approach)
   • Tasks.md (task breakdown)
   • Data-model.md (schemas)
   • API contracts

2. 🧠 Makes Autonomous Decisions

   • Selects best tech stack automatically
   • Determines optimal project structure
   • Plans component architecture
   • Decides on file organization

3. 💻 Generates Production Code

   • Complete, working code files
   • No placeholders or TODOs
   • Implements all requirements
   • Includes comprehensive test suite
   • UI validation tests
   • Functionality tests with edge cases

4. 📁 Creates Project Folder

   • New folder in your workspace
   • Complete project structure
   • All files written and ready
   • Test files included
   • Can be run immediately

What The AI Agent Does:

1. 📖 Reads All Documents

   • Constitution (project principles)
   • Spec.md (requirements)
   • Plan.md (technical approach)
   • Tasks.md (task breakdown)
   • Data-model.md (schemas)
   • API contracts

2. 🧠 Makes Autonomous Decisions

   • Suggests multiple tech stack options
   • Recommends best approach based on requirements
   • Decides on project structure after confirmation
   • Determines file organization
   • Plans component architecture

3. 💻 Generates Production Code

   • Complete, working code files
   • No placeholders or TODOs
   • Follows chosen tech stack exactly
   • Implements all requirements
   • Includes comprehensive test suite
   • UI validation tests
   • Functionality tests with edge cases

4. 📁 Creates Project Folder

   • New folder in your workspace
   • Complete project structure
   • All files written and ready
   • Test files included
   • Can be run immediately

5. 🧪 Generates Tests Automatically

   • Unit tests for all components
   • Integration tests for APIs
   • End-to-end tests for user flows
   • UI validation tests
   • 80%+ code coverage goal

6. 🔍 Validates Quality

   • Document structure validation
   • Requirement coverage checks
   • Test suite completeness
   • UI accessibility validation
   • Comprehensive logging throughout

📁 Project Structure

When you use SpecDriven Agent, it creates this structure:

.specify/
├── memory/
│   └── constitution.md       # Project principles and guidelines
├── specs/
│   ├── 001-feature-name/
│   │   ├── spec.md           # Feature specification
│   │   ├── plan.md           # Implementation plan
│   │   ├── tasks.md          # Task breakdown
│   │   ├── research.md       # Technical research (if needed)
│   │   ├── data-model.md     # Data models (if applicable)
│   │   ├── quickstart.md     # Validation scenarios
│   │   └── contracts/        # API contracts (if applicable)
│   └── 002-another-feature/
│       └── ...
└── templates/                # Built-in templates (from extension)

🎯 Core Philosophy

SpecDriven Agent implements Spec-Driven Development (SDD), which emphasizes:

• Intent-driven development: Specifications define the "what" before the "how"
• Rich specification creation: Using structured templates and guidelines
• Multi-step refinement: Rather than one-shot code generation
• Local-first approach: All data stored in your workspace

💡 Usage Tips

Working with Git

SpecDriven Agent automatically creates feature branches when you use /specify:

• Branch naming: 001-feature-name, 002-another-feature, etc.
• Switch branches to work on different features
• The active branch determines which feature you're working on

Non-Git Workflows

Without Git, SpecDriven Agent tracks features by directory:

• Set SPECIFY_FEATURE environment variable to specify active feature
• Or work with the most recently created feature

Best Practices

1. Start with Constitution: Define your project principles first
2. Focus on What, Not How: In specifications, describe requirements without implementation details
3. Iterate Specifications: Use /clarify to refine before moving to implementation
4. Follow the Workflow: Constitution → Specify → Plan → Tasks → Implement
5. Review Generated Documents: Templates provide structure, but review and customize

🔧 Development

Building from Source

npm install
npm run compile

Running in Development

1. Press F5 to open Extension Development Host
2. Open a folder in the new window
3. Open Copilot Chat and use @specdriven commands

Project Structure

src/
├── extension.ts              # Main extension entry point
├── managers/
│   └── SpecifyManager.ts     # File and directory management
└── commands/
    ├── ConstitutionCommand.ts
    ├── SpecifyCommand.ts
    ├── PlanCommand.ts
    ├── TasksCommand.ts
    ├── ImplementCommand.ts
    └── UtilityCommands.ts

📝 License

MIT License - See LICENSE file for details

🙏 Acknowledgements

This project is inspired by and based on github/spec-kit - an open source toolkit for spec-driven development.

Key differences from original spec-kit:

• VS Code extension instead of CLI tool
• GitHub Copilot chat participant integration
• Simplified workflow focused on VS Code users
• No external dependencies or cloud services

🤝 Contributing

Contributions are welcome! Please feel free to submit issues or pull requests.

📧 Support

For issues and questions:

• GitHub Issues: [Your Repository URL]
• VS Code Extension Marketplace: [Extension URL]

Built with ❤️ for spec-driven development