TSYSGroupCorporate/TSYSGroupAIOS
Template
1
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity

refactor: restore Makefile, document two usage modes

Browse Source 
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:
mrcharles
2026-08-07 12:17:40 -05:00
parent f5292183f4
commit 0d76ca4ca5
4 changed files with 113 additions and 46 deletions
Download Patch File Download Diff File Expand all files Collapse all files
ADOPTING.md
+2 -2
View File
@@ -16,8 +16,8 @@ tea repo create --owner <org> --name <project> --template-from TSYSGroupCorporat
# or clone directly:
git clone ssh://git@git.knownelement.com:29418/TSYSGroupCorporate/TSYSGroupAIOS.git <project>
cd <project>
bash scripts/setup-hooks.sh # install git hooks
bash scripts/check-rules.sh --fast # verify baseline
make setup # install git hooks (= bash scripts/setup-hooks.sh)
make fast # verify baseline (= bash scripts/check-rules.sh --fast)
```
Then edit `AGENTS.md` (fill bracketed fields), override `scripts/test.sh`, and start work.
AGENTS.md
+13 -7
View File
@@ -50,6 +50,7 @@ Replace this bracketed text.>
│ ├── up.sh / down.sh ← docker compose lifecycle wrappers
│ ├── garden.sh ← doc-sprawl / Discourse-migration report
│ └── lib/common.sh ← shared bash library (colors, log_*, docker_run, check)
├── Makefile ← convenience dispatch (setup/validate/fast/lint/test/garden/up/down/status)
├── docker-compose.yml.example ← lifecycle template (copy to docker-compose.yml)
├── .env.example ← copy to .env, fill in secrets
└── .crush/memory/ ← operational memory read each session (if using Crush)
@@ -145,16 +146,21 @@ docker run --rm --env-file ~/projects/KNEL-AIMiddleware/discourse-cli/.env \
## Key Commands
At a terminal (Mode 1), use `make` or call scripts directly:
```bash
bash scripts/setup-hooks.sh # install git hooks (run once after clone)
bash scripts/check-rules.sh --fast # fast rule audit (pre-commit equivalent)
bash scripts/check-rules.sh # full audit (includes test suite)
bash scripts/test.sh # run the test suite (override per project)
bash scripts/garden.sh # doc-sprawl / Discourse-migration report
bash scripts/up.sh # bring up the docker-compose stack
bash scripts/down.sh # bring it down
bash scripts/setup-hooks.sh # make setup — install git hooks
bash scripts/check-rules.sh --fast # make fast — fast audit (pre-commit)
bash scripts/check-rules.sh # make validate — full audit (incl tests)
bash scripts/test.sh # make test — run test suite
bash scripts/garden.sh # make garden — doc-sprawl report
bash scripts/up.sh # make up — bring up stack
bash scripts/down.sh # make down — bring down stack
```
Via MCP/API (Mode 2): invoke the same scripts through container exec or MCP
tool calls. The scripts are the real entry points; `make` is shorthand.
## Enforcement Model (belt and suspenders)
Policy is enforced by **git hooks** (portable, harness-agnostic): `scripts/pre-commit`
Makefile
+46
View File
@@ -0,0 +1,46 @@
# Makefile — convenience dispatch to scripts/.
#
# Not required. The scripts in scripts/ are the real entry points and work
# standalone. This file just gives you short verbs if you're at a terminal.
#
# In Mode 2 (Hermes/OWUI/MCP), agents call the scripts directly or via API —
# they don't need this file.
.PHONY: setup validate fast lint test garden up down status clean help
help: ## Show available targets
@grep -E '^[a-zA-Z_-]+:.*?## ' $(MAKEFILE_LIST) | awk 'BEGIN{FS=":.*?## "}{printf " \033[36m%-12s\033[0m %s\n", $$1, $$2}'
setup: ## Install git hooks
@bash scripts/setup-hooks.sh
validate: ## Full rule audit (includes tests)
@bash scripts/check-rules.sh
fast: ## Fast rule audit (pre-commit equivalent)
@bash scripts/check-rules.sh --fast
lint: ## Lint shell scripts (shellcheck via docker)
@docker run --rm -v "$$(pwd):/mnt" koalaman/shellcheck:stable \
$$(find . -path ./.git -prune -o -path ./.tmp -prune -o -path ./vendor -prune -o -path ./node_modules -prune -o \( -name '*.sh' -o -name '*.bash' \) -print | sed 's|^\./|/mnt/|') || true
test: ## Run the test suite (override per project)
@bash scripts/test.sh
garden: ## Doc-sprawl / Discourse-migration report
@bash scripts/garden.sh
up: ## Bring up the docker-compose stack
@bash scripts/up.sh
down: ## Bring down the docker-compose stack
@bash scripts/down.sh
status: ## Show repo status snapshot
@echo "== branch =="; git branch --show-current 2>/dev/null || echo "(no branch)"
@echo "== last commit =="; git log --oneline -1 2>/dev/null || true
@echo "== working tree =="; git status --short 2>/dev/null || echo "(not a git repo)"
@echo "== STATUS.md head =="; sed -n '1,12p' STATUS.md 2>/dev/null || echo "(no STATUS.md)"
clean: ## Remove build/test artifacts (override per project)
@echo "make clean: nothing to clean — override this in your project's Makefile."
README.md
+52 -37
View File
@@ -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.