# 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.