From 4c040c4673cdb0d0c49106e98d517b50a347bcc1 Mon Sep 17 00:00:00 2001 From: reachableceo Date: Fri, 7 Aug 2026 12:05:22 -0500 Subject: [PATCH] =?UTF-8?q?docs:=20add=20ADOPTING.md=20=E2=80=94=20how=20e?= =?UTF-8?q?xisting=20projects=20adopt=20this=20framework?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Step-by-step guide for brownfield adoption (e.g. PFVCluster): copy the enforcement layer (scripts, Makefile, hooks), install, fix failures incrementally, merge AGENTS.md, configure project env vars. Also documents greenfield creation from the Gitea template. 💘 Generated with Crush Assisted-by: Crush via Crush --- ADOPTING.md | 140 +++++++++++++++++++++++++++++++++++++++++ scripts/check-rules.sh | 2 +- 2 files changed, 141 insertions(+), 1 deletion(-) create mode 100644 ADOPTING.md diff --git a/ADOPTING.md b/ADOPTING.md new file mode 100644 index 0000000..fd02c79 --- /dev/null +++ b/ADOPTING.md @@ -0,0 +1,140 @@ +# ADOPTING.md — How to adopt this framework into an existing project + +> This is the guide you give to an agent (or human) that says: +> "Look at `~/daytoday/meta` and adopt its rules/patterns for this project." +> +> The framework lives at: `ssh://git@git.knownelement.com:29418/TSYSGroupCorporate/TSYSGroupAIOS.git` +> Template repo: https://git.knownelement.com/TSYSGroupCorporate/TSYSGroupAIOS + +--- + +## For a NEW project (greenfield) + +```bash +# Create from the Gitea template, clone, done: +tea repo create --owner --name --template-from TSYSGroupCorporate/TSYSGroupAIOS +# or clone directly: +git clone ssh://git@git.knownelement.com:29418/TSYSGroupCorporate/TSYSGroupAIOS.git +cd +make setup # install git hooks +make fast # verify baseline +``` + +Then edit `AGENTS.md` (fill bracketed fields), define `make test`, and start work. + +--- + +## For an EXISTING project (brownfield — e.g. PFVCluster) + +Adoption is incremental. You don't rewrite the project — you overlay the +framework's enforcement layer and adjust the project's existing conventions to +match. Do these steps in order: + +### Step 1: Copy the enforcement layer + +```bash +cd ~/projects/ + +# Bring in the framework files that don't already exist. +# Get them from the meta repo: +META=~/daytoday/meta + +# Scripts, hooks engine, Makefile, shared lib (the mechanical enforcement) +cp -n "$META/Makefile" . +mkdir -p scripts/lib +cp -n "$META/scripts/check-rules.sh" scripts/ +cp -n "$META/scripts/setup-hooks.sh" scripts/ +cp -n "$META/scripts/pre-commit" scripts/ +cp -n "$META/scripts/pre-push" scripts/ +cp -n "$META/scripts/docker-run.sh" scripts/ +cp -n "$META/scripts/garden.sh" scripts/ +cp -n "$META/scripts/lib/common.sh" scripts/lib/ +chmod +x scripts/*.sh scripts/pre-commit scripts/pre-push +``` + +### Step 2: Bring in the workflow files (if the project doesn't have them) + +```bash +cp -n "$META/STATUS.md" . # if the project's STATUS.md is a Discourse pointer, KEEP IT +cp -n "$META/WORKING.md" . +cp -n "$META/questions-v1.md" . +cp -n "$META/.env.example" . # only if the project doesn't have one +``` + +**Important:** if the project already uses Discourse as its SoR (like PFVCluster), +its existing `STATUS.md` may be a pointer stub to Discourse. In that case, do NOT +overwrite it — the project already has the right pattern. The template `STATUS.md` +is for projects that don't have one yet. + +### Step 3: Install git hooks and verify + +```bash +make setup # installs pre-commit + pre-push from scripts/ +make fast # see what passes and what fails +``` + +### Step 4: Fix the failures (incrementally) + +`make fast` will likely report failures — the project's existing code may not +pass shellcheck, or `.md` files lack Discourse pointers. **Fix these +incrementally; don't rewrite the project in one pass.** + +Common fixes: +- **shellcheck violations:** run `make lint` for details; fix warnings in the flagged files. +- **`:latest` image tags:** pin to a specific version in docker-compose / Dockerfile. +- **Container naming:** add `container_name:` to every service in docker-compose files. +- **Missing required files:** create `questions-v1.md`, `.env.example`, etc. +- **Discourse pointer-header:** for `.md` files that should be Discourse stubs, migrate content to Discourse and leave a pointer. For operational files (`AGENTS.md`, `STATUS.md`, etc.), add them to `PROJECT_DOC_EXEMPT`. + +### Step 5: Merge the project's AGENTS.md with the template + +Read both the project's existing `AGENTS.md` and the template's (`~/daytoday/meta/AGENTS.md`). +Merge by: +1. Keeping all project-specific content (VM paths, auth details, domain knowledge). +2. Adding the template's standard sections the project is missing (Quick Start, Systems of Record, Working Style, Key Commands, Enforcement Model). +3. Replacing any conflicting policy with the baseline (the template wins on cross-project conventions; the project wins on domain specifics). + +### Step 6: Configure project-specific env vars + +Set these in the project's `.env` or in the Makefile to customize checks: + +```bash +PROJECT_DOC_EXEMPT="AGENTS.md STATUS.md WORKING.md ..." # files that don't need Discourse pointers +PROJECT_DISCOURSE_HOST="community.turnsys.com" # Discourse instance +PROJECT_REQUIRED_FILES="..." # extra required files beyond the defaults +PROJECT_BANNED_SUFFIXES="py|js|ts" # banned production file types (optional) +``` + +### Step 7: Commit and push + +```bash +make validate # full audit should pass +git add -A +git commit -m "chore: adopt TSYSGroupAIOS framework (git hooks, rules engine, SoR policy)" +git push +``` + +--- + +## What NOT to change during adoption + +- **Don't rewrite existing code** that works. The framework enforces conventions going forward; fix existing violations incrementally via `make lint` / `make fast`. +- **Don't remove the project's Redmine/Discourse integration.** The framework *requires* it — the project already has it. Align the AGENTS.md prose to match. +- **Don't add `docs/JOURNAL.md`.** Redmine is the system of record for work; Discourse for docs. No JOURNAL.md. +- **Don't add Crush hooks.** The framework is harness-agnostic. Enforcement is git hooks + AGENTS.md prose only. + +--- + +## Quick reference: what the framework gives you + +| What | Files | Portable? | +|---|---|---| +| Git hooks (pre-commit/pre-push) | `scripts/pre-commit`, `scripts/pre-push` | Yes — any git, any agent | +| Rules engine | `scripts/check-rules.sh` | Yes | +| Shared bash library | `scripts/lib/common.sh` | Yes | +| Docker wrapper | `scripts/docker-run.sh` | Yes | +| Lifecycle scripts | `scripts/up.sh`, `scripts/down.sh` | Yes | +| Gardening | `scripts/garden.sh` | Yes | +| Makefile targets | `make setup/fast/validate/lint/test/garden/up/down/status` | Yes | +| Policy document | `AGENTS.md` | Yes — any agent framework reads it | +| Global baseline | `BASELINE-PROMPT.md` | Yes — reference it, don't need to ship it | diff --git a/scripts/check-rules.sh b/scripts/check-rules.sh index 6af9679..8407e06 100755 --- a/scripts/check-rules.sh +++ b/scripts/check-rules.sh @@ -140,7 +140,7 @@ fi # ---------------------------------------------------------------------------- $RULE_VERBOSE && log_step "Discourse pointer-header" DISCOURSE_HOST="${PROJECT_DISCOURSE_HOST:-community.turnsys.com}" -DOC_EXEMPT="${PROJECT_DOC_EXEMPT:-AGENTS.md STATUS.md WORKING.md README.md LICENSE .env.example questions-v*.md BASELINE-PROMPT.md PATTERNS.md}" +DOC_EXEMPT="${PROJECT_DOC_EXEMPT:-AGENTS.md STATUS.md WORKING.md README.md ADOPTING.md LICENSE .env.example questions-v*.md BASELINE-PROMPT.md PATTERNS.md}" POINTER_MISSING=0 while IFS= read -r -d '' f; do base="$(basename "$f")"