refresh-agent-context

# Refresh Agent Context Use this skill to keep the repo understandable for coding agents as the Turborepo evolves. ## Goal Detect drift between the actual workspace structure and the agent-facing docs, then update the smallest set of docs that restore a fast path into the correct app or package. Prefer updating these files, in this order: 1. root `AGENTS.md` 2. root `README.md` 3. root or app-level `CLAUDE.md` 4. app-level `apps/*/AGENTS.md` 5. package docs only when they materially help route ownership or shared-code discovery ## Quick Start From the repo root, run: ```bash node skills/refresh-agent-context/scripts/workspace_inventory.mjs ``` This prints a current inventory of: - app and package workspaces - package names - dev ports inferred from `package.json` - asset prefixes and `NEXT_PUBLIC_APP_NAME` inferred from `next.config.ts` - whether `AGENTS.md`, `README.md`, and `CLAUDE.md` exist per app ## Workflow ### 1. Build the current repo inventory Run the inventory script first. Treat its output as the baseline snapshot of the current monorepo shape. ### 2. Audit doc coverage Check for: - missing root `AGENTS.md` - apps missing `AGENTS.md` - stale or missing `CLAUDE.md` files when Claude-specific onboarding exists - empty or stub-only `AGENTS.md` - stale README or `CLAUDE.md` entries for app names, ports, package names, or CMS/framework ownership - missing references to important shared packages such as `packages/i18n`, `packages/ui-chrome`, or `packages/ecosystem-data` - route ownership that is not obvious from the current docs ### 3. Patch the minimal doc set Prefer concise guides that answer these questions quickly: - which workspace owns the requested feature - which commands validate only that workspace - which config files define routing, asset prefixes, or cross-app navigation - which shared packages are likely involved - which `CLAUDE.md` files need the same operational updates as agent docs Do not turn the docs into a full architecture book. Keep them as jump-start guides. ### 4. Verify against source files Before finalizing: - verify package names from `package.json` - verify ports from workspace scripts - verify asset prefixes, rewrites, and `NEXT_PUBLIC_APP_NAME` from `next.config.ts` - verify content ownership from the actual `content/`, `src/`, or package layout ### 5. Report the audit Summarize: - what was stale or missing - what docs were updated - what could not be verified automatically ## Output Standards - keep docs short and operational - prefer tables for workspace maps and bullets for gotchas - keep `AGENTS.md`, `CLAUDE.md`, and root onboarding docs aligned when they describe the same workspace facts - do not duplicate long app docs when a short pointer is enough - if no changes are needed, say so and include the audit findings ## Example Requests - "Refresh the repo's agent docs after adding a new app" - "Audit the Turborepo and update AGENTS.md files" - "Rebuild agent context after changing ports and route ownership" - "Run the periodic agent-reference refresh"