Agents Template 🤖

A streamlined, agent-agnostic repository template designed for seamless collaboration between human developers and AI coding agents (Claude, GitHub Copilot, Cursor, etc.).

---

🌟 Why This Template?

Modern software development often involves multiple AI agents. Without a clear structure, these agents can struggle with context, overwrite each other's work, or lose track of long-term project goals. This template provides a stable framework for any agent to understand your codebase's current state, rules, and priorities.

🚀 Key Features

• Agent-Agnostic Core: Centralized instructions in AGENTS.md that work for any AI.
• Persistent Context: Dedicated docs/developer/current-state.md for session-to-session continuity.
• Structured Task Tracking: Lightweight task management in docs/tasks.md.
• Customizable Adapters: Thin wrappers like CLAUDE.md and COPILOT.md for tool-specific behaviors.
• Modern Standards: Built-in support for conventional commits and clear quality gates.

📁 Project Structure

.
├── AGENTS.md                # 🧠 The "Brain" - repo-wide agent rules
├── CLAUDE.md                # 🔧 Adapter for Claude Desktop/Dev
├── COPILOT.md               # 🔧 Adapter for GitHub Copilot
├── docs/
│   ├── tasks.md             # 📝 Current roadmap and priorities
│   └── developer/           # 🏗️ Internal documentation index
│       ├── current-state.md # 📍 The "Source of Truth" (read first)
│       ├── architecture-guide.md # 🏛️ System design & patterns
│       └── ...              # 📚 Testing, Releases, and more
└── README.md                # 📖 You are here

🛠️ Quick Start

1. Clone & Adapt: Copy these files into your new or existing repository.
2. Customize AGENTS.md: Update these 3 specific areas:
   • Package Manager: Set your preferred tool (npm, pnpm, yarn, etc.).
   • Validation Command: Define your "check everything" script (e.g., npm run test).
   • Stack-Specific Patterns: Add rules for your framework (React, Go, etc.).
3. Initialize State: Update docs/developer/current-state.md with your current progress.
4. Explore Docs: Check the developer index for architecture, testing, and release guides.
5. Start Coding: Point your AI agent to AGENTS.md and watch it work with precision.

Best Practices for Agents

• Read Before Editing: Agents are instructed to read related files and documentation before making changes.
• Update State: Every significant session should end with an update to current-state.md.
• Senior Architect Mindset: Prioritize maintainability and performance over quick fixes.