Learn: Using This Repo as a Boilerplate

Note: The learn/ folder lives at the project root of this boilerplate repo. It is a standalone guide — not copied into your project when you install.

What This Repo Is

This repository is a ready-to-use boilerplate for setting up GitHub Copilot for any software development team. It contains:

8 pre-configured agents (Discuss, Research, Planner, TDD, Reviewer, Verify, ApiBuilder, ParallelBuilder)
9 instruction files (developer guide, API architecture, backend, frontend, testing, Playwright, commenting, doc-sync, parallel-agents)
14 prompt slash commands (/start-issue, /discuss, /research, /plan, /execute, /verify, /debug, /add-new-api, /receive-review, /finish-branch, /generate-api-doc, /update-api-doc, /status, /sync-docs)
2 automation hooks (session-auto-commit, session-logger)
13 skills (TDD, subagent-driven-dev, Playwright × 3, code review × 2, doc-reviewer, documentation-writer, activity-logger, acquire-codebase-knowledge, GitHub CLI workflow, GitLab CLI workflow)
9 documentation templates (Issue, API doc, wrapper doc, external API, flow, ADR, architecture, project, copilot-instructions)
A complete learn series (this series, 11 blog-style guides)

Everything is designed to drop into an existing project with minimal customization.

Option 1: GitHub Template (Easiest)

If this repo is public and configured as a GitHub template:

Click “Use this template” on GitHub
Create your new repo
Follow Part 7 — Team Lead Setup for customization

Option 2: Install into an Existing Project

PowerShell (Windows)

# Navigate to your project
cd your-project

# Clone the boilerplate
git clone https://github.com/SriSatyaLokesh/copilot-team-workflow.git copilot-boilerplate

# Copy .github folder and docs structure (excludes learn/ and boilerplate-only docs)
Copy-Item -Recurse copilot-boilerplate\.github .\
$excludeDocs = @('learn','AGENT-MODE-VS-TDD-AGENT.md','blog-best-way-to-use-copilot.md','COMPLETE-WORKFLOW-VISUAL.md','CONTRIBUTING.md','copilot-team-setup-guide.md','DEVELOPER-STANDARD-GUIDE.md','MIGRATION-V2.md','MODEL-SELECTION.md','RESEARCH-DECISIONS.md','team-copilot-guide.md','vscode-team-copilot-research.md','WHATS-NEW-V2.md','WORK-FOLDER-STRUCTURE.md')
Get-ChildItem copilot-boilerplate\docs -Exclude $excludeDocs | Copy-Item -Destination .\docs -Recurse -Force

# Create required local log folders (never committed)
New-Item -ItemType Directory -Force logs\copilot

# Add logs folder to .gitignore
Add-Content .gitignore "`nlogs/"

# Clean up
Remove-Item -Recurse -Force copilot-boilerplate

# Commit
git add .github/ docs/ .gitignore
git commit -m "chore: add Copilot team workflow boilerplate"
git push

Bash (Linux / macOS)

# Navigate to your project
cd your-project

# Clone the boilerplate
git clone https://github.com/SriSatyaLokesh/copilot-team-workflow.git copilot-boilerplate

# Copy .github folder and docs structure (excludes learn/ and boilerplate-only docs)
cp -r copilot-boilerplate/.github ./
rsync -av \
  --exclude='learn/' \
  --exclude='AGENT-MODE-VS-TDD-AGENT.md' \
  --exclude='blog-best-way-to-use-copilot.md' \
  --exclude='COMPLETE-WORKFLOW-VISUAL.md' \
  --exclude='CONTRIBUTING.md' \
  --exclude='copilot-team-setup-guide.md' \
  --exclude='DEVELOPER-STANDARD-GUIDE.md' \
  --exclude='MIGRATION-V2.md' \
  --exclude='MODEL-SELECTION.md' \
  --exclude='RESEARCH-DECISIONS.md' \
  --exclude='team-copilot-guide.md' \
  --exclude='vscode-team-copilot-research.md' \
  --exclude='WHATS-NEW-V2.md' \
  --exclude='WORK-FOLDER-STRUCTURE.md' \
  copilot-boilerplate/docs/ ./docs/ 2>/dev/null || {
  cp -r copilot-boilerplate/docs ./
  rm -rf docs/learn docs/AGENT-MODE-VS-TDD-AGENT.md docs/blog-best-way-to-use-copilot.md \
    docs/COMPLETE-WORKFLOW-VISUAL.md docs/CONTRIBUTING.md docs/copilot-team-setup-guide.md \
    docs/DEVELOPER-STANDARD-GUIDE.md docs/MIGRATION-V2.md docs/MODEL-SELECTION.md \
    docs/RESEARCH-DECISIONS.md docs/team-copilot-guide.md docs/vscode-team-copilot-research.md \
    docs/WHATS-NEW-V2.md docs/WORK-FOLDER-STRUCTURE.md
}

# Create required local log folders (never committed)
mkdir -p logs/copilot

# Make hook scripts executable
chmod +x .github/hooks/session-auto-commit/auto-commit.sh
chmod +x .github/hooks/session-logger/*.sh

# Add logs folder to .gitignore
echo "logs/" >> .gitignore

# Clean up
rm -rf copilot-boilerplate

# Commit
git add .github/ docs/ .gitignore
git commit -m "chore: add Copilot team workflow boilerplate"
git push

📂 What Gets Copied from `docs/`

Copied into your project	Not copied (boilerplate-only)
`docs/README.md`	`AGENT-MODE-VS-TDD-AGENT.md`
`docs/project.md`	`blog-best-way-to-use-copilot.md`
`docs/templates/` (11 templates)	`COMPLETE-WORKFLOW-VISUAL.md`
`docs/codebase/` (7 scaffold files)	`CONTRIBUTING.md`
`docs/apis/` (README + example)	`copilot-team-setup-guide.md`
`docs/flows/` (README + example)	`DEVELOPER-STANDARD-GUIDE.md`
`docs/external-apis/` (README + example)	`MIGRATION-V2.md`
`docs/issues/` (README + example)	`MODEL-SELECTION.md`
`docs/decisions/` (empty folder)	`RESEARCH-DECISIONS.md`
`docs/team-notes/` (empty folder)	`team-copilot-guide.md`
	`vscode-team-copilot-research.md`
	`WHATS-NEW-V2.md`
	`WORK-FOLDER-STRUCTURE.md`

learn/ is never copied — it’s a standalone guide, read at the boilerplate repo.

VS Code Settings

After copying, add these to your workspace .vscode/settings.json then reload VS Code:

{
  "github.copilot.chat.codeGeneration.useInstructionFiles": true,
  "chat.promptFilesLocations": [".github/prompts"],
  "chat.instructionsFilesLocations": [".github/instructions"],
  "chat.promptFilesRecommendations": {
    "start-issue": true,
    "debug": true
  }
}

chat.promptFilesRecommendations: Surfaces /start-issue and /debug as suggested actions whenever a developer opens a new chat — so they always start from the correct entry point.

What to Customize (The Minimum Set)

After copying, these are the files you MUST edit for your project:

1. `.github/copilot-instructions.md`

# [YOUR PROJECT NAME] — GitHub Copilot Configuration

## What This Project Is
[One sentence describing your project]
Stack: [Your tech stack]

## Key Documentation
[Your relevant doc links]

2. `.github/instructions/api-architecture.instructions.md`

Update applyTo file globs to match your folder structure
Update example file paths (e.g., src/wrappers/ → wherever your wrappers live)
Add any project-specific architecture rules

3. `.github/instructions/backend.instructions.md`

Set your actual framework (Express, Fastify, NestJS, etc.)
Set your validation library (zod, class-validator, joi)
Set your ORM (Prisma, TypeORM, Drizzle, Sequelize)

4. `docs/external-apis/` (if you have external APIs)

Create one folder per external API
Copy and fill in docs/templates/external-api-doc-template.md
Fill in the field mapping table for each entity — this is the highest-value work

What to Leave As-Is

These files require no changes and work out of the box:

File	Why it works as-is
All 8 agents	Logic is generic, not project-specific
All 15 prompts	Commands work for any project
Both hooks	Shell scripts are project-agnostic
All 9 templates	Generic — fill in per use
All 13 skills	Generic knowledge packs
`developer-guide.instructions.md`	Generic developer guide
`learn/` folder (boilerplate root)	The learning series, read before installing

The Files in One View

.github/
├── copilot-instructions.md              ← EDIT: your project overview
├── tool-sets.json                       ← works as-is
├── instructions/
│   ├── developer-guide.instructions.md  ← works as-is
│   ├── api-architecture.instructions.md ← EDIT: your folder paths
│   ├── backend.instructions.md          ← EDIT: your stack
│   ├── frontend.instructions.md         ← EDIT: your frontend stack
│   ├── testing.instructions.md          ← EDIT: your test framework
│   ├── playwright-typescript.instructions.md         ← works as-is
│   ├── self-explanatory-code-commenting.instructions.md ← works as-is
│   ├── update-docs-on-code-change.instructions.md   ← works as-is
│   └── parallel-agents.instructions.md  ← works as-is
├── agents/
│   ├── discuss.agent.md                 ← works as-is
│   ├── research.agent.md                ← works as-is
│   ├── plan.agent.md                    ← works as-is
│   ├── tdd.agent.md                     ← works as-is
│   ├── review.agent.md                  ← works as-is
│   ├── verify.agent.md                  ← works as-is
│   ├── api-builder.agent.md             ← works as-is
│   └── parallel-builder.agent.md        ← works as-is (3+ independent tasks)
├── prompts/
│   ├── start-issue.prompt.md            ← works as-is (always start here)
│   ├── discuss.prompt.md                ← works as-is
│   ├── research.prompt.md               ← works as-is
│   ├── plan.prompt.md                   ← works as-is
│   ├── execute.prompt.md                ← works as-is
│   ├── verify.prompt.md                 ← works as-is
│   ├── debug.prompt.md                  ← works as-is
│   ├── add-new-api.prompt.md            ← works as-is
│   ├── receive-review.prompt.md         ← works as-is
│   ├── finish-branch.prompt.md          ← works as-is (post-verify)
│   ├── generate-api-doc.prompt.md       ← works as-is
│   ├── update-api-doc.prompt.md         ← works as-is
│   ├── status.prompt.md                 ← works as-is (check progress)
│   ├── summarize.prompt.md              ← works as-is (save session context)
│   └── sync-docs.prompt.md              ← works as-is (bulk doc updates)
├── skills/
│   ├── acquire-codebase-knowledge/SKILL.md  ← works as-is
│   ├── agent-activity-logger/SKILL.md       ← works as-is
│   ├── doc-reviewer/SKILL.md                ← works as-is
│   ├── documentation-writer/SKILL.md        ← works as-is
│   ├── github-cli-workflow/SKILL.md         ← works as-is (GitHub: gh issues, PRs, merge)
│   ├── gitlab-cli-workflow/SKILL.md         ← works as-is (GitLab: glab issues, MRs, merge)
│   ├── playwright-automation-fill-in-form/SKILL.md ← works as-is
│   ├── playwright-explore-website/SKILL.md  ← works as-is
│   ├── playwright-generate-test/SKILL.md    ← works as-is
│   ├── receiving-code-review/SKILL.md       ← works as-is
│   ├── requesting-code-review/SKILL.md      ← works as-is
│   ├── subagent-driven-development/SKILL.md ← works as-is
│   └── test-driven-development/SKILL.md     ← works as-is
└── hooks/
    ├── session-auto-commit/             ← works as-is
    └── session-logger/                  ← works as-is

docs/
├── README.md                            ← How to use each template and folder
├── templates/                           ← works as-is (copy-paste starters)
│   ├── issue-template.md
│   ├── api-doc-template.md
│   ├── api-wrapper-doc-template.md
│   ├── external-api-doc-template.md
│   ├── flow-doc-template.md
│   ├── adr-template.md
│   ├── architecture-template.md
│   ├── project-template.md
│   └── copilot-instructions-template.md
├── external-apis/                       ← CREATE: one folder per external API
├── issues/                              ← FILL: one doc per Issue
├── apis/                                ← FILL: one doc per internal endpoint
├── flows/                               ← FILL: one doc per user journey
└── decisions/                           ← FILL: one ADR per major decision

learn/                                   ← standalone guide (not copied on install)
├── 00-introduction.md
├── 01-github-folder-explained.md
├── 02-five-phase-workflow.md
├── 03-api-architecture.md
├── 04-documenting-external-apis.md
├── 05-daily-workflow.md
├── 06-hooks-and-automation.md
├── 07-team-lead-setup.md
├── 08-boilerplate-setup.md              ← this file
├── 09-test-driven-development.md
└── 10-subagent-driven-development.md

Estimated Setup Time

Task	Time
Copy .github folder	5 min
Update copilot-instructions.md	15 min
Customize instruction files	45 min
Document first external API	60 min
Install and test hooks	20 min
Brief the team	30 min
Total	~3 hours

What You Get After Setup

✅ Every Copilot session loads architecture rules automatically based on the file open
✅ Every developer follows the same 5-phase workflow
✅ Correct field names used in every external API call (from docs)
✅ Every session is logged with timestamps and key decisions
✅ Every work item has a full paper trail (discuss → research → plan → execute → verify)
✅ New developers onboard in 30 minutes by reading the learn/ series on the boilerplate repo

Upgrading from a Previous Version

If you installed an earlier version of this boilerplate, your docs/ folder may contain boilerplate-only files that are no longer intended for consumer projects. Run these commands to clean them up:

PowerShell:

$toRemove = @('AGENT-MODE-VS-TDD-AGENT.md','blog-best-way-to-use-copilot.md','COMPLETE-WORKFLOW-VISUAL.md','CONTRIBUTING.md','copilot-team-setup-guide.md','DEVELOPER-STANDARD-GUIDE.md','MIGRATION-V2.md','MODEL-SELECTION.md','RESEARCH-DECISIONS.md','team-copilot-guide.md','vscode-team-copilot-research.md','WHATS-NEW-V2.md','WORK-FOLDER-STRUCTURE.md')
$toRemove | ForEach-Object { Remove-Item -Force "docs\$_" -ErrorAction SilentlyContinue }

Bash:

cd docs && rm -f AGENT-MODE-VS-TDD-AGENT.md blog-best-way-to-use-copilot.md COMPLETE-WORKFLOW-VISUAL.md \
  CONTRIBUTING.md copilot-team-setup-guide.md DEVELOPER-STANDARD-GUIDE.md MIGRATION-V2.md \
  MODEL-SELECTION.md RESEARCH-DECISIONS.md team-copilot-guide.md vscode-team-copilot-research.md \
  WHATS-NEW-V2.md WORK-FOLDER-STRUCTURE.md && cd ..

Continue the Series

You’ve set up the system — now learn how to keep your code quality high with TDD.

Next: Test-Driven Development (TDD) → 09-test-driven-development.md

You now know:

What every file in .github/ does and why it exists
How the 5-phase Issue workflow prevents “just start coding” chaos
The architecture rules that keep every layer doing one job
How to document external APIs so Copilot uses the right field names
What your daily workflow looks like in practice
How hooks automate session management
How to set this up as a team lead
How to use this repo as a boilerplate for any project

Share this series: learn/00-introduction.md is the entry point for your whole team — link them to the boilerplate repo directly.

Learn: Using This Repo as a Boilerplate

What This Repo Is

Option 1: GitHub Template (Easiest)

Option 2: Install into an Existing Project

PowerShell (Windows)

Bash (Linux / macOS)

📂 What Gets Copied from `docs/`

VS Code Settings

What to Customize (The Minimum Set)

1. `.github/copilot-instructions.md`

2. `.github/instructions/api-architecture.instructions.md`

3. `.github/instructions/backend.instructions.md`

4. `docs/external-apis/` (if you have external APIs)

What to Leave As-Is

The Files in One View

Estimated Setup Time

What You Get After Setup

Upgrading from a Previous Version

Continue the Series

Further Reading

VS Code team’s `.github/` folder — the gold standard: 13 instructions, 17 prompts, 11 skills in production

Learn: Using This Repo as a Boilerplate

What This Repo Is

Option 1: GitHub Template (Easiest)

Option 2: Install into an Existing Project

PowerShell (Windows)

Bash (Linux / macOS)

📂 What Gets Copied from docs/

VS Code Settings

What to Customize (The Minimum Set)

1. .github/copilot-instructions.md

2. .github/instructions/api-architecture.instructions.md

3. .github/instructions/backend.instructions.md

4. docs/external-apis/ (if you have external APIs)

What to Leave As-Is

The Files in One View

Estimated Setup Time

What You Get After Setup

Upgrading from a Previous Version

Continue the Series

Further Reading

VS Code team’s .github/ folder — the gold standard: 13 instructions, 17 prompts, 11 skills in production

📂 What Gets Copied from `docs/`

1. `.github/copilot-instructions.md`

2. `.github/instructions/api-architecture.instructions.md`

3. `.github/instructions/backend.instructions.md`

4. `docs/external-apis/` (if you have external APIs)

VS Code team’s `.github/` folder — the gold standard: 13 instructions, 17 prompts, 11 skills in production