Template
mrcharles
3d83b07f30
Remove references to crush.json, hooks/, and Crush-specific enforcement from README, AGENTS.md, BASELINE-PROMPT.md, and PATTERNS.md. Generalize the commit footer to be harness-agnostic (<harness/tool> placeholder). Update PATTERNS.md decisions and scorecard to reflect the reversal: Crush hooks were studied but deliberately not shipped. The only remaining Crush mention explicitly states it is avoided for portability. The .crush/memory/ dir is kept as an optional Crush feature. 💘 Generated with Crush Assisted-by: Crush via Crush <crush@charm.land>
3.8 KiB
3.8 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, rules engine, Discourse/Redmine SoR policy, Docker-first conventions).
- 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
├── 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, Discourse pointers, 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
├── 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 (optional, Crush-only)
├── 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) |
| Rules engine | shellcheck, image pinning, container naming, required files, doc freshness, Discourse pointers, 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.