Make It Your Own¶

BaseCoat is designed to be adopted as-is, then shaped to fit your team. This guide explains the three levels of customization — from zero-config adoption to a fully maintained private fork — and when each makes sense.

The customization spectrum¶

[Sync & go] ──────── [Configure] ──────── [Fork & extend] ──────── [Full fork]
     │                     │                      │                      │
  5 minutes             30 minutes             1–2 hours             Ongoing
  Zero config          .basecoat.yml          Private agents         Full control
  Best for:            Best for:              Best for:              Best for:
  Trying it out        Teams with             Enterprises with       Platform teams
                       preferences            proprietary patterns   maintaining
                                                                     a shared fork

Level 1 — Sync and go¶

The fastest path. Run the sync script and start using BaseCoat immediately. No configuration file required.

# macOS / Linux
export BASECOAT_REPO='https://github.com/IBuySpy-Shared/basecoat.git'
curl -fsSL https://raw.githubusercontent.com/IBuySpy-Shared/basecoat/main/sync.sh | bash

# Windows PowerShell
$env:BASECOAT_REPO = 'https://github.com/IBuySpy-Shared/basecoat.git'
irm https://raw.githubusercontent.com/IBuySpy-Shared/basecoat/main/sync.ps1 | iex

What you get: all agents, skills, instructions, and prompts overlaid into .github/.

Best for: individuals, small teams, and anyone evaluating BaseCoat.

Level 2 — Configure with `.basecoat.yml`¶

Add a .basecoat.yml file to your repo root to control which assets are synced and how. The sync script reads it automatically on the next run.

# .basecoat.yml
source: https://github.com/IBuySpy-Shared/basecoat.git
ref: v3.25.0   # pin to a release tag for stability

# Only sync agents relevant to your stack
agents:
  - solution-architect
  - code-review
  - sprint-planner
  - security-review

# Only sync skills relevant to your work
skills:
  - azure-diagnostics
  - database-migration

# Always include governance instructions
instructions:
  - governance
  - token-economics

sync:
  exclude:
    - archive/   # skip archived assets

What configuration lets you do¶

Capability	How
Pin to a specific version	Set `ref: v3.x.y`
Include only relevant agents	List them under `agents:`
Exclude noisy or irrelevant skills	Omit from `skills:` or add to `exclude:`
Skip the `archive/` directory	Add `archive/` to `sync.exclude`
Point at your org's fork	Set `source:` to your fork URL

Best for: teams that want to stay in sync with upstream but don't need everything.

Level 3 — Add private agents (without forking)¶

You can add agents, skills, or instructions that live only in your repo — they co-exist with synced BaseCoat assets without any conflict.

Place private assets outside the sync target paths:

your-repo/
├── .github/
│   ├── agents/               ← synced from BaseCoat (do not edit)
│   ├── skills/               ← synced from BaseCoat (do not edit)
│   └── copilot-instructions.md  ← synced from BaseCoat (do not edit)
├── copilot/
│   ├── agents/               ← your private agents (not touched by sync)
│   │   └── deploy-to-prod.agent.md
│   └── skills/
│       └── our-stack/SKILL.md

Or, add your private agents as custom instructions that extend the synced globals:

<!-- .github/my-team.instructions.md — not synced; committed by you -->
applyTo: "src/**/*.py"
---
Always use our internal `app.logger` module, not the stdlib `logging` module.

Best for: teams with proprietary domain knowledge or internal tooling that shouldn't be contributed upstream.

Level 4 — Fork and extend¶

Fork BaseCoat into your GitHub org and maintain your own version. Your fork gets upstream updates on your schedule; you add organization-specific assets that are available to all your consumer repos.

Fork setup¶

# Fork via GitHub CLI
gh repo fork IBuySpy-Shared/basecoat --org YOUR-ORG --clone

# Or: mirror to your org
git clone https://github.com/IBuySpy-Shared/basecoat.git
cd basecoat
git remote rename origin upstream
git remote add origin https://github.com/YOUR-ORG/basecoat.git
git push -u origin main

Point your consumers at the fork¶

# .basecoat.yml in each consumer repo
source: https://github.com/YOUR-ORG/basecoat.git

Stay in sync with upstream¶

Add an upstream sync workflow to your fork:

# .github/workflows/upstream-sync.yml
name: Sync from upstream
on:
  schedule:
    - cron: '0 6 * * 1'  # weekly Monday 6am
  workflow_dispatch:

jobs:
  sync:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - name: Fetch upstream
        run: |
          git remote add upstream https://github.com/IBuySpy-Shared/basecoat.git
          git fetch upstream
          git merge upstream/main --no-edit || echo "Conflicts need manual resolution"
      - name: Open PR if changes
        run: gh pr create --fill --base main || true
        env:
          GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}

Best for: enterprises managing multiple teams, platform teams, and orgs that need to add proprietary agents centrally.

Override strategy: your version always wins¶

When you add a file with the same name as a BaseCoat asset in your fork, your version takes precedence after the next sync. Downstream consumers get your version, not the upstream original.

IBuySpy-Shared/basecoat
  └── agents/code-review.agent.md   ← upstream original

YOUR-ORG/basecoat (fork)
  └── agents/code-review.agent.md   ← your override wins

Use this to:

Add org-specific patterns to an existing agent
Replace a BaseCoat instruction with your team's version
Add a skill that wraps your internal platform

Contributing back¶

If something you built would help everyone using BaseCoat, contribute it upstream. See the contribution guide for the process.

The memory triage guide helps you decide whether a learning belongs in the shared repo or stays in your fork.

Verification¶

After any customization, verify BaseCoat is correctly wired:

# Run the full test suite
pwsh tests/run-tests.ps1

# Check asset structure
pwsh scripts/validate-basecoat.ps1

# Verify instruction coverage
pwsh scripts/check-coherence.ps1 -Strict

If tests pass, Copilot can see all your agents, skills, and instructions.