feat: add Documents/, Tools/, Analytics/ folders; move tool guides into Tools/; add AGENTS.md; update README.md + manifest.json

2026-05-30 23:44:28 -05:00
parent 0e823a66bd
commit 9967c6709b
9 changed files with 187 additions and 28 deletions
@@ -0,0 +1,90 @@
+# AGENTS.md
+
+Operational instructions for AI agents working in this repository.
+
+---
+
+## Purpose of This Repo
+
+`llm-tools` is a **navigation phonebook** for AI agents. It answers the fundamental questions any LLM needs when starting work in Jacob Mathison's environment:
+
+- Where is the code? (Gitea, GitHub)
+- What cloud resources exist? (AWS)
+- Which agent am I, and how should I behave? (`agents/`)
+- What workflows are available? (`workflows/`)
+
+Read `README.md` first for the full picture.
+
+---
+
+## Repository Structure
+
+```
+llm-tools/
+├── AGENTS.md           This file — instructions for AI agents
+├── README.md           Overview, quick-start, environment at a glance
+├── llm.txt             Plain-text summary for rapid LLM ingestion
+├── manifest.json       Machine-readable index of everything in this repo
+│
+├── Tools/              Access guides for third-party services
+│   ├── README.md
+│   ├── gitea.llm.md    Local self-hosted Gitea
+│   ├── github.llm.md   GitHub (MathisonProjects + silmaai)
+│   └── aws-cli.llm.md  AWS account and services
+│
+├── agents/             Per-agent configuration and notes
+│   ├── README.md
+│   ├── claude.md
+│   ├── cursor.md
+│   └── codex.md
+│
+├── workflows/          Reusable automation and prompt chains
+│   └── README.md
+│
+├── Documents/          Project specs, architecture docs, written context
+│   └── README.md
+│
+└── Analytics/          Data sources, dashboards, reporting guides
+    └── README.md
+```
+
+---
+
+## Rules for AI Agents Working Here
+
+### Reading
+- Start with `README.md` + `manifest.json` to orient yourself
+- Read the relevant `Tools/` guide before touching any external service
+- Check `agents/<your-agent>.md` for any agent-specific config or instructions
+
+### Writing
+- **Always update `README.md` and `manifest.json`** when adding files or folders
+- Follow the existing file naming pattern: `<service>.llm.md` in `Tools/`
+- Use [Conventional Commits](https://www.conventionalcommits.org/): `docs:`, `feat:`, `chore:`
+- One concern per file — don't bundle unrelated guides together
+
+### What Goes Where
+
+| Content type | Folder |
+|---|---|
+| External service access guide | `Tools/` |
+| Per-agent config / instructions | `agents/` |
+| Reusable prompt chains / automation | `workflows/` |
+| Specs, architecture, written context | `Documents/` |
+| Data sources, dashboards, reporting | `Analytics/` |
+
+### What NOT to Do
+- Do not commit secrets, tokens, or credentials — reference `credentials/secrets.env` by path only
+- Do not delete files without updating `manifest.json` and `README.md`
+- Do not make destructive AWS or git operations without confirming intent
+
+---
+
+## Keeping the Index Current
+
+Every time a file is added, moved, or removed:
+1. Update `manifest.json` — add/remove the entry
+2. Update `README.md` — update the structure tree if needed
+3. Update the relevant folder's `README.md` if it has a file table
+
+This keeps the repo self-describing and useful to the next agent that opens it cold.