Skip to content

Commit 3e7449d

Browse files
mmemme
committed
Merge remote-tracking branch 'origin/main' into lukas/cpk-7526-copilotkitruntimev2-configurable-mcp-server-on-builtinagent
2 parents 6ed400c + d446b29 commit 3e7449d

2,587 files changed

Lines changed: 202142 additions & 55543 deletions

File tree

Some content is hidden

Large Commits have some content hidden by default. Use the searchbox below for content that may be hidden.

‎.claude/skills/copilotkit-demo-parity/SKILL.md‎

Lines changed: 147 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,147 @@
1+
---
2+
name: copilotkit-demo-parity
3+
description: Keeps examples/integrations/* demos aligned to the north-star (langgraph-python). Use when the user says "sync demos", "sync integrations", "port to north-star", "align integration demos", "parity check", or when working inside examples/integrations/ and tracked files diverge. Drives the pnpm parity:sync / parity:verify commands and handles the manual-merge zones (agent code, api route, Dockerfile).
4+
---
5+
6+
# CopilotKit demo parity
7+
8+
Keeps the three (soon more) integration demos under `examples/integrations/`
9+
aligned. `langgraph-python` is north-star; every other entry is an instance
10+
that tracks it via `examples/integrations/_parity/manifest.json`.
11+
12+
## When this skill fires
13+
14+
- User says "sync demos", "align integrations", "port to north-star",
15+
"parity check", "run parity sync".
16+
- User edits a file under `examples/integrations/langgraph-python/**` that is
17+
listed in `manifest.json` → tracked.verbatimFiles.
18+
- User is about to add a new integration under `examples/integrations/`.
19+
- `pnpm parity:verify` is failing locally or in CI.
20+
21+
## Ground truth
22+
23+
Read these first before making any parity decision — they override
24+
anything memorized:
25+
26+
- `examples/integrations/_parity/manifest.json` — what is tracked, what is
27+
allowed to diverge, per-instance overrides.
28+
- `examples/integrations/_parity/canonical/PROMPT.md` — the canonical
29+
system prompt. Every agent inlines this as a string literal in source.
30+
The verifier greps the canonical first line against each agent's source.
31+
- `examples/integrations/_parity/README.md` — human-facing how-to.
32+
33+
## Procedure: sync from north-star to instance(s)
34+
35+
Use when north-star changed and instances need to catch up, OR when a new
36+
instance is being bootstrapped.
37+
38+
1. **Confirm the north-star change is intentional.** If the user changed
39+
a file under `langgraph-python/`, ask whether it should propagate.
40+
Changes to `agent/` are never auto-propagated.
41+
2. **Dry-run first.**
42+
```bash
43+
pnpm parity:sync --target=<instance> --dry-run
44+
```
45+
Read the report: file count, rewritten package.json keys, prompt update.
46+
3. **Apply.**
47+
```bash
48+
pnpm parity:sync --target=<instance>
49+
# or --all to sync every instance
50+
```
51+
4. **Resolve manual-merge zones.** Sync does NOT touch:
52+
- `agent/**` — port agent code by hand. See `tracked.agentSurface.toolNames`
53+
and `stateKeys` in `manifest.json` for what must be present.
54+
- `src/app/api/copilotkit/**` — api route differs across instances
55+
(north-star=LangGraphAgent, Docker instances=HttpAgent).
56+
- `Dockerfile`, `docker/Dockerfile.agent`, `serve.py`, `scripts/**` —
57+
language-specific. Each instance keeps its own.
58+
5. **Verify.**
59+
```bash
60+
pnpm parity:verify --target=<instance>
61+
```
62+
Exit 0 = green. Exit 1 = unresolved drift; fix until green.
63+
64+
## Procedure: verify (CI-equivalent)
65+
66+
```bash
67+
pnpm parity:verify # all instances
68+
pnpm parity:verify --target=<instance>
69+
pnpm parity:verify --json # machine-readable
70+
```
71+
72+
Output kinds:
73+
74+
- `verbatim-file` — byte-compare against north-star.
75+
- `package-json` — tracked key mismatch vs expected value.
76+
- `prompt` — canonical prompt first line not found in instance agent
77+
source. Instance agent needs the prompt inlined as a string literal.
78+
- `agent-tool` — tool name from manifest not found in instance agent
79+
source. Usually means a tool was renamed or dropped; update manifest
80+
OR port the tool.
81+
- `agent-state` — state key from manifest not found (warn only).
82+
83+
## Procedure: add a new instance
84+
85+
1. Create the demo dir under `examples/integrations/<name>/` with the
86+
usual Next.js frontend root and an `agent/` subdir.
87+
2. Add an entry to `manifest.json` → `instances`:
88+
```json
89+
"<name>": {
90+
"role": "instance",
91+
"agent": { "language": "...", "runtime": "..." },
92+
"allowedDivergence": [
93+
"agent/**",
94+
"src/app/api/copilotkit/**",
95+
"Dockerfile",
96+
"docker/Dockerfile.agent",
97+
"serve.py",
98+
"scripts/**"
99+
],
100+
"packageJsonOverrides": {
101+
"scripts.dev:agent": "<invocation>",
102+
"scripts.install:agent": "<install>"
103+
}
104+
}
105+
```
106+
3. `pnpm parity:sync --target=<name>`
107+
4. Port agent code (tool implementations, state schema, prompt loading).
108+
Agent must read prompt from `agent/PROMPT.md` at startup.
109+
5. `pnpm parity:verify --target=<name>` until green.
110+
111+
## Procedure: change the canonical prompt
112+
113+
1. Edit `examples/integrations/_parity/canonical/PROMPT.md`.
114+
2. `pnpm parity:sync --all` — writes the new prompt to every instance's
115+
`agent/PROMPT.md`.
116+
3. If the prompt change requires new tools or state keys, update
117+
`manifest.json` → `tracked.agentSurface` to match, then port each
118+
instance's agent.
119+
120+
## Procedure: change the tracked surface
121+
122+
To track a new file or key:
123+
124+
1. Edit `manifest.json` → `tracked.verbatimFiles` or `tracked.packageJsonPaths`.
125+
2. Run `pnpm parity:verify` — instances will flag as drifted until synced.
126+
3. `pnpm parity:sync --all` to apply.
127+
128+
To stop tracking something, remove it from `manifest.json`. The verifier
129+
and sync stop touching it. Any drift that already exists stays.
130+
131+
## Red flags
132+
133+
| Signal | What it means | Do instead |
134+
| ----------------------------------------------- | --------------------- | ----------------------------------------------- |
135+
| "Just copy the file manually" | Bypasses the manifest | Add to `tracked.verbatimFiles` then sync |
136+
| "Add a try/catch so verify doesn't fail" | Silencing drift | Resolve the drift or declare divergence |
137+
| "Move this into `allowedDivergence` to unblock" | Scope creep | Only add to divergence with explicit reason |
138+
| `pnpm parity:sync` on north-star directly | Overwrites canonical | Sync is instance-only; script refuses |
139+
| Agent code copied between languages | Doesn't work | Port by hand; `tracked.agentSurface` names what |
140+
141+
## Related skills
142+
143+
- `copilotkit-integrations` — framework-specific wiring (LangGraph, CrewAI,
144+
Mastra, etc.) when bootstrapping a new instance.
145+
- `copilotkit-dev-workflow` — monorepo conventions, Nx, commit format.
146+
- `docker-ci-safety` — Dockerfile safety when editing per-instance
147+
container builds.

0 commit comments

Comments
 (0)