mrcharles
f5292183f4
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>
3.5 KiB
TSYSGroupAIOS — cross-project best-practices framework
This repo serves a single purpose: capture the operating knowledge that makes AI agents effective, and make it portable to any agent interface.
It works in three layers — use whichever you need:
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 | 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 | How to bring an existing project under this framework. |
| 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.
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
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:
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
Fill in bracketed fields in AGENTS.md, override scripts/test.sh, start work.
Adopting into an existing project
See ADOPTING.md.
License
GNU Affero General Public License v3.0.