{
  "markdown": "<div align=\"center\">\n\n<img src=\"docs/assets/images/aldc-brand-banner.svg\" alt=\"ALDC — AL Agentic Engineering System\" width=\"900\">\n\n# ALDC — AL Agentic Engineering System\n\n**Skills-based, spec-driven, TDD-orchestrated development framework for Microsoft Dynamics 365 Business Central.**\n\n_Engineering systems, visibly reasoned._\n\n[![ALDC Core](https://img.shields.io/badge/ALDC%20Core-v1.2%20Compliant-0891B2.svg?style=flat-square&labelColor=0F172A)](docs/framework/ALDC-Core-Spec-v1.2.md)\n[![Version](https://img.shields.io/badge/version-4.2.0-D946EF?style=flat-square&labelColor=0F172A)](CHANGELOG.md)\n[![Claude Code Plugin](https://img.shields.io/badge/Claude%20Code-plugin%20available-38BDF8.svg?style=flat-square&labelColor=0F172A)](claude-plugin/)\n[![Framework](https://img.shields.io/badge/framework-AI--Native--Instructions-0891B2?style=flat-square&labelColor=0F172A)](https://danielmeppiel.github.io/awesome-ai-native/)\n[![License](https://img.shields.io/badge/license-MIT-0891B2?style=flat-square&labelColor=0F172A)](./LICENSE)\n[![GitHub Issues](https://img.shields.io/github/issues/javiarmesto/AL-Development-Collection-for-GitHub-Copilot?style=flat-square&labelColor=0F172A&color=0891B2)](https://github.com/javiarmesto/AL-Development-Collection-for-GitHub-Copilot/issues)\n[![GitHub Stars](https://img.shields.io/github/stars/javiarmesto/AL-Development-Collection-for-GitHub-Copilot?style=flat-square&labelColor=0F172A&color=D946EF)](https://github.com/javiarmesto/AL-Development-Collection-for-GitHub-Copilot/stargazers)\n\n</div>\n\n> [!IMPORTANT]\n> **Now available for both GitHub Copilot and Claude Code.** ALDC is under active development against **Core Spec v1.2**, with conformance enforced in CI. See [What's New](#whats-new) for the latest release.\n\n---\n\n## Why ALDC?\n\nAI 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.\n\n| Without ALDC | With ALDC |\n| --- | --- |\n| Ad-hoc, one-shot code generation | **Contract-driven** development (spec → architecture → test-plan → code) |\n| No checkpoints — you find out at the end | **Human-in-the-loop gates** at every phase |\n| Tests written last (or never) | **TDD-orchestrated** — tests FIRST, then code |\n| Base-app edits sneak in | **Extension-only** by construction |\n| \"Looks fine to me\" reviews | **Cited reviews & audits** against BC knowledge |\n\n---\n\n## What is ALDC?\n\nALDC (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 — the same framework working natively across two platforms:\n\n- **GitHub Copilot** — Agents, skills, prompts, and instructions in `.github/` and `agents/`\n- **Claude Code** — Agents, skills, rules, and hooks in `.claude/` + official plugin in `claude-plugin/`\n\n---\n\n## Installation\n\n### GitHub Copilot\n\nInstall from the VS Code Marketplace or:\n\n```bash\ncode --install-extension JavierArmesto.aldc-al-development-collection\n```\n\nThen, from the Command Palette:\n\n- `AL Collection: Install Toolkit to Workspace` — copies the framework into your project's `.github/`\n- `AL Collection: Update Toolkit` — merges a new version, preserving your customizations\n- `AL Collection: Validate Installation` — verifies compliance\n\n### Claude Code (Plugin)\n\n```bash\n/plugin install aldc\n/aldc:al-initialize\n```\n\n`al-initialize` copies path-scoped rules to `.claude/rules/`, generates a project `CLAUDE.md`, and configures the workspace.\n\n### Claude Code (Direct)\n\nClone this repo and open it with Claude Code. The `.claude/` directory and `CLAUDE.md` are detected automatically.\n\n---\n\n## Quick Start\n\n### GitHub Copilot\n\n1. Install the extension and open your AL project\n2. Run `AL Collection: Install Toolkit to Workspace`\n3. Start with `@workspace use al-spec.create` plus your requirement\n4. Follow the guided flow\n\n### Claude Code\n\n1. `/plugin install aldc`\n2. `/aldc:al-initialize`\n3. Call any agent: `@al-architect`, `@al-developer`, `@al-conductor`, `@al-presales`\n4. Or run a workflow: `/aldc:al-spec-create`\n\nSee [QUICKSTART.md](docs/framework/QUICKSTART.md) for the full onboarding guide.\n\n---\n\n## Key Features\n\n### 🤖 4 Public Agents — one specialist per development phase\n\n| Agent | Role |\n| --- | --- |\n| `@AL Architecture & Design Specialist` | Designs solutions, information flows, technical decisions |\n| `@AL Implementation Specialist` | Implements, debugs, quick adjustments |\n| `@AL Development Conductor` | Orchestrates TDD implementation with subagents |\n| `@AL Pre-Sales & Project Estimation Specialist` | Estimation and scoping |\n\n### 🔬 3 Internal Subagents — autonomous specialists inside the Conductor\n\n- **AL Planning Subagent** — research and context gathering\n- **AL Implementation Subagent** — TDD-only (tests FIRST, code SECOND)\n- **AL Code Review Subagent** — review against spec + architecture\n\n### 🩺 2 On-demand Specialists — user-invocable, read-only on code\n\n- `@AL Triage` — reactive diagnosis: reproduce → root-cause → minimal-fix recommendation\n- `@Dredd` — independent auditor: BCQuality-cited static audit with an advisory verdict\n\n### 🧠 11 Composable Skills — domain knowledge loaded on demand\n\n- **Required:** api · copilot · debug · performance · events · permissions · testing\n- **Recommended:** migrate · pages · translate · estimation\n- Plus `skill-contribution-assistant` — guided workflow for contributing back to ALDC\n\n### ⚙️ 6 Workflows — automated processes\n\n`al-spec.create` · `al-build` · `al-pr-prepare` · `al-context.create` · `al-memory.create` · `al-initialize`\n\n### 📐 9 Instructions — auto-applied coding standards (always active)\n\nal-guidelines · al-code-style · al-naming-conventions · al-performance · al-error-handling · al-events · al-testing · copilot-instructions · index\n\n### 📚 BCQuality (optional) — external, citable BC knowledge layer\n\nAn externally-consumed BC knowledge base (multi-root), defaulting to the canonical upstream [`microsoft/BCQuality`](https://github.com/microsoft/BCQuality) and configurable to your own fork. Agents cite findings to real knowledge files, with a graceful native fallback when it is absent. See [`docs/bcquality.md`](docs/bcquality.md).\n\n### 📄 Contracts per Requirement — structured docs in `.github/plans/{req_name}/`\n\n- `{req_name}.architecture.md` — solution design (from architect)\n- `{req_name}.spec.md` — technical blueprint (from spec.create)\n- `{req_name}.test-plan.md` — test strategy\n- `memory.md` — global context across sessions\n\n---\n\n## How It Works\n\n### Development Flow\n\n```text\nLOW complexity:\n  al-spec.create → @AL Implementation Specialist\n\nMEDIUM/HIGH complexity:\n  @AL Architecture & Design Specialist → al-spec.create → @AL Development Conductor\n```\n\nThe architect designs the solution and can decompose complex requirements into multiple specs, each implemented independently by the conductor.\n\n```mermaid\nflowchart TD\n    REQ[Requirement] --> CLASSIFY{Complexity?}\n    CLASSIFY -->|LOW| SPEC_LOW[al-spec.create]\n    SPEC_LOW --> DEV[\"@AL Implementation Specialist\"]\n\n    CLASSIFY -->|MEDIUM/HIGH| ARCH[\"@AL Architecture & Design Specialist\"]\n    ARCH -->|Designs solution| ARCH_DOC[architecture.md]\n    ARCH --> DECOMPOSE{Decompose?}\n    DECOMPOSE -->|Yes| SPEC_A[al-spec.create → spec-A]\n    DECOMPOSE -->|Yes| SPEC_B[al-spec.create → spec-B]\n    DECOMPOSE -->|No| SPEC_SINGLE[al-spec.create → spec.md]\n    SPEC_A --> COND_A[\"@AL Development Conductor\"]\n    SPEC_B --> COND_B[\"@AL Development Conductor\"]\n    SPEC_SINGLE --> COND[\"@AL Development Conductor\"]\n```\n\n### TDD Orchestration\n\nThe conductor enforces Test-Driven Development:\n\n```mermaid\nflowchart LR\n    PLAN[Phase 1\\nPlanning] --> IMPL[Phase N\\nImplementation]\n    IMPL --> REVIEW[Review\\nSubagent]\n    REVIEW --> HITL{HITL Gate}\n    HITL -->|Approved| NEXT[Next Phase]\n    HITL -->|Revise| IMPL\n\n    subgraph IMPL_DETAIL[Implement Subagent - TDD]\n        RED[RED\\nWrite failing tests] --> GREEN[GREEN\\nMinimal code]\n        GREEN --> REFACTOR[REFACTOR\\nAL patterns]\n    end\n```\n\n1. Planning subagent researches context\n2. Implement subagent creates tests FIRST (RED)\n3. Implement subagent writes code to pass tests (GREEN)\n4. Implement subagent refactors to AL patterns (REFACTOR)\n5. Review subagent validates against spec + architecture\n6. Human approves each phase (HITL gate)\n\n### Framework Architecture\n\n```mermaid\ngraph TB\n    subgraph PUBLIC[\"Public Agents (user-invocable)\"]\n        ARCH[\"@AL Architecture & Design Specialist\"]\n        DEV[\"@AL Implementation Specialist\"]\n        COND[\"@AL Development Conductor\"]\n        PRE[\"@AL Pre-Sales & Project Estimation Specialist\"]\n    end\n\n    subgraph INTERNAL[\"Internal Subagents (conductor-only)\"]\n        PLAN[AL Planning Subagent]\n        IMPL[AL Implementation Subagent]\n        REV[AL Code Review Subagent]\n    end\n\n    subgraph SKILLS[\"11 Composable Skills\"]\n        S1[skill-api]\n        S2[skill-copilot]\n        S3[skill-debug]\n        S4[skill-performance]\n        S5[skill-events]\n        S6[skill-permissions]\n        S7[skill-testing]\n        S8[skill-migrate]\n        S9[skill-pages]\n        S10[skill-translate]\n        S11[skill-estimation]\n    end\n\n    subgraph WORKFLOWS[\"6 Retained Workflows\"]\n        W1[al-spec.create]\n        W2[al-build]\n        W3[al-pr-prepare]\n        W4[al-context.create]\n        W5[al-memory.create]\n        W6[al-initialize]\n    end\n\n    ARCH --> SKILLS\n    DEV --> SKILLS\n    COND --> INTERNAL\n    PRE --> SKILLS\n\n    W1 --> ARCH\n    W1 --> COND\n```\n\n### Contract Structure\n\n```text\n.github/\n└── plans/\n    ├── memory.md                          ← Global (cross-session context)\n    └── {req_name}/\n        ├── {req_name}.architecture.md    ← From @AL Architecture & Design Specialist\n        ├── {req_name}.spec.md            ← From al-spec.create\n        ├── {req_name}.test-plan.md       ← From al-spec.create or conductor\n        ├── {req_name}-plan.md            ← From @AL Development Conductor (Planning)\n        ├── {req_name}-phase-1-complete.md\n        └── {req_name}-phase-N-complete.md\n```\n\n---\n\n## Routing Guide\n\n| Complexity | Route | When |\n| ---------- | ----- | ---- |\n| **LOW** | `al-spec.create` → `@AL Implementation Specialist` | Simple field, validation, single UI change |\n| **MEDIUM** | `@AL Architecture & Design Specialist` → `al-spec.create` → `@AL Development Conductor` | Business logic, event-driven feature |\n| **HIGH** | `@AL Architecture & Design Specialist` → `al-spec.create` → `@AL Development Conductor` | Multi-module, external integration, architectural change |\n\n**Not sure where to start?**\n\n```text\n@AL Architecture & Design Specialist\n\nI need to [describe your requirement]\n```\n\nThe architect analyzes requirements, designs the solution, and recommends the appropriate workflow.\n\n---\n\n## ALDC for Claude Code\n\nALDC is available as a native **Claude Code** integration in two forms:\n\n- **Official Plugin** (`claude-plugin/`) — Install with `/plugin install aldc`, namespaced as `aldc:*`\n- **Direct Integration** (`.claude/`) — Auto-detected when opening the repo in Claude Code\n\n### What's Included\n\n| Primitive | Direct (`.claude/`) | Plugin (`aldc:`) | Count |\n| --------- | ------------------- | ---------------- | ----- |\n| Agents | `.claude/agents/` | `agents/` | 7 public + 3 internal |\n| Skills | `.claude/skills/` | `skills/` | 16 composable knowledge modules |\n| Rules | `.claude/rules/` | `rules-templates/` (injected via `al-initialize`) | 8 coding standards |\n| MCP Servers | `.mcp.json` | `.mcp.json` | 3 servers |\n| Hooks | `.claude/settings.json` | `hooks/hooks.json` | 2 hooks |\n| Instructions | `CLAUDE.md` | `CLAUDE.md` | Agent routing, workflows |\n\n### How It Maps\n\n```text\nGitHub Copilot              →  Claude Code (Direct)         →  Claude Code (Plugin)\n──────────────────────────────────────────────────────────────────────────────────────\nagents/*.agent.md           →  .claude/agents/*.md          →  agents/*.md\nskills/*/SKILL.md           →  .claude/skills/*/SKILL.md    →  skills/*/SKILL.md\ninstructions/*.md           →  .claude/rules/*.md           →  rules-templates/*.md\nprompts/*.prompt.md         →  .claude/skills/ (workflows)  →  skills/ (workflows)\n.github/copilot-instructions.md → CLAUDE.md                 →  plugin.json + CLAUDE.md\n```\n\n### Agent Routing (Claude Code)\n\n| Agent | Direct | Plugin |\n| ----- | ------ | ------ |\n| Architecture & Design | `@al-architect` | `@aldc:al-architect` |\n| Implementation | `@al-developer` | `@aldc:al-developer` |\n| TDD Orchestration | `@al-conductor` | `@aldc:al-conductor` |\n| Estimation & Scoping | `@al-presales` | `@aldc:al-presales` |\n| Agent Builder | `@al-agent-builder` | `@aldc:al-agent-builder` |\n\n### Workflows (Claude Code)\n\n| Workflow | Direct | Plugin |\n| -------- | ------ | ------ |\n| Create specifications | `/al-spec-create` | `/aldc:al-spec-create` |\n| Build & deploy | `/al-build` | `/aldc:al-build` |\n| Prepare PR | `/al-pr-prepare` | `/aldc:al-pr-prepare` |\n| Session memory | `/al-memory-create` | `/aldc:al-memory-create` |\n| Project context | `/al-context-create` | `/aldc:al-context-create` |\n| Environment setup | `/al-initialize` | `/aldc:al-initialize` |\n\n### Hooks\n\nClaude Code hooks enforce quality gates automatically:\n\n- **PostToolUse** (Write/Edit) — Reminds to run tests after file modifications\n- **Stop** — Reminds to verify Skills Evidencing was declared\n\n### Plugin User Configuration\n\nOn first enable, the plugin prompts for optional settings:\n\n| Setting | Description |\n| ------- | ----------- |\n| `bcSandboxUrl` | URL of your Business Central sandbox environment |\n| `publisherName` | Your extension publisher name for app.json |\n\n---\n\n## Using BCQuality (optional)\n\nBCQuality is an optional, externally-consumed BC knowledge layer for cited reviews and audits. The source is configurable in `aldc.yaml` and defaults to the canonical upstream [microsoft/BCQuality](https://github.com/microsoft/BCQuality) (point it at your own fork if you keep one); it is consumed via a multi-root workspace — **not a submodule, never compiled**. When absent, agents fall back gracefully to the native A–G checklist and are never blocked.\n\n**Quick start (3 steps):**\n\n1. From your AL project root, run the install script — clones the pinned fork to `../bcquality`:\n   ```bash\n   bash tools/bcquality/install.sh\n   # or on Windows:\n   pwsh -File tools/bcquality/install.ps1\n   ```\n   Override the target location with `$BCQUALITY_HOME` if needed.\n\n2. Open `aldc.code-workspace` (multi-root: your extension + `../bcquality`, which does **not** compile).\n\n3. Run a review or audit (`@AL Development Conductor`, `@Dredd`, or `@AL Triage`): they cite BCQuality if mounted, or degrade gracefully to native checks if not.\n\nSee [`docs/bcquality.md`](docs/bcquality.md) for the full guide.\n\n---\n\n## BC Agent Builder (optional)\n\nBuild Business Central Agents with the AI Development Toolkit and Agent SDK.\nIncludes: `@AL Agent Builder` agent, 3 skills, 4 workflows, validation tools.\nSee [BC Agent Builder documentation](docs/bc-agent-builder.md).\n\n---\n\n## Validation\n\n```bash\nnode tools/aldc-validate/index.js --config aldc.yaml\n```\n\nExpected result: `✅ ALDC Core v1.2 COMPLIANT`\n\n---\n\n## File Structure\n\n```text\nAL-Development-Collection-for-GitHub-Copilot/\n│\n│── GitHub Copilot ─────────────────────────────────────\n├── .github/\n│   ├── copilot-instructions.md           # Master coordination\n│   └── plans/                            # Per-requirement contracts\n│       ├── memory.md                     # Global memory (cross-session)\n│       └── {req_name}/\n│           ├── {req_name}.architecture.md\n│           ├── {req_name}.spec.md\n│           └── {req_name}.test-plan.md\n├── agents/                               # 10 agents (4 core + 2 on-demand + 3 subagents + 1 extension)\n├── skills/                               # 11 composable skills\n├── prompts/                              # 6 retained workflows\n├── instructions/                         # 9 auto-applied coding standards\n│\n│── Claude Code (Direct) ───────────────────────────────\n├── CLAUDE.md                             # Master instructions\n├── .mcp.json                             # MCP server configuration\n├── .claude/\n│   ├── agents/                           # 10 agents (7 public + 3 internal)\n│   ├── skills/                           # 16 skills (composable knowledge modules)\n│   ├── rules/                            # 8 path-scoped coding standards\n│   └── settings.json                     # Hooks + permissions\n│\n│── Claude Code Plugin ─────────────────────────────────\n├── claude-plugin/\n│   ├── .claude-plugin/plugin.json        # Plugin manifest\n│   ├── agents/                           # 10 agents (auto-discovered)\n│   ├── skills/                           # 16 skills (auto-discovered)\n│   ├── hooks/hooks.json                  # PostToolUse + Stop hooks\n│   ├── rules-templates/                  # 8 rules (injected via al-initialize)\n│   ├── .mcp.json                         # 3 MCP servers\n│   └── README.md                         # Plugin documentation\n│\n│── Shared ─────────────────────────────────────────────\n├── docs/\n│   ├── framework/                        # Normative spec + diagrams\n│   └── templates/                        # Immutable contract templates (7)\n├── tools/aldc-validate/                  # ALDC Core validator\n├── aldc.yaml                             # Core v1.2 configuration\n├── CHANGELOG.md                          # Version history\n└── README.md                             # This file\n```\n\n---\n\n## Reference\n\n### Framework Documentation\n\n- [Core Specification v1.2](docs/framework/ALDC-Core-Spec-v1.2.md)\n- [Architecture Diagrams](docs/framework/ALDC-Architecture-Diagrams.md)\n- [Manifesto](docs/framework/ALDC-Manifesto.md)\n- [Quickstart](docs/framework/QUICKSTART.md)\n- [Governance](docs/framework/ALDC-Governance.md)\n- [Compliance Model](docs/framework/ALDC-Compliance-Model.md)\n- [Migration Guide v1.0→v1.1](docs/framework/ALDC-Migration-v1.0-to-v1.1.md)\n\n### MCP Servers Integration\n\n| Server | Purpose |\n| ------ | ------- |\n| [al-symbols-mcp](https://github.com/StefanMaron/AL-Dependency-MCP-Server) | AL object analysis from compiled .app packages |\n| [context7](https://github.com/upstash/context7) | Up-to-date library documentation retrieval |\n| [microsoft-docs](https://github.com/nicholasglazer/microsoft-docs-mcp) | Official Microsoft/Azure documentation search |\n\n### Requirements\n\n**GitHub Copilot**\n- Visual Studio Code 1.85.0+\n- GitHub Copilot (agent and skill features)\n- AL Language Extension\n- Node.js 14+ (for validator)\n\n**Claude Code**\n- Claude Code CLI v1.0.33+\n- AL Language Extension\n- Node.js 14+ (for MCP servers via npx)\n\n---\n\n## What's New\n\n### 4.2.0 — Conformance release\n\nThe framework now enforces its own spec in CI.\n\n- **Core Spec v1.2** — normalizes the real tier model: 4 core agents + 2 on-demand (`al-triage`, `dredd`) + 3 subagents + 1 extension (`al-agent-builder`); 16 skills; 11 workflows. Everything that ships is declared.\n- **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.\n- **`ARCHITECTURE.md`** — one-page map of what is source, what is generated, and which distribution channel consumes each tree.\n- Fixed: truncated `skill-manifest` in `packages/foundation/`, broken README links, undeclared primitives in `aldc.yaml`, contradictory counters.\n\n### 4.1.0 — Lower token cost & cited audits\n\n- **⚡ 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.\n- **📚 Cited reviews & audits with BCQuality (optional)** — agents back findings with a pinned BC knowledge base; graceful native fallback (never blocks).\n- **`@AL Triage`** and **`@Dredd`** — read-only on-demand specialists.\n- **`skill-contribution-assistant`** — guided contribution workflow.\n- Restored full architecture & spec templates with authoring guidance.\n\n### 4.0.0 — Token efficiency & foundation layout\n\n- Agents, instructions, skills, prompts, and templates condensed for a lower token footprint — behavior preserved.\n- New `packages/foundation/` layout; Architecture Decision Records (`docs/decisions/`); new `al-agent.build-instructions` prompt; English-only content.\n- **Breaking:** primitives also available under `packages/foundation/`; agent/instruction/skill wording token-optimized (behavior unchanged).\n\nSee [CHANGELOG.md](CHANGELOG.md) for full details.\n\n---\n\n## Author\n\n**Javier Armesto González**\nMicrosoft MVP (Business Central & Azure AI Services)\nHead of R&D & AI at VS Sistemas\n[LinkedIn](https://www.linkedin.com/in/jarmesto/) · [Tech Sphere Dynamics](https://techspheredynamics.com)\n\n---\n\n## Support & Contributing\n\n- Report issues: [GitHub Issues](https://github.com/javiarmesto/AL-Development-Collection-for-GitHub-Copilot/issues)\n- Ask questions: [GitHub Discussions](https://github.com/javiarmesto/AL-Development-Collection-for-GitHub-Copilot/discussions)\n- See [CONTRIBUTING.md](CONTRIBUTING.md) for contribution guidelines\n\n---\n\n## License\n\nMIT — See [LICENSE](LICENSE) for details.\n\n<div align=\"center\">\n\n**Status:** ALDC Core v1.2 COMPLIANT · **Platforms:** GitHub Copilot + Claude Code · **Version:** 4.2.0 · **Last Updated:** 2026-03-30\n\n</div>\n",
  "bytes": 21641,
  "sha": "3586a0995ff486732163b9a1f6f5512a2a809c5141dbe5a108964064efeae5ec",
  "repo_slug": "javiarmesto/aldc-al-development-collection-for-github-copilot",
  "fonte": "repo",
  "truncated": false,
  "api": "https://agentalog.com/api/listings/plg_javiarmesto_aldc_al_development_collecti_d0668946/readme"
}