Template
refactor: restore Makefile, document two usage modes
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>
This commit is contained in:
@@ -1,33 +1,40 @@
|
||||
# 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.**
|
||||
This repo captures the operating knowledge that makes AI agents effective and
|
||||
makes it work across **two usage modes**:
|
||||
|
||||
It works in three layers — use whichever you need:
|
||||
| | 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) |
|
||||
|
||||
## Layer 1: Knowledge (works everywhere)
|
||||
Both modes share the same knowledge base. The difference is how the agent
|
||||
touches systems: CLI tools vs MCP/APIs.
|
||||
|
||||
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.
|
||||
## The knowledge base (both modes)
|
||||
|
||||
| File | What it does |
|
||||
These markdown files are the core. Any agent reads them — no CLI required.
|
||||
|
||||
| File | Purpose |
|
||||
|---|---|
|
||||
| **[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. |
|
||||
| **[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 template for the human. |
|
||||
| **questions-v1.md** | Git-tracked question log 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.
|
||||
**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.
|
||||
|
||||
## Layer 2: Git hooks (for projects using git)
|
||||
## Mode 1: CLI tools (SSH/screen/harness)
|
||||
|
||||
When a project uses git, copy in the enforcement scripts for mechanical checks
|
||||
at commit/push time. Works under any agent — no harness coupling.
|
||||
For technical operations. Scripts provide enforcement and lifecycle:
|
||||
|
||||
```
|
||||
scripts/
|
||||
@@ -36,32 +43,40 @@ scripts/
|
||||
├── 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
|
||||
```
|
||||
|
||||
## Layer 3: Docker lifecycle (for containerized projects)
|
||||
A `Makefile` provides short verbs (`make setup`, `make validate`, `make fast`,
|
||||
etc.) as a convenience. The scripts work standalone too — use whichever you prefer.
|
||||
|
||||
```
|
||||
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 the enforcement layer checks
|
||||
|
||||
## What it enforces (layer 2)
|
||||
`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.
|
||||
|
||||
`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)
|
||||
## 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
|
||||
|
||||
@@ -71,8 +86,8 @@ 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
|
||||
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.
|
||||
|
||||
Reference in New Issue
Block a user