Project Template

A modern Python-first project template following 2025-2026 industry standards for AI-augmented development. Battle-tested patterns from production projects.

What's Included

AI Agent Configuration

File	Standard	Supported By
AGENTS.md	AAIF / Linux Foundation	Claude, Copilot, Cursor, Codex, Devin, Gemini CLI
CLAUDE.md	Anthropic	Claude Code (with Documentation Router + Trust Levels)
.claude/	Claude Code Preset	Skills (/commit, /push), hooks, permissions
.cursor/rules/	Cursor	Cursor AI
.github/copilot-instructions.md	GitHub	GitHub Copilot
.well-known/agent-card.json	A2A Protocol	Agent-to-Agent communication

Claude Code Preset (.claude/)

Production-ready preset for consistent agent behavior:

File	Purpose
settings.json	Permissions (git, python, pytest, pip, gh) + hook configuration
hooks/protect-files.py	Blocks edits to .env, secrets, lock files, .git/
skills/commit/SKILL.md	Smart commit with conventional commits + Co-Authored-By
skills/push/SKILL.md	Push with automatic GitHub issue creation for untested features
.gitignore	Excludes local settings and session data from git

Development Standards (docs/core/)

26 production-tested standards (Python-first):

Category	Documents	Trust Level
Fundamentals	Project Guidelines, Testing Strategy, Git Workflow, Trust Levels, Self-Validation, Documentation, Best Practices, Python Tools, Preset Guide	1 (Auto)
Architecture	Interface Contracts, Service Layer, Error Handling, API Design, Performance, Performance Patterns, Configuration, Logging, Dependencies, Deployment, Agent Optimization, Skills Architecture, Server Setup	2 (AI Review)
Critical	Security, Database Strategy, AI Governance	3 (Human Review)

Project Management

Folder	Purpose
tasks/	Task tracking (active, backlog, done)
docs/decisions/	Architecture Decision Records (ADR) with template + real example
docs/specs/	Feature specifications (Spec-Driven Development)
docs/guides/	Setup and deployment guides
context/	Business context, market research, domain knowledge
data-sources/	Raw/source data (gitignored)

DevOps

File	Purpose
.github/workflows/ci.yml	CI pipeline template
.github/ISSUE_TEMPLATE/	Bug, feature, and idea templates
.github/PULL_REQUEST_TEMPLATE.md	PR template
scripts/validate.sh	Pre-commit validation (ruff, mypy, pytest)
CONTRIBUTING.md	Contribution guidelines
SECURITY.md	Security policy
CHANGELOG.md	Version history

Quick Start

1. Click "Use this template" on GitHub
2. Fill in AGENTS.md and CLAUDE.md with your project details (replace TODOs)
3. Review .claude/settings.json — adjust permissions for your stack
4. Set up docs/architecture/overview.md with your system design
5. Start adding tasks to tasks/backlog.md
6. Run ./scripts/validate.sh to verify your setup

Directory Structure

.
├── AGENTS.md                 # Universal AI agent instructions (AAIF standard)
├── CLAUDE.md                 # Claude Code instructions (Documentation Router + Trust Levels)
├── README.md                 # This file
├── CONTRIBUTING.md           # How to contribute
├── CHANGELOG.md              # Version history
├── SECURITY.md               # Security policy
├── .editorconfig             # Editor settings
├── .gitignore                # Git ignore rules
├── .env.example              # Environment template
│
├── .claude/                  # Claude Code preset
│   ├── settings.json         # Permissions + hooks
│   ├── .gitignore            # Local files exclusion
│   ├── hooks/
│   │   └── protect-files.py  # Block edits to sensitive files
│   └── skills/
│       ├── commit/SKILL.md   # /commit command
│       └── push/SKILL.md     # /push command
│
├── .cursor/rules/            # Cursor AI rules
├── .github/                  # GitHub config (CI, templates, Copilot)
├── .well-known/              # A2A agent discovery
│
├── docs/
│   ├── core/                 # 26 development standards (Python-first)
│   ├── architecture/         # System design
│   ├── decisions/            # ADRs (template + example)
│   ├── specs/                # Feature specifications
│   └── guides/               # Setup, deployment guides
│
├── tasks/
│   ├── backlog.md            # Ideas and future tasks
│   ├── active/               # Tasks in progress
│   └── done/                 # Completed tasks archive
│
├── context/                  # Business context
│   ├── company/              # Company info
│   ├── market/               # Market research
│   └── products/             # Product details
│
├── scripts/
│   └── validate.sh           # Pre-commit validation (ruff, mypy, pytest)
│
├── data/                     # Application data (partially gitignored)
├── data-sources/             # Raw/source data (fully gitignored)
├── src/                      # Source code
└── tests/                    # Tests (unit, integration)

Trust Levels

Level	Review	Examples
1	Auto-approve	UI changes, CRUD by pattern, docs, tests
2	AI Review	New API endpoints, business logic, integrations
3	Human Review	Auth, payments, database migrations, crypto

Open Tasks

• Design System / UI approach — Unified design system for Python web projects (Jinja2 + Alpine.js + HTMX + Tailwind) is not yet standardized. Needs separate planning.

Standards Reference

• AGENTS.md (AAIF) — Universal agent instructions
• MCP (Model Context Protocol) — Agent-to-tool communication
• A2A Protocol — Agent-to-agent communication
• MADR — Architecture Decision Records
• Conventional Commits — Commit message standard
• Keep a Changelog — Changelog format

License

Choose a license