feat: add Documents/, Tools/, Analytics/ folders; move tool guides into Tools/; add AGENTS.md; update README.md + manifest.json
This commit is contained in:
@@ -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.
|
||||
@@ -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
|
||||
@@ -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
|
||||
@@ -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/<repo>.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 <file> with <change>"
|
||||
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.
|
||||
|
||||
---
|
||||
|
||||
|
||||
@@ -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 `<toolname>.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`.
|
||||
+23
-4
@@ -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"
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
|
||||
Reference in New Issue
Block a user