🌐 Web App Template - Complete Package

Everything you need to build Next.js/React web apps with AI agents

📦 Package Contents

web-template/
├── README.md                    ← You are here
├── STRUCTURE_GUIDE.md           ← How agents understand this
├── PROJECT_CONTEXT.md           ← Define your Next.js stack
├── INITIAL.md                   ← Feature request template
├── INITIAL_EXAMPLE.md           ← Complete example
├── .agent/
│   ├── context/
│   │   └── GLOBAL_RULES.md     ← Universal standards
│   ├── orchestration/
│   │   ├── directives/
│   │   │   └── web_feature.md  ← How to build web features
│   │   └── knowledge_base/     ← ML learning data
│   └── execution/
│       └── context_utils.py    ← ML operations
└── requirements.txt

---

⚡ Quick Start

# 1. Copy to your project
cd my-web-app
cp -r /path/to/web-template/* .
cp -r /path/to/web-template/.agent .

# 2. Initialize ML system
pip install -r requirements.txt
python .agent/execution/context_utils.py init

# 3. Configure your stack in PROJECT_CONTEXT.md
# - Next.js version (App Router or Pages Router?)
# - Styling (Tailwind? shadcn/ui?)
# - State management (Zustand? Server state?)
# - Auth (NextAuth? Supabase? Clerk?)

# 4. Build features using INITIAL.md

---

🎯 What This Does

For Next.js/React applications:

• Server Components vs Client Components
• SSR/SSG/ISR strategies
• API Routes & Server Actions
• SEO & metadata management
• Core Web Vitals optimization

Agent learns:

• Hydration issues
• Server/client boundaries
• Performance optimization
• Browser compatibility

---

🧠 How Agents Use This

Reading Order

1. PROJECT_CONTEXT.md → Next.js setup (App/Pages Router, rendering strategy)
2. INITIAL.md → What to build
3. GLOBAL_RULES.md → Coding standards
4. web_feature.md → Build process
5. knowledge_base/*.yaml → Past learnings

Key Decisions

"App Router or Pages Router?"

Read PROJECT_CONTEXT.md → User chose App Router
Therefore: Use Server Components, app/ directory, Route Handlers

"Client or Server Component?"

Check if needs:
- Interactivity (onClick, useState) → Client Component ('use client')
- Data fetching from DB → Server Component
- Browser APIs → Client Component

"Where to fetch data?"

App Router:
- Server Components → async/await directly
- Client Components → React Query/SWR

Pages Router:
- getServerSideProps for SSR
- getStaticProps for SSG

---

📋 Common Use Cases

Authentication (NextAuth)

# INITIAL.md
## 🎯 FEATURE
NextAuth.js authentication with Google OAuth

## 🏗️ TECH STACK
- Auth: NextAuth.js
- Session: JWT tokens
- Storage: httpOnly cookies

Dashboard with Data

# INITIAL.md
## 🎯 FEATURE
User dashboard with server-side data

## 🏗️ TECH STACK
- Rendering: Server Components
- Database: Prisma + PostgreSQL
- Caching: Next.js cache

Form with Validation

# INITIAL.md
## 🎯 FEATURE
Contact form with server action

## 🏗️ TECH STACK
- Form: React Hook Form
- Validation: Zod
- Submission: Server Action

---

🚨 Web-Specific Gotchas

Agents must prevent:

• ❌ Hydration mismatches (server ≠ client HTML)
• ❌ Using hooks in Server Components
• ❌ Client-side API calls from Server Components
• ❌ Missing 'use client' directive
• ❌ Forgetting 'use server' for Server Actions

Agents ensure:

• ✅ Proper Server/Client separation
• ✅ Metadata for SEO
• ✅ Image optimization with next/image
• ✅ Core Web Vitals < targets
• ✅ Browser compatibility

---

📊 Performance Targets

From PROJECT_CONTEXT.md:

• LCP: < 2.5s
• FID: < 100ms
• CLS: < 0.1
• First Load JS: < 100KB
• Lighthouse: > 90

---

💡 Pro Tips

1. Use Server Components by default - Only add 'use client' when needed
2. Optimize images - Always use next/image
3. Monitor Core Web Vitals - Check Lighthouse scores
4. Cache strategically - SSG for static, ISR for semi-static, SSR for dynamic

---

This is a complete, standalone web template. Everything for Next.js/React apps is here. 🌐