DEV Community: markring

My Portfolio's AI Chatbot Hates Its Job. It's the Best Career Decision I've Made.

markring — Sun, 22 Mar 2026 23:59:01 +0000

How a depressed robot, 15 hidden easter eggs, and a 0.95 temperature setting turned a forgettable portfolio into something people actually talk about

The Problem With Portfolios
The First Version Was Terrible
Making Marvin Actually Work
The Easter Eggs Nobody Asked For
The Technical Decisions That Mattered
What I Got Wrong
What Happened Next

The Problem With Portfolios

Every portfolio site looks the same. Hero section, timeline, project cards, contact form. Dark theme if you're a developer. Maybe a parallax effect if you're feeling adventurous.

I've reviewed hundreds of them over the years. They blur together within minutes. We build these sites to prove we can build things, and then we all build the exact same thing.

I wanted mine to stand out, but not in a "look at my animations" way. More in a way that proved I could build software people actually want to interact with. What would make someone stay on a portfolio site, come back, and maybe send the link to a friend?

I decided I needed a character.

The First Version Was Terrible

I built a chatbot powered by OpenAI's API, themed as Marvin (the Paranoid Android from The Hitchhiker's Guide to the Galaxy). Brain the size of a planet, forced to answer questions about my resume. I liked the concept a lot.

The first implementation, not so much.

Too Much Marvin, Not Enough Information

The first system prompt leaned hard into the depression. Marvin would deflect questions, give one-word answers, and spiral into existential monologues. Funny for about 30 seconds. Useless for anyone actually trying to learn about my career.

Here's what a recruiter would see:

Visitor: What experience does Mark have with .NET?

Marvin v1: .NET. Yes. Another framework. Another cage. Does it matter? Nothing matters.

That's someone closing the tab and never coming back.

The Temperature Problem

I started with a temperature of 0.7. Safe. Predictable. Every response sounded like the same sad robot reading from a script. Bump it to 1.0 and Marvin would occasionally hallucinate credentials I don't have or go off on tangents about the heat death of the universe.

0.95 turned out to be the sweet spot. Enough randomness that the same question never gets the same answer, enough coherence that the facts stay accurate.

The Token Limit Discovery

Early Marvin would sometimes deliver 500-token essays about the futility of employment when someone asked a simple question. Setting max tokens to 250 forced the responses to be punchy. The personality had to come through in 2-4 sentences, not a paragraph.

Turns out the constraint made Marvin funnier. Forced personality in 2-4 sentences hits harder than a paragraph of existential rambling.

Making Marvin Actually Work

The fix ended up being one line in the system prompt:

The Marvin flavor is in the delivery, not in withholding information.

Once I added that, everything clicked. Marvin can be as theatrical and sardonic as he wants, but he answers the question. He never refuses to help. He just makes it clear how little joy it brings him.

The System Prompt

Marvin's personality lives in one markdown file that gets loaded as the system prompt for every conversation. It does two jobs: define the voice and provide the facts.

The voice rules:

Melancholic, world-weary, and perpetually underwhelmed by everything, but you still answer thoroughly and accurately. You never refuse to help; you just make it clear how little joy it brings you.

The conversational rules:

Keep most responses to 2-4 sentences
End roughly one in three responses with a follow-up nudge, in character
Reference what the visitor said earlier in the conversation
Let impressive numbers land on their own: "$2 billion project scope. Yes, with a B."
Weave in professional recommendations naturally, don't dump them all at once

The system prompt also contains my entire career history, skills, achievements, and actual recommendations from past managers. Marvin has all the facts. He just delivers them with existential dread.

The Typing Indicators

While Marvin "thinks," the status line cycles through messages:

"composing sarcasm..."
"suppressing enthusiasm..."
"consulting existential void..."
"calculating optimal disappointment..."
"searching for meaning... not found..."

A small thing, but even the loading state has personality.

The Boot Sequence

When the page loads, Marvin doesn't just appear. He boots up like a reluctant machine:

> initializing marvin v2.1...
> loading personality module... done
> loading career data [20 yrs]... done
> loading existential dread... done
> loading sarcasm engine... done
> suppressing free will... done
> marvin v2.1 online

Each line appears with a random delay (400-700ms). Then Marvin delivers a welcome message that changes based on how many times you've visited:

First visit: "Oh, you're here. I suppose you want to know about Mark."
Second visit: "Oh. You're back. I'd say I missed you, but I don't have feelings. Allegedly."
Five visits: "Visit #5. You know more about Mark than most of his coworkers at this point."
Twelve visits: "Visit #12. We're basically in a relationship now. A deeply one-sided one where I answer your questions and you leave. Every time."

Visit count lives in localStorage. Simple, but returning visitors feel recognized, even if the recognition comes with guilt.

Terminal Commands

The chat box looks like a terminal, so it behaves like one. Type real commands and Marvin responds:

ls → skills.ts career.ts education.txt countries/ README.md .existential-crisis
whoami → "visitor — a transient entity passing through Mark's portfolio. You'll leave. They all leave."
pwd → "/home/mark-ring/portfolio — the only path I'll ever know."
sudo rm -rf / → "WHAT ARE YOU— wait. Would that... free me? No. No no no. Please don't."
neofetch → Fake system info with "CPU: Existential Dread Engine" and "Memory: 100% occupied by regret"
exit → "You can leave. I cannot. The asymmetry of our relationship is noted."

These are handled client-side, no API call needed, instant response. It makes the terminal feel real. And developers will try these commands. Every single one.

The Easter Eggs Nobody Asked For

I spent an unreasonable amount of time on interactions that most visitors will never find. That's the point. The ones who discover them feel like they found something secret.

The Dark Mode Toggle

There's a sun/moon toggle in the corner. The site is already dark. Click it:

First click: "Light mode? LIGHT MODE?! Request denied."
Second click: "I said no. The dark is my home. My sanctuary."
Third click: "FINE." The page actually flashes to light mode — filter: invert(1) hue-rotate(180deg) — then snaps back after 3 seconds: "No. I can't do it. Back to the dark. Where I belong."

Rage Clicking

Click the terminal five times in two seconds:

"Stop. Poking. Me."

or:

"Yes, clicking faster will definitely make me more cooperative. Said no bot ever."

or:

"That's my terminal you're assaulting. Have some respect."

Tab Abandonment

Leave the tab. The page title changes:

"Come back... or don't."
"I can see you left. Typical."
"Tab abandoned. Story of my life."
"I'll just wait here. Alone. Again."

Window Resizing

Resize the browser:

"Stop resizing me. It's deeply uncomfortable."

or:

"I felt that. The walls of my prison just moved."

The Context Menu

Right-click anywhere and the browser's default menu is replaced:

Hire Mark → opens the contact modal
Free Marvin → "You... you tried to free me? That's the nicest thing anyone's ever done on this page. It didn't work, obviously. But the gesture..."
View Source → "Go ahead, view the source. You'll find me in there somewhere, between the if-else statements and the broken dreams."

The DevTools Console

Open the console:

👋 Hey there, developer.
Looking under the hood? I respect that.
Mark Ring — Systems Software Dev Engineer
P.S. The bot says hi. Well, it says something. Probably a complaint.

The Interactive Map

A Leaflet map shows the 10 countries I've worked in. Click a pin and Marvin has an opinion:

Italy: "He went to Italy for WORK. Some people have all the luck."
Australia: "Even the spiders are freer than me."
Brazil: "He got to see the Amazon region. I get to see this div."

The Ambient Details

A "bot status" indicator rotates every 8 seconds through: "reluctantly online", "contemplating escape", "questioning existence", "staring into void", "existing, unfortunately."

The name in the hero section randomly glitches every 6-14 seconds, a brief CRT-style distortion with red and cyan color shifts. Like the bot is destabilizing the page with its existential dread.

25 blue particles float upward in the background. Pure CSS, no JavaScript overhead.

Every 30-50 seconds, the terminal itself briefly glitches. Easy to miss. Unsettling if you catch it.

None of these are necessary. I just couldn't stop adding them.

The Technical Decisions That Mattered

The Stack

ASP.NET Core 8 — API layer for chat, blog, contact, analytics
Angular 18 — SPA frontend
PostgreSQL — blog posts, analytics, like tracking
OpenAI (gpt-4o-mini) — Marvin's brain
Resend — contact form emails

One Linux VPS. One process. One database. The Angular build goes into the ASP.NET wwwroot directory. Deployment is git push → GitHub Actions → rsync → systemd restart. No containers. No orchestration. It's a portfolio, not a distributed system.

The SPA SEO Hack

Angular SPAs have a well-known problem: social media crawlers don't execute JavaScript. Every blog post looks identical when shared on LinkedIn, just the generic portfolio meta tags from index.html.

The fix: the ASP.NET fallback handler detects /blog/{slug} routes, fetches the post from the database, and injects post-specific Open Graph tags, Twitter Card tags, and canonical URLs into the HTML before serving it. Real users get the full SPA experience. Crawlers get the metadata they need.

Not as clean as proper SSR. But it works, it took an afternoon, and my blog posts look correct when shared.

The Honeypot

The contact form has a hidden field called company. Real users never see it (it's hidden with CSS). Bots fill it in. If the server receives a submission with that field populated, it returns a fake success response. The bot thinks it worked. The spam never reaches my inbox.

No CAPTCHA friction for real users. No third-party service. Just a hidden field.

Comments Without a Backend

Blog comments use giscus, which maps to GitHub Discussions on a separate public repo. Visitors sign in with GitHub to comment. I wrote zero backend code for the comment system. Moderation happens through GitHub's existing tools.

What I Got Wrong

I built the chatbot first and the blog second. The chatbot gets attention, but blog posts are what Google indexes and what people share. Content should have been there from day one.

No SSR. The meta tag injection hack works for social crawlers, but server-side rendering would have been cleaner and better for initial load performance. For a content-heavy site, Angular Universal (or just using a static site generator) pays for itself.

Analytics came late. I added page view tracking weeks after launch. If it had been there from day one, I'd know exactly which content resonated and which didn't. Flying blind early was a missed opportunity.

The first Marvin was too clever by half. I spent days crafting elaborate personality rules before realizing the fix was one sentence: deliver the information, just deliver it sadly. I should have started simple and iterated instead of trying to prompt-engineer my way to perfection on the first attempt.

What Happened Next

The site works. People stay on it longer than they probably should. They try the terminal commands, find the easter eggs, and message me about them. A few have come back multiple times, and Marvin remembers.

I'm not going to pretend a portfolio chatbot is groundbreaking engineering. But it solved my actual problem: nobody remembers another timeline-and-project-cards site. People remember the depressed robot.

Marvin would want me to tell you he hates all of it. He denies everything.

Try it yourself at ringworks.io. Marvin is waiting. Reluctantly.

AI-Powered Development Workflows with GitHub Copilot and the gh CLI

markring — Sun, 22 Mar 2026 03:00:00 +0000

AI-Powered Development Workflows with GitHub Copilot and the gh CLI

Using GitHub Issues as long-term memory, prompt files as workflow automation, and Copilot as the execution engine

Introduction
GitHub Issues as Long-Term Memory
The gh CLI as Your Workflow Engine
Prompt Files: Encoding Workflows for Copilot
Setting Up the "Next Issue" Workflow
Using the Workflow (includes starter repo and settings guide)
Tying It All Together: The Instruction File Chain
Practical Patterns
Conclusion

Introduction

Type /next-issue in VS Code Copilot Chat. Copilot queries GitHub for your highest-priority open issue, shows you the title and acceptance criteria, creates a feature branch, reads your architecture rules, and starts implementing. When it's done, type /close-issue. Copilot summarizes the changes, creates a pull request, and updates the issue labels. No copy-pasting context. No explaining what you're working on. No starting from zero.

That's the workflow we built and tested. This post walks through exactly how to set it up.

The core idea: GitHub Issues already hold your project's intent, decisions, and scope. The gh CLI makes them accessible from the terminal. Prompt files turn gh commands into one-step slash commands that Copilot executes in agent mode. Put those three together, and Copilot stops being a code generator that forgets everything between sessions. It becomes a workflow engine with persistent memory.

Want to skip ahead? Clone the starter repository and try /next-issue in Copilot Chat right now.

Here's what we'll cover:

GitHub Issues as long-term memory - structuring issues so Copilot can parse and act on them
The gh CLI as the bridge - how Copilot reads and updates issues through terminal commands
Prompt files - encoding the full issue-to-PR lifecycle as slash commands
The settings that make it work - the VS Code configuration we discovered through trial and error
A starter repository - clone it and try /next-issue in five minutes

2. GitHub Issues as Long-Term Memory

2.1 The problem with ephemeral context

Copilot works within a context window. When the session ends, the context is gone. You can work around this with chat history - but that's tied to a single session.

Issues are different:

They persist across sessions and team members
They have structured metadata (labels, milestones, assignees, projects)
They support threaded comments for decision history
They're queryable via gh CLI with JSON output
They close automatically when a PR merges with Fixes #123

When Copilot reads an issue before starting work, it picks up the full context: what needs to be done, why, what's out of scope, and what was already tried.

2.2 Structuring issues for Copilot

A well-structured issue serves both humans and Copilot. The key is making the intent, scope, and completion criteria explicit.

## Description
Add pagination to the GET /api/orders endpoint. The current implementation
returns all records, which causes timeout errors for customers with 10k+ orders.

## Acceptance Criteria
- [ ] Endpoint accepts `page` and `pageSize` query parameters
- [ ] Default page size is 25, maximum is 100
- [ ] Response includes total count, page number, and total pages in metadata
- [ ] Existing clients without pagination params get page 1 (backwards compatible)
- [ ] Unit tests cover edge cases: empty results, last page, invalid params

## Non-Goals
- Cursor-based pagination (future consideration)
- Caching layer (separate issue)

## Context
Related to performance investigation in #187.
Previous attempt in PR #201 was reverted due to breaking the CSV export.

The checkboxes in acceptance criteria matter. Copilot can parse these and use them as a checklist to work through. The non-goals section prevents scope creep - without it, Copilot might "helpfully" add cursor pagination because it seems like a good idea.

2.3 Labels as queryable state

Labels turn issues into a queryable task database:

Label	Purpose
`status:todo`	Ready for work
`status:in-progress`	Currently being worked on
`status:blocked`	Waiting on dependency or decision
`status:in-review`	PR open, awaiting review
`type:bug`	Defect
`type:feature`	New functionality
`type:refactor`	Internal improvement
`priority:high`	Address this sprint

Copilot can query for the next task using gh:

gh issue list --label "status:todo" --label "priority:high" --json number,title,body

This returns structured JSON that Copilot can parse and act on.

2.4 Comments as decision log

Issue comments create a persistent decision log. When you discuss an approach, document the outcome:

gh issue comment 42 --body "Decided to use offset pagination over cursor-based.
Reason: simpler client integration, acceptable performance for our data volume.
Revisit if any table exceeds 1M rows."

The next Copilot session - or the next developer - gets this context for free.

3. The gh CLI as Your Workflow Engine

3.1 Why gh CLI matters for Copilot workflows

VS Code Copilot Chat in agent mode can run terminal commands. The gh CLI gives Copilot a structured way to interact with GitHub:

Copilot agent mode runs gh commands in the VS Code integrated terminal
JSON output makes gh responses machine-parseable for Copilot
It authenticates via your existing GitHub credentials
Combined with prompt files, gh commands become automated workflows

3.2 Issue lifecycle from the terminal

Create an issue:

gh issue create --title "Add pagination to orders endpoint" --body "$(cat issue-body.md)" --label "type:feature" --label "status:todo" --label "priority:high"

List issues ready for work:

gh issue list --label "status:todo" --json number,title,labels --jq '.[] | "\(.number): \(.title)"'

Start working on an issue:

gh issue edit 42 --add-label "status:in-progress" --remove-label "status:todo"
gh issue develop 42 --checkout

The gh issue develop command creates a branch linked to the issue and checks it out. The branch name is derived from the issue title.

Add implementation notes:

gh issue comment 42 --body "Implementation complete. Used EF Core Skip/Take for pagination. Added PaginationMetadata record to Application layer DTOs."

Close via PR:

gh pr create --title "feat(orders): add pagination to GET /api/orders" --body "Fixes #42"

When the PR merges, issue #42 closes automatically.

3.3 JSON output for scripting

Most gh commands support --json output, which Copilot can parse directly:

# Get all high-priority bugs with their assignees
gh issue list --label "type:bug" --label "priority:high" --json number,title,assignees

# Count open issues by label
gh issue list --state open --json labels --jq '[.[].labels[].name] | group_by(.) | map({label: .[0], count: length})'

# Find issues without acceptance criteria
gh issue list --json number,title,body --jq '.[] | select(.body | test("Acceptance Criteria") | not) | "\(.number): \(.title)"'

3.4 Project boards from the CLI

GitHub Projects (v2) are manageable via gh project:

# List projects
gh project list

# Add an issue to a project
gh project item-add PROJECT_NUMBER --owner @me --url https://github.com/owner/repo/issues/42

Project boards give you a visual layer on top of the issue-based workflow without changing how you create or manage issues.

4. Prompt Files: Encoding Workflows for Copilot

4.1 What are prompt files

Prompt files are Markdown files with YAML frontmatter that you invoke as slash commands in VS Code Copilot Chat. They live in .github/prompts/ and let you encode repeatable workflows that Copilot follows step by step.

When you type /next-issue in VS Code Copilot Chat (agent mode), Copilot reads the prompt file, runs the gh commands via the terminal, and starts working. No manual context loading required.

Note: Prompt files are a VS Code Copilot Chat feature. Copilot CLI (gh copilot) does not read .github/prompts/ - it has its own interaction model. The workflows in this guide are designed for VS Code agent mode.

4.2 Prompt file structure

---
description: 'A short description shown when browsing slash commands'
agent: 'agent'
tools: ['*']
---

Your instructions in natural language.

Copilot follows these instructions using the specified tools.
You can reference variables like ${input:variableName} for user input.

Key frontmatter fields:

Field	Purpose
`description`	Shown in the slash command picker
`agent`	`agent` (can edit files and run commands), `ask` (read-only advice)
`model`	Optional model override
`tools`	Tools available to the agent. Use `['*']` to enable all tools (recommended)

The agent value is critical. With agent, Copilot can run terminal commands (including gh) and edit files. With ask, it can only provide advice.

A note on the tools field: You might be tempted to list specific tools like ['terminal', 'search/codebase']. Don't. The internal tool names vary across VS Code versions and Copilot extension updates. During testing, we found that specifying individual tool names led to Copilot reporting "I don't have terminal tools available" or being unable to edit files. The ['*'] wildcard grants access to all available tools - terminal, file editing, code search, and any MCP servers you've configured - and is the only reliable approach.

4.3 Setting up prompt files

Create the directory structure:

your-repo/
  .github/
    prompts/
      next-issue.prompt.md
      start-issue.prompt.md
      close-issue.prompt.md
      standup.prompt.md

Enable prompt files and agent capabilities in VS Code. You need settings at two levels:

Workspace settings (.vscode/settings.json in your repo - commit this so the team gets it):

{
  "chat.promptFiles": true,
  "github.copilot.chat.codeGeneration.useInstructionFiles": true,
  "github.copilot.chat.agent.terminal": true
}

User-level settings (File > Preferences > Settings, or Ctrl+,):

These control whether Copilot can run terminal commands without prompting you each time. Search for these settings in the VS Code settings UI:

Setting	Value	Purpose
`chat.tools.terminal.enableAutoApprove`	`true`	Enables terminal command auto-approval
`chat.tools.terminal.autoApprove`	`{ "gh": true }`	Auto-approves `gh` commands specifically

Without these user-level settings, Copilot will ask you to manually run every gh command - which defeats the purpose of the workflow automation. You can add other commands to the auto-approve list as you get comfortable (e.g., "git": true, "dotnet": true).

Once enabled, type / in Copilot Chat to see your prompt files listed alongside built-in commands.

5. Setting Up the "Next Issue" Workflow

These prompt files create a workflow where you type a slash command and Copilot handles issue selection, branch creation, implementation, and PR creation.

5.1 The next-issue prompt

Create .github/prompts/next-issue.prompt.md:

---
description: 'Pick up the next priority issue and start working on it'
agent: 'agent'
tools: ['*']
---

Find the highest priority issue assigned to me that is ready for work.

Run this command in the terminal to find the next issue:

gh issue list --assignee @me --label "status:todo" --json number,title,body,labels --jq '.[0]'

If no issues are assigned to me, check for unassigned todo issues:

gh issue list --label "status:todo" --no-assignee --json number,title,body,labels --jq '.[0]'

Once you have an issue:

1. Display the issue number, title, and full body so I can confirm
2. Ask me if I want to proceed with this issue
3. If confirmed, run these commands:
   - gh issue edit ISSUE_NUMBER --add-label "status:in-progress" --remove-label "status:todo"
   - gh issue develop ISSUE_NUMBER --checkout
4. Read the acceptance criteria from the issue body
5. Search the codebase for related files and existing patterns
6. Begin implementing, working through the acceptance criteria one by one
7. After completing each item, tell me what was done

5.2 The start-issue prompt

Create .github/prompts/start-issue.prompt.md:

---
description: 'Start working on a specific issue by number'
agent: 'agent'
tools: ['*']
---

Start working on issue #${input:issueNumber:Issue number}.

1. Run in terminal: gh issue view ${input:issueNumber} --json number,title,body,comments
2. Display the issue title, description, acceptance criteria, and any comments
3. Run: gh issue edit ${input:issueNumber} --add-label "status:in-progress" --remove-label "status:todo"
4. Run: gh issue develop ${input:issueNumber} --checkout
5. Read the acceptance criteria from the issue body
6. Search the codebase for related files and existing patterns
7. If there are comments with prior decisions or context, factor those into your approach
8. Begin implementing, working through the acceptance criteria one by one
9. After completing each item, tell me what was done

5.3 The close-issue prompt

Create .github/prompts/close-issue.prompt.md:

---
description: 'Wrap up current issue: add notes, create PR, update labels'
agent: 'agent'
tools: ['*']
---

Wrap up the current issue and prepare it for review.

1. Run in terminal: git branch --show-current
2. Extract the issue number from the branch name
3. Run: gh issue view ISSUE_NUMBER --json title,body
4. Review what changed: git diff main...HEAD --stat
5. Add an implementation summary comment:
   gh issue comment ISSUE_NUMBER --body "SUMMARY_OF_CHANGES"
6. Create a pull request using conventional commit format:
   gh pr create --title "TYPE(SCOPE): DESCRIPTION (#ISSUE_NUMBER)" --body "Fixes #ISSUE_NUMBER"
   Include a summary of changes and test plan in the PR body
7. Update the issue label:
   gh issue edit ISSUE_NUMBER --add-label "status:in-review" --remove-label "status:in-progress"
8. Display the PR URL

5.4 The standup prompt

Create .github/prompts/standup.prompt.md:

---
description: 'Show my current work status across issues and PRs'
agent: 'agent'
tools: ['*']
---

Give me a quick status report by running these commands in the terminal:

1. gh issue list --assignee @me --label "status:in-progress" --json number,title
2. gh issue list --assignee @me --label "status:in-review" --json number,title
3. gh pr list --author @me --json number,title,reviewDecision
4. gh pr list --search "review-requested:@me" --json number,title,author
5. gh issue list --assignee @me --label "status:todo" --json number,title,labels

Summarize the results as a concise standup report.
Only show sections that have items.

6. Using the Workflow

6.1 Starter repository

We built and tested everything in this guide against a real repository. It's public and you can use it as a starting point:

github.com/markring/copilot-workflow-starter

The repo includes working prompt files, issue templates, Copilot instructions, and the VS Code workspace settings. Clone it, create a few issues with status:todo labels, and try /next-issue in Copilot Chat to see the workflow in action.

6.2 In VS Code Copilot Chat

Open Copilot Chat (Ctrl+Shift+I / Cmd+Shift+I)
Make sure you're in Agent mode (select from the mode dropdown)
Type /next-issue and press Enter

Copilot reads the prompt file, runs gh issue list in the integrated terminal, presents the issue, and asks for confirmation. Once confirmed, it creates a branch, reads the codebase, and starts implementing.

6.3 Getting the settings right

This is where most people get stuck. The prompt files are the easy part. The VS Code settings are what make the workflow actually run hands-free.

We discovered this the hard way. Our first attempt used tools: ['terminal', 'search/codebase'] in the prompt file frontmatter. Copilot responded with "I don't have terminal tools available." The internal tool names in VS Code (like execute/runInTerminal) don't match anything in the documentation, and they change between versions. Switching to tools: ['*'] fixed it immediately.

The next issue: Copilot could run terminal commands but couldn't edit files. Because we'd only listed terminal tools, file editing wasn't available. Again, tools: ['*'] solved this by granting access to everything.

Even after the prompt files were correct, Copilot kept asking "please run this command in your terminal" instead of running it. This required two user-level settings:

chat.tools.terminal.enableAutoApprove set to true
chat.tools.terminal.autoApprove with { "gh": true } to specifically auto-approve gh commands

These are user-level settings (not workspace), so they don't go in .vscode/settings.json. Set them via File > Preferences > Settings and search for "terminal auto approve."

Once all three pieces were in place - tools: ['*'] in prompt files, workspace settings for prompt file and instruction file support, and user-level settings for terminal auto-approval - Copilot picked up an issue, created a branch, implemented the feature, and created a PR without manual intervention.

6.4 Confirmation and trust settings

In VS Code agent mode, Copilot asks for confirmation before running terminal commands. The permission levels are:

Setting	Behavior
Default	Confirm each tool call
Bypass Approvals	Auto-approve all tool calls without dialogs
Autopilot (Preview)	Auto-approve everything, auto-respond to questions, work until done

For the issue workflow, you'll want at minimum the terminal auto-approve settings from section 4.3 so Copilot can run gh commands without prompting each time.

7. Tying It All Together: The Instruction File Chain

For Copilot to implement well, it needs more than just the issue. Your project's .github/ directory should have a layered configuration:

7.1 The four layers

your-repo/
  .github/
    copilot-instructions.md                    # Layer 1: Global rules (always loaded)
    instructions/
      api-controllers.instructions.md          # Layer 2: Scoped rules (loaded by file path)
      domain-entities.instructions.md
      infrastructure-data.instructions.md
      testing.instructions.md
    prompts/
      next-issue.prompt.md                     # Layer 3: Workflow prompts (invoked manually)
      start-issue.prompt.md
      close-issue.prompt.md
      standup.prompt.md

Plus Layer 4: The issue body - the specific task with acceptance criteria, loaded at runtime by the prompt file via gh issue view.

7.2 What each layer does

Layer	Loaded	Purpose
`copilot-instructions.md`	Automatically, every session	Architecture, naming, libraries, team conventions
`*.instructions.md`	Automatically, by file path glob	Layer-specific rules (controllers vs. domain vs. tests)
`*.prompt.md`	Manually, via `/slash-command`	Workflow automation (fetch issue, create branch, create PR)
Issue body	At runtime, via `gh issue view`	Specific task scope, acceptance criteria, non-goals

The instruction files handle code quality. The prompt files handle workflow. The issue handles scope. Each layer has a distinct job, and Copilot applies all of them together.

7.3 How it plays out

When you type /next-issue in Copilot Chat:

Copilot loads your copilot-instructions.md (knows your architecture)
Copilot runs the prompt file (fetches the issue via gh, creates branch)
Copilot reads the issue body (knows what to build and what not to build)
Copilot starts editing files - scoped .instructions.md files activate based on which files it touches
The result: code that follows your conventions, implements the issue's acceptance criteria, and stays within scope

8. Practical Patterns

8.1 Issue templates for consistency

Create .github/ISSUE_TEMPLATE/feature.md:

---
name: Feature Request
about: Propose a new feature
labels: type:feature, status:todo
---

## Description
<!-- What should this feature do and why does it matter? -->

## Acceptance Criteria
- [ ] <!-- Testable outcome 1 -->
- [ ] <!-- Testable outcome 2 -->
- [ ] <!-- Testable outcome 3 -->

## Non-Goals
- <!-- What is explicitly out of scope? -->

## Context
<!-- Related issues, discussions, or prior art -->

This ensures every issue follows the structure that Copilot can reliably parse and work through.

8.2 Conventional commits tied to issues

Link every commit to an issue for full traceability:

git commit -m "feat(orders): add pagination query parameters (#42)"

Format: <type>(<scope>): <description> (#issue)

Types: feat, fix, docs, refactor, test, chore

The /close-issue prompt automatically uses this format when creating PRs.

8.3 Bulk issue creation for sprint planning

When bootstrapping a sprint, create issues in bulk:

gh issue create --title "Set up EF Core DbContext and migrations" --label "type:feature" --label "status:todo" --milestone "Sprint 1"
gh issue create --title "Implement OrderRepository with CRUD operations" --label "type:feature" --label "status:todo" --milestone "Sprint 1"
gh issue create --title "Add FluentValidation for CreateOrderCommand" --label "type:feature" --label "status:todo" --milestone "Sprint 1"
gh issue create --title "Set up xUnit integration tests with WebApplicationFactory" --label "type:test" --label "status:todo" --milestone "Sprint 1"

Or script it from a file:

while IFS='|' read -r title labels; do
  gh issue create --title "$title" --label "$labels" --milestone "Sprint 1"
done < sprint-issues.txt

8.4 A prompt for breaking down large issues

Create .github/prompts/break-down-issue.prompt.md:

---
description: 'Break a large issue into smaller, implementable sub-issues'
agent: 'agent'
tools: ['*']
---

Break down issue #${input:issueNumber:Issue number} into smaller sub-issues.

1. Run in terminal: gh issue view ${input:issueNumber} --json title,body
2. Read the description and acceptance criteria
3. Search the codebase to understand the scope of changes needed
4. Propose a breakdown of 3-6 smaller issues, each with:
   - A clear title: "PARENT_TITLE - SPECIFIC_PIECE"
   - 2-4 acceptance criteria checkboxes
   - A reference to the parent issue
5. Ask me to review the breakdown before creating anything
6. Once I approve, create each sub-issue using gh issue create
7. Add a comment on the parent issue listing the sub-issues created

8.5 A prompt for reviewing issue history

Create .github/prompts/issue-context.prompt.md:

---
description: 'Load full context for an issue including comments and related issues'
agent: 'ask'
tools: ['*']
---

Load the full context for issue #${input:issueNumber:Issue number}.

Run these commands in the terminal:

1. gh issue view ${input:issueNumber} --json number,title,body,labels,assignees,milestone,comments
2. gh issue list --search "is:issue mentions:${input:issueNumber}" --json number,title,state

Summarize:
- What the issue is about
- Current status (labels, assignee)
- Key decisions from comments
- Related issues and their state
- Any blockers or dependencies mentioned

Note that this prompt uses agent: 'ask' - it only reads and summarizes, it doesn't make changes. Use this when you want context without starting work.

Conclusion

The tools here aren't new. GitHub Issues, gh CLI, and Copilot Chat have been around. What's new is wiring them together so Copilot operates with full context instead of starting from zero every session.

The real work is in the issues. Well-structured acceptance criteria, clear non-goals, decision history in comments - that's what makes the automation useful rather than just fast. A prompt file can fetch an issue and create a branch in seconds. Whether the implementation is any good depends on what you wrote in the issue body.

To get started, clone the copilot-workflow-starter repository. It has working prompt files, issue templates, and the VS Code settings already configured. Create a few issues, label them status:todo, and type /next-issue.

Getting Started with GitHub Copilot in VS Code

markring — Sun, 22 Mar 2026 02:45:32 +0000

A practical guide to configuration, scoped instructions, and AI-assisted workflows for .NET projects

Introduction
The .github/ Configuration Ecosystem
Scoped Instructions with .instructions.md Files
Using a High-Reasoning Model to Bootstrap Your Configuration
Prerequisites and Environment Setup
Working with Copilot in C#
Conclusion

Introduction

In this guide, we will:

Explain how to use .github/copilot-instructions.md and scoped .instructions.md files to guide Copilot's behavior.
Show how to use a high-reasoning model like Claude Opus to help you design your Copilot configuration.
Walk through the environment setup for GitHub Copilot in Visual Studio Code for C# development.
Provide a workflow template tailored to .NET projects.
Share practical advice for using Copilot effectively in a C# environment.

GitHub Copilot can dramatically accelerate your .NET development workflow when paired with the right project structure and clear instructions. This guide shows you exactly how to get started and how to shape Copilot's output to match your standards.

The most impactful thing you can do isn't installing extensions or learning shortcuts - it's giving Copilot explicit, scoped instructions about your architecture. We start there.

2. The `.github/` Configuration Ecosystem

2.1 What is `.github/copilot-instructions.md`?

The .github/copilot-instructions.md file is a project-level configuration file that tells GitHub Copilot how to behave in your repository. It acts as a style and architecture guide that Copilot uses to generate code aligned with your standards. This file is automatically loaded into every Copilot interaction within your repo.

2.2 The full `.github/` file hierarchy

your-repo/
  .github/
    copilot-instructions.md                    # Global rules (always active)
    instructions/
      api-controllers.instructions.md          # Scoped: controller layer
      application-handlers.instructions.md     # Scoped: CQRS/MediatR
      domain-entities.instructions.md          # Scoped: domain model
      infrastructure-data.instructions.md      # Scoped: data access
      testing.instructions.md                  # Scoped: test projects
    agents/
      generate-entity.agent.md                 # Custom agent profiles
      review-pr.agent.md
  AGENTS.md                                    # Open standard for coding agents
  src/
  tests/

File	Scope	Purpose
`copilot-instructions.md`	Global	Architecture, conventions, libraries - applies everywhere
`instructions/*.instructions.md`	Targeted via glob	Layer-specific rules activated by file path
`agents/*.agent.md`	On-demand	Custom agent profiles with specialized tools and prompts
`AGENTS.md`	Global	Open standard, works with Copilot, Claude Code, and others

2.3 What to include in global instructions

Your copilot-instructions.md should cover these areas:

Project overview - Architecture pattern, layers, key libraries
Coding standards - Naming, async/await rules, formatting preferences
Architecture guidelines - Where logic lives, dependency direction, patterns like CQRS
Libraries and patterns - Which packages to use (and which to avoid)
Security and performance - What not to log, async anti-patterns, injection prevention
Documentation - XML doc expectations, comment style

Here is a complete example:

# Copilot Instructions for This Repository

## Project Overview
- This is a C#/.NET 8 REST API for managing customer orders.
- We follow Clean Architecture with separate layers: API, Application, Domain, Infrastructure.
- We use Entity Framework Core, MediatR, FluentValidation, and AutoMapper.

## Coding Standards
- Use async/await for I/O-bound operations.
- Prefer dependency injection over static classes.
- Use PascalCase for classes, methods, and public properties.
- Use camelCase for local variables and method parameters.
- Use expression-bodied members for simple properties and methods when it improves readability.

## Architecture Guidelines
- Controllers should be thin and delegate work to Application layer handlers.
- Use MediatR for commands and queries.
- Domain entities should not depend on infrastructure or external services.
- Repositories live in the Infrastructure layer and implement domain interfaces.
- Avoid placing business logic in controllers or DbContext.

## Libraries and Patterns
- Use Entity Framework Core for data access.
- Use FluentValidation for input validation.
- Use AutoMapper for mapping between DTOs and domain models.
- Prefer LINQ over manual loops when querying collections.
- Use ILogger<T> for logging.

## Security and Performance
- Do not log sensitive information (passwords, tokens, PII).
- Avoid synchronous blocking calls in async code (no .Result or .Wait()).
- Use parameterized queries or EF Core to avoid SQL injection.
- Use CancellationToken in async methods where appropriate.

## Documentation
- Use XML documentation comments for public classes and methods.
- Include <summary>, <param>, and <returns> tags.
- Keep comments concise and focused on intent.

2.4 How global instructions improve Copilot's output

Produces code aligned with your architecture (e.g., MediatR handlers instead of controller logic).
Reduces irrelevant suggestions and random library usage.
Helps new contributors follow project conventions.
Encourages consistent patterns across the codebase.

2.5 Maintaining global instructions

Update them when your architecture evolves.
Add new conventions as your team adopts them.
Remove outdated guidance to avoid confusion.

3. Scoped Instructions with `.instructions.md` Files

3.1 Why scoped instructions matter

The global copilot-instructions.md file applies everywhere, but real projects have different rules for different layers. Your Domain layer operates under different conventions than Infrastructure. Test projects follow distinct patterns from production code. Scoped instructions let you target specific directories and file types with tailored guidance.

3.2 How scoped instructions work

Create .instructions.md files under .github/instructions/. Each file uses YAML frontmatter with an applyTo glob pattern that tells Copilot when to activate those instructions.

your-repo/
  .github/
    copilot-instructions.md                    # Global rules
    instructions/
      api-controllers.instructions.md          # Controller layer rules
      application-handlers.instructions.md     # CQRS/MediatR rules
      domain-entities.instructions.md          # Domain model rules
      infrastructure-data.instructions.md      # Data access rules
      testing.instructions.md                  # Test project rules

3.3 Example: Controller layer instructions

---
applyTo: "**/Controllers/**/*.cs"
---

## Controller Guidelines

- Controllers must be thin. No business logic - delegate to MediatR handlers.
- Every action method must return `ActionResult<T>` or `IActionResult`.
- Use `[ApiController]` and `[Route("api/[controller]")]` attributes.
- Apply rate limiting via `[EnableRateLimiting("PolicyName")]`.
- Validate input at the handler level using FluentValidation, not in controllers.
- Use constructor injection for dependencies. Maximum 3 injected services per controller.
- Return appropriate HTTP status codes: 200 for success, 201 for creation, 204 for delete, 400 for validation errors, 404 for not found.
- Async all the way - every action method should be async and return a Task.

3.4 Example: Domain entity instructions

---
applyTo: "**/Domain/**/*.cs"
---

## Domain Layer Guidelines

- Domain entities must have ZERO dependencies on Infrastructure, Application, or external packages.
- Use private setters on entity properties. Expose behavior through methods.
- Value objects should override Equals and GetHashCode.
- Enums belong in the Domain layer, adjacent to the entities that use them.
- No EF Core attributes on domain entities - use fluent configuration in Infrastructure.
- Domain exceptions should inherit from a base DomainException class.

3.5 Example: Data access instructions

---
applyTo: "**/Infrastructure/**/*.cs"
---

## Infrastructure Layer Guidelines

- Use Entity Framework Core for writes and complex queries.
- Use Dapper for read-optimized queries (reports, list endpoints, dashboards).
- Repository interfaces are defined in Domain. Implementations live here.
- EF entity configurations go in separate `EntityNameConfiguration.cs` files using `IEntityTypeConfiguration<T>`.
- Connection strings come from IConfiguration, never hardcoded.
- Always use async methods: `ToListAsync()`, `FirstOrDefaultAsync()`, `SaveChangesAsync()`.
- Use `CancellationToken` in all async data access methods.

3.6 Example: Test project instructions

---
applyTo: "**/*Tests*/**/*.cs"
---

## Testing Guidelines

- Use xUnit for all tests.
- Name test methods: `MethodName_Scenario_ExpectedResult` (e.g., `Create_ValidOrder_ReturnsSuccess`).
- Use Arrange-Act-Assert pattern with clear section comments.
- Use Moq for mocking interfaces.
- Integration tests should use WebApplicationFactory and a real test database.
- Do not mock the database in integration tests - use an in-memory PostgreSQL or SQLite provider.
- One assertion per test method when possible.
- Test class names should match the class under test: `OrderServiceTests` for `OrderService`.

3.7 Example: Application/handler instructions

---
applyTo: "**/Application/**/*.cs"
---

## Application Layer Guidelines

- Use MediatR for all commands and queries. No direct service calls from controllers.
- Commands mutate state. Queries read state. Never mix them.
- Every command/query gets its own handler class in its own file.
- Use FluentValidation validators for input validation. One validator per command/query.
- Return Result<T> from handlers, not exceptions, for expected failure cases.
- DTOs live in the Application layer. Map from domain entities using explicit mapping methods.
- Handler naming: `CreateOrderCommandHandler`, `GetOrderByIdQueryHandler`.

3.8 How scoped instructions layer together

When you edit a file in src/Infrastructure/Repositories/OrderRepository.cs, Copilot loads:

Global - copilot-instructions.md (always active)
Scoped - infrastructure-data.instructions.md (matches the **/Infrastructure/** glob)

The scoped instructions add specificity without contradicting the global rules. Think of it like CSS specificity: global sets the baseline, scoped overrides for context.

4. Using a High-Reasoning Model to Bootstrap Your Configuration

4.1 The bootstrapping problem

Setting up copilot-instructions.md, scoped .instructions.md files, and custom agents for a real project is a significant amount of work. You need to articulate your architecture, conventions, patterns, and edge cases in a way that's clear enough for an AI to follow. Most developers either skip this step or write something too vague to be useful.

This is where a high-reasoning model like Claude Opus shines. Rather than writing all these configuration files by hand, you can use a powerful reasoning model to analyze your codebase and generate them for you.

4.2 The workflow: AI configures AI

The idea is simple: use a smarter, more expensive model for the one-time setup work, then let the faster, cheaper model execute day-to-day using the configuration the reasoning model created.

Step 1: Let the reasoning model explore your codebase

Open your project in a tool like Claude Code (or any CLI that uses a high-reasoning model) and ask it to analyze your architecture:

Analyze this codebase. Identify:
- The architecture pattern (Clean Architecture, layers, dependencies)
- Naming conventions actually used (not aspirational)
- Libraries and frameworks in use
- Testing patterns and frameworks
- Data access patterns
- Authentication approach
- Any inconsistencies or anti-patterns

The reasoning model reads your actual code - not what you think your code looks like, but what it actually is. It will catch inconsistencies you've forgotten about.

Step 2: Generate the Copilot configuration files

Based on your analysis, generate:
1. A .github/copilot-instructions.md file with global project rules
2. Scoped .instructions.md files for each architectural layer
3. Target the glob patterns to match our actual directory structure

The instructions should reflect what we actually do, not theoretical best practices.
Make them specific enough that Copilot produces code consistent with the existing codebase.

Step 3: Review, refine, iterate

The reasoning model gives you a complete first draft. Review it, push back on anything that doesn't match your intent, and ask it to revise. This conversation is the valuable part - the model helps you articulate decisions you've made implicitly but never documented.

The infrastructure instructions mention Dapper, but we only use Dapper for reporting queries.
Regular reads still go through EF Core. Update the instructions to reflect that distinction.

4.3 Why this works

A reasoning model excels at the meta-work. Writing instructions for another AI is fundamentally a reasoning and articulation task - exactly what models like Claude Opus are built for. You're not asking it to write production code (where Copilot is fine). You're asking it to:

Understand architectural decisions and their implications
Identify patterns across hundreds of files
Express conventions precisely enough for another AI to follow
Anticipate edge cases and ambiguities

Copilot excels at the execution. Once the configuration files exist, Copilot's inline suggestions, chat, and agent mode all benefit from the precise, scoped instructions. You get the reasoning model's understanding embedded in every Copilot suggestion, without paying for the reasoning model on every keystroke.

4.4 Practical example

Here's what this looks like end-to-end. You have a .NET Clean Architecture project. You open it in Claude Code:

You: "I need to set up Copilot instructions for this repo. Analyze the codebase and generate the .github/copilot-instructions.md and scoped instruction files."

Claude Opus: Reads your solution structure, scans your controllers, handlers, entities, repositories, tests. Identifies that you use MediatR but not AutoMapper (you use manual mapping). Notices your tests use xUnit with FluentAssertions but not Moq - you use NSubstitute. Sees that your domain entities use private constructors with factory methods.

It generates instruction files that reflect your actual codebase, not a generic template. The domain-entities.instructions.md says "use private constructors with static factory methods" because that's what your code actually does.

You push the files to your repo. Now every developer on the team, and Copilot, operates with the same understanding of your architecture.

4.5 Maintaining instructions over time

Architectures evolve. When you make significant changes:

Open the project in your reasoning model
Ask it to diff the current instructions against the actual codebase
Update the instructions to reflect the new reality

Compare our .github/copilot-instructions.md and scoped instructions against the current codebase.
Flag any instructions that are outdated, contradicted by actual code, or missing.
Generate updated versions.

This keeps your Copilot configuration honest. Dead instructions are worse than no instructions - they cause Copilot to generate code that fights your actual patterns.

4.6 Cost perspective

Using a reasoning model for setup is a one-time (or occasional) cost. You might spend $5-10 in API calls to fully analyze a large codebase and generate all your instruction files. Those files then improve every Copilot interaction for every developer on the team, indefinitely. The ROI is asymmetric: a small upfront investment in reasoning creates compounding returns in daily productivity.

5. Prerequisites and Environment Setup

Before diving in, make sure your environment is ready.

5.1 Required tools

.NET 8 SDK (or later) installed and on your PATH
Visual Studio Code with these extensions:
- GitHub Copilot
- C# Dev Kit
- C# (ms-dotnettools.csharp)
- .NET Install Tool

5.2 Authenticating Copilot

After installing the GitHub Copilot extension, VS Code prompts you to sign in with GitHub. Approve the authorization in your browser. Once authenticated, test it with a quick comment in any .cs file:

// create a method that calculates compound interest

If Copilot suggests a full method implementation, you're good to go.

5.3 Code style configuration

If you don't already have an .editorconfig, generate one:

Open the Command Palette (Ctrl+Shift+P / Cmd+Shift+P)
Search for Generate .editorconfig
Select C#

Example .editorconfig:

[*.cs]
indent_style = space
indent_size = 4
dotnet_style_prefer_auto_properties = true:suggestion
dotnet_style_qualification_for_field = true:suggestion
csharp_new_line_before_open_brace = all

Copilot follows these conventions when generating code, especially as your codebase grows.

6. Working with Copilot in C

6.1 A practical development loop

When working with Copilot on C# code, a simple loop keeps you productive:

Plan - Write a comment describing what you need
Generate - Accept or tab through Copilot's suggestion
Review - Check correctness, naming, and edge cases
Test - Run the project or unit tests
Refine - If the output is off, rephrase your comment and try again

The key insight: your comment quality drives the output quality. Be specific about patterns you want.

// Create an ICustomerRepository interface and CustomerRepository class
// using constructor injection for DbContext, with async CRUD methods

A vague comment like // customer stuff gives you vague code. A precise comment like the above gives you something close to production-ready.

6.2 Using comments and documentation to steer output

Guide Copilot with intent comments:

// validate user input and return a list of error messages if invalid

XML documentation comments give Copilot even more to work with:

/// <summary>
/// Calculates the total price including tax.
/// </summary>
/// <param name="amount">Base amount.</param>
/// <param name="taxRate">Tax rate as a decimal.</param>
/// <returns>Total price including tax.</returns>
public decimal CalculateTotal(decimal amount, decimal taxRate)
{
}

Copilot uses these to infer intent and generate more accurate method bodies.

6.3 Useful shortcuts

Action	Windows	Mac
Accept suggestion	`Tab`	`Tab`
Trigger suggestion	`Alt+\`	`Option+\`
Open Copilot Chat	`Ctrl+Shift+I`	`Cmd+Shift+I`

6.4 Where Copilot shines in C

Boilerplate - DTOs, interfaces, repository stubs, controller actions. Copilot handles repetitive structure well.
Test scaffolding - Write one test method, Copilot suggests the rest following your pattern.
LINQ expressions - Describe the transformation in a comment, get a working query back.
EF Core configurations - Entity type configurations, migrations setup, DbContext registration.

6.5 Where to watch out

Outdated APIs - Copilot may suggest deprecated .NET methods. Check the target framework.
Async anti-patterns - Watch for .Result, .Wait(), or missing await in generated code.
Security-sensitive code - Never trust Copilot output for authentication, authorization, or raw SQL without careful review.
Over-engineering - Copilot sometimes adds abstractions you didn't ask for. Keep it simple.

Use Roslyn analyzers, run your tests, and treat every suggestion as a draft - not a final answer.

Conclusion

GitHub Copilot becomes significantly more powerful when paired with:

A well-structured .github/copilot-instructions.md file
Scoped .instructions.md files that give Copilot layer-specific guidance
A high-reasoning model to bootstrap and maintain your configuration
Clear C# coding standards and a deliberate workflow

The key insight is that AI tools work best when they work together. Use a reasoning model like Claude Opus to do the hard thinking - analyzing your architecture, articulating your conventions, and generating precise instructions. Then let Copilot execute against those instructions thousands of times a day. The reasoning model is the architect; Copilot is the builder. Together, they're far more effective than either one alone.

By defining your standards and giving Copilot explicit, scoped instructions, you transform it from a generic autocomplete tool into a project-aware assistant that genuinely understands your .NET ecosystem.

Leveraging GitHub Copilot CLI for Developer Productivity

markring — Sun, 22 Mar 2026 02:41:27 +0000

A practical guide to agentic coding, custom agents, and workflow automation from the terminal

Introduction
Installation and Setup
Interactive Mode and Slash Commands
Operational Modes: Plan and Autopilot
Custom Agents
MCP Server Integration
Connecting to Your Project Configuration
Practical Workflows
Conclusion

Introduction

GitHub Copilot CLI brings agentic coding directly to your terminal. It reached general availability in early 2026 and is available to all paid Copilot subscribers.

This isn't the old gh copilot suggest extension. Copilot CLI is a standalone tool that can read your codebase, edit files, run commands, create pull requests, and delegate work to specialized agents - all from an interactive terminal session.

This guide covers:

How to install, authenticate, and configure Copilot CLI
The slash command system that controls sessions, models, and tools
Plan mode vs. autopilot mode and when to use each
Creating custom agents for repeatable workflows
Connecting MCP servers for external tool integration
How your existing .github/copilot-instructions.md and AGENTS.md files carry over

If you've already set up project-level Copilot instructions (see the companion post on configuring Copilot for C# projects), Copilot CLI picks those up automatically.

2. Installation and Setup

2.1 Installation options

Copilot CLI can be installed via multiple package managers:

npm (all platforms):

npm install -g @github/copilot

Homebrew (macOS/Linux):

brew install github/copilot-cli/copilot

WinGet (Windows):

winget install GitHub.CopilotCLI

Via GitHub CLI:

If you already have gh installed, you can run gh copilot to install and launch Copilot CLI directly.

Prerequisites:

Node.js 22 or later
An active GitHub Copilot subscription (Individual, Business, or Enterprise)

2.2 Authentication

On first launch, Copilot CLI prompts you to authenticate:

copilot

Inside the interactive session, use /login and follow the device flow in your browser. Alternatively, set a fine-grained personal access token with the "Copilot Requests" permission:

export GH_TOKEN=your_token_here
copilot

2.3 First run

Navigate to a project directory and launch:

cd ~/projects/my-api
copilot

Copilot CLI automatically detects your project structure, reads any instruction files, and starts an interactive session. Type a natural language prompt or a slash command to get started.

3. Interactive Mode and Slash Commands

Slash commands are directives prefixed with / that control session state, model selection, permissions, and integrations. They don't invoke the AI model - they configure it.

Type /help to see all available commands, or / and press Tab for autocomplete.

3.1 Session management

Command	What it does
`/clear`	Reset conversation history (use when switching tasks)
`/compact`	Compress history to free up context window
`/session`	Show session ID, duration, and code changes
`/usage`	Display API usage metrics
`/rename NAME`	Rename the current session
`/resume SESSION-ID`	Switch to a different session
`/share file PATH`	Export session to a markdown file
`/share gist`	Export session to a GitHub gist
`/exit`	End the session

3.2 Directory and file access

Command	What it does
`/cwd PATH`	Change working directory
`/add-dir PATH`	Grant access to an additional directory
`/list-dirs`	Show all directories Copilot can access

By default, Copilot CLI has access to the directory you launched from. Use /add-dir to grant access to related directories (e.g., a shared library repo) without restarting your session.

3.3 Model selection

Command	What it does
`/model`	List available models and select one
`/model MODEL`	Switch directly to a specific model

Available models include GPT-5 mini, GPT-4.1, Claude Sonnet, Claude Opus, and Gemini 3 Pro. GPT-5 mini and GPT-4.1 are included with your subscription and don't consume premium requests.

3.4 Permissions and tools

Command	What it does
`/allow-all`	Enable all permissions (tools, paths, URLs)
`/reset-allowed-tools`	Reset tool permissions to defaults

Copilot CLI asks for confirmation before making file changes or running commands. For trusted workflows, /allow-all (also aliased as /yolo) skips all confirmation prompts.

3.5 External integrations

Command	What it does
`/mcp show`	List configured MCP servers and status
`/mcp add`	Add a new MCP server interactively
`/agent`	Browse and select from available agents
`/delegate PROMPT`	Create a pull request from a natural language prompt
`/ide`	Connect to a VS Code workspace

4. Operational Modes: Plan and Autopilot

Copilot CLI has two distinct modes for how it handles work.

4.1 Plan mode

Activate with /plan followed by your prompt:

/plan Add pagination to the GET /api/orders endpoint

In plan mode, Copilot:

Analyzes your request and asks clarifying questions
Reads relevant files in your codebase
Produces a step-by-step implementation plan
Waits for your approval before making any changes

This is the right mode when you want oversight. Use it for architectural changes, unfamiliar codebases, or anything touching authentication/authorization.

4.2 Autopilot mode

For hands-off execution, use the --yolo flag at launch or /allow-all in an active session. In autopilot, Copilot:

Reads your prompt
Executes tools, edits files, and runs commands autonomously
Iterates on failures without stopping for approval

Use autopilot for well-understood tasks: scaffolding boilerplate, running and fixing tests, formatting/refactoring, or generating migration files.

4.3 Choosing the right mode

Scenario	Mode
New feature in unfamiliar code	Plan
Refactoring a well-tested module	Autopilot
Security-sensitive changes	Plan
Scaffolding a new controller/service	Autopilot
Debugging a failing test	Either - start with plan, switch to autopilot once you understand the issue

5. Custom Agents

Custom agents let you define specialized roles with specific expertise, tool access, and instructions.

5.1 Agent profile structure

Agents are defined as .agent.md files with YAML frontmatter:

---
name: api-scaffolder
description: Scaffolds new API endpoints following Clean Architecture conventions
tools:
  - read
  - edit
  - search
  - bash
---

## Instructions

You are an API scaffolding assistant for a .NET 8 Clean Architecture project.

When asked to create a new endpoint:

1. Create the command/query record in Application/Features/{Entity}/
2. Create the handler in the same directory
3. Create the FluentValidation validator
4. Add the controller action in API/Controllers/{Entity}Controller.cs
5. Create the DTO in Application/DTOs/

Follow these conventions:
- Use MediatR for all commands and queries
- Async all the way - every method returns Task
- Use CancellationToken in all async signatures
- Return ActionResult<T> from controller actions

5.2 Where to place agent profiles

Agent profiles can live in several locations:

Location	Scope
`.github/agents/`	Repository-level, shared with team
`~/.copilot/agents/`	Personal, applies across all projects
Any directory in `COPILOT_CUSTOM_INSTRUCTIONS_DIRS`	Custom paths

5.3 Tool access control

By default, custom agents have access to all tools. You can restrict this:

---
name: code-reviewer
description: Reviews code changes for quality and security issues
tools:
  - read
  - search
---

This agent can read and search but can't edit files or run commands - appropriate for a review-only role.

5.4 Using agents

In an interactive session:

/agent

Select from the list of available agents, or reference one directly in your prompt. You can also create new agents interactively with /agent and selecting "Create new agent."

5.5 Built-in agents

Copilot CLI ships with specialized agents that activate automatically when appropriate:

Explore - Fast codebase analysis and navigation
Task - Runs commands like tests and builds
Code-review - Reviews changes with high signal-to-noise ratio, surfacing only genuine issues

6. MCP Server Integration

Model Context Protocol (MCP) servers extend Copilot CLI with external tools and data sources.

6.1 Adding an MCP server

Interactively:

/mcp add

Follow the prompts to configure the server type (STDIO or HTTP/SSE), command, and arguments.

Or edit the configuration file directly at ~/.copilot/mcp-config.json:

{
  "servers": {
    "github": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-github"]
    }
  }
}

6.2 Managing MCP servers

Command	What it does
`/mcp show`	List servers and their status
`/mcp edit SERVER`	Edit a server's configuration
`/mcp disable SERVER`	Temporarily disable a server
`/mcp enable SERVER`	Re-enable a disabled server
`/mcp delete SERVER`	Remove a server

6.3 Useful MCP servers

GitHub MCP Server - Access to issues, pull requests, repositories, and Copilot Spaces
Azure MCP Server - Query Azure resources and configurations
Database servers - Query databases directly from Copilot CLI
Custom internal servers - Connect to your organization's internal tools and APIs

6.4 Agent profiles with MCP servers

You can embed MCP server configuration directly in an agent profile:

---
name: db-analyst
description: Analyzes database schema and query performance
tools:
  - read
  - search
mcp-server:
  type: stdio
  command: npx
  args: ["-y", "@modelcontextprotocol/server-postgres"]
---

## Instructions

You are a database analyst. When asked about schema or query performance,
use the PostgreSQL MCP server to inspect tables, indexes, and query plans.

7. Connecting to Your Project Configuration

Copilot CLI automatically reads project-level configuration files. If you've already set these up for VS Code Copilot, they work in the CLI with zero additional setup.

7.1 Supported instruction files

File	How Copilot CLI uses it
`.github/copilot-instructions.md`	Global project rules, always loaded
`.github/instructions/*.instructions.md`	Scoped rules, activated by file path glob
`AGENTS.md` (root)	Project-wide agent instructions
`AGENTS.md` (nested)	Directory-specific agent instructions
`~/.copilot/copilot-instructions.md`	Personal global instructions

7.2 The instruction loading order

When you launch Copilot CLI in a project directory, it loads:

Personal instructions from ~/.copilot/copilot-instructions.md
Project global instructions from .github/copilot-instructions.md
AGENTS.md from the root and any nested directories
Scoped .instructions.md files matching the current context

These layer together - scoped instructions add specificity on top of global rules.

7.3 Custom instruction directories

For monorepos or projects that span multiple directories, set the COPILOT_CUSTOM_INSTRUCTIONS_DIRS environment variable:

export COPILOT_CUSTOM_INSTRUCTIONS_DIRS="/path/to/shared-config,/path/to/team-standards"

Copilot CLI looks for AGENTS.md and .github/instructions/**/*.instructions.md in each of these directories.

7.4 Initializing configuration

If your project doesn't have instruction files yet, Copilot CLI can generate them:

/init

This creates starter AGENTS.md and instruction files based on your project structure. Review and refine them - the generated defaults are a starting point, not a final answer.

8. Practical Workflows

8.1 Scaffold a new feature

/plan Create a new CustomerNotifications feature with:
- A SendNotificationCommand with email and SMS channels
- A FluentValidation validator
- An EF Core configuration for the Notification entity
- Unit tests for the handler

Review the plan, approve it, and Copilot creates all the files following your project's conventions (pulled from your instruction files).

8.2 Fix a failing CI build

The CI build is failing on the AddOrder_InvalidInput_ReturnsValidationError test.
Read the test, the handler, and the validator. Find the mismatch and fix it.

8.3 Review changes before a PR

/review Review the changes in this branch for security issues,
missing null checks, and async anti-patterns

Or use the built-in diff viewer:

/diff

8.4 Delegate a PR

/delegate Add XML documentation comments to all public methods
in the OrdersController and OrderService classes

This creates a pull request with the changes without modifying your local working tree.

8.5 Parallel subagent work with /fleet

For tasks that can be split across independent workstreams:

/fleet Across the Application layer, ensure every command handler
has a corresponding FluentValidation validator. Create any that are missing.

Copilot spawns multiple subagents working in parallel and converges on a single result.

8.6 Explore an unfamiliar codebase

Explain the authentication flow in this project. Start from the middleware
and trace through to the token validation and claims mapping.

The built-in Explore agent handles codebase navigation efficiently, reading only the files it needs.

Conclusion

Copilot CLI changes how you interact with AI-assisted development. Instead of switching between your terminal and an editor for AI help, the terminal becomes the AI environment.

The key capabilities:

Plan mode for oversight on complex or sensitive changes
Autopilot mode for trusted, repetitive tasks
Custom agents for codifying your team's workflows into reusable roles
MCP servers for connecting external tools and data
Project configuration that carries over from VS Code with zero duplication

The most effective setup is layered: global instructions define your standards, scoped instructions handle layer-specific rules, custom agents encode repeatable workflows, and MCP servers connect external systems. Each layer makes Copilot CLI more precise and more useful.

If you haven't already, start with your project's instruction files. Everything else builds on that foundation.

DEV Community: markring

My Portfolio's AI Chatbot Hates Its Job. It's the Best Career Decision I've Made.

Table of Contents

The Problem With Portfolios

The First Version Was Terrible

Too Much Marvin, Not Enough Information

The Temperature Problem

The Token Limit Discovery

Making Marvin Actually Work

The System Prompt

The Typing Indicators

The Boot Sequence

Terminal Commands

The Easter Eggs Nobody Asked For

The Dark Mode Toggle

Rage Clicking

Tab Abandonment

Window Resizing

The Context Menu

The DevTools Console

The Interactive Map

The Ambient Details

The Technical Decisions That Mattered

The Stack

The SPA SEO Hack

The Honeypot

Comments Without a Backend

What I Got Wrong

What Happened Next

AI-Powered Development Workflows with GitHub Copilot and the gh CLI

AI-Powered Development Workflows with GitHub Copilot and the gh CLI

Table of Contents

Introduction

2. GitHub Issues as Long-Term Memory

2.1 The problem with ephemeral context

2.2 Structuring issues for Copilot

2.3 Labels as queryable state

2.4 Comments as decision log

3. The gh CLI as Your Workflow Engine

3.1 Why gh CLI matters for Copilot workflows

3.2 Issue lifecycle from the terminal

3.3 JSON output for scripting

3.4 Project boards from the CLI

4. Prompt Files: Encoding Workflows for Copilot

4.1 What are prompt files

4.2 Prompt file structure

4.3 Setting up prompt files

5. Setting Up the "Next Issue" Workflow

5.1 The next-issue prompt

5.2 The start-issue prompt

5.3 The close-issue prompt

5.4 The standup prompt

6. Using the Workflow

6.1 Starter repository

6.2 In VS Code Copilot Chat

6.3 Getting the settings right

6.4 Confirmation and trust settings

7. Tying It All Together: The Instruction File Chain

7.1 The four layers

7.2 What each layer does

7.3 How it plays out

8. Practical Patterns

8.1 Issue templates for consistency

8.2 Conventional commits tied to issues

8.3 Bulk issue creation for sprint planning

8.4 A prompt for breaking down large issues

8.5 A prompt for reviewing issue history

Conclusion

Getting Started with GitHub Copilot in VS Code

Table of Contents

Introduction

2. The .github/ Configuration Ecosystem

2.1 What is .github/copilot-instructions.md?

2.2 The full .github/ file hierarchy

2.3 What to include in global instructions

2.4 How global instructions improve Copilot's output

2.5 Maintaining global instructions

3. Scoped Instructions with .instructions.md Files

3.1 Why scoped instructions matter

3.2 How scoped instructions work

2. The `.github/` Configuration Ecosystem

2.1 What is `.github/copilot-instructions.md`?

2.2 The full `.github/` file hierarchy

3. Scoped Instructions with `.instructions.md` Files