My Spec Kit 🌱🤖

A personal wrapper application for GitHub's spec-kit toolkit that enables custom spec-driven development workflows enhanced with AI-powered specification generation.

🚀 Overview

My Spec Kit provides a TypeScript-based interface to GitHub's spec-kit, allowing you to create, manage, and use personalized specification templates and workflows. It's designed to streamline your spec-driven development process with customizable templates, multiple configuration profiles, AI-powered generation, and an intuitive command-line interface.

Key Features

🤖 AI-Powered Generation: Generate comprehensive specifications using Azure OpenAI GPT-4
📝 Custom Templates: Create and manage your own specification templates with AI prompt engineering
👤 Multiple Profiles: Switch between different configuration profiles for different projects
🔧 TypeScript Support: Built with TypeScript for type safety and better developer experience
🎯 Interactive CLI: User-friendly command-line interface with interactive prompts and AI feedback
⚙️ Flexible Configuration: Highly customizable settings, workflows, and AI agent configurations
🔄 Spec-Kit Integration: Seamless integration with GitHub's spec-kit toolkit
📊 Usage Tracking: Monitor AI usage, costs, and token consumption
🔒 Secure by Design: Safe handling of AI credentials and generated content

📦 Installation

Prerequisites

Node.js 18 or higher
npm or yarn
Git
Azure OpenAI service (optional, for AI-powered generation)
GitHub spec-kit toolkit (for core spec generation)

Option 1: Install from Source

# Clone the repository
git clone https://github.com/lukeus/my-spec-kit.git
cd my-spec-kit

# Install dependencies
npm install

# Build the project
npm run build

# Install globally (optional)
npm install -g .

Option 2: Local Development Setup

# Clone and setup
git clone https://github.com/lukeus/my-spec-kit.git
cd my-spec-kit
npm install
npm run build

# Use with npx
npx my-spec-kit --help

🎯 Quick Start

1. Initialize Your Configuration

# Interactive initialization
my-spec-kit init

# Or with parameters
my-spec-kit init --name "My Project Kit" --description "Custom spec kit for my project"

2. Configure AI (Optional)

# Configure Azure OpenAI for AI-powered generation
my-spec-kit ai configure --provider azure-openai

# Check AI service status
my-spec-kit ai status

3. Generate Your First Specification

# AI-powered generation (requires configured AI agent)
my-spec-kit ai generate --template api-spec --context auto

# Traditional template-based generation
my-spec-kit generate basic-feature --interactive

# Quick generation with defaults
my-spec-kit generate basic-feature --output ./my-feature-spec.md

4. Explore Available Commands

# Show current configuration
my-spec-kit config

# List available templates
my-spec-kit list

# View AI usage statistics
my-spec-kit ai usage

# Get help
my-spec-kit --help

📚 Usage Guide

Command Reference

Core Commands

my-spec-kit init - Initialize a new spec-kit configuration
my-spec-kit generate <template-id> - Generate a specification using a template
my-spec-kit config - Show current configuration
my-spec-kit doctor - Run system diagnostics and health checks
my-spec-kit --help - Display help information

AI Commands

my-spec-kit ai configure - Configure AI agents (Azure OpenAI, etc.)
my-spec-kit ai generate - Generate specifications using AI
my-spec-kit ai status - Check AI service health and availability
my-spec-kit ai usage - View AI usage statistics and costs

Template Management

my-spec-kit list - List all available templates
my-spec-kit list --category feature - Filter templates by category

Profile Management

my-spec-kit profile create <name> - Create a new profile
my-spec-kit profile list - List all profiles
my-spec-kit profile switch <profile-id> - Switch to a different profile

Templates

My Spec Kit comes with a default template and supports custom templates:

Default Template: Basic Feature Spec

ID: basic-feature
Category: feature
Variables:
- featureName (required): Name of the feature
- description (required): Feature description
- priority (optional): Priority level (low, medium, high, critical)

Creating Custom Templates

Templates are stored in your configuration and can include:

Variables: Define required and optional input variables
Validation: Set validation rules for variables
Output Format: Markdown, YAML, or JSON
Categories: Organize templates by category

Configuration Profiles

Profiles allow you to maintain different configurations for different projects:

# Create a work profile
my-spec-kit profile create "Work Projects" -d "Configuration for work-related projects"

# Create a personal profile
my-spec-kit profile create "Personal" -d "Configuration for personal projects"

# Switch between profiles
my-spec-kit profile switch <profile-id>

🏗️ Project Structure

my-spec-kit/
├── src/
│   ├── cli/                          # Command-line interface
│   │   └── cli.ts                   # Main CLI implementation with AI commands
│   ├── config/                       # Configuration management
│   │   └── ConfigManager.ts         # Profile, config, and AI agent handling
│   ├── lib/                          # Core library
│   │   ├── SpecKitWrapper.ts        # Main wrapper class
│   │   ├── AIAgentManager.ts        # AI agent orchestration
│   │   ├── AzureOpenAIService.ts    # Azure OpenAI integration
│   │   ├── PromptEngine.ts          # AI prompt template management
│   │   ├── ascii-art.ts             # CLI branding and visuals
│   │   └── EnvironmentValidator.ts  # System requirements validation
│   ├── types/                        # TypeScript type definitions
│   │   └── index.ts                 # Shared types and interfaces
│   └── index.ts                     # Main entry point
├── dist/                             # Compiled JavaScript output
├── tests/                            # Comprehensive test suite
│   ├── unit/                         # Unit tests (100% coverage)
│   └── integration/                  # End-to-end CLI tests
├── templates/                        # Template files
├── .specify/memory/                  # Project constitution and memory
├── examples/                         # Usage examples
├── docs/                             # Documentation
└── WARP.md                          # Development guidelines and AI rules

🔧 Development

Scripts

# Build the project
npm run build

# Development mode with watch
npm run dev

# Run comprehensive test suite (100% coverage)
npm run test

# Run tests in watch mode
npm run test:watch

# Generate test coverage report
npm run test:coverage

# Lint code
npm run lint

# Format code
npm run format

# Clean build directory
npm run clean

# Run system diagnostics
npm run doctor

Contributing

Fork the repository
Create a feature branch: git checkout -b feature/new-feature
Make your changes and add tests
Run linting: npm run lint
Format code: npm run format
Build and test: npm run build && npm run test
Commit your changes: git commit -m 'Add new feature'
Push to the branch: git push origin feature/new-feature
Submit a pull request

Code Quality

This project maintains high standards with:

ESLint: For code linting and style enforcement
Prettier: For consistent code formatting
TypeScript: Strict mode for type safety and better development experience
Jest: Comprehensive testing with 100% coverage requirement
Constitutional Governance: Development guided by .specify/memory/constitution.md
AI Service Testing: Specialized mocking strategies for AI integrations
Integration Testing: End-to-end CLI workflow validation

📄 Configuration

Configuration File Structure

version: "1.0.0"
name: "My Spec Kit"
description: "Personal spec-kit configuration"
author: "your-username"

templates:
  - id: "basic-feature"
    name: "Basic Feature Spec"
    description: "A basic template for feature specifications"
    category: "feature"
    templatePath: "./templates/feature-spec.md"
    outputFormat: "markdown"
    variables:
      - name: "featureName"
        type: "string"
        required: true
      # ... more variables

agents:
  - id: "azure-openai-prod"
    name: "Azure OpenAI Production"
    type: "azure-openai"
    enabled: true
    settings:
      endpoint: "https://your-resource.openai.azure.com/"
      deploymentName: "gpt-4"
      apiVersion: "2024-02-15-preview"
      maxTokens: 2000
      temperature: 0.7
  - id: "github-copilot"
    name: "GitHub Copilot"
    type: "github-copilot"
    enabled: false

workflows: []

settings:
  outputDirectory: "./specs"
  autoSave: true
  validation:
    enabled: true
    strict: false
  integrations:
    git: true
    github: true
    vscode: true

Environment Variables

SPEC_KIT_PATH: Path to the spec-kit CLI (defaults to 'specify')
MY_SPEC_KIT_CONFIG: Custom configuration file path
AZURE_OPENAI_ENDPOINT: Azure OpenAI service endpoint URL
AZURE_OPENAI_API_KEY: Azure OpenAI API key (secure credential)
DEBUG: Enable verbose logging (e.g., DEBUG=my-spec-kit:*)

🤝 Integration with GitHub Spec-Kit

This wrapper is designed to work seamlessly with GitHub's spec-kit. Make sure you have spec-kit installed and available in your PATH:

# Install spec-kit (example - check official docs for latest instructions)
curl -sSL https://github.com/github/spec-kit/releases/latest/download/install.sh | sh

📋 Roadmap

Completed ✅

AI Integration: Azure OpenAI GPT-4 powered specification generation
Comprehensive Testing: 100% test coverage with robust mocking
Type Safety: Strict TypeScript implementation
CLI Enhancement: Beautiful ASCII art and user experience
Constitutional Governance: Development standards and principles

Planned 🗺️

Multi-Provider AI: OpenAI, Anthropic Claude integration
Template Marketplace: Share and discover templates
Workflow Automation: Advanced workflow support with AI triggers
Integration Plugins: VS Code, GitHub Actions
Cloud Sync: Sync configurations across devices
Team Collaboration: Shared team configurations with AI usage policies
Advanced Analytics: Usage analytics, cost optimization, and insights
Streaming Generation: Real-time AI response streaming

🐛 Troubleshooting

Common Issues

Command not found: Ensure the package is installed globally or use npx
Permission errors: Check file permissions in your configuration directory
Template not found: Verify template ID and configuration
Spec-kit integration: Ensure spec-kit is installed and in PATH
AI service unavailable: Check Azure OpenAI credentials and endpoint configuration
AI generation fails: Verify API key permissions and usage quotas
High AI costs: Review usage with my-spec-kit ai usage and configure cost limits

Debug Mode

Enable verbose logging by setting the environment variable:

DEBUG=my-spec-kit:* my-spec-kit <command>

📊 Development Investment

Based on the complexity and features implemented:

Phase 1: Core Implementation (Completed)

Initial Development: ~45 hours
AI Integration: ~25 hours
Testing & Documentation: ~20 hours
Polish & Refinement: ~15 hours
Total Phase 1: ~105 hours

This includes TypeScript setup, CLI implementation, configuration management, AI integration with Azure OpenAI, comprehensive testing (100% coverage), error handling, and extensive documentation.

Phase 2: Advanced Features (Planned)

Multi-Provider AI Support: ~20 hours
Advanced Workflows: ~15 hours
Integration Plugins: ~25 hours
Estimated Phase 2: ~60 hours

📜 License

MIT License - see LICENSE file for details.

🙏 Acknowledgments

GitHub Spec-Kit - The underlying toolkit this project wraps
Azure OpenAI Service - AI-powered specification generation
Commander.js - Command-line interface framework
Inquirer.js - Interactive command-line user interfaces
Jest - Comprehensive testing framework with excellent TypeScript support
Chalk - Terminal colors and styling
Zod - TypeScript-first schema validation

📞 Support

🐛 Report Issues
💬 Discussions

Built with ❤️ and 🤖 for AI-enhanced spec-driven development

Name		Name	Last commit message	Last commit date
Latest commit History 16 Commits
.github		.github
.specify		.specify
custom-specs		custom-specs
dev-specs		dev-specs
docs		docs
examples		examples
scripts		scripts
src		src
tests		tests
.eslintrc.js		.eslintrc.js
.gitignore		.gitignore
.prettierignore		.prettierignore
.prettierrc.js		.prettierrc.js
CHANGELOG.md		CHANGELOG.md
README.md		README.md
SECURITY.md		SECURITY.md
SUPPORT.md		SUPPORT.md
WARP.md		WARP.md
audit-ci.jsonc		audit-ci.jsonc
jest.config.js		jest.config.js
package-lock.json		package-lock.json
package.json		package.json
tsconfig.json		tsconfig.json

Lukeus/my-spec-kit

Folders and files

Latest commit

History

Repository files navigation