TSYSGroupAIOS/ADOPTING.md

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)

# Create from the Gitea template, clone, done:
tea repo create --owner <org> --name <project> --template-from TSYSGroupCorporate/TSYSGroupAIOS
# or clone directly:
git clone ssh://git@git.knownelement.com:29418/TSYSGroupCorporate/TSYSGroupAIOS.git <project>
cd <project>
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

cd ~/projects/<existing-project>

# 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)

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

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:

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

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