From eb195c82618aae9fc3dba257da4fe3e683fb25d2 Mon Sep 17 00:00:00 2001 From: Danijel Martinek Date: Mon, 6 Apr 2026 15:02:01 +0200 Subject: [PATCH] feat: add root documentation (CLAUDE.md, AGENTS.md, .mcp.json) --- .mcp.json | 13 ++++ AGENTS.md | 71 +++++++++++++++++++ CLAUDE.md | 37 ++++++++++ .../plans/2026-04-06-plan-6-documentation.md | 9 +++ 4 files changed, 130 insertions(+) create mode 100644 .mcp.json create mode 100644 AGENTS.md create mode 100644 CLAUDE.md create mode 100644 docs/superpowers/plans/2026-04-06-plan-6-documentation.md diff --git a/.mcp.json b/.mcp.json new file mode 100644 index 0000000..8b126b6 --- /dev/null +++ b/.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"] + } + } +} diff --git a/AGENTS.md b/AGENTS.md new file mode 100644 index 0000000..fe99908 --- /dev/null +++ b/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` diff --git a/CLAUDE.md b/CLAUDE.md new file mode 100644 index 0000000..d8e080a --- /dev/null +++ b/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 | diff --git a/docs/superpowers/plans/2026-04-06-plan-6-documentation.md b/docs/superpowers/plans/2026-04-06-plan-6-documentation.md new file mode 100644 index 0000000..dbf0024 --- /dev/null +++ b/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.