feat: add Documentation Expert agent profile
New specialized agent for technical writing, documentation standards, and generating docs from code. Includes Diataxis framework, severity-based review checklists, code-to-docs patterns, and quality metrics. Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
This commit is contained in:
olekhondera
77
README.md
77
README.md
@@ -16,7 +16,7 @@ Universal starter template for AI-assisted project documentation and agent profi
|
||||
### Key Features
|
||||
|
||||
- 📚 **Complete Documentation Structure** - Pre-built docs hierarchy with navigation index
|
||||
- 🤖 **AI Agent Profiles** - 6 specialized agent roles (Frontend, Backend, Security, Testing, Code Review, Prompt Engineering)
|
||||
- 🤖 **AI Agent Profiles** - 7 specialized agent roles (Frontend, Backend, Security, Testing, Code Review, Prompt Engineering, Documentation)
|
||||
- 🎯 **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
|
||||
@@ -29,13 +29,13 @@ Universal starter template for AI-assisted project documentation and agent profi
|
||||
## Current Status
|
||||
|
||||
- 🚀 **Phase 0 - Planning** (Template Ready):
|
||||
- ✅ Complete documentation structure (`/docs`)
|
||||
- ✅ 6 AI agent profiles with detailed instructions
|
||||
- ✅ 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
|
||||
- ✅ Complete documentation structure (`/docs`)
|
||||
- ✅ 7 AI agent profiles with detailed instructions
|
||||
- ✅ 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
|
||||
|
||||
---
|
||||
|
||||
@@ -95,21 +95,21 @@ ls -la 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 |
|
||||
| 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.
|
||||
|
||||
@@ -156,7 +156,8 @@ your-project/
|
||||
│ ├── security-auditor.md # Security agent profile
|
||||
│ ├── test-engineer.md # Testing agent profile
|
||||
│ ├── code-reviewer.md # Code review agent profile
|
||||
│ └── prompt-engineer.md # Prompt engineering agent
|
||||
│ ├── prompt-engineer.md # Prompt engineering agent
|
||||
│ └── documentation-expert.md # Documentation specialist
|
||||
├── apps/ # Application code (Phase 2+)
|
||||
│ ├── web/ # Frontend app (Next.js)
|
||||
│ └── api/ # Backend API (Node.js)
|
||||
@@ -188,6 +189,7 @@ your-project/
|
||||
### 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
|
||||
@@ -195,12 +197,14 @@ your-project/
|
||||
- **[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
|
||||
@@ -208,6 +212,7 @@ your-project/
|
||||
- **[Payment Flow](./docs/backend/payment-flow.md)** - Provider-agnostic payment design
|
||||
|
||||
**AI Agents:**
|
||||
|
||||
- **[RULES.md](./RULES.md)** - Agent selection protocol and project rules
|
||||
- **[Frontend Architect](./agents/frontend-architect.md)** - Frontend specialist agent
|
||||
- **[Backend Architect](./agents/backend-architect.md)** - Backend specialist agent
|
||||
@@ -215,6 +220,7 @@ your-project/
|
||||
- **[Test Engineer](./agents/test-engineer.md)** - Testing specialist agent
|
||||
- **[Code Reviewer](./agents/code-reviewer.md)** - Code quality agent
|
||||
- **[Prompt Engineer](./agents/prompt-engineer.md)** - AI prompt specialist
|
||||
- **[Documentation Expert](./agents/documentation-expert.md)** - Technical writing & docs maintenance
|
||||
|
||||
---
|
||||
|
||||
@@ -223,6 +229,7 @@ your-project/
|
||||
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
|
||||
@@ -230,6 +237,7 @@ This template follows a 5-phase methodology. Adapt to your project timeline:
|
||||
- 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
|
||||
@@ -238,6 +246,7 @@ This template follows a 5-phase methodology. Adapt to your project timeline:
|
||||
- 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
|
||||
@@ -246,6 +255,7 @@ This template follows a 5-phase methodology. Adapt to your project timeline:
|
||||
- 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
|
||||
@@ -254,6 +264,7 @@ This template follows a 5-phase methodology. Adapt to your project timeline:
|
||||
- Prepare for production deployment
|
||||
|
||||
### Phase 4 - Support & Evolution (Ongoing)
|
||||
|
||||
- Production deployment and monitoring
|
||||
- Bug fixes and maintenance
|
||||
- Feature iterations based on user feedback
|
||||
@@ -272,6 +283,7 @@ See [`docs/phases-plan.md`](docs/phases-plan.md) for detailed phase breakdown.
|
||||
### For New Projects
|
||||
|
||||
1. **Clone/Fork this repository**
|
||||
|
||||
```bash
|
||||
git clone <your-repo-url>
|
||||
cd <your-project-name>
|
||||
@@ -330,10 +342,12 @@ Before starting a task, select the appropriate agent based on [`RULES.md`](RULES
|
||||
- **Testing** → [`test-engineer.md`](agents/test-engineer.md)
|
||||
- **Code review** → [`code-reviewer.md`](agents/code-reviewer.md)
|
||||
- **AI/LLM integration** → [`prompt-engineer.md`](agents/prompt-engineer.md)
|
||||
- **Documentation** → [`documentation-expert.md`](agents/documentation-expert.md)
|
||||
|
||||
### 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
|
||||
@@ -354,6 +368,7 @@ Each agent profile includes:
|
||||
The template includes patterns for common modules. **Keep only what you need:**
|
||||
|
||||
### Core Modules (Common to Most Projects)
|
||||
|
||||
- ✅ Authentication & Authorization
|
||||
- ✅ User Management
|
||||
- ✅ Database & ORM
|
||||
@@ -362,6 +377,7 @@ The template includes patterns for common modules. **Keep only what you need:**
|
||||
- ✅ 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)
|
||||
@@ -378,6 +394,7 @@ 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)
|
||||
@@ -385,6 +402,7 @@ See [`docs/archetypes.md`](docs/archetypes.md) for detailed module descriptions.
|
||||
- ✅ Use ADRs for architecture decisions
|
||||
|
||||
### Code Organization
|
||||
|
||||
- ✅ Feature-first structure (frontend)
|
||||
- ✅ Modular monolith (backend)
|
||||
- ✅ Colocate tests with code
|
||||
@@ -392,6 +410,7 @@ See [`docs/archetypes.md`](docs/archetypes.md) for detailed module descriptions.
|
||||
- ✅ Follow single responsibility principle
|
||||
|
||||
### Security
|
||||
|
||||
- ✅ OWASP Top 10 compliance
|
||||
- ✅ Input validation (client + server)
|
||||
- ✅ Rate limiting on sensitive endpoints
|
||||
@@ -399,6 +418,7 @@ See [`docs/archetypes.md`](docs/archetypes.md) for detailed module descriptions.
|
||||
- ✅ Regular security audits
|
||||
|
||||
### AI Agent Usage
|
||||
|
||||
- ✅ Select appropriate agent for each task
|
||||
- ✅ Provide context in agent prompts
|
||||
- ✅ Review AI-generated code before committing
|
||||
@@ -414,21 +434,25 @@ See [`RECOMMENDATIONS.md`](RECOMMENDATIONS.md) for detailed best practices.
|
||||
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
|
||||
@@ -476,6 +500,7 @@ Need help using this template?
|
||||
## 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
|
||||
@@ -485,6 +510,6 @@ Inspired by best practices from Next.js, T3 Stack, and enterprise SaaS architect
|
||||
---
|
||||
|
||||
**Status:** Phase 0 🚀 Template Ready - **Ready for Customization**
|
||||
**Documentation:** 📚 Complete (20+ guides) | **AI Agents:** 🤖 6 specialized profiles
|
||||
**Documentation:** 📚 Complete (20+ guides) | **AI Agents:** 🤖 7 specialized profiles
|
||||
**Architecture:** ✅ Frontend (Feature-first) + Backend (Modular Monolith)
|
||||
**Security:** ✅ OWASP Top 10 patterns | **Deployment:** ✅ Docker + CI/CD templates
|
||||
**Security:** ✅ OWASP Top 10 patterns | **Deployment:** ✅ Docker + CI/CD templates
|
||||
|
||||
Reference in New Issue
Block a user