iFacto Playbook VS Code Extension
Automates setup and configuration for iFacto development environments
Overview
The iFacto Playbook VS Code Extension streamlines the onboarding process for developers by automating the installation and configuration of:
- Model Context Protocol (MCP) servers from company-specific configurations
- BC Code Intelligence with company guidelines (recommended for Business Central)
- Development environment validation and health checks
- Authentication setup for Azure DevOps and internal systems
- Multi-company support through configurable company profiles
🏢 Company Profile System
New in v0.2.0: The extension now supports multiple companies through Company Profiles.
What is a Company Profile?
A company profile is a pre-configured set of settings that defines:
- Azure DevOps organization(s) and repository locations
- Atlassian (Jira/Confluence) site configurations
- Issue tracker system settings (Mantis, Jira, etc.)
- Company branding and documentation URLs
Selecting Your Company Profile
First Time Setup:
- Open Command Palette (Ctrl+Shift+P)
- Run:
iFacto: Select Company Profile
- Choose your company from the list
- The extension automatically configures all services for your company
Changing Profile:
Run iFacto: Select Company Profile anytime to switch companies.
Available Profiles
- iFactoBE - iFacto Belgium configuration (@ifacto.be, 'ifacto' Atlassian site)
- iFactoNL - iFacto Netherlands configuration (@ifacto.nl, 'ifactonl' Atlassian site)
- Template - Placeholder profile for adding new companies (see documentation)
Note: Each profile configures different Atlassian sites and email domains, ensuring MCPs connect to the correct systems.
Adding or Editing Company Profiles
Quick Start: See 5-Minute Quick Start Guide
Complete Documentation:
Key Points When Adding/Editing:
- ✅ Update both
companyProfiles.ts AND package.json
- ✅ Email domain must include '@' (e.g.,
'@ifacto.nl')
- ✅ Atlassian site names differ by region (e.g.,
'ifacto' vs 'ifactonl')
- ✅ Always test with Jira MCP installation to verify settings
- ✅ Reload VS Code after changes
Features
🎯 BC Code Intelligence (Recommended for Business Central)
- User-level MCP configuration - Applies company standards to all Business Central projects
- Automatic update detection - Checks for BCCompanyGuidelines updates every 4 hours
- Status bar notifications - Shows "$(cloud-download) BC Code Intel Update" when updates available
- One-click updates - Click status bar to update to latest company guidelines
- Workspace copilot files sync - Automatically copies agents and prompts to
.github folder
- Azure CLI authentication - Seamless Azure DevOps integration
- Version tracking - Tracks installed version for accurate update detection
- Legacy migration - Automatic detection and migration from BCCopilotGuidance
🚀 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
BC Code Intelligence Quick Start (Recommended for Business Central)
For Business Central development, set up BC Code Intelligence MCP:
- Ensure Prerequisites: Azure CLI installed and authenticated (
az login)
- Open Command Palette (Ctrl+Shift+P)
- Run "iFacto: Setup BC Code Intelligence"
- Configuration created in
~/.bc-code-intel/config.json
- Agents and prompts synced to workspace
.github folder
- Ready! Company standards now apply to all your BC projects
Automatic Updates: Extension checks for updates every 4 hours. Click the status bar notification to update instantly.
Legacy Migration: If you have BCCopilotGuidance installed, the extension will prompt you to migrate to BC Code Intelligence for a better experience.
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"
- 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
Available Commands
| Command |
Description |
|
|
|
| Company Profile |
|
|
|
|
iFacto: Select Company Profile |
Choose your company profile for automated configuration |
|
|
|
| Setup & Configuration |
|
|
|
|
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 |
|
|
|
| BC Code Intelligence (Recommended) |
|
|
|
|
iFacto: Setup BC Code Intelligence |
Setup BC Code Intel MCP with iFacto company guidelines |
\n |
iFacto: Check for BC Code Intel Updates |
Manually check for BCCompanyGuidelines updates |
iFacto: Migrate to BC Code Intelligence |
Migrate from legacy BCCopilotGuidance to BC Code Intel |
|
|
|
| Advanced/Debug Commands |
|
|
|
|
iFacto: Switch DevOps Organization |
Switch Azure DevOps organization |
|
|
|
iFacto: Test Azure DevOps MCP Configuration |
Test Azure DevOps MCP Configuration (Debug) |
|
|
|
BC Code Intelligence Setup (Recommended)
|---------|-------------|
| 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
BC Code Intelligence Setup
The extension provides an alternative setup option using bc-code-intel MCP with iFacto company guidelines. This is a user-level configuration that applies to all Business Central projects.
What is BC Code Intelligence?
BC Code Intelligence is an MCP server that provides AI-powered Business Central development guidance through a layered knowledge system:
- Embedded Layer (Priority 0): Core BC knowledge from bc-code-intelligence-mcp
- Company Guidelines (Priority 25): iFacto standards from Azure DevOps (BCCompanyGuidelines repository)
- Project Overrides (Priority 100): Local
./bc-code-intel-overrides/ folder for project-specific rules
Setup BC Code Intelligence
Prerequisites:
- Azure CLI installed and authenticated (
az login)
- Git installed
- Access to iFacto Azure DevOps organization
Setup Command:
Command Palette → "iFacto: Setup BC Code Intelligence"
What This Does:
- Configures Git for Azure DevOps: Sets
useHttpPath for Azure DevOps authentication
- Creates user-level config: Places
bc-code-intel-config.json in your home directory
- Syncs Copilot Files: Copies agents and prompts from BCCompanyGuidelines to workspace
.github folder
- Verifies MCP server: Ensures
bc-code-intelligence is configured in VS Code MCP settings
- Configures company layer: Points to iFacto's BCCompanyGuidelines repository in Azure DevOps
Configuration Locations:
- User Config:
- Windows:
C:\Users\{username}\.bc-code-intel\config.json
- macOS:
/Users/{username}/.bc-code-intel/config.json
- Linux:
/home/{username}/.bc-code-intel/config.json
- Workspace Copilot Files:
.github/agents/ and .github/prompts/ (synced from BCCompanyGuidelines)
- Version Tracking:
.github/.ifacto-bccodeintel-version.json (tracks installed version for update detection)
MCP Configuration: The extension automatically adds the bc-code-intelligence MCP server to your VS Code settings if not already present.
GitHub Copilot Integration: The setup also copies company-specific agents and prompts to your workspace's .github folder, making them available to GitHub Copilot chat as custom agents and prompt libraries.
Automatic Update Detection: The extension checks for updates to BCCompanyGuidelines every 4 hours:
- Status Bar Notification: Shows "$(cloud-download) BC Code Intel Update" when updates are available
- Click to Update: Click the status bar notification to run Setup BC Code Intelligence and update to the latest version
- Version Tracking: Installation version is tracked in
.github/.ifacto-bccodeintel-version.json
- Manual Update: Re-run "Setup BC Code Intelligence" command anytime to get the latest company guidelines
BC Code Intelligence vs Legacy BCCopilotGuidance
BC Code Intelligence is the recommended approach for Business Central development:
| Feature |
BC Code Intelligence (Recommended) |
BCCopilotGuidance (Legacy) |
| Scope |
User-level (all projects) |
Project-level (per workspace) |
| Configuration |
~/.bc-code-intel/config.json |
.github/copilot-instructions.md |
| Company Guidelines |
Auto-synced from Azure DevOps |
Downloaded files in .github/ |
| Updates |
Automatic every 4 hours |
Manual commands (deprecated) |
| Project Overrides |
Local bc-code-intel-overrides/ |
Project-specific instructions |
| Status |
✅ Active & Supported |
⚠️ Legacy - Migration Recommended |
| Best For |
All BC developers |
Legacy projects only |
Migration: If you're using BCCopilotGuidance, the extension will automatically detect this and prompt you to migrate to BC Code Intelligence for a better experience.
Setup Status View
The extension adds a "iFacto Setup Status" view to the Explorer panel showing:
- ✅ Prerequisites validation
- 🔐 Authentication status
- 🤖 MCP servers installation
- 📝 BC Code Intelligence setup status
Status Bar Integration:
- BC Code Intel update notifications - Shows "$(cloud-download) BC Code Intel Update" when updates are available
- Click-to-update functionality for instant 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.companyProfile |
Company profile selection - Configures Azure DevOps, Atlassian, and other company-specific settings. Options: iFactoBE (Belgium), iFactoNL (Netherlands), template |
"iFactoBE" |
ifacto-playbook.autoSetupCopilot |
Automatically setup copilot instructions |
true |
ifacto-playbook.checkBCCodeIntelForUpdates |
Check for updates to BC Code Intel (BCCompanyGuidelines) content |
true |
ifacto-playbook.logLevel |
Logging level for diagnostic information |
"info" |
Note: The companyProfile setting is the first thing you should configure. It determines which Azure DevOps organization, Atlassian sites, and other services the extension connects to.
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
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.
BC Code Intelligence Features
BC Code Intelligence provides a comprehensive MCP-based solution for Business Central development with iFacto company guidelines integration.
What BC Code Intelligence Provides
🎯 Core Capabilities:
- Layered Knowledge System: Embedded BC knowledge + Company guidelines + Project overrides
- Automatic Updates: Extension checks for company guideline updates every 4 hours
- User-Level Configuration: One setup applies to all BC projects on your machine
- Azure DevOps Integration: Seamless authentication via Azure CLI
- Workspace File Sync: Company-specific agents and prompts copied to workspace
.github folder
📚 Company Guidance Integration:
- AI Specialist Personas: iFacto-specific BC development experts (Waldo, Isabelle, etc.)
- Development Standards: Mandatory iFacto coding patterns and conventions
- Code Quality Rules: Enforced best practices for AL development
- Documentation Standards: Required documentation patterns and templates
🔄 Automatic Update Management:
- Background Checks: Every 4 hours, extension compares local vs remote versions
- Status Bar Notifications: Visual indicator when updates are available
- One-Click Updates: Click status bar to update to latest company guidelines
- Version Tracking:
.ifacto-bccodeintel-version.json tracks installed version
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 BC Code Intelligence setup and provides actionable feedback.
BC Code Intelligence File Structure
BC Code Intelligence creates the following structure:
User-Level Configuration:
~/.bc-code-intel/
└── config.json # User-level MCP configuration
Workspace Files:
.github/
├── .ifacto-bccodeintel-version.json # Version tracking (excluded from git)
├── agents/ # Company-specific AI agents (synced from BCCompanyGuidelines)
│ ├── iFacto.ALCoder.agent.md
│ ├── iFacto.CodeReviewer.agent.md
│ └── ... # Other company agents
└── prompts/ # Prompt templates (synced from BCCompanyGuidelines)
├── documentation.full.prompt.md
└── ... # Other prompt templates
Configuration Details:
The user-level config.json contains:
- MCP server configuration for bc-code-intel
- Company guidelines layer pointing to iFacto BCCompanyGuidelines repository
- Azure DevOps authentication settings (using Azure CLI)
- Git configuration for Azure DevOps integration
The .ifacto-bccodeintel-version.json file contains:
version: Commit ID from BCCompanyGuidelines repositorycommitMessage: Latest commit messagetimestamp: When the version was installed/updatedconfigPath: Path to user-level bc-code-intel config
Legacy BCCopilotGuidance Migration
For users with existing BCCopilotGuidance installations:
Automatic Detection:
- Extension detects
.github/.bccopilot-guidance-config.json on startup
- Shows migration notification with "Migrate Now" option
Migration Process:
- Backup prompt: Confirms user wants to migrate
- Legacy cleanup: Removes entire
.github folder
- BC Code Intel setup: Runs Setup BC Code Intelligence command
- Fresh start: User-level configuration + workspace file sync
Why Migrate:
- ✅ User-level scope (applies to all BC projects)
- ✅ Automatic updates (no manual refresh needed)
- ✅ Simpler maintenance (one configuration for all projects)
- ✅ Better integration
v0.2.0 - Multi-Company Support (January 2026)
Latest (January 21, 2026) - Multi-Region Support:
- iFactoBE & iFactoNL Profiles: Separate profiles for Belgium and Netherlands operations
- Region-Specific Atlassian: Each profile uses correct Jira/Confluence site (
ifacto vs ifactonl)
- Region-Specific Email Domains: Prompts show correct email domain (
@ifacto.be vs @ifacto.nl)
- Profile System Fixes: All commands now correctly use selected profile settings
- Comprehensive Documentation:
Initial Release (January 16, 2026):
- Company Profile System: Configure extension for different companies with one selection
- Template Profile: Easy-to-use template for adding new company configurations
- Automatic Profile Detection: Extension prompts for profile selection on first use
- Profile-Based MCP Installation: All MCP servers automatically use company-specific settings
v0.1.0 - December 2025
- ✅ Continued support and updates
Recent Improvements (v0.1.0 - December 2025)
🎯 BC Code Intelligence Migration (December 20-22, 2025)
- User-Level MCP Configuration: Transitioned from project-level BCCopilotGuidance to user-level BC Code Intelligence
- Automatic Update Detection: Extension checks for BCCompanyGuidelines updates every 4 hours with status bar notifications
- Legacy Migration Support: Automatic detection of BCCopilotGuidance installations with guided migration workflow
- Azure CLI Authentication: Seamless Azure DevOps integration using
az_cli authentication
- Version Tracking System: Precise update detection using commit-based versioning
- Workspace File Sync: Automatic synchronization of company agents and prompts to workspace
.github folder
- Status Bar Integration: Click status bar notification to instantly update to latest company guidelines
🔧 Technical Enhancements
- Version Tracking Service: New
versionTrackingService.ts for BC Code Intel version management
- Update Notification Service: New
bcCodeIntelNotificationService.ts for background update checks
- Legacy Config Checker: New
legacyConfigChecker.ts for automatic BCCopilotGuidance detection
- Cross-platform Compatibility: Improved setup process across Windows, macOS, and Linux
- Error Recovery: Enhanced error handling with clear user feedback
- Debug Logging: Comprehensive console output for troubleshooting
🧹 Cleanup & Deprecation
- BCCopilotGuidance Deprecated: Removed BCCopilotGuidance setup, update, and validate commands from command palette
- Unified Validation: AL project validation now exclusively checks for BC Code Intelligence
- Streamlined Commands: Simplified command structure focusing on BC Code Intelligence
- Documentation Updates: All documentation updated to reflect BC Code Intelligence as primary approach
Architecture
Extension Structure
src/
├── commands/ # Command implementations
│ ├── setupBCCodeIntel.ts # BC Code Intel setup (primary)
│ ├── checkBCCodeIntelUpdates.ts # Manual update checks
│ ├── migrateToBCCodeIntel.ts # Legacy migration
│ ├── installMcpServers.ts # MCP server installation
│ ├── validateEnvironment.ts # Environment validation
│ ├── showSetupWizard.ts # Setup wizard
│ ├── installPrerequisites.ts # Node.js & Azure CLI installation
│ └── ... # Other commands
├── services/ # Core business logic
│ ├── bcCodeIntelUpdateService.ts # BC Code Intel update detection
│ ├── bcCodeIntelNotificationService.ts # Status bar & notifications
│ ├── versionTrackingService.ts # Version management
│ ├── mcpService.ts # MCP installation management
│ ├── authService.ts # Authentication handling
│ └── gitService.ts # Git/repository operations
├── ui/ # User interface components
│ ├── setupStatusView.ts # Setup status tree view
│ ├── devOpsStatusBar.ts # Azure DevOps status bar
│ └── updateNotificationView.ts # Update notification (currently disabled)
├── utils/ # Shared utilities
│ ├── legacyConfigChecker.ts # BCCopilotGuidance detection
│ ├── alProjectValidator.ts # AL project & BC Code Intel validation
│ ├── logger.ts # Logging utilities
│ └── fileUtils.ts # File system operations
└── 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
- BCCompanyGuidelines - iFacto company-specific BC development guidelines (Azure DevOps)
- bc-code-intel - BC Code Intelligence MCP server
- iFacto Playbook - Development environment documentation
Built with ❤️ by the DevLead team to make developer onboarding effortless!
