gh-template

Agent-first GitHub repo template with extensive AI agent configs, agent-traversable template files (machine-readable "machreadified", non-prose), git hooks, automation scripts, asset management, metadata sanitzation

 

Structure

.hooks/
├── pre-commit              ← em-dash policy + metadata strip
├── pre-push                ← Touch ID gate (shelllock) + health check (large files, embedded repos)
├── post-checkout           ← `.gitconfig` include (hooks path)
└── scripts/
    ├── setup.sh            ← one-time setup after clone
    ├── set-remote.sh       ← set origin from repo.spine.json (remote.prefer / origin_url)
    ├── clearmeta.sh
    ├── gen-social.sh
    ├── health-check.sh
    └── upload-cloudinary.sh
.github/
└── templates/
    ├── README.template.md 
    ├── TODOs.template.md       ← copy to root → TODOs.md
    ├── _0/                     ← copy to root (cp -r) → gitignored working dir (_archive, _artifacts, _plans)
    ├── .gitignore.template     ← mega gitignore (set & forget)
    ├── timeline.template.json  ← project timeline/milestones
    └── [agent configs]/        ← aider, claude, codex, cursor, etc.
.gitconfig                  ← repo-level git config (core.hooksPath)
git-template/               ← optional: Git init template (post-checkout reminder after clone)
├── hooks/
│   └── post-checkout       ← prints "Run .hooks/scripts/setup.sh" until setup is run
assets/
├── icons/
│   └── agents/                 
└── social-preview-blank.png    ← social preview (1280x640)
repo.spine.json 

.github/ is almost entirely templates you copy out (no Actions/workflows here). Forge-agnostic; GitHub-only where a tool expects it (e.g. Copilot → .github/copilot-instructions.md).

Setup

# create repo from template in GitHub UI
# clone + activate hooks
git clone <your-repo-url> && cd <path-to-your-repo>
.hooks/scripts/setup.sh

# edit repo.spine.json (project details)
cp ".github/templates/.gitignore.template" ".gitignore"
cp ".github/templates/timeline.template.json" "timeline.json" # agents auto-extend this
cp ".github/templates/TODOs.template.md" "TODOs.md"
cp -r ".github/templates/_0" .


# replace this README with your project README (run only when done with setup)
cp .github/templates/README.template.md README.md  
# then replace placeholders (see "Template copy & placeholders" below)

Step 2 is mandatory - hooks don't activate until you run setup.sh.

Remote (SSH vs HTTPS)

In repo.spine.json, set remote to control origin:

Key	Values	Effect
prefer	"ssh"	Set origin to git@host:slug.git (default; use when SSH is set globally).
prefer	"auto"	Leave current URL as-is.
prefer	"https"	Set origin to https://host/slug.git.
origin_url	"git@github.com:user/repo.git" or any URL	Overrides; use this to pin exact URL.

Default is ssh so repos created from this template match a global SSH preference (e.g. git config --global url.git@github.com:.insteadOf https://github.com/). After editing, run .hooks/scripts/set-remote.sh (or re-run setup.sh).

Included

Agent configs

	Agent	Files	Site
	Cursor	.cursor/rules/*.mdc, .cursorignore	cursor.com
	Copilot	.github/copilot-instructions.md	GitHub Copilot
	Claude	CLAUDE.md	anthropic.com
	Gemini	GEMINI.md	ai.google.dev
	Codex	AGENTS.md	openai.com
	Windsurf	.windsurfrules	codeium.com
	Mistral	.vibe/config.toml	mistral.ai
	Cline	.clinerules/*.md	cline.dev
	Aider	.aider.conf.yml, CONVENTIONS.md	aider.chat
	Devin	devin.md	devin.ai
	Replit	.replit	replit.com
	Continue	.continue/config.json	continue.dev
	Tabnine	.tabnine/	tabnine.com
	Cody	.sourcegraph/	sourcegraph.com
	JetBrains AI	.aiassistant/rules/*.md	jetbrains.com/ai
	Amazon Q	.amazonq/rules/*.md	AWS Amazon Q
	Codeium	.codeiumignore	codeium.com
	Gemini CLI	GEMINI.md, .gemini/settings.json	geminicli.com
	v0	v0.json	v0.dev
	Bolt	bolt.json	bolt.new
	Lovable	lovable.json	lovable.dev
	CodeRabbit	.coderabbit.yaml	coderabbit.ai
	Codegen	AGENTS.md	codegen.com
	Sweep	sweep.yaml, SWEEP.md	sweep.dev
	Roo	.roomodes	roo.codes
	Augment / Auggie	.augment/, .augment/commands/	augmentcode.com
	Junie	.junie/AGENTS.md, .junie/guidelines.md, .junie/skills/, .junie/mcp/mcp.json	junie.jetbrains.com
	Supermaven	.supermaven/	supermaven.com
	Warp	warp.md	warp.dev
	Zed	.rules	zed.dev
	Void	.voidrules, .void/rules/	voideditor.com
	Aide	.aide/	aide.dev
	Goose	.goosehints	goose.ai
	Amp	AMP.md	useamp.com
	Trae	.trae/project_rules.md, .trae/user_rules.md	gettrae.com
	Kiro	.kiro/steering/	kiro.ai
	Graphite	.graphite/	graphite.com
	Greptile	.greptile/	greptile.com
	SWE-agent	.swe-agent.yaml	swe-agent.com
	OpenHands	.openhands/, .agents/skills/, AGENTS.md	openhands.dev
	Mentat	.mentat/	mentat.ai
	Pieces	.pieces/	pieces.app
	Capy	.capy/	capy.ai
	Tonkotsu	.tonkotsu/	tonkotsu.ai
	Sourcery	.sourcery.yaml	sourcery.ai
	Qodo	.qodo/	qodo.ai
	Blackbox	.blackbox/	blackbox.ai
	Pear AI	~/.pearai/config.json	pear.ai
	Droid	.droid.yaml	droid.ai
	OpenCode	opencode.json	opencode.ai
	Kilo	.kilocode/launchConfig.json	kilocode.com
	Qwen CLI	.env, .qwen-ignore	qwen.ai
	Kimi CLI	AGENTS.md	moonshot.cn
	Qoder	.qoder/	qoder.com
	Traycer	.traycer/	traycer.com
	Conductor	conductor.json	conductor.com
	Antigravity	.antigravity	antigravity.dev
	Superset	.superset/config.json	superset.com
	Zencoder	.zencoder/	zencoder.ai

Git forges

	Forge	Conventions	Site
	GitHub	.github/ (Actions, templates); Copilot → .github/copilot-instructions.md	github.com
	GitLab	.gitlab-ci.yml, .gitlab/	gitlab.com
	Codeberg	Forgejo; same git + .hooks/ workflow as this template	codeberg.org
	Gitea	Self-hosted; optional .gitea/ CI; origin is your host	gitea.io
	Bitbucket	bitbucket-pipelines.yml	bitbucket.org

Template copy & placeholders

	Template	Install to	Notes
	.github/templates/.gitignore.template	.gitignore
	.github/templates/timeline.template.json	timeline.json
	.github/templates/TODOs.template.md	TODOs.md
	.github/templates/_0/	./_0/	cp -r; gitignored scratch dirs
	.github/templates/README.template.md	README.md	when project README is ready
	.github/templates/<agent>/	see Agent configs	e.g. cp -r .github/templates/cursor/.cursor .

	Token	Replace in	Notes
	PROJECT_NAME	repo.spine.json - repo.name, social_preview.title
	One-liner description	repo.spine.json - repo.description
	project-name, tagline	README.md (from README.template)	same values as PROJECT_NAME / description
	<REPO_URL>, <REPO_NAME>	README.md - How to build
	owner.username, website, twitter	repo.spine.json - owner
	$REPO_OWNER, $REPO_TOKEN	repo.spine.json - access_control or .env
	$CLOUDINARY_*	env or repo.spine.json - cloudinary
	workflows.main_account	repo.spine.json - workflows	e.g. primary GitHub handle

Git hooks (platform-agnostic)

Hooks live in .hooks/ (not .github/hooks/) - works with any git platform (GitHub, GitLab, Codeberg, Gitea, Bitbucket, self-hosted).

One-time setup after clone: .hooks/scripts/setup.sh

Post-clone reminder (optional): To see a terminal message after every clone reminding you to run setup.sh, set Git's template once per machine (from this repo): git config --global init.templateDir "$(pwd)/git-template". Then every new clone of any repo created from this template will print the reminder until you run .hooks/scripts/setup.sh. The template dir can live anywhere; point init.templateDir at it.

Hook	Trigger	What it does
pre-commit	before commit	blocks unapproved em dashes, supports autofix/whitelist approval, strips file metadata
pre-push	before push	Touch ID gate when shelllock is installed (blocks AI push); then health check (large files, embedded repos)
post-checkout	after checkout	ensures repo .gitconfig include (hooks path)

Scripts

usage instructions per script at top of file

Script	Purpose
setup.sh	one-time setup after cloning (activates hooks)
set-remote.sh	set origin from repo.spine.json (remote.prefer or origin_url)
clearmeta.sh	NUCLEAR metadata strip; note: Apple SIP-protected provenance may persist
gen-social.sh	generate social preview image
health-check.sh	pre-push health check
upload-cloudinary.sh	upload assets to Cloudinary (set CLOUDINARY_CLOUD_NAME, CLOUDINARY_UPLOAD_PRESET env vars)

Em-dash hook quick use:

• autofix flagged files: EM_DASH_AUTOFIX=1 git commit ...
• approve current matches to whitelist: EM_DASH_APPROVE=1 git commit ...
• optional custom fixer: EM_DASH_FIXER=/path/to/fixer.sh git commit ...

timeline.json

• Append-only project memory
• timestamped ledger/makeshift database for full traceability/auditability
• AI agents extend timeline.json as you work (or manually invoke via /timeline slash command → .github/templates/cursor/commands/timeline.md)

Why: Context persists across sessions → when you return to a project, agents can read timeline to understand what happened, what decisions were made, what's blocked

Contact