bw-copilot-resources/docs/architecture.md

Architecture

Overview

This repository is the canonical source of truth for shared Copilot resources. It separates reusable workflows from tool-specific adapters and keeps propagation Git-based after a resource is published.

Layers

• resources/skills/: portable workflows for VS Code, Copilot CLI, and cloud agents
• resources/prompts/: VS Code slash-command adapters
• resources/instructions/: shared instruction packs
• resources/agents/: shared custom agents for local chat and overlays
• resources/hooks/: shared hook definitions
• config/mcp/: tracked MCP templates and example machine-local overrides
• install/merge-managed-mcp-config.mjs: managed MCP merge and prune logic for user config files
• install/mcp/: wrapper scripts for MCP servers that need runtime adaptation
• templates/repo-overlay/: files that can be copied into another repository for repository-scoped behavior

Discovery Model

Bootstrap prefers linking default discovery paths back to this repository:

• ~/.copilot/skills -> resources/skills
• ~/.copilot/agents -> resources/agents
• ~/.copilot/instructions -> resources/instructions
• ~/.copilot/hooks -> resources/hooks
• VS Code user prompts directory -> resources/prompts

This keeps the repository authoritative while still using default discovery locations whenever possible.

For MCP, bootstrap uses generated user-level config instead of links:

• VS Code user mcp.json
• Copilot CLI user ~/.copilot/mcp-config.json

Those generated files come from tracked templates plus machine-local data in .local/mcp.local.jsonc.

Propagation Model

There are only two supported creation paths:

• repo-first
• local-first followed by publish-to-repo

Once a resource lands in the repository, commit and push it. Other systems pick it up through install/update.* or future scheduled sync.

Managed MCP propagation follows the same rule, but with a split between shared and local inputs:

• Shared defaults and server definitions are tracked in the repo
• Machine-local secrets and enablement stay in .local/
• install/update.* pulls the repo and reruns bootstrap so the generated MCP files refresh from the latest templates on every machine