mirror of
https://github.com/microsoft/BCQuality.git
synced 2026-10-05 14:46:55 +01:00
332947bcdb
Reconcile the read-only plan-enrichment contracts with main's folder-review inputs and documentation structure. Record Windows alternate streams in runner evidence and clear the regression harness exit status after expected negative probes. Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com> Copilot-Session: 638b66d2-9f06-4f60-8781-808709e1485c
187 lines
8.2 KiB
Markdown
187 lines
8.2 KiB
Markdown
# BCQuality
|
|
|
|
Quality skills and knowledge that help AI tools make better Business Central
|
|
development decisions: catch BC-specific defects, avoid misleading advice,
|
|
and explain findings with references you can read.
|
|
|
|
BCQuality contains **knowledge and reusable skills**, not agents or a Business
|
|
Central extension. Your host supplies the agent. You can install the content
|
|
as a plugin, use it from another integration, or browse the knowledge directly.
|
|
|
|
## Quick start
|
|
|
|
The walkthrough below uses **GitHub Copilot CLI in a terminal**, not the
|
|
Copilot Chat panel in VS Code. First
|
|
[install Copilot CLI and sign in](https://docs.github.com/en/copilot/get-started/cli-quickstart).
|
|
Your account and organization policy must allow its use. You do not need to
|
|
clone BCQuality, build a runner, or deploy an app to Business Central for this
|
|
source-review example.
|
|
|
|
### Standalone plugin installation
|
|
|
|
Run these commands in your terminal:
|
|
|
|
```powershell
|
|
copilot plugin install microsoft/BCQuality
|
|
copilot plugin list
|
|
```
|
|
|
|
The list should include `bcquality`. The plugin exposes
|
|
[`al-code-review`](skills/al-code-review/SKILL.md) and the read-only
|
|
[`al-development-plan`](skills/al-development-plan/SKILL.md) plan-enrichment
|
|
skill. Installation and skill discovery are the general pattern; reviewing an
|
|
app is one example of using it.
|
|
|
|
Plugin version `0.3.0` adds `al-development-plan`, a read-only adapter for
|
|
enriching an **existing** plan. It does not generate a plan or implement code.
|
|
|
|
The adapters are intentionally not second implementations:
|
|
|
|
```text
|
|
standalone host skill: skills/al-code-review/SKILL.md
|
|
-> routing contract: skills/entry.md
|
|
-> review coordinator: microsoft/skills/review/al-code-review.md
|
|
-> domain review leaves
|
|
|
|
standalone host skill: skills/al-development-plan/SKILL.md
|
|
-> routing contract: skills/entry.md
|
|
-> enrichment skill: microsoft/skills/development/al-development-plan.md
|
|
-> referenced constraints for the consumer's existing workflow (read-only)
|
|
```
|
|
|
|
Only the files under `skills/*/SKILL.md` follow the host's packaging format.
|
|
The remaining files are BCQuality's internal protocol and layered action
|
|
skills. Entry remains the single owner of routing and index preparation. This
|
|
separation keeps standalone installation available without duplicating policy
|
|
in either adapter.
|
|
|
|
### Example: Review a complete app folder
|
|
|
|
Start a **new** CLI session in your own app folder, replacing the example path:
|
|
|
|
```powershell
|
|
cd "C:\Repos\MyBusinessCentralApp"
|
|
copilot
|
|
```
|
|
|
|
Approve access only to a project you trust, then ask:
|
|
|
|
> 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.
|
|
|
|
The folder should contain `app.json` and your AL source; it does **not** need
|
|
to be a Git repository. On macOS or Linux, use your app's local path instead.
|
|
|
|
Each host adapter and internal action skill intentionally share a name: they
|
|
expose the same operation in two different skill formats. Their paths make the
|
|
boundary explicit.
|
|
|
|
Expect a report for each selected review, with findings, source locations,
|
|
severity, confidence, and references to the relevant guidance. Some hosts show
|
|
the structured JSON directly. `completed` with no findings means nothing was
|
|
flagged in that review's scope; `partial` or `failed` is **not** a clean result.
|
|
See [reading your results](docs/using-bcquality.md#reading-your-results).
|
|
|
|
[PowerShell 7](https://learn.microsoft.com/en-us/powershell/scripting/install/installing-powershell)
|
|
(`pwsh`) is recommended for fast knowledge discovery. If it is unavailable,
|
|
the review can still discover knowledge by reading the folders.
|
|
|
|
## Documentation
|
|
|
|
| I want to... | Start here |
|
|
| --- | --- |
|
|
| Choose direct reading, a supplied skill, or my own agent | [Ways to use BCQuality](docs/using-bcquality.md#choose-how-to-use-bcquality) |
|
|
| Review a file, changes, a branch, or a particular concern | [Using BCQuality](docs/using-bcquality.md) |
|
|
| Resolve setup problems, incomplete reviews, or incorrect findings | [Troubleshooting and support](docs/troubleshooting.md) |
|
|
| Browse the available guidance | [Knowledge by domain](docs/using-bcquality.md#knowledge-by-domain) |
|
|
| Configure the plugin or use my organization's rules | [Customizing BCQuality](docs/customizing-bcquality.md) |
|
|
| Contribute knowledge or improve a rule | [Your first contribution](docs/contributing.md#your-first-contribution) |
|
|
| Connect a host, agent, or CI integration | [Minimal integration example](docs/agent-consumption.md#try-a-minimal-integration) |
|
|
|
|
[All documentation and technical references](docs/README.md).
|
|
|
|
## Scope
|
|
|
|
Today's curated content focuses on **technical AL code review**. It augments
|
|
the agent's judgment; it is not an exhaustive BC manual or a substitute for
|
|
compilation, analyzers, tests, or human review. See
|
|
[coverage and limits](docs/using-bcquality.md#coverage-and-limits) for the
|
|
available domains and the difference between a folder review and a comparison.
|
|
|
|
The read-only `al-development-plan` interface selects relevant constraints
|
|
before the consumer implements its own existing plan.
|
|
|
|
Repository-specific orchestrators retain planning, implementation, approvals,
|
|
tests, environment, propagation, and delivery ownership. The intended flow is
|
|
consumer analysis and normalized plan -> read-only BCQuality guidance ->
|
|
existing implementation phases -> independent final BCQuality review ->
|
|
delivery. Consumer uptake and a real runtime pilot are follow-up work, not
|
|
implemented integrations or demonstrated authoring improvements.
|
|
|
|
`no-knowledge` means no additional applicable BCQuality constraints, with empty
|
|
`knowledge`; it does not make a plan unsafe or prevent the consumer from using
|
|
its ordinary gates. Retrieval failures and materially unresolved conditional
|
|
guidance are distinct outcomes, not empty knowledge. Do not add generic advice
|
|
just to avoid a `no-knowledge` result.
|
|
|
|
Functional areas such as Finance, Supply Chain Management, Manufacturing, Jobs,
|
|
Warehousing, and Service, and technologies such as PowerShell, pipelines, and
|
|
Power Platform, remain valid future scope, **not current coverage claims**.
|
|
|
|
## Evidence and follow-up scope
|
|
|
|
The [guidance evaluation](evaluation/README.md#read-only-plan-guidance) separates
|
|
credential-free contract/scorer regressions from external agent and runtime
|
|
evidence. Prepared requests and fixture counts do not establish compilation,
|
|
test execution, better repairs, or a capability percentage. Consumer adoption,
|
|
a pinned baseline comparison and runtime pilot, standalone authoring, and
|
|
source-ingestion catalog work remain separate follow-ups.
|
|
|
|
## What's in this repo
|
|
|
|
Knowledge articles cover one concern each. Skills tell an agent how to find
|
|
and apply the relevant knowledge. Both live in three layers:
|
|
|
|
| Layer | Purpose |
|
|
| --- | --- |
|
|
| [Microsoft](microsoft/) | Microsoft-endorsed skills and their knowledge. |
|
|
| [Community](community/) | Community-owned skills and their knowledge. |
|
|
| [Custom](custom/) | Organization-specific additions and overrides in your own fork. |
|
|
|
|
Review skills emit a `findings-report`; plan enrichment emits a read-only
|
|
`development-guidance-report`. Both contracts are defined in
|
|
[`skills/do.md`](skills/do.md). See
|
|
[how agents consume BCQuality](docs/agent-consumption.md) for the integration
|
|
flow.
|
|
|
|
All three are enabled by default; Custom is empty upstream. You do not need
|
|
to configure layers to get started.
|
|
|
|
## Versioning
|
|
|
|
Update the installed plugin from your terminal, then start a new session:
|
|
|
|
```powershell
|
|
copilot plugin update bcquality
|
|
```
|
|
|
|
Plugin versions and content-release tags are different. For reproducible runs
|
|
and organization forks, see [updates and versions](docs/customizing-bcquality.md#updates-and-versions).
|
|
|
|
## What belongs here
|
|
|
|
Knowledge belongs here when it prevents a BC-specific mistake an otherwise
|
|
capable agent would make, including false-positive findings. BC facts belong
|
|
in knowledge articles, not skill instructions. See the
|
|
[admission test and examples](docs/contributing.md#what-belongs-here).
|
|
|
|
## Contributing
|
|
|
|
Partners are welcome to contribute to the layer that owns the domain,
|
|
regardless of affiliation. Start with the [contribution guide](docs/contributing.md).
|
|
To report a problem without authoring a rule, see [support](docs/troubleshooting.md#reporting-a-problem).
|
|
|
|
## License
|
|
|
|
[MIT](LICENSE)
|