iFacto Playbook VS Code Extension

Troubleshooting guidance and repair options

🔄 BCCopilotGuidance Update Management

Commit-based update tracking - Uses Git commit ID- 🗂️ Organized file structure: Config file stored in .github folder alongside other BCCopilotGuidance files
📊 Installation metadata: Tracks commit ID, installation date, repository URL, and target folder
🔒 Reliable cleanup: Improved temporary directory cleanup with multiple fallback methods
⚡ Auto-Fix Actions: "Fix Issues" button automatically executes setup/update commands instead of manual instructionso precisely track installed versions
Configuration management - Stores installation metadata in .github/.bccopilot-guidance-config.json
Automatic update detection - Compares local vs remote commit IDs to detect when updates are available
Status bar notifications - Shows "$(sync) BCG Update" when updates are available
Smart notifications - Alerts for updates without overwhelming users
One-click updates - Update directly from status bar or notifications
Reliable validation - Config-based validation ensures accurate installation detection

🔐 Multiple Authentication Methodsutomates setup and configuration for iFacto development environments**

Overview

The iFacto Playbook VS Code Extension streamlines the onboarding process for iFacto developers by automating the installation and configuration of:

Model Context Protocol (MCP) servers from the iFacto Playbook
GitHub Copilot instructions from the BCCopilotGuidance project
Development environment validation and health checks
Authentication setup for Azure DevOps and internal systems

Features

🚀 One-Click Environment Setup

Complete development environment configuration with a single command
Automated installation of all required MCP servers
GitHub Copilot instruction provisioning
Environment validation and troubleshooting

⚡ Prerequisites Installation (NEW!)

Automatic prerequisites detection - Checks for Node.js 18+ and Azure CLI
One-click installation - Install both Node.js and Azure CLI automatically
Individual installation options - Install Node.js or Azure CLI separately
Smart error handling - Clear guidance when automatic installation fails
Cross-platform support - Works on Windows, macOS, and Linux
Multiple installation methods - Uses winget, Homebrew, or direct download as appropriate

🔧 Modular Setup Options

Install Prerequisites: Check and install Node.js and Azure CLI
Install MCP Servers: Install Model Context Protocol servers individually
Setup Copilot Instructions: Configure GitHub Copilot with BC development guidance
Validate Environment: Check current setup and identify issues
Setup Wizard: Guided setup experience with step-by-step instructions

📊 Setup Status Monitoring

Real-time status view showing configuration progress
Health checks for prerequisites, authentication, and installed components
Troubleshooting guidance and repair options

� Multiple Authentication Methods

Azure CLI integration (recommended)
VS Code Azure Account extension support
Personal Access Token fallback
Automatic credential validation

Usage

Quick Start

Open Command Palette (Ctrl+Shift+P)
Run "iFacto: Show Setup Wizard"
Follow the guided setup process

Prerequisites Installation

If you get errors about missing Node.js or Azure CLI, use these commands:

Check What's Missing

Command Palette → "iFacto: Check Prerequisites Status"

This shows which prerequisites are installed and which are missing.

Install Everything Automatically

Command Palette → "iFacto: Install Prerequisites (Node.js + Azure CLI)"

This will:

Check current versions of Node.js and Azure CLI
Automatically install or update missing components
Use the best installation method for your platform (winget, Homebrew, direct download)
Provide clear guidance if automatic installation fails

Install Individual Prerequisites

Command Palette → "iFacto: Install Node.js"
Command Palette → "iFacto: Install Azure CLI"

Platform-Specific Installation Methods

Windows: Uses winget (preferred) or PowerShell with direct download
macOS: Uses Homebrew (preferred) or direct download
Linux: Uses package managers or official installation scripts

Troubleshooting Prerequisites

If automatic installation fails:

Permission Issues: Try running VS Code as Administrator (Windows) or using sudo
Network Issues: Check internet connection and firewall settings
Manual Installation: The extension will provide direct links to official installers
Corporate Environments: Contact IT support if installation is blocked by policies

BCCopilotGuidance Quick Start

For Business Central projects, set up GitHub Copilot guidance:

Open your AL project in VS Code
Open Command Palette (Ctrl+Shift+P)
Run "iFacto: BCCopilotGuidance: Setup"
Select your workspace folder (if multiple)
Files downloaded to .github/BCCopilotGuidance/
Repository instructions created at .github/copilot-instructions.md
Ready! GitHub Copilot now has access to BC development guidance

Validation & Auto-Fix: The extension automatically validates your setup when opening AL files and provides actionable feedback. Click "Fix Issues" to automatically run the appropriate setup or update commands - no manual intervention required!

Available Commands

Command	Description
`iFacto: Show Setup Wizard`	Open guided setup experience
Prerequisites Management
`iFacto: Check Prerequisites Status`	Check Node.js and Azure CLI installation status
`iFacto: Install Prerequisites (Node.js + Azure CLI)`	Automatically install both Node.js and Azure CLI
`iFacto: Install Node.js`	Install Node.js 18+ automatically
`iFacto: Install Azure CLI`	Install Azure CLI for authentication
`iFacto: Install Azure DevOps CLI Extension`	Install Azure DevOps CLI extension
`iFacto: Troubleshoot Azure DevOps CLI Extension`	Troubleshoot Azure DevOps CLI extension issues
`iFacto: Azure Login`	Authenticate with Azure services
MCP and Configuration
`iFacto: Install MCP Servers`	Install Model Context Protocol servers
`iFacto: Remove iFacto Playbook MCP Servers`	Remove all iFacto Playbook MCP servers
`iFacto: Setup Copilot Instructions`	Configure GitHub Copilot guidance
`iFacto: Validate Environment`	Check current setup status
BCCopilotGuidance
`iFacto: BCCopilotGuidance: Setup`	Complete BCCopilotGuidance setup (files + repo instructions)
`iFacto: BCCopilotGuidance: Update`	Update BCCopilotGuidance files and refresh repo instructions
`iFacto: BCCopilotGuidance: Validate`	Validate BCCopilotGuidance installation
`iFacto: Check for BCCopilotGuidance Updates`	Manually check for BCCopilotGuidance updates
Advanced/Debug Commands
`iFacto: Switch DevOps Organization`	Switch Azure DevOps organization
`iFacto: Test Azure DevOps MCP Configuration`	Test Azure DevOps MCP Configuration (Debug)

BCCopilotGuidance Commands

The extension includes streamlined commands for managing Business Central Copilot guidance:

Command	Description
`iFacto: BCCopilotGuidance: Setup`	Complete setup: downloads files and creates repository instructions
`iFacto: BCCopilotGuidance: Update`	Updates existing files and refreshes repository instructions
`iFacto: BCCopilotGuidance: Validate`	Validate BC Copilot guidance installation

Simplified BCCopilotGuidance Workflow

Step 1: Setup - Use BCCopilotGuidance: Setup command for initial installation:

New installation: Downloads BC Copilot guidance files to .github/BCCopilotGuidance
Creates configuration file: Stores commit ID and installation metadata in .github/.bccopilot-guidance-config.json
Creates repository instructions: Automatically generates .github/copilot-instructions.md if it doesn't exist
Existing installation: Detects previous installations using config file and offers update options
Preserves customizations: Never overwrites existing .github/copilot-instructions.md
Automatic .gitignore: Adds entries to prevent committing copied files and config file

Step 2: Update - Use BCCopilotGuidance: Update command for refreshing:

Commit-based updates: Compares installed commit ID with latest remote commit to determine if updates are needed
Updates files: Downloads latest version of BCCopilotGuidance files when changes are detected
Updates configuration: Refreshes .github/.bccopilot-guidance-config.json with new commit ID and timestamp
Refreshes instructions: Always regenerates .github/copilot-instructions.md with current file links
Validates prerequisites: Ensures existing installation before updating using config-based validation

Step 3: Validate - Use BCCopilotGuidance: Validate command for verification:

Config-based validation: Uses .github/.bccopilot-guidance-config.json to accurately detect installations
AL project detection: Automatically detects Business Central projects
Installation validation: Checks for required configuration and proper structure
Update status: Shows whether installed version matches latest available commit
Quick fixes: One-click automatic fix execution - "Fix Issues" button runs setup/update commands automatically
Automatic validation: Runs when AL files are opened, with improved accuracy

Key Implementation Features:

🚫 Excludes dot folders: Automatically skips .git, .github, and .vscode folders during copy
📝 Intelligent instruction management: Creates repo instructions only when needed, preserves existing customizations
🧹 Clean gitignore management: Automatically adds/removes .github/BCCopilotGuidance/ and config file entries
⚡ One-command setup: Complete setup from download to repository configuration with commit tracking
🔍 Config-based validation: Uses .github/.bccopilot-guidance-config.json for accurate installation detection
🔄 Commit-based updates: Precise update detection using Git commit IDs instead of file modification times
�️ Organized file structure: Config file stored in .github folder alongside other BCCopilotGuidance files
📊 Installation metadata: Tracks commit ID, installation date, repository URL, and target folder
🔒 Reliable cleanup: Improved temporary directory cleanup with multiple fallback methods

Setup Status View

The extension adds a "iFacto Setup Status" view to the Explorer panel showing:

✅ Prerequisites validation
🔐 Authentication status
🤖 MCP servers installation
📝 Copilot instructions setup

Status Bar Integration:

BCCopilotGuidance update notifications - Shows "$(sync) BCG Update" when updates are available
Click-to-update functionality for quick updates
Automatic hiding when no updates are needed

Click any item to run the associated setup command.

Configuration

Extension Settings

Setting	Description	Default
`ifacto-playbook.autoSetupCopilot`	Automatically setup copilot instructions	`true`
`ifacto-playbook.checkBCCopilotGuidanceForUpdates`	Check for updates to BCCopilotGuidance content	`true`
`ifacto-playbook.logLevel`	Logging level for diagnostic information	`"info"`

Authentication Configuration

The extension supports multiple authentication methods:

Azure CLI (Recommended)
```
az login
```
VS Code Azure Account Extension
- Install the Azure Account extension
- Sign in through the Azure Account panel
Personal Access Token
- Generate a PAT at: https://dev.azure.com/iFactoAcademy/_usersSettings/tokens
- The extension will prompt for the token if other methods fail

MCP Servers Installed

The extension automatically installs these MCP servers:

Azure DevOps MCP Server (@azure-devops/mcp): Azure DevOps integration for iFactoCustomers organization
AL Dependency MCP Server (al-mcp-server): AL project dependency analysis
AL Object ID MCP Server (@sshadows/objid-mcp): AL object ID management and tracking for Business Central projects
Microsoft Learn MCP Server (HTTP): Official Microsoft documentation and training workflows
Jira MCP Server (@aashari/mcp-server-atlassian-jira): Atlassian Jira integration (interactive API token setup)
Confluence MCP Server (@aashari/mcp-server-atlassian-confluence): Atlassian Confluence integration (interactive API token setup)
Mantis IssueTracker MCP Server (mantis-mcp-server): iFacto's issue tracking system (interactive API token setup)

Note: For Jira, Confluence, and Mantis MCP servers, the extension will guide you through generating and entering your API token with a user-friendly workflow ("Open Link" and "Continue" dialogs), making setup seamless and secure.

BCCopilotGuidance Integration

The extension provides seamless integration with the BCCopilotGuidance project by downloading and managing comprehensive GitHub Copilot instructions specifically designed for Business Central development.

What BCCopilotGuidance Provides

🎯 Downloaded Content Includes:

Expert AI Guidance Files: Specialized BC development instructions and patterns
AI Specialist Personas: Documentation for specialized BC development experts (Alex Architect, Casey Copilot, Dean Debug, Jordan Bridge)
Development Workflows: Structured approaches for BC project lifecycle management
Code Quality Standards: Enforced best practices for AL development
Business Context Integration: Ensures code includes proper business reasoning and error handling

📚 Comprehensive Documentation:

Core Development Patterns: Essential BC development practices and architectures
Modern AL Patterns: Advanced techniques and contemporary approaches
Testing & Validation: Quality assurance strategies and validation workflows
Performance Optimization: System tuning and efficiency guidelines
Integration & Deployment: Deployment strategies and system integration patterns

🔒 Mandatory Compliance Framework:

Template Project Protection: Prevents premature coding on minimal projects
English-Only Identifiers: Enforces naming conventions for international teams
Quality Gates: Ensures every AI response meets BC development standards
Business Context Requirements: Mandates business reasoning in all technical suggestions

Automatic AL Project Detection

The extension automatically detects AL (Application Language) projects by looking for:

app.json files in workspace folders
.al source files

When an AL project is detected, the extension validates the BCCopilotGuidance setup and provides actionable feedback.

BCCopilotGuidance Implementation Workflow

Setup: Use BCCopilotGuidance: Setup to download guidance files from Azure DevOps and create repository instructions
Update: Use BCCopilotGuidance: Update to refresh downloaded files and regenerate repository instructions
Validate: Use BCCopilotGuidance: Validate to verify installation and get actionable feedback

File Structure Created

When BCCopilotGuidance files are downloaded, they create this structure:

.github/
├── .bccopilot-guidance-config.json  # Installation metadata and commit tracking (excluded from git)
├── BCCopilotGuidance/               # Downloaded guidance files (excluded from git)
│   ├── copilot-instructions.md      # Main copilot instructions
│   ├── README.md                    # BCCopilotGuidance overview
│   ├── bc-specialists/              # AI specialist personas
│   ├── core-development/            # BC development patterns
│   ├── copilot-techniques/          # AI-specific guidance
│   └── ...                          # Additional guidance folders
├── chatmodes/                       # Chat mode configurations (excluded from git)
│   ├── alex-architect.chatmode.md   # Architecture specialist
│   ├── casey-copilot.chatmode.md    # General BC development
│   └── ...                          # Other specialist chat modes
├── prompts/                         # Prompt templates (excluded from git)
│   ├── pullrequest.prompt.md        # Pull request analysis prompts
│   └── ...                          # Other prompt templates
└── copilot-instructions.md          # Repository instructions (committed to git)

Configuration File Details: The .github/.bccopilot-guidance-config.json file contains:

lastInstalledCommit: Git commit ID of the installed BCCopilotGuidance version
installDate: Timestamp of when BCCopilotGuidance was installed/updated
targetFolder: Target directory for BCCopilotGuidance files (.github/BCCopilotGuidance)
repositoryUrl: Source repository URL for updates and validation

Repository Instructions Generation

The Setup and Update commands automatically create a comprehensive .github/copilot-instructions.md file that:

🚨 Enforces Mandatory Compliance:

Uses applyTo: '**' frontmatter to apply to all files
Establishes non-negotiable enforcement points for AI agents
Requires full compliance with BCCopilotGuidance standards
Includes quality gates and validation checklists

📚 Provides Complete Documentation Access:

References all downloaded BCCopilotGuidance documentation by category
Links to specialist AI personas with direct file paths
Organizes guidance into logical sections (Core Development, Specialists, etc.)
Maintains current file structure with automatic link updates

🔒 Ensures Development Standards:

Template project protection workflows
English-only identifier enforcement
Business context and error handling requirements
Escalation paths for non-compliance

This ensures that GitHub Copilot has access to all relevant Business Central development guidance and operates under strict compliance requirements when working in your repository.

Recent Improvements (v0.1.0)

🔧 Enhanced BCCopilotGuidance Management

Commit-based Update System: Replaced file-based update detection with precise Git commit tracking
Configuration Management: Added .github/.bccopilot-guidance-config.json for reliable installation state tracking
Improved Validation: Config-based validation eliminates false negatives and provides accurate installation detection
Better File Organization: Config file stored alongside other BCCopilotGuidance files in .github folder
Robust Cleanup: Enhanced temporary directory cleanup with multiple fallback methods and error handling
Unified Command Experience: Both "Setup" and "Manage BCCopilotGuidance Files" commands now create config files

🎯 Technical Enhancements

Cross-platform Compatibility: Improved cleanup using VS Code filesystem API with PowerShell fallback
Error Recovery: Non-blocking configuration creation - setup completes successfully even if config creation fails
Debug Logging: Enhanced console output for troubleshooting installation and update processes
Gitignore Management: Automatic inclusion of config file in gitignore to prevent accidental commits
Repository URL Consistency: Unified repository URL handling across setup and management commands

Architecture

Extension Structure

src/
├── commands/          # Command implementations
│   ├── setupEnvironment.ts
│   ├── installMcpServers.ts
│   ├── removeAllMcps.ts
│   ├── setupCopilotInstructions.ts
│   ├── validateEnvironment.ts
│   ├── showSetupWizard.ts
│   ├── installAzureCli.ts
│   ├── testAzureDevOpsMcp.ts
│   ├── setupBCCopilotGuidance.ts          # Combined BC guidance setup and update
│   └── validateBCCopilotGuidance.ts       # BC guidance validation
├── services/          # Core business logic
│   ├── mcpService.ts     # MCP installation and management
│   ├── authService.ts    # Authentication handling
│   └── gitService.ts     # Git/repository operations
├── ui/                # User interface components
│   └── setupStatusView.ts # Setup status tree view
├── utils/             # Shared utilities
│   ├── logger.ts         # Logging utilities
│   ├── fileUtils.ts      # File system operations
│   ├── bcGuidanceConfigManager.ts  # BCCopilotGuidance configuration management
│   ├── gitignoreUtils.ts # Gitignore file management
│   └── alProjectValidator.ts  # AL project detection and BC guidance validation
└── extension.ts       # Main extension entry point

Key Dependencies

vscode: VS Code Extension API
axios: HTTP client for API calls
simple-git: Git operations
fs-extra: Enhanced file system operations

License

Internal use only - iFacto Academy

BCCopilotGuidance - GitHub Copilot instructions for BC development
iFacto Playbook - Development environment documentation
BCCopilotGuidanceMCPServer - BC guidance MCP server implementation

Built with ❤️ by the DevLead team to make developer onboarding effortless!

iFacto Playbook

ifacto