SpecDriven Agent - VS Code Extension

A local spec-driven development toolkit integrated with GitHub Copilot as a chat participant. Build high-quality software faster with fully autonomous AI-driven implementation that reads specifications and writes production-ready code.

🌟 Features

• 🤖 Autonomous AI Implementation: AI agent reads specs and autonomously generates complete, production-ready code
• Local Storage Only: All specification documents stored in .specify folder - no cloud storage
• GitHub Copilot Integration: Works as a chat participant with slash commands
• Spec-Driven Workflow: Structured approach from requirements to implementation
• Git-Aware: Automatically creates feature branches and tracks work
• Template-Based: Consistent documentation structure across features
• AI-Driven Actions: Agent autonomously creates files, runs commands, and drives implementation

📋 Commands

Core Workflow

1. @specdriven /constitution - Define project principles and development guidelines
2. @specdriven /specify - Create feature specifications from natural language descriptions
3. @specdriven /plan - Generate technical implementation plans with your tech stack
4. @specdriven /tasks - Break down features into actionable task lists
5. @specdriven /implement - 🤖 AUTONOMOUS AI AGENT - Analyzes all documents, makes decisions, and generates production-ready code automatically

Additional Commands

• @specdriven /clarify - Refine ambiguous or underspecified requirements
• @specdriven /analyze - Validate consistency across specification documents
• @specdriven /checklist - Generate quality validation checklists
• @specdriven /tests - 🧪 AI generates comprehensive test suite (unit, integration, E2E, UI tests)
• @specdriven /validate - 🔍 AI validates project structure, docs, and implementation quality

Natural Language Support

The agent now understands natural language! You can say:

• "create all files" - Agent creates all generated files in your workspace
• "show me the login code" - Agent displays specific code
• "implement task T001" - Agent reads specs and generates code for that task
• "build the payment feature" - Agent autonomously implements based on specs

🚀 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 - Autonomous AI Implementation

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