llm-tools/AGENTS.md

# 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/` |
| Client engagement context | `clients/` |
| Internal / personal project context | `projects/` |

### 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.