Initial shared Copilot resources scaffold

docs/architecture.md

@@ -0,0 +1,40 @@
+# 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
+- `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.
+
+## 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.

docs/authoring.md

@@ -0,0 +1,29 @@
+# Authoring Guide
+
+## Choose The Right Primitive
+
+- Use a skill for reusable multi-step workflows, especially if the workflow
+  should work in Copilot CLI as well as VS Code.
+- Use a prompt for a lightweight VS Code slash command.
+- Use an instruction file for conventions or rules that should influence model
+  behavior.
+- Use an agent for a reusable persona with tool restrictions or handoffs.
+- Use a hook only when the behavior must be deterministic and enforced in code.
+
+## Supported Creation Paths
+
+### Repo-first
+
+Open this repository in VS Code and create the resource directly in the matching
+ folder.
+
+### Local-first
+
+Create the resource from a normal VS Code workspace or user-profile flow, then
+publish it into this repository with `install/publish.sh` or
+`install/publish.ps1`.
+
+## Rule Of Record
+
+If a resource is meant to be shared, the version in this repository is the only
+version that counts.

docs/deprecation.md

@@ -0,0 +1,9 @@
+# Deprecation Policy
+
+## Rules
+
+- Do not remove a shared resource without documenting the replacement or the
+  reason for removal.
+- Prefer marking a resource deprecated in its description or body before
+  deleting it.
+- Keep migration guidance in the same change that introduces the replacement.

docs/governance.md

@@ -0,0 +1,18 @@
+# Governance
+
+## Scope
+
+This repository stores shared Copilot resources, the tooling needed to install
+them, and the documentation required to maintain them.
+
+## Decision Rules
+
+- Prefer portable workflows over tool-specific duplication.
+- Prefer additive changes over breaking changes.
+- Prefer repo-first authoring when the work is intentionally shared.
+- Require publish-to-repo before considering a local resource shared.
+
+## Stewardship
+
+Project stewards review structural changes, naming conventions, lifecycle rules,
+and anything that changes propagation behavior.

docs/naming.md

@@ -0,0 +1,20 @@
+# Naming Standards
+
+## General
+
+- Use lowercase kebab-case for directory names and skill names.
+- Keep filenames descriptive and stable.
+- Match skill directory names to the `name` field in `SKILL.md`.
+
+## File Conventions
+
+- Prompts end in `.prompt.md`
+- Instructions end in `.instructions.md`
+- Agents end in `.agent.md`
+- Hooks end in `.json`
+
+## Frontmatter
+
+- Always include a meaningful `description` for skills, prompts, and agents.
+- Keep descriptions discovery-oriented: include what the resource does and when
+  to use it.

docs/operations.md

@@ -0,0 +1,23 @@
+# Operations
+
+## Update
+
+```bash
+install/update.sh
+```
+
+```powershell
+install/update.ps1
+```
+
+## Verify
+
+```bash
+install/verify.sh
+```
+
+```powershell
+install/verify.ps1
+```
+
+Scheduled sync will be added on top of the same update and verify entrypoints.

docs/ownership.md

@@ -0,0 +1,14 @@
+# Ownership
+
+## Resource Ownership
+
+- Skills and scripts should have a clear maintainer because they affect multiple
+  surfaces.
+- Hooks require extra scrutiny because they execute code.
+- Repository overlay templates should be maintained with GitHub-side behavior in
+  mind.
+
+## Change Responsibility
+
+Whoever introduces a shared resource is responsible for documenting it,
+verifying it, and proposing deprecation guidance if it later becomes obsolete.

docs/publishing.md

@@ -0,0 +1,37 @@
+# Publishing Guide
+
+## Why Publishing Exists
+
+VS Code creation flows can write to a workspace or user profile, but those
+locations are not the authoritative shared source. Publishing moves the resource
+into this repository so other sessions and machines can consume the same asset.
+
+## Examples
+
+```bash
+install/publish.sh --source /path/to/example.prompt.md
+```
+
+```powershell
+install/publish.ps1 -Source C:\path\to\example.agent.md
+```
+
+## What Publish Normalizes
+
+- target filenames and skill directory names are normalized into lowercase
+	kebab-case
+- expected suffixes are enforced for prompts, instructions, agents, and hooks
+- skill `name` metadata is aligned to the published directory name
+
+## What Publish Rejects
+
+- exact content duplicates that already exist elsewhere in the shared repo
+- effective display-name duplicates, even if the filenames differ
+- conflicting targets unless you explicitly replace them with `--force` or
+	`-Force`
+
+## After Publishing
+
+1. Review the normalized target in this repository.
+2. Commit and push.
+3. Update other systems.

docs/release-process.md

@@ -0,0 +1,10 @@
+# Release Process
+
+## Flow
+
+1. Add or publish the resource into this repository.
+2. Review the change against naming, review, and portability rules.
+3. Commit and push.
+4. Run `install/update.sh` or `install/update.ps1` on consuming systems, or let
+   scheduled sync pick up the change.
+5. Verify the resource appears in the expected VS Code and CLI surfaces.

docs/review-standards.md

@@ -0,0 +1,10 @@
+# Review Standards
+
+A new shared resource should be reviewed for:
+
+- Correct location and naming
+- Valid frontmatter and discovery text
+- Portability expectations
+- Security implications, especially for hooks and scripts
+- Clear purpose and expected usage
+- Duplication with existing resources

docs/setup.md

@@ -0,0 +1,31 @@
+# Setup
+
+## macOS Or Linux
+
+```bash
+install/bootstrap.sh
+```
+
+## Windows
+
+```powershell
+install/bootstrap.ps1
+```
+
+## What Bootstrap Does
+
+- Creates a canonical path at `~/.copilot-resources`
+- Links default discovery locations back to this repository
+- Merges only the managed Copilot-related VS Code settings into the user settings file
+- Writes a managed Copilot CLI environment fragment and sources it from the shell or PowerShell profile
+- Writes a local install-state file outside the repository
+
+## Optional Settings
+
+Bootstrap renders and merges the managed keys from
+`config/vscode/settings.template.jsonc` into the user settings file. Existing
+unmanaged VS Code settings are preserved.
+
+Bootstrap also writes a managed Copilot CLI environment file into the local
+state directory and adds a small managed source block to the active shell or
+PowerShell profile instead of replacing the whole profile.

docs/troubleshooting.md

@@ -0,0 +1,21 @@
+# Troubleshooting
+
+## Resource Does Not Appear
+
+- Run the verify script.
+- Confirm the resource exists in the repository.
+- Confirm the default discovery link exists.
+- Use VS Code Chat Diagnostics to confirm the resource is being loaded.
+
+## Changed Resource Does Not Reload
+
+Treat hot reload as likely but not guaranteed. If needed:
+
+- start a new chat session
+- restart the Copilot CLI session
+- reopen VS Code
+
+## Publish Refused To Overwrite
+
+The publish scripts stop on collisions by default. Use a new name or rerun with
+`--force` only after confirming the replacement is intentional.

docs/versioning.md

@@ -0,0 +1,10 @@
+# Versioning
+
+This repository versions the shared resource set as a whole through Git.
+
+## Compatibility
+
+- Additive resources are preferred and should not require coordinated rollout.
+- Renames and removals should be treated as breaking changes.
+- If a resource changes behavior in a non-obvious way, document it in the
+  change description and deprecation notes.