TSYSGroupAIOS/AGENTS.md

# <Project Name> — Agent Guidelines

> **Active agent:** Crush running <model> (<provider>). 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) (parent project).

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

---

## Quick Start

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

1. **Set up the environment:** `make setup` (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. **Read [docs/JOURNAL.md](docs/JOURNAL.md)** — decisions and patterns already established.
6. **Check current state:** `git log --oneline -10` and `make status`.

## 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? what's the 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 task tracker (todos tool is banned)
├── questions-v1.md      ← git-tracked questions for the human (version up per round)
├── crush.json           ← Crush PreToolUse hooks (behavioral guardrails)
├── .crush/memory/       ← operational memory read each session
├── hooks/               ← Crush agent hooks (block-todos, enforce-*, audit-*, exit-protocol)
├── scripts/
│   ├── setup-hooks.sh   ← install git hooks into .git/hooks/
│   ├── pre-commit       ← fast rule audit (hot-path bypass for status/journal)
│   ├── pre-push         ← full audit + clean-tree gate
│   ├── check-rules.sh   ← the rule audit engine (pass/warn/fail accumulator)
│   ├── 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)
├── docs/
│   └── JOURNAL.md       ← append-only decision & pattern log
├── Makefile             ← standard targets: setup/validate/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
```

## 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` tool. **Do not use Gitea issues.**
- **Discourse** is the single system of record for documentation. Use the `discourse-cli` tool. **Do not author long-form docs in gitea.**
- **Git-tracked `.md` files are stubs** that point to the relevant Discourse URL. Operational files that must live next to code (`AGENTS.md`, `STATUS.md`, `questions-v*.md`, `docs/JOURNAL.md`) are the documented exceptions.
- `STATUS.md` is a scratchpad for token efficiency, **not** a system of record.

## Git Workflow

- **Use the `tea` CLI for pull requests.**
- **Work smart off master.** Branches on the workstation are encouraged for moving fast, exploring, and avoiding stash churn.
- **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 Crush

  Assisted-by: <AI-Model> via Crush <crush@charm.land>
  ```
  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 task tracker.** The `todos` tool is banned by hook.
- Only mark `[x]` after the work is verified complete.
- A commit is **blocked** (pre-commit + audit-before-git hook) while any task remains unchecked.
- Clear WORKING.md (to "all done") before responding to the user; the exit-protocol hook will not let you stop otherwise.
- **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 Crush has an LSP 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** for well-defined parallel deliverables, not as staff augmentation.

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

```bash
make setup      # install git hooks (run once after clone)
make fast       # fast rule audit (pre-commit equivalent)
make validate   # full audit (includes the test suite)
make lint       # shellcheck via docker
make test       # run the test suite (define per project)
make garden     # doc-sprawl / Discourse-migration report
make up         # bring up the docker-compose stack
make down       # bring it down
make status     # repo status snapshot
```

## Status & Journal Maintenance

After any work session, you MUST:

1. **Update [STATUS.md](STATUS.md)** — reflect completed work, inbox, blockers. Update "Last updated". (check-rules.sh warns if stale.)
2. **Append to [docs/JOURNAL.md](docs/JOURNAL.md)** — one section per change (what, why, pattern, challenges, commit hash). Never delete or reorder. (check-rules.sh warns if no today-entry.)
3. **Synthesize to Redmine/Discourse** — status and journal are not the system of record; push decisions and durable docs there.
4. **Grep for stale paths** after any rename/restructure: `grep -rn 'old/path'` and fix in the same commit.
5. **Run `make garden`** periodically — migrate oversized `.md` to Discourse, leaving stubs.

## Enforcement Model (belt and suspenders)

Policy is enforced in two complementary layers:

- **Git hooks** (`.git/hooks/`, installed from `scripts/` by `make setup`) — *mechanical* checks at commit/push: shellcheck, image pinning, container naming, required files, doc freshness, WORKING.md completion, hygiene, full test suite on push.
- **Crush hooks** (`hooks/`, wired in `crush.json`) — *behavioral* guardrails at agent-tool-call time: ban the todos tool, block banned commands and host language tools, block edits to banned file types, run the fast audit before any commit/push, enforce the exit protocol.

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 JOURNAL.md BEFORE starting work.
- Write a failing test first (TDD).
- Read files before editing. Use exact text matching.
- Run `make validate` 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