From 9bd041888e1e3c8f334d30b8a5bded624bfdbb35 Mon Sep 17 00:00:00 2001 From: Alem Tuzlak Date: Mon, 23 Feb 2026 18:15:52 +0100 Subject: [PATCH] docs: refactor AGENTS.md and CLAUDE.md with progressive disclosure (#3259) Co-authored-by: Claude Opus 4.6 --- .claude/docs/architecture.md | 75 ++++++++++++++++++++++++++++++++++++ .claude/docs/git.md | 27 +++++++++++++ .claude/docs/hooks.md | 8 ++++ .claude/docs/workflow.md | 30 +++++++++++++++ AGENTS.md | 21 +++++++--- CLAUDE.md | 21 +++++++--- 6 files changed, 170 insertions(+), 12 deletions(-) create mode 100644 .claude/docs/architecture.md create mode 100644 .claude/docs/git.md create mode 100644 .claude/docs/hooks.md create mode 100644 .claude/docs/workflow.md diff --git a/.claude/docs/architecture.md b/.claude/docs/architecture.md new file mode 100644 index 0000000000..9b5dba78ee --- /dev/null +++ b/.claude/docs/architecture.md @@ -0,0 +1,75 @@ +# Architecture & Packages + +## Three-Layer Architecture + +``` +Frontend (React/Angular/Vanilla) → Runtime (Express/Hono server) → Agent (LangGraph/CrewAI/BuiltIn/Custom) +``` + +All layers communicate via the **AG-UI protocol** — an event-based standard streamed over SSE. + +## V1 vs V2 + +V2 (`@copilotkitnext/`) is the real implementation. V1 (`@copilotkit/`) is the public API that wraps V2 internally. New features always go in V2. If V1 compatibility is needed, create a thin re-export or wrapper in the corresponding V1 package. + +## V2 Packages + +- **shared**: Common utilities, types, and constants used across all other packages. +- **core**: The `CopilotKitCore` orchestrator — the central brain on the frontend. Manages the agent registry, tool registry, context store, and event subscriptions. All framework packages (React, Angular, Vanilla) wrap this. +- **react**: React hooks (`useAgent`, `useFrontendTool`, `useAgentContext`, etc.) and `CopilotKitProvider`. Hooks are thin wrappers that register/unregister with `CopilotKitCore` on mount/unmount. +- **angular**: Angular DI tokens, services, and signal-based state. Same concepts as React but using Angular patterns (`inject()`, signals, `AgentStore`). +- **runtime**: The server-side `CopilotRuntime` class that receives HTTP requests and delegates to agents. Provides Express and Hono adapters. Contains the `AgentRunner` abstraction for managing thread/conversation state. +- **agent**: The `BuiltInAgent` — a default agent implementation powered by the Vercel AI SDK. Used when developers don't bring their own agent framework. +- **voice**: Voice input and transcription support. +- **web-inspector**: A debug console (Lit web component) for inspecting agent communication in development. +- **sqlite-runner**: An `AgentRunner` implementation that persists thread state to SQLite instead of memory. + +## V1 Packages + +- **react-core**: The public `` provider and hooks. Internally delegates to V2 core. +- **react-ui**: Chat UI components — `CopilotChat`, `CopilotPopup`, `CopilotSidebar`, `CopilotPanel`. +- **react-textarea**: The `CopilotTextarea` component for AI-assisted text editing. +- **shared**: Shared types and telemetry utilities. +- **runtime**: Server-side runtime with GraphQL server and LLM adapters. +- **runtime-client-gql**: urql-based GraphQL client for frontend-to-runtime communication. +- **sdk-js**: Helpers for LangGraph/LangChain agent integration. + +## Request Lifecycle + +1. **Init**: Frontend creates `CopilotKitCore` → fetches agent info from runtime → creates a `ProxiedAgent` instance per remote agent. +2. **User sends message**: Message is added to the agent, then `runAgent()` is called. +3. **HTTP request**: A POST is sent to the runtime with a `RunAgentInput` payload containing messages, registered tools, context, threadId, and state. +4. **Runtime processing**: Request middleware runs → agent is resolved and cloned → `AgentRunner` executes the agent. +5. **SSE stream back**: Agent emits AG-UI events streamed to the frontend: run lifecycle events, text message chunks (streaming), and optional tool call events. +6. **Frontend tool execution**: When the agent calls a frontend tool, Core looks up the handler in its registry, executes it locally in the browser, and sends the result back to the agent which continues processing. +7. **UI update**: Core updates its message store and notifies subscribers → React/Angular re-renders. + +## Core Concepts + +### AG-UI Protocol + +All agent↔UI communication is event-based. Events follow a structured lifecycle: `RUN_STARTED` → `STEP_STARTED` → message/tool events → `STEP_FINISHED` → `RUN_FINISHED`. Events are streamed over SSE and validated with Zod schemas. The `EventType` enum in `@ag-ui/core` defines all event types. + +### ProxiedAgent + +The frontend representation of a remote agent. Implements the `AbstractAgent` interface but translates calls into HTTP requests to the runtime, streaming SSE events back. Created automatically when the runtime reports available agents. + +### AgentRunner + +An abstract class on the runtime side responsible for managing thread state (conversation history, agent state). The default `InMemoryAgentRunner` is ephemeral; `SQLiteAgentRunner` provides persistence. Custom runners can be built for any storage backend. + +### Tool Registration + +Tools can be **frontend tools** (handler runs in the browser, registered via `useFrontendTool`) or **backend tools** (handler runs on the server, defined in the agent config). Tools can be scoped to a specific agent via `agentId`, or available to all agents by omitting it. + +### Context + +Application data sent alongside messages to give agents awareness of the current UI state. Registered via `useAgentContext(description, data)` where data is any JSON-serializable value. Automatically included in every agent run. + +### Multi-Agent + +Multiple agents can be registered in a single `CopilotRuntime`. Each agent gets its own endpoint, message thread, state, and optionally scoped tools. The frontend selects which agent to interact with via `useAgent({ agentId })`. + +### Middleware + +`CopilotRuntime` supports `beforeRequestMiddleware` and `afterRequestMiddleware` for cross-cutting concerns like authentication, logging, and request/response transformation. diff --git a/.claude/docs/git.md b/.claude/docs/git.md new file mode 100644 index 0000000000..7fe9ce9e12 --- /dev/null +++ b/.claude/docs/git.md @@ -0,0 +1,27 @@ +# Git & PRs + +## Worktree Workflow + +Always use a git worktree for non-trivial work. This keeps the main working tree clean and lets you work in isolation. + +1. **Start a worktree** at the beginning of a task. This creates a new branch and a separate working directory. +2. **Do all work** inside the worktree — commits, builds, tests. +3. **Push the worktree branch** to the remote with `-u` to set up tracking. +4. **Create a PR** targeting `main` using `gh pr create --base main`. +5. **Clean up** the worktree after the PR is merged. + +## Creating a PR + +When the work is ready: + +1. Stage and commit your changes in the worktree. +2. Push the branch: `git push -u origin ` +3. Create the PR: `gh pr create --base main` +4. Use a clear title (under 70 chars) and a body summarizing what changed and why. + +## Commit Conventions + +- Write concise commit messages focused on the "why", not the "what". +- Stage specific files — avoid `git add -A` or `git add .` to prevent accidentally including unrelated changes. +- Never amend commits unless explicitly asked. Always create new commits. +- Never force-push unless explicitly asked. diff --git a/.claude/docs/hooks.md b/.claude/docs/hooks.md new file mode 100644 index 0000000000..f8ba41407b --- /dev/null +++ b/.claude/docs/hooks.md @@ -0,0 +1,8 @@ +# Hook Development + +When creating a new hook, always complete **all** of the following: + +1. **Implementation**: Create the hook in the V2 react package. If V1 compatibility is needed, add a re-export in the V1 react-core package. +2. **JSDoc**: Add JSDoc on top of the hook implementation, including usage examples. +3. **Tests**: Write extensive tests covering behavior, edge cases, and lifecycle (mount/unmount/re-render). +4. **Documentation**: Add a dedicated docs page under `/docs` and update the relevant docs metadata file(s) so the page appears in navigation. diff --git a/.claude/docs/workflow.md b/.claude/docs/workflow.md new file mode 100644 index 0000000000..869da5384c --- /dev/null +++ b/.claude/docs/workflow.md @@ -0,0 +1,30 @@ +# Workflow & Process + +## When to Plan vs. Fix Autonomously + +- **Bug fixes** (small/medium, < 5 files): Fix autonomously. No plan mode, no check-in. Just fix it, run tests, done. +- **Large bugs** (5+ files or architectural impact): Enter plan mode first. +- **New features and refactors**: Always enter plan mode. Get user sign-off on the approach before implementing. + +## Planning + +- Enter plan mode for non-trivial features and refactors. +- Write the plan to `tasks/todo.md` with checkable items. +- If something goes sideways during implementation, stop and re-plan — don't push through a broken approach. + +## Verification + +- Never mark a task complete without proving it works. +- Run tests and check for regressions. +- Diff behavior between main and your changes when relevant. + +## Bug Fixing + +- When given a bug report: find the root cause, fix it, verify. No hand-holding needed. +- Point at logs, errors, failing tests — then resolve them. +- Go fix failing CI tests without being told how. + +## Self-Improvement + +- After any correction from the user: update `tasks/lessons.md` with the pattern and a rule to prevent it. +- Review lessons at session start. diff --git a/AGENTS.md b/AGENTS.md index dacd9b4623..41465f5c7a 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -13,11 +13,20 @@ -# Hook Development Requirements +# CopilotKit -When creating a new hook, always complete all of the following: +AI agent framework with three layers: **Frontend** (React/Angular/Vanilla) → **Runtime** (Express/Hono) → **Agent** (LangGraph/CrewAI/BuiltIn/Custom), communicating via the AG-UI protocol (event-based SSE). -- Add dedicated documentation for the hook under `/docs`. -- Update the relevant docs metadata file(s) so the page appears in docs navigation. -- Add JSDoc on top of the hook implementation, including usage examples. -- Write extensive tests for the hook (covering behavior, edge cases, and lifecycle where applicable). +## Essentials + +- **Nx monorepo** — always run tasks through `nx` (`nx run`, `nx run-many`, `nx affected`), never the underlying tooling directly. +- **V1 wraps V2** — V2 (`@copilotkitnext/`) is the real implementation. V1 (`@copilotkit/`) is the public compatibility layer that delegates to V2. Build new features in V2 first. Add V1 wrappers only if backward compatibility is needed. +- **Simplicity** — prefer the simplest correct solution. For non-trivial changes, consider if there's a cleaner approach before committing. +- **Worktrees** — always work in a git worktree for isolation. See [Git & PRs](.claude/docs/git.md) for the full workflow. + +## Reference (read when relevant to your task) + +- [Architecture & Packages](.claude/docs/architecture.md) — V2/V1 package roles, request lifecycle, core concepts (AG-UI, ProxiedAgent, AgentRunner, tools, context, multi-agent) +- [Hook Development](.claude/docs/hooks.md) — checklist for creating new hooks (docs, tests, JSDoc) +- [Workflow & Process](.claude/docs/workflow.md) — when to plan, when to fix autonomously, verification, self-improvement loop, this should be your default mindset when working on any task +- [Git & PRs](.claude/docs/git.md) — worktree workflow, branching, creating PRs diff --git a/CLAUDE.md b/CLAUDE.md index dacd9b4623..41465f5c7a 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -13,11 +13,20 @@ -# Hook Development Requirements +# CopilotKit -When creating a new hook, always complete all of the following: +AI agent framework with three layers: **Frontend** (React/Angular/Vanilla) → **Runtime** (Express/Hono) → **Agent** (LangGraph/CrewAI/BuiltIn/Custom), communicating via the AG-UI protocol (event-based SSE). -- Add dedicated documentation for the hook under `/docs`. -- Update the relevant docs metadata file(s) so the page appears in docs navigation. -- Add JSDoc on top of the hook implementation, including usage examples. -- Write extensive tests for the hook (covering behavior, edge cases, and lifecycle where applicable). +## Essentials + +- **Nx monorepo** — always run tasks through `nx` (`nx run`, `nx run-many`, `nx affected`), never the underlying tooling directly. +- **V1 wraps V2** — V2 (`@copilotkitnext/`) is the real implementation. V1 (`@copilotkit/`) is the public compatibility layer that delegates to V2. Build new features in V2 first. Add V1 wrappers only if backward compatibility is needed. +- **Simplicity** — prefer the simplest correct solution. For non-trivial changes, consider if there's a cleaner approach before committing. +- **Worktrees** — always work in a git worktree for isolation. See [Git & PRs](.claude/docs/git.md) for the full workflow. + +## Reference (read when relevant to your task) + +- [Architecture & Packages](.claude/docs/architecture.md) — V2/V1 package roles, request lifecycle, core concepts (AG-UI, ProxiedAgent, AgentRunner, tools, context, multi-agent) +- [Hook Development](.claude/docs/hooks.md) — checklist for creating new hooks (docs, tests, JSDoc) +- [Workflow & Process](.claude/docs/workflow.md) — when to plan, when to fix autonomously, verification, self-improvement loop, this should be your default mindset when working on any task +- [Git & PRs](.claude/docs/git.md) — worktree workflow, branching, creating PRs