diff --git a/AGENTS.md b/AGENTS.md index bcab761..8012c12 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -97,9 +97,9 @@ docker run --rm --env-file ~/projects/KNEL-AIMiddleware/discourse-cli/.env \ - ๐Ÿ’˜ Generated with Crush + ๐Ÿ’˜ Generated with - Assisted-by: via Crush + Assisted-by: via ``` 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. diff --git a/BASELINE-PROMPT.md b/BASELINE-PROMPT.md index 3f29668..ff11c44 100644 --- a/BASELINE-PROMPT.md +++ b/BASELINE-PROMPT.md @@ -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 diff --git a/PATTERNS.md b/PATTERNS.md index 727e330..725b421 100644 --- a/PATTERNS.md +++ b/PATTERNS.md @@ -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) | --- diff --git a/README.md b/README.md index f27cb08..7a540cc 100644 --- a/README.md +++ b/README.md @@ -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: ``` / โ”œโ”€โ”€ 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`,