BaseCoat
Enterprise-grade shared repository for GitHub Copilot customizations.
BaseCoat provides a curated library of agents, skills, instructions, and prompts that teams adopt across repositories through a single sync command. Instead of every team writing Copilot customizations from scratch, BaseCoat gives you production-ready assets that enforce consistent standards, accelerate development workflows, and scale across an entire GitHub Enterprise organization.
The operating model combines Guardrails (BaseCoat assets and standards) with Visibility (issues, PRs, workflows, and milestones) so execution is both governed and observable.
131 agents · 139 skills · 91 instruction files · 11 prompt starters
Quick Start
Choose your intent
Each onboarding entry point serves one intent. Installing assets and preparing
repository readiness are separate steps; run only the ones you need.
| Intent | Entry point | Side effects | Next step |
|---|
| Install or update BaseCoat assets | sync.ps1 / sync.sh | Writes .github/base-coat/, the Copilot-discoverable asset folders, and .github/base-coat/guidance-lock.json; seeds the PR template, issue template, and .github/release-notes/templates/default.md only if missing. Stages workflow definitions under .github/base-coat/workflows/ without activating them (nothing is written to .github/workflows/). Does not change repository settings. | Review and commit the changes in a pull request. |
| Guided asset install or refresh | scripts/bootstrap-basecoat.ps1 | Runs sync.ps1 (same file scope, including staged but inactive workflow definitions), validates the result and, when files changed and gh is available, offers to commit them on a new branch and open a pull request (-SkipPR opts out). Does not change repository settings. | Review the generated pull request, or open one yourself with -SkipPR. |
| Repository readiness and governance profile | scripts/bootstrap.ps1 | Checks tooling, GitHub Actions status, and the profile-driven secret and variable matrix; may install the gh aw extension, update .gitignore, initialize the local memory store, and prompt for missing secrets or variables; writes .memory/bootstrap-audit.json. In interactive runs of portal-enabled, non-solo profiles with missing Azure variables, it also runs portal OIDC bootstrap without a separate prompt: creates or reuses an Entra application and federated credential, assigns Contributor and User Access Administrator at subscription scope, and sets the Azure repository variables. When portal-deploy.yml exists and required secrets are ready, it offers to dispatch that workflow (after confirmation), which can start a cloud deployment. Does not install assets. | Resolve the remediation items in the audit log. |
| Memory contribution enlistment | scripts/onboard-basecoat.sh --repo ORG/REPO | Adds the basecoat-enabled repository topic and creates the learning labels. Does not install assets. | The repository joins the weekly memory sweep. |
| New repository scaffolding | project-onboarding agent | Creates or clones the repository, scaffolds root files, runs sync, configures hook packs and issue templates, and logs the first sprint issue. For a brand-new repository it commits and pushes the scaffolded files; reruns on existing repositories use a review branch. | Continue with readiness using scripts/bootstrap.ps1. |
Installing assets does not activate workflows or change repository settings.
Staged workflow definitions run only after you explicitly install them into
.github/workflows/ with configure-downstream-workflows.ps1. sync.ps1
installs that script under .github/base-coat/scripts/; sync.sh does not,
so stay in the consumer repository and invoke the script by path from a
separate BaseCoat source checkout (for example,
pwsh ../basecoat/scripts/configure-downstream-workflows.ps1). The installer
targets the git repository of the current working directory.
See Downstream workflows setup.
Readiness and onboarding entry points do change repository or cloud
configuration; review the side effects in the table before running them. For
example, scripts/onboard-basecoat.sh updates the repository topic and labels
without prompting, and scripts/bootstrap.ps1 can provision portal OIDC
resources as described above.
Install assets with the sync script
macOS / Linux:
BASECOAT_REPO=https://github.com/YOUR-ORG/basecoat.git ./sync.sh
Windows PowerShell:
$env:BASECOAT_REPO = 'https://github.com/YOUR-ORG/basecoat.git'; .\sync.ps1
Pin to a release tag (recommended for production):
$env:BASECOAT_REPO = 'https://github.com/YOUR-ORG/basecoat.git'
$env:BASECOAT_REF = 'v1.0.0'
irm https://raw.githubusercontent.com/YOUR-ORG/basecoat/$env:BASECOAT_REF/sync.ps1 | iex
The sync script clones BaseCoat, copies the standard assets into .github/base-coat/, then copies agents, instructions, and prompts to .github/agents/, .github/instructions/, and .github/prompts/ so that GitHub Copilot auto-discovers them. The whole process takes under a minute.
Environment Variables
| Variable | Default | Description |
|---|
BASECOAT_REPO | https://github.com/YOUR-ORG/basecoat.git | Source repository URL |
BASECOAT_REF | main | Branch or tag to sync from |
BASECOAT_TARGET_DIR | .github/base-coat | Target directory inside your repo (relative to repo root) |
What Gets Synced
The sync script copies these items into BASECOAT_TARGET_DIR:
README.md · CHANGELOG.md · inventory.md · version.json · instructions/ · skills/ · prompts/ · agents/ · templates/ · schemas/
On first adoption, BaseCoat also seeds intake defaults if they are missing:
.github/PULL_REQUEST_TEMPLATE.md.github/ISSUE_TEMPLATE/issue.md
Everything else (tests, non-runtime scripts, CI workflows, examples) stays in
the source repo and is not copied into consumers. Selected runtime helpers
and validators are installed under .github/base-coat/scripts/.
Shared destination ownership
BaseCoat, Sheen, and Adhesion coordinate physical files in .github/skills,
.github/agents, .github/agent-references, .github/instructions,
.github/prompts, and .agents/skills through the versioned lock at
.github/base-coat/guidance-lock.json. Sync blocks foreign ownership
collisions and consumer-modified managed files before overwrite. The installed
reference implementation is .github/base-coat/scripts/guidance-lock.ps1;
see Shared guidance ownership lock
for the schema, migration behavior, and sibling-product integration contract.
Manual copy is unsupported
Copying files by hand, from a release archive or a submodule, is not a
supported install method. It bypasses the guidance-lock/v1 ownership lock,
asset provenance, and stale-file cleanup, which leads to stale assets, missing
files, and incorrect target paths. Always use sync.ps1 or sync.sh (or
scripts/bootstrap-basecoat.ps1, which runs sync for you). The scripts handle
cloning, copying, locking, and cleanup in a single idempotent operation.
🏷️ Issue Labels
BaseCoat uses a consistent label taxonomy for issue triage, discovery, and sprint management.
Label Categories
| Category | Labels | Purpose |
|---|
| Asset Type | agent, skill, instruction, prompt | Identifies the type of customization asset for filtering and discovery |
| Issue Type | bug, enhancement, documentation, question, chore, security | Classifies the issue by its primary type |
| Priority | priority:high, priority:medium, priority:low | Indicates urgency and SLA (high = 1hr, medium = 4hr, low = 1 week) |
| Sprint | sprint-1, sprint-2, sprint-3, sprint-4 | Assigns issue to a sprint milestone |
| Status | blocked, spec-required, governance | Indicates blocking conditions or special handling |
| Technology | azure, dotnet, kubernetes, python, terraform, etc. | Domain or technology focus |
| Approval | approved, copilot-agent | Applied when issue is approved for agent implementation |
Quick Discovery
- Find all agents:
is:issue label:agent
- Find Sprint 3 skills:
is:issue label:sprint-3 label:skill
- Find high-priority bugs:
is:issue label:priority:high label:bug
- Find blocked issues:
is:issue label:blocked
For complete label reference: docs/reference/LABEL_taxonomy.md · governance.md
Architecture Overview
BaseCoat is built on four GitHub Copilot customization primitives:
┌─────────────────────────────────────────────────────┐
│ BaseCoat │
├──────────┬──────────┬───────────────┬───────────────┤
│ Agents │ Skills │ Instructions │ Prompts │
│ (73) │ (55) │ (56) │ (8) │
│ │ │ │ │
│ Multi- │ Reusable │ Coding │ Quick task │
│ step │ workflow │ standards & │ entry points │
│ flows │ recipes │ guardrails │ │
└──────────┴──────────┴───────────────┴───────────────┘
▲ ▲
│ Agents reference │ Instructions are
│ skills for │ auto-loaded by
│ templates │ Copilot in every
└────────────────────┘ conversation
-
Agents (agents/) — Multi-step workflow definitions for complex tasks like backend development, code review, sprint planning, and security analysis. Each agent has a defined role, instructions, and often references paired skills.
-
Skills (skills/) — Reusable workflow recipes with templates. A skill contains a SKILL.md workflow definition plus template files (checklists, specs, scaffolds) that agents and users invoke during work.
-
Instructions (instructions/) — Coding standards and guardrails that Copilot loads automatically. These govern how code is written, reviewed, tested, and deployed across every conversation.
-
Prompts (prompts/) — Quick-start entry points for common tasks like architecture planning, code review, and bugfixing.
-
Operating model reference: docs/reference/ai-sdlc-operating-model.md
Agent Catalog
| Agent | Description |
|---|
| agent-designer | Designs and authors Copilot agent definitions |
| agentops | Agent lifecycle, versioning, rollout, health monitoring, and rollback |
| api-designer | API design for OpenAPI, REST, GraphQL, and governance |
| app-inventory | Legacy app scanning for dependencies, tech stacks, and migration complexity |
| azure-landing-zone | Azure Landing Zone scaffolding following Cloud Adoption Framework |
| backend-dev | APIs, service layers, business logic, and data access |
| chaos-engineer | Fault injection, game days, resilience scoring, and recovery validation |
| code-review | Structured multi-step code review workflow |
| config-auditor | Scans for committed or unprotected config secrets |
| containerization-planner |
Full machine-readable catalog with skill pairings and model recommendations: docs/reference/asset-catalog.md
Copy-ready examples for every intent, skill, and agent: docs/reference/prompt-library.md
Skill Catalog
| Skill | Templates | Paired Agent(s) |
|---|
| agent-design | agent-template, instruction-template, skill-template | agent-designer |
| api-design | openapi-template, governance-checklist, breaking-change-checklist, versioning-decision-tree | api-designer |
| app-inventory | inventory-report-template, complexity-scoring-template | app-inventory |
| architecture | adr-template, c4-diagram-template, risk-register-template, tech-selection-matrix-template | solution-architect |
| azure-container-apps | SKILL.md workflow | devops-engineer |
| azure-identity | rbac-role-assignment-template, managed-identity-mapping-template, app-registration-checklist, workload-identity-federation-template, conditional-access-policy-template | identity-architect |
| azure-landing-zone | adr-template, hub-networking-template, landing-zone-vending-template, platform-subscription-template, policy-assignment-template, policy-exemption-template | azure-landing-zone |
| azure-networking | hub-spoke-topology, cidr-allocation, private-endpoint-dns-zones, nsg-rule-matrix | solution-architect, devops-engineer |
| azure-policy |
Instruction Files
Instructions are automatically loaded by GitHub Copilot to enforce standards across every conversation.
| Instruction | Scope |
|---|
| agent-behavior | Retry loops, edit thrashing, and escalation guardrails |
| agents | Agent authoring standards |
| architecture | Architecture, API, and design-diagram guidance |
| azure | Azure service, SDK, and deployment guidance |
| backend | Backend APIs, services, workers, and data access |
| bicep | Azure Bicep authoring and validation |
| config | Config file safety and secrets prevention |
| development | Shared dev standards for all dev-core agents |
| documentation | Documentation and change-note expectations |
| drift-monitor |
Guardrails
Guardrail policies in docs/reference/guardrails/ enforce non-negotiable standards:
Additional security docs: docs/operations/security/BRANCH_PROTECTION.md · docs/operations/security/SECRET_SCANNING.md
Governance
BaseCoat operates under a lightweight enterprise governance framework:
- Issue-first: All changes must be backed by a logged GitHub issue.
- PRs only: Never commit directly to
main. Open a pull request; self-approval is permitted.
- No secrets: Never commit credentials, tokens, API keys, or sensitive data.
- Branch naming:
feature/<issue-number>-<short-description> or fix/<issue-number>-<short-description>
Full reference: docs/reference/governance.md · Contributing: CONTRIBUTING.md
Platform interfaces
BaseCoat is the controls source for the AI-SDLC governance family. Contracts are
defined in the family's internal API specification (internal contract source)
and MCP specification (internal contract source) repositories;
shared IDs and schemas come from Binder. BaseCoat stays Git-native: releases,
sync.ps1/sync.sh, and the files in this repository remain the source of truth,
and the API is a read adapter over them rather than a separate service of record.
| Interface | Direction |
|---|
| Authorization | Controls are readable by any family product and consumer; publishing or changing controls follows the PR-only governance above. Access to customer repos stays with the caller's identity. |
| API | Controls and policy catalog: versioned agents, skills, instructions, guardrails, and release metadata, served through an adapter over Git releases. |
| MCP | Read-only: list_controls, get_control, explain_control. Control changes are proposed as PRs, not executed through MCP. |
| Integrated graph | Contributes control and release-version nodes; Batchbook records which repos have adopted which versions. |
These are initial directions, not approved contracts.
Repository Layout
basecoat/
├── agents/ # 30 agent definitions
├── skills/ # 19 skill directories with templates
├── instructions/ # 19 instruction files (auto-loaded)
├── prompts/ # 3 prompt starters
├── docs/ # Governance, guardrails, security, guides
│ ├── guardrails/ # 6 guardrail policies
│ └── security/ # Branch protection, secret scanning
├── examples/ # IaC samples, workflows, repo templates
├── scripts/ # Packaging, validation, hook installers
├── tests/ # Smoke tests
├── .github/workflows/ # CI/CD pipelines
├── sync.ps1 # Windows sync script
├── sync.sh # macOS/Linux sync script
├── docs/reference/asset-catalog.md # Machine-readable asset registry
├── CHANGELOG.md # Release history
├── CONTRIBUTING.md # Contribution guidelines
├── inventory.md # Asset inventory
└── version.json # Current version metadata
Adoption Options
Option 1 — Sync Script (Recommended)
# macOS / Linux
curl -fsSL https://raw.githubusercontent.com/YOUR-ORG/basecoat/main/sync.sh | bash
# Windows PowerShell
irm https://raw.githubusercontent.com/YOUR-ORG/basecoat/main/sync.ps1 | iex
Option 2 — Pinned Release (Enterprise)
tag=v1.0.0
curl -fsSL https://raw.githubusercontent.com/YOUR-ORG/basecoat/${tag}/sync.sh | bash
Unsupported — Git Submodule or Manual Copy
Adding BaseCoat as a git submodule and copying its folders into the
Copilot-discoverable paths by hand is not supported. Manual copies bypass the
guidance-lock/v1 ownership lock, provenance, and cleanup. Use Option 1 or
Option 2 instead.
Copilot CLI Plugin
The basecoat CLI plugin routes natural-language commands to the best-matching Basecoat agent.
npx basecoat "review this code for security vulnerabilities"
See plugins/copilot-cli-plugin/ for installation and usage.
Enterprise Setup
For GitHub Enterprise onboarding, organization-level configuration, and custom agent development, see the Enterprise Setup Guide.
Test Suite
./tests/run-tests.ps1 # Windows
bash tests/run-tests.sh # macOS / Linux
Contributing
See CONTRIBUTING.md for guidelines on adding agents, skills, instructions, and prompts.
License
This project is for internal use. Contact your organization's open-source program office for licensing terms.
