Code My Spec - VSCode Extension

Process-Guided AI Development for Phoenix Applications

Code My Spec is a VSCode extension that connects to the Code My Spec platform to help development teams build Phoenix/LiveView applications through structured, test-driven workflows. Instead of letting AI agents generate sprawling specifications that compound errors across layers, Code My Spec enforces tight architectural boundaries and human oversight at critical decision points.

Core Philosophy

Stop letting LLMs design your architecture. The best way to use AI for software development is to strictly define your process in procedural code, then guide AI agents through it step-by-step. Code My Spec provides the scaffolding—user stories, component boundaries, dependency tracking, and test workflows—while Claude Code handles generation tasks within those constraints.

The result: high-quality, traceable implementations where design errors are caught early, not compounded across layers of AI-generated slop.

Features

🎯 Structured Development Process

• User Story Management: Define requirements that drive behavior, not bloated specifications
• Component Architecture: Phoenix contexts, schemas, LiveViews with explicit type classification and dependency tracking
• Session Orchestration: Guided workflows for component design and test generation with approval gates
• Test-Driven Development: Generate tests from designs, implement to pass tests, maintain traceability

🔗 Seamless Integration

• OAuth2 Authentication: Secure connection to Code My Spec platform (local, staging, or production)
• Project Synchronization: Sync file lists, test results, and component status with backend
• Session Execution: Run Claude Code commands directly from VSCode with automatic pipe handling
• Real-Time Status: View component requirements, implementation status, and test results in sidebar

🤖 AI-Assisted Without AI-Driven

• MCP Server Integration: Expose Stories and Components APIs to Claude Code via Hermes MCP
• Structured Prompts: Heavy specification work creates "fly ass prompts" with minimal wiggle room
• Human Oversight: Approve designs before test generation; review tests before implementation
• Fail-Fast Feedback: Test results analyzed by Project Coordinator to recommend next actions

Installation

1. Install the Extension (when published to marketplace):

   code --install-extension myspec.code-my-spec
   

2. Configure Server URL:

   • Open VSCode settings (Cmd+, on macOS)
   • Search for "Code My Spec"
   • Select server environment:
     • http://localhost:4000 - Local development
     • https://staging.codemyspec.com - Staging
     • https://api.codemyspec.com - Production

3. Authenticate:

   • Click "Login to Code My Spec" in the sidebar
   • Complete OAuth2 flow in browser
   • Extension will automatically connect on startup

Requirements

• VSCode: Version 1.101.0 or higher
• Code My Spec Account: Sign up at codemyspec.com
• Phoenix Project: Elixir/Phoenix application with ExUnit tests
• Claude Code (optional): For AI-assisted design and test generation via MCP

Extension Commands

Access via Command Palette (Cmd+Shift+P on macOS):

• Login to Code My Spec - Authenticate with OAuth2
• Logout from Code My Spec - Revoke authentication token
• Refresh Project - Sync file list and test results with server
• Sync Project - Full sync with persistence to backend
• Start Session - Begin component design or test generation workflow
• Open Session View - View active session details and execute commands

Usage

1. Define User Stories

Use the Code My Spec web UI to create user stories that define application behavior. Stories drive component requirements.

2. Design Components

In VSCode sidebar, view components requiring design:

• Click component → Start Session → Generate design with Claude Code
• Review design in session view
• Approve to proceed to test generation

3. Generate Tests

After design approval:

• Session automatically advances to test generation
• Claude Code generates ExUnit tests based on design
• Execute commands in VSCode terminal
• Tests added to project, tracked by extension

4. Implement to Pass Tests

Run mix test to see failures:

• Project Coordinator analyzes results
• Recommends next components to implement
• Repeat cycle: design → test → implement

5. Maintain Traceability

All artifacts linked:

• Stories → Components → Sessions → Tests → Implementation
• Regenerate application from documentation if needed
• Change languages/frameworks while preserving design

Architecture

VSCode Extension Components

• AuthenticationProvider: OAuth2 client for secure server communication
• ProjectCoordinator: Orchestrates file sync, test execution, and recommendations
• SessionProvider: Manages active design/test generation sessions
• CommandProcessor: Handles pipe content for complex Claude Code commands
• CodeMySpecClient: HTTP client for platform API (stories, components, sessions)

Platform Integration

• MCP Servers: Expose Stories and Components tools to Claude Code/Desktop
• Session Orchestration: Backend manages workflow state and step progression
• Project Coordinator API: Analyzes component status against filesystem and test results
• Content Sync: Git-based management of markdown/HTML/HEEx files with frontmatter

Extension Settings

This extension contributes the following settings:

• codeMySpec.serverUrl: Code My Spec server URL
  • http://localhost:4000 - Local development server
  • https://staging.codemyspec.com - Staging environment
  • https://api.codemyspec.com - Production environment

Development

Build and Run

# Install dependencies
yarn install

# Compile TypeScript
yarn compile

# Watch for changes
yarn watch

# Run tests
yarn test

# Package extension
yarn package

Testing

# Unit tests only
yarn test:unit

# Full extension tests
yarn test:extension

Technology Stack

• TypeScript - Type-safe extension code
• VSCode Extension API - TreeViews, commands, authentication
• OAuth2 - Secure authentication with Code My Spec platform
• Esbuild - Fast compilation and bundling

Known Issues

• Session command execution requires Claude Code installation for full workflow
• Pipe content handling limited to Unix-like systems (uses cat)
• Test result parsing assumes ExUnit JSON formatter

Contributing

This extension is part of the Code My Spec platform. For issues, feature requests, or contributions, visit the main project repository or contact support.

License

UNLICENSED - Private extension for Code My Spec platform

The point isn't to hand off your idea to an LLM. The point is to guide the LLM through a rigorous process that produces artifacts you can trust.