From 3afd522bce7c548a9ae41f6bc3536be4ae003b32 Mon Sep 17 00:00:00 2001 From: sriram veeraghanta Date: Fri, 19 Jun 2026 01:31:26 +0530 Subject: [PATCH] docs: consolidate agent guidance into AGENTS.md, symlink CLAUDE.md Merge the project overview, commands, architecture, custom-component reference, API doc pattern, and conventions from CLAUDE.md together with the directory map and key documentation paths from AGENTS.md into a single canonical AGENTS.md (the cross-tool standard). CLAUDE.md is now a symlink to AGENTS.md so Claude Code and other agents share one source of truth. Also refresh stale paths for the recent restructure: plane-ai.md is now the plane-ai/ directory, and add the pnpm check:types command. --- AGENTS.md | 96 +++++++++++++++++++++++++++++++++++++++++++++---------- CLAUDE.md | 69 +-------------------------------------- 2 files changed, 81 insertions(+), 84 deletions(-) mode change 100644 => 120000 CLAUDE.md diff --git a/AGENTS.md b/AGENTS.md index 4d5dba98..a0a016bb 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -1,10 +1,37 @@ -# Developer Docs Agent Context +# AGENTS.md -## Purpose +Guidance for AI coding agents (Claude Code, Codex, Cursor, etc.) working in this repository. `CLAUDE.md` is a symlink to this file, so both resolve to the same content. -Internal developer documentation for Plane EE. +## Project Overview -## Structure +This is the **Plane developer documentation site** built with **VitePress** (Vue 3-based static site generator). It covers REST API reference, self-hosting guides, and developer tools documentation for the Plane project management platform. + +Live site: https://developers.plane.so + +## Commands + +```bash +pnpm install # Install dependencies (use --frozen-lockfile in CI) +pnpm dev # Start dev server at http://localhost:5173 +pnpm build # Production build +pnpm preview # Preview production build +pnpm check:format # Check Prettier formatting +pnpm fix:format # Auto-fix Prettier formatting +pnpm check:types # Type-check the VitePress config and theme +``` + +**CI checks on PRs** (to `master`): Prettier formatting + VitePress build must pass. + +## Architecture + +- **`docs/`** — All documentation content and VitePress config + - **`docs/.vitepress/config.mts`** — Main VitePress config: navigation, sidebar structure, SEO, Algolia search, analytics. This is a large file that defines the entire site structure. + - **`docs/.vitepress/theme/`** — Custom theme (extends `@voidzero-dev/vitepress-theme` via `extendConfig`) with Vue components and global styles + - **`docs/api-reference/`** — REST API endpoint docs (180+ endpoints across 30+ resource categories) + - **`docs/self-hosting/`** — Deployment and configuration guides + - **`docs/dev-tools/`** — Webhooks, OAuth apps, agents, MCP server docs + +### Directory structure ```text docs/ @@ -22,26 +49,63 @@ docs/ install-methods-commercial/ # Commercial Docker Compose and Kubernetes govern/ # Auth, integrations, settings, SSL, DNS, env vars integrations/ # GitHub, GitLab, Slack, Sentry + plane-ai/ # AI features configuration (configure-plane-ai, embedding models) manage/ # Backup/restore, Prime CLI, update Plane, logs, user management troubleshoot/ # CLI errors, installation, license, storage errors ``` ## Key Documentation Paths -- `self-hosting/methods/kubernetes.md` - K8s deployment guide -- `self-hosting/methods/install-methods-commercial/` - Commercial Docker Compose and Kubernetes -- `self-hosting/govern/integrations/` - GitHub, GitLab, Slack, Sentry -- `self-hosting/govern/plane-ai.md` - AI features configuration -- `self-hosting/govern/environment-variables.md` - All env var reference -- `self-hosting/govern/authentication.md` - Auth setup (LDAP, OIDC, SAML, OAuth) -- `self-hosting/govern/reverse-proxy.md` - Reverse proxy setup -- `self-hosting/manage/` - Instance management, backup/restore, Prime CLI -- `dev-tools/agents/` - Agent development docs -- `dev-tools/mcp-server.md` and `mcp-server-claude-code.md` - MCP server docs +- `self-hosting/methods/kubernetes.md` — K8s deployment guide +- `self-hosting/methods/install-methods-commercial/` — Commercial Docker Compose and Kubernetes +- `self-hosting/govern/integrations/` — GitHub, GitLab, Slack, Sentry +- `self-hosting/govern/plane-ai/` — AI features configuration (`configure-plane-ai.md`, `configure-embedding-model.md`, `aws-opensearch-embedding.md`) +- `self-hosting/govern/environment-variables.md` — All env var reference +- `self-hosting/govern/authentication.md` — Auth setup (LDAP, OIDC, SAML, OAuth) +- `self-hosting/govern/reverse-proxy.md` — Reverse proxy setup +- `self-hosting/manage/` — Instance management, backup/restore, Prime CLI +- `dev-tools/agents/` — Agent development docs +- `dev-tools/mcp-server.md` and `mcp-server-claude-code.md` — MCP server docs + +## Custom Vue Components + +Used directly in markdown files — defined in `docs/.vitepress/theme/components/`: + +| Component | Usage | +| ---------------------- | ----------------------------------------------------------------- | +| `` | API parameter with name, type, required badge, expandable details | +| `` | Multi-language code tabs (cURL, Python, JavaScript) | +| `` | Syntax-highlighted API response JSON | +| `` | Feature card with icon, title, description | +| `` | Responsive grid layout (2, 3, or 4 columns) | + +## API Documentation Pattern + +API endpoint pages follow a strict two-column layout pattern: + +```markdown +
+
+ +
+
+ +
+
+``` + +Each endpoint page: one file per endpoint, includes path/body params, OAuth scopes, and code examples in cURL/Python/JavaScript. + +## Conventions + +- **Frontmatter**: Every markdown page needs `title`, `description`, and `keywords` fields +- **Images**: Stored in `docs/.vitepress/public/images/`, referenced with absolute paths (`/images/...`) +- **Branch workflow**: Branch from `master`, use `fix/`, `feat/`, `docs/`, `update/` prefixes +- **Formatting**: Prettier enforced — 120 char width, 2-space indent, semicolons, double quotes, ES5 trailing commas +- **Sidebar updates**: When adding new pages, update the sidebar config in `docs/.vitepress/config.mts` ## Important Notes - Not all features are documented immediately after release -- Check both public docs (docs.plane.so) and internal docs -- `self-hosting/govern/plane-ai.md` is the correct path for AI config (not `self-hosting/plane-ai.md`) - API reference covers 30+ resource categories — check `docs/api-reference/` for the full list +- `self-hosting/govern/plane-ai/` is the correct location for AI configuration (the former `self-hosting/govern/plane-ai.md` was split into a directory) diff --git a/CLAUDE.md b/CLAUDE.md deleted file mode 100644 index b2aa565f..00000000 --- a/CLAUDE.md +++ /dev/null @@ -1,68 +0,0 @@ -# CLAUDE.md - -This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository. - -## Project Overview - -This is the **Plane developer documentation site** built with **VitePress** (Vue 3-based static site generator). It covers REST API reference, self-hosting guides, and developer tools documentation for the Plane project management platform. - -Live site: https://developers.plane.so - -## Commands - -```bash -pnpm install # Install dependencies (use --frozen-lockfile in CI) -pnpm dev # Start dev server at http://localhost:5173 -pnpm build # Production build -pnpm preview # Preview production build -pnpm check:format # Check Prettier formatting -pnpm fix:format # Auto-fix Prettier formatting -``` - -**CI checks on PRs** (to `master`): Prettier formatting + VitePress build must pass. - -## Architecture - -- **`docs/`** — All documentation content and VitePress config - - **`docs/.vitepress/config.mts`** — Main VitePress config: navigation, sidebar structure, SEO, Algolia search, analytics. This is a large file (~39KB) that defines the entire site structure. - - **`docs/.vitepress/theme/`** — Custom theme with Vue components and global styles - - **`docs/api-reference/`** — REST API endpoint docs (180+ endpoints across 25+ categories) - - **`docs/self-hosting/`** — Deployment guides (Docker, Kubernetes, etc.) - - **`docs/dev-tools/`** — Webhooks, OAuth apps, agents, MCP server docs - -## Custom Vue Components - -Used directly in markdown files — defined in `docs/.vitepress/theme/components/`: - -| Component | Usage | -| ---------------------- | ----------------------------------------------------------------- | -| `` | API parameter with name, type, required badge, expandable details | -| `` | Multi-language code tabs (cURL, Python, JavaScript) | -| `` | Syntax-highlighted API response JSON | -| `` | Feature card with icon, title, description | -| `` | Responsive grid layout (2, 3, or 4 columns) | - -## API Documentation Pattern - -API endpoint pages follow a strict two-column layout pattern: - -```markdown -
-
- -
-
- -
-
-``` - -Each endpoint page: one file per endpoint, includes path/body params, OAuth scopes, and code examples in cURL/Python/JavaScript. - -## Conventions - -- **Frontmatter**: Every markdown page needs `title`, `description`, and `keywords` fields -- **Images**: Stored in `docs/.vitepress/public/images/`, referenced with absolute paths (`/images/...`) -- **Branch workflow**: Branch from `master`, use `fix/`, `feat/`, `docs/`, `update/` prefixes -- **Formatting**: Prettier enforced — 120 char width, 2-space indent, semicolons, double quotes, ES5 trailing commas -- **Sidebar updates**: When adding new pages, update the sidebar config in `docs/.vitepress/config.mts` diff --git a/CLAUDE.md b/CLAUDE.md new file mode 120000 index 00000000..47dc3e3d --- /dev/null +++ b/CLAUDE.md @@ -0,0 +1 @@ +AGENTS.md \ No newline at end of file