# TSYSGroupAIOS — cross-project best-practices framework

This repo captures the operating knowledge that makes AI agents effective and
makes it work across **two usage modes**:

| | Mode 1: Technical Operations | Mode 2: Knowledge Work |
|---|---|---|
| **Interface** | SSH, screen, CLI | Web/app UI (Hermes, OWUI, Conduit) |
| **Agent** | Harness in a terminal (Crush, etc.) | Hermes/OWUI with docker/k8s/MCP |
| **Systems access** | CLI tools (ssh, conman, redmine-cli, discourse-cli) | MCP servers, API calls, container exec |
| **Focus** | Infra ops, switches, VMs, IAC | Document production, knowledge synthesis |
| **Who** | Engineers and ops agents | Anyone (including non-CLI users) |

Both modes share the same knowledge base. The difference is how the agent
touches systems: CLI tools vs MCP/APIs.

## The knowledge base (both modes)

These markdown files are the core. Any agent reads them — no CLI required.

| File | Purpose |
|---|---|
| **[BASELINE-PROMPT.md](BASELINE-PROMPT.md)** | The 13-section global working principles. Load into any agent's system prompt. |
| **AGENTS.md** | Project-level policy. Agents that read files pick 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 for the human. |

**Mode 2 minimal setup:** load `BASELINE-PROMPT.md` into the agent's system
prompt. Add `AGENTS.md` as project context. That's it — the agent has the full
operating discipline without touching a CLI.

## Mode 1: CLI tools (SSH/screen/harness)

For technical operations. Scripts provide enforcement and lifecycle:

```
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)
├── 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
```

A `Makefile` provides short verbs (`make setup`, `make validate`, `make fast`,
etc.) as a convenience. The scripts work standalone too — use whichever you prefer.

### What the enforcement layer checks

`scripts/check-rules.sh` runs: shellcheck (zero info-level), Docker image
pinning (no `:latest`), container naming, required files, doc freshness,
Discourse pointer-headers, WORKING.md completion, CNW markers, hygiene,
test suite.

## Mode 2: Hermes/OWUI/MCP (emerging)

For knowledge work and non-CLI users. No SSH or screen required.

The same scripts can be invoked via MCP tool calls or container exec. To adapt:

1. Load `BASELINE-PROMPT.md` into the agent's system prompt.
2. Point the agent at `AGENTS.md` for project policy.
3. Replace CLI tools with MCP equivalents:
   - `redmine-cli` → Redmine MCP server
   - `discourse-cli` → Discourse MCP server
   - `ssh/conman` → docker exec / k8s API / infrastructure MCP
4. If the project uses git, the hook scripts run the same checks whether
   triggered by a CLI commit or an MCP-initiated one.

Over time, the framework will gain MCP-native enforcement paths. Today, the
prose policy in `BASELINE-PROMPT.md` + `AGENTS.md` carries the discipline
even with zero tooling.

## 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
make setup    # or: bash scripts/setup-hooks.sh
make fast     # or: 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.