GitHub - grantcarthew/dotai-template: Local cache of commonly used documentation for efficient AI agent access

5 min read Original article ↗

dotai - AI Resources Hub

A structured system for AI agent resources, including environment configuration, documentation references, task templates, role definitions, and workflow guides.

Overview

This repository provides a complete AI resources hub for your home directory (~/.ai) or project directories (./.ai). It goes beyond just documentation to include environment configuration, DDD workflow, task templates, and role definitions - everything your AI agents need to work effectively.

Why Use This?

For AI Agents:

  • Fast access to comprehensive documentation without web queries
  • Structured indexing (CSV) for efficient navigation
  • Clear environment and workflow context
  • Task templates and role definitions
  • Reduced token usage through direct file access

For Developers:

  • Offline access to critical documentation
  • Consistent AI agent configuration across projects
  • Customizable to your workflow and tech stack
  • Automated documentation updates
  • Support for multiple branches (work, personal, etc.)

Features

  • Environment Configuration: Customizable environment.md for AI agent context
  • Documentation Management: Automated updates for reference documentation
  • Workflow Integration: Documentation Driven Development (DDD) workflow
  • Task Templates: Code review, release, and workflow templates
  • Role Definitions: AI agent behaviour and responsibility definitions
  • CSV Indexing: Efficient navigation system for both humans and AI
  • Branching Strategy: Different contexts for work, personal, projects
  • Minimal Dependencies: Only requires Git, Bash 5+, fd, ripgrep

Prerequisites

  • Git: Version control (2.25+)
  • Bash: Shell (5.0+)
  • fd: Fast file finder (installation)
  • ripgrep: Fast text search (installation)

Optional but recommended:

  • snag: Fetch web page content using a browser engine (installation)
  • kagi: Query the Kagi search engine FastGPT API (Bash script)
  • lsd: Enhanced directory listings

Installation

Home Directory Setup (~/.ai)

Clone this repository to your home directory for system-wide AI resources:

git clone https://github.com/grantcarthew/dotai-template.git ~/.ai
cd ~/.ai

Customise environment.md with your details:

nvim ~/.ai/environment.md

Fill in:

  • Your name, skills, and preferences
  • Desktop environment and package manager details
  • Preferred CLI tools

Make scripts executable:

chmod +x ~/.ai/context/refresh-context
chmod +x ~/.ai/context/scripts/update-repos
chmod +x ~/.ai/context/scripts/update-docs

Project Directory Setup (./.ai)

For project-specific AI resources, use the project-template instead:

# In your project directory
git clone https://github.com/grantcarthew/project-template.git .ai

Or copy from your home setup:

cp -r ~/.ai ./.ai
# Then customize for project-specific needs

Branch Strategy

Create branches for different contexts:

# Create work branch for work-related documentation
git checkout -b work

# Create personal branch
git checkout -b personal

# Create project-specific branches as needed
git checkout -b project-name

The .gitignore excludes child directories and branch-specific files, allowing different documentation sets per branch while keeping core files synchronized.

Directory Structure

~/.ai/ (or ./.ai/)
├── AGENTS.md              # AI agent entry point
├── README.md              # This file
├── environment.md         # Your environment configuration
├── workflow.md            # Documentation Driven Development workflow
├── index.csv              # Top-level directory index
├── context/               # Third-party documentation
│   ├── AGENTS.md          # Context-specific agent instructions
│   ├── README.md          # Context directory documentation
│   ├── index.csv          # Documentation index (gitignored, branch-specific)
│   ├── indexes/           # Tracked child indexes
│   ├── project.md         # Current context maintenance tasks
│   ├── role.md            # AI agent role definition
│   ├── refresh-context    # Main update script
│   ├── scripts/           # Utility scripts
│   │   ├── lib.sh
│   │   ├── update-repos
│   │   ├── update-docs
│   │   └── update-docs-url-list.csv
│   ├── docs/              # Local documentation
│   └── [your-docs]/       # Cloned documentation (gitignored)
├── tasks/                 # Task templates
│   └── README.md
├── roles/                 # Role definitions
│   └── README.md
└── docs/                  # Authored documentation
    └── README.md

Quick Start

Adding Your First Documentation

cd ~/.ai/context
git clone --depth=1 https://github.com/kubernetes/website.git kubernetes
./refresh-context

Configure AI Agent Startup

Configure your AI assistant to read these files at session start:

# Home context
~/.ai/environment.md
~/.ai/index.csv
~/.ai/AGENTS.md

# Project context (when in a project)
./.ai/AGENTS.md
./.ai/context/project.md

Example startup prompt:

Read the ~/.ai/environment.md file for environment context.
Read the ./.ai/AGENTS.md file for project context.
Read the ./.ai/context/project.md document for current work.

Adding Multiple Documentation Sources

cd ~/.ai/context

# Frameworks
git clone --depth=1 https://github.com/golang/go.git golang
git clone --depth=1 https://github.com/docker/docs.git docker

# Tools
git clone --depth=1 https://github.com/hashicorp/terraform-docs.git terraform

# Update all at once
./refresh-context

Usage

Updating Documentation

Run the refresh script regularly:

~/.ai/context/refresh-context

This will:

  1. Update all git repositories (shallow pull)
  2. Download web-based documentation
  3. Regenerate index.csv files
  4. Report successes and failures

Searching Documentation

# Search across all documentation
rg -i "search term" ~/.ai/context/ --type md

# Search within specific documentation
rg -i "kubernetes pod" ~/.ai/context/kubernetes/

# Find files by name
fd "install.md" ~/.ai/context/

Using Task Templates

# Copy task template to project
cp ~/.ai/tasks/code-review.md ./.ai/tasks/

Using Roles

# Reference role in project AGENTS.md
See ~/.ai/roles/architect.md for this agent's role definition.

Workflow

See workflow.md for the complete Documentation Driven Development (DDD) workflow, which includes:

  • Design phase documentation
  • Project planning and task management
  • Code review processes
  • Release procedures

Customisation

Creating index.csv Files

Use your AI agent to generate index files:

Read the ~/.ai/context/AGENTS.md file for context instructions.
Read the ~/.ai/context/project.md document to understand your task.
Start the Context Repository Refresh project work.

Adding Web-Based Documentation

Edit context/scripts/update-docs-url-list.csv:

url,filename,description
https://example.com/docs,example-docs.md,Example Documentation

Requires snag or similar tool.

Maintenance

Regular Updates

# Add to crontab or run manually
~/.ai/context/refresh-context

Troubleshooting

Script fails to find lib.sh:

  • Ensure scripts are run from correct directory
  • Check script paths are correct

Git repositories fail to update:

  • Check network connectivity
  • Verify repository URLs are still valid

Disk space issues:

  • Use shallow clones (--depth=1)
  • Use sparse checkouts for large repositories
  • Remove unused documentation repositories

Contributing

Contributions welcome! Please:

  1. Fork this repository
  2. Create a feature branch
  3. Make your changes
  4. Submit a pull request

Ensure:

  • Scripts support Bash 5+
  • Documentation is clear and concise
  • Changes benefit the general use case

License

Mozilla Public License Version 2.0

Resources