# AgentSpec
[](https://github.com/keyurgolani/AgentSpec/actions)
[](https://codecov.io/gh/keyurgolani/AgentSpec)
[](https://badge.fury.io/py/agentspec)
[](https://www.python.org/downloads/)
**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
```bash
# Install AgentSpec
pip install agentspec
# 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
```bash
# 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
```bash
# 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
```bash
# Guided setup with questions and recommendations
agentspec interactive
```
### Browse Available Options
```bash
# 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?](docs/what-is-agentspec.md)** - Simple explanation for beginners
- **[Quick Start Guide](docs/quick-start.md)** - Get running in 5 minutes
- **[Your First Project](docs/your-first-project.md)** - Complete step-by-step tutorial
**Reference & Guides:**
- **[Core Concepts](docs/core-concepts.md)** - Understanding instructions, templates, and specs
- **[Command Line Guide](docs/command-line-guide.md)** - Complete CLI reference
- **[Working with Templates](docs/working-with-templates.md)** - Using and customizing templates
**Advanced:**
- **[Instructions Reference](docs/instructions-reference.md)** - All available instructions
- **[Templates Reference](docs/templates-reference.md)** - All available templates
- **[API Documentation](docs/api-reference.md)** - Python API for advanced usage
- **[Examples](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?](docs/what-is-agentspec.md)
2. **Try it out:** Follow the [Quick Start Guide](docs/quick-start.md) (5 minutes)
3. **Build something:** Complete [Your First Project](docs/your-first-project.md) 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](docs/working-with-templates.md)
## 🔧 Troubleshooting
**Common issues and solutions:**
**Installation problems:**
```bash
# 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:**
```bash
# Make sure AgentSpec is in your PATH
which agentspec
# Or run as module:
python -m agentspec --version
```
**Template not working:**
```bash
# List available templates:
agentspec list-templates
# Use exact template ID:
agentspec generate --template react_app --output instructions.md
```
**Need more help?** Check our [GitHub Discussions](https://github.com/keyurgolani/AgentSpec/discussions)
## 🤝 Contributing
We welcome contributions! See [CONTRIBUTING.md](CONTRIBUTING.md) for guidelines.
```bash
# Quick development setup
git clone https://github.com/keyurgolani/AgentSpec.git
cd AgentSpec
pip install -e ".[dev]"
pytest
```
## 📄 License
MIT License - see [LICENSE](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?](docs/what-is-agentspec.md)** - Simple explanation
- **[Quick Start](docs/quick-start.md)** - Get running in 5 minutes
- **[Your First Project](docs/your-first-project.md)** - Complete tutorial
**Ready to use?**
- **[Examples](examples/)** - Real-world project examples
- **[Command Reference](docs/command-line-guide.md)** - All CLI commands
- **[Templates](docs/templates-reference.md)** - Browse all templates
---
**Get better AI code with AgentSpec - professional instructions for professional results.**
Raw data
{
"_id": null,
"home_page": null,
"name": "agentspec",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.8",
"maintainer_email": null,
"keywords": "specification, development, automation, templates, cli",
"author": null,
"author_email": "Keyur Golani <keyur@keyurgolani.com>",
"download_url": "https://files.pythonhosted.org/packages/5b/49/55d100ed743fa360fafcf97dee1913ba0d3322da96e903fa5adcc1209b30/agentspec-2.0.1.tar.gz",
"platform": null,
"description": "# AgentSpec\n\n[](https://github.com/keyurgolani/AgentSpec/actions)\n[](https://codecov.io/gh/keyurgolani/AgentSpec)\n[](https://badge.fury.io/py/agentspec)\n[](https://www.python.org/downloads/)\n\n**Transform AI Code Generation with Professional Instructions**\n\nAgentSpec 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.\n\n## \ud83d\ude80 Quick Start\n\n```bash\n# Install AgentSpec\npip install agentspec\n\n# Generate instructions for a React app\nagentspec generate --template react_app --output react-instructions.md\n\n# Generate instructions for a Python API\nagentspec generate --template python-api --output api-instructions.md\n\n# Let AgentSpec analyze your existing project\nagentspec analyze ./my-project\n\n# Interactive wizard to guide you through the process\nagentspec interactive\n```\n\n**What you get:** A comprehensive instruction file that transforms your AI assistant into a professional development partner, ensuring consistent, high-quality code generation.\n\n## \u2728 What AgentSpec Does\n\n- **\ud83d\udccb Smart Instructions**: 106 proven coding guidelines organized by technology and domain\n- **\ud83c\udfaf Ready-Made Templates**: 15 project templates for common scenarios (React apps, Python APIs, etc.)\n- **\ud83d\udd0d Project Analysis**: Automatically detects your tech stack and suggests relevant instructions\n- **\ud83e\udd16 AI-Friendly Format**: Instructions designed specifically for AI coding assistants\n- **\ud83d\udd12 Security Built-In**: Includes security best practices and vulnerability prevention\n- **\u2705 Quality Focused**: Ensures AI generates professional-grade, tested code\n\n## \ud83c\udfaf How It Works\n\n### 1. Choose Your Project Type\nPick from 15 templates like \"React App\", \"Python API\", \"E-commerce Site\", etc.\n\n### 2. Get Custom Instructions\nAgentSpec generates a detailed instruction file tailored to your project.\n\n### 3. Share with AI\nGive the instructions to your AI coding assistant (ChatGPT, Copilot, Claude, etc.).\n\n### 4. Get Better Code\nYour AI now follows professional standards and best practices automatically.\n\n## \ud83d\udccb Available Templates\n\nAgentSpec includes 15 ready-to-use templates:\n\n**Technology Templates:**\n- `react_app` - React web applications with TypeScript\n- `python-api` - Python REST APIs with FastAPI\n- `nodejs-api` - Node.js APIs with Express\n- `vue-frontend` - Vue.js applications\n- `mobile-app` - Cross-platform mobile apps\n\n**Domain Templates:**\n- `saas-application` - SaaS platforms with billing\n- `ecommerce-application` - Online stores and marketplaces\n- `fintech-application` - Financial applications\n- `healthcare-application` - Healthcare platforms\n- `data-science-application` - ML and analytics platforms\n\n**Architecture Templates:**\n- `web-application` - General web applications\n- `enterprise-web-application` - Large-scale enterprise apps\n- `microservice` - Microservice architectures\n\n**Methodology Templates:**\n- `ai-assisted-development` - AI-first development practices\n- `security-focused-development` - Security-critical applications\n\n## \ud83d\udee0\ufe0f Usage Examples\n\n### For New Projects\n\n```bash\n# React web application\nagentspec generate --template react_app --output react-instructions.md\n\n# Python REST API\nagentspec generate --template python-api --output api-instructions.md\n\n# E-commerce platform\nagentspec generate --template ecommerce-application --output ecommerce-instructions.md\n\n# SaaS application\nagentspec generate --template saas-application --output saas-instructions.md\n```\n\n### For Existing Projects\n\n```bash\n# Let AgentSpec analyze your project and suggest instructions\nagentspec analyze ./my-project\n\n# Generate instructions based on detected technologies\nagentspec generate --project-path ./my-project --tags auto --output project-instructions.md\n```\n\n### Interactive Mode\n\n```bash\n# Guided setup with questions and recommendations\nagentspec interactive\n```\n\n### Browse Available Options\n\n```bash\n# See all templates\nagentspec list-templates\n\n# See all instruction categories\nagentspec list-tags\n\n# See specific instructions\nagentspec list-instructions --tag testing\n```\n\n## \ud83d\udca1 Real Example\n\n**Without AgentSpec:**\n```\nYou: \"Create a React login form\"\nAI: Creates basic form with no validation, security issues, no tests\n```\n\n**With AgentSpec:**\n```\nYou: \"Create a React login form\" + AgentSpec instructions\nAI: Creates form with:\n- Input validation and error handling\n- Security best practices (CSRF protection, etc.)\n- Accessibility features (ARIA labels, keyboard navigation)\n- Comprehensive tests (unit, integration, accessibility)\n- TypeScript types and proper documentation\n- Performance optimization and loading states\n```\n\nThe difference: **Production-ready code that follows industry best practices.**\n\n## \ud83d\udcda Documentation\n\n**New to AgentSpec?**\n- **[What is AgentSpec?](docs/what-is-agentspec.md)** - Simple explanation for beginners\n- **[Quick Start Guide](docs/quick-start.md)** - Get running in 5 minutes\n- **[Your First Project](docs/your-first-project.md)** - Complete step-by-step tutorial\n\n**Reference & Guides:**\n- **[Core Concepts](docs/core-concepts.md)** - Understanding instructions, templates, and specs\n- **[Command Line Guide](docs/command-line-guide.md)** - Complete CLI reference\n- **[Working with Templates](docs/working-with-templates.md)** - Using and customizing templates\n\n**Advanced:**\n- **[Instructions Reference](docs/instructions-reference.md)** - All available instructions\n- **[Templates Reference](docs/templates-reference.md)** - All available templates\n- **[API Documentation](docs/api-reference.md)** - Python API for advanced usage\n- **[Examples](examples/)** - Real-world project examples\n\n## \ud83c\udff7\ufe0f Available Templates & Tags\n\n### Templates by Category\n\n**Technology Templates:**\n- `react_app` - React applications with TypeScript\n- `python-api` - Python REST APIs with FastAPI\n- `nodejs-api` - Node.js APIs with Express\n- `vue-frontend` - Vue.js applications\n- `mobile-app` - Cross-platform mobile apps\n\n**Domain Templates:**\n- `saas-application` - SaaS platforms with billing\n- `ecommerce-application` - E-commerce platforms\n- `fintech-application` - Financial applications\n- `healthcare-application` - Healthcare platforms\n- `data-science-application` - ML and data platforms\n\n**Architecture Templates:**\n- `web-application` - General web applications\n- `enterprise-web-application` - Enterprise-scale apps\n- `microservice` - Microservice architectures\n\n**Methodology Templates:**\n- `ai-assisted-development` - AI-first development\n- `security-focused-development` - Security-critical apps\n\n### Instruction Categories\n\n**Core Instructions (Always Included):**\n- `core` - Fundamental development practices (25 instructions)\n- `workflow` - Development workflow and process (included in core)\n\n**Specialized Instructions:**\n- `frontend` - Frontend development (12 instructions)\n- `backend` - Backend development (15 instructions)\n- `testing` - Testing strategies (9 instructions)\n- `security` - Security practices (distributed across categories)\n- `performance` - Performance optimization (distributed across categories)\n\n**Technology-Specific:**\n- `python`, `javascript`, `typescript` - Language-specific guidelines\n- `react`, `vue`, `angular` - Framework-specific practices\n- `api`, `database`, `docker` - Technology-specific instructions\n\n## \ud83d\udd27 Who Should Use AgentSpec?\n\n**Perfect for:**\n- **Developers using AI assistants** (GitHub Copilot, ChatGPT, Claude, etc.)\n- **Teams** who want consistent coding standards\n- **Beginners** learning best practices\n- **Experienced developers** scaling their knowledge\n\n**Especially useful if you:**\n- Want AI to generate professional-grade code, not just examples\n- Need to ensure security and quality in AI-generated code\n- Want consistent standards across projects and team members\n- Are building production applications with AI assistance\n\n## \ud83d\ude80 Getting Started\n\n### For Complete Beginners\n\n**Never used AgentSpec before?**\n\n1. **Learn what it does:** Read [What is AgentSpec?](docs/what-is-agentspec.md)\n2. **Try it out:** Follow the [Quick Start Guide](docs/quick-start.md) (5 minutes)\n3. **Build something:** Complete [Your First Project](docs/your-first-project.md) tutorial\n\n### For Experienced Developers\n\n**Ready to jump in?**\n\n1. **Install:** `pip install agentspec`\n2. **Generate instructions:** `agentspec generate --template react_app --output instructions.md`\n3. **Share with AI:** Copy instructions.md content to your AI assistant\n4. **Start coding:** Ask AI to build features following the instructions\n\n### Need Help Choosing?\n\n- **Interactive setup:** `agentspec interactive` for guided template selection\n- **Project analysis:** `agentspec analyze .` to analyze existing projects\n- **Browse templates:** `agentspec list-templates` to see all options\n- **Get recommendations:** Check the [Templates Guide](docs/working-with-templates.md)\n\n## \ud83d\udd27 Troubleshooting\n\n**Common issues and solutions:**\n\n**Installation problems:**\n```bash\n# If pip install fails, try:\npip install --upgrade pip\npip install agentspec\n\n# For Python 3.8 compatibility issues:\npip install \"agentspec[dev]\" --no-deps\n```\n\n**Command not found:**\n```bash\n# Make sure AgentSpec is in your PATH\nwhich agentspec\n\n# Or run as module:\npython -m agentspec --version\n```\n\n**Template not working:**\n```bash\n# List available templates:\nagentspec list-templates\n\n# Use exact template ID:\nagentspec generate --template react_app --output instructions.md\n```\n\n**Need more help?** Check our [GitHub Discussions](https://github.com/keyurgolani/AgentSpec/discussions)\n\n## \ud83e\udd1d Contributing\n\nWe welcome contributions! See [CONTRIBUTING.md](CONTRIBUTING.md) for guidelines.\n\n```bash\n# Quick development setup\ngit clone https://github.com/keyurgolani/AgentSpec.git\ncd AgentSpec\npip install -e \".[dev]\"\npytest\n```\n\n## \ud83d\udcc4 License\n\nMIT License - see [LICENSE](LICENSE) for details.\n\n## \ud83c\udf1f Why AgentSpec Works\n\n- **Proven Instructions**: Based on industry best practices and real-world experience\n- **AI-Optimized**: Instructions written specifically for AI understanding\n- **Comprehensive**: Covers security, testing, performance, accessibility, and more\n- **Flexible**: Works with any AI assistant and any project type\n- **Time-Saving**: Get professional code faster than writing detailed prompts every time\n\n## \ud83d\ude80 Quick Links\n\n**New to AgentSpec?**\n- **[What is AgentSpec?](docs/what-is-agentspec.md)** - Simple explanation\n- **[Quick Start](docs/quick-start.md)** - Get running in 5 minutes\n- **[Your First Project](docs/your-first-project.md)** - Complete tutorial\n\n**Ready to use?**\n- **[Examples](examples/)** - Real-world project examples\n- **[Command Reference](docs/command-line-guide.md)** - All CLI commands\n- **[Templates](docs/templates-reference.md)** - Browse all templates\n\n---\n\n**Get better AI code with AgentSpec - professional instructions for professional results.**\n",
"bugtrack_url": null,
"license": "MIT",
"summary": "Specification-driven development toolkit with smart context detection",
"version": "2.0.1",
"project_urls": {
"Bug Tracker": "https://github.com/keyurgolani/AgentSpec/issues",
"Documentation": "https://github.com/keyurgolani/AgentSpec#readme",
"Homepage": "https://github.com/keyurgolani/AgentSpec",
"Repository": "https://github.com/keyurgolani/AgentSpec.git"
},
"split_keywords": [
"specification",
" development",
" automation",
" templates",
" cli"
],
"urls": [
{
"comment_text": null,
"digests": {
"blake2b_256": "156f98d7d8cadf7728ce25b13fe5cfbb86dd6bcc83a3c28a68be7cbefc8ec113",
"md5": "a28fc73182c475541d36a74b151f2210",
"sha256": "83bd973bb46541b22873d6ce88a6e05cc2081e77b5341b5f4c786dcc75dfed8d"
},
"downloads": -1,
"filename": "agentspec-2.0.1-py3-none-any.whl",
"has_sig": false,
"md5_digest": "a28fc73182c475541d36a74b151f2210",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.8",
"size": 140101,
"upload_time": "2025-09-16T14:30:02",
"upload_time_iso_8601": "2025-09-16T14:30:02.286719Z",
"url": "https://files.pythonhosted.org/packages/15/6f/98d7d8cadf7728ce25b13fe5cfbb86dd6bcc83a3c28a68be7cbefc8ec113/agentspec-2.0.1-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": null,
"digests": {
"blake2b_256": "5b4955d100ed743fa360fafcf97dee1913ba0d3322da96e903fa5adcc1209b30",
"md5": "d540d36187aa6301de603d8231716b36",
"sha256": "5b8553dbde7dc05b55e743d9fa39e15f0389cfa9db01d747cb6d10f6e2e2f079"
},
"downloads": -1,
"filename": "agentspec-2.0.1.tar.gz",
"has_sig": false,
"md5_digest": "d540d36187aa6301de603d8231716b36",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.8",
"size": 241076,
"upload_time": "2025-09-16T14:30:03",
"upload_time_iso_8601": "2025-09-16T14:30:03.726569Z",
"url": "https://files.pythonhosted.org/packages/5b/49/55d100ed743fa360fafcf97dee1913ba0d3322da96e903fa5adcc1209b30/agentspec-2.0.1.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2025-09-16 14:30:03",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "keyurgolani",
"github_project": "AgentSpec",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"lcname": "agentspec"
}
JSON
