Reliable AI Workflow with GitHub Copilot: A Complete Guide with Examples

Hi! Today, I'm sharing a concise guide on setting up a project for GitHub Copilot.

Reliable AI Workflow with GitHub Copilot: A Complete Guide with Examples

This guide demonstrates how to create predictable and reproducible AI workflows in your repository and IDE/CLI using agent primitives and context engineering. You'll find file structure, ready-made templates, security rules, and commands.

⚠️ Note: The functionality of prompt files and the agent mode in IDE/CLI may change—adapt this guide to the specific versions of Copilot and VS Code you are using.

1) Overview: What Constitutes a Workflow

The main goal is to break down the agent's work into transparent and controllable steps. For this purpose, the following tools are available:

• Custom Instructions (.github/copilot-instructions.md) — global project rules (how to build, how to test, code style, PR policies).
• Path-specific Instructions (.github/instructions/*.instructions.md) — rules for specific areas, applied via applyTo (glob patterns).
• Chat Modes (.github/chatmodes/*.chatmode.md) — specialized chat modes (e.g., Plan/Frontend/DBA) with fixed tools and models.
• Prompt Files (.github/prompts/*.prompt.md) — reusable scenarios/"programs" for typical tasks (review, refactoring, generation).
• Context helpers (docs/*.spec.md, docs/*.context.md, docs/*.memory.md) — specifications, references, and project memory for precise context.
• MCP servers (.vscode/mcp.json or via UI) — tools and external resources the agent can use.

2) Project File Structure

The following structure corresponds to the tools described above and helps construct a complete workflow for agents.

1.github/
2  copilot-instructions.md
3  instructions/
4    backend.instructions.md
5    frontend.instructions.md
6    actions.instructions.md
7  prompts/
8    implement-from-spec.prompt.md
9    security-review.prompt.md
10    refactor-slice.prompt.md
11    test-gen.prompt.md
12  chatmodes/
13    plan.chatmode.md
14    frontend.chatmode.md
15.vscode/
16  mcp.json
17docs/
18  feature.spec.md
19  project.context.md
20  project.memory.md

3) Files and Their Purpose — Technical Explanation

Now, let's examine each tool separately and its role. Below is an explanation of how it all works under the hood: what these files are, why they exist, how they influence the agent's task understanding, and in what order they are combined/overridden. Code examples below comply with the specification.

Order of combining rules and settings: Prompt Frontmatter → Chat Mode → Repo/Path Instructions → Defaults.

Now let's look at each tool individually.

3.1. Global Rules — .github/copilot-instructions.md

What it is: A Markdown file with short, verifiable rules: how to build, test, code style, and PR policies.

Purpose: To ensure all responses adhere to a single set of standards (without duplication in each prompt).

How it works: The file automatically becomes part of the system context for all queries within the repository. It has no applyTo (more on that below) – it applies everywhere.

Minimal Example:

1# Repository coding standards
2- Build: `npm ci && npm run build`
3- Tests: `npm run test` (coverage ≥ 80%)
4- Lint/Typecheck: `npm run lint && npm run typecheck`
5- Commits: Conventional Commits; keep PRs small and focused
6- Docs: update `CHANGELOG.md` in every release PR

Tips.

1. Keep points concise.
2. Avoid vague phrases.
3. Include only what can influence the outcome (build/test/lint/type/PR policy).

3.2. Path-Specific Instructions — .github/instructions/*.instructions.md

What it is: Modular rules with YAML frontmatter applyTo — glob patterns for files to which they apply.

Purpose: To differentiate standards in different areas (frontend/backend/CI). Allows controlling context based on task type.

How it works: When processing a task, Copilot finds all *.instructions.md files whose applyTo matches the current context (files you are discussing/editing). Matching rules are added to the global ones.

Example:

1---
2applyTo: "apps/web/**/*.{ts,tsx},packages/ui/**/*.{ts,tsx}"
3---
4- React: function components and hooks
5- State: Zustand; data fetching with TanStack Query
6- Styling: Tailwind CSS; avoid inline styles except dynamic cases
7- Testing: Vitest + Testing Library; avoid unstable snapshots

Note.

1. Avoid duplicating existing global rules.
2. Ensure the glob pattern accurately targets the intended paths.

3.3. Chat Modes — .github/chatmodes/*.chatmode.md

What it is: Configuration files that define the agent's operating mode for a conversation: a short description, model (if needed), and a list of allowed tools.

Purpose: To separate work phases (planning/frontend/DBA/security) and restrict tools at each stage. This makes results more predictable.

File Structure:

1---
2description: "Plan - analyze code/specs and propose a plan; read-only tools"
3model: GPT-4o
4tools:[ "search/codebase"]
5---
6In this mode:
7- Produce a structured plan with risks and unknowns
8- Do not edit files; output a concise task list instead

How it works:

• A chat mode applies to the current chat in the IDE.
• If you activate a prompt file, its frontmatter takes precedence (it can change the model and narrow down tools).
• The effective list of allowed tools: chat mode tools, restricted by prompt tools and --allow/--deny CLI flags.

Management and Switching:

• In IDE (VS Code):

1. Open the Copilot Chat panel.
2. In the top bar, select the desired chat mode from the dropdown list (the list is built from .github/chatmodes/*.chatmode.md + built-in modes).
3. The mode applies only to this conversation thread. To change it, select another mode or create a new thread with the desired mode.
4. Check the active mode in the conversation header/panel; *.chatmode.md will be visible in References.

• In CLI: (a bit hacky, better via prompts)

  • There's usually no special CLI flag for switching modes; encode the desired restrictions in the prompt file's frontmatter and/or via --allow-tool/--deny-tool flags.
  • You can specify in the first line: "Use i18n chat mode." — if the version supports it, the agent might switch; if not, the prompt's frontmatter will still apply tool restrictions.

• Without switching modes: run a prompt with the desired tools: in the frontmatter — this will restrict tools regardless of the chat mode.

Diagnostics: If the agent uses "extra" tools or doesn't see the required ones, check: (1) which chat mode is selected; (2) tools in the prompt frontmatter; (3) --allow/--deny CLI flags; (4) References in the response (visible *.chatmode.md/*.prompt.md files).

3.4. Prompt Files — .github/prompts/*.prompt.md

What it is: Scenario files for reusable tasks. Consist of YAML frontmatter (configuration) and body (instructions/steps/acceptance criteria). Invoked in chat via /name or via CLI.

When to Use: When a predictable, automatable process is needed: PR review, test generation, feature implementation from a specification, etc.

Frontmatter Structure

• description — brief purpose of the scenario.
• mode — ask (Q&A, no file editing) · edit (local editing of open files) · agent (multi-step process with tools).
• model — desired model profile.
• tools — list of allowed tools for the scenario (restricts even what the chat mode allowed).

Execution Algorithm (Sequence)

1. Where to Run:

• In Chat: type /prompt-name and arguments in the message field.
• In CLI: invoke copilot and pass the string /prompt-name … (interactively or via heredoc / -p flag).

2. Context Gathering: Copilot builds the execution context in the following order: repo-instructions → path-instructions (applyTo) → chat mode → prompt frontmatter (prompt frontmatter has the highest priority and can restrict tools/change the model).

3. Parameter Parsing (Where and How):

   • In Chat: parameters follow in the same message after the name, e.g.: /security-review prNumber=123 target=apps/web.
   • In CLI: parameters follow in the same line /… in stdin or after the -p flag.
   • Inside the prompt file, they are available as ${input:name}. If a required parameter is missing, the prompt may ask for it via text in the dialogue.

4. Tool Permission Resolution:

• Effective list of allowed tools: chat mode tools, restricted by prompt tools and --allow/--deny CLI flags.
• If a tool is denied, the corresponding step is skipped or requires confirmation / policy change.

5. Executing Prompt Body Steps: The agent strictly follows the order of steps, performing only what is permitted by policies/tools (codebase search, diff generation, test execution, etc.). For potentially risky actions, it requests confirmation.

6. Validation Gates: At the end, the prompt runs checks (build/tests/lint/typecheck). If a check fails, the agent returns a list of issues and suggests next steps (without auto-merge/saving changes).

7. Where the Result Appears (What is Visible Where):

• Main Response — in the chat panel (IDE) or stdout (CLI): tables, lists, text reports, code blocks with diff.
• File Changes — in your working tree: diffs/proposed patches are visible in the IDE; files are modified locally in the CLI (if permitted by tools).
• Additional Artifacts — e.g., a PR comment, if GitHub tools are allowed and the prompt specifies it.

Output Format and Checks (Recommendations)

• Always specify the output format (e.g., a table of «issue | file | line | severity | fix»).
• Include validation gates: build/tests/lint/typecheck; require unified-diff for proposed changes; a TODO list for unresolved issues.

Example Complete Prompt File

1---
2mode: 'agent'
3model: GPT-4o
4tools: ['search/codebase']
5description: 'Implement a feature from a spec'
6---
7Goal: Implement the feature described in @docs/feature.spec.md.
8
9Steps:
101) Read @docs/feature.spec.md and produce a short implementation plan (bullets)
112) List files to add/modify with paths
123) Propose code patches as unified diff; ask before installing new deps
134) Generate minimal tests and run them (report results)
14
15Validation gates:
16- Build, tests, lint/typecheck must pass
17- Output includes the final diff and a TODO list for anything deferred
18- If any gate fails, return a remediation plan instead of "done"

Anti-patterns

• Vague descriptions: keep description to 1-2 lines.
• Missing output format.
• Too many tools: allow only necessary ones (tools).

Quick Start

• Chat: /implement-from-spec
• CLI: copilot <<<'/implement-from-spec' or copilot -p "Run /implement-from-spec"

3.5. Context Files — specs/context/memory

What it is: Auxiliary Markdown files (not special types) that you reference via @ in the dialogue/prompt. Usually stored as documentation.

• docs/*.spec.md — precise task definitions (goal, acceptance criteria, edge cases, non-goals).
• docs/*.context.md — short references (API policies, security, UI styleguide, SLA).
• docs/*.memory.md — a "decision log" with dates and justifications, so the agent doesn't revisit long-resolved issues.

Example:

1# Feature: Export report to CSV
2Goal: Users can export the filtered table to CSV.
3Acceptance criteria:
4- "Export CSV" button on /reports
5- Server generates file ≤ 5s for 10k rows
6- Column order/headers match UI; locale-independent values
7Edge cases: empty values, large numbers, special characters
8Non-goals: XLSX, multi-column simultaneous filters

3.6. MCP — .vscode/mcp.json

What it is: Configuration for Model Context Protocol servers (e.g., GitHub MCP) that provide tools to the agent.

Purpose: To allow the agent to read PRs/issues, run tests, interact with databases/browsers — within allowed permissions.

Example:

1{
2  "servers": {
3    "github-mcp": {
4      "type": "http",
5      "url": "https://api.githubcopilot.com/mcp"
6    }
7  }
8}

Security. Only connect trusted servers; use allow/deny lists for tools in prompts/chat modes/CLI.

3.7. General Context Combination Order and Priorities (Rules & Tools)

1. Instructions: copilot-instructions + all *.instructions.md with applyTo matching current paths. Specific instructions are added to the general context.
2. Chat Mode: restricts the set of tools and (if necessary) the model for the session.
3. Prompt Frontmatter: has the highest priority; can restrict tools and override the model.
4. Context: everything you reference via @ is guaranteed to be considered by the model.

Diagnostics. Check the References section in the output — it indicates which instruction files were considered and which prompt was run.

3.8. Example: Full i18n Cycle with Goman MCP (Create/Update/Delete)

Below is the precise process and templates to ensure that: (a) when UI components are created, localization keys are created/updated in Goman; (b) when components are deleted, unused entries are detected and (after confirmation) deleted.

Code snippets and frontmatter are in English.

3.8.1. MCP Configuration — Connecting Goman

/.vscode/mcp.json

1{
2  "servers": {
3    "goman-mcp": {
4      "type": "http",
5      "url": "https://mcp.goman.live/mcp",
6      "headers": {
7        "apiKey": "<YOUR_API_KEY>",
8        "applicationid": "<YOUR_APPLICATION_ID>"
9      }
10    }
11  }
12}

3.8.2. Repo/Path Rules — Enforcing Default i18n

/.github/instructions/frontend.instructions.md (Addition)

1---
2applyTo: "apps/web/**/*.{ts,tsx}"
3---
4- All user-facing strings **must** use i18n keys (no hardcoded text in JSX/TSX)
5- Key naming: `<ui_component_area>.<n>` (e.g., `ui_button_primary.label`)
6- When creating components, run `/i18n-component-scaffold` and commit both code and created keys
7- When deleting components, run `/i18n-prune` and confirm removal of unused keys

3.8.3. Chat Mode — Restricted i18n Tools

/.github/chatmodes/i18n.chatmode.md

1---
2description: "i18n - manage localization keys via Goman MCP; enforce no hardcoded strings"
3model: GPT-4o
4tools:
5  - "files"
6  - "goman-mcp:*"
7---
8In this mode, prefer:
9- Creating/updating keys in Goman before writing code
10- Checking for existing keys and reusing them
11- Producing a table of changes (created/updated/skipped)

3.8.4. Prompt — Component Scaffolding + Goman Keys

/.github/prompts/i18n-component-scaffold.prompt.md

1---
2mode: 'agent'
3model: GPT-4o
4tools: ['files','goman-mcp:*']
5description: 'Scaffold a React component with i18n keys synced to Goman'
6---
7Inputs: componentName, namespace (e.g., `ui.button`), path (e.g., `apps/web/src/components`)
8
9Goal: Create a React component and ensure all user-visible strings use i18n keys stored in Goman.
10
11Steps:
121) Plan the component structure and list all user-visible strings
132) For each string, propose a key under `${namespace}`; reuse if it exists
143) Using Goman MCP, create/update translations for languages: en, be, ru (values may be placeholders)
154) Generate the component using `t('<key>')` and export it; add a basic test
165) Output a Markdown table: key | en | be | ru | action(created/updated/reused)
17
18Validation gates:
19- No hardcoded literals in the produced .tsx
20- Confirm Goman actions succeeded (report tool responses)
21- Tests and typecheck pass

Example Component Code:

1import { t } from '@/i18n';
2import React from 'react';
3
4type Props = { onClick?: () => void };
5
6export function PrimaryButton({ onClick }: Props) {
7  return (
8    <button aria-label={t('ui.button.primary.aria')} onClick={onClick}>
9      {t('ui.button.primary.label')}
10    </button>
11  );
12}

3.8.5. Prompt — Deleting Unused Keys on Component Removal

/.github/prompts/i18n-prune.prompt.md

1---
2mode: 'agent'
3model: GPT-4o
4tools: ['files','goman-mcp:*']
5description: 'Find and prune unused localization keys in Goman after code deletions'
6---
7Inputs: pathOrDiff (e.g., a deleted component path or a PR number)
8
9Goal: Detect keys that are no longer referenced in the codebase and remove them from Goman after confirmation.
10
11Steps:
121) Compute the set of removed/renamed UI elements (scan git diff or provided paths)
132) Infer candidate keys by namespace (e.g., `ui.<component>.*`) and check code references
143) For keys with **zero** references, ask for confirmation and delete them via Goman MCP
154) Produce a Markdown table: key | status(kept/deleted) | reason | notes
16
17Validation gates:
18- Never delete keys that still have references
19- Require explicit confirmation before deletion
20- Provide a rollback list of deleted keys

3.8.6. Prompt — Syncing and Checking for Missing Translations (Optional)

/.github/prompts/i18n-sync.prompt.md

1---
2mode: 'agent'
3model: GPT-4o
4tools: ['files','goman-mcp:*']
5description: 'Sync new/changed i18n keys and check for missing translations'
6---
7Goal: Compare code references vs Goman and fill gaps.
8
9Steps:
101) Scan code for `t('...')` keys under provided namespaces
112) For missing keys in Goman - create them (placeholder text ok)
123) For missing languages - create placeholders and report coverage
134) Output coverage table: key | en | be | de | missing

4) How to Use (IDE and CLI)

4.1. In VS Code / Other IDE

• Open Copilot Chat — select Agent/Edit/Ask from the dropdown.
• For prompt files, simply type /file-name without the extension (e.g., /security-review).
• Add context using @-mentions of files and directories.
• Switch chat modes (Plan/Frontend/DBA) when changing task types.

4.2. In Copilot CLI (Terminal)

• Installation Example: npm install -g @github/copilot → run copilot.
• Interactively: «Run /implement-from-spec on @docs/feature.spec.md».
• Programmatically / in CI: copilot -p "Implement feature from @docs/feature.spec.md" --deny-tool shell("rm*").
• Add/restrict tools using flags: --allow-all-tools, --allow-tool, --deny-tool (globally or by pattern, e.g., shell(npm run test:*)).

4.3. Command Recipes for CLI (Chat Modes and Prompts)

Ready-made recipes below. All commands should be run from the repository root and respect your deny/allow lists.

A. Running a Prompt File in an Interactive Session

1copilot
2# inside the session (type the string as is)
3/security-review prNumber=123

B. Running a Prompt File in Non-Interactive Mode (Heredoc)

1copilot <<'EOF'
2/security-review prNumber=123
3EOF

C. Passing Parameters to a Prompt File

1copilot <<'EOF'
2/implement-from-spec path=@docs/feature.spec.md target=apps/web
3EOF

Inside the prompt, values can be read as ${input:target} and ${input:path}.

D. Running a Prompt with Safe Tool Permissions

1copilot --allow-tool "shell(npm run test:*)" \
2        --deny-tool  "shell(rm*)" \
3        <<'EOF'
4/security-review prNumber=123
5EOF

E. Using Chat Mode (Specialized Mode) in CLI

1copilot
2# inside the session — ask to switch to the desired mode and run the prompt
3Use the i18n chat mode.
4/i18n-component-scaffold componentName=PrimaryButton namespace=ui.button path=apps/web/src/components

If your client supports mode selection via a menu, choose i18n before running the prompt. Otherwise, specify restrictions in the prompt's frontmatter (tools and rules in the prompt body).

F. Passing File/Diff Links as Context

1copilot <<'EOF'
2Please review these changes:
3@apps/web/src/components/PrimaryButton.tsx
4@docs/feature.spec.md
5/security-review prNumber=123
6EOF

G. Changing the Model for a Specific Run

We recommend specifying the model in the prompt's frontmatter. If supported, you can also pass a model flag during execution:

1copilot --model GPT-4o <<'EOF'
2/implement-from-spec
3EOF

H. i18n Cycle with Goman MCP (CHAT)

Run sequentially in the same chat thread:

1/i18n-component-scaffold componentName=PrimaryButton namespace=ui.button path=apps/web/src/components
2/i18n-prune pathOrDiff=@last-diff
3/i18n-sync namespace=ui.button

What you get:

• final tables/reports in the chat panel;
• code changes in your working tree (IDE shows diff);
• no need to run CLI commands for Goman MCP here.

5) Context Engineering: How Not to Overload with Extra Context

1. Separate sessions by phases: Plan → Implementation → Review/Tests. Each phase has its own Chat Mode.
2. Attach only necessary instructions: use path-specific *.instructions.md instead of loading everything.
3. Project Memory: record short ADRs in project.memory.md — this reduces the agent's "forgetfulness" between tasks.
4. Context Helpers: store frequent references (API/security/UI) in *.context.md and link to them from prompt files.
5. Focus on the Task: in prompt files, always specify the goal, steps, and output format (table, diff, checklist).

6) Security and Tool Management

• Require explicit confirmation before running commands/tools. In CI, use --deny-tool by default and add local allow lists.
• Permission Patterns: allow only what's necessary (shell(npm run test:*), playwright:*), deny dangerous patterns (shell(rm*)).
• Secrets: do not put keys in prompts and instructions; use GitHub Environments or local secret managers and .env with .gitignore.
• Any MCP: only from trusted sources; verify code/configuration before connecting.
• Patch Checks: require unified-diff and explanations in prompt files — this simplifies review.

7) CI/CD Recipe (Optional Example)

Ensure "everything builds": run Copilot CLI in safe mode to generate a PR comment.

1# .github/workflows/ai-review.yml
2name: AI Review (Copilot CLI)
3on:
4  pull_request:
5    types: [opened, synchronize, reopened]
6
7jobs:
8  ai_review:
9    runs-on: ubuntu-latest
10    permissions:
11      contents: read
12      pull-requests: write
13    steps:
14      - uses: actions/checkout@v4
15      - uses: actions/setup-node@v4
16        with:
17          node-version: 22
18      - name: Install Copilot CLI
19        run: npm install -g @github/copilot
20      - name: Run security review prompt (no dangerous tools)
21        env:
22          PR: ${{ github.event.pull_request.number }}
23        run: |
24          copilot -p "Run /security-review with prNumber=${PR}" \
25            --deny-tool shell("rm*") --deny-tool shell("curl*") \
26            --allow-tool shell("npm run test:*") \
27            --allow-tool "github:*" \
28            > ai-review.txt || true
29      - name: Comment PR with results
30        if: always()
31        run: |
32          gh pr comment ${{ github.event.pull_request.number }} --body-file ai-review.txt

Tip: Maintain strict deny/allow lists; do not give the agent "full freedom" in CI.

8) Small Scenarios and Useful Tips

• From Idea to PR: /plan — discuss the plan — /implement-from-spec → local tests — PR — /security-review.
• Maintenance: /refactor-slice for local improvements without changing behavior.
• Tests: /test-gen for new modules + manual additions for edge cases.
• Gradual Introduction: start with 1-2 prompt files and one chat mode; expand later.

9) Quality Checks (Validation Gates)

In each prompt file, define "what counts as done":

• Output Format: risk table, unified-diff, checklist.
• Automated Checks: build, unit/integration tests, lint/typecheck.
• Manual Check: "OK to merge?" with justification and residual risks.

10) Anti-patterns and Hacks

• Anti-pattern: one huge instructions.md. Prefer multiple *.instructions.md with applyTo.
• Anti-pattern: vague words instead of rules. Prefer specific commands/steps.
• Anti-pattern: running dangerous shell commands without checks. Use deny/allow and manual confirmation.
• Anti-pattern: forgotten specifications/memory. Maintain feature.spec.md and project.memory.md.
• Anti-pattern: mixing tasks in one session. Create Chat Modes for each phase.

11) Implementation Checklist

1. Add .github/copilot-instructions.md (at least 5-8 points on build/tests/style).
2. Create 1-2 *.instructions.md with applyTo (frontend/backend or workflows).
3. Add plan.chatmode.md and one prompt (e.g., implement-from-spec.prompt.md).
4. Create docs/feature.spec.md and docs/project.memory.md.
5. Connect MCP (at least GitHub MCP) via .vscode/mcp.json.
6. Run the workflow in VS Code: /implement-from-spec — check — PR.
7. (Optional) Add a simple AI review in CI via Copilot CLI with strict deny/allow lists.

12) Questions and Answers (FAQ)

Q: How to ensure Copilot "sees" my instructions? A: Check the summary/References in the response; also keep rules short and specific.

Q: Can parameters be passed dynamically to prompt files? A: Yes, typically via placeholder variables (like ${prNumber}) or simply by text prompt when running /prompt in chat.

Q: Where to store secrets for MCP? A: In GitHub Environments or local secret managers; not in .prompt.md/.instructions.md.

Q: What to choose: Chat Mode or Prompt File? A: Chat Mode defines the "frame" (model/tools/role). Prompt File is the "script" within that frame.

13) Next Steps

• Add a second prompt for your most frequent manual process.
• Make project.memory.md mandatory after all architectural decisions.
• Gradually move collective knowledge to *.context.md and link to them from prompt files.

Appendix A — Quick Start Templates

All keys, paths, and flags comply with documentation (October 28, 2025).

/.github/copilot-instructions.md — Repository-Wide Rules

1# Repository coding standards
2- Build: `npm ci && npm run build`
3- Tests: `npm run test` (coverage ≥ 80%)
4- Lint/Typecheck: `npm run lint && npm run typecheck`
5- Commits: Conventional Commits; keep PRs small and focused
6- Docs: update `CHANGELOG.md` in every release PR

/.github/instructions/frontend.instructions.md — Path-Specific Instructions

1---
2applyTo: "apps/web/**/*.{ts,tsx},packages/ui/**/*.{ts,tsx}"
3---
4- React: function components and hooks
5- State: Zustand; data fetching with TanStack Query
6- Styling: Tailwind CSS; avoid inline styles except dynamic cases
7- Testing: Vitest + Testing Library; avoid unstable snapshots

/.github/instructions/backend.instructions.md — Path-Specific Instructions

1---
2applyTo: "services/api/**/*.{ts,js},packages/server/**/*.{ts,js}"
3---
4- HTTP: Fastify; version APIs under `/v{N}`
5- DB access: Prisma; migrations via `prisma migrate`
6- Security: schema validation (Zod), rate limits, audit logs
7- Testing: integration tests via `vitest --config vitest.integration.ts`

/.github/instructions/actions.instructions.md — GitHub Actions

1---
2applyTo: ".github/workflows/**/*.yml"
3---
4- Keep jobs small; reuse via composite actions
5- Cache: `actions/setup-node` + built-in cache for npm/pnpm
6- Secrets: only through GitHub Environments; never hardcode

/.github/chatmodes/plan.chatmode.md — Custom Chat Mode

1---
2description: "Plan - analyze code/specs and propose a plan; read-only tools"
3model: GPT-4o
4tools:
5  - "search/codebase"
6---
7In this mode:
8- Produce a structured plan with risks and unknowns
9- Do not edit files; output a concise task list instead

/.github/prompts/security-review.prompt.md — Prompt File

1---
2mode: 'agent'
3model: GPT-4o
4tools: ['search/codebase']
5description: 'Perform a security review of a pull request'
6---
7Goal: Review PR ${input:prNumber} for common security issues.
8
9Checklist:
10- Authentication/authorization coverage
11- Input validation and output encoding (XSS/SQLi)
12- Secret management and configuration
13- Dependency versions and known CVEs
14
15Output:
16- A Markdown table: issue | file | line | severity | fix
17- If trivial, include a unified diff suggestion

/.github/prompts/implement-from-spec.prompt.md — Prompt File

1---
2mode: 'agent'
3model: GPT-4o
4tools: ['search/codebase']
5description: 'Implement a feature from a spec'
6---
7Your task is to implement the feature described in @docs/feature.spec.md.
8
9Steps:
101) Read @docs/feature.spec.md and summarize the plan
112) List files to add or modify
123) Propose code changes; ask before installing new dependencies
134) Generate minimal tests and run them
14
15Validation gates:
16- Build, tests, lint/typecheck must pass
17- Provide a TODO list for anything deferred

/.github/prompts/refactor-slice.prompt.md — Prompt File

1---
2mode: 'agent'
3model: GPT-4o
4description: 'Refactor a specific code slice without changing behavior'
5---
6Goal: Improve readability and reduce side effects in @src/feature/* while keeping behavior unchanged.
7Criteria: fewer side effects, clearer structure, all tests pass.

/.github/prompts/test-gen.prompt.md — Prompt File

1---
2mode: 'agent'
3model: GPT-4o-mini
4description: 'Generate tests for a given file/module'
5---
6Ask the user to @-mention the target file; generate unit/integration tests and edge cases.

/docs/feature.spec.md — Specification Template

1# Feature: Export report to CSV
2Goal: Users can export the filtered table to CSV.
3Acceptance criteria:
4- "Export CSV" button on /reports
5- Server generates file ≤ 5s for 10k rows
6- Column order/headers match UI; locale-independent values
7Edge cases: empty values, large numbers, special characters
8Non-goals: XLSX, multi-column simultaneous filters

/.vscode/mcp.json — Minimal MCP Configuration

1{
2  "servers": {
3    "github-mcp": {
4      "type": "http",
5      "url": "https://api.githubcopilot.com/mcp"
6    }
7  }
8}

Appendix B — Operational Addenda (CLI & CI Examples)

These examples supplement Appendix A; they describe usage in execution/automation and do not duplicate the templates above.

Copilot CLI — Safe Tool Permissions (Interactive / CI)

1# Run an interactive session in your repository
2copilot
3
4# Allow/deny specific tools (exact flags per GitHub documentation)
5copilot --allow-tool "shell(npm run test:*)" --deny-tool "shell(rm*)"
6
7# Run a prompt file in non-interactive mode (example)
8copilot <<'EOF'
9/security-review prNumber=123
10EOF

GitHub Actions — Commenting Review Results in PR

1name: AI Security Review (Copilot CLI)
2on:
3  pull_request:
4    types: [opened, synchronize, reopened]
5
6jobs:
7  review:
8    runs-on: ubuntu-latest
9    permissions:
10      contents: read
11      pull-requests: write
12    steps:
13      - uses: actions/checkout@v4
14      - uses: actions/setup-node@v4
15        with:
16          node-version: 22
17      - name: Install Copilot CLI
18        run: npm install -g @github/copilot
19      - name: Run security review prompt
20        env:
21          PR: ${{ github.event.pull_request.number }}
22        run: |
23          copilot --allow-tool "shell(npm run test:*)" --deny-tool "shell(rm*)" <<'EOF'
24          /security-review prNumber=${PR}
25          EOF
26      - name: Post results
27        run: |
28          gh pr comment ${{ github.event.pull_request.number }} --body "Copilot review completed. See artifacts/logs for details."

14) Setting Up Context on an Existing Project

This section addresses a specific task: taking a live project and creating a complete context and instructions for GitHub Copilot in one go. We're not inventing anything; everything is derived from what's already in the code.

Each step is a prompt executed in VS Code in Agent mode. Each subsequent step depends on the result of the previous one, so the order is important.

14.1. Step 1 — Project Audit

Goal: Obtain an objective project map. Without it, everything else is guesswork.

What to do: Open Copilot Chat, select Agent mode, attach the root folder via @, and run:

1@/
2
3Analyze the structure of this project. Determine:
4
5- Stack: language, frameworks, package manager
6- Build, test, lint commands (exact ones from package.json / pom.xml / Makefile, etc.)
7- Existing CI workflows (.github/workflows) — what runs there
8- Main folders and their purpose
9- Existing configurations: lint, prettier, typescript, and similar
10
11Return the result as a structured list.
12Do not guess — only what is actually visible in the files.

Result: Save the response — it will be needed in Step 2. This is the "source map"; the quality of everything that follows depends on it.

14.2. Step 2 — Generating Global Instructions

Goal: Create .github/copilot-instructions.md — a single source of truth for repository-wide rules.

What to do: Take the result from Step 1 and run:

1Based on this project audit:
2
3[insert Step 1 result here]
4
5Create the file .github/copilot-instructions.md
6
7Requirements:
8- Only facts from the audit, nothing made up
9- Build, test, lint commands — exact, copied from configs
10- Code style — only if prettier/eslint config exists, and only what's defined there
11- Commit policy — only if commitlint or similar exists
12- 8–12 points maximum
13- Each point — a single, specific line

Result: The .github/copilot-instructions.md file is created and committed to the working tree.

14.3. Step 3 — Generating Path-Specific Instructions

Goal: Create separate rules for different code areas that are automatically included based on path patterns.

When Needed: If the project has at least two logically separate areas — frontend and backend, apps and packages, multiple services. If the project is homogeneous — skip this step.

What to do: For each area, attach the relevant folder and run a separate prompt. Example for frontend:

1@src/components/
2@src/pages/
3
4Analyze this part of the project and determine:
5
6- Which framework and how components are written
7- State management patterns (if visible)
8- How tests are structured (if any)
9- Import and file naming conventions
10
11Create the file .github/instructions/frontend.instructions.md
12
13Requirements:
14- applyTo — an exact glob covering precisely these folders
15- Rules — only from what you see in the code
16- Does not duplicate what's already in copilot-instructions.md
17- No more than 6–8 points

A similar prompt for the backend, if it exists, with corresponding folders in @.

Result: Files in .github/instructions/ for each area.

14.4. Step 4 — Generating Project References

Goal: Create docs/project.context.md — a stable reference that reduces chat "noise" and doesn't require updates with every change.

What to do:

1@/
2@README.md
3@package.json
4
5Create the file docs/project.context.md —
6this is the project's reference for the AI assistant.
7
8Include:
9- Brief description: what the project does, for whom
10- Key architectural patterns, if visible in folder structure and imports
11- External dependencies and their roles (why these specific ones, if clear from context)
12- What NOT to do: deprecated folders, common pitfalls, known limitations
13
14Constraints:
15- Max 30–40 lines
16- Only what is objectively visible in the project
17- No assumptions or recommendations

Result: The docs/project.context.md file.

14.5. Step 5 — Generating Project Memory

Goal: Record decisions already made, so the agent doesn't revisit them.

What to do:

1@/
2
3Look at the project and find decisions that are already documented in the code:
4
5- Library choices — if obvious alternatives are visible in lock files or comments
6- Folder structure — if it's non-standard for this stack
7- Any TODO or FIXME items with context on why
8- Configurations with comments explaining the reasoning
9
10Create the file docs/project.memory.md in the format:
11
12## [Date or "unknown"] | Decision | Reason
13
14Each entry — max 2 lines.
15No more than 10–12 entries.
16Only what is actually visible.

Result: The docs/project.memory.md file.

14.6. Step 6 — First Prompt File

Goal: Create one working prompt for the most frequent task. No need for all five from the templates immediately — start with one and add as needed.

When to Use Which Prompt: If the team more often implements new features, use implement-from-spec. If they review PRs more often, use security-review. Choose what is used daily.

What to do (example for implement-from-spec):

1@.github/copilot-instructions.md
2
3Create the file .github/prompts/implement-from-spec.prompt.md
4for this project.
5
6Requirements:
7- mode: agent
8- tools: only search/codebase
9- steps should use build and test commands
10  from copilot-instructions.md
11- validation gates: build, tests, lint must pass
12- description — one line

Result: The .github/prompts/implement-from-spec.prompt.md file, adapted to the project's specific stack.

14.7. Outcome and What's Next

After these six steps, the repository will have:

1.github/
2  copilot-instructions.md          ← global rules (step 2)
3  instructions/
4    frontend.instructions.md       ← frontend rules (step 3)
5    backend.instructions.md        ← backend rules (step 3)
6  prompts/
7    implement-from-spec.prompt.md  ← first prompt (step 6)
8docs/
9  project.context.md               ← project references (step 4)
10  project.memory.md                ← decision memory (step 5)

This is a minimally functional set. Next, iterate:

• Add prompt files as new typical tasks arise.
• Update project.memory.md after each architectural decision.
• Add chat modes when you notice different work phases interfering with each other.
• Connect MCP only after the basic context is working.

Everything described above fits into one work session. Each prompt can be run sequentially without manually switching files — the agent will create the files in the working tree itself.

Resources

Custom Chat Modes in VS Code

Using MCP Servers in VS Code

Add Repository Instructions for GitHub Copilot

How to Build Reliable AI Workflows with Agentic Primitives and Context Engineering

🙌 PS:

Thanks for reading to the end! If you found this material useful, we'd be happy if you:

Technologies become more accessible when they are understood. And you've already taken the first important step 💪