feat: add root documentation (CLAUDE.md, AGENTS.md, .mcp.json)

.mcp.json

@@ -0,0 +1,13 @@
+{
+  "mcpServers": {
+    "storybook": {
+      "type": "http",
+      "url": "http://localhost:6006/mcp"
+    },
+    "playwright": {
+      "type": "stdio",
+      "command": "npx",
+      "args": ["@anthropic-ai/playwright-mcp"]
+    }
+  }
+}

AGENTS.md

@@ -0,0 +1,71 @@
+# Agent Instructions
+
+## Monorepo Package Map
+
+| Package | Purpose |
+|---|---|
+| `@repo/core` | Clean architecture: entities, use cases, interfaces, DI |
+| `@repo/api` | tRPC router definitions (calls core controllers) |
+| `@repo/api-client` | Shared React Query hooks + ApiProvider |
+| `@repo/cms-core` | Payload CMS config, collections, hooks, globals |
+| `@repo/cms-client` | Dual-mode Payload client (local + HTTP) |
+| `@repo/ui` | shadcn/ui + Atomic Design component library |
+| `@repo/eslint-config` | Shared ESLint flat configs |
+| `@repo/typescript-config` | Shared TypeScript configs |
+
+| App | Purpose |
+|---|---|
+| `apps/web-next` | Next.js 15 reference app |
+| `apps/web-tanstack` | TanStack Start reference app |
+| `apps/cms` | Thin Next.js shell for Payload admin |
+| `apps/storybook` | Centralized Storybook instance |
+
+## Dependency Flow (one direction only)
+
+```
+apps/web-next, apps/web-tanstack → @repo/api-client → @repo/api → @repo/core
+apps/cms → @repo/cms-core → @repo/core/application (hooks only)
+@repo/core/infrastructure → @repo/cms-client (standalone)
+@repo/ui (standalone)
+```
+
+## HARD RULES — NEVER VIOLATE
+
+- **NEVER:** packages/core → apps/*
+- **NEVER:** apps/cms → packages/core/infrastructure
+- **NEVER:** packages/cms-client → apps/cms or packages/core or packages/cms-core
+- **NEVER:** packages/cms-core → packages/cms-client
+- **NEVER:** core/entities → anything
+- **NEVER:** core/application → core/infrastructure
+
+## How to Add a New Feature (end-to-end)
+
+1. Define entity in `packages/core/src/entities/models/`
+2. Define repository interface in `packages/core/src/application/repositories/`
+3. Write use case in `packages/core/src/application/use-cases/{domain}/`
+4. Write controller in `packages/core/src/interface-adapters/controllers/{domain}/`
+5. Write infrastructure implementation in `packages/core/src/infrastructure/`
+6. Register in DI container (`packages/core/src/di/`)
+7. Add tRPC router in `packages/api/src/router/`
+8. Add React Query hook in `packages/api-client/src/hooks/`
+9. If CMS collection needed: add to `packages/cms-core/src/collections/`
+10. Build UI component in `packages/ui/src/` (classify atomic level)
+11. Write Storybook story (co-located `.stories.tsx`)
+12. Write tests (unit in packages/core/tests/, E2E in tests/e2e/)
+
+## How to Add a New UI Component
+
+1. Classify: atom (single element), molecule (2-3 atoms), organism (complex section), template (layout)
+2. Create folder: `packages/ui/src/{level}/{component-name}/`
+3. Create: `{name}.tsx`, `{name}.stories.tsx`, `index.ts`
+4. Story title: `"{Level}/{ComponentName}"` (e.g., `"Atoms/Button"`)
+5. Export from level's `index.ts` barrel file
+6. Import rules: atoms ← nothing | molecules ← atoms | organisms ← atoms+molecules | templates ← all
+
+## How to Add a Payload CMS Collection
+
+1. Create folder: `packages/cms-core/src/collections/{name}/`
+2. Create: `index.ts` (CollectionConfig), `fields.ts`, optionally `hooks/`, `access/`
+3. Import in `packages/cms-core/src/payload.config.ts` collections array
+4. Export from `packages/cms-core/src/index.ts`
+5. Hooks that contain business logic must delegate to use cases in `@repo/core/application`

CLAUDE.md

@@ -0,0 +1,37 @@
+# Clean Architecture Monorepo Template
+
+## Quick Start
+
+```bash
+pnpm install          # Install all dependencies
+pnpm dev              # Start all dev servers
+pnpm build            # Build all packages
+pnpm test             # Run all tests
+docker compose up -d  # Start PostgreSQL
+```
+
+## Project Overview
+
+Turborepo + pnpm monorepo based on Clean Architecture (Uncle Bob / Lazar Nikolov). Supports Next.js and TanStack Start as frontend frameworks, Payload CMS for content management, and comprehensive agent-optimized documentation.
+
+## Read First
+
+- `AGENTS.md` — Monorepo structure, dependency flow, hard rules
+- `docs/architecture/overview.md` — High-level architecture
+- `docs/guides/adding-a-feature.md` — End-to-end walkthrough
+
+## MCP Servers
+
+Start Storybook before UI work: `pnpm dev --filter @repo/storybook`
+
+Storybook MCP available at `http://localhost:6006/mcp` — use `list-all-documentation` to discover existing components before creating new ones.
+
+## Key Ports
+
+| Service | Port |
+|---|---|
+| Next.js | 3000 |
+| Payload CMS | 3001 |
+| TanStack Start | 3002 |
+| PostgreSQL | 5432 |
+| Storybook | 6006 |

docs/superpowers/plans/2026-04-06-plan-6-documentation.md

@@ -0,0 +1,9 @@
+# Plan 6: Documentation + Agent Infrastructure
+
+> **For agentic workers:** REQUIRED SUB-SKILL: Use superpowers:subagent-driven-development (recommended) or superpowers:executing-plans to implement this plan task-by-task.
+
+**Goal:** Create all AGENTS.md files (~22), root CLAUDE.md, .mcp.json, and docs/ architecture guides so AI agents can navigate and extend the codebase autonomously.
+
+**Architecture:** 4-tier documentation: Root (CLAUDE.md + AGENTS.md) → Package → Layer → Domain. Each file contains rules, recipes, and tables — not prose.
+
+**Tasks:** 5 tasks covering root docs, core AGENTS.md files, package AGENTS.md files, app AGENTS.md files, and docs/ folder.