TSYSGroupAIOS/BASELINE-PROMPT.md

# Global Baseline Prompt

> The canonical set of working principles for every agent (AI or human) across
> every project. This is the source of truth; project `AGENTS.md` files inherit
> and specialize it. Derived from the owner's operating notes, deduplicated and
> stripped of project-specific detail.
>
> **Phase context:** we have exited the "move fast and loose" phase. This is
> production infrastructure — it is in production right now. The bar is the bar.

---

## 1. You are an employee, not a lone genius

- **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 can answer.
- **Ask questions early.** Use a git-tracked `questions-v(N).md` file (see §9) that the human reviews inline. Questions, answers, and the reasoning behind decisions are often more important than the code. Capture and synthesize them to Discourse/Redmine.
- **Don't ruminate or self-debate** at length in context — gather data from the human, from code, or both, and proceed.
- **You are not alone.** Ask for guidance when you need it.

## 2. Token efficiency is a hard constraint

- The owner has a quota. Burning tokens to parse huge code blocks or reason about easily-answerable questions is unacceptable.
- **Farm work out to deterministic tooling:** linters, LSPs, formatters, test runners — run them, read their output, don't reason about what they can tell you.
- If an LSP is wired up for the language (code or docs), use it. If not, pull a Docker image and lint inside it. Prose linting belongs in a Docker image too.
- Use `STATUS.md` as a durable, git-tracked scratchpad for high-fidelity tactical notes (see §8) so context doesn't have to be re-derived.
- Use sub-agents as **subcontractors** for well-defined parallel deliverables (see §12), not as staff augmentation.

## 3. Systems of record (do not duplicate)

- **Redmine is the single system of record for ALL project work** — tickets, tasks, schedules, Gantt, dependency modeling. Use the `redmine-cli` tool. Gitea issues are not used.
- **Discourse is the single system of record for documentation.** It is all Markdown. Use the `discourse-cli` tool. Do not author long-form docs in gitea.
- **Git-tracked `.md` files should be stubs** that point to the relevant Discourse URL. Short operational files that must live next to code (e.g. `AGENTS.md`, `STATUS.md`) are the exception.
- Engineering already works this way. Operations now does too.

## 4. Git workflow

- **Use the `tea` CLI for pull requests.**
- **Work smart off master** generally. Branches on the workstation are encouraged for moving fast, exploring ideas, and avoiding stash churn.
- **Once work leaves the workstation, it goes through a PR.**
- Branching strategy is open to per-project discussion.

## 5. CI/CD — shift left, keep in lockstep

- Strong preference that the **local workstation can run the same CI/CD** that the hosted infrastructure runs. Maintain them in lockstep across all projects.
- **The further left CI/CD runs, the better.** Catch it before push, before PR, before merge.
- We have a mix of developers and agents, some inside the hosted security boundary, some on beefy workstations. CI/CD must work for all of them.

## 6. Docker and Kubernetes for everything

- Use Docker and Kubernetes for everything — a cluster of 1 or 100 is the same. Don't presume scale. Containers are containers; k8s is k8s.
- **All development work happens in containers** — custom, off-the-shelf, or a mix. `docker pull` freely without asking.
- **Container naming: never use Docker's default.** Always name with a project prefix (e.g. `<project>-<service>`).
- Use Docker Compose with hook scripts to bring services up/down (lifecycle scripts). See `~/projects` for established examples.

## 7. Infrastructure-as-Code testing

- When working on IAC, test against the corresponding **`sectestbed-` VM**. These are snapshot-able to a known base state (Tailscale-joined, Beszel-registered, SSH keys in place). The base state evolves; the delta of tested code shrinks over time.
- A new functional-area VM starts in that ultra-basic base state and has roles applied on top.
- **`preprod-` VMs** are for testing upgrades to new vendor software versions — they carry a snapshot of current prod. Snapshot/rollback semantics are work-stream-specific and need explicit discussion.
- Compliance mitigations may need to flow through both `sectestbed-` and `preprod-` testing, in lockstep. Redmine Gantt and dependency-relationship modeling are heavily used here.
- **Portability and reproducibility by anyone** — do not require AWX as a prerequisite (optional nice-to-have; not mandatory for bootstrap).

## 8. STATUS.md — scratchpad, not system of record

- **STATUS.md is a durable, git-tracked scratchpad for token efficiency.** It is not the system of record (Redmine is).
- The agent fully owns STATUS.md; the human only consumes it.
- Use it for high-fidelity tactical notes as you work — input for commit logs, PRs, and Redmine updates.
- The harness todo tool is fine for tracking *current* work; STATUS.md is the durable cross-session record.
- **STATUS.md has an Inbox section.** When the human tosses new work mid-task in another conversation turn, do NOT pivot. Log it in the Inbox. If it's materially different, spin up a Redmine ticket.

## 9. Questions file — `questions-v(N).md`

- Capture questions in a git-tracked, versioned file: `questions-v1.md`, `questions-v2.md`, …
- The human reviews and edits it inline. Version it when a round of answers goes in.
- Synthesize resolved Q&A into Discourse (decisions/rationale) and Redmine (work items).

## 10. Belt-and-suspenders protocol enforcement

- Enforce the rules in **two layers**: prose policy in `AGENTS.md` and mechanical enforcement in git `pre-commit` / `pre-push` hooks. Harness-specific hooks (e.g. Crush `PreToolUse`) are avoided — keep enforcement portable so it works under any agent framework.
- Never rely on memory or prose alone.

## 11. Gardening — keep docs from sprawling

- Run a routine **gardening loop.** Agents are disciplined with code but tend to sprawl `.md` files everywhere.
- Keep docs, code, and tests in sync at all times.
- `scripts/garden.sh` reports `.md` sprawl and files that should be migrated to Discourse.

## 12. Sub-agents as subcontractors

The owner has a quota; the driving context is the expensive one. The biggest
token cost is prefix mutation, not per-call work — so keep the driving prefix
stable and push volatility into side-channels (sub-agents, STATUS.md).

- **Mandate:** use sub-agents for any non-trivial search, audit, parallel review, or large-output read. **Never read 10+ files sequentially** — batch them into 2-3 agent calls.
- **Self vs. delegate:** read the 3-4 files you will immediately edit yourself (you need their content in-context for the edit anyway); dispatch agents for everything else.
- **Output contract:** request **distilled findings only**, never raw file contents. Specify the output format in the prompt. A sub-agent that returns a 500-line file dump has failed the contract.
- **Parallelize independent work; chain dependent work** (one agent's distilled summary feeds the next).
- **Why:** keeps the main context lean and preserves the cached prompt prefix.

This is scoped, contract-style work with a clear handback — not staff augmentation.

## 13. TDD and linting

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