Template
mrcharles
374288a105
Extract patterns from 18 projects across two machines (12 local infra + 6 remote personal/business via ssh survey). Ship a reusable Gitea template with AGENTS.md, 5 Crush PreToolUse hooks, git pre-commit/pre-push, a generalized rules engine, shared bash library, Makefile, lifecycle scripts, and gardening loop. Includes the canonical BASELINE-PROMPT.md (13 sections) and PATTERNS.md (standardization scorecard). The repo self-applies: it passes its own shellcheck (zero info-level), make fast, and all check-rules.sh checks. 💘 Generated with Crush Assisted-by: Crush via Crush <crush@charm.land>
4.2 KiB
4.2 KiB
meta — cross-project best-practices template
This repo serves two purposes at once:
- It is a Gitea template repository. Create new projects from it to inherit the full best-practices stack from the start (AGENTS.md, git hooks, Crush hooks, rules engine, Makefile, lifecycle scripts, gardening).
- It is the design source that maintains the global baseline prompt and the
cross-project pattern extraction. New projects can delete
BASELINE-PROMPT.mdandPATTERNS.mdif they don't want the authoring context — or keep them as reference.
What you get when you create a project from this template
<new-project>/
├── AGENTS.md ← fill in the bracketed fields, delete the rest
├── crush.json ← 5 Crush PreToolUse hooks (behavioral guardrails)
├── hooks/ ← block-todos, enforce-bash, enforce-rules, audit-before-git, exit-protocol
├── scripts/
│ ├── setup-hooks.sh ← install git hooks (run once: make setup)
│ ├── pre-commit / pre-push ← fast audit / full audit + clean-tree gate
│ ├── check-rules.sh ← rule audit engine (shellcheck, image pin, container naming, required files, freshness, hygiene, tests)
│ ├── docker-run.sh ← canonical ephemeral-container wrapper
│ ├── up.sh / down.sh ← docker-compose lifecycle wrappers
│ ├── garden.sh ← doc-sprawl / Discourse-migration report
│ └── lib/common.sh ← shared bash library (colors, log_*, docker_run, check)
├── Makefile ← setup/validate/fast/lint/garden/up/down/status/clean
├── STATUS.md ← agent scratchpad (token-efficiency; has Inbox)
├── WORKING.md ← the only task tracker (todos tool banned)
├── questions-v1.md ← git-tracked question log for the human
├── docs/JOURNAL.md ← append-only decision & pattern log
├── docker-compose.yml.example ← lifecycle template (copy to docker-compose.yml)
├── .env.example ← secrets/config template
├── .gitignore
├── .crush/memory/operational.md ← per-session operational memory skeleton
├── BASELINE-PROMPT.md ← the global working principles (delete if unwanted)
└── PATTERNS.md ← the pattern extraction analysis (delete if unwanted)
Quick start (for a new project)
# Create from this Gitea template, then:
cd my-new-project
git init # if not already
make setup # install git hooks
make fast # confirm baseline passes
# Fill in bracketed fields in AGENTS.md (project name, overview, model, etc.)
# Define `make test` for your stack
# Delete BASELINE-PROMPT.md and PATTERNS.md if you don't want them
What it enforces
| Layer | What | How |
|---|---|---|
| Git hooks | mechanical checks at commit/push | scripts/pre-commit (fast audit + hot-path bypass), scripts/pre-push (full audit + clean-tree gate) |
| Crush hooks | behavioral guardrails at tool-call time | hooks/ wired in crush.json: ban todos, block banned commands + host language tools, block banned file types, audit before git ops, exit protocol |
| Rules engine | shellcheck, image pinning, container naming, required files, doc freshness, WORKING.md completion, CNW markers, hygiene, test suite | scripts/check-rules.sh (--fast for pre-commit, --quiet for pre-push) |
| Makefile | standard verbs everywhere | make setup/fast/validate/lint/test/garden/up/down/status/clean |
Configurable via env without editing hooks: PROJECT_BANNED_COMMANDS,
PROJECT_BANNED_SUFFIXES, PROJECT_BANNED_ALLOW, PROJECT_SOURCE_SUFFIXES,
PROJECT_REQUIRED_FILES.
The two extra docs (meta-authoring, optional)
- BASELINE-PROMPT.md — the canonical global working principles (13 sections), distilled from operating notes. Projects inherit it; they don't need to ship it.
- PATTERNS.md — the cross-project pattern extraction from 18 projects across two machines, with a standardization scorecard. Documents why every template decision was made.