Template
fix: purge stale Crush references from all docs
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>
This commit is contained in:
@@ -97,9 +97,9 @@ docker run --rm --env-file ~/projects/KNEL-AIMiddleware/discourse-cli/.env \
|
||||
|
||||
<body: WHAT changed, WHY, and the context>
|
||||
|
||||
💘 Generated with Crush
|
||||
💘 Generated with <harness/tool>
|
||||
|
||||
Assisted-by: <AI-Model> via Crush <crush@charm.land>
|
||||
Assisted-by: <AI-Model> via <harness/tool>
|
||||
```
|
||||
Types: `feat`, `fix`, `docs`, `refactor`, `test`, `chore`, `security`.
|
||||
- **Never interrupt current work** when the human tosses new work mid-task. Log it in the **Inbox** section of `STATUS.md`. If materially different, spin up a Redmine ticket.
|
||||
|
||||
+2
-2
@@ -21,7 +21,7 @@
|
||||
|
||||
- The owner has a quota. Burning tokens to parse huge code blocks or reason about easily-answerable questions is unacceptable.
|
||||
- **Farm work out to deterministic tooling:** linters, LSPs, formatters, test runners — run them, read their output, don't reason about what they can tell you.
|
||||
- If Crush has an LSP wired up for the language (code or docs), use it. If not, pull a Docker image and lint inside it. Prose linting belongs in a Docker image too.
|
||||
- If an LSP is wired up for the language (code or docs), use it. If not, pull a Docker image and lint inside it. Prose linting belongs in a Docker image too.
|
||||
- Use `STATUS.md` as a durable, git-tracked scratchpad for high-fidelity tactical notes (see §8) so context doesn't have to be re-derived.
|
||||
- Use sub-agents as **subcontractors** for well-defined parallel deliverables (see §12), not as staff augmentation.
|
||||
|
||||
@@ -76,7 +76,7 @@
|
||||
|
||||
## 10. Belt-and-suspenders protocol enforcement
|
||||
|
||||
- Enforce the rules in **two layers**: prose policy in `AGENTS.md` and mechanical enforcement in git `pre-commit` / `pre-push` hooks (and Crush `PreToolUse` hooks where applicable).
|
||||
- Enforce the rules in **two layers**: prose policy in `AGENTS.md` and mechanical enforcement in git `pre-commit` / `pre-push` hooks. Harness-specific hooks (e.g. Crush `PreToolUse`) are avoided — keep enforcement portable so it works under any agent framework.
|
||||
- Never rely on memory or prose alone.
|
||||
|
||||
## 11. Gardening — keep docs from sprawling
|
||||
|
||||
+7
-7
@@ -38,7 +38,7 @@ These recur strongly and are baked into the template:
|
||||
1. **Auto-commit + push is mandatory and non-negotiable.** Stated with ALL-CAPS force in nearly every file. The template states the override-once and lets the hooks enforce it.
|
||||
2. **Atomic commits — one logical change per commit.** Universal.
|
||||
3. **Conventional-commit format** (`feat:`/`fix:`/`docs:`/…). Universal, but the **💘 Crush attribution footer is inconsistent**: mandated only by `football` and `KNELIAC`; absent on the remote entirely. **Decision:** the template mandates the footer once, in the AGENTS.md commit block.
|
||||
4. **Docker-only host hygiene.** The single most consistent convention across *both* machines (`KNEL-AIMiddleware`, `EngStack`, `LocalWorkstation`, `RCEO-PersonalAssistant`, `ThreeYearPlan`, `CharlesNWybleResume`). **Decision:** enforced by hook (`hooks/enforce-bash.sh`) and rule, and supported by `scripts/docker-run.sh`.
|
||||
4. **Docker-only host hygiene.** The single most consistent convention across *both* machines (`KNEL-AIMiddleware`, `EngStack`, `LocalWorkstation`, `RCEO-PersonalAssistant`, `ThreeYearPlan`, `CharlesNWybleResume`). **Decision:** the template's `check-rules.sh` enforces host hygiene via the Docker-only rule (no `:latest` tags, container naming) and `scripts/docker-run.sh` provides the canonical container wrapper. The Crush-specific `enforce-bash.sh` hook was removed for harness portability; the policy lives in AGENTS.md prose.
|
||||
5. **Sub-agents encouraged.** Explicit in `football`, `ThreeYearPlan`, `RCEO-PersonalAssistant`. **Decision:** standard section in the template.
|
||||
6. **No secrets in git (infra genre).** Inverted on the remote private repos (`RCEO-PersonalAssistant` deliberately commits credentials). **Decision:** the template keeps the infra stance (`.env` gitignored) as the default; private repos may opt out.
|
||||
|
||||
@@ -81,7 +81,7 @@ RCEO's crush.json wires five `PreToolUse` hooks that form a behavioral guardrail
|
||||
| `audit-before-git.sh` | `^bash$` | runs the fast audit before any `git commit`/`git push` |
|
||||
| `exit-protocol.sh` | `.*` | blocks stopping while WORKING.md has unchecked tasks |
|
||||
|
||||
**Decision:** the template generalizes all five into `hooks/`, configurable via env vars (`PROJECT_BANNED_COMMANDS`, `PROJECT_BANNED_SUFFIXES`, `PROJECT_SOURCE_SUFFIXES`, …) so they are project-agnostic. This is the template's highest-leverage feature: it converts the one-off RCEO invention into a reusable baseline.
|
||||
**Decision:** the Crush hooks were studied as the proof-of-concept and their *policies* (ban todos, Docker-only, banned file types, audit before git, exit protocol) were ported into AGENTS.md prose and `check-rules.sh` mechanical checks. The harness-specific `crush.json` + `hooks/` layer was **deliberately removed** for portability — the user is shifting away from Crush to OpenWebUI/Hermes, so all enforcement is git hooks + prose only.
|
||||
|
||||
---
|
||||
|
||||
@@ -145,7 +145,7 @@ Crush defines a priority chain (`$HOME/.config/crush/crush.json` → `crush.json
|
||||
- The highest-priority `.crush.json` layer is **unused anywhere**.
|
||||
- **No project sets `model` or `provider`** in config.
|
||||
|
||||
**Decision:** the template ships only the `hooks` block in `crush.json` (the universally-applicable part). LSP/MCP remain project-local concerns. A future shared global config could baseline common LSPs (bash, markdown) and universal MCPs (context7) once.
|
||||
**Decision:** no Crush config is shipped. The hooks layer was removed for harness portability. LSP/MCP remain project-local concerns.
|
||||
|
||||
---
|
||||
|
||||
@@ -153,7 +153,7 @@ Crush defines a priority chain (`$HOME/.config/crush/crush.json` → `crush.json
|
||||
|
||||
Only `PFVCluster` has operational memory (`.crush/memory/operational.md`). Its format — Identity → Tracking Systems (with READY/PARTIAL/BLOCKED status) → Tooling → Access chokepoints → Key commands → Mandatory rules → Credential TODOs — is strong and reusable.
|
||||
|
||||
**Decision:** the template ships `.crush/memory/operational.md` as a fill-in skeleton.
|
||||
**Decision:** the template ships `.crush/memory/operational.md` as a fill-in skeleton (optional, for projects using Crush).
|
||||
|
||||
---
|
||||
|
||||
@@ -188,11 +188,11 @@ The remote personal genre contributes a discipline absent from infra: a **task/s
|
||||
| Task runner | 5 conventions | one `Makefile` |
|
||||
| Git hook install | 3 mechanisms, 1 missing | one `setup-hooks.sh` (copy) |
|
||||
| Git hook coverage | 3/18 projects | every project, two hooks |
|
||||
| Crush hooks | 1/18 projects | every project, five hooks |
|
||||
| Crush hooks | 1/18 projects | not used (harness-agnostic; git hooks only) |
|
||||
| Rules engine | 1 project (Go-specific) | generalized, project-agnostic |
|
||||
| Crush memory | 1 project | skeleton in template |
|
||||
| Crush memory | 1 project | skeleton in template (optional, Crush-only) |
|
||||
| AGENTS.md structure | bespoke per project | canonical 10-section skeleton |
|
||||
| 💘 commit footer | 2/18 projects | mandated in template |
|
||||
| 💘 commit footer | 2/18 projects | mandated in template (harness-agnostic) |
|
||||
|
||||
---
|
||||
|
||||
|
||||
@@ -3,8 +3,8 @@
|
||||
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).
|
||||
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
|
||||
@@ -15,12 +15,10 @@ This repo serves two purposes at once:
|
||||
```
|
||||
<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)
|
||||
│ ├── 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
|
||||
@@ -29,11 +27,10 @@ This repo serves two purposes at once:
|
||||
├── 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
|
||||
├── .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)
|
||||
```
|
||||
@@ -56,8 +53,7 @@ make fast # confirm baseline passes
|
||||
| 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) |
|
||||
| **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`,
|
||||
|
||||
Reference in New Issue
Block a user