dev-starter-kit

Production-ready starter repository with CI/CD, testing enforcement, and AI coding tool configurations.

Clone this repo to start any Python project with best practices already wired up — linting, formatting, testing, pre-commit hooks, GitHub Actions workflows, issue templates, incident runbooks, and instruction files for every major AI coding tool.

---

What's Included

CI/CD Workflows (.github/workflows/)

Workflow	Purpose
pr-checks.yml	Ruff auto-fix + commit, pytest, test coverage enforcement with PR comments
lint.yml	Incremental lint on changed files only (push + PR)
merge-ready.yml	Merge gate: strict lint, YAML validation, syntax check, tests

All workflows only check changed files for speed and use explicit permissions blocks for security.

Test Coverage Enforcement

The PR checks workflow detects when you change Python source files and:

• Requires corresponding test files to be added/updated
• Posts a PR comment with exact test file names, class names, and method signatures you need to write
• Bypassable with the skip-test-check label for config-only PRs

Issue Templates (.github/ISSUE_TEMPLATE/)

Template	Use Case
Bug Report	Structured bug reporting with component classification and priority
Incident Report	SEV-1 through SEV-4 incident tracking with triage checklists
Infrastructure Issue	CI/CD, tooling, dependency, and environment issues

Pre-commit Hooks (.pre-commit-config.yaml)

• Ruff lint + format on every commit
• Python syntax check (check-ast)
• YAML, JSON, TOML validation
• Trailing whitespace, line endings, large file detection
• Private key detection
• Branch protection (blocks direct commits to main)

Incident Runbook (docs/INCIDENT_RUNBOOK.md)

• Severity classification table (SEV-1 through SEV-4)
• 3-phase triage checklist
• Component-specific diagnostic commands
• CI/CD troubleshooting
• 4 common failure scenarios with diagnosis and fixes
• Post-incident review template

AI Coding Tool Instructions

Every major AI coding tool is configured out of the box:

File	Tool	Purpose
AGENTS.md	Codex, Cursor, Claude Code, Copilot, Windsurf	Universal agent instructions
CLAUDE.md	Claude Code	Session-persistent instructions
.cursor/rules/*.mdc	Cursor IDE	Modular rules (general, python, testing)
.claude/rules/*.md	Claude Code	Scoped rules with glob patterns
.github/copilot-instructions.md	GitHub Copilot	Code generation guidelines

These files teach AI tools to:

• Follow your project's coding conventions
• Run lint and tests after every change
• Write tests for new code
• Use conventional commits
• Never commit secrets

---

Quick Start

1. Clone and customize

# Clone
git clone https://github.com/humzakt/dev-starter-kit.git my-project
cd my-project

# Remove git history and start fresh
rm -rf .git
git init
git checkout -b main

# Update project metadata
# Edit: pyproject.toml (name, description)
# Edit: README.md (this file)
# Edit: LICENSE (if not MIT)

2. Set up development environment

python -m venv .venv
source .venv/bin/activate  # or .venv\Scripts\activate on Windows
pip install -r requirements.txt

3. Install pre-commit hooks

pre-commit install

4. Start building

# Write code in src/
# Write tests in tests/
# Lint: ruff check --fix . && ruff format .
# Test: pytest tests/ -v

5. Push and open a PR

git add -A
git commit -m "feat: initial project setup"
git remote add origin https://github.com/YOUR_USERNAME/YOUR_REPO.git
git push -u origin main

# Create a feature branch for your first PR
git checkout -b feat/my-feature
# ... make changes ...
git push -u origin feat/my-feature
# Open PR -> CI runs automatically

---

Customization Guide

Adapting Issue Templates

Edit files in .github/ISSUE_TEMPLATE/ to match your project's components:

1. Bug Report → Update the "Affected Component" dropdown options
2. Incident Report → Update the "Affected Components" checklist
3. Infrastructure Issue → Update the "Issue Category" dropdown

Adapting Workflows

The workflows work out of the box for any Python project. To customize:

• Change Python version: Edit python-version in workflow files
• Add dependencies: The workflows install from requirements.txt
• Change test directory: Edit testpaths in pyproject.toml
• Add new CI jobs: See .github/workflows/README.md for instructions

Adapting AI Tool Instructions

• AGENTS.md → Update the project overview and architecture sections
• CLAUDE.md → Update commands and architecture
• .cursor/rules/ → Add new .mdc files for framework-specific rules
• .claude/rules/ → Add new .md files with glob-based scoping

Adding a Language/Framework

This starter is Python-focused, but the structure works for any stack:

• JavaScript/TypeScript: Add ESLint config, Jest setup, update workflows
• Go: Add golangci-lint, go test commands, update workflows
• Rust: Add clippy, cargo test, update workflows

---

Project Structure

.
├── .github/
│   ├── ISSUE_TEMPLATE/
│   │   ├── bug-report.yml          # Bug report template
│   │   ├── incident-report.yml     # Incident report template
│   │   ├── infrastructure-issue.yml # Infra issue template
│   │   └── config.yml              # Template chooser config
│   ├── workflows/
│   │   ├── pr-checks.yml           # PR quality gates
│   │   ├── lint.yml                # Incremental linting
│   │   ├── merge-ready.yml         # Merge readiness check
│   │   └── README.md               # Workflow documentation
│   └── copilot-instructions.md     # GitHub Copilot config
├── .cursor/
│   └── rules/
│       ├── general.mdc             # Always-apply project rules
│       ├── python.mdc              # Python-specific rules
│       └── testing.mdc             # Testing conventions
├── .claude/
│   └── rules/
│       └── development.md          # Development workflow rules
├── docs/
│   └── INCIDENT_RUNBOOK.md         # Incident response playbook
├── src/
│   └── __init__.py                 # Your source code goes here
├── tests/
│   ├── __init__.py
│   └── conftest.py                 # Shared pytest fixtures
├── .gitignore                      # Comprehensive gitignore
├── .pre-commit-config.yaml         # Pre-commit hooks
├── AGENTS.md                       # AI agent instructions (universal)
├── CLAUDE.md                       # Claude Code instructions
├── LICENSE                         # MIT License
├── pyproject.toml                  # Ruff + pytest + project config
├── requirements.txt                # Python dependencies
└── README.md                       # This file

---

FAQ

Q: Do I need all of these AI tool files? A: No. Keep only the ones for tools you use. AGENTS.md has the broadest compatibility.

Q: Can I use this for non-Python projects? A: Yes. Keep the issue templates, incident runbook, and AI tool files. Replace the Python-specific configs (pyproject.toml, ruff, pytest) with your stack's equivalents.

Q: How do I bypass test coverage enforcement? A: Add the skip-test-check label to your PR. Use this for config-only or documentation changes.

Q: The CI auto-fixed my code. What do I do? A: Run git pull to get the auto-fix commit, then continue working. To avoid this, run ruff check --fix . && ruff format . locally before pushing.

---

License

MIT License. See LICENSE for details.