TSYSGroupCorporate/TSYSGroupAIOS
Template
1
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity

refactor: go harness-agnostic — drop Crush hooks, enforce Discourse SoR

Browse Source 
Apply answers to questions-v1.md (Q1–Q5):

- Q4: Remove crush.json and hooks/ entirely. All enforcement is now portable
  via git hooks (pre-commit/pre-push) + check-rules.sh + AGENTS.md prose.
  Works under Crush, OpenWebUI, Hermes, or any agent framework.
- Q5: Remove docs/JOURNAL.md. Redmine is the system of record for work;
  Discourse for docs. JOURNAL.md was a stopgap.
- Q3: Add mandatory Discourse pointer-header check to check-rules.sh. Any
  non-exempt tracked .md without a Discourse URL FAILs. All projects, no
  exceptions.
- Q2: Reference real CLI container invocation paths
  (KNEL-AIMiddleware/{redmine,discourse}-cli/) in AGENTS.md instead of the
  missing bin/ shortcuts.
- Q1: Note tea + docker login are preconfigured on TSYS workstations.

Also: make test default is now no-op pass so the template self-validates;
make validate now passes clean on the repo itself (17 PASS / 0 FAIL).

💘 Generated with Crush

Assisted-by: Crush via Crush <crush@charm.land>
This commit is contained in:
mrcharles
2026-08-07 12:04:04 -05:00
parent 374288a105
commit 9dc85ba41e
15 changed files with 121 additions and 268 deletions
Download Patch File Download Diff File Expand all files Collapse all files
AGENTS.md
+46 -41
View File
@@ -1,12 +1,11 @@
# <Project Name> — Agent Guidelines
> **Active agent:** Crush running <model> (<provider>). Permission mode: <yolo|normal>.
> **Read [`STATUS.md`](STATUS.md), [`.crush/memory/operational.md`](.crush/memory/operational.md), and [`questions-v1.md`](questions-v1.md) first, every session.**
> **Governing baseline:** [`BASELINE-PROMPT.md`](BASELINE-PROMPT.md) (parent project).
> **Active agent:** <agent/model>. **Permission mode:** <yolo|normal>.
> **Read [STATUS.md](STATUS.md), [`.crush/memory/operational.md`](.crush/memory/operational.md), and [questions-v1.md](questions-v1.md) first, every session.**
> **Governing baseline:** [`BASELINE-PROMPT.md`](BASELINE-PROMPT.md) (delete if your project doesn't ship it; the principles still apply).
This file is the project-level policy. The hooks and `scripts/check-rules.sh`
This file is the project-level policy. The git hooks and `scripts/check-rules.sh`
enforce the mechanical rules below; this document states the policy and intent.
Inherit from the baseline; specialize here.
---
@@ -18,7 +17,7 @@ Inherit from the baseline; specialize here.
2. **Read [STATUS.md](STATUS.md)** — current state, inbox, blockers, tactical notes.
3. **Read [`.crush/memory/operational.md`](.crush/memory/operational.md)** — access details, key IDs, gotchas.
4. **Read [questions-v1.md](questions-v1.md)** — open questions awaiting human input.
5. **Read [docs/JOURNAL.md](docs/JOURNAL.md)** — decisions and patterns already established.
5. **Check Redmine** — `redmine list --assigned-to-me -p <project-id>` for active work.
6. **Check current state:** `git log --oneline -10` and `make status`.
## Project Overview
@@ -31,7 +30,7 @@ Replace this bracketed text.>
> We have exited the "move fast and loose" phase. This is production
> infrastructure. The bar is the bar. (See `BASELINE-PROMPT.md`.)
<Adjust per project: is this in production? serving what? what's the blast radius?>
<Adjust per project: is this in production? serving what? blast radius?>
## Repository Layout
@@ -39,38 +38,53 @@ Replace this bracketed text.>
<root>/
├── AGENTS.md ← THIS FILE — project policy
├── STATUS.md ← agent scratchpad (token-efficiency; NOT the system of record)
├── WORKING.md ← the ONLY task tracker (todos tool is banned)
├── WORKING.md ← the ONLY in-repo task tracker
├── questions-v1.md ← git-tracked questions for the human (version up per round)
├── crush.json ← Crush PreToolUse hooks (behavioral guardrails)
├── .crush/memory/ ← operational memory read each session
├── hooks/ ← Crush agent hooks (block-todos, enforce-*, audit-*, exit-protocol)
├── scripts/
│ ├── setup-hooks.sh ← install git hooks into .git/hooks/
│ ├── pre-commit ← fast rule audit (hot-path bypass for status/journal)
│ ├── pre-commit ← fast rule audit (hot-path bypass for status/working)
│ ├── pre-push ← full audit + clean-tree gate
│ ├── check-rules.sh ← the rule audit engine (pass/warn/fail accumulator)
│ ├── 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)
├── docs/
│ └── JOURNAL.md ← append-only decision & pattern log
├── Makefile ← standard targets: setup/validate/lint/test/garden/up/down/status
├── Makefile ← standard targets: setup/validate/fast/lint/test/garden/up/down/status
├── docker-compose.yml.example ← lifecycle template (copy to docker-compose.yml)
└── .env.example ← copy to .env, fill in secrets
├── .env.example ← copy to .env, fill in secrets
└── .crush/memory/ ← operational memory read each session (if using Crush)
```
## Systems of Record (do not duplicate)
- **Redmine** is the single system of record for ALL project work — tickets, schedules, Gantt, dependencies. Use the `redmine-cli` tool. **Do not use Gitea issues.**
- **Discourse** is the single system of record for documentation. Use the `discourse-cli` tool. **Do not author long-form docs in gitea.**
- **Git-tracked `.md` files are stubs** that point to the relevant Discourse URL. Operational files that must live next to code (`AGENTS.md`, `STATUS.md`, `questions-v*.md`, `docs/JOURNAL.md`) are the documented exceptions.
- **Redmine** is the single system of record for ALL project work — tickets, schedules, Gantt, dependencies. Use the `redmine-cli`. **Do not use Gitea issues.** Reference tickets as `[#NNN]`.
- **Discourse** is the single system of record for documentation. Use the `discourse-cli`. **Do not author long-form docs in gitea.**
- **Git-tracked `.md` files are stubs** that point to the relevant Discourse topic URL. Operational files that must live next to code (`AGENTS.md`, `STATUS.md`, `questions-v*.md`) are the documented exceptions.
- `STATUS.md` is a scratchpad for token efficiency, **not** a system of record.
### CLI invocation (no bin/ shortcuts — invoke the real containers)
```
# redmine-cli (source: ~/projects/KNEL-AIMiddleware/redmine-cli/)
docker run --rm --env-file ~/projects/KNEL-AIMiddleware/redmine-cli/.env \
git.knownelement.com/reachableceo/redmine-cli:latest <command>
# subcommands: whoami, projects, statuses, list, show <id>, create, update <id>, close <id>
# discourse-cli (source: ~/projects/KNEL-AIMiddleware/discourse-cli/)
docker run --rm --env-file ~/projects/KNEL-AIMiddleware/discourse-cli/.env \
git.knownelement.com/reachableceo/discourse-cli:latest <command>
# subcommands: whoami, categories, cat-info, topics, show <id>, create, reply <id>, update <post_id>, delete <post_id>, search
```
### Redmine↔Discourse split (project decides the details)
- **Redmine**: working notes, evolving status, checklists, TODOs, ticket state, schedules.
- **Discourse**: synthesized decisions, runbooks, architecture docs, audit logs, reference material.
- Working notes → Redmine; synthesize durable knowledge → Discourse.
## Git Workflow
- **Use the `tea` CLI for pull requests.**
- **Work smart off master.** Branches on the workstation are encouraged for moving fast, exploring, and avoiding stash churn.
- **Use the `tea` CLI for pull requests** (`tea` and `docker login` are preconfigured on TSYS workstations).
- **Work smart off master.** Branches on the workstation are encouraged for moving fast.
- **Once work leaves the workstation, it goes through a PR.**
- **Commit & push policy:** ALWAYS commit and push automatically; NEVER wait to be asked. This overrides any default "never commit unless asked" behavior.
1. **Atomic commits** — one logical change per commit.
@@ -92,10 +106,10 @@ Replace this bracketed text.>
## Task Tracking
- **WORKING.md is the ONLY task tracker.** The `todos` tool is banned by hook.
- **WORKING.md is the only in-repo task tracker.** The system of record for tasks is Redmine; WORKING.md is the scratchpad for the current session.
- Only mark `[x]` after the work is verified complete.
- A commit is **blocked** (pre-commit + audit-before-git hook) while any task remains unchecked.
- Clear WORKING.md (to "all done") before responding to the user; the exit-protocol hook will not let you stop otherwise.
- A commit is **blocked** (pre-commit hook) while any task remains unchecked.
- Clear WORKING.md (to "all done") before responding to the user.
- **The human decides when the work is done and when to deploy.** Never declare "done" unilaterally.
## Questions
@@ -108,8 +122,8 @@ Replace this bracketed text.>
- **Stop over-thinking.** Get to code and output faster. Explore with code; gather ground truth. Do not burn tokens reasoning about things a quick command answers.
- **Ask questions early** via `questions-v(N).md`. Don't ruminate or self-debate at length.
- **Farm work out to deterministic tooling:** linters, LSPs, formatters, test runners. If Crush has an LSP wired up, use it; otherwise pull a Docker image and lint inside it. Do not parse huge code blocks in context.
- **Use sub-agents as subcontractors** for well-defined parallel deliverables, not as staff augmentation.
- **Farm work out to deterministic tooling:** linters, LSPs, formatters, test runners. If an LSP is wired up, use it; otherwise pull a Docker image and lint inside it. Do not parse huge code blocks in context.
- **Use sub-agents as subcontractors** (see BASELINE-PROMPT.md §12): scoped spec in, distilled deliverable out. Never read 10+ files sequentially; batch into 2-3 agent calls. Read the 3-4 files you'll edit yourself; delegate the rest.
## CI/CD
@@ -143,22 +157,13 @@ make down # bring it down
make status # repo status snapshot
```
## Status & Journal Maintenance
After any work session, you MUST:
1. **Update [STATUS.md](STATUS.md)** — reflect completed work, inbox, blockers. Update "Last updated". (check-rules.sh warns if stale.)
2. **Append to [docs/JOURNAL.md](docs/JOURNAL.md)** — one section per change (what, why, pattern, challenges, commit hash). Never delete or reorder. (check-rules.sh warns if no today-entry.)
3. **Synthesize to Redmine/Discourse** — status and journal are not the system of record; push decisions and durable docs there.
4. **Grep for stale paths** after any rename/restructure: `grep -rn 'old/path'` and fix in the same commit.
5. **Run `make garden`** periodically — migrate oversized `.md` to Discourse, leaving stubs.
## Enforcement Model (belt and suspenders)
Policy is enforced in two complementary layers:
- **Git hooks** (`.git/hooks/`, installed from `scripts/` by `make setup`) — *mechanical* checks at commit/push: shellcheck, image pinning, container naming, required files, doc freshness, WORKING.md completion, hygiene, full test suite on push.
- **Crush hooks** (`hooks/`, wired in `crush.json`) — *behavioral* guardrails at agent-tool-call time: ban the todos tool, block banned commands and host language tools, block edits to banned file types, run the fast audit before any commit/push, enforce the exit protocol.
Policy is enforced by **git hooks** (portable, harness-agnostic): `scripts/pre-commit`
runs a fast rule audit; `scripts/pre-push` runs the full audit + clean-tree gate.
Install with `make setup`. The checks are in `scripts/check-rules.sh` and cover:
shellcheck, image pinning, container naming, required files, doc freshness,
Discourse pointer-headers, WORKING.md completion, CNW markers, hygiene, and the test suite.
Bypass with `--no-verify` in genuine emergencies only.
@@ -169,7 +174,7 @@ Bypass with `--no-verify` in genuine emergencies only.
## DO
- Read STATUS.md, questions file, operational memory, and JOURNAL.md BEFORE starting work.
- Read STATUS.md, questions file, operational memory, and Redmine BEFORE starting work.
- Write a failing test first (TDD).
- Read files before editing. Use exact text matching.
- Run `make validate` before committing.