Skip to content

GitHub Copilot Customization

Klondike generates a rich .github/ directory structure that integrates with GitHub Copilot to create an effective agent workflow. This guide explains how all the pieces work together.

Overview

When you run klondike init, it creates customization files in your .github/ directory:

.github/
├── copilot-instructions.md    # Main agent instruction file
├── instructions/              # Context-specific instruction files
│   ├── git-practices.instructions.md
│   ├── session-artifacts.instructions.md
│   └── testing-practices.instructions.md
├── prompts/                   # Reusable prompt templates
│   ├── session-start.prompt.md
│   ├── session-end.prompt.md
│   ├── verify-feature.prompt.md
│   └── ...more prompts
└── templates/                 # Project templates
    ├── init.sh               # Unix initialization script
    ├── init.ps1              # PowerShell initialization script
    └── features.schema.json  # Feature registry schema

How It Works

graph TD
    A[klondike init] --> B[.github/ files]
    B --> C[copilot-instructions.md]
    B --> D[instructions/]
    B --> E[prompts/]
    B --> F[templates/]

    C --> G[Always loaded by Copilot]
    D --> H[Loaded based on file patterns]
    E --> I[User-triggered prompts]
    F --> J[Copied to project root]

    G --> K[Agent Behavior]
    H --> K
    I --> K

The Integration Loop

  1. Klondike CLI manages structured artifacts (features, sessions, progress)
  2. Instruction files tell Copilot to use klondike CLI commands
  3. Copilot reads instructions and uses klondike to access project state
  4. Prompt files provide structured workflows for common tasks

This creates a virtuous cycle where the agent maintains proper workflow discipline automatically.

Instruction Files

Instruction files use the .instructions.md extension and provide context-aware guidance to Copilot.

Format

---
description: "Brief description shown in VS Code"
applyTo: "**/*.test.*,**/tests/**"
---

# Your Instructions

Content that will be included in Copilot's context
when working with matching files.

The applyTo Property

The applyTo frontmatter uses glob patterns to determine when instructions apply:

Pattern Matches
**/* All files (always active)
**/*.test.* All test files
**/tests/** Any file under a tests directory
**/.klondike/** Klondike artifact files
**/agent-progress.md Progress file specifically

Included Instruction Files

git-practices.instructions.md

Applies to: **/* (all files)

Covers: - Commit frequency and message formats - Recovery patterns (revert, stash, reflog) - Branch management - Session end checklist

# This instruction file ensures agents use good git hygiene
# Example: conventional commit format
git commit -m "feat(auth): add login form validation"

session-artifacts.instructions.md

Applies to: **/agent-progress.md,**/.klondike/**

Critical instruction that prevents agents from reading raw JSON files:

Key Rule

Agents must use klondike CLI commands instead of reading artifact files directly. This ensures consistent interpretation and prevents corruption.

testing-practices.instructions.md

Applies to: **/*.test.*,**/*.spec.*,**/test/**,**/tests/**,**/__tests__/**

Defines: - E2E verification requirements - Testing approaches by application type - Evidence documentation standards

Prompt Files

Prompt files use the .prompt.md extension and provide structured workflows that users can trigger.

Format

---
name: prompt-name
description: "What this prompt does"
---

# Goal

What the agent should accomplish.

## Instructions

Step-by-step guidance for the agent.

Using Prompts

In VS Code with GitHub Copilot:

  1. Open the Command Palette (Ctrl+Shift+P / Cmd+Shift+P)
  2. Type "Copilot: Use Prompt File"
  3. Select the desired prompt

Or reference prompts in chat: 

@workspace /session-start

Included Prompt Files

session-start.prompt.md

Executes the standardized startup routine:

  1. Orient yourself (pwd, ls)
  2. Check project status with klondike status
  3. Review git history
  4. Start session with klondike session start
  5. Run init scripts if present
  6. Create a session plan
  7. Begin implementation

session-end.prompt.md

Executes the standardized shutdown routine:

  1. Run pre-commit verification
  2. Commit outstanding work
  3. Verify feature completion with klondike feature verify
  4. End session with klondike session end
  5. Verify clean git state

verify-feature.prompt.md

Rigorous end-to-end feature verification:

  1. Load feature details with klondike feature show
  2. Ensure environment is running
  3. Design verification plan for each criterion
  4. Execute tests as a real user would
  5. Document results
  6. Update feature status with evidence

add-features.prompt.md

Expand the feature registry:

  1. Review existing features
  2. Structure new features with proper criteria
  3. Add using klondike feature add
  4. Verify with klondike feature list

recover-from-failure.prompt.md

Recovery workflow when things go wrong:

  1. Assess the damage
  2. Use git to recover
  3. Fix broken tests/builds
  4. Document what happened
  5. Resume normal workflow

Templates

Templates are copied to your project root during klondike init.

init.sh / init.ps1

Environment initialization scripts that:

  1. Check prerequisites (Node.js, Python, etc.)
  2. Kill stale processes on dev ports
  3. Install dependencies
  4. Start dev server in background
  5. Wait for server to be ready with health checks
  6. Exit cleanly (don't block)

Background Processes

The key insight is that init scripts start servers in the background and exit. This allows agents to verify the server is running without blocking.

See the Init Scripts Guide for customization details.

features.schema.json

JSON Schema for the features.json file structure. Used for:

  • IDE validation
  • Documentation generation
  • Third-party tool integration

Customization

Adding Custom Instructions

Create new instruction files for project-specific needs:

---
description: "API endpoint conventions for this project"
applyTo: "**/api/**,**/routes/**"
---

# API Development Guidelines

## Endpoint Naming
- Use kebab-case for URLs
- Use plural nouns for collections

## Response Format
Always return:
```json
{
  "data": {},
  "error": null,
  "meta": {}
}

### Adding Custom Prompts

Create prompts for recurring tasks:

```markdown
---
name: deploy-staging
description: "Deploy current branch to staging environment"
---

# Goal

Deploy the current branch to staging and verify it's working.

## Instructions

1. Run `klondike validate` to ensure clean state
2. Push to origin
3. Trigger staging deployment
4. Verify health endpoints
5. Run smoke tests

Modifying Templates

Edit the init scripts for your stack:

For a Python project: 

# In init.ps1
if (-not (Get-Command python -ErrorAction SilentlyContinue)) {
    Write-Host "❌ Python is required but not installed" -ForegroundColor Red
    exit 1
}

# Use uv for package management
uv sync
uv run python manage.py runserver &

For a different port: 

# In init.sh
DEV_PORT=8080  # Change from default 3000

Integration with klondike CLI

The customization files work together with klondike CLI commands:

Component Purpose CLI Integration
copilot-instructions.md Define agent behavior References all klondike commands
Instruction files Context-specific rules Tell agents to use specific commands
Prompt files Structured workflows Execute klondike commands as steps
Init scripts Environment setup Called before klondike operations

Example Flow

  1. User says: "Start a new session"
  2. Copilot loads copilot-instructions.md (always active)
  3. Instructions say: "Run klondike session start"
  4. Copilot executes the command
  5. Klondike updates .klondike/agent-progress.json
  6. Session is tracked and ready for handoff

Best Practices

Do

  • ✅ Keep instruction files focused and specific
  • ✅ Use precise applyTo patterns
  • ✅ Reference klondike CLI commands, not file paths
  • ✅ Create prompts for complex, recurring workflows
  • ✅ Customize init scripts for your project

Don't

  • ❌ Put sensitive information in instruction files
  • ❌ Create overlapping applyTo patterns that conflict
  • ❌ Tell agents to read .klondike/*.json directly
  • ❌ Create prompts that skip verification steps
  • ❌ Modify templates in .github/templates/ (copy to root first)

Next Steps