bcquality/docs/using-bcquality.md

Using BCQuality

Documentation | Quick start | Troubleshooting

BCQuality supplies knowledge and reusable skills to your AI host. The plugin currently exposes al-code-review; the examples below use that skill. The host supplies authentication, model access, tools, permissions, and rendering. Installing BCQuality does not install a Business Central extension or an agent.

Hosts and prerequisites

The quick start documents GitHub Copilot CLI. Use a current CLI release with plugin support and sign in to an account allowed to use it. In an interactive CLI session, /skills list should include al-code-review; in the terminal, copilot plugin list should include bcquality.

Do not assume a CLI installation also installs the plugin into VS Code, another editor, or another agent host. Follow that host's plugin instructions and confirm it discovers skills/al-code-review/SKILL.md. Hosts without compatible plugin discovery need an integration.

Source review needs access to your files, not a running BC environment. Include app.json and any relevant surrounding source. Dependency symbols or a historical baseline may be needed to substantiate particular findings; a review must not invent missing definitions or an earlier version of your app. PowerShell 7 (pwsh) accelerates discovery by generating the knowledge index. Without it, folder-based discovery is available and may take longer.

Common review requests

Start a new host session after installing or updating the plugin. Use the skill name explicitly and say what is in scope. Replace example paths and branch names with ones in your project.

Task	Example prompt
Complete app	Use the installed al-code-review skill to review the complete Business Central app in this folder without changing my source files. Return the complete BCQuality findings report.
One file	Use the installed al-code-review skill to review src\CustomerMgt.Codeunit.al without changing it. Return the complete BCQuality findings report.
Uncommitted changes	Use the installed al-code-review skill to review my staged and unstaged tracked changes against HEAD, without changing files. Identify any untracked AL files not included in that diff.
Branch changes	Use the installed al-code-review skill to review changes on this branch since its merge base with origin/main. Exclude uncommitted changes and do not edit files.
Focused review	Use the installed al-code-review skill to review performance in the app in this folder, without changing files. Return the complete performance findings report.
Agent SDK code	Use the installed al-code-review skill to review Agent SDK implementation and usage in this app folder, without changing files. Return the complete Agents findings report.

For Git comparisons, the named base ref must exist locally. If it is missing, fetch the intended branch first. A PR review also requires the host to have the PR's changes and repository access; installing the plugin does not automatically connect it to your PR workflow.

A complete-folder review considers relevant files recursively, not just modified files. Start in a single app's root for the clearest scope. For a repository containing several apps, name each app folder and review them separately when their target versions or dependencies differ.

If known, add the target BC major version and localization to the request. Do not use your extension's own version as the BC version. Missing applicability context can reduce a finding's confidence or leave a rule out.

Reading your results

The skill returns structured reports. A host may render them as text, a table, or annotations, or show the JSON directly. You can ask the host to explain the returned report without rerunning the review or changing files.

For example, a performance report could contain this finding:

Field	Illustrative value
Outcome	completed
Location	src\CustomerExport.Codeunit.al, line 42
Severity / confidence	major / high
Finding	A country filter is evaluated inside the customer loop, so rows that will be discarded are still read. Apply the filter before iterating.
Guidance	Apply filters before iterating, with linked good/bad samples.

This illustrates a report, not a guaranteed finding or host screen. Read the referenced article and the surrounding source before accepting a fix.

Outcomes

Outcome	Meaning and action
completed	The selected review finished. An empty findings list means it found nothing to flag in that scope, not that the app is certified defect-free.
not-applicable	The review did not apply to the supplied input. It is not a clean-review result.
no-knowledge	No applicable knowledge was available. Check scope, target context, and enabled layers.
partial	Some work did not finish. Read outcome-reason and the individual reports; do not treat the result as a full pass.
failed	No reliable result from that review. Resolve the reported error before relying on it.
no-match	Routing found no suitable skill. Check the request, input type, and disabled skills.

A broad review includes individual domain reports in sub-results. Separately dispatched skills return separate reports, so do not mistake the first report for the whole run. Coverage counts describe selected knowledge items evaluated, not a percentage of all possible defects or every rule in the repository.

For example, this completed domain report evaluated one selected knowledge item and found nothing to flag:

{
  "skill": { "id": "al-performance-review", "version": 1 },
  "outcome": "completed",
  "summary": {
    "counts": { "blocker": 0, "major": 0, "minor": 0, "info": 0 },
    "coverage": { "worklist-size": 1, "items-evaluated": 1 }
  },
  "findings": [],
  "suppressed": []
}

This is not evidence that other domains ran; their reports must also be present when requested.

Severity, confidence, and references

Severity	Meaning
blocker	A platform-level guarantee is violated; the work cannot proceed as-is.
major	A significant defect that should be addressed before merge.
minor	A quality concern; advisory rather than a gate.
info	Concrete context or an observation, not an instruction to change code.

Confidence (high, medium, or low) describes the strength of the evidence, not the impact. Missing version or localization context must be disclosed in the finding when conditionally applicable knowledge is used.

Knowledge-backed findings link to the articles that informed them. Findings from the agent's own reasoning have no knowledge reference (references: []); these are advisory, with severity capped at minor and confidence at medium. The display domain Agents means Agent SDK guidance; it is different from Agent, the label for the broad coordinator's own cross-cutting observations. Any suppressed entries explain knowledge overridden by configuration or layer precedence.

A report can include a code suggestion. A suggestion is not an applied change. Review the explanation first, then request any edits explicitly, for example: "Apply only the filter fix at line 42 from this report." Continue using your normal compilation, analyzer, test, and human-review workflow.

Coverage and limits

The Microsoft broad review composes the 16 Microsoft domains listed below. The Community Agents review is a separate skill selected by the request, not a nested part of that coordinator. All current review leaves accept app folders, files, and diffs; request an Agent SDK review explicitly when that coverage matters and look for its separate report.

Available knowledge is not a promise that every rule will run. Selection depends on the task, target context, enabled layers, and source evidence. A whole-folder review is a current-state snapshot: detecting a published API removal or another comparison-only regression requires an actual baseline. The corpus is technical AL guidance, not exhaustive functional validation or AppSource certification.

Knowledge by domain

Each article describes one concern. Where samples exist, use its linked .good.al and .bad.al files. Samples are demonstrations, not a deployable app.

Domain	Browse knowledge
Agent SDK	Agents (Community)
AppSource	AppSource
Compatibility	Breaking changes
Data modeling	Data modeling
Error handling	Error handling
Events	Events
Interfaces	Interfaces
Performance	Performance
Privacy	Privacy
Query objects	Query
Security	Security
Style	Style
Telemetry	Telemetry
Testing	Testing
User interface	UI
Upgrades	Upgrade
APIs and web services	Web services

Permissions and data

The review instructions produce findings, not source edits or deployment. The host still controls tool permissions: keep approval prompts enabled and do not grant blanket write or deployment access just to run a review. BCQuality may write its generated knowledge-index.json into its own installed directory; that is separate from your app's source.

BCQuality is content, not an AI service. Your chosen host and model determine where source code is processed, what usage is billed, and which data policies apply. Review those policies before supplying proprietary or customer code. Installing the plugin does not make an online host run locally or offline.