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	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	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 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:

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.

License

GNU Affero General Public License v3.0.