The Copilot Integration Trilogy

How Plan Forge teaches GitHub Copilot about your project, three tools, two generated files, one dashboard tab, zero manual setup after the first run.

Why a trilogy?

GitHub Copilot reads two files automatically when you open a workspace:

1. .github/copilot-instructions.md, "what you must always know about this project". Architectural rules, naming conventions, build commands, security commitments.
2. .github/copilot-memory-hints.md, "what we've learned from doing this work". Trajectories from prior plans, recurring patterns, auto-skills extracted from successful slices.

Both files exist before Plan Forge, you can hand-author them. But hand-authoring means: (a) they go stale the moment you ship the next plan, (b) every team member writes a slightly different one, and (c) when the underlying decisions change in .forge.json or PROJECT-PRINCIPLES.md, nothing reminds you to regenerate.

The trilogy solves all three problems by making both files build outputs, not human-authored sources:

The data flow

Both tools are idempotent and additive. They use content-hash deduplication, so running the same sync twice in a row produces zero file changes. They also use atomic write (temp file + rename), so a crash mid-write never leaves a half-baked file.

forge_sync_instructions — the "always true" file

forge_sync_instructions generates .github/copilot-instructions.md by composing four sources, in this order:

1. Project Profile (docs/plans/PROJECT-PROFILE.md), the tech stack, build commands, key paths. Generated once via the project-profile.prompt.md in Session 1.
2. Project Principles (docs/plans/PROJECT-PRINCIPLES.md), non-negotiable architectural and engineering commitments. Generated via project-principles.prompt.md.
3. Extra instruction files (.github/instructions/*.instructions.md), auto-loaded by Copilot via their applyTo frontmatter. The trilogy stitches the relevant ones into the master file so Copilot sees them as a single context.
4. .forge.json commitments, tech choices that the project has locked in (e.g. "database": "postgres", "frontend": "react").

The output is a single Markdown file ~150–400 lines (depends on profile complexity) with a deterministic structure: Identity → Stack → Build commands → Architectural rules → Forbidden patterns → Cost guardrails → Talking to Plan Forge tools.

Running it

# Generate (preview only, does not write)
pforge sync-instructions --preview

# Generate and write
pforge sync-instructions

# Force overwrite even if file is identical (skips hash check)
pforge sync-instructions --force

forge_sync_instructions({ preview: true })
// → { ok: true, written: false, diff: "...", contentHash: "sha256:..." }

forge_sync_instructions({ preview: false })
// → { ok: true, written: true, path: ".github/copilot-instructions.md", contentHash: "..." }

What the output looks like

The generated file follows a canonical template so that Copilot Chat's prompt-injection logic finds the same anchors every time:

# Instructions for Copilot

> **Project**: <name>
> **Stack**: <stack summary>
> **Generated by**: forge_sync_instructions @ v3.x

## Architecture Principles
<merged from architecture-principles.instructions.md + project-principles>

## Project Overview
<merged from PROJECT-PROFILE.md>

## Quick Commands
<merged from project profile + .forge.json>

## Coding Standards
<stack-specific from instructions/>

## Planning & Execution
<pipeline + prompts overview>

## Cost Estimates
<always-included; mandates forge_estimate_quorum>

## Talking to Forge-Master
<always-included; mandates forge_master_ask for open-ended reasoning>

forge_sync_memories — the "we learned this" file

forge_sync_memories generates .github/copilot-memory-hints.md by harvesting three runtime sources:

1. Trajectories (.forge/trajectories/*.jsonl), per-slice notes the worker left for itself: "I tried X, it failed because Y, so I switched to Z". These are the gold for "don't repeat this mistake" guidance.
2. Auto-skills (.forge/auto-skills/*.md), reusable patterns extracted by the Inner Loop. If three slices all needed the same shape of repository test, the fourth slice gets it for free as a skill, and Copilot Chat should know it exists too.
3. OpenBrain entries (L3, if configured), long-form lessons captured via forge_memory_capture or auto-stamped by tools like forge_run_plan.

Each source is filtered, hashed, deduped, and ranked by recency × signal strength. The output is bounded to ~80–120 lines so Copilot's context budget stays healthy.

Running it

# After every plan ships
pforge sync-memories

# Limit to last N trajectories (default: 50)
pforge sync-memories --since=14d

# Verbose: show which entries were included/excluded and why
pforge sync-memories --explain

What the output looks like

# Copilot Memory Hints

> **Generated by**: forge_sync_memories @ v3.x
> **Last sync**: 2026-05-17T14:22:11Z · 47 trajectories, 12 auto-skills, 8 brain entries

<!-- pforge:auto -->

## Recently learned patterns
- **Snapshot pop** uses `git stash apply` + explicit drop, not blind `git stash pop` (lesson from #201)
- **Vitest output parser** ignores subagent hallucination markers (lesson from #198)
- ...

## Auto-skills available
- `repository-vitest-pattern`, generated 2026-05-12 from 4 slices
- `bicep-rbac-scaffold`, generated 2026-05-10 from 3 slices

<!-- /pforge:auto -->

<!-- pforge:custom -->
<!-- Anything you write here is preserved across syncs -->
<!-- /pforge:custom -->

The Settings → Copilot dashboard tab

If you'd rather see the diff before it lands, open the dashboard and navigate to Settings → Copilot. The tab gives you four panels:

Backed by three REST endpoints (full reference: Appendix W — Copilot integration):

GET  /api/copilot-instructions         # read current file
POST /api/copilot-instructions/preview # generate without writing
POST /api/copilot-instructions/sync    # generate + write atomically

When to run what

Capability summary

For the full tool-by-tool reference, see docs/capabilities.md on GitHub. The three trilogy surfaces, at a glance: