c213f1495e
The narrowed UI-handler guidance still stated the execution rule without the qualifier the linked Microsoft reference uses. The article said every listed handler must execute at least once, and the testing leaf skill asked for `[HandlerFunctions(...)]` to match the invoked handlers exactly. The reference says every *nonoptional* listed handler must execute, and that send-notification and recall-notification handlers can be optional. As written, an agent could flag a deliberately unused optional notification handler. The discriminator is narrower than the handler type. Both `[SendNotificationHandler([HandlerIsOptional: Boolean])]` and `[RecallNotificationHandler([HandlerIsOptional: Boolean])]` take an explicit optionality argument, so `[SendNotificationHandler(true)]` is exempt while the same attribute written without the argument stays nonoptional like every other handler type. Keying the exemption on the argument rather than the type keeps it checkable from the diff and avoids the opposite false positive, where an agent stops flagging genuinely nonoptional notification handlers. Changes: - The article now states the nonoptional qualifier, explains that optionality is declared rather than inferred, and adds an explicit do-not-flag clause. That clause also forbids proposing removal, because the listed entry is what keeps the test passing on the runs where the notification does fire. - The testing leaf skill carries the same boundary in its `ui-handlers-in-tests` cue, and its mechanical-fix list no longer allows removing a listed optional notification handler as a one-click suggestion. - `SendNotificationHandler` and `RecallNotificationHandler` were missing from the skill's testing token list, so notification handlers were not reliably surfaced to the relevance step at all. Both are now listed. - The good sample gains a test that lists an unreached `[SendNotificationHandler(true)]`; the bad sample gains the mirror image, an unreached `[SendNotificationHandler]` with no optionality argument. The pair differs only by that argument, which is the point. - `evaluation/review-fixtures.json` pins the testing domain to `ui-handlers-in-tests` so the boundary is exercised: the good sample is the clean control at `minimumCleanRate` 1.0 and the bad sample is the expected finding. Keywords were retagged with `notification` and `optional-handler`. validate_frontmatter.py reports 0 errors; Test-ReviewFixtures.ps1 passes with 32 cases across 16 leaf domains and resolves the testing fixture to this article. |
||
|---|---|---|
| .claude-plugin | ||
| .github | ||
| community | ||
| custom | ||
| evaluation | ||
| microsoft | ||
| skills | ||
| tools | ||
| .gitignore | ||
| agent-consumption.md | ||
| CODEOWNERS | ||
| LICENSE | ||
| plugin.json | ||
| README.md | ||
| SECURITY.md | ||
BCQuality
Quality skills and knowledge for Business Central development.
BCQuality is a curated knowledge base and skills library for Business Central. It provides structured, machine-readable guidance that development agents and tools can consume — establishing a consistent quality bar across tooling and teams.
What belongs here
BCQuality is a remedial knowledge base. A file exists because a capable LLM would get something wrong, or miss something, without it — not because the topic is important. The admission test for a knowledge file is one question:
If this file did not exist, would a modern LLM reviewing or generating BC code make a mistake this file would have prevented?
If the answer is no — the advice is generic software-engineering guidance, or the LLM already knows the BC mechanic in question — the file does not belong here, regardless of how sound the content is. A file earns its place by encoding something BC-specific that LLMs demonstrably get wrong: a CodeCop rule number, a platform API whose semantics the training data gets backwards, a non-obvious ordering rule, a BC property whose default is a footgun.
Good fit: "SetLoadFields must be called before filters, not after" (non-obvious ordering rule). "FindSet(true) takes a LockTable and the two-parameter signature is obsolete" (subtle platform behaviour + outdated training data). "CodeCop AA0233 flags FindFirst … Next loops" (rule-specific).
Poor fit: "Use HTTPS instead of HTTP." "Don't hardcode secrets." "Keep transactions short." These are true but any capable LLM already applies them without prompting.
The practical consequence: when a code-review agent flags something it shouldn't have, or misses something it should have caught, the remedy is a new knowledge file. When it already behaves correctly on a topic, no file is needed.
A file that prevents a false positive — documenting why a pattern is legitimate so the agent stops flagging it — is as valid as one that catches a defect: negative clarifications are first-class knowledge files. What never belongs is a BC fact hard-coded into a skill. Skills are finders and appliers; knowledge files are what the agent knows. See skills/do.md and skills/write.md.
What's in this repo
BCQuality contains knowledge and skills. It does not contain agents. Agents that consume BCQuality ship with AL-Go and other orchestrators.
Knowledge files
Atomic markdown files with YAML frontmatter. Each file covers one concern — one thing an agent would cite when reviewing or generating code. Knowledge files live in two layers:
-
/microsoft/— Microsoft-endorsed layer./microsoft/knowledge/— Platform guardrails, official guidance./microsoft/skills/— Microsoft-endorsed action skills.
-
/community/— BC community layer./community/knowledge/— Community patterns and shared guidance./community/skills/— Community-contributed action skills.
-
/custom/— Partner- and customer-specific overrides. Empty by default; populated in forks./custom/knowledge/— Organization-specific knowledge files./custom/skills/— Organization-specific action skills.
All three layers are enabled by default when an agent consumes BCQuality. Content can be promoted from Community to Microsoft-endorsed once it proves itself — this is a first-class concept, not an afterthought.
Skills
Skills define how agents consume knowledge. They come in three flavors:
-
The entry-point skill (
skills/entry.md) — the first skill an agent invokes at runtime. Given a task context (goal, available inputs, technologies, BC version, etc.), it returns a dispatch record naming the action skill or skills to invoke next. Routing logic lives here, not in the orchestrator. -
Meta-skill contracts (
/skills/) — three stable references that define the rest of the repo:- Schema + Use (READ,
skills/read.md) — how to read a knowledge file: interpret frontmatter, parse sections, understand layer precedence. Any agent or skill that reads knowledge files depends on it. - Action Skill (DO,
skills/do.md) — the template every action skill follows. Defines the four-step pattern (Source → Relevance → Worklist → Action) and the structured output format that orchestrators expect. - New Knowledge (WRITE,
skills/write.md) — how to author a valid knowledge file. References Schema + Use for the format specification and adds authoring rules (atomicity, section guidance).
READ and DO are read on demand — typically when the first dispatched action skill runs. They are not prerequisites for invoking Entry. WRITE is only used when scaffolding new content.
- Schema + Use (READ,
-
Action skills — concrete skills that follow the Action Skill template to do real work (review code, audit telemetry, etc.). Action skills live inside the layers that own them (
/microsoft/skills/,/community/skills/,/custom/skills/). An action skill is either a leaf that evaluates knowledge files directly, or a super-skill that composes other action skills (declared viasub-skillsin frontmatter). The canonical reference ismicrosoft/skills/review/al-code-review.md(super-skill), which composes the AL review leaf skills undermicrosoft/skills/review/— one per knowledge domain.
Agent bootstrapping
An orchestrator (such as AL-Go) points the agent at BCQuality's URL and provides a task context. The agent's first call is /skills/entry.md, which returns a dispatch record naming the action skill(s) to invoke. The agent then invokes each dispatched skill in turn, reading READ and DO on demand. No prior knowledge of BCQuality's structure is baked into the orchestrator — only the convention "invoke /skills/entry.md first."
Knowledge file format
Every knowledge file is a markdown file with mandatory YAML frontmatter. Files target under 100 lines (ideal under 50). If two ideas would share a file, split them.
Frontmatter schema (v1)
---
bc-version: [all] # or [26..28], or [26..] for "26 and later"
domain: performance # security | performance | ux | telemetry | ...
keywords: [query, filtering, partial] # free-text tags for retrieval
technologies: [al] # al | javascript | powershell | ...
countries: [w1] # ISO codes, or [w1]
application-area: [all] # finance | manufacturing | jobs | [all]
---
All six fields are required. The schema is locked — changes require a PR approved by both maintainers.
Sections
Every knowledge file must contain a ## Description section. The following sections are optional but recommended:
## Best Practice— the recommended approach## Anti Pattern— what to avoid and why
Code examples belong in separate files, not in the knowledge file itself. Knowledge files must not contain fenced code blocks.
Scope
The current curated corpus is focused on technical AL code review: AppSource and compatibility, data modeling, error handling, events, interfaces, performance, privacy, Query objects, security, style, telemetry, testing, UI, upgrade, and web services. These are the domains backed by knowledge files and registered review leaves today.
Business Central functional domains (Finance, Supply Chain Management, Manufacturing, Jobs, Warehousing, Service), PowerShell, pipelines, and Power Platform remain valid future repository scope, but they are not current coverage claims until corresponding knowledge and action skills exist. Consumers should derive supported review scope from the live knowledge index and dispatched skills, not from roadmap breadth.
How agents consume BCQuality
Action skills follow a four-step pattern:
- Source — which knowledge folders and tags to search
- Relevance — filter by frontmatter (version, technology, country, area)
- Worklist — narrow from N candidates to the M that apply to the current task
- Action — apply the relevant knowledge and produce structured output
Every action skill produces output in a common format that orchestrators can consume without skill-specific parsing. The format is JSON and includes an outcome (so a clean run, a not-applicable skill, and a partial failure are all distinguishable), findings (what the skill observed), structured references back to the knowledge files that informed each finding, per-finding confidence, and a suppressed list recording any knowledge files overridden by layer precedence. This contract is defined in the Action Skill meta-skill so that orchestrators and action skills remain independently evolvable.
BCQuality is an additive knowledge layer: it augments the agent's review judgement, it does not replace it. Super-skills (such as al-code-review) run a self-review pass alongside their sub-skills and surface concerns the agent identified on its own, marked with from-sub-skill: "agent" and an empty references: [] so consumers can render them distinctly from knowledge-backed findings. See agent-consumption.md and skills/do.md for the full contract.
The meta-skills in /skills/ define this pattern. Every concrete action skill follows it.
For the end-to-end flow — from orchestrator trigger through to how output reaches developers — see agent-consumption.md.
Repository structure
├── /skills/ # Global: entry-point skill + meta-skill contracts (READ, DO, WRITE)
├── /evaluation/ # Neutral good/bad review fixtures and scoring contract
├── /.github/ # Actions and workflows
├── /microsoft/ # Microsoft-endorsed layer
│ ├── /knowledge/ # Knowledge files by domain
│ │ └── /<domain>/ # Each article: <slug>.md + optional <slug>.good.al / <slug>.bad.al
│ └── /skills/ # Microsoft-endorsed action skills
├── /community/ # BC community layer
│ ├── /knowledge/ # Knowledge files by domain
│ │ └── /<domain>/ # Article + sibling samples, same convention
│ └── /skills/ # Community action skills
├── /custom/ # Partner/customer-specific overrides (empty; populated in forks)
│ ├── /knowledge/
│ └── /skills/
Versioning
BCQuality content is released on demand — roughly monthly, not on every commit. A
release is a major.minor value derived from git tags, cut manually via the
Release version workflow: pick whether to bump the minor or the major, and it
computes the next version and tags the current main as v{major}.{minor}.
- Bump the minor for the usual periodic content update; bump the major only for a breaking change.
- The minor is a monotonic counter — it only ever increments and never resets, even across a major bump — so it uniquely identifies a release.
Contributing
Contributions are welcome. Before submitting a PR:
- Read the knowledge file format above — frontmatter and sections are validated by CI.
- Keep files atomic: one concern per file, under 100 lines.
- Target your contribution to the right layer — most community contributions go in
/community/knowledge/. - Adding a BC fact — or stopping the agent from flagging a false positive — is a knowledge file, not a skill edit. If a PR changes what a review skill flags, the change almost certainly belongs in a knowledge file. See
skills/write.md.
CI runs validation on every PR. If your knowledge file has schema violations, missing sections, code blocks, or exceeds 100 lines, the check will fail with a clear error message.
Companion samples must be referenced by filename from their article, and every referenced sample must exist. The review evaluation corpus under evaluation/ adds one positive and one clean control for every registered AL review leaf; see evaluation/README.md for credential-free validation and optional fast-model scoring.