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)

```bash
# 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

```bash
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)

```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 |