# 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.