Configuring GitHub Copilot
Relevant source files
The following files were used as context for generating this wiki page:
GitHub Copilot is one of the supported AI coding agents for the Spec-Driven Development (SDD) workflow within the spec-kit project. Proper configuration ensures that Copilot has the necessary context to understand the project's architecture, technologies, and recent changes, enabling it to effectively execute commands like /specify, /plan, and /tasks.
The primary mechanism for configuring Copilot is the .github/copilot-instructions.md file. This file is automatically generated and updated by the spec-kit tooling, providing a dynamic and up-to-date context for the AI agent. This approach ensures that as the project evolves, Copilot's knowledge evolves with it.
Sources: README.md:39-42, spec-driven.md:120-123, templates/plan-template.md:11-12
Project Initialization with Copilot
To begin a project using GitHub Copilot, you use the specify init command. This command bootstraps the project environment with the necessary artifacts for the SDD workflow.
Sources: README.md:144-147
init Command
The specify init command can be used with the --ai copilot option to specifically configure the project for use with GitHub Copilot. If no AI assistant is specified, the CLI will present an interactive menu where you can select "GitHub Copilot".
Sources: src/specify_cli/init.py:646-650, src/specify_cli/init.py:688-696
The following diagram illustrates the initialization flow when selecting GitHub Copilot.
The key options for the init command are summarized below:
| Option | Description | Example |
|---|---|---|
project_name | The name for the new project directory. | specify init my-app |
--ai | Specifies the AI assistant to use. | specify init --ai copilot |
--here | Initializes the project in the current directory. | specify init --here --ai copilot |
Sources: src/specify_cli/init.py:623-630
Agent Context File: .github/copilot-instructions.md
The core of Copilot's configuration is the .github/copilot-instructions.md file. This file is created and updated during the SDD workflow, specifically by the /plan command, which invokes the update-agent-context.sh script. Its purpose is to provide a concise, high-level summary of the project's technical landscape.
Sources: templates/plan-template.md:11-12, scripts/update-agent-context.sh:3-4
Structure of the Context File
The .github/copilot-instructions.md file is generated from templates/agent-file-template.md and contains several key sections that are incrementally updated.
| Section | Description | Source of Information |
|---|---|---|
| Active Technologies | A list of languages, frameworks, and databases used in the project. | Extracted from all plan.md files. |
| Project Structure | A high-level view of the repository's directory structure. | Determined from the Project Type in plan.md. |
| Commands | Common commands for testing and linting active technologies. | Added based on the languages detected. |
| Code Style | A brief note on following standard conventions for the languages in use. | Based on languages from plan.md. |
| Recent Changes | A list of the last 3 features and the technologies they added. | Updated with each new feature plan. |
| Manual Additions | A dedicated section for developers to add persistent, custom instructions. | Preserved between automatic updates. |
Sources: templates/agent-file-template.md, scripts/update-agent-context.sh:105-180
Context Update Process
The update-agent-context.sh script is responsible for maintaining the .github/copilot-instructions.md file. It is designed as an incremental, O(1) operation that reads the current plan.md for a new feature and updates the context file without re-scanning the entire repository.
The following diagram shows the logic of the update script when the agent type is copilot.
The script identifies the Copilot context file via a hardcoded path:
# scripts/update-agent-context.sh:16
COPILOT_FILE="$REPO_ROOT/.github/copilot-instructions.md"
When the script is executed with copilot as an argument, it specifically targets this file for updates.
# scripts/update-agent-context.sh:214-216
"copilot")
update_agent_file "$COPILOT_FILE" "GitHub Copilot"
;;
Sources: scripts/update-agent-context.sh:16, scripts/update-agent-context.sh:214-216
Workflow Integration
GitHub Copilot is integrated into the core Spec-Driven Development workflow. The user interacts with Copilot using chat commands to drive the process from specification to implementation.
The following sequence diagram illustrates the end-to-end workflow.
This automated, context-aware workflow ensures that as a developer defines the technical plan for a new feature, GitHub Copilot is immediately updated with that context, making it ready for the subsequent implementation tasks.
Sources: CONTRIBUTING.md:10-13, spec-driven.md:105-118