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: 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:

Update manifest.json — add/remove the entry
Update README.md — update the structure tree if needed
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.

3.2 KiB Raw Blame History