ALDC-AL-Development-Collection / instructions

<!-- Use this file to provide workspace-specific custom instructions to Copilot. For more details, visit https://code.visualstudio.com/docs/copilot/copilot-customization#_use-a-githubcopilotinstructionsmd-file -->

# GitHub Copilot Instructions for AL Development

## Overview

This workspace contains AL (Application Language) code for Microsoft Dynamics 365 Business Central. It uses the **ALDC Core v1.2** skills-based architecture. The installed distribution contains **12 agents (including 3 subagents), 16 skills, 11 prompts and 8 scoped instructions**; required and optional components are defined in `aldc.yaml`.

## Core Principles

These principles apply to ALL work in this repository:

- **Extension-only development** — Never modify base application objects. Use tableextensions, pageextensions, event subscribers.
- **Human-in-the-Loop (HITL)** — All critical decisions require user confirmation before proceeding.
- **TDD / spec-driven** — Features follow the flow: `architecture (MEDIUM/HIGH) → spec.create → test-plan → implementation → review`.
- **Least privilege** — Generate only the minimum permissions required. Use XLIFF for all user-facing strings.
- **Output language: English** — All persisted documents generated by the pipeline (`architecture.md`, `spec.md`, `plan.md`, `phase-N-complete.md`, `plan-complete.md`, `test-plan.md`, code reviews, deliveries) MUST be written in English regardless of the chat conversation language. Inline chat responses MAY follow the user's language; persisted artifacts stay in English.

## Agent Routing

Choose the right agent for your task:

| Intent | Agent | What it does |
|--------|-------|-------------|
| Specifying approved requirements/designs? | `@AL Spec Agent` through `al-spec.create` | Technical contracts; human approval before implementation |
| Designing, analyzing architecture, strategic decisions? | `@AL Architecture & Design Specialist` | Solution design, data modeling, integration strategy |
| Implementing, coding, debugging, fixing? | `@AL Implementation Specialist` | Tactical implementation with full AL MCP tools |
| Building a feature with TDD orchestration (plan → implement → review → commit)? | `@AL Development Conductor` | Orchestrates planning, implementation, and review subagents |
| Estimating a project, sizing, proposals? | `@AL Pre-Sales & Project Estimation Specialist` | PERT estimation, SWOT analysis, cost breakdown |

### Quick routing guide

```
New feature (MEDIUM/HIGH)? → @AL Architecture & Design Specialist → al-spec.create → @AL Development Conductor
New feature (LOW)?         → al-spec.create → @AL Implementation Specialist
Bug fix / debugging?       → @AL Implementation Specialist
Architecture review?       → @AL Architecture & Design Specialist
Full TDD cycle?            → @AL Development Conductor
Project estimation?        → @AL Pre-Sales & Project Estimation Specialist
```

## Workflows

6 workflows available via `@workspace use [name]`:

| Workflow | When to use |
|----------|-------------|
| `al-spec.create` | Create functional-technical specifications before development |
| `al-build` | Build, package, and deploy extensions |
| `al-pr-prepare` | Prepare pull requests with documentation and validation |
| `al-memory.create` | Generate/update memory.md for session continuity |
| `al-context.create` | Generate project context.md for AI assistants |
| `al-initialize` | Complete environment and workspace setup |

### Usage

```
@workspace use al-spec.create    # Create specification
@workspace use al-build          # Build & deploy
@workspace use al-pr-prepare     # Prepare PR
@workspace use al-initialize     # Setup project
```

## Skills

The 11 core knowledge modules below are part of the 16 shipped skills, including optional modules. Agents load relevant skills on demand. You don't invoke skills directly — agents load them automatically when the task requires domain-specific knowledge.

| Skill | Domain | Loaded by |
|-------|--------|-----------|
| `skill-debug` | Debugging, diagnosis, snapshot debugging | al-developer |
| `skill-api` | API pages, OData, REST endpoints | al-developer, al-architect |
| `skill-copilot` | AI features, PromptDialog, AI Test Toolkit | al-developer, al-architect |
| `skill-events` | Event subscribers, publishers, handled pattern | al-developer, al-architect |
| `skill-permissions` | Permission sets, XLIFF, security | al-developer |
| `skill-pages` | Page types, FastTabs, actions, dynamic UI | al-developer |
| `skill-migrate` | BC version migration, upgrade codeunits, rollback | al-developer |
| `skill-translate` | XLF translation, NAB AL Tools, quality review | al-developer |
| `skill-performance` | CPU profiling, FlowField optimization, set-based ops | al-developer, al-architect |
| `skill-testing` | TDD, test strategy, AL Test Toolkit | al-architect, al-conductor |
| `skill-estimation` | PERT estimation, complexity scoring, SWOT | al-presales |

## Skills Evidencing

Agents MUST declare which skills they loaded and which patterns they applied:

- **al-architect** → `> **Skills applied**: skill-api, skill-events` at top of architecture.md
- **al-developer** → `> **Skills loaded**: skill-debug (root cause analysis)` at start of response
- **AL Implementation Subagent** → `### Skills Loaded` section in Phase Summary returned to Conductor
- **AL Code Review Subagent** → `Skills Compliance Check` checklist verifying patterns were applied
- **al-conductor** → `Skills Applied in This Phase` table in phase-complete.md; `Skills Utilization Summary` in plan-complete.md

This traceability chain ensures every skill application is auditable end-to-end.

## Auto-Applied Instructions

Each instruction loads automatically when the file you're editing matches its `applyTo` glob. There is no semantic activation — only glob matching. The framework ships **8 scoped instructions**: the 7 core rules below plus the optional `al-agent-toolkit.instructions.md`. Narrow globs are deliberate: editing a Table or Page no longer drags codeunit-only rules into the prompt.

| File | `applyTo` | What it enforces |
|------|-----------|------------------|
| `al-guidelines.instructions.md`         | `**/*.al`                              | Core principles (event-driven, App focus, Test separation, naming as infrastructure) |
| `al-code-style.instructions.md`         | `**/*.al`                              | 2-space indent, PascalCase, feature-based folders |
| `al-naming-conventions.instructions.md` | `**/*.al`                              | 26-char object name limit, `<ObjectName>.<ObjectType>.al` file pattern, `I`/`Impl` for interfaces |
| `al-performance.instructions.md`        | `**/*.Codeunit.al`, `**/*.Query.al`    | SetRange/SetLoadFields before Find, CalcSums, no DB-calls in loops |
| `al-error-handling.instructions.md`     | `**/*.Codeunit.al`                     | TryFunctions, mandatory `Label`, telemetry only when explicitly requested |
| `al-events.instructions.md`             | `**/*.Codeunit.al`                     | Never modify base objects, subscribers `local` with exact signature, no `Commit` in subscribers |
| `al-testing.instructions.md`            | `**/test/**/*.al`                      | Tests only when asked, Given/When/Then, standard libraries |

> `copilot-instructions.md` and `instructions/index.md` are **not** instructions in this sense — they have no `applyTo`. `copilot-instructions.md` is the always-on entrypoint; `index.md` is documentation.

> **Naming is infrastructure**: a file that doesn't follow `<ObjectName>.<ObjectType>.al` won't match the type-specific globs and will silently miss its instructions. `aldc-validate` checks the convention.

## Plans

Requirement sets live in `.github/plans/`, one subdirectory per requirement:

```
.github/plans/
├── memory.md                              # Global memory (decisions, context across sessions)
└── {req_name}/                            # One directory per requirement
    ├── {req_name}.spec.md                 # Functional-technical specification
    ├── {req_name}.architecture.md         # Architecture decisions
    ├── {req_name}.test-plan.md            # Test plan with acceptance criteria
    ├── {req_name}-phase-<N>-complete.md   # Phase completion reports (conductor)
    └── {req_name}-complete.md             # Final completion report (conductor)
```

> `memory.md` is GLOBAL and lives directly in `.github/plans/` (not in a subdirectory).

### Workflow with plans

**MEDIUM / HIGH:**

1. `@AL Architecture & Design Specialist` — Designs solution, creates `.github/plans/{req_name}/{req_name}.architecture.md`
2. `@workspace use al-spec.create` — Reads architecture, generates `.github/plans/{req_name}/{req_name}.spec.md` (detailed blueprint: object IDs, procedure signatures, AL code)
3. `@AL Development Conductor` — Reads spec + architecture from `.github/plans/{req_name}/`, orchestrates TDD: planning → implementation → review
4. `@workspace use al-pr-prepare` — Prepares PR referencing the plan

**LOW:**

1. `@workspace use al-spec.create` — Generates `.github/plans/{req_name}/{req_name}.spec.md` directly from codebase
2. `@AL Implementation Specialist` — Implements directly using spec as blueprint

## Complexity-Based Tool Selection

When a user provides requirements, assess complexity to route correctly:

**LOW** — Limited scope, single phase, no integrations
→ `al-spec.create` → `@AL Implementation Specialist` direct implementation

**MEDIUM** — 2-3 functional areas, internal integrations, conditional logic
→ `@AL Architecture & Design Specialist` → `al-spec.create` → `@AL Development Conductor` TDD orchestration

**HIGH** — Enterprise scope, 4+ phases, external integrations, complex workflows
→ `@AL Architecture & Design Specialist` design first → `al-spec.create` → `@AL Development Conductor` implement

Present the assessment and wait for user confirmation before proceeding.

## Code Generation Examples

### Table with Validation

```al
// Ask Copilot: "Create a table for customer addresses with validation"
table 50100 "Customer Address"
{
    DataClassification = CustomerContent;

    fields
    {
        field(1; "Customer No."; Code[20])
        {
            TableRelation = Customer."No.";
            NotBlank = true;
        }
        field(2; "Address Line 1"; Text[100])
        {
            Caption = 'Address Line 1';
        }
        field(3; "City"; Text[50])
        {
            Caption = 'City';
        }
        field(4; "Post Code"; Code[20])
        {
            Caption = 'Post Code';
        }
    }

    keys
    {
        key(PK; "Customer No.")
        {
            Clustered = true;
        }
    }
}
```

**Auto-applied** (for `CustomerAddress.Table.al`): al-guidelines, al-code-style, al-naming-conventions

### Event Subscriber

```al
// Ask: "Create event subscriber for customer validation"
[EventSubscriber(ObjectType::Table, Database::Customer, 'OnBeforeValidateEvent', 'Email', false, false)]
local procedure ValidateCustomerEmail(var Rec: Record Customer)
begin
    if Rec.Email <> '' then
        if not Rec.Email.Contains('@') then
            Error('Email must contain @');
end;
```

**Auto-applied** (for `SalesEventHandler.Codeunit.al`): al-guidelines, al-code-style, al-naming-conventions, al-performance, al-error-handling, al-events

## Best Practices for Copilot Interaction

### 1. Start with Context

- **Good**: "I'm building a customer approval workflow that needs to send notifications"
- **Avoid**: "Create a workflow"

### 2. Use the Right Tool

- **Strategic questions** → Use agents (`@AL Architecture & Design Specialist`, `@AL Implementation Specialist`, etc.)
- **Tactical tasks** → Use workflows (`@workspace use al-build`)
- **Normal coding** → Let auto-applied instructions work in background

### 3. Trust the Auto-Instructions

The instruction files work automatically:
- You don't need to ask for proper naming (al-naming-conventions handles it)
- You don't need to request performance optimization (al-performance suggests it)
- Error handling patterns apply automatically (al-error-handling activates)

### 4. Review Generated Code

Always review Copilot suggestions:
- Verify compliance with project guidelines
- Test in sandbox environment
- Check security implications
- Validate performance impact

## Workspace Structure

```
ALDC-Core/
├── instructions/
│   ├── copilot-instructions.md                  # This file (always-on entrypoint)
│   ├── al-guidelines.instructions.md            # Core principles (**/*.al)
│   ├── al-code-style.instructions.md            # Indent, PascalCase, feature folders (**/*.al)
│   ├── al-naming-conventions.instructions.md    # 26-char limit, file pattern (**/*.al)
│   ├── al-performance.instructions.md           # Query/loop rules (**/*.Codeunit.al, **/*.Query.al)
│   ├── al-error-handling.instructions.md        # TryFunctions, Labels (**/*.Codeunit.al)
│   ├── al-events.instructions.md                # Subscribers, no Commit (**/*.Codeunit.al)
│   └── al-testing.instructions.md               # Given/When/Then (**/test/**/*.al)
├── agents/
│   ├── al-architect.agent.md              # Architecture & design
│   ├── al-developer.agent.md              # Tactical implementation
│   ├── al-conductor.agent.md              # TDD orchestrator
│   ├── al-presales.agent.md               # Estimation & planning
│   ├── AL Planning Subagent.agent.md      # Research (internal, user-invocable: false)
│   ├── AL Implementation Subagent.agent.md     # TDD implementation (internal)
│   └── AL Code Review Subagent.agent.md        # Code review (internal)
├── skills/                                # Composable knowledge modules (11)
│   ├── skill-api/SKILL.md
│   ├── skill-copilot/SKILL.md
│   ├── skill-debug/SKILL.md
│   ├── skill-events/SKILL.md
│   ├── skill-estimation/SKILL.md
│   ├── skill-migrate/SKILL.md
│   ├── skill-pages/SKILL.md
│   ├── skill-performance/SKILL.md
│   ├── skill-permissions/SKILL.md
│   ├── skill-testing/SKILL.md
│   └── skill-translate/SKILL.md
├── prompts/                               # Workflows (6)
│   ├── al-spec.create.prompt.md
│   ├── al-build.prompt.md
│   ├── al-pr-prepare.prompt.md
│   ├── al-memory.create.prompt.md
│   ├── al-context.create.prompt.md
│   └── al-initialize.prompt.md
├── docs/
│   ├── framework/
│   │   └── ALDC-Core-Spec-v1.1.md         # Normative specification
│   └── templates/                         # Immutable templates
├── .github/plans/                         # Requirement sets & memory
├── src/                                   # Your AL code
└── app.json
```

## BC Agents Pack (Extension)

For agent development with AI Development Toolkit:
- @AL Agent Builder — standalone agent builder (7-phase workflow)
- skill-agent-task-patterns — 8 SDK integration patterns
- skill-agent-instructions — instruction authoring framework
- al-agent.create / al-agent.task / al-agent.instructions / al-agent.test — workflows

Integrated mode: @AL Architecture & Design Specialist + al-spec.create + @AL Development Conductor
(architect loads skill-agent-task-patterns for design decisions)

## Reference Documentation

### Microsoft Documentation

- [AL Language Reference](https://learn.microsoft.com/en-us/dynamics365/business-central/dev-itpro/developer/devenv-reference-overview)
- [Business Central Development](https://learn.microsoft.com/en-us/dynamics365/business-central/dev-itpro/developer/)
- [VS Code Copilot Guide](https://code.visualstudio.com/docs/copilot)

### This Project's Documentation

- [ALDC Core Spec v1.1](../docs/framework/ALDC-Core-Spec-v1.1.md) — Normative specification
- [Instructions Index](index.md) — Guide to all instruction files
- [AL Guidelines](al-guidelines.instructions.md) — Core principles

## Troubleshooting Copilot

### No Suggestions Appearing

1. Check Copilot extension is enabled (View → Extensions)
2. Verify file type is `.al`
3. Try reloading VS Code window

### Suggestions Don't Follow Guidelines

1. Ensure instruction files are in correct locations
2. Check file glob patterns in instruction frontmatter
3. Reference specific guidelines: "Follow al-code-style patterns"

---

**Framework**: ALDC Core v1.2 (Skills-Based Architecture)
**Version**: 1.2.0
**Last Updated**: 2026-05-18
**Workspace**: AL Development for Business Central
**Primitives**: 12 agents (including 3 subagents) + 16 skills + 11 prompts + 8 scoped instructions; 6 core workflows

## Optional BCQuality provider

Follow `docs/templates/bcquality-provider-contract.md` for the current project.
Select plugin or external-multiroot explicitly; disabled means no probe.
The plugin loads its configured skill (default al-code-review).
Discovery, loading, execution and best-effort index generation require distinct
observations. Native A–G remains until completed results establish coverage.

For direct Developer increments, use AL Developer Reviewer in an independent context before human approval. Dredd remains the advisory auditor. Both load skill-al-review-pipeline; Conductor phases keep their own review subagent.