القائمة
Sync docs and skills so they never drift from the code. Use before opening or updating a PR, or when a change touches a command, path, convention, or the skill set a doc or skill documents.
التثبيت باستخدام Codex أو Claude انسخ هذا Prompt والصقه في Codex أو Claude أو مساعد آخر ليراجع صفحة Skill ويثبّتها لك.
استنادا إلى تصنيف SOC المهني
| name | doc-sync |
| description | Sync docs and skills so they never drift from the code. Use before opening or updating a PR, or when a change touches a command, path, convention, or the skill set a doc or skill documents. |
A change ships with its docs or it ships drift. This is the procedure to catch drift across every hand-authored surface before the PR goes up. AGENTS.md makes the sync mandatory; this makes it checkable.
Hand-authored, keep these in step with the code:
| Surface | Documents | Drifts when |
|---|---|---|
web/next/content/docs/**.mdx | concepts and how-to (getting-started, deployment, manage, resources) | a feature, convention, API, command, script, or env var it describes changes |
web/next/docs.config.ts | the docs nav and page registry, the single source the sidebar, meta.json, and MDX frontmatter all derive from | a doc page is added, removed, renamed, or re-slugged |
README.md | top-level story: stack, structure, quick start, scripts, deployment | the stack, setup, scripts, or pitch changes |
.agents/skills/<name>/SKILL.md | one task procedure each (canonical; .claude and .github symlink in) | a command, path, convention, or tooling a skill encodes changes, or a skill is added or removed |
AGENTS.md (CLAUDE.md symlinks in) | the rules and the skills catalog table | a rule changes, or the skill set changes |
Generated, never hand-edit (they regenerate from the surfaces above): content/docs/meta.json (git-ignored), the /llms.txt and /llms-full.txt routes, and the fumadocs search index.
List what the diff touched: paths, commands, script names, env vars, conventions, tooling, and whether the skill set changed. Start from git diff --stat and the code diff.
Grep every surface for each changed path, command, or symbol. Every hit is a candidate:
rg -n "<changed-path-or-command>" web/next/content/docs README.md AGENTS.md .agents/skills web/next/docs.config.ts
Update each hit in the same change. Two couplings are easy to miss:
AGENTS.md skills table, the resources/ai-skills.mdx catalog row, and that file's "N skills" counts.web/next/docs.config.ts, not the .mdx alone.bun .github/scripts/docs.ts --strict
This is the fast gate (seconds): it exits non-zero on any .mdx missing from docs.config.ts, any config entry with no file, or frontmatter drifted from docs.config.ts. To fix a failure, run it without --strict to rewrite the managed frontmatter and scaffold missing pages, then commit. Before the PR, also run cd web/next && bun run build once: it reruns this check inside the full build and additionally catches type errors and rebuilds the search index. Done when the strict gate passes AND a fresh rg for every removed or renamed path, command, and skill name finds zero stale mentions across the surfaces.
.agents/skills is canonical, edit once./llms.txt and /llms-full.txt routes mirror the docs and regenerate at build, so fix the doc, never the route.Add a new shared workspace package under packages/*. Use when creating a new @packages/<name>, whether a bundled library other workspaces import or a build-only script package that runs during a build.
Orient in this repo: which file to edit for a change, how a change ripples across the stack, and how to search the code. Use at the start of a task in an unfamiliar area, or before a cross-cutting change.
Prefer Bun-native APIs, else Node built-ins with the node: prefix. Use when importing a Node built-in (fs, path, child_process, crypto, os, util), reading or writing files, spawning a process, or choosing between a Bun and a Node API.
Icebox a raised-but-undecided concern instead of forcing a plan-or-dismiss call: record it with no verdict so the context survives. Use when a review, PR, audit, or eval surfaces something real-maybe that should not be scheduled or closed yet, or when the user says to icebox or park an item.
Add a typed Hono API endpoint or WebSocket route: router, OpenAPI docs, validation envelope, and RPC client wiring. Use when adding or modifying routes in api/hono.
Start, restart, and verify the ZeroStarter dev stack. `bun run dev` serves portless named `.localhost` URLs (branch-prefixed in a worktree); resolve them with `bunx portless get`. Use when asked to run the app, when the API returns NOT_FOUND for routes that exist in source, or before browser testing.