meta — cross-project best-practices template

This repo serves two purposes at once:

1. 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).
2. It is the design source that maintains the global baseline prompt and the cross-project pattern extraction. New projects can delete BASELINE-PROMPT.md and PATTERNS.md if 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.