Template
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>
87 lines
3.5 KiB
Markdown
87 lines
3.5 KiB
Markdown
# 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](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.
|
|
|
|
```
|
|
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:
|
|
```bash
|
|
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](ADOPTING.md).
|
|
|
|
## License
|
|
|
|
GNU Affero General Public License v3.0.
|