docs: add AGENTS.md to orient agents working in this repo
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
This commit is contained in:
TSYS Group COO
committed by
TSYS Group COO
TSYS Group COO
parent
eaaac18159
commit
88a2f14415
@@ -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-<area>.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.
|
||||
Reference in New Issue
Block a user