ALDC — AL Agentic Engineering System

Skills-based, spec-driven, TDD-orchestrated development framework for Microsoft Dynamics 365 Business Central.

Engineering systems, visibly reasoned.

ALDC combines specialist agents, reusable domain skills and human approval to support Business Central extension development from requirements to review.

Release status: canonical package and plugin manifests declare 5.0.0. These changes are released as 5.0.0. Previously built VSIX files retain their original version and packaged snapshot. Installing newer source content does not itself publish a Marketplace update.

Capability	What it provides
Architect and Spec Agent	Approved design, bounded Specs, explicit dependencies and joint consistency review before implementation.
Conductor	Planning, implementation and review coordinated through existing human gates.
Doctor	Read-only diagnosis of configuration and operation-specific runtime observations.
Recommended BCQuality	Plugin or external multiroot reviews, with discovery, loading, execution and index evidence distinguished.
BC28 / BC29-native	Explicit Chat profile selection with role-specific tools and AL18 guidance.
Host adapters	Dedicated content for Copilot Chat, Copilot CLI, Claude Code and Codex.
Recoverable installation	Preview, visible collisions, receipts, verification and restoration.

See Spec Agent, profiles, plugins and recovery and Doctor.

Why ALDC?

AI accelerates AL development — but raw code generation is unpredictable, hard to review, and easy to get wrong against Business Central's extension rules. ALDC adds the engineering discipline around it.

Without ALDC	With ALDC
Ad-hoc, one-shot code generation	Contract-driven development (architecture → spec → human approval → test-plan → code)
No checkpoints — you find out at the end	Human-in-the-loop gates at every phase
Tests written last (or never)	TDD-orchestrated — tests FIRST, then code
Base-app edits sneak in	Extension-only by construction
"Looks fine to me" reviews	Cited reviews & audits against BC knowledge

What is ALDC?

ALDC (AL Development Collection) transforms how you develop Business Central extensions. Instead of ad-hoc code generation, it provides structured, contract-driven development with specialized agents, composable skills, and human-in-the-loop gates — with host-specific distributions:

GitHub Copilot — Agents, skills, prompts, and instructions in .github/ and agents/
Claude Code — Agents, skills, rules, and hooks in .claude/ and claude-plugin/
Copilot CLI — Terminal agents and commands in copilot-cli-plugin/
Codex — Generated agent profiles and a local ALDC skill in plugins/aldc-codex/

Updating to 5.0.0

The VS Code extension and each host plugin are separate distribution channels. Updating the VSIX does not refresh installed Claude Code, Copilot CLI or Codex plugins.

In VS Code, open AL Collection: Open Project Manager (also available as a view in the Explorer) to preview and confirm the update, verify the installation, restore the previous transaction and run Doctor without leaving the panel; the ALDC Visor view lists the plan artifacts of each requirement with template-specific icons. The palette command AL Collection: Update Toolkit remains available: review file collisions, verify the installation and reload the window. Existing installations retain their recorded profile. The extension's optional al-collection.autoInstall setting is false by default; when enabled, it attempts installation on AL project detection. Toolkit restoration covers installation files, not Business Central data or all project history. See installation and recovery.

Installation

Choose your surface — installation guide · Guía en castellano

For the opt-in BC29 / AL18 native profile in Copilot Chat, see installation, role changes and local validation. BC28 remains the installer default. Claude Code and the dedicated aldc-cli plugin include terminal-specific BC29/AL18 contracts; see the same guide for checkout-local installation and pending runtime verification. The VS Code extension is published separately.

GitHub Copilot

Install from the VS Code Marketplace or:

code --install-extension javierarmestogonzalez.al-development-collection

Then, from the Command Palette:

AL Collection: Install Toolkit to Workspace — copies the framework into your project's .github/
AL Collection: Update Toolkit — updates toolkit content; review collision behavior in your installed version
AL Collection: Validate Installation — verifies compliance

GitHub Copilot (Plugin Marketplace)

ALDC also ships as an installable Copilot plugin — plugin.json declares the agents (agents/), skills (skills/), and prompts (prompts/) that get installed, for editors that support the Copilot plugin marketplace:

The root plugin retains the VS Code-oriented primitives. For Copilot CLI, use the dedicated terminal distribution from this checkout:

copilot plugin install ./copilot-cli-plugin
copilot plugin list

The catalog entry is aldc-cli@aldc-marketplace. See plugin loading checks and limitations before testing. The directory is generated with npm run sync:copilot-cli.

Claude Code (Plugin)

/plugin install aldc
/aldc:al-initialize

al-initialize copies path-scoped rules to .claude/rules/, generates a project CLAUDE.md, and configures the workspace.

Claude Code (Direct)

Clone this repo and open it with Claude Code. The .claude/ directory and CLAUDE.md are detected automatically.

Quick Start

GitHub Copilot

Install the extension and open your AL project
Run AL Collection: Install Toolkit to Workspace
Start with @workspace use al-spec.create plus your requirement
Follow the guided flow

Claude Code

/plugin install aldc
/aldc:al-initialize
Call any agent: @al-architect, @al-developer, @al-conductor, @al-presales
Or run a workflow: /aldc:al-spec-create

See QUICKSTART.md for the full onboarding guide.

Key Features

🤖 5 Public Agents — one specialist per development phase

Agent	Role
`@AL Architecture & Design Specialist`	Designs solutions, information flows, technical decisions
`@AL Spec Agent`	Specifies approved designs through the shared `al-spec.create` contract
`@AL Implementation Specialist`	Implements, debugs, quick adjustments
`@AL Development Conductor`	Orchestrates TDD implementation with subagents
`@AL Pre-Sales & Project Estimation Specialist`	Estimation and scoping

🔬 3 Internal Subagents — autonomous specialists inside the Conductor

AL Planning Subagent — research and context gathering
AL Implementation Subagent — TDD-only (tests FIRST, code SECOND)
AL Code Review Subagent — review against spec + architecture

🩺 2 On-demand Specialists — user-invocable, read-only on code

@AL Triage — reactive diagnosis: reproduce → root-cause → minimal-fix recommendation
@Dredd — independent auditor: BCQuality-cited static audit with an advisory verdict

🧠 11 Composable Skills — domain knowledge loaded on demand

Required: api · copilot · debug · performance · events · permissions · testing
Recommended: migrate · pages · translate · estimation
Plus skill-contribution-assistant — guided workflow for contributing back to ALDC

⚙️ 6 Workflows — automated processes

al-spec.create · al-build · al-pr-prepare · al-context.create · al-memory.create · al-initialize

📐 9 Instructions — auto-applied coding standards (always active)

al-guidelines · al-code-style · al-naming-conventions · al-performance · al-error-handling · al-events · al-testing · copilot-instructions · index

📚 BCQuality (recommended) — external, citable BC knowledge layer

Optional cited review through an explicitly selected host plugin or external multiroot knowledge base. Agents distinguish discovery, loading, execution and best-effort index generation; unavailable providers retain native A–G coverage. See docs/bcquality.md.

📄 Contracts per Requirement — structured docs in `.github/plans/{req_name}/`

{req_name}.architecture.md — solution design (from architect)
{req_name}.spec.md — technical blueprint (from spec.create)
{req_name}.test-plan.md — test strategy
memory.md — global context across sessions

How It Works

Development Flow

LOW complexity:
  al-spec.create → @AL Implementation Specialist

MEDIUM/HIGH complexity:
  @AL Architecture & Design Specialist → al-spec.create → @AL Development Conductor

The architect designs the solution and can decompose complex requirements into multiple specs, each implemented independently by the conductor.

flowchart TD
    REQ[Requirement] --> CLASSIFY{Complexity?}
    CLASSIFY -->|LOW| SPEC_LOW[al-spec.create]
    SPEC_LOW --> DEV["@AL Implementation Specialist"]

    CLASSIFY -->|MEDIUM/HIGH| ARCH["@AL Architecture & Design Specialist"]
    ARCH -->|Designs solution| ARCH_DOC[architecture.md]
    ARCH --> DECOMPOSE{Decompose?}
    DECOMPOSE -->|Yes| SPEC_A[al-spec.create → spec-A]
    DECOMPOSE -->|Yes| SPEC_B[al-spec.create → spec-B]
    DECOMPOSE -->|No| SPEC_SINGLE[al-spec.create → spec.md]
    SPEC_A --> COND_A["@AL Development Conductor"]
    SPEC_B --> COND_B["@AL Development Conductor"]
    SPEC_SINGLE --> COND["@AL Development Conductor"]

TDD Orchestration

The conductor enforces Test-Driven Development:

flowchart LR
    PLAN[Phase 1\nPlanning] --> IMPL[Phase N\nImplementation]
    IMPL --> REVIEW[Review\nSubagent]
    REVIEW --> HITL{HITL Gate}
    HITL -->|Approved| NEXT[Next Phase]
    HITL -->|Revise| IMPL

    subgraph IMPL_DETAIL[Implement Subagent - TDD]
        RED[RED\nWrite failing tests] --> GREEN[GREEN\nMinimal code]
        GREEN --> REFACTOR[REFACTOR\nAL patterns]
    end

Planning subagent researches context
Implement subagent creates tests FIRST (RED)
Implement subagent writes code to pass tests (GREEN)
Implement subagent refactors to AL patterns (REFACTOR)
Review subagent validates against spec + architecture
Human approves each phase (HITL gate)

Framework Architecture

graph TB
    subgraph PUBLIC["Public Agents (user-invocable)"]
        ARCH["@AL Architecture & Design Specialist"]
        DEV["@AL Implementation Specialist"]
        COND["@AL Development Conductor"]
        PRE["@AL Pre-Sales & Project Estimation Specialist"]
    end

    subgraph INTERNAL["Internal Subagents (conductor-only)"]
        PLAN[AL Planning Subagent]
        IMPL[AL Implementation Subagent]
        REV[AL Code Review Subagent]
    end

    subgraph SKILLS["11 Composable Skills"]
        S1[skill-api]
        S2[skill-copilot]
        S3[skill-debug]
        S4[skill-performance]
        S5[skill-events]
        S6[skill-permissions]
        S7[skill-testing]
        S8[skill-migrate]
        S9[skill-pages]
        S10[skill-translate]
        S11[skill-estimation]
    end

    subgraph WORKFLOWS["6 Retained Workflows"]
        W1[al-spec.create]
        W2[al-build]
        W3[al-pr-prepare]
        W4[al-context.create]
        W5[al-memory.create]
        W6[al-initialize]
    end

    ARCH --> SKILLS
    DEV --> SKILLS
    COND --> INTERNAL
    PRE --> SKILLS

    W1 --> ARCH
    W1 --> COND

Contract Structure

.github/
└── plans/
    ├── memory.md                          ← Global (cross-session context)
    └── {req_name}/
        ├── {req_name}.architecture.md    ← From @AL Architecture & Design Specialist
        ├── {req_name}.spec.md            ← From al-spec.create
        ├── {req_name}.test-plan.md       ← From al-spec.create or conductor
        ├── {req_name}-plan.md            ← From @AL Development Conductor (Planning)
        ├── {req_name}-phase-1-complete.md
        └── {req_name}-phase-N-complete.md

Routing Guide

Complexity	Route	When
LOW	`al-spec.create` → `@AL Implementation Specialist`	Simple field, validation, single UI change
MEDIUM	`@AL Architecture & Design Specialist` → `al-spec.create` → `@AL Development Conductor`	Business logic, event-driven feature
HIGH	`@AL Architecture & Design Specialist` → `al-spec.create` → `@AL Development Conductor`	Multi-module, external integration, architectural change

Not sure where to start?

@AL Architecture & Design Specialist

I need to [describe your requirement]

The architect analyzes requirements, designs the solution, and recommends the appropriate workflow.

ALDC for Claude Code

ALDC is available as a native Claude Code integration in two forms:

Official Plugin (claude-plugin/) — Install with /plugin install aldc, namespaced as aldc:*
Direct Integration (.claude/) — Auto-detected when opening the repo in Claude Code

What's Included

Primitive	Direct (`.claude/`)	Plugin (`aldc:`)	Count
Agents	`.claude/agents/`	`agents/`	8 public + 3 internal
Skills	`.claude/skills/`	`skills/`	16 composable knowledge modules
Rules	`.claude/rules/`	`rules/` (injected via `al-initialize`)	8 coding standards
MCP Servers	`.mcp.json`	`.mcp.json`	3 servers
Hooks	`.claude/settings.json`	`hooks/hooks.json`	2 hooks
Instructions	`CLAUDE.md`	`CLAUDE.md`	Agent routing, workflows

How It Maps

GitHub Copilot              →  Claude Code (Direct)         →  Claude Code (Plugin)
──────────────────────────────────────────────────────────────────────────────────────
agents/*.agent.md           →  .claude/agents/*.md          →  agents/*.md
skills/*/SKILL.md           →  .claude/skills/*/SKILL.md    →  skills/*/SKILL.md
instructions/*.md           →  .claude/rules/*.md           →  rules/*.md
prompts/*.prompt.md         →  .claude/skills/ (workflows)  →  skills/ (workflows)
.github/copilot-instructions.md → CLAUDE.md                 →  plugin.json + CLAUDE.md

Agent Routing (Claude Code)

Agent	Direct	Plugin
Architecture & Design	`@al-architect`	`@aldc:al-architect`
Technical Specification	`@al-spec-agent`	`@aldc:al-spec-agent`
Implementation	`@al-developer`	`@aldc:al-developer`
TDD Orchestration	`@al-conductor`	`@aldc:al-conductor`
Estimation & Scoping	`@al-presales`	`@aldc:al-presales`
Agent Builder	`@al-agent-builder`	`@aldc:al-agent-builder`

Workflows (Claude Code)

Workflow	Direct	Plugin
Create specifications	`/al-spec-create`	`/aldc:al-spec-create`
Build & deploy	`/al-build`	`/aldc:al-build`
Prepare PR	`/al-pr-prepare`	`/aldc:al-pr-prepare`
Session memory	`/al-memory-create`	`/aldc:al-memory-create`
Project context	`/al-context-create`	`/aldc:al-context-create`
Environment setup	`/al-initialize`	`/aldc:al-initialize`

Hooks

Claude Code hooks enforce quality gates automatically:

PostToolUse (Write/Edit) — Reminds to run tests after file modifications
Stop — Reminds to verify Skills Evidencing was declared

Plugin User Configuration

On first enable, the plugin prompts for optional settings:

Setting	Description
`bcSandboxUrl`	URL of your Business Central sandbox environment
`publisherName`	Your extension publisher name for app.json

Using BCQuality (recommended)

BCQuality supports explicit plugin and external-multiroot modes in aldc.yaml. Plugin mode loads the configured skill (default al-code-review); multiroot retains the external Entry workflow. An expected version or commit is not proof of the installed identity, and catalog discovery is not execution. When unavailable, native review continues. See configuration and evidence.

BC Agent Builder (optional)

Build Business Central Agents with the AI Development Toolkit and Agent SDK. Includes: @AL Agent Builder agent, 3 skills, 4 workflows, validation tools. See BC Agent Builder documentation.

Validation

node tools/aldc-validate/index.js --config aldc.yaml

Expected result: ✅ ALDC Core v1.2 COMPLIANT

File Structure

AL-Development-Collection-for-GitHub-Copilot/
│
│── GitHub Copilot ─────────────────────────────────────
├── .github/
│   ├── copilot-instructions.md           # Master coordination
│   └── plans/                            # Per-requirement contracts
│       ├── memory.md                     # Global memory (cross-session)
│       └── {req_name}/
│           ├── {req_name}.architecture.md
│           ├── {req_name}.spec.md
│           └── {req_name}.test-plan.md
├── agents/                               # 12 agents (5 core + 3 on-demand + 3 subagents + 1 extension)
├── skills/                               # 11 composable skills
├── prompts/                              # 6 retained workflows
├── instructions/                         # 9 auto-applied coding standards
│
│── Claude Code (Direct) ───────────────────────────────
├── CLAUDE.md                             # Master instructions
├── .mcp.json                             # MCP server configuration
├── .claude/
│   ├── agents/                           # 12 agents (9 public + 3 internal)
│   ├── skills/                           # 16 skills (composable knowledge modules)
│   ├── rules/                            # 8 path-scoped coding standards
│   └── settings.json                     # Hooks + permissions
│
│── Claude Code Plugin ─────────────────────────────────
├── claude-plugin/                        # generado: scripts/sync-plugin-support.js
│   ├── .claude-plugin/plugin.json        # Plugin manifest
│   ├── agents/                           # 12 agents (auto-discovered)
│   ├── skills/                           # 9 role entries + 11 workflows + 16 knowledge
│   ├── hooks/hooks.json                  # PostToolUse + Stop hooks
│   ├── rules/                            # 8 rules (injected via al-initialize)
│   ├── .mcp.json                         # 3 MCP servers
│   └── README.md                         # Plugin documentation
│
│── Shared ─────────────────────────────────────────────
├── docs/
│   ├── framework/                        # Normative spec + diagrams
│   └── templates/                        # Immutable contract templates (7)
├── tools/aldc-validate/                  # ALDC Core validator
├── aldc.yaml                             # Core v1.2 configuration
├── CHANGELOG.md                          # Version history
└── README.md                             # This file

Reference

Framework Documentation

MCP Servers Integration

Server	Purpose
al-symbols-mcp	AL object analysis from compiled .app packages
context7	Up-to-date library documentation retrieval
microsoft-docs	Official Microsoft/Azure documentation search

Requirements

GitHub Copilot

Visual Studio Code 1.85.0+
GitHub Copilot (agent and skill features)
AL Language Extension
Node.js 20+ (for validator)

Claude Code

Claude Code CLI v1.0.33+
AL Language Extension
Node.js 20+ (for MCP servers via npx)

What's New

5.0.0 — one delivery across every surface

Dedicated Spec Agent, per-operation Doctor, BC29-native tooling, terminal adapters and recoverable initialization, plus the VS Code Project Manager and Visor, BCQuality read as context in the design phases, and a Claude Code plugin that is generated rather than hand-written. It supersedes the unreleased 4.3.0 and 4.3.1, neither of which was ever tagged or published. Major for the plugin layout and the per-surface plans and audits roots; see the 5.0.0 changelog.

4.2.0 — Conformance release

The framework now enforces its own spec in CI.

Core Spec v1.2 (original 4.2.0 release) — originally normalized the tier model to 4 core agents + 2 on-demand (al-triage, dredd) + 3 subagents + 1 extension (al-agent-builder); 16 skills; 11 workflows. The subsequent canonical Spec Agent increment adds a fifth core role (11 total); Developer Reviewer adds a direct review role (12 total, with 17 skills).
Conformance tooling — scripts/check-conformance.js (counters, cross-references, links, frontmatter) and scripts/sync-foundation.js --check (zero drift between the canonical trees and packages/foundation/) run on every push and PR.
ARCHITECTURE.md — one-page map of what is source, what is generated, and which distribution channel consumes each tree.
Fixed: truncated skill-manifest in packages/foundation/, broken README links, undeclared primitives in aldc.yaml, contradictory counters.

4.1.0 — Lower token cost & cited audits

⚡ Lower token / AIC cost — trimmed always-on entrypoint (~31% lighter), narrow instruction globs (applyTo by object type), curated context passing, condensed primitives, BCQuality task-context built once and passed inline.
📚 Cited reviews & audits with BCQuality (recommended) — agents back findings with a pinned BC knowledge base; graceful native fallback (never blocks).
@AL Triage and @Dredd — read-only on-demand specialists.
skill-contribution-assistant — guided contribution workflow.
Restored full architecture & spec templates with authoring guidance.

4.0.0 — Token efficiency & foundation layout

Agents, instructions, skills, prompts, and templates condensed for a lower token footprint — behavior preserved.
New packages/foundation/ layout; Architecture Decision Records (docs/decisions/); new al-agent.build-instructions prompt; English-only content.
Breaking: primitives also available under packages/foundation/; agent/instruction/skill wording token-optimized (behavior unchanged).

See CHANGELOG.md for full details.

Author

Javier Armesto González Microsoft MVP (Business Central & Azure AI Services) Head of R&D & AI at VS Sistemas LinkedIn · Tech Sphere Dynamics

Support & Contributing

Report issues: GitHub Issues
Ask questions: GitHub Discussions
See CONTRIBUTING.md for contribution guidelines

License

MIT — See LICENSE for details.

Status: ALDC Core v1.2 COMPLIANT · Distributions: Copilot Chat / CLI, Claude Code, Codex · Package version: 5.0.0

Independent review

Use Developer Reviewer after a direct Developer increment; use the Conductor's review subagent for orchestrated phases. Dredd remains the independent advisory auditor for an explicit file set, changes or a broader codebase. All three share provider execution and coverage rules: loading BCQuality is not execution, and skipping its optional index refresh does not stop path-based review. A partial review never becomes approval from zero findings. See the review contract.

Name		Name	Last commit message	Last commit date
.claude-plugin		.claude-plugin
.claude		.claude
.github		.github
.vscode		.vscode
agents		agents
archive/v2.11.0		archive/v2.11.0
claude-plugin		claude-plugin
collections		collections
copilot-cli-plugin		copilot-cli-plugin
docs		docs
instructions		instructions
packages/foundation		packages/foundation
plugins/aldc-codex		plugins/aldc-codex
prompts		prompts
scripts		scripts
skills		skills
tools		tools
.gitattributes		.gitattributes
.gitignore		.gitignore
.markdownlint.json		.markdownlint.json
.mcp.json		.mcp.json
.npmignore		.npmignore
ARCHITECTURE.md		ARCHITECTURE.md
CHANGELOG.md		CHANGELOG.md
CLAUDE.md		CLAUDE.md
CONTRIBUTING.md		CONTRIBUTING.md
LICENSE		LICENSE
README.md		README.md
SECURITY.md		SECURITY.md
aldc.code-workspace		aldc.code-workspace
aldc.yaml		aldc.yaml
known-installations.json		known-installations.json
mkdocs.yml		mkdocs.yml
package-lock.json		package-lock.json
package.json		package.json
plugin.json		plugin.json
requirements.txt		requirements.txt

Latest commit

History

Folders and files

Repository files navigation

ALDC — AL Agentic Engineering System

Why ALDC?

What is ALDC?

Updating to 5.0.0

Installation

GitHub Copilot

GitHub Copilot (Plugin Marketplace)

Claude Code (Plugin)

Claude Code (Direct)

Quick Start

GitHub Copilot

Claude Code

Key Features

🤖 5 Public Agents — one specialist per development phase

🔬 3 Internal Subagents — autonomous specialists inside the Conductor

🩺 2 On-demand Specialists — user-invocable, read-only on code

🧠 11 Composable Skills — domain knowledge loaded on demand

⚙️ 6 Workflows — automated processes

📐 9 Instructions — auto-applied coding standards (always active)

📚 BCQuality (recommended) — external, citable BC knowledge layer

📄 Contracts per Requirement — structured docs in .github/plans/{req_name}/

How It Works

Development Flow

TDD Orchestration

Framework Architecture

Contract Structure

Routing Guide

ALDC for Claude Code

What's Included

How It Maps

Agent Routing (Claude Code)

Workflows (Claude Code)

Hooks

Plugin User Configuration

Using BCQuality (recommended)

BC Agent Builder (optional)

Validation

File Structure

Reference

Framework Documentation

MCP Servers Integration

Requirements

What's New

5.0.0 — one delivery across every surface

4.2.0 — Conformance release

4.1.0 — Lower token cost & cited audits

4.0.0 — Token efficiency & foundation layout

Author

Support & Contributing

License

Independent review

About

Topics

Resources

Contributing

Security policy

Stars

Watchers

Forks

Releases

Packages

Contributors

📄 Contracts per Requirement — structured docs in `.github/plans/{req_name}/`