dotcopilot

Personal dotfiles for GitHub Copilot CLI and VS Code Copilot configuration. Modular, token-efficient instructions that replace a monolithic 1233-line config.

Philosophy

Instead of one massive global instructions file loaded into every context:

• Global file: ~130 lines of core principles (always loaded)
• Per-repo rules: path-scoped .github/instructions/*.instructions.md files loaded only when editing matching files
• Agents: loaded only when invoked — zero cost otherwise
• Hooks: shell scripts — zero token cost

Result: ~80-120 tokens loaded per context instead of ~1200.

Quick Start

# Clone
git clone https://github.com/askb/dotcopilot.git ~/git/dotcopilot

# Install (symlink mode — edits in repo auto-propagate)
cd ~/git/dotcopilot
bash install.sh --link

# Or copy mode (independent copies)
bash install.sh --copy

# With backup of existing files
bash install.sh --link --backup

After install, edit ~/.copilot/config.json to set your trusted_folders.

Directory Structure

dotcopilot/
├── copilot-instructions.md        # Global CLI instructions (~130 lines)
├── copilot-instructions-vscode.md # VS Code instructions (~70 lines)
├── config.json.example            # Copilot CLI config template
├── mcp-config.json.example        # MCP server config template
├── install.sh                     # Bootstrap installer
├── uninstall.sh                   # Clean uninstaller
├── agents/                        # Custom agent definitions
│   ├── bash-scripts.md            # Bash scripting expert
│   ├── code-quality.md            # Linting and compliance
│   ├── github-actions.md          # Actions development
│   ├── home-assistant.md          # Home Assistant config
│   ├── jjb-specialist.md          # Jenkins Job Builder
│   ├── openstack-infra.md         # OpenStack infrastructure
│   ├── repo-management.md         # Git repo operations
│   └── security-reviewer.md       # Security code review
├── rules/                         # Domain-specific rules (reference + templates)
│   ├── bash-standards.md          # applyTo: **/*.sh
│   ├── core-principles.md         # Always-apply reference
│   ├── documentation.md           # applyTo: **/*.md
│   ├── gerrit-workflow.md         # applyTo: .github/workflows/**
│   ├── github-actions.md          # applyTo: .github/workflows/**
│   ├── jjb-development.md         # applyTo: jjb/**
│   ├── openstack-infra.md         # applyTo: packer/**
│   ├── python-standards.md        # applyTo: **/*.py
│   └── security.md                # applyTo: scripts/**
├── hooks/                         # Shell script guardrails (zero token cost)
│   ├── block-dangerous-commands.sh
│   ├── protect-files.sh
│   └── scan-secrets.sh
├── skills/                        # Copilot skills
│   ├── gerrit-submit/SKILL.md     # Gerrit submission workflow
│   ├── packer-debug/SKILL.md      # Packer build debugging
│   └── setup-project/SKILL.md     # Auto-detect and setup
├── templates/                     # Per-repo config templates
│   ├── github-action/             # For GitHub Action repos
│   ├── odl-project/               # For OpenDaylight repos
│   ├── packer-repo/               # For Packer repos
│   └── python-tool/               # For Python CLI tools
├── .github/workflows/
│   ├── ci.yaml                    # Lint, shellcheck, test-install
│   ├── release.yaml               # Tag-based releases
│   ├── issue-triage.md            # AI: auto-label new issues
│   ├── pr-review.md               # AI: standards compliance review
│   ├── docs-sync.md               # AI: weekly README tree check
│   └── health-report.md           # AI: monthly health assessment
├── .github/
│   ├── dependabot.yml             # Automated dependency updates
│   ├── PULL_REQUEST_TEMPLATE.md   # PR checklist template
│   └── ISSUE_TEMPLATE/            # Issue form templates
│       ├── bug.yaml
│       └── feature.yaml
└── LICENSES/
    └── Apache-2.0.txt             # REUSE compliance

How Instructions Load

Layer 1: Global (always loaded)

~/.copilot/copilot-instructions.md — core principles, commit format, non-negotiable rules. ~130 lines.

Layer 2: Per-Repo (loaded per-repo)

.github/copilot-instructions.md — project-specific context. Installed from templates.

Layer 3: Path-Scoped (loaded per-file)

.github/instructions/*.instructions.md — loaded only when editing files matching the applyTo: glob pattern.

---
applyTo: "jjb/**"
---

JJB-specific instructions here...

Layer 4: Agents (loaded on invocation)

~/.copilot/agents/*.md — loaded only when you invoke @agent-name.

Using Templates

Copy the appropriate template into your repo:

# For an ODL project (builder, netconf, etc.)
mkdir -p .github/instructions
cp ~/git/dotcopilot/templates/odl-project/copilot-instructions.md .github/
cp ~/git/dotcopilot/templates/odl-project/AGENTS.md .
cp ~/git/dotcopilot/templates/odl-project/instructions/*.instructions.md \
    .github/instructions/

# For a GitHub Action repo
cp ~/git/dotcopilot/templates/github-action/copilot-instructions.md .github/
cp ~/git/dotcopilot/templates/github-action/AGENTS.md .
cp ~/git/dotcopilot/templates/github-action/instructions/*.instructions.md \
    .github/instructions/

Or use the setup-project skill to auto-detect your stack.

Token Cost Comparison

Configuration	Lines	Tokens (approx)
Old monolithic	1233	~4000
New global only	~130	~400
+ 1 path-scoped rule	~45	~150
+ 1 agent (invoked)	~40	~130
Typical session	~175	~550

~85% reduction in baseline token cost.

Agents

Agent	Purpose
@bash-scripts	Shellcheck-compliant bash with error handling
@code-quality	Pre-commit, SPDX, linting, formatting
@github-actions	Composite actions, reusable workflows
@home-assistant	HA automations, blueprints, dashboards
@jjb-specialist	JJB configuration for ODL projects
@openstack-infra	Bastion pattern, Packer, Tailscale
@repo-management	Repo splits, git-filter-repo, migrations
@security-reviewer	Secrets, supply chain, auth patterns

Hooks

Shell scripts that guard against dangerous operations. Exit code 0 = allow, exit code 2 = block.

Hook	Guards Against
protect-files.sh	Edits to .env, .pem, .key, credentials
scan-secrets.sh	AWS keys, GitHub tokens, private keys in content
block-dangerous-commands.sh	Force push, rm -rf /, DROP TABLE

New Machine Setup

# 1. Clone dotcopilot
git clone https://github.com/askb/dotcopilot.git ~/git/dotcopilot

# 2. Install global config
cd ~/git/dotcopilot && bash install.sh --link

# 3. Edit config
vim ~/.copilot/config.json     # Set trusted_folders
vim ~/.copilot/mcp-config.json # Set MCP server token

# 4. For each project repo, install templates
cd ~/git/builder
mkdir -p .github/instructions
cp ~/git/dotcopilot/templates/odl-project/instructions/*.instructions.md \
    .github/instructions/

Agentic Workflows

This repository uses GitHub Agentic Workflows (gh aw) to automate repository maintenance with AI-powered agents.

Workflow	Trigger	Purpose
Issue Triage	Issue opened/edited	Labels issues and posts guidance
PR Review	PR opened/synced	Checks SPDX headers, shellcheck, secrets
Docs Sync	Weekly (Monday)	Verifies README tree matches repo structure
Health Report	Monthly (1st)	Generates repository health assessment

See .github/workflows/ for the full workflow definitions.

Contributing

1. Fork and create a topic branch
2. Make changes following the coding standards in rules/
3. Run pre-commit run --all-files
4. Commit with DCO: git commit -s -m "type: description"
5. Submit a pull request

License

SPDX-License-Identifier: Apache-2.0