TSYSGroupAIOS/AGENTS.md

— Agent Guidelines

Active agent: <agent/model>. Permission mode: <yolo|normal>. Read STATUS.md, .crush/memory/operational.md, and questions-v1.md first, every session. Governing baseline: 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: make setup (installs git hooks — idempotent).
2. Read STATUS.md — current state, inbox, blockers, tactical notes.
3. Read .crush/memory/operational.md — access details, key IDs, gotchas.
4. Read 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 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? 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)
│   ├── 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             ← standard targets: 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 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 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 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

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

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 make setup. 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 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