agentspec 2.1.1

Specification-driven development toolkit with smart context detection

AgentSpec

Transform AI Code Generation with Professional Instructions

AgentSpec creates comprehensive instruction guides that transform AI coding assistants (GitHub Copilot, ChatGPT, Claude) from basic code generators into professional development partners. Get production-ready code that follows industry best practices, security standards, and your specific project requirements.

🚀 Quick Start

# Install AgentSpec
pip install agentspec

# Enable shell completion (optional but recommended)
agentspec --install-completion

# Generate instructions for a React app
agentspec generate --template react_app --output react-instructions.md

# Generate instructions for a Python API
agentspec generate --template python-api --output api-instructions.md

# Let AgentSpec analyze your existing project
agentspec analyze ./my-project

# Interactive wizard to guide you through the process
agentspec interactive

What you get: A comprehensive instruction file that transforms your AI assistant into a professional development partner, ensuring consistent, high-quality code generation.

✨ What AgentSpec Does

• 📋 Smart Instructions: 106 proven coding guidelines organized by technology and domain
• 🎯 Ready-Made Templates: 15 project templates for common scenarios (React apps, Python APIs, etc.)
• 🔍 Project Analysis: Automatically detects your tech stack and suggests relevant instructions
• 🤖 AI-Friendly Format: Instructions designed specifically for AI coding assistants
• 🔒 Security Built-In: Includes security best practices and vulnerability prevention
• ✅ Quality Focused: Ensures AI generates professional-grade, tested code

🎯 How It Works

1. Choose Your Project Type

Pick from 15 templates like "React App", "Python API", "E-commerce Site", etc.

2. Get Custom Instructions

AgentSpec generates a detailed instruction file tailored to your project.

3. Share with AI

Give the instructions to your AI coding assistant (ChatGPT, Copilot, Claude, etc.).

4. Get Better Code

Your AI now follows professional standards and best practices automatically.

📋 Available Templates

AgentSpec includes 15 ready-to-use templates:

Technology Templates:

• react_app - React web applications with TypeScript
• python-api - Python REST APIs with FastAPI
• nodejs-api - Node.js APIs with Express
• vue-frontend - Vue.js applications
• mobile-app - Cross-platform mobile apps

Domain Templates:

• saas-application - SaaS platforms with billing
• ecommerce-application - Online stores and marketplaces
• fintech-application - Financial applications
• healthcare-application - Healthcare platforms
• data-science-application - ML and analytics platforms

Architecture Templates:

• web-application - General web applications
• enterprise-web-application - Large-scale enterprise apps
• microservice - Microservice architectures

Methodology Templates:

• ai-assisted-development - AI-first development practices
• security-focused-development - Security-critical applications

🛠️ Usage Examples

For New Projects

# React web application
agentspec generate --template react_app --output react-instructions.md

# Python REST API
agentspec generate --template python-api --output api-instructions.md

# E-commerce platform
agentspec generate --template ecommerce-application --output ecommerce-instructions.md

# SaaS application
agentspec generate --template saas-application --output saas-instructions.md

For Existing Projects

# Let AgentSpec analyze your project and suggest instructions
agentspec analyze ./my-project

# Generate instructions based on detected technologies
agentspec generate --project-path ./my-project --tags auto --output project-instructions.md

Interactive Mode

# Guided setup with questions and recommendations
agentspec interactive

Browse Available Options

# See all templates
agentspec list-templates

# See all instruction categories
agentspec list-tags

# See specific instructions
agentspec list-instructions --tag testing

💡 Real Example

Without AgentSpec:

You: "Create a React login form"
AI: Creates basic form with no validation, security issues, no tests

With AgentSpec:

You: "Create a React login form" + AgentSpec instructions
AI: Creates form with:
- Input validation and error handling
- Security best practices (CSRF protection, etc.)
- Accessibility features (ARIA labels, keyboard navigation)
- Comprehensive tests (unit, integration, accessibility)
- TypeScript types and proper documentation
- Performance optimization and loading states

The difference: Production-ready code that follows industry best practices.

📚 Documentation

New to AgentSpec?

• What is AgentSpec? - Simple explanation for beginners
• Quick Start Guide - Get running in 5 minutes
• Your First Project - Complete step-by-step tutorial

Reference & Guides:

• Core Concepts - Understanding instructions, templates, and specs
• Command Line Guide - Complete CLI reference with completion
• Shell Completion Setup - Shell completion installation guide
• Working with Templates - Using and customizing templates

Advanced:

• Instructions Reference - All available instructions
• Templates Reference - All available templates
• Completion Customization - Advanced completion configuration
• API Documentation - Python API for advanced usage
• Examples - Real-world project examples

🏷️ Available Templates & Tags

Templates by Category

Technology Templates:

• react_app - React applications with TypeScript
• python-api - Python REST APIs with FastAPI
• nodejs-api - Node.js APIs with Express
• vue-frontend - Vue.js applications
• mobile-app - Cross-platform mobile apps

Domain Templates:

• saas-application - SaaS platforms with billing
• ecommerce-application - E-commerce platforms
• fintech-application - Financial applications
• healthcare-application - Healthcare platforms
• data-science-application - ML and data platforms

Architecture Templates:

• web-application - General web applications
• enterprise-web-application - Enterprise-scale apps
• microservice - Microservice architectures

Methodology Templates:

• ai-assisted-development - AI-first development
• security-focused-development - Security-critical apps

Instruction Categories

Core Instructions (Always Included):

• core - Fundamental development practices (25 instructions)
• workflow - Development workflow and process (included in core)

Specialized Instructions:

• frontend - Frontend development (12 instructions)
• backend - Backend development (15 instructions)
• testing - Testing strategies (9 instructions)
• security - Security practices (distributed across categories)
• performance - Performance optimization (distributed across categories)

Technology-Specific:

• python, javascript, typescript - Language-specific guidelines
• react, vue, angular - Framework-specific practices
• api, database, docker - Technology-specific instructions

🔧 Who Should Use AgentSpec?

Perfect for:

• Developers using AI assistants (GitHub Copilot, ChatGPT, Claude, etc.)
• Teams who want consistent coding standards
• Beginners learning best practices
• Experienced developers scaling their knowledge

Especially useful if you:

• Want AI to generate professional-grade code, not just examples
• Need to ensure security and quality in AI-generated code
• Want consistent standards across projects and team members
• Are building production applications with AI assistance

🚀 Getting Started

For Complete Beginners

Never used AgentSpec before?

1. Learn what it does: Read What is AgentSpec?
2. Try it out: Follow the Quick Start Guide (5 minutes)
3. Build something: Complete Your First Project tutorial

For Experienced Developers

Ready to jump in?

1. Install: pip install agentspec
2. Generate instructions: agentspec generate --template react_app --output instructions.md
3. Share with AI: Copy instructions.md content to your AI assistant
4. Start coding: Ask AI to build features following the instructions

Need Help Choosing?

• Interactive setup: agentspec interactive for guided template selection
• Project analysis: agentspec analyze . to analyze existing projects
• Browse templates: agentspec list-templates to see all options
• Get recommendations: Check the Templates Guide

🔧 Troubleshooting

Common issues and solutions:

Installation problems:

# If pip install fails, try:
pip install --upgrade pip
pip install agentspec

# For Python 3.8 compatibility issues:
pip install "agentspec[dev]" --no-deps

Command not found:

# Make sure AgentSpec is in your PATH
which agentspec

# Or run as module:
python -m agentspec --version

Template not working:

# List available templates:
agentspec list-templates

# Use exact template ID:
agentspec generate --template react_app --output instructions.md

Shell completion not working:

# Install completion for your shell
agentspec --install-completion

# Or show completion script for manual setup
agentspec --show-completion

# Check completion status
agentspec --completion-status

Need more help? Check our GitHub Discussions

🤝 Contributing

We welcome contributions! See CONTRIBUTING.md for guidelines.

# Quick development setup
git clone https://github.com/keyurgolani/AgentSpec.git
cd AgentSpec
pip install -e ".[dev]"
pytest

📄 License

MIT License - see LICENSE for details.

🌟 Why AgentSpec Works

• Proven Instructions: Based on industry best practices and real-world experience
• AI-Optimized: Instructions written specifically for AI understanding
• Comprehensive: Covers security, testing, performance, accessibility, and more
• Flexible: Works with any AI assistant and any project type
• Time-Saving: Get professional code faster than writing detailed prompts every time

🚀 Quick Links

New to AgentSpec?

• What is AgentSpec? - Simple explanation
• Quick Start - Get running in 5 minutes
• Your First Project - Complete tutorial

Ready to use?

• Examples - Real-world project examples
• Command Reference - All CLI commands
• Templates - Browse all templates

---

Get better AI code with AgentSpec - professional instructions for professional results.