three-tier-ai-context

Quick Start: Setting Up the Three-Tier System in Your Repository

This is a 5-minute setup guide to implement the token-efficient three-tier documentation system in your own repository.

What You’ll Get

Prerequisites

Step 1: Copy the Template Files (2 minutes)

# Copy the TEMPLATES directory to your repository
cp -r /path/to/AI-agents/TEMPLATES /path/to/your-repo/

# Navigate to your repository
cd /path/to/your-repo

# Run the setup script
bash TEMPLATES/setup-three-tier.sh

# Follow the prompts to create your first project

Option B: Manual

# In your repository, create the structure
mkdir -p docs projects agents

# Copy Tier 1 files
cp TEMPLATES/tier1-claude-template.md docs/docs-claude.md
cp TEMPLATES/tier1-session-template.md docs/docs-session-summary.md

# Copy Tier 2 files
cp TEMPLATES/tier2-claude-template.md projects/projects-claude.md
cp TEMPLATES/tier2-session-template.md projects/projects-session-summary.md

# Copy the agent
cp TEMPLATES/close-and-commit-agent-template.md agents/close_and_commit_GIT.md

# Create your first project (replace "MyProject" with your project name)
mkdir -p projects/MyProject
cp TEMPLATES/tier3-claude-template.md projects/MyProject/MyProject-claude.md
cp TEMPLATES/tier3-session-template.md projects/MyProject/MyProject-session-summary.md

Step 2: Customize (2 minutes)

Open these files and fill in the placeholders:

1. docs/docs-claude.md

2. agents/close_and_commit_GIT.md

3. projects/MyProject/MyProject-claude.md

Step 3: Test It (1 minute)

Make a small change to test the system:

# Make a small edit to any file in your repository
echo "# Test" >> README.md

# Tell your AI assistant to run the agent
# (In your AI chat, type:)
@agents/close_and_commit_GIT.md

The agent should:

  1. ✅ Detect which files changed
  2. ✅ Update the appropriate session files
  3. ✅ Create a commit
  4. ✅ Push to your remote repository

Step 4: Start Using It

From now on, follow this workflow:

Starting a Session

Working on a specific project?

Tell AI: "Read projects/MyProject/MyProject-claude.md and MyProject-session-summary.md"

Working on multiple projects?

Tell AI: "Read projects/projects-claude.md and projects-session-summary.md"

Quick context (fastest)?

Tell AI: "Run git log -5 --oneline --stat and summarize recent changes"

Ending a Session

Tell AI: "@agents/close_and_commit_GIT.md"

The agent handles everything automatically!

Understanding the Three Tiers

🏛️ Tier 1: Vault Level

📁 Tier 2: Projects Overview

🎯 Tier 3: Individual Project

Token Savings Example

Old way (flat structure):

New way (three-tier):

Adding More Projects

# Create a new project directory
PROJECT_NAME="NewProject"
mkdir -p "projects/$PROJECT_NAME"

# Copy templates
cp TEMPLATES/tier3-claude-template.md "projects/$PROJECT_NAME/${PROJECT_NAME}-claude.md"
cp TEMPLATES/tier3-session-template.md "projects/$PROJECT_NAME/${PROJECT_NAME}-session-summary.md"

# Edit the files to fill in project details

Then update:

  1. agents/close_and_commit_GIT.md - Add project to detection map
  2. docs/docs-claude.md - Add to active projects list
  3. projects/projects-claude.md - Add project overview

Common Questions

“Do I need all three tiers?”

For small repos (1-2 projects): Use 2 tiers (Tier 1 + Tier 3, skip Tier 2)

For medium repos (3-10 projects): Use all 3 tiers (recommended)

For large repos (10+ projects): Consider adding Tier 4 for sub-projects

“What if I forget to run the agent?”

No problem! Run it whenever you remember. You can manually update the session files if needed.

“Can I customize the format?”

Absolutely! The templates are yours to modify. Change the structure, add sections, remove what you don’t need.

“Does this work with other AI assistants?”

Yes! Any AI that can:

Examples: Claude Code, Cursor, Aider, Codex, custom setups

Troubleshooting

Agent doesn’t detect my project

Session files are getting too long

Don’t know which tier to use

Next Steps

  1. ✅ Set up the structure (you just did this!)
  2. 📝 Customize the templates with your info
  3. 🧪 Test with a small change
  4. 🚀 Start using it for real work
  5. 📊 Monitor your token usage (you should see big savings!)

Full Documentation

For complete details, see:

Support

This system is battle-tested and actively used. The templates include:

One More Thing

After you set this up, share it with others! The three-tier system is designed to be:

Help other developers save tokens and stay organized! 🎉

Questions? Issues? Improvements?

The templates are designed to be self-explanatory, but if you get stuck:

  1. Check the inline documentation in the template files
  2. Review THREE_TIER_SYSTEM_GUIDE.md
  3. Look at the examples in the original implementation

Happy documenting! 📚✨

This site is open source. Improve this page.