# SpecifyX
**Enhanced spec-driven development CLI with modern architecture and Jinja2 templating**
[](https://github.com/barisgit/spec-kit-improved/actions/workflows/release.yml)
[](https://badge.fury.io/py/specifyx)
---
## What is SpecifyX?
SpecifyX is a modern, Python-installable CLI tool forked from the popular [spec-kit](https://github.com/github/spec-kit) for spec-driven development that helps organizations focus on product scenarios rather than writing undifferentiated code.
### Key Benefits for Users
- **Easy Installation**: Install with `uv tool install specifyx` or run `uvx specifyx` without installation
- **Powerful Templating**: Use Jinja2 templates with variables, conditionals, and loops for complex project generation
- **Flexible Branch Naming**: Customize branch patterns like `feature/{name}` or `task/{id}-{name}` and more instead of fixed formats
- **Enhanced User Experience**: Interactive menus, progress tracking, and better error messages
- **Project Generation**: Generate projects from templates with variables, conditionals, and loops for complex project generation
- **Configurable Python Scripts**: Uses python for scripts with utils imported from specifyx to achieve user customizable scripts with low boilerplate
- **Configuration System**: Save your preferences in TOML files instead of repeating command-line options
## Installation
### Using uv (recommended)
```bash
uv tool install specifyx
```
#### Alternative if you don't want to install
```bash
uvx specifyx
```
> Note: `uvx` is a shortcut for `uv tool run`
### Using pipx (for CLI tools)
```bash
pipx install specifyx
```
### Using pip
```bash
pip install specifyx
```
### From git (development version)
```bash
uv tool install --from git+https://github.com/barisgit/spec-kit-improved
```
## Quick Start
Initialize a new spec-driven project:
```bash
specifyx init my-project
specifyx init --here # in current directory
```
Check tool requirements:
```bash
specifyx check
```
Run specifyx python scripts in your project with:
```bash
specifyx run my-script
# List available scripts
specifyx run --list
# Show path to specified script
specifyx run --which my-script
```
> Note: Your AI assistant is instructed to use specifyx when you run commands.
## Attribution and Philosophy
### Inspiration and Attribution
This project is **inspired by and builds upon** the foundational work of the original [specify](https://github.com/github/spec-kit) project by the GitHub team, particularly [John Lam](https://github.com/jflam) and [Den Delimarsky](https://github.com/dend). Their pioneering work in spec-driven development methodology laid the groundwork for this enhanced implementation.
### Why a Separate Project?
While deeply respecting the original specify project, SpecifyX takes a different philosophical approach in several key areas:
#### **1. Installation and Distribution**
- **Original specify**: Git-based templates requiring manual setup
- **SpecifyX**: Standard Python package installable via PyPI for easier adoption
#### **2. Templating Capabilities**
- **Original specify**: Basic string replacement templating
- **SpecifyX**: Full Jinja2 templating with variables, loops, conditionals, and complex logic
#### **3. Configuration and Customization**
- **Original specify**: Minimal configuration, mostly environment-based
- **SpecifyX**: Rich TOML-based configuration system with user preferences and project-specific settings
#### **4. Branch Naming Flexibility**
- **Original specify**: Fixed pattern like "001-feature-name"
- **SpecifyX**: Customizable patterns to match your team's conventions AND branch validation logic so your AI assistant can't generate invalid branch names
#### **5. User Experience Focus**
- **Original specify**: Bash scripts with basic output
- **SpecifyX**: Customizable scripts with utils imported from specifyx to achieve user customizable scripts with low boilerplate
### Our Vision
SpecifyX aims to make spec-driven development more **accessible and powerful** for teams who want enhanced tooling while maintaining full respect for the original methodology. We believe both approaches serve different needs in the ecosystem.
## What is Spec-Driven Development?
Spec-Driven Development **flips the script** on traditional software development. Instead of code being king, **specifications become executable**, directly generating working implementations rather than just guiding them.
### Core Philosophy
- **Intent-driven development** where specifications define the "_what_" before the "_how_"
- **Rich specification creation** using guardrails and organizational principles
- **Multi-step refinement** rather than one-shot code generation from prompts
- **Heavy reliance** on advanced AI model capabilities for specification interpretation
## Development Phases
| Phase | Focus | Key Activities |
|-------|-------|----------------|
| **0-to-1 Development** | Generate from scratch | Generate specs → Plan implementation → Build production-ready applications |
| **Creative Exploration** | Parallel implementations | Explore diverse solutions → Support multiple tech stacks → Experiment with UX patterns |
| **Iterative Enhancement** | Brownfield modernization | Add features iteratively → Modernize legacy systems → Adapt processes |
## Prerequisites
- **Linux/macOS** (or WSL2 on Windows)
- **Python 3.11+**
- AI coding agent: [Claude Code](https://www.anthropic.com/claude-code), [GitHub Copilot](https://code.visualstudio.com/), or [Gemini CLI](https://github.com/google-gemini/gemini-cli)
- [uv](https://docs.astral.sh/uv/) for package management (recommended)
- [Git](https://git-scm.com/downloads)
## Enhanced Features
### Jinja2 Templating
In your generated project, you can see spec, plan and tasks templates in `.specify/templates/` directory. You can customize them to your needs. They will be rendered with your project variables.
### Enhanced User Interface
- Interactive menus with keyboard navigation
- Progress tracking with live updates
- Rich console output with colored themes
- Graceful fallbacks for limited terminals
## Technical Details
For developers interested in the architecture:
- **Modern Architecture**: Modular services instead of monolithic code
- **Type Safety**: Full type annotations and validation throughout
- **Comprehensive Testing**: Contract, integration, and unit tests
- **TOML Configuration**: Flexible configuration with dynaconf
## Documentation
To be updated.
## Development
### Setup Development Environment
```bash
git clone https://github.com/barisgit/spec-kit-improved
cd spec-kit-improved
uv sync --extra dev
```
### Run Tests
```bash
pytest # All tests
pytest tests/contract/ # Contract tests
pytest tests/integration/ # Integration tests
pytest tests/unit/ # Unit tests
```
### Code Quality
```bash
ruff check . # Linting
ruff format . # Formatting
pyrefly check . # Type checking
```
#### There is also a Makefile in the root of the project for convenience.
You can run `make help` to see the available commands.
## Contributing
We welcome contributions! Please see `CONTRIBUTING.md` for more details.
## Support
For support, please open a [GitHub issue](https://github.com/barisgit/spec-kit-improved/issues/new). We welcome bug reports, feature requests, and questions about using SpecifyX.
## License
This project is licensed under the MIT License - see the [LICENSE](./LICENSE) file for details.
---
**SpecifyX**: Making spec-driven development more accessible and powerful for modern development teams.
Raw data
{
"_id": null,
"home_page": null,
"name": "specifyx",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.11",
"maintainer_email": null,
"keywords": "cli, development, jinja2, project-generation, spec-driven, templates, toml",
"author": null,
"author_email": "SpecifyX Contributors <blaz@paxia.co>",
"download_url": "https://files.pythonhosted.org/packages/27/16/0e09b985432ceefa4b9d261d8ebb7f7f377979397cb8849085c8804054cf/specifyx-0.2.1.tar.gz",
"platform": null,
"description": "# SpecifyX\n\n**Enhanced spec-driven development CLI with modern architecture and Jinja2 templating**\n\n[](https://github.com/barisgit/spec-kit-improved/actions/workflows/release.yml)\n[](https://badge.fury.io/py/specifyx)\n\n---\n\n## What is SpecifyX?\n\nSpecifyX is a modern, Python-installable CLI tool forked from the popular [spec-kit](https://github.com/github/spec-kit) for spec-driven development that helps organizations focus on product scenarios rather than writing undifferentiated code.\n\n### Key Benefits for Users\n\n- **Easy Installation**: Install with `uv tool install specifyx` or run `uvx specifyx` without installation\n- **Powerful Templating**: Use Jinja2 templates with variables, conditionals, and loops for complex project generation\n- **Flexible Branch Naming**: Customize branch patterns like `feature/{name}` or `task/{id}-{name}` and more instead of fixed formats\n- **Enhanced User Experience**: Interactive menus, progress tracking, and better error messages\n- **Project Generation**: Generate projects from templates with variables, conditionals, and loops for complex project generation\n- **Configurable Python Scripts**: Uses python for scripts with utils imported from specifyx to achieve user customizable scripts with low boilerplate\n- **Configuration System**: Save your preferences in TOML files instead of repeating command-line options\n\n## Installation\n\n### Using uv (recommended)\n```bash\nuv tool install specifyx\n```\n\n#### Alternative if you don't want to install\n\n```bash\nuvx specifyx\n```\n\n> Note: `uvx` is a shortcut for `uv tool run`\n\n### Using pipx (for CLI tools)\n```bash\npipx install specifyx\n```\n\n### Using pip\n```bash\npip install specifyx\n```\n\n### From git (development version)\n```bash\nuv tool install --from git+https://github.com/barisgit/spec-kit-improved\n```\n\n## Quick Start\n\nInitialize a new spec-driven project:\n```bash\nspecifyx init my-project\nspecifyx init --here # in current directory\n```\n\nCheck tool requirements:\n```bash\nspecifyx check\n```\n\nRun specifyx python scripts in your project with:\n```bash\nspecifyx run my-script\n\n# List available scripts\nspecifyx run --list\n\n# Show path to specified script\nspecifyx run --which my-script\n```\n\n> Note: Your AI assistant is instructed to use specifyx when you run commands.\n\n## Attribution and Philosophy\n\n### Inspiration and Attribution\n\nThis project is **inspired by and builds upon** the foundational work of the original [specify](https://github.com/github/spec-kit) project by the GitHub team, particularly [John Lam](https://github.com/jflam) and [Den Delimarsky](https://github.com/dend). Their pioneering work in spec-driven development methodology laid the groundwork for this enhanced implementation.\n\n### Why a Separate Project?\n\nWhile deeply respecting the original specify project, SpecifyX takes a different philosophical approach in several key areas:\n\n#### **1. Installation and Distribution**\n- **Original specify**: Git-based templates requiring manual setup\n- **SpecifyX**: Standard Python package installable via PyPI for easier adoption\n\n#### **2. Templating Capabilities** \n- **Original specify**: Basic string replacement templating\n- **SpecifyX**: Full Jinja2 templating with variables, loops, conditionals, and complex logic\n\n#### **3. Configuration and Customization**\n- **Original specify**: Minimal configuration, mostly environment-based\n- **SpecifyX**: Rich TOML-based configuration system with user preferences and project-specific settings\n\n#### **4. Branch Naming Flexibility**\n- **Original specify**: Fixed pattern like \"001-feature-name\"\n- **SpecifyX**: Customizable patterns to match your team's conventions AND branch validation logic so your AI assistant can't generate invalid branch names\n\n#### **5. User Experience Focus**\n- **Original specify**: Bash scripts with basic output\n- **SpecifyX**: Customizable scripts with utils imported from specifyx to achieve user customizable scripts with low boilerplate\n\n### Our Vision\n\nSpecifyX aims to make spec-driven development more **accessible and powerful** for teams who want enhanced tooling while maintaining full respect for the original methodology. We believe both approaches serve different needs in the ecosystem.\n\n## What is Spec-Driven Development?\n\nSpec-Driven Development **flips the script** on traditional software development. Instead of code being king, **specifications become executable**, directly generating working implementations rather than just guiding them.\n\n### Core Philosophy\n\n- **Intent-driven development** where specifications define the \"_what_\" before the \"_how_\"\n- **Rich specification creation** using guardrails and organizational principles \n- **Multi-step refinement** rather than one-shot code generation from prompts\n- **Heavy reliance** on advanced AI model capabilities for specification interpretation\n\n## Development Phases\n\n| Phase | Focus | Key Activities |\n|-------|-------|----------------|\n| **0-to-1 Development** | Generate from scratch | Generate specs \u2192 Plan implementation \u2192 Build production-ready applications |\n| **Creative Exploration** | Parallel implementations | Explore diverse solutions \u2192 Support multiple tech stacks \u2192 Experiment with UX patterns |\n| **Iterative Enhancement** | Brownfield modernization | Add features iteratively \u2192 Modernize legacy systems \u2192 Adapt processes |\n\n## Prerequisites\n\n- **Linux/macOS** (or WSL2 on Windows)\n- **Python 3.11+** \n- AI coding agent: [Claude Code](https://www.anthropic.com/claude-code), [GitHub Copilot](https://code.visualstudio.com/), or [Gemini CLI](https://github.com/google-gemini/gemini-cli)\n- [uv](https://docs.astral.sh/uv/) for package management (recommended)\n- [Git](https://git-scm.com/downloads)\n\n## Enhanced Features\n\n### Jinja2 Templating\n\nIn your generated project, you can see spec, plan and tasks templates in `.specify/templates/` directory. You can customize them to your needs. They will be rendered with your project variables.\n\n### Enhanced User Interface\n- Interactive menus with keyboard navigation\n- Progress tracking with live updates \n- Rich console output with colored themes\n- Graceful fallbacks for limited terminals\n\n## Technical Details\n\nFor developers interested in the architecture:\n\n- **Modern Architecture**: Modular services instead of monolithic code\n- **Type Safety**: Full type annotations and validation throughout\n- **Comprehensive Testing**: Contract, integration, and unit tests\n- **TOML Configuration**: Flexible configuration with dynaconf\n\n## Documentation\n\nTo be updated.\n\n## Development\n\n### Setup Development Environment\n```bash\ngit clone https://github.com/barisgit/spec-kit-improved\ncd spec-kit-improved\nuv sync --extra dev\n```\n\n### Run Tests\n```bash\npytest # All tests\npytest tests/contract/ # Contract tests\npytest tests/integration/ # Integration tests\npytest tests/unit/ # Unit tests\n```\n\n### Code Quality\n```bash\nruff check . # Linting\nruff format . # Formatting \npyrefly check . # Type checking\n```\n\n#### There is also a Makefile in the root of the project for convenience.\n\nYou can run `make help` to see the available commands.\n\n## Contributing\n\nWe welcome contributions! Please see `CONTRIBUTING.md` for more details.\n\n## Support\n\nFor support, please open a [GitHub issue](https://github.com/barisgit/spec-kit-improved/issues/new). We welcome bug reports, feature requests, and questions about using SpecifyX.\n\n## License\n\nThis project is licensed under the MIT License - see the [LICENSE](./LICENSE) file for details.\n\n---\n\n**SpecifyX**: Making spec-driven development more accessible and powerful for modern development teams.",
"bugtrack_url": null,
"license": "MIT",
"summary": "Enhanced spec-driven development CLI with modern architecture and Jinja2 templating",
"version": "0.2.1",
"project_urls": null,
"split_keywords": [
"cli",
" development",
" jinja2",
" project-generation",
" spec-driven",
" templates",
" toml"
],
"urls": [
{
"comment_text": null,
"digests": {
"blake2b_256": "99b28e32a6c2e2cc0d1126fff04fc45fa1d5e4d947d1385df080e2e006d9e875",
"md5": "c4332f9b4bec05eebb82708a5f71ba32",
"sha256": "a4984dd26e026f51133725eb91f299fa0065f76ed24e9a2ea1d4639c6d48ec0d"
},
"downloads": -1,
"filename": "specifyx-0.2.1-py3-none-any.whl",
"has_sig": false,
"md5_digest": "c4332f9b4bec05eebb82708a5f71ba32",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.11",
"size": 105195,
"upload_time": "2025-09-10T00:30:11",
"upload_time_iso_8601": "2025-09-10T00:30:11.485442Z",
"url": "https://files.pythonhosted.org/packages/99/b2/8e32a6c2e2cc0d1126fff04fc45fa1d5e4d947d1385df080e2e006d9e875/specifyx-0.2.1-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": null,
"digests": {
"blake2b_256": "27160e09b985432ceefa4b9d261d8ebb7f7f377979397cb8849085c8804054cf",
"md5": "f7fac922728678568e142dc372c2787e",
"sha256": "af2b1faa91e57df0bcf732a6c8b9939a91c8a477cae3bc2c563cd9a02e93e35f"
},
"downloads": -1,
"filename": "specifyx-0.2.1.tar.gz",
"has_sig": false,
"md5_digest": "f7fac922728678568e142dc372c2787e",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.11",
"size": 2211332,
"upload_time": "2025-09-10T00:30:12",
"upload_time_iso_8601": "2025-09-10T00:30:12.993351Z",
"url": "https://files.pythonhosted.org/packages/27/16/0e09b985432ceefa4b9d261d8ebb7f7f377979397cb8849085c8804054cf/specifyx-0.2.1.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2025-09-10 00:30:12",
"github": false,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"lcname": "specifyx"
}
JSON