# Improved-SDD
[](LICENSE)
[](https://www.python.org/)
A GitHub Copilot Studio project with Improved Spec-Driven Development templates for building high-quality Python CLI applications.
## Features
- **Spec-Driven Development**: Structured approach to software development with comprehensive specifications
- **GitLab Flow Integration**: Built-in workflow guidance with automatic commit prompts and PR creation
- **Python CLI Framework**: Built with Typer and Rich for modern, beautiful command-line interfaces
- **Automated Code Quality**: Pre-commit hooks with Flake8, Black, isort, and mypy
- **GitHub Copilot Integration**: Custom templates and instructions for AI-assisted development
- **CI/CD Ready**: GitHub Actions workflow for automated testing and linting
- **Cross-Platform**: Works on Windows, macOS, and Linux
## Quick Start
1. **Clone the repository**
```bash
git clone <repository-url>
cd improved-sdd
```
2. **Install dependencies**
```bash
pip install -r requirements.txt
```
3. **Set up development environment**
```bash
pip install pre-commit
pre-commit install
```
4. **Open in VS Code** and start developing with GitHub Copilot using the provided templates
## Usage
### CLI Commands
The project includes a CLI tool for managing spec-driven development projects:
```bash
# Initialize a new project with GitLab Flow (default)
python src/improved_sdd_cli.py init <project-name>
# Initialize without GitLab Flow integration
python src/improved_sdd_cli.py init <project-name> --no-gitlab-flow
# Delete a project (with confirmation)
python src/improved_sdd_cli.py delete <project-name>
# Check project configuration
python src/improved_sdd_cli.py check <project-name>
# Get help
python src/improved_sdd_cli.py --help
```
### Development Workflow
1. Create a specification in `specs/`
2. Use the CLI to initialize your project structure
3. Develop following the spec-driven approach
4. Commit changes (linting runs automatically)
### GitLab Flow Integration
The improved-sdd CLI includes built-in GitLab Flow support that provides workflow guidance during spec development:
#### **Automatic Workflow Integration**
- **Setup Guidance**: Branch creation and repository validation before starting specs
- **Phase Commit Prompts**: Commit guidance after completing each spec phase (feasibility, requirements, design, tasks)
- **PR Creation**: Step-by-step PR creation guidance after implementation completion
- **Platform-Specific Commands**: Windows PowerShell vs Unix/macOS bash command syntax
#### **How It Works**
GitLab Flow uses a **dynamic keyword integration** approach:
1. **Markdown Files as Variables**: GitLab Flow content stored in `templates/gitlab-flow/*.md` files
2. **Keyword Replacement**: Keywords like `{GITLAB_FLOW_SETUP}`, `{GITLAB_FLOW_COMMIT}`, `{GITLAB_FLOW_PR}` in chatmode files
3. **Conditional Loading**: Keywords replaced with GitLab Flow content when enabled, empty when disabled
4. **Platform Detection**: Commands automatically adjusted for Windows vs Unix systems
#### **CLI Flag Control**
```bash
# Enable GitLab Flow (default behavior)
python src/improved_sdd_cli.py init my-project --gitlab-flow
# Disable GitLab Flow
python src/improved_sdd_cli.py init my-project --no-gitlab-flow
```
#### **Example Workflow**
1. **Project Initialization**: `improved-sdd init my-feature --gitlab-flow`
2. **Branch Setup**: Follow GitLab Flow setup guidance in chatmode
3. **Spec Development**: Complete feasibility → requirements → design → tasks
4. **Automatic Commits**: Commit after each phase using provided guidance
5. **Implementation**: Execute tasks with commit prompts between tasks
6. **PR Creation**: Create pull request when all implementation complete
#### **GitLab Flow Templates**
The system includes three core templates:
- **`gitlab-flow-setup.md`**: Repository validation and branch creation
- **`gitlab-flow-commit.md`**: Phase completion commit guidance with conventional commit format
- **`gitlab-flow-pr.md`**: PR creation with timing safeguards and templates
#### **Benefits**
- ✅ **Integrated Workflow**: Git operations embedded naturally in spec development
- ✅ **Zero Breaking Changes**: Existing workflows unchanged when disabled
- ✅ **Platform Agnostic**: Works on Windows, macOS, and Linux
- ✅ **Flexible Control**: Easy to enable/disable via CLI flag
- ✅ **Best Practices**: Conventional commits and proper PR timing
## Development Setup
### Prerequisites
- Python 3.8 or higher
- VS Code with Python extension
- Git
### Installation
1. Clone the repository
2. Install dependencies:
```bash
pip install -r requirements.txt
```
3. Install pre-commit hooks:
```bash
pip install pre-commit
pre-commit install
```
### Code Quality Tools
This project uses comprehensive linting and formatting tools:
#### Automatic Linting (Pre-commit Hooks)
Pre-commit hooks run automatically on each commit. Install them with:
```bash
pre-commit install
```
Run manually on all files:
```bash
pre-commit run --all-files
```
#### Manual Tools
```bash
# Style guide enforcement
flake8 src/ --max-line-length=120
# Code formatting
black src/
# Import sorting
isort src/ --profile=black
# Type checking
mypy src/
```
#### VS Code Integration
The project includes optimized VS Code settings for:
- Real-time linting with Flake8
- Automatic formatting with Black on save
- Import sorting
- 120-character line ruler
#### CI/CD
GitHub Actions automatically runs quality checks on:
- Pushes to main/develop branches
- Pull requests
## Project Structure
```
improved-sdd/
├── src/ # Source code
├── specs/ # Project specifications
├── templates/ # Development templates
│ ├── chatmodes/ # AI behavior patterns
│ ├── instructions/ # Development guidance
│ ├── prompts/ # Structured AI prompts
│ └── gitlab-flow/ # GitLab Flow workflow templates
├── memory/ # Project memory and constitution
├── .github/ # GitHub templates and workflows
├── requirements.txt # Python dependencies
├── pyproject.toml # Project configuration
├── .pre-commit-config.yaml # Pre-commit hooks
└── .flake8 # Linting configuration
```
## Templates Available
- **Chatmodes**: AI behavior patterns for different development scenarios
- **Instructions**: Context-specific development guidance
- **Prompts**: Structured prompts for AI interactions
- **GitLab Flow**: Workflow templates for git operations and branch management
## Contributing
1. Fork the repository
2. Create a feature branch: `git checkout -b feature/your-feature`
3. Make your changes and ensure tests pass
4. Commit with pre-commit hooks: `git commit -m "Add your feature"`
5. Push to your branch: `git push origin feature/your-feature`
6. Create a Pull Request
### Development Guidelines
- Follow the spec-driven development approach
- Write clear, documented code
- Use type hints for better code quality
- Run pre-commit hooks before committing
- Update specifications for new features
## Resources
- [Typer Documentation](https://typer.tiangolo.com/)
- [Rich Documentation](https://rich.readthedocs.io/)
- [CLI Guidelines](https://clig.dev/)
- [Python CLI Development Guide](.github/instructions/python-cli-development.md)
## License
This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.
Raw data
{
"_id": null,
"home_page": null,
"name": "improved-sdd",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.9",
"maintainer_email": null,
"keywords": "spec-driven-development, ai, github-copilot, templates, cli, development-tools, gitlab-flow, git-workflow",
"author": null,
"author_email": "Robert Meisner <robert@catchit.pl>",
"download_url": "https://files.pythonhosted.org/packages/6a/6b/1e6a0e485fef2a12f1b1e51f81579aa4977dcf18a4e073617adea6ded86b/improved_sdd-0.1.4.tar.gz",
"platform": null,
"description": "# Improved-SDD\n\n[](LICENSE)\n[](https://www.python.org/)\n\nA GitHub Copilot Studio project with Improved Spec-Driven Development templates for building high-quality Python CLI applications.\n\n## Features\n\n- **Spec-Driven Development**: Structured approach to software development with comprehensive specifications\n- **GitLab Flow Integration**: Built-in workflow guidance with automatic commit prompts and PR creation\n- **Python CLI Framework**: Built with Typer and Rich for modern, beautiful command-line interfaces\n- **Automated Code Quality**: Pre-commit hooks with Flake8, Black, isort, and mypy\n- **GitHub Copilot Integration**: Custom templates and instructions for AI-assisted development\n- **CI/CD Ready**: GitHub Actions workflow for automated testing and linting\n- **Cross-Platform**: Works on Windows, macOS, and Linux\n\n## Quick Start\n\n1. **Clone the repository**\n ```bash\n git clone <repository-url>\n cd improved-sdd\n ```\n\n2. **Install dependencies**\n ```bash\n pip install -r requirements.txt\n ```\n\n3. **Set up development environment**\n ```bash\n pip install pre-commit\n pre-commit install\n ```\n\n4. **Open in VS Code** and start developing with GitHub Copilot using the provided templates\n\n## Usage\n\n### CLI Commands\n\nThe project includes a CLI tool for managing spec-driven development projects:\n\n```bash\n# Initialize a new project with GitLab Flow (default)\npython src/improved_sdd_cli.py init <project-name>\n\n# Initialize without GitLab Flow integration\npython src/improved_sdd_cli.py init <project-name> --no-gitlab-flow\n\n# Delete a project (with confirmation)\npython src/improved_sdd_cli.py delete <project-name>\n\n# Check project configuration\npython src/improved_sdd_cli.py check <project-name>\n\n# Get help\npython src/improved_sdd_cli.py --help\n```\n\n### Development Workflow\n\n1. Create a specification in `specs/`\n2. Use the CLI to initialize your project structure\n3. Develop following the spec-driven approach\n4. Commit changes (linting runs automatically)\n\n### GitLab Flow Integration\n\nThe improved-sdd CLI includes built-in GitLab Flow support that provides workflow guidance during spec development:\n\n#### **Automatic Workflow Integration**\n- **Setup Guidance**: Branch creation and repository validation before starting specs\n- **Phase Commit Prompts**: Commit guidance after completing each spec phase (feasibility, requirements, design, tasks)\n- **PR Creation**: Step-by-step PR creation guidance after implementation completion\n- **Platform-Specific Commands**: Windows PowerShell vs Unix/macOS bash command syntax\n\n#### **How It Works**\n\nGitLab Flow uses a **dynamic keyword integration** approach:\n\n1. **Markdown Files as Variables**: GitLab Flow content stored in `templates/gitlab-flow/*.md` files\n2. **Keyword Replacement**: Keywords like `{GITLAB_FLOW_SETUP}`, `{GITLAB_FLOW_COMMIT}`, `{GITLAB_FLOW_PR}` in chatmode files\n3. **Conditional Loading**: Keywords replaced with GitLab Flow content when enabled, empty when disabled\n4. **Platform Detection**: Commands automatically adjusted for Windows vs Unix systems\n\n#### **CLI Flag Control**\n\n```bash\n# Enable GitLab Flow (default behavior)\npython src/improved_sdd_cli.py init my-project --gitlab-flow\n\n# Disable GitLab Flow\npython src/improved_sdd_cli.py init my-project --no-gitlab-flow\n```\n\n#### **Example Workflow**\n\n1. **Project Initialization**: `improved-sdd init my-feature --gitlab-flow`\n2. **Branch Setup**: Follow GitLab Flow setup guidance in chatmode\n3. **Spec Development**: Complete feasibility \u2192 requirements \u2192 design \u2192 tasks\n4. **Automatic Commits**: Commit after each phase using provided guidance\n5. **Implementation**: Execute tasks with commit prompts between tasks\n6. **PR Creation**: Create pull request when all implementation complete\n\n#### **GitLab Flow Templates**\n\nThe system includes three core templates:\n\n- **`gitlab-flow-setup.md`**: Repository validation and branch creation\n- **`gitlab-flow-commit.md`**: Phase completion commit guidance with conventional commit format\n- **`gitlab-flow-pr.md`**: PR creation with timing safeguards and templates\n\n#### **Benefits**\n\n- \u2705 **Integrated Workflow**: Git operations embedded naturally in spec development\n- \u2705 **Zero Breaking Changes**: Existing workflows unchanged when disabled\n- \u2705 **Platform Agnostic**: Works on Windows, macOS, and Linux\n- \u2705 **Flexible Control**: Easy to enable/disable via CLI flag\n- \u2705 **Best Practices**: Conventional commits and proper PR timing\n\n## Development Setup\n\n### Prerequisites\n\n- Python 3.8 or higher\n- VS Code with Python extension\n- Git\n\n### Installation\n\n1. Clone the repository\n2. Install dependencies:\n ```bash\n pip install -r requirements.txt\n ```\n\n3. Install pre-commit hooks:\n ```bash\n pip install pre-commit\n pre-commit install\n ```\n\n### Code Quality Tools\n\nThis project uses comprehensive linting and formatting tools:\n\n#### Automatic Linting (Pre-commit Hooks)\n\nPre-commit hooks run automatically on each commit. Install them with:\n\n```bash\npre-commit install\n```\n\nRun manually on all files:\n```bash\npre-commit run --all-files\n```\n\n#### Manual Tools\n\n```bash\n# Style guide enforcement\nflake8 src/ --max-line-length=120\n\n# Code formatting\nblack src/\n\n# Import sorting\nisort src/ --profile=black\n\n# Type checking\nmypy src/\n```\n\n#### VS Code Integration\n\nThe project includes optimized VS Code settings for:\n- Real-time linting with Flake8\n- Automatic formatting with Black on save\n- Import sorting\n- 120-character line ruler\n\n#### CI/CD\n\nGitHub Actions automatically runs quality checks on:\n- Pushes to main/develop branches\n- Pull requests\n\n## Project Structure\n\n```\nimproved-sdd/\n\u251c\u2500\u2500 src/ # Source code\n\u251c\u2500\u2500 specs/ # Project specifications\n\u251c\u2500\u2500 templates/ # Development templates\n\u2502 \u251c\u2500\u2500 chatmodes/ # AI behavior patterns\n\u2502 \u251c\u2500\u2500 instructions/ # Development guidance\n\u2502 \u251c\u2500\u2500 prompts/ # Structured AI prompts\n\u2502 \u2514\u2500\u2500 gitlab-flow/ # GitLab Flow workflow templates\n\u251c\u2500\u2500 memory/ # Project memory and constitution\n\u251c\u2500\u2500 .github/ # GitHub templates and workflows\n\u251c\u2500\u2500 requirements.txt # Python dependencies\n\u251c\u2500\u2500 pyproject.toml # Project configuration\n\u251c\u2500\u2500 .pre-commit-config.yaml # Pre-commit hooks\n\u2514\u2500\u2500 .flake8 # Linting configuration\n```\n\n## Templates Available\n\n- **Chatmodes**: AI behavior patterns for different development scenarios\n- **Instructions**: Context-specific development guidance\n- **Prompts**: Structured prompts for AI interactions\n- **GitLab Flow**: Workflow templates for git operations and branch management\n\n## Contributing\n\n1. Fork the repository\n2. Create a feature branch: `git checkout -b feature/your-feature`\n3. Make your changes and ensure tests pass\n4. Commit with pre-commit hooks: `git commit -m \"Add your feature\"`\n5. Push to your branch: `git push origin feature/your-feature`\n6. Create a Pull Request\n\n### Development Guidelines\n\n- Follow the spec-driven development approach\n- Write clear, documented code\n- Use type hints for better code quality\n- Run pre-commit hooks before committing\n- Update specifications for new features\n\n## Resources\n\n- [Typer Documentation](https://typer.tiangolo.com/)\n- [Rich Documentation](https://rich.readthedocs.io/)\n- [CLI Guidelines](https://clig.dev/)\n- [Python CLI Development Guide](.github/instructions/python-cli-development.md)\n\n## License\n\nThis project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.\n",
"bugtrack_url": null,
"license": null,
"summary": "Setup tool for Improved Spec-Driven Development projects with AI assistant templates and GitLab Flow integration",
"version": "0.1.4",
"project_urls": {
"Documentation": "https://github.com/robertmeisner/improved-sdd#readme",
"Homepage": "https://github.com/robertmeisner/improved-sdd",
"Issues": "https://github.com/robertmeisner/improved-sdd/issues",
"Repository": "https://github.com/robertmeisner/improved-sdd"
},
"split_keywords": [
"spec-driven-development",
" ai",
" github-copilot",
" templates",
" cli",
" development-tools",
" gitlab-flow",
" git-workflow"
],
"urls": [
{
"comment_text": null,
"digests": {
"blake2b_256": "fd55ed18ed158a1fca72a1982033055ec5bc7791825fc61b31df8696c62a154b",
"md5": "7353dd82bc913727ab42fd6005383e8d",
"sha256": "d9ce75cdbfc82d0f79953a20318a2362cce03e62d17d5fcff5db304991f6771b"
},
"downloads": -1,
"filename": "improved_sdd-0.1.4-py3-none-any.whl",
"has_sig": false,
"md5_digest": "7353dd82bc913727ab42fd6005383e8d",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.9",
"size": 44477,
"upload_time": "2025-09-15T02:52:32",
"upload_time_iso_8601": "2025-09-15T02:52:32.798199Z",
"url": "https://files.pythonhosted.org/packages/fd/55/ed18ed158a1fca72a1982033055ec5bc7791825fc61b31df8696c62a154b/improved_sdd-0.1.4-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": null,
"digests": {
"blake2b_256": "6a6b1e6a0e485fef2a12f1b1e51f81579aa4977dcf18a4e073617adea6ded86b",
"md5": "b33edf7bab44bce0acefd2d920b48461",
"sha256": "e1820ba782f858aea74bbfc677b25f377f23c99fd3d856eb4a2463aad9ea17f4"
},
"downloads": -1,
"filename": "improved_sdd-0.1.4.tar.gz",
"has_sig": false,
"md5_digest": "b33edf7bab44bce0acefd2d920b48461",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.9",
"size": 44131,
"upload_time": "2025-09-15T02:52:34",
"upload_time_iso_8601": "2025-09-15T02:52:34.028608Z",
"url": "https://files.pythonhosted.org/packages/6a/6b/1e6a0e485fef2a12f1b1e51f81579aa4977dcf18a4e073617adea6ded86b/improved_sdd-0.1.4.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2025-09-15 02:52:34",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "robertmeisner",
"github_project": "improved-sdd#readme",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"requirements": [
{
"name": "typer",
"specs": []
},
{
"name": "rich",
"specs": []
},
{
"name": "platformdirs",
"specs": []
},
{
"name": "readchar",
"specs": []
},
{
"name": "httpx",
"specs": []
},
{
"name": "flake8",
"specs": [
[
">=",
"6.0.0"
]
]
},
{
"name": "black",
"specs": [
[
">=",
"23.0.0"
]
]
},
{
"name": "isort",
"specs": [
[
">=",
"5.12.0"
]
]
},
{
"name": "pre-commit",
"specs": [
[
">=",
"3.0.0"
]
]
},
{
"name": "mypy",
"specs": [
[
">=",
"1.0.0"
]
]
},
{
"name": "pytest",
"specs": [
[
">=",
"7.0.0"
]
]
},
{
"name": "pytest-asyncio",
"specs": [
[
">=",
"0.21.0"
]
]
},
{
"name": "pytest-cov",
"specs": [
[
">=",
"4.0.0"
]
]
},
{
"name": "pytest-mock",
"specs": [
[
">=",
"3.10.0"
]
]
}
],
"lcname": "improved-sdd"
}
JSON
