From 88a2f14415d40ccfef3956c060c961bd55929671 Mon Sep 17 00:00:00 2001 From: TSYS Group COO Date: Thu, 13 Aug 2026 11:10:32 -0500 Subject: [PATCH] docs: add AGENTS.md to orient agents working in this repo MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit This is a docs-only repo with no build/test/lint commands. AGENTS.md captures the non-obvious knowledge an agent needs: the org glossary (TSYS Group/KNEL/TCTC/PFV/CMMC/STIG/ITAR), the document map, the Discourse/Redmine systems-of-record workflow, doc conventions, and gotchas (missing LICENSE, k8s.md filename mismatch, snapshot dates). ๐Ÿ’˜ Generated with Crush Assisted-by: Crush:glm-5.2 --- AGENTS.md | 210 ++++++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 210 insertions(+) create mode 100644 AGENTS.md diff --git a/AGENTS.md b/AGENTS.md new file mode 100644 index 0000000..d706cbb --- /dev/null +++ b/AGENTS.md @@ -0,0 +1,210 @@ +# AGENTS.md โ€” org-buildout + +> **This is a docs-only repository.** There is no source code, no build system, +> no tests, and no lint config. Do not waste time searching for a `package.json`, +> `Makefile`, `Dockerfile`, or CI workflow โ€” none exist. The only "build" step is +> writing Markdown and committing it. (`.gitignore` line 2 states this explicitly: +> *"This is a docs-only repo โ€” no secrets, no code artifacts."*) + +This repo captures the **planning, architecture, and operational-design thinking** +behind TSYS Group's transition from a solo-founder operating model to an +AI-agent-augmented organization. It is shared publicly as a bootstrapping +reference (see `README.md`). Work here is *thinking and writing*, not coding. + +--- + +## What an agent does in this repo + +Edits and extends Markdown planning documents. Specifically: + +- Keep `README.md`'s document table in sync whenever a doc is added, renamed, or + substantially changes scope. +- Respect the `Status:` / `Date:` frontmatter convention on planning docs (see + "Document conventions" below). +- Preserve cross-references between docs (they point at each other heavily; see + "Document map"). +- Remember these are **working-session artifacts**, not the system of record โ€” + the workflow is to draft here, then *synthesize* to Discourse (docs) and + Redmine (work). See "Systems of record" below. + +--- + +## Organization glossary (read this first) + +The docs use dense, abbreviation-heavy org vocabulary. An agent cannot navigate +the content without this map. None of it is self-evident from any single file. + +| Term | Meaning | +|---|---| +| **TSYS Group** | The overall umbrella organization (multiple business entities) | +| **KNEL** | Known Element Enterprises โ€” owns and operates *all* IT/business systems for TSYS Group | +| **TCTC** | The Campus Trading Company โ€” financial-services entity under TSYS Group | +| **RedWFO** | RWSCP Family Office โ€” mission-critical, can preempt other workloads | +| **RWSCP** | A business entity (paired with RedWFO) | +| **PFV** | The physical site (private residence) hosting the on-prem Proxmox cluster | +| **PFVCluster** | The bare-metal Proxmox/k8s fleet at PFV โ€” the compute foundation | +| **RCEO / reachableceo** | Charles Lebsch, the founder (transitioning COO โ†’ CTO) | +| **AJ / Albert J Lebsch** | TSYS Group COO (oversees the AI agents) | +| **Hermes** | The AI-agent runtime/deployment model in use (one known sec note: full host access) | +| **Crush** | The CLI AI assistant harness; agents run as Crush sessions per identity | +| **FLO** | "Front-Line Offering" โ€” e.g. MorsePod is the FLO entry to CommonsNet | +| **CMMC L3** | Cybersecurity Maturity Model Certification Level 3 โ€” the compliance *goal* (not L1/L2) | +| **STIG** | Security Technical Implementation Guides โ€” targeted at highest (mission-critical classified) level | +| **ITAR** | International Traffic in Arms Regulations โ€” governs all technical operations | +| **SCIF** | Sensitive Compartmented Information Facility โ€” remote-access SCIF capability is a target | +| **FOCI** | Foreign Ownership Control Influence โ€” a concern (Cloudron VPS host Netcup is German-owned) | + +### Org reporting structure (as designed) + +``` +TSYS Group (Board of Directors) +โ”œโ”€โ”€ CTO โ€” Charles (R&D, architecture, tier-4 SME) +โ””โ”€โ”€ COO โ€” AJ Lebsch (operations; oversees AI agents) + โ”œโ”€โ”€ SVP KNEL (owns ALL IT/business systems) + โ”‚ โ”œโ”€โ”€ VP TechOps โ† the only function with real content today + โ”‚ โ”œโ”€โ”€ VP SecOps โ† does not exist yet + โ”‚ โ””โ”€โ”€ VP TechCompliance โ† Discourse cat 75 exists, empty + โ””โ”€โ”€ SVP TCTC + โ””โ”€โ”€ VP Finance / Accounting / Investing / Treasury / Trading +``` + +The AI **agents** are named after these roles (`vp-techops`, `vp-secops`, +`vp-techcompliance`, `coo`, `svp-knel`, `svp-tctc`, etc.) โ€” each is a separate +Cloudron identity with its own API keys, SSH key, and Bitwarden collection. + +--- + +## Document map + +`README.md` is the canonical index and contains a document table. Keep it +in sync. The files and their roles: + +| File | Role | Notes | +|---|---|---| +| `README.md` | Public-facing index + org context | Has the document table and the "Context" section (KNEL/TCTC, ITAR/CMMC/TS-SCI, Proxmox in residence, Cloudron+k8s stack) | +| `prompt.md` | Q2/Q3 2026 planning โ€” org chart, AI team roles, goals, SDLC/process requirements | References `k8s.md` which is actually `prompt-k8s.md` | +| `prompt-techops.md` | IaC testing model โ€” `sectestbed-` / `preprod-` VM workflow | Short; explains snapshot-based testing tiers | +| `prompt-k8s.md` | K8s vision โ€” VCluster, Rancher, multi-tenancy, workload catalog | Lists all tenant workloads (RackRental, Suborbital, TCTC, RedWFO, etc.) | +| `transition-map.md` | **The master map** โ€” current-state across Redmine/Discourse/Gitea/infra, Q3/Q4 timeline, risk register, open decisions, SecOps/compliance context, OAM monitoring | Largest doc; the single best source of "where things stand". Has dated `Status:` header | +| `agent-identity-bootstrap.md` | Agent identity provisioning plan โ€” Cloudron enrollment, API key generation, Bitwarden credential architecture, Playwright automation design, 5-phase pipeline | Architecture is "confirmed, awaiting user prerequisites" | +| `tsgcoo-bootstrap-prompt.md` | First-session prompt for the TSGCOO Linux account (the orchestration layer that provisions agents) | Points back at `transition-map.md` and `agent-identity-bootstrap.md` | + +When adding a new planning doc, add a row to `README.md`'s table and follow the +existing naming patterns (`prompt-.md` for vision notes, descriptive names +for plans/maps). + +--- + +## Systems of record (critical workflow rule) + +This repo is **not** the system of record. It is a drafting/thinking space. The +org-wide rules (from `prompt.md`): + +- **Discourse** (`community.turnsys.com`) is the single SoR for **all documentation**. + It is all Markdown. Long-form docs get synthesized *from here into Discourse*. +- **Redmine** (`projects.knownelement.com`) is the single SoR for **all work**. + Tickets, not prose, track execution. +- **Gitea** (`git.knownelement.com`) holds executable code. **`.md` files in Gitea + repos should be stubs that link to the relevant Discourse URLs** โ€” not the + documentation itself. Do not replicate doc content into Gitea wikis/issues. + (`prompt.md` line 73, 87.) + +So: when a planning doc here matures, the correct next step is to synthesize it +into Discourse topics + Redmine tickets, not to leave the only copy here. Several +docs already carry a note like *"not yet synthesized to Discourse/Redmine"*. + +### Live infrastructure referenced (do not treat as fictional) + +The docs name real, operational systems. URLs that appear: + +- `git.knownelement.com` โ€” Gitea (code) +- `community.turnsys.com` โ€” Discourse (docs) +- `projects.knownelement.com` โ€” Redmine (work) +- `tsys-cloudron.knel.net` โ€” Cloudron (IdP / PaaS) + +These are referenced for context. This repo does not interact with them, but an +agent extending these docs should keep the URLs/names accurate. + +--- + +## Document conventions + +- **Frontmatter-style headers.** Planning docs begin with `**Status:**` and + `**Date:**` lines (see `transition-map.md`, `agent-identity-bootstrap.md`). + Match this when creating new planning docs. Update `Date:` when materially + revising. +- **Status values observed:** `DRAFT for review`, `DRAFT โ€” architecture + confirmed, awaiting user prerequisites`. Indicate review maturity honestly. +- **Tables** are used heavily for matrices (maturity, gaps, risks, identity + rosters). Prefer extending an existing table over prose when the content is + tabular. +- **ASCII diagrams** for org charts and architecture boxes (see + `agent-identity-bootstrap.md` ยง1). Use box-drawing/ASCII, not images. +- **Emoji maturity markers** appear in `transition-map.md`: + ๐ŸŸข = minor gap, ๐ŸŸก = moderate, ๐Ÿ”ด = critical. Reuse consistently. +- **Checkboxes** (`- [ ]` / `- [x]`) track open vs. resolved items + (see transition-map ยง2, agent-identity-bootstrap ยง8). `~~strikethrough~~` + marks superseded decisions in the "Open Decisions" section. +- **Deadline sensitivity.** This is a live transition with hard dates: + **Sep 30 2026** (COO-handoff readiness), **Oct 1 2026** (Charles = CTO), + **Jan 1 2027** (full handoff). When editing timeline/roadmap content, keep + these anchors consistent with `transition-map.md` ยง0 and ยง4. + +--- + +## Git conventions + +(From `prompt.md` ยง"Meta Considerations"; these are org-wide and apply here.) + +- **Conventional-commit messages**, atomic commits, commit often. Recent history + uses the `docs:` type, e.g. `docs: add TSGCOO session bootstrap prompt`. +- **Develop on `main`/`master`.** Push after completing a logical unit of work. + Branches are allowed locally for exploration but multiple remote branches are + discouraged without human approval. +- **PRs** via the `tea` CLI (Gitea's CLI), from `main` โ†’ release branch. +- **`status.md`** is the durable, git-tracked scratchpad for token efficiency + (high-fidelity tactical notes โ†’ commit log / PR / Redmine). It is *not* the + system of record. Not currently present in this repo. +- **Questions** go in a git-tracked `questions-v(x).md` file (e.g. + `questions-v1.md`), not in harness question tools. Capture Q/A/decisions and + synthesize to Discourse/Redmine. + +--- + +## Related repositories (not in this repo, but tightly coupled) + +This repo is consumed by and references sibling repos in the TSYS Group Gitea. +An agent doing substantial work here will likely need to know they exist: + +- **`TSYSGroupCorporate/TSYSGroupAIOS`** โ€” the canonical governance/framework + template ("house rules"): `BASELINE-PROMPT.md` (14 principles), the 10-section + `AGENTS.md` template, `scripts/check-rules.sh`, git hooks, `bw-run.sh`, + `clone-as.sh`, `agent-profile.sh`. This is the framework every TSYS project + adopts. `tsgcoo-bootstrap-prompt.md` clones it *first*. +- **`TSYSGroupCorporate/agent-identity-provisioning`** โ€” the Playwright-based + automation that implements the pipeline described in + `agent-identity-bootstrap.md` (Cloudron enrollment, API-key generation, BW + storage). Has its own `agents.yaml` manifest and `questions-v1.md`. +- **`reachableceo/org-buildout`** โ€” this repo. + +When docs here describe scripts (`bw-run.sh`, `clone-as.sh`, `check-rules.sh`, +`agent-profile.sh`), the *implementations* live in `TSYSGroupAIOS/scripts/`, +not here. Keep descriptions here consistent with that repo. + +--- + +## Gotchas + +- **`README.md` references a `LICENSE` file that does not exist** in the repo. + Do not assume content is licensed beyond the "educational/reference" note. +- **`prompt.md` says "See `k8s.md`"** but the file is named `prompt-k8s.md`. +- **`.crush/`** is the local Crush harness config dir โ€” git-ignored, not part of + the documented content. Do not commit it. +- **These docs describe a transition in progress.** State described as "current" + (e.g. "k8s cnodes were wiped", "Cloudron 10/57 apps packaged", "Redmine + project 55 has 86 open tickets") is a **point-in-time snapshot dated + 2026-08-13**, not a live feed. Verify against the real systems before relying + on a specific number for execution. +- **`tsgcoo-bootstrap-prompt.md` is an operational prompt, not just docs** โ€” it + is intended to be read and executed by the TSGCOO Crush session as its first + action. Edits to it affect agent bootstrapping behavior.