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 configcd~/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 templatescd~/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