sync-context

name	sync-context
description	| Use when this capability is needed.

Sync Context Command

Analyzes codebase and intelligently updates .github/copilot-instructions.md with current project context.

Usage

/sync-context                    # Full analysis and update
/sync-context --section agents   # Update specific section
/sync-context --dry-run          # Preview changes without saving

---

What It Does

1. Analyzes current codebase structure
2. Extracts patterns, conventions, and architecture
3. Merges with existing copilot-instructions.md content
4. Preserves manual customizations
5. Updates sections that need refresh

---

Analysis Process

Step 1: Scan Codebase Structure

# Discover project structure
Glob("**/*.py")              # Python files
Glob("**/*.ts")              # TypeScript files
Glob("**/package.json")      # Node projects
Glob("**/pyproject.toml")    # Python projects
Glob("**/Dockerfile")        # Container configs
Glob("**/*.tf")              # Terraform

Step 2: Extract Patterns

# Code patterns
Grep("@dataclass")           # Dataclass usage
Grep("class.*Parser")        # Parser patterns
Grep("def test_")            # Test patterns
Grep("async def")            # Async patterns

# Architecture patterns
Grep("from src")             # Import structure
Grep("@router")              # API patterns
Grep("@lambda_handler")      # Lambda patterns

Step 3: Analyze Agents

# List available agents
Glob(".github/agents/*.agent.md")

# Categorize by name prefix
- workflow-*    → SDD pipeline agents (brainstorm, define, design, build, ship, iterate)
- architect-*   → System design (schema, pipeline, lakehouse, genai, the-planner)
- cloud-*       → AWS, GCP, CI/CD, deployment agents
- fabric-*      → Microsoft Fabric specialists
- python-*      → Code review, clean, document, prompt engineering
- test-*        → Testing, data quality, data contracts
- de-*          → Data engineering: Spark, dbt, Airflow, Lakeflow, streaming, SQL
- dev-*         → Codebase explorer, meeting analyst, prompt crafter

Step 4: Merge Updates

# Sections to update
- Project Structure (from scan)
- Coding Standards (from patterns)
- Agent Usage (from agent analysis)
- Commands (from commands/)
- Environment (from config files)

# Sections to preserve
- Project Context (manual)
- Core Mission (manual)
- Important Dates (manual)
- Getting Help (manual)

---

copilot-instructions.md Template

Generated .github/copilot-instructions.md follows this structure:

# {Project Name}

## Project Context

{Manual: What this project does and why}

---

## Architecture Overview

{Auto-generated from codebase scan}

```text
{Data flow diagram}

Stage	Technology	Purpose
{stage}	{tech}	{purpose}

---

Project Structure

{Auto-generated from Glob scans}

{project}/
├── src/
│   ├── {folders discovered}
├── tests/
├── .github/
│   ├── agents/
│   ├── kb/
│   ├── sdd/
│   ├── skills/
│   └── storage/

---

Agent Usage Guidelines

{Auto-generated from agents/ folder}

Available Agents by Category

Category	Agents	Use When
Workflow	brainstorm-agent, define-agent, ...	Building features with SDD
Code Quality	python-code-reviewer, test-generator, ...	Improving code
{category}	{agents}	{trigger}

---

Coding Standards

{Auto-generated from detected patterns}

Language: {Python/TypeScript/etc}

• Version: {detected from config}
• Style: {detected patterns}
• Testing: {detected framework}

Detected Patterns

Pattern	Usage	Example File
{pattern}	{where used}	{file path}

---

Commands

{Auto-generated from commands/ folder}

Command	Purpose
/build-feature	Full SDD pipeline
/memory	Save session insights
{command}	{purpose}

---

Environment Variables

{Auto-generated from .env.example, config files}

Variable	Purpose
{var}	{purpose}

---

MCP Tools Available

{Auto-generated from settings}

MCP Server	Purpose
context7-mcp	Library documentation
exa	Code context search
{mcp}	{purpose}

---

Important Dates

{Manual: Project-specific dates}

---

Getting Help

{Auto-generated from structure}

• Documentation: Start with relevant docs
• Agents: Review .github/agents/
• Commands: Use /help for available commands

---

## Section Update Rules

| Section | Source | Update Mode |
| ------- | ------ | ----------- |
| Project Context | Manual | Preserve |
| Architecture | Codebase scan | Replace |
| Project Structure | Glob patterns | Replace |
| Agent Usage | agents/ folder | Replace |
| Coding Standards | Pattern detection | Merge |
| Commands | commands/ folder | Replace |
| Environment | Config files | Merge |
| MCP Tools | settings.json | Replace |
| Important Dates | Manual | Preserve |
| Getting Help | Structure | Replace |

**Replace**: Fully regenerate from source
**Merge**: Add new, preserve custom
**Preserve**: Never auto-modify

---

## Execution Flow

```text
1. Read existing .github/copilot-instructions.md
   │
   ▼
2. Parse into sections
   │
   ▼
3. Analyze codebase (parallel)
   ├── Glob for structure
   ├── Grep for patterns
   ├── Read config files
   └── List agents/commands
   │
   ▼
4. Generate new sections
   │
   ▼
5. Apply update rules
   ├── Replace auto sections
   ├── Merge semi-auto sections
   └── Preserve manual sections
   │
   ▼
6. Validate (dry-run or save)
   │
   ▼
7. Write updated .github/copilot-instructions.md

---

Example Output

UPDATE .github/copilot-instructions.md
━━━━━━━━━━━━━━━━

Analyzing codebase...
✓ Found 47 Python files
✓ Found 12 test files
✓ Found 28 agents
✓ Found 8 commands

Detected patterns:
✓ Dataclass pattern (15 usages)
✓ Parser pattern (4 files)
✓ Generator pattern (8 usages)

Section updates:
• Architecture: UPDATED (new components detected)
• Project Structure: UPDATED (3 new folders)
• Agent Usage: UPDATED (2 new agents)
• Coding Standards: MERGED (1 new pattern)
• Commands: UPDATED (1 new command)
• Project Context: PRESERVED (manual content)

━━━━━━━━━━━━━━━━
.github/copilot-instructions.md updated successfully

---

Flags

Flag	Description
--dry-run	Preview changes without saving
--section {name}	Update only specific section
--force	Replace all sections (ignores preserve rules)
--verbose	Show detailed analysis

---

Best Practices

When to Run

• After adding new agents or commands
• After significant architecture changes
• After adding new file types
• When onboarding new team members

What to Customize

After running, manually update:

1. Project Context - Add business context
2. Important Dates - Add milestone dates
3. Architecture - Add business-specific details
4. Coding Standards - Add team conventions

Version Control

# Review changes before committing
git diff .github/copilot-instructions.md

# Commit with context
git add .github/copilot-instructions.md
git commit -m "chore: update copilot-instructions.md with latest project structure"

---

Source: Arthur1511/agentspec-copilot — distributed by TomeVault.