# AI Agent Documentation Template Universal starter template for AI-assisted project documentation and agent profiles. Use it as a foundation for new projects: adapt structure, rules, agent profiles, and technical recommendations to your domain. [![Documentation](https://img.shields.io/badge/docs-comprehensive-blue)](./DOCS.md) [![Phase](https://img.shields.io/badge/phase-0%20planning-yellow)](./docs/phases-plan.md) [![AI Ready](https://img.shields.io/badge/AI-ready-green)](./agents/) [![License](https://img.shields.io/badge/license-MIT-blue)](./LICENSE) --- ## Project Overview **AI Agent Documentation Template** is a comprehensive, production-ready documentation framework designed for AI-assisted software development. It provides structured guidelines, agent profiles, and best practices for building modern web applications with AI agents like Claude Code. ### Key Features - 📚 **Complete Documentation Structure** - Pre-built docs hierarchy with navigation index - 🤖 **AI Agent Profiles** - 10 specialized agent roles with model/tool restrictions (Planner, Frontend, Backend, Security, Code Review, Testing, Prompt Engineering, Documentation, Build Error Resolver, Loop Operator) - 🎯 **Product Archetypes** - Pre-defined patterns for common product types (SaaS, Marketplace, Content Platform) - 🏗️ **Architecture Guidelines** - Frontend (feature-first) and Backend (modular monolith) best practices - 🔒 **Security by Default** - OWASP Top 10 compliance, security patterns, and audit checklists - 💳 **Payment Integration Patterns** - Provider-agnostic payment flow design (Stripe, LiqPay, etc.) - 📋 **ADR Framework** - Architecture Decision Records for tracking design decisions - 🔄 **Phase-Based Planning** - 5-phase development methodology (Discovery → Support) - 🌍 **i18n Ready** - Internationalization guidelines and structure - 🐳 **DevOps Templates** - Docker, CI/CD, deployment checklists ## Current Status - 🚀 **Phase 0 - Planning** (Template Ready): - ✅ Complete documentation structure (`/docs`) - ✅ 10 AI agent profiles with model/tools frontmatter - ✅ Frontend & Backend architecture guidelines - ✅ Security, API design, and payment flow patterns - ✅ ADR framework and templates - ✅ Development setup guidelines - ⏳ **Ready for customization** - Adapt to your project needs --- ## Quick Start ### Prerequisites - Basic understanding of your project requirements - Familiarity with AI-assisted development (Claude Code, GitHub Copilot, etc.) - Your preferred tech stack (this template suggests Next.js + Node.js + PostgreSQL) ### Getting Started ```bash # 1. Clone or use this template git clone cd # 2. Review the product archetypes cat docs/archetypes.md # 3. Choose your archetype and fill project overview # Edit: docs/project-overview.md # 4. Plan your phases # Edit: docs/phases-plan.md # 5. Review agent profiles ls -la agents/ # 6. Start development with AI agents # Read: RULES.md for agent selection protocol ``` ### First Steps 1. **Define Your Product** - Read [`docs/archetypes.md`](docs/archetypes.md) - Choose archetype: SaaS Platform, Marketplace, Content Platform, or Custom - Select optional modules: Multi-tenancy, Payments, Analytics, etc. 2. **Fill Project Overview** - Edit [`docs/project-overview.md`](docs/project-overview.md) - Define goals, audience, tech stack, and key features 3. **Plan Development Phases** - Edit [`docs/phases-plan.md`](docs/phases-plan.md) - Map features to phases (0-4) - Set milestones and success criteria 4. **Configure AI Agents** - Review [`RULES.md`](RULES.md) for agent selection protocol - Customize agent profiles in [`agents/`](agents/) if needed - Start working with specialized agents --- ## Tech Stack (Recommended) | Category | Technology | | ---------------------- | ------------------------------------------- | | **Frontend Framework** | Next.js 15+ (App Router), React 19+ | | **Language** | TypeScript 5.x | | **Styling** | Tailwind CSS 4.x, shadcn/ui | | **State Management** | React Query / SWR + Zustand (optional) | | **Backend** | Node.js + Express/Fastify | | **Database** | PostgreSQL + Prisma/Drizzle ORM | | **Vector DB (AI)** | pgvector (PostgreSQL extension) | | **Authentication** | NextAuth.js v5 / Clerk | | **i18n** | next-intl | | **Payments** | Stripe / LiqPay / Fondy (provider-agnostic) | | **Email** | Resend / SendGrid | | **File Storage** | Vercel Blob / Cloudflare R2 / AWS S3 | | **Deployment** | Vercel / Docker + VPS | **Note:** This is a suggested stack. Adapt to your project needs - the documentation structure works with any modern web stack. --- ## Project Structure ``` your-project/ ├── docs/ # Complete documentation │ ├── archetypes.md # Product archetypes & optional modules │ ├── project-overview.md # Project overview template │ ├── phases-plan.md # Phase-based development plan │ ├── content-structure.md # Content/page structure │ ├── dev-setup.md # Development setup guide │ ├── ci-cd.md # Woodpecker CI + Gitea pipeline │ ├── adr/ # Architecture Decision Records │ │ ├── README.md # ADR guidelines │ │ └── 0000-template.md # ADR template │ ├── frontend/ # Frontend documentation │ │ ├── overview.md # Frontend overview │ │ ├── architecture.md # Feature-first architecture │ │ ├── ui-ux-guidelines.md # UX/UI best practices │ │ └── seo-performance.md # SEO & performance │ ├── backend/ # Backend documentation │ │ ├── overview.md # Backend overview │ │ ├── architecture.md # Modular monolith architecture │ │ ├── api-design.md # API design principles │ │ ├── security.md # Security patterns │ │ └── payment-flow.md # Payment integration │ ├── llm/ # AI/LLM system documentation │ │ ├── prompting.md # Prompt structure & versioning │ │ ├── evals.md # Evaluation strategy & datasets │ │ ├── safety.md # Safety, privacy, injection defense │ │ ├── caching-costs.md # Token caching & budget optimization │ │ └── rag-embeddings.md # RAG design & evaluation │ └── examples/ # Filled-in examples │ └── RECOMMENDATIONS-example.md ├── agents/ # AI agent profiles (10 agents) │ ├── planner.md # Implementation planner (opus) │ ├── frontend-architect.md # Frontend architect (opus) │ ├── backend-architect.md # Backend architect (opus) │ ├── security-auditor.md # Security auditor (opus) │ ├── code-reviewer.md # Code reviewer (sonnet) │ ├── test-engineer.md # Test engineer (sonnet) │ ├── prompt-engineer.md # Prompt engineer (sonnet) │ ├── documentation-expert.md # Documentation expert (sonnet) │ ├── build-error-resolver.md # Build error fixer (sonnet) │ └── loop-operator.md # Autonomous loop monitor (sonnet) ├── apps/ # Application code (Phase 2+) │ ├── web/ # Frontend app (Next.js) │ └── api/ # Backend API (Node.js) ├── packages/ # Shared packages (if monorepo) │ └── shared/ # Types, utils, API client ├── scripts/ # DevOps & CI scripts │ ├── setup-project.sh # VPS setup (user, dir, nginx, systemd) │ ├── deploy.sh # VPS deploy (rsync + npm ci + restart) │ └── ci-lint-fix.sh # ESLint auto-fix with commit-back ├── .claude/ # Claude Code configuration │ ├── settings.json # Hooks configuration (profiles, lifecycle) │ ├── status-update-checklist.md # Docs sync checklist for commits │ ├── hooks/ # Hook scripts (profile-gated) │ │ ├── run-with-profile.sh # Profile gate (minimal/standard/strict) │ │ ├── protect-files.sh # Block edits to sensitive files │ │ ├── bash-firewall.sh # Block dangerous commands │ │ ├── config-protection.sh # Block linter/formatter config edits │ │ ├── suggest-compact.sh # Suggest /compact every ~50 calls │ │ ├── auto-tmux-dev.sh # Suggest tmux for dev servers │ │ ├── post-edit-format.sh # Auto-format after edits (strict) │ │ ├── audit-log.sh # Log all Bash commands │ │ ├── commit-docs-reminder.sh # Remind to sync docs on commit │ │ ├── session-load.sh # Restore previous session context │ │ └── session-save.sh # Save session context on stop │ ├── sessions/ # Session state persistence │ └── skills/ # Slash-command skills (20 total) ├── .editorconfig # Editor formatting standards ├── .env.example # Environment variables template ├── .woodpecker.yml # Woodpecker CI pipeline config ├── package.json # Project metadata & engines ├── DOCS.md # Documentation index ├── RULES.md # Project rules & agent protocol ├── RECOMMENDATIONS.md # Project-specific decisions ├── RESEARCH-SDD-TOOLS.md # SDD tools research (Spec Kit, AI Factory) └── README.md # This file ``` --- ## Documentation 📚 **[Full Documentation Index](./DOCS.md)** - Complete documentation map ### Core Documentation **Planning & Architecture:** - **[Product Archetypes](./docs/archetypes.md)** 🎯 - Choose your product pattern - **[Project Overview](./docs/project-overview.md)** 📋 - Project definition template - **[Phases Plan](./docs/phases-plan.md)** 🗓️ - 5-phase development methodology - **[Content Structure](./docs/content-structure.md)** 📄 - Page/content organization - **[ADR Framework](./docs/adr/README.md)** 📝 - Architecture Decision Records **Frontend:** - **[Frontend Overview](./docs/frontend/overview.md)** - Frontend stack overview - **[Architecture](./docs/frontend/architecture.md)** - Feature-first architecture pattern - **[UI/UX Guidelines](./docs/frontend/ui-ux-guidelines.md)** - Design system principles - **[SEO & Performance](./docs/frontend/seo-performance.md)** - Optimization strategies **Backend:** - **[Backend Overview](./docs/backend/overview.md)** - Backend stack overview - **[Architecture](./docs/backend/architecture.md)** - Modular monolith pattern - **[API Design](./docs/backend/api-design.md)** - RESTful/GraphQL best practices - **[Security](./docs/backend/security.md)** - OWASP Top 10, auth patterns - **[Payment Flow](./docs/backend/payment-flow.md)** - Provider-agnostic payment design **AI Agents (10 profiles, model/tools-gated):** - **[RULES.md](./RULES.md)** - Agent selection protocol and project rules - **[Planner](./agents/planner.md)** - Implementation planner (opus, read-only) - **[Frontend Architect](./agents/frontend-architect.md)** - Frontend specialist (opus) - **[Backend Architect](./agents/backend-architect.md)** - Backend specialist (opus) - **[Security Auditor](./agents/security-auditor.md)** - Security review (opus) - **[Code Reviewer](./agents/code-reviewer.md)** - Code quality (sonnet) - **[Test Engineer](./agents/test-engineer.md)** - Testing specialist (sonnet) - **[Prompt Engineer](./agents/prompt-engineer.md)** - AI prompt specialist (sonnet) - **[Documentation Expert](./agents/documentation-expert.md)** - Technical writing (sonnet) - **[Build Error Resolver](./agents/build-error-resolver.md)** - Minimal-diff error fixer (sonnet) - **[Loop Operator](./agents/loop-operator.md)** - Autonomous loop monitor (sonnet) --- ## Development Phases This template follows a 5-phase methodology. Adapt to your project timeline: ### Phase 0 - Discovery & Requirements (1-2 weeks) - Define product vision, goals, and target audience - Choose product archetype and optional modules - Select tech stack and tools - Document requirements and constraints - Set up initial project structure ### Phase 1 - Architecture & Design (2-3 weeks) - Design system architecture (frontend + backend) - Define API contracts and data models - Create database schema - Plan authentication and authorization - Document architecture decisions (ADRs) - Set up development environment ### Phase 2 - MVP Implementation (4-8 weeks) - Implement core user flows - Build essential UI/UX components - Set up authentication and user management - Integrate third-party services (payments, email, etc.) - Implement basic admin features - Set up monitoring and logging ### Phase 3 - Improvements & Scaling (3-4 weeks) - Improve code quality and test coverage - Optimize performance (frontend + backend) - Conduct security audit and fixes - Enhance observability (logs, metrics, traces) - Implement advanced features - Prepare for production deployment ### Phase 4 - Support & Evolution (Ongoing) - Production deployment and monitoring - Bug fixes and maintenance - Feature iterations based on user feedback - Scaling infrastructure as needed - Documentation updates - Continuous improvement **Total estimated time:** 10-17 weeks (single developer) or 6-10 weeks (2-3 developers) See [`docs/phases-plan.md`](docs/phases-plan.md) for detailed phase breakdown. --- ## How to Use This Template ### For New Projects 1. **Clone/Fork this repository** ```bash git clone cd ``` 2. **Choose Your Archetype** - Read [`docs/archetypes.md`](docs/archetypes.md) - Identify your product type (SaaS, Marketplace, Content, Custom) - Select optional modules (Multi-tenancy, Payments, Analytics, etc.) 3. **Fill Project Documentation** - Edit [`docs/project-overview.md`](docs/project-overview.md) - define your product - Edit [`docs/phases-plan.md`](docs/phases-plan.md) - plan your roadmap - Edit [`docs/content-structure.md`](docs/content-structure.md) - define pages/features 4. **Customize Agent Profiles** - Review [`RULES.md`](RULES.md) - understand agent selection protocol - Review agent profiles in [`agents/`](agents/) - Customize profiles if needed (add project-specific context) 5. **Start Development** - Use specialized agents for different tasks - Document decisions in [`docs/adr/`](docs/adr/) - Keep documentation updated as you build ### For Existing Projects 1. **Adopt Documentation Structure** - Copy relevant docs from [`docs/`](docs/) to your project - Adapt templates to match your current architecture - Document existing decisions as ADRs 2. **Configure AI Agents** - Copy [`RULES.md`](RULES.md) and [`agents/`](agents/) to your project - Customize agent profiles with project-specific context - Train your team on agent selection protocol 3. **Incremental Adoption** - Start with one area (e.g., frontend architecture docs) - Gradually expand documentation coverage - Use agents for new features first, then refactor existing code --- ## AI Agent Workflow This template is optimized for AI-assisted development. Here's the recommended workflow: ### 1. Agent Selection Protocol Before starting a task, select the appropriate agent based on [`RULES.md`](RULES.md): - **Task planning** → [`planner.md`](agents/planner.md) (opus) - **Frontend tasks** → [`frontend-architect.md`](agents/frontend-architect.md) (opus) - **Backend tasks** → [`backend-architect.md`](agents/backend-architect.md) (opus) - **Security review** → [`security-auditor.md`](agents/security-auditor.md) (opus) - **Code review** → [`code-reviewer.md`](agents/code-reviewer.md) (sonnet) - **Testing** → [`test-engineer.md`](agents/test-engineer.md) (sonnet) - **Build errors** → [`build-error-resolver.md`](agents/build-error-resolver.md) (sonnet) - **AI/LLM integration** → [`prompt-engineer.md`](agents/prompt-engineer.md) (sonnet) - **Documentation** → [`documentation-expert.md`](agents/documentation-expert.md) (sonnet) - **Autonomous loops** → [`loop-operator.md`](agents/loop-operator.md) (sonnet) ### 2. Task Execution Each agent profile includes: - **Role description** - What this agent specializes in - **Responsibilities** - What tasks to delegate - **Guidelines** - How the agent should work - **Best practices** - Domain-specific recommendations - **Checklist** - Pre-flight checks before starting ### 3. Documentation Updates - Document architecture decisions in [`docs/adr/`](docs/adr/) - Update relevant docs when making changes - Keep phase plan current as you progress - Use ADR template for significant decisions --- ## Optional Modules The template includes patterns for common modules. **Keep only what you need:** ### Core Modules (Common to Most Projects) - ✅ Authentication & Authorization - ✅ User Management - ✅ Database & ORM - ✅ API Layer - ✅ Email Notifications - ✅ File Uploads ### Optional Modules (Archetype-Specific) - 💳 **Payment Processing** - Stripe, LiqPay, Fondy (SaaS, Marketplace) - 🏢 **Multi-tenancy** - Organizations, teams, workspaces (SaaS B2B) - 🤖 **AI/LLM Integration** - OpenAI, Anthropic, reasoning traces (AI Apps) - 🔄 **Background Jobs** - Queue processing, scheduled tasks (Data Processing) - 📊 **Analytics & Events** - Event logging, user tracking (Product Analytics) - 🎥 **Media Streaming** - Video, audio, HLS (Content Platforms) - 📱 **Real-time Features** - WebSockets, SSE (Collaboration Tools) - 🌐 **Multi-region** - Geo-distributed deployments (Global SaaS) See [`docs/archetypes.md`](docs/archetypes.md) for detailed module descriptions. --- ## Best Practices ### Documentation - ✅ Write docs in English (international audience) - ✅ Use Markdown for all documentation - ✅ Keep docs close to code (docs/ folder) - ✅ Update docs when making changes - ✅ Use ADRs for architecture decisions ### Code Organization - ✅ Feature-first structure (frontend) - ✅ Modular monolith (backend) - ✅ Colocate tests with code - ✅ Use TypeScript for type safety - ✅ Follow single responsibility principle ### Security - ✅ OWASP Top 10 compliance - ✅ Input validation (client + server) - ✅ Rate limiting on sensitive endpoints - ✅ Environment variable validation - ✅ Regular security audits ### AI Agent Usage - ✅ Select appropriate agent for each task - ✅ Provide context in agent prompts - ✅ Review AI-generated code before committing - ✅ Document AI-assisted decisions - ✅ Iterate with feedback See [`RECOMMENDATIONS.md`](RECOMMENDATIONS.md) for detailed best practices. --- ## Example Use Cases This template is designed for various product types: ### SaaS Platforms - Subscription-based services with billing - Multi-tenant B2B applications - Admin panels with RBAC ### Marketplace Applications - E-commerce platforms with vendor management - Service marketplaces with booking systems - Rental platforms with availability calendars ### Content Platforms - Blog/CMS systems with authoring workflows - Media galleries with CDN integration - Knowledge bases with search ### AI-Powered Applications - LLM integration with reasoning traces - Document processing pipelines - Intelligent automation tools --- ## Contributing Contributions are welcome! This template is designed to evolve with community feedback. ### How to Contribute 1. **Report Issues** - Found a mistake or have a suggestion? Open an issue 2. **Submit Improvements** - Better docs, new agent profiles, or patterns? Open a PR 3. **Share Use Cases** - Used this template successfully? Share your story! ### Contribution Guidelines - Follow existing documentation style - Update relevant sections when adding features - Include examples and use cases - Test with AI agents (Claude Code, GitHub Copilot) - Keep language clear and concise --- ## License [MIT](./LICENSE) --- ## Support Need help using this template? - 📖 Read the [full documentation](./DOCS.md) - 💡 Check [best practices](./RECOMMENDATIONS.md) - 🤔 Review [agent profiles](./agents/) - 🐛 Open an issue for bugs or questions - 💬 Start a discussion for general questions --- ## Acknowledgments This template is designed for AI-assisted development with: - **[Claude Code](https://claude.ai/claude-code)** - Primary development assistant - **[GitHub Copilot](https://github.com/features/copilot)** - Code completion - **[Cursor](https://cursor.sh/)** - AI-first IDE Inspired by best practices from Next.js, T3 Stack, and enterprise SaaS architectures. --- **Status:** Phase 0 🚀 Template Ready - **Ready for Customization** **Documentation:** 📚 Complete (20+ guides) | **AI Agents:** 🤖 10 specialized profiles **Architecture:** ✅ Frontend (Feature-first) + Backend (Modular Monolith) **Security:** ✅ OWASP Top 10 patterns | **Deployment:** ✅ Docker + CI/CD templates