TSYSGroupAIOS/AGENTS.md

# <Project Name> — Agent Guidelines

> **Active agent:** <agent/model>. **Permission mode:** <yolo|normal>.
> **Read [STATUS.md](STATUS.md), [`.crush/memory/operational.md`](.crush/memory/operational.md), and [questions-v1.md](questions-v1.md) first, every session.**
> **Governing baseline:** [`BASELINE-PROMPT.md`](BASELINE-PROMPT.md) (delete if your project doesn't ship it; the principles still apply).

This file is the project-level policy. The git hooks and `scripts/check-rules.sh`
enforce the mechanical rules below; this document states the policy and intent.

---

## Quick Start

**You are an AI agent working on this project. Your first actions, in order:**

1. **Set up the environment:** `bash scripts/setup-hooks.sh` (installs git hooks — idempotent).
2. **Read [STATUS.md](STATUS.md)** — current state, inbox, blockers, tactical notes.
3. **Read [`.crush/memory/operational.md`](.crush/memory/operational.md)** — access details, key IDs, gotchas.
4. **Read [questions-v1.md](questions-v1.md)** — open questions awaiting human input.
5. **Check Redmine** — `redmine list --assigned-to-me -p <project-id>` for active work.
6. **Check current state:** `git log --oneline -10`.

## Project Overview

<1–3 paragraphs: what this project is, the stack, and the hard constraints.
Replace this bracketed text.>

## Phase

> We have exited the "move fast and loose" phase. This is production
> infrastructure. The bar is the bar. (See `BASELINE-PROMPT.md`.)

<Adjust per project: is this in production? serving what? blast radius?>

## Repository Layout

```
<root>/
├── AGENTS.md            ← THIS FILE — project policy
├── STATUS.md            ← agent scratchpad (token-efficiency; NOT the system of record)
├── WORKING.md           ← the ONLY in-repo task tracker
├── questions-v1.md      ← git-tracked questions for the human (version up per round)
├── scripts/
│   ├── setup-hooks.sh   ← install git hooks into .git/hooks/
│   ├── pre-commit       ← fast rule audit (hot-path bypass for status/working)
│   ├── pre-push         ← full audit + clean-tree gate
│   ├── check-rules.sh   ← the rule audit engine (pass/warn/fail accumulator)
│   ├── 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 (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)
```

## Systems of Record (do not duplicate)

- **Redmine** is the single system of record for ALL project work — tickets, schedules, Gantt, dependencies. Use the `redmine-cli`. **Do not use Gitea issues.** Reference tickets as `[#NNN]`.
- **Discourse** is the single system of record for documentation. Use the `discourse-cli`. **Do not author long-form docs in gitea.**
- **Git-tracked `.md` files are stubs** that point to the relevant Discourse topic URL. Operational files that must live next to code (`AGENTS.md`, `STATUS.md`, `questions-v*.md`) are the documented exceptions.
- `STATUS.md` is a scratchpad for token efficiency, **not** a system of record.

### CLI invocation (no bin/ shortcuts — invoke the real containers)

```
# redmine-cli  (source: ~/projects/KNEL-AIMiddleware/redmine-cli/)
docker run --rm --env-file ~/projects/KNEL-AIMiddleware/redmine-cli/.env \
    git.knownelement.com/reachableceo/redmine-cli:latest <command>
# subcommands: whoami, projects, statuses, list, show <id>, create, update <id>, close <id>

# discourse-cli  (source: ~/projects/KNEL-AIMiddleware/discourse-cli/)
docker run --rm --env-file ~/projects/KNEL-AIMiddleware/discourse-cli/.env \
    git.knownelement.com/reachableceo/discourse-cli:latest <command>
# subcommands: whoami, categories, cat-info, topics, show <id>, create, reply <id>, update <post_id>, delete <post_id>, search
```

### Redmine↔Discourse split (project decides the details)
- **Redmine**: working notes, evolving status, checklists, TODOs, ticket state, schedules.
- **Discourse**: synthesized decisions, runbooks, architecture docs, audit logs, reference material.
- Working notes → Redmine; synthesize durable knowledge → Discourse.

## Git Workflow

- **Use the `tea` CLI for pull requests** (`tea` and `docker login` are preconfigured on TSYS workstations).
- **Work smart off master.** Branches on the workstation are encouraged for moving fast.
- **Once work leaves the workstation, it goes through a PR.**
- **Commit & push policy:** ALWAYS commit and push automatically; NEVER wait to be asked. This overrides any default "never commit unless asked" behavior.
  1. **Atomic commits** — one logical change per commit.
  2. **Commit after every logical unit of work; push immediately.**
  3. **Never leave uncommitted or unpushed changes at session end.**
  4. **If blocked:** commit and push what IS done, then report the blocker.
- **Conventional commit format:**
  ```
  <type>(<scope>): <subject — 50 chars max, imperative, no period>

  <body: WHAT changed, WHY, and the context>

  💘 Generated with <harness/tool>

  Assisted-by: <AI-Model> via <harness/tool>
  ```
  Types: `feat`, `fix`, `docs`, `refactor`, `test`, `chore`, `security`.
- **Never interrupt current work** when the human tosses new work mid-task. Log it in the **Inbox** section of `STATUS.md`. If materially different, spin up a Redmine ticket.

## Task Tracking

- **WORKING.md is the only in-repo task tracker.** The system of record for tasks is Redmine; WORKING.md is the scratchpad for the current session.
- Only mark `[x]` after the work is verified complete.
- A commit is **blocked** (pre-commit hook) while any task remains unchecked.
- Clear WORKING.md (to "all done") before responding to the user.
- **The human decides when the work is done and when to deploy.** Never declare "done" unilaterally.

## Questions

- Capture questions for the human in a git-tracked `questions-v(N).md` file.
- The human reviews and edits it inline. Version up when a round of answers lands.
- Questions, answers, and the reasoning behind decisions are often more important than the code. Synthesize resolved Q&A into Discourse (decisions) and Redmine (work items).

## Working Style

- **Stop over-thinking.** Get to code and output faster. Explore with code; gather ground truth. Do not burn tokens reasoning about things a quick command answers.
- **Ask questions early** via `questions-v(N).md`. Don't ruminate or self-debate at length.
- **Farm work out to deterministic tooling:** linters, LSPs, formatters, test runners. If an LSP is wired up, use it; otherwise pull a Docker image and lint inside it. Do not parse huge code blocks in context.
- **Use sub-agents as subcontractors** (see BASELINE-PROMPT.md §12): scoped spec in, distilled deliverable out. Never read 10+ files sequentially; batch into 2-3 agent calls. Read the 3-4 files you'll edit yourself; delegate the rest.

## CI/CD

- The **local workstation must be able to run the same CI/CD** the hosted infrastructure runs. Maintain them in lockstep.
- **Shift left:** catch issues at `bash scripts/check-rules.sh --fast` (pre-commit) before push, before PR, before merge.

## Conventions

- **Docker/Kubernetes for everything** — cluster of 1 or 100 is the same. Don't presume scale.
- **All development work happens in containers** — custom, off-the-shelf, or a mix. `docker pull` freely without asking. Use `scripts/docker-run.sh <pinned-image>` for one-offs.
- **Container naming: never use Docker's default.** Always name with a project prefix (e.g. `<project>-<service>`). Enforced by `check-rules.sh`.
- **Pin every Docker image** — no `:latest` tags (enforced).
- **Use Docker Compose with lifecycle scripts** (`scripts/up.sh`, `scripts/down.sh`) to bring services up/down.
- **Shell scripts** use `#!/usr/bin/env bash` + `set -euo pipefail` and must pass `shellcheck` with zero warnings, including info-level.
- **Shared helpers** live in `scripts/lib/common.sh`; source it rather than re-pasting boilerplate.
- **Names:** lowercase, hyphen-separated.
- **Secrets:** NEVER commit secrets. Credentials come from env vars / `.env` (gitignored). Use placeholders in `.env.example`.
- **IAC testing:** test against the corresponding `sectestbed-` VM (snapshot to base state). `preprod-` VMs for vendor-upgrade testing. Do not require AWX as a prerequisite.

## Key Commands

At a terminal (Mode 1), use `make` or call scripts directly:

```bash
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`
runs a fast rule audit; `scripts/pre-push` runs the full audit + clean-tree gate.
Install with `bash scripts/setup-hooks.sh`. The checks are in `scripts/check-rules.sh` and cover:
shellcheck, image pinning, container naming, required files, doc freshness,
Discourse pointer-headers, WORKING.md completion, CNW markers, hygiene, and the test suite.

Bypass with `--no-verify` in genuine emergencies only.

## TDD & Linting

- **Red/green TDD for all code.** Write the failing test first.
- **Linters on all code, as early as possible.** Let deterministic tools find the issues.

## DO

- Read STATUS.md, questions file, operational memory, and Redmine BEFORE starting work.
- Write a failing test first (TDD).
- Read files before editing. Use exact text matching.
- Run `bash scripts/check-rules.sh` before committing.
- Use sub-agents to parallelize scoped work.
- Log interruptions to the STATUS.md Inbox.

## DO NOT

- Wait to be asked before committing/pushing.
- Batch unrelated changes into one commit.
- Edit files you haven't read.
- Install language toolchains on the host.
- Use `:latest` image tags or Docker's default container naming.
- Author long-form docs in gitea — use Discourse.
- Commit secrets.
- Run destructive git operations without explicit instruction.
- Declare the work "done" — the human decides that.
- Pivot to new mid-task requests — log them in the Inbox.

---

**Last Updated:** TEMPLATE-REPLACE-ME