feat: bootstrap meta — cross-project best-practices template

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>
2026-08-07 11:17:53 -05:00
commit 374288a105
27 changed files with 1612 additions and 0 deletions
@@ -0,0 +1,70 @@
+# 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)
+
+```bash
+# 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](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](PATTERNS.md)** — the cross-project pattern extraction from 18 projects across two machines, with a standardization scorecard. Documents *why* every template decision was made.