Template
mrcharles
0d76ca4ca5
The framework supports both technical operations (SSH/screen/CLI/harness) and knowledge work (Hermes/OWUI/Conduit via MCP/API). The Makefile is restored as a convenience layer over the scripts — use make or call scripts directly, whichever fits the interface you're working through. README rewritten with a Mode 1 / Mode 2 comparison table. AGENTS.md key commands now show both make and direct script invocation. ADOPTING.md updated to use make shorthand. The scripts remain the real entry points; make is shorthand. Mode 2 agents invoke the same scripts via container exec or MCP tool calls. 💘 Generated with Crush Assisted-by: Crush via Crush <crush@charm.land>
102 lines
4.2 KiB
Markdown
102 lines
4.2 KiB
Markdown
# 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.
|