A language-agnostic base for a new GitHub repository. It holds the community health files, the issue and pull request templates, a pinned toolchain, git hooks, a CI gate, and the documentation convention. Every other template in the blueprints set starts from it.
It holds no application code. A repo made from it adds the language tools and fills in the task contract.
| Tool | Owns |
|---|---|
| Nix with flakes | Tool versions, the dev shell, and the sandboxed checks |
| tabkit | The shared dev shell, git hooks, and checks, and the rules for prose, comments, and ADRs |
| just | Tasks |
| Zed | The supported editor, with project settings in .zed/ |
| git-hooks.nix | Git hooks |
| cocogitto | Conventional Commits checks |
| rumdl | Markdown lint |
| dprint | JSON, TOML, and YAML format |
| gitleaks | Secret scan |
| Renovate | Updates to the pinned versions |
-
Install Nix and enable flakes. For the editor, also install Zed, and direnv with nix-direnv. direnv enters the dev shell on
cd, and Zed loads it through direnv. -
Clone the repo and enter the dev shell. The first entry downloads every tool and installs the git hooks:
git clone git@github.com:tabmadi/github-project-template.git cd github-project-template nix develop -
Run the gate:
just check
Open the folder in Zed, and run direnv allow once. Zed suggests its Nix extension when you open flake.nix, so install it once on each machine. Zed then uses the language servers and formatters of the dev shell, formats on save, and lists every recipe under task: spawn. Zed loads the dev shell when it opens the folder. After a change to flake.nix, open the folder again, so Zed loads the new tools. Any other editor works through the same dev shell.
| Recipe | Does |
|---|---|
just setup |
Builds the dev shell and installs the git hooks |
just format |
Applies every formatter |
just lint |
Runs every linter: lint-md and lint-secrets |
just test |
Runs the tests. Here it is a placeholder |
just check |
Runs lint and test. Run it before you finish a change |
just ci |
Runs nix flake check, exactly what CI runs. The pre-push hook runs it too |
.
├── .config/
│ ├── cog.toml Commit types
│ ├── dprint.json JSON, TOML, and YAML format rules
│ ├── gitleaks.toml Secret scan rules
│ └── rumdl.toml Markdown rules
├── .github/
│ ├── ISSUE_TEMPLATE/ Bug, feature, and documentation issue forms
│ ├── workflows/check.yml The CI gate: just ci
│ ├── CODE_OF_CONDUCT.md
│ ├── PULL_REQUEST_TEMPLATE.md
│ ├── SECURITY.md
│ └── renovate.json Updates to the pinned versions
├── .zed/ Zed project settings and tasks
├── docs/adr/ The decisions of the project: foundations, doc conventions, toolchain
├── template/ What only the template needs: its contract, checks, and outputs
├── .envrc Enters the dev shell through direnv
├── flake.nix The dev shell, the git hooks, and the checks
├── flake.lock The pinned nixpkgs and inputs
├── justfile Tasks
├── AGENTS.md Hints for coding agents
├── README.md
└── LICENSE
Make a new project with Nix. It copies every file except the template/ folder, which holds what only the template needs. This is the preferred way:
nix flake new -t github:tabmadi/github-project-template my-projectThen follow these steps:
-
In the new folder, run
git initandgit add -A. A flake sees only the files that git tracks. -
Run
nix develop. It downloads the tools and installs the git hooks. -
Add your language tools to the dev shell in
flake.nix, and your checks underchecks. -
Fill in the
format,lint, andtestrecipes injustfilewith real commands. Keep the recipe names. -
Rewrite this README for the project, with the sections that ADR-0001 sets for its kind of repo.
-
Update the contacts in
.github/SECURITY.mdand the copyright line inLICENSE. -
Delete the line that starts with
A new copyfromAGENTS.md. -
Set the squash merge message to the pull request title, with no body, and turn off the other merge styles:
gh api -X PATCH repos/OWNER/REPO -f squash_merge_commit_title=PR_TITLE -f squash_merge_commit_message=BLANK -F allow_merge_commit=false -F allow_rebase_merge=false
-
Add a
RENOVATE_TOKENrepository secret. Therenovateworkflow uses it to open update pull requests.
The button copies every file, the template/ folder included. Its first commit, Initial commit, is not a Conventional Commit.
-
Clone the new repository, and run
nix developin it. -
Run
just init. It removes thetemplate/folder and theA new copyline ofAGENTS.md. -
Replace the first commit of GitHub. This is safe before anyone else clones the repository:
git add -A git commit --amend -m "chore: start from <template> <release>" git push --force-with-lease -
Follow the steps above from step 2, and skip the step on
AGENTS.md. Your repository already has git.
The ADRs in docs/adr record every decision and the reason for it. template/adr/0000-template-contract.md records what makes this repo a template. ADR-0001 is the house style for all text.
Follow the Code of Conduct. Commit messages follow Conventional Commits, and the commit-msg hook checks them. Run just check before you open a pull request.
To report a vulnerability, follow SECURITY.md.
Apache License 2.0. See LICENSE.