context-sync

name	Context Sync
description	Scan the codebase and regenerate contexts/*.yaml to keep AI agent knowledge current. Run when starting a session or after making structural changes.

Context Sync Skill

You (the agent) scan the codebase and regenerate contexts/ directly. Use your own tools (list files, read package.json, write files). No script needed.

When to Sync

Before working:

• Check Last synced date in contexts/project.yaml header
• If stale or data looks wrong, regenerate

After structural changes:

• Added/removed a workspace app or package
• Added/removed a store, view, component, route, dep, test
• Bumped version
• BMAD agents generated new artifacts in _bmad-output/

Not needed: code edits inside existing files.

How to Sync

1. Read pnpm-workspace.yaml to know workspace layout
2. List apps/ and packages/ directories to discover all workspaces
3. For each workspace with a package.json, scan its structure
4. Write compact YAML to contexts/
5. Add header: # Auto-generated by context sync — {YYYY-MM-DD}

Directory Structure

contexts/
├── project.yaml           ← monorepo overview (always loaded)
├── tech.yaml              ← monorepo-level deps only
├── prd.yaml               ← product roadmap (from BMAD or manual)
├── ui/                    ← apps/ui/ workspace
│   ├── architecture.yaml  ← stores, routes, views, components
│   ├── features.yaml      ← feature areas, tests
│   └── tech.yaml          ← workspace deps + devDeps
├── {new-app}/             ← auto-created per workspace
│   ├── architecture.yaml
│   ├── features.yaml
│   └── tech.yaml
└── README.md

Root level = monorepo-wide context (identity, workspaces, rules, root deps, PRD). Workspace dirs = per-app context (architecture, features, deps).

Context Files — Root Level

project.yaml — ALWAYS loaded

Scan:

• Root package.json → monorepo name, version, scripts
• pnpm-workspace.yaml → workspace patterns
• List apps/ and packages/ → discover workspaces
• For each workspace: name, version from its package.json
• Primary app key deps for the stack summary

Write: identity, workspaces list, primary_app, stack, lang, rules, commands. Include all scripts from root package.json (dev, build, test, bmad:install, bmad:update, etc.). Footer: comments listing all available context files.

tech.yaml — monorepo root deps only

Scan:

• Root package.json → devDependencies (turbo, tsx, etc.)
• Node/pnpm version requirements

Write: root deps only. Per-workspace deps go in contexts/{app}/tech.yaml.

prd.yaml — product planning

Source:

• _bmad-output/prd.md → if non-empty, extract as YAML block
• _bmad-output/product-brief.md → if non-empty, extract
• _bmad-output/planning-artifacts/ → check for additional planning docs
• If all empty: preserve existing manual prd.yaml

Context Files — Per Workspace

For each app in apps/, create a contexts/{app-name}/ directory with:

{app}/architecture.yaml

Scan:

• apps/{app}/package.json → type (Electron, web, etc.)
• apps/{app}/src/ → directory structure
• Entry points (main, preload, renderer for Electron; pages, components for web)
• Stores → list all files with sizes
• Routes → extract from router config
• Views → list all files/dirs with sizes
• Components → list all files/dirs with sizes

Write: entry points, stores, routes, views, components, data flow.

{app}/features.yaml

Scan:

• Feature directories within the app (anti-detection, bmad, scrum, etc.)
• Test files in the app's test directory
• BMAD version from _bmad/bmm/config.yaml → bmad_version field
• BMAD agents from _bmad/bmm/agents/ → bmad_agents list
• BMAD outputs: list all files in _bmad-output/ including subdirs (planning-artifacts/, implementation-artifacts/)

Write: file lists per feature area, test files, bmad_version, bmad_agents, bmad_outputs.

{app}/tech.yaml

Scan:

• apps/{app}/package.json → dependencies + devDependencies
• Build/packaging config

Write: all deps with versions, packaging targets.

Adding a New Workspace

When a new app apps/web/ or package packages/shared/ appears:

1. Sync discovers it by listing apps/ and packages/
2. project.yaml lists it under workspaces
3. contexts/web/ directory is created
4. architecture.yaml, features.yaml, tech.yaml generated inside it

No config needed — the structure follows the monorepo.

Token Budget

• project.yaml: ~500 tokens (always loaded)
• {app}/architecture.yaml: ~600 tokens each (load for the app you're working on)
• {app}/features.yaml: ~400 tokens each
• {app}/tech.yaml: ~600 tokens each
• Root tech.yaml: ~200 tokens
• prd.yaml: ~600 tokens

Rules

• Use file: size format (e.g. kanbanStore.js: 41KB)
• YAML lists for enums, maps for key-value
• No prose — agents parse structure, not sentences
• Header comment with sync date
• Never hardcode workspace names — always discover from filesystem
• Root context = monorepo-wide, workspace dirs = app-specific