mirror of
https://github.com/CopilotKit/CopilotKit.git
synced 2026-09-14 16:26:20 +08:00
Jordan Ritter
34f615a0fb
Restore the 12 Python integration tools/ dirs to symlinks into
shared/python/tools. They had eroded to real, drifting copies via an
accidental stage_shared() leak (commit 534cd1efa7) — the structural root
cause of showcase divergence bugs. Symlinking re-establishes the single
source of truth; content is identical to shared (only render_a2ui naming
and the shared roll_dice/sanitize additions are adopted).
Add showcase/AGENTS.md documenting the 4 iron rules and the single-source
symlink mechanism, plus a validate-shared-symlinks CI guard (shrink-only
baseline) that fails on any NEW erosion.
3.2 KiB
3.2 KiB
General Guidelines for working with Nx
- When running tasks (for example build, lint, test, e2e, etc.), always prefer running the task through
nx(i.e.nx run,nx run-many,nx affected) instead of using the underlying tooling directly - You have access to the Nx MCP server and its tools, use them to help the user
- When answering questions about the repository, use the
nx_workspacetool first to gain an understanding of the workspace architecture where applicable. - When working in individual projects, use the
nx_project_detailsmcp tool to analyze and understand the specific project structure and dependencies - For questions around nx configuration, best practices or if you're unsure, use the
nx_docstool to get relevant, up-to-date docs. Always use this instead of assuming things about nx configuration - If the user needs help with an Nx configuration or project graph error, use the
nx_workspacetool to get any errors - For Nx plugin best practices, check
node_modules/@nx/<plugin>/PLUGIN.md. Not all plugins have this file - proceed without it if unavailable.
Working under
showcase/? Readshowcase/AGENTS.mdFIRST — it defines the non-negotiable iron rules for showcase cells.
CopilotKit
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).
Essentials
- Nx monorepo — always run tasks through
nx(nx run,nx run-many,nx affected), never the underlying tooling directly. - Flat package structure — all packages live directly under
packages/(nov1/orv2/subdirectories). Every package uses the@copilotkit/scope. - 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 for the full workflow.
- Documentation lives in shell-docs — author all CopilotKit docs in
showcase/shell-docs/src/content/. The top-leveldocs/path is only a symlink toshowcase/shell-docs/; never recreate the olddocs/content/docs/tree. AG-UI protocol docs are authored upstream inag-ui-protocol/ag-ui, not here. See Documentation.
Reference (read when relevant to your task)
- Architecture & Packages — package roles, request lifecycle, core concepts (AG-UI, ProxiedAgent, AgentRunner, tools, context, multi-agent)
- Hook Development — checklist for creating new hooks (docs, tests, JSDoc)
- Workflow & Process — when to plan, when to fix autonomously, verification, self-improvement loop, this should be your default mindset when working on any task
- Git & PRs — worktree workflow, branching, creating PRs
- Documentation — where to author docs (CopilotKit → shell-docs; AG-UI → upstream);
docs/is retired