Copilot Workflow Automation

GitHub Copilot workflow automation for Microsoft Learn platform development.

Quick Start

# Research a feature
@mslearn-research Analyze the article rating system in docs-ui

# Create implementation plan
@mslearn-planning Create plan from: copilot-config/agent-artifacts/research/{file}.md

# Implement
@mslearn-implementation Execute Phase 1 of plan

# Ship it
/mslearn-ship-it

Multi-Repo Workspace Setup

Agents are discovered from .github/agents/ relative to your active file's repo. Run the setup script once after cloning to make agents available from all sibling repos:

One-Time Setup

# Windows (PowerShell)
.\setup-agents.ps1

# macOS/Linux
./setup-agents.sh

This auto-discovers sibling repos and creates junctions/symlinks to copilot-config's agents folder.

Options

# Preview changes without applying
./setup-agents.sh --dry-run

# Link specific repos only
./setup-agents.sh docs-ui feature-gap-wt

# Replace existing agents folders
./setup-agents.sh --force

Manual Setup

If you prefer manual setup or need to add repos in different locations:

# Windows (PowerShell) - Junction (no admin required)
New-Item -ItemType Junction -Path "{TARGET_REPO}\.github\agents" -Target "c:\repos\mslearn\copilot-config\.github\agents"

# macOS/Linux - Symlink
ln -s /path/to/copilot-config/.github/agents {TARGET_REPO}/.github/agents

Notes

Junctions/symlinks are local - each developer runs setup once
If target repo has existing agents, use --force to replace or manually merge
Agents have full access to all repos in the workspace regardless of discovery location

Environment Configuration

The workflow configuration uses environment variables to avoid storing personal information in Git. Set up your environment:

Initial Setup

Copy the environment template:
```
cp .env.example .env
```

Edit .env with your personal information:

# User Information  
USER_ALIAS=your-alias
USER_EMAIL=your-email@microsoft.com
ADO_ASSIGNEE=your-email@microsoft.com
ADO_AREA_PATH=Engineering\\POD\\YourTeam

The .env file is already included in .gitignore and will not be committed.

Environment Variables

Variable	Description	Example
`USER_ALIAS`	Your Microsoft alias	`jumunn`
`USER_EMAIL`	Your Microsoft email	`jumunn@microsoft.com`
`ADO_ASSIGNEE`	Default assignee for ADO items	`jumunn@microsoft.com`
`ADO_AREA_PATH`	Your team's area path	`Engineering\POD\YourTeam`
`ADO_ORGANIZATION`	Azure DevOps org URL	`https://dev.azure.com/ceapex`
`ADO_PROJECT`	Azure DevOps project name	`Engineering`
`ADO_SWE_ASSIGNEE`	SWE agent identity (GUID)	(see .env.example)

The workflow configuration in .github/config/workflow-config.json uses ${VAR_NAME} placeholders that resolve from your .env file.

System Architecture

graph TB
    subgraph "User Commands"
        P["/prompts"]
    end
    
    subgraph "Orchestration Layer"
        P --> WF["Workflow Prompts<br/>(small-feature, large-feature, ship-it, etc.)"]
        WF --> |delegates to| SK["Skills<br/>(pre-commit, create-handoff, etc.)"]
    end
    
    subgraph "Agent Personas (referenced via prompt frontmatter)"
        WF --> RA["mslearn-research"]
        WF --> PA["mslearn-planning"]
        WF --> IA["mslearn-implementation"]
        WF --> CR["mslearn-code-review"]
    end
    
    subgraph "Automatic (no user invocation)"
        HK_I["Instruction Hooks<br/>(.vscode/settings.json)<br/>commit msg · code review · test gen"]
        HK_A["Agent Lifecycle Hooks<br/>(.github/hooks/)<br/>safety guard · pre-commit gate · session logging"]
        INS["Instructions<br/>(.github/instructions/)<br/>auto-loaded by file pattern"]
    end
    
    subgraph "Artifacts (agent-artifacts/)"
        RA --> |creates| RES["research/*.md"]
        PA --> |creates| PLN["plans/*.md"]
        WF --> |creates| HND["handoffs/*.md"]
        CR --> |creates| REV["reviews/*.md"]
    end
    
    subgraph "Configuration"
        CFG["workflow-config.json"]
    end
    
    WF --> CFG
    HK_A --> |reads| CFG
    INS --> |enriches| WF

Component Types

graph LR
    subgraph "Invoked by User"
        P["Prompts (/command)"]
    end
    
    subgraph "Used by Prompts"
        AG["Agent Personas"]
        SK["Skills (SKILL.md)"]
    end
    
    subgraph "Automatic"
        I["Instructions"]
        HI["Instruction Hooks"]
        HA["Agent Lifecycle Hooks"]
        C["Config"]
    end
    
    P --> |"agent: frontmatter"| AG
    P --> |"reads SKILL.md"| SK
    I --> |"enriches context"| P
    HI --> |"shapes output"| P
    HA --> |"guards actions"| P
    C --> |configures| P

Type	Invocation	Context	Purpose
Prompts	`/command`	On invoke · High	User-initiated multi-step workflows
Skills	SKILL.md packages	Metadata auto, body on-demand · Low–Medium	Self-contained single-purpose actions
Agent Personas	Prompt `agent:` frontmatter	Loaded with prompt execution · Medium	Shared tool/instruction configs for prompt workflows
Instruction Hooks	Automatic	Auto on Copilot action · Low	Shape generated content (commit msgs, reviews, tests)
Agent Lifecycle Hooks	Automatic	Auto on agent events · Low	Guardrails and gates (safety guard, pre-commit, session logging)
Instructions	Auto-loaded	Auto on file match · Medium	Static rules by file pattern
Config	Referenced	On-demand · Low	Central settings

Prompts vs Skills: Prompts use .prompt.md files with frontmatter for multi-step interactive workflows. Skills use SKILL.md in .github/skills/{name}/ directories — self-contained packages with optional references/ for templates. Instruction hooks live in .vscode/settings.json and shape Copilot-generated content. Agent lifecycle hooks live in .github/hooks/ and run shell scripts on events like sessionStart and preToolUse.

Workflow Selection

flowchart TD
    START([New Task]) --> Q1{Single repo?}
    Q1 --> |Yes| Q2{< 2 hours?}
    Q1 --> |No| Q3{Parity or E2E?}
    
    Q2 --> |Yes| SF["/mslearn-small-feature"]
    Q2 --> |No| LF["/mslearn-large-feature"]
    
    Q3 --> |Parity| PF["/mslearn-parity-feature"]
    Q3 --> |E2E| LF
    
    SF --> IMPL([Implement])
    LF --> RES["/research-codebase"] --> PLAN["/create-plan"] --> IMPL
    PF --> RES
    
    IMPL --> DONE{Done?}
    DONE --> |"Ready to ship"| SHIP["/mslearn-ship-it"]
    DONE --> |"Stopping for now"| HO["/mslearn-create-handoff"]
    
    HO --> LATER([Resume later])
    LATER --> RESUME["/mslearn-resume-handoff"]

Artifact Flow

sequenceDiagram
    participant U as User
    participant R as /research-codebase
    participant P as /create-plan
    participant I as /implement-plan
    participant A as Artifacts
    
    U->>R: /research-codebase [topic]
    R->>A: Creates research/*.md
    R-->>U: ⏸️ PAUSED - Review artifact
    
    U->>P: /create-plan [from research]
    P->>A: Reads research/*.md
    P->>A: Creates plans/*.md
    P-->>U: ⏸️ PAUSED - Review plan
    
    U->>I: /implement-plan [phase]
    I->>A: Reads plans/*.md
    I->>I: Modifies codebase
    I-->>U: Phase complete

Directory Structure

copilot-config/
├── README.md                    # This file - system overview
├── WORKFLOWS.md                 # Detailed workflow documentation
├── .github/
│   ├── config/
│   │   └── workflow-config.json # Central configuration
│   ├── agents/                  # Agent personas (referenced via prompt agent: frontmatter)
│   ├── prompts/                 # User-invoked workflows
│   │   ├── mslearn-small-feature.prompt.md
│   │   ├── mslearn-large-feature.prompt.md
│   │   ├── mslearn-parity-feature.prompt.md
│   │   ├── mslearn-create-plan.prompt.md
│   │   ├── mslearn-implement-plan.prompt.md
│   │   ├── mslearn-research-codebase.prompt.md
│   │   ├── mslearn-ship-it.prompt.md
│   │   ├── mslearn-review-it.prompt.md
│   │   ├── mslearn-update-plan.prompt.md
│   │   ├── mslearn-resume-handoff.prompt.md
│   │   ├── mslearn-create-handoff.prompt.md
│   │   ├── mslearn-create-ado-workitems.prompt.md
│   │   ├── mslearn-assign-swe.prompt.md
│   │   ├── mslearn-explain-pr.prompt.md
│   │   ├── mslearn-pre-commit.prompt.md
│   │   ├── mslearn-prune-worktree.prompt.md
│   │   └── mslearn-create-worktree.prompt.md
│   ├── skills/                  # Self-contained single-purpose actions
│   │   ├── assign-swe/            # SKILL.md
│   │   ├── create-ado-workitems/   # SKILL.md + references/templates.md
│   │   ├── create-handoff/        # SKILL.md + references/template.md
│   │   ├── create-worktree/       # SKILL.md
│   │   ├── explain-pr/            # SKILL.md + references/template.md
│   │   ├── pre-commit/            # SKILL.md
│   │   ├── prune-worktree/        # SKILL.md
│   │   └── session-learnings/     # SKILL.md + references/template.md
│   ├── hooks/                   # Agent lifecycle hooks
│   │   ├── copilot-agent-hooks.json  # Hook config
│   │   └── scripts/                  # Shell scripts for hooks
│   └── instructions/            # Auto-loaded rules
│       └── azure-devops-workitems.instructions.md
├── .vscode/
│   └── settings.json            # Copilot hooks (commit, review, test)
├── vscode-extension/            # MSLearn Copilot Agents extension
└── agent-artifacts/             # Agent outputs (gitignored)
    ├── research/                # Research documents
    ├── plans/                   # Implementation plans
    ├── handoffs/                # Session handoffs
    └── reviews/                 # Code review documents

Key Concepts

Pause Points

Research and planning agents pause after creating artifacts to allow user review:

✅ Research complete!
⏸️ PAUSED FOR REVIEW

When ready:
  @mslearn-planning Create plan from: {artifact path}

Mermaid Diagrams

All artifacts include Mermaid diagrams for context efficiency:

Research: Architecture + data flow diagrams
Plans: Architecture overview + phase dependencies
Handoffs: Component relationships + current flow

Diagrams help agents understand systems without re-reading files.

Configuration

Two-layer config: .env for personal settings, workflow-config.json for shared structure.

.env: alias, email, ADO assignee, area path, org, project (see Environment Configuration)
workflow-config.json: ${ENV_VAR} placeholders, repo commands, preview URLs, artifact patterns
Setup: cp .env.example .env then edit with your values

Commands Reference

Workflows (multi-step, interactive)

Command	Description
`/mslearn-small-feature`	Quick feature implementation (< 2 hours, single repo)
`/mslearn-large-feature`	Complex multi-repo feature with research and planning
`/mslearn-parity-feature`	Port feature between repos
`/mslearn-create-plan`	Create detailed implementation plans
`/mslearn-implement-plan`	Execute plan phases with verification
`/mslearn-research-codebase`	Document codebase without evaluation
`/mslearn-ship-it`	Commit, push, create PR
`/mslearn-review-it`	Review PR branch
`/mslearn-update-plan`	Sync plan with codebase status
`/mslearn-resume-handoff`	Resume from handoff document
`/mslearn-create-handoff`	Create a session handoff document
`/mslearn-create-ado-workitems`	Create ADO work items from a plan
`/mslearn-assign-swe`	Assign GitHub SWE to a work item
`/mslearn-explain-pr`	Generate PR explanation documentation
`/mslearn-pre-commit`	Run repository quality checks
`/mslearn-prune-worktree`	Remove worktrees and clean up resources
`/mslearn-create-worktree`	Create worktree with auth, deps, and agent symlinks

Skills (self-contained SKILL.md packages in `.github/skills/`)

Skill	Location	Description
`create-ado-workitems`	`.github/skills/create-ado-workitems/`	Create ADO items from plan
`assign-swe`	`.github/skills/assign-swe/`	Assign GitHub SWE to work item
`create-handoff`	`.github/skills/create-handoff/`	Save session context for later
`create-worktree`	`.github/skills/create-worktree/`	Create worktree with auth and npm install
`explain-pr`	`.github/skills/explain-pr/`	Generate PR explanation document
`pre-commit`	`.github/skills/pre-commit/`	Run quality gate checks
`prune-worktree`	`.github/skills/prune-worktree/`	Remove worktrees and workspace files

Hooks

Instruction Hooks (`.vscode/settings.json`)

Hook	Trigger	What It Does
Commit message generation	Copilot generates commit message	Enforces conventional commits format
Code review instructions	Copilot reviews code	Applies Learn platform standards
Test generation instructions	Copilot generates tests	Applies Jest/TypeScript conventions

Agent Lifecycle Hooks (`.github/hooks/`)

Hook	Event	Script	What It Does
Safety guard	`preToolUse`	`safety-guard.sh/ps1`	Blocks destructive commands, force pushes to protected branches, edits to CI/CD configs
Pre-commit gate	`preToolUse`	`pre-commit-gate.sh/ps1`	Runs repo-specific quality checks before `git commit`
Session start	`sessionStart`	`setup-node.sh`	Installs Node.js/npm in SWE agent containers
Session logging	`sessionStart`	`session-start-log.sh`	Logs session metadata for diagnostics
Session end	`sessionEnd`	`session-end-learnings.sh/ps1`	Writes marker for learnings extraction

Agents

Agent Persona	Description
`mslearn-research`	Deep codebase research and documentation
`mslearn-planning`	Create implementation plans
`mslearn-implementation`	Execute plan phases
`mslearn-code-review`	Review code changes

Documentation

WORKFLOWS.md - Detailed workflow usage with examples
workflow-config.json - Configuration reference

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Repository files navigation

Copilot Workflow Automation

Quick Start

Multi-Repo Workspace Setup

One-Time Setup

Options

Manual Setup

Notes

Environment Configuration

Initial Setup

Environment Variables

System Architecture

Component Types

Workflow Selection

Artifact Flow

Directory Structure

Key Concepts

Pause Points

Mermaid Diagrams

Configuration

Commands Reference

Workflows (multi-step, interactive)

Skills (self-contained SKILL.md packages in `.github/skills/`)

Hooks

Instruction Hooks (`.vscode/settings.json`)

Agent Lifecycle Hooks (`.github/hooks/`)

Agents

Documentation

About

Uh oh!

Releases

Packages

Uh oh!

Contributors

Uh oh!

Languages

Name		Name	Last commit message	Last commit date
Latest commit History 33 Commits
.github		.github
.vscode		.vscode
agent-artifacts		agent-artifacts
vscode-extension		vscode-extension
.env.example		.env.example
.gitignore		.gitignore
README.md		README.md
WORKFLOWS.md		WORKFLOWS.md
install-vscode-extension.ps1		install-vscode-extension.ps1
install-vscode-extension.sh		install-vscode-extension.sh
lofi-gritty-at.svg		lofi-gritty-at.svg
setup-agents.ps1		setup-agents.ps1
setup-agents.sh		setup-agents.sh

Folders and files

Latest commit

History

Repository files navigation

Copilot Workflow Automation

Quick Start

Multi-Repo Workspace Setup

One-Time Setup

Options

Manual Setup

Notes

Environment Configuration

Initial Setup

Environment Variables

System Architecture

Component Types

Workflow Selection

Artifact Flow

Directory Structure

Key Concepts

Pause Points

Mermaid Diagrams

Configuration

Commands Reference

Workflows (multi-step, interactive)

Skills (self-contained SKILL.md packages in .github/skills/)

Hooks

Instruction Hooks (.vscode/settings.json)

Agent Lifecycle Hooks (.github/hooks/)

Agents

Documentation

About

Resources

Uh oh!

Stars

Watchers

Forks

Releases

Packages 0

Uh oh!

Contributors

Uh oh!

Languages

Skills (self-contained SKILL.md packages in `.github/skills/`)

Instruction Hooks (`.vscode/settings.json`)

Agent Lifecycle Hooks (`.github/hooks/`)

Packages