From 0d76ca4ca556779cdc0aa70b89e356abd1023840 Mon Sep 17 00:00:00 2001 From: reachableceo Date: Fri, 7 Aug 2026 12:17:40 -0500 Subject: [PATCH] refactor: restore Makefile, document two usage modes MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit 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 --- ADOPTING.md | 4 +-- AGENTS.md | 20 +++++++----- Makefile | 46 +++++++++++++++++++++++++++ README.md | 89 +++++++++++++++++++++++++++++++---------------------- 4 files changed, 113 insertions(+), 46 deletions(-) create mode 100644 Makefile diff --git a/ADOPTING.md b/ADOPTING.md index 50c463f..43ff244 100644 --- a/ADOPTING.md +++ b/ADOPTING.md @@ -16,8 +16,8 @@ tea repo create --owner --name --template-from TSYSGroupCorporat # or clone directly: git clone ssh://git@git.knownelement.com:29418/TSYSGroupCorporate/TSYSGroupAIOS.git cd -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. diff --git a/AGENTS.md b/AGENTS.md index ac8a664..7dc5f81 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -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` diff --git a/Makefile b/Makefile new file mode 100644 index 0000000..da4191f --- /dev/null +++ b/Makefile @@ -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." diff --git a/README.md b/README.md index c69f0d3..75828ee 100644 --- a/README.md +++ b/README.md @@ -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.