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>
67 lines
3.8 KiB
Markdown
67 lines
3.8 KiB
Markdown
# 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, rules
|
|
engine, Discourse/Redmine SoR policy, Docker-first conventions).
|
|
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
|
|
├── 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)
|
|
|
|
```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) |
|
|
| **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](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.
|