A GitHub-native starting point for public and private repositories that need the same baseline: human-first engineering standards, architecture and decision docs, security defaults, and CI that runs on GitHub Actions.
This repository is the template, not an application. Use it to bootstrap a new repo, then replace placeholders with the product you are actually building.
Most new repos accumulate process after the fact: a README that goes stale, CI copied from the last project, and no written architecture. This template inverts that. The first files you get are the ones that keep humans and coding agents aligned:
- what “done” means
- where architecture and decisions live
- how to change the repo without leaving orphans or fake implementations
- a small Actions pipeline that validates the template itself (not a fake app build)
The template repository flag is enabled on this repo today. Use this template works now — you do not need to wait for a later publish step.
- On GitHub, open this repository and choose Use this template → Create a new repository.
- Clone your new repo.
- Rewrite this README for the product. Keep the
docs/layout unless you have a reason to change it. - Fill in
docs/architecture/architecture.mdfor the real system. Add ADRs when you make significant decisions. - Add application code and language-specific workflows in later commits — do not invent a sample app here just to look complete.
You can still clone or fork this repo and treat it the same way. Prefer Use this template when you want a clean history without this template’s commit log.
GitHub-native and GitHub Free-first. Prefer features that work on a free personal or organization account:
| Use | Avoid as a default |
|---|---|
| GitHub Actions, Issues, Projects, Discussions as needed | Third-party CI as the primary pipeline |
| Markdown docs in the repo | Wiki-only or undocumented Slack process |
| Dependabot / CodeQL | Paid scanners required to merge |
| Shell-based template validation | Adding Node/npm only to run docs or lint Markdown |
Do not introduce Node, npm, or other runtimes in this template unless a later application slice actually needs them.
.
├── AGENTS.md # Read before changing code or docs
├── CONTRIBUTING.md # How to propose changes
├── CODE_OF_CONDUCT.md # Contributor Covenant
├── SUPPORT.md # Where to ask for help
├── SECURITY.md # Vulnerability reporting for this template
├── CHANGELOG.md # Template release history
├── LICENSE
├── README.md # You are here
├── scripts/ # Template validation + changelog extract (see scripts/README.md)
├── tests/ # Checks for the validator
├── .github/ # Actions, Dependabot, community templates
└── docs/
├── architecture/ # Current system + diagrams
├── decisions/ # Architecture Decision Records
├── development/ # Contributor workflow
├── operations/ # Maintainer ops + release process
├── references/ # Consumer evolution examples
└── security/ # Security posture for template consumers
bash scripts/validate-template.sh
bash tests/test_validate_template.shGitHub Actions runs those same checks on pull requests, pushes to main, and on a weekly schedule (.github/workflows/validate-scheduled.yml), plus bash -n and ShellCheck on the template scripts. CodeQL analyzes Actions workflow YAML. Pushing a v* tag creates a GitHub Release via .github/workflows/release.yml. Details: docs/development/development.md.
| Doc | Purpose |
|---|---|
| AGENTS.md | Guardrails for humans and coding agents |
| CONTRIBUTING.md | How to open a change |
| SECURITY.md | How to report vulnerabilities |
| CODE_OF_CONDUCT.md | Contributor Covenant conduct policy |
| SUPPORT.md | Where questions and reports should go |
| Development | Local validation and what CI does |
| First-week checklist | Day-0 checklist after Use this template |
| Architecture overview | How architecture docs are organized |
| Current architecture | What this repo is today |
| Architecture diagram | Mermaid view of template surfaces |
| Network diagram note | No runtime network; consumer stub |
| Decisions | When and how to write an ADR |
| ADR-001 | Why GitHub-native free-first |
| ADR-002 | Why validation runs in Actions CI |
| ADR-003 | Why validation also runs on a weekly schedule |
| ADR-004 | Why template validation stays shell-only (no Node/npm) |
| ADR-005 | Why GitHub Actions are pinned to commit SHAs |
| ADR-006 | Why GitHub Release notes embed CHANGELOG sections |
| Security | Baseline security expectations |
| Operations | Maintainer ops for this template |
| Troubleshooting | Common CI/docs/release failure modes |
| Upgrading from upstream | Adopt later template releases in a derived repo |
| Secrets and OIDC | Credential hygiene for derived repos |
| Release process | Tagging and template releases |
| Tagging | v* tags and the release workflow |
| Branch protection | Recommended required checks |
| Incident response | Light IR checklist for template consumers |
| Changelog | Notable template changes |
| Examples (derived repos) | How Java/Python/Go/Rust/.NET/PHP/Ruby/Kotlin/Terraform/Azure-AKS consumers can evolve from this template |
| FAQ (derived repos) | Short answers after Use this template |
Read CONTRIBUTING.md and AGENTS.md before you edit. Changes should be the smallest complete slice that leaves docs, structure, and tests consistent. Newcomers: look for issues labeled good first issue.