From 9967c6709ba6c09dce1fd6da30eb3dd1997eca82 Mon Sep 17 00:00:00 2001 From: Jacob Mathison Date: Sat, 30 May 2026 23:44:28 -0500 Subject: [PATCH] feat: add Documents/, Tools/, Analytics/ folders; move tool guides into Tools/; add AGENTS.md; update README.md + manifest.json --- AGENTS.md | 90 ++++++++++++++++++++++++++ Analytics/README.md | 12 ++++ Documents/README.md | 12 ++++ README.md | 50 +++++++------- Tools/README.md | 24 +++++++ aws-cli.llm.md => Tools/aws-cli.llm.md | 0 gitea.llm.md => Tools/gitea.llm.md | 0 github.llm.md => Tools/github.llm.md | 0 manifest.json | 27 ++++++-- 9 files changed, 187 insertions(+), 28 deletions(-) create mode 100644 AGENTS.md create mode 100644 Analytics/README.md create mode 100644 Documents/README.md create mode 100644 Tools/README.md rename aws-cli.llm.md => Tools/aws-cli.llm.md (100%) rename gitea.llm.md => Tools/gitea.llm.md (100%) rename github.llm.md => Tools/github.llm.md (100%) diff --git a/AGENTS.md b/AGENTS.md new file mode 100644 index 0000000..ebdb6cd --- /dev/null +++ b/AGENTS.md @@ -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/.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: `.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. diff --git a/Analytics/README.md b/Analytics/README.md new file mode 100644 index 0000000..f8a7a82 --- /dev/null +++ b/Analytics/README.md @@ -0,0 +1,12 @@ +# Analytics + +Data sources, dashboards, and analytics tooling available to AI agents in this environment. + +> This folder is a placeholder — add analytics access guides, data source maps, and reporting context here as they are developed. + +## Intended Contents + +- Analytics platform access guides (e.g. Google Analytics, Mixpanel, Amplitude) +- AWS CloudWatch / CloudTrail query patterns +- Database query references for reporting +- Data pipeline documentation diff --git a/Documents/README.md b/Documents/README.md new file mode 100644 index 0000000..656eeff --- /dev/null +++ b/Documents/README.md @@ -0,0 +1,12 @@ +# Documents + +Reference documents, specs, and written context for AI agents working in this environment. + +> This folder is a placeholder — add project specs, architecture docs, onboarding docs, and written context here as they are developed. + +## Intended Contents + +- Project specifications and requirements +- Architecture overviews +- Onboarding documents for specific projects +- Meeting notes or decision logs relevant to AI context diff --git a/README.md b/README.md index 69b9036..72f4165 100644 --- a/README.md +++ b/README.md @@ -22,21 +22,30 @@ This repo answers all of those questions. Think of it as a rolodex — structure ``` llm-tools/ +├── AGENTS.md Instructions for AI agents working in this repo ├── README.md This file ├── llm.txt Plain-text overview for LLM agents ├── manifest.json Machine-readable index of everything │ -├── gitea.llm.md Local Gitea instance — clone URLs, PAT auth, API -├── github.llm.md GitHub accounts — MathisonProjects + silmaai -├── aws-cli.llm.md AWS — profiles, S3, Amplify, CloudFront, Lambda +├── Tools/ Access guides for external services +│ ├── README.md +│ ├── gitea.llm.md Local Gitea — clone URLs, PAT auth, API +│ ├── github.llm.md GitHub — MathisonProjects + silmaai +│ └── aws-cli.llm.md AWS — profiles, S3, Amplify, CloudFront, Lambda │ -├── agents/ Per-agent notes and config +├── agents/ Per-agent configuration and notes │ ├── README.md │ ├── claude.md │ ├── cursor.md │ └── codex.md │ -└── workflows/ Reusable workflows and automation +├── workflows/ Reusable workflows and automation +│ └── README.md +│ +├── Documents/ Project specs, architecture docs, written context +│ └── README.md +│ +└── Analytics/ Data sources, dashboards, reporting guides └── README.md ``` @@ -44,27 +53,28 @@ llm-tools/ ## Quick Start for an AI Agent -**1. Check your network access** +**1. Read `AGENTS.md`** — operational instructions and rules for working in this repo. + +**2. Check your network access** ```bash curl -s http://100.79.253.19:3000/api/v1/version # Gitea — expect {"version":"1.26.2"} aws sts get-caller-identity # AWS — expect account 567637986724 ``` -**2. Clone something** +**3. Clone something** ```bash # Any repo on the local Gitea (Tailscale required): git clone http://100.79.253.19:3000/jacob-mathison/.git - -# This repo itself: -git clone http://100.79.253.19:3000/jacob-mathison/llm-tools.git ``` -**3. Read the guide for whatever surface you need** +**4. Read the guide for whatever surface you need** -Working with source control (local) → [`gitea.llm.md`](./gitea.llm.md) -Working with GitHub → [`github.llm.md`](./github.llm.md) -Working with AWS → [`aws-cli.llm.md`](./aws-cli.llm.md) -Agent-specific config → [`agents/`](./agents/) +| Need | Go to | +|------|-------| +| Local git repos | [`Tools/gitea.llm.md`](./Tools/gitea.llm.md) | +| GitHub | [`Tools/github.llm.md`](./Tools/github.llm.md) | +| AWS | [`Tools/aws-cli.llm.md`](./Tools/aws-cli.llm.md) | +| Agent-specific config | [`agents/`](./agents/) | --- @@ -96,15 +106,7 @@ Agent-specific config → [`agents/`](./agents/) ## Keeping This Up to Date -When a new service, machine, repo, or agent is added, update the relevant file and push. **Always update `manifest.json` and this `README.md`** so the index stays accurate. - -```bash -cd /Volumes/Hagia/workspaces/workspace_Father/llm-tools -# edit the file(s) -git add . -git commit -m "docs: update with " -git push -``` +When a new file, folder, service, or agent is added — update `manifest.json` and this `README.md`. See `AGENTS.md` for the full rules. --- diff --git a/Tools/README.md b/Tools/README.md new file mode 100644 index 0000000..a9ef448 --- /dev/null +++ b/Tools/README.md @@ -0,0 +1,24 @@ +# Tools + +Access guides for the third-party services and platforms AI agents need to work with in this environment. + +Each file covers one surface — authentication, available resources, and common CLI/API patterns. + +## Guides + +| File | Surface | Key Info | +|------|---------|----------| +| [`gitea.llm.md`](./gitea.llm.md) | Local Gitea (self-hosted git) | `http://100.79.253.19:3000` · PAT auth · Tailscale required | +| [`github.llm.md`](./github.llm.md) | GitHub | MathisonProjects + silmaai · PAT in `credentials/secrets.env` | +| [`aws-cli.llm.md`](./aws-cli.llm.md) | AWS | Account `567637986724` · S3 · Amplify · CloudFront · Lambda | + +## Adding a New Tool + +Create a new `.llm.md` file in this folder following the same pattern: +1. Service/account details +2. Authentication method +3. Available resources (list what exists) +4. Common CLI/API patterns +5. Notes for AI agents + +Then update `Tools/README.md` and the root `manifest.json`. diff --git a/aws-cli.llm.md b/Tools/aws-cli.llm.md similarity index 100% rename from aws-cli.llm.md rename to Tools/aws-cli.llm.md diff --git a/gitea.llm.md b/Tools/gitea.llm.md similarity index 100% rename from gitea.llm.md rename to Tools/gitea.llm.md diff --git a/github.llm.md b/Tools/github.llm.md similarity index 100% rename from github.llm.md rename to Tools/github.llm.md diff --git a/manifest.json b/manifest.json index 5d6c35b..7ef138e 100644 --- a/manifest.json +++ b/manifest.json @@ -136,15 +136,22 @@ }, "files": { + "AGENTS.md": "Operational instructions and rules for AI agents working in this repo", "README.md": "Human + AI overview, repo structure, quick-start, environment at a glance", "llm.txt": "Plain-text overview for LLM agents", - "manifest.json": "This file — machine-readable index of repos, tools, endpoints, and structure", - "gitea.llm.md": "Local Gitea instance — clone URLs, PAT auth, API examples", - "github.llm.md": "GitHub accounts (MathisonProjects, silmaai) — repos, PAT, CLI patterns", - "aws-cli.llm.md": "AWS account — profiles, S3 buckets, Amplify apps, CloudFront, Lambda" + "manifest.json": "This file — machine-readable index of repos, tools, endpoints, and structure" }, "directories": { + "Tools": { + "description": "Access guides for external services and platforms", + "files": { + "README.md": "Index of tool guides and instructions for adding new ones", + "gitea.llm.md": "Local Gitea instance — clone URLs, PAT auth, API examples", + "github.llm.md": "GitHub accounts (MathisonProjects, silmaai) — repos, PAT, CLI patterns", + "aws-cli.llm.md": "AWS account — profiles, S3 buckets, Amplify apps, CloudFront, Lambda" + } + }, "agents": { "description": "Per-agent configuration, context, and notes for AI coding tools", "files": { @@ -159,6 +166,18 @@ "files": { "README.md": "Index and intended contents for workflows" } + }, + "Documents": { + "description": "Project specs, architecture docs, and written context for AI agents", + "files": { + "README.md": "Index and intended contents for Documents" + } + }, + "Analytics": { + "description": "Data sources, dashboards, and analytics tooling", + "files": { + "README.md": "Index and intended contents for Analytics" + } } } }