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

refactor: remove Makefile, restructure as knowledge-first framework

Browse Source 
The primary value is the knowledge layer (markdown files that any agent
reads — Crush, OpenWebUI, Hermes, Conduit on iPhone). CLI tooling
(scripts, git hooks) is optional, for projects that use git/docker.

Changes:
- Remove Makefile entirely. All commands are now direct script invocations
  (bash scripts/check-rules.sh, bash scripts/setup-hooks.sh, etc.)
- Add scripts/test.sh stub (replaces make test)
- check-rules.sh: test-suite check now calls scripts/test.sh, not make test
- Rewrite README as three-layer architecture: knowledge → git hooks → docker
- Update all docs (AGENTS.md, BASELINE-PROMPT.md, ADOPTING.md, PATTERNS.md,
  STATUS.md) to remove every make reference

The framework now works for:
- CLI/harness users (git hooks + scripts + AGENTS.md)
- Non-CLI users (BASELINE-PROMPT.md loaded into any agent's system prompt)

💘 Generated with Crush

Assisted-by: Crush via Crush <crush@charm.land>
This commit is contained in:
mrcharles
2026-08-07 12:14:30 -05:00
parent 3d83b07f30
commit f5292183f4
11 changed files with 120 additions and 156 deletions
Download Patch File Download Diff File Expand all files Collapse all files
README.md
+71 -51
View File
@@ -1,66 +1,86 @@
# meta — cross-project best-practices template
# TSYSGroupAIOS — cross-project best-practices framework
This repo serves two purposes at once:
This repo serves a single purpose: **capture the operating knowledge that makes
AI agents effective, and make it portable to any agent interface.**
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.
It works in three layers — use whichever you need:
## What you get when you create a project from this template
## Layer 1: Knowledge (works everywhere)
The markdown files are the core product. Any agent — Crush, OpenWebUI, Hermes,
Conduit on an iPhone — reads them. No CLI, no git, no SSH required.
| File | What it does |
|---|---|
| **[BASELINE-PROMPT.md](BASELINE-PROMPT.md)** | The global working principles (13 sections). Paste into any agent's system prompt. |
| **AGENTS.md** | Project-level policy skeleton. Any agent that reads files picks this up automatically. |
| **[ADOPTING.md](ADOPTING.md)** | How to bring an existing project under this framework. |
| **[PATTERNS.md](PATTERNS.md)** | Why every decision was made (pattern extraction from 18 projects). |
| **STATUS.md** | Agent scratchpad template (token-efficiency, not system of record). |
| **WORKING.md** | Task tracker template (the only in-repo task list). |
| **questions-v1.md** | Git-tracked question log template for the human. |
**For non-CLI users (e.g. Conduit/iPhone/Hermes):** load `BASELINE-PROMPT.md`
into the agent's system prompt. That alone carries the operating principles.
Add `AGENTS.md` as project context for project-specific policy.
## Layer 2: Git hooks (for projects using git)
When a project uses git, copy in the enforcement scripts for mechanical checks
at commit/push time. Works under any agent — no harness coupling.
```
<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)
scripts/
├── setup-hooks.sh ← install git hooks (bash scripts/setup-hooks.sh)
├── pre-commit ← fast rule audit + hot-path bypass
├── pre-push ← full audit + clean-tree gate
├── check-rules.sh ← the rule audit engine
├── test.sh ← project test runner (override per project)
├── garden.sh ← doc-sprawl / Discourse-migration report
└── lib/common.sh ← shared bash library
```
## Quick start (for a new project)
## Layer 3: Docker lifecycle (for containerized projects)
```
scripts/docker-run.sh ← canonical ephemeral-container wrapper
scripts/up.sh ← docker compose up
scripts/down.sh ← docker compose down
docker-compose.yml.example ← lifecycle template
```
## What it enforces (layer 2)
`scripts/check-rules.sh` runs these checks:
- **shellcheck** (zero warnings incl. info-level, via Docker)
- **Docker image pinning** (no `:latest`)
- **Container naming** (explicit `container_name:`, never Docker defaults)
- **Required files** (AGENTS.md, STATUS.md, questions-v1.md, .env.example, etc.)
- **Doc freshness** (STATUS.md updated today)
- **Discourse pointer-header** (non-exempt .md must cite a Discourse URL)
- **WORKING.md completion** (no unchecked tasks at commit time)
- **CNW markers** (unresolved questions flagged)
- **Hygiene** (no merge-conflict markers)
- **Test suite** (scripts/test.sh, in full audit only)
## Creating a new project from this template
In Gitea: use this repo as a template (`TSYSGroupCorporate/TSYSGroupAIOS`).
Or clone and go:
```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
git clone ssh://git@git.knownelement.com:29418/TSYSGroupCorporate/TSYSGroupAIOS.git my-project
cd my-project
bash scripts/setup-hooks.sh
bash scripts/check-rules.sh --fast
```
## What it enforces
Fill in bracketed fields in `AGENTS.md`, override `scripts/test.sh`, start work.
| 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` |
## Adopting into an existing project
Configurable via env without editing hooks: `PROJECT_BANNED_COMMANDS`,
`PROJECT_BANNED_SUFFIXES`, `PROJECT_BANNED_ALLOW`, `PROJECT_SOURCE_SUFFIXES`,
`PROJECT_REQUIRED_FILES`.
See [ADOPTING.md](ADOPTING.md).
## The two extra docs (meta-authoring, optional)
## License
- **[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.
GNU Affero General Public License v3.0.