mirror of
https://github.com/microsoft/BCQuality.git
synced 2026-10-05 14:46:55 +01:00
53e2cf2fa4
* feat(community/agents): add AL agent quality guidance - add 20 agent knowledge rules with good and bad AL samples - clarify setup dialog shape, temporary persistence, permissions, profiles, instructions, capability registration, and interface wiring - add the community-owned AL agents review skill - make review fixture discovery layer-aware with custom, community, and Microsoft precedence - document layer-aware evaluation behavior * fix(community/agents): align setup and permission samples - mark agent setup pages as non-extensible where required - narrow the agent profile by hiding an unrelated sales-order field - define a dedicated read-only permission set for the sales review agent - assign AL-defined permission sets with system scope and the owning app ID - clarify the permission scope guidance for default access controls * Address agent review feedback
70 lines
No EOL
4.7 KiB
Markdown
70 lines
No EOL
4.7 KiB
Markdown
---
|
|
kind: action-skill
|
|
id: al-agents-review
|
|
version: 1
|
|
title: AL agents review
|
|
description: Reviews AL source changes against agent guidance from BCQuality.
|
|
inputs: [pr-diff, file-path]
|
|
outputs: [findings-report]
|
|
bc-version: [all]
|
|
technologies: [al]
|
|
countries: [w1]
|
|
application-area: [all]
|
|
---
|
|
|
|
# AL agents review
|
|
|
|
Reviews AL source changes against the `agents` knowledge domain in BCQuality and emits a findings report. This is a leaf action skill: it invokes no sub-skills. It is not one of the skills composed by `al-code-review`; Entry discovers and dispatches it as a top-level peer, so it produces an independent findings report.
|
|
|
|
Agent findings apply to AL files that implement or invoke Agent SDK surfaces, including agent interfaces, setup, creation, task execution, capability registration, profiles, access controls, instructions, and session-bound subscribers. Return `not-applicable` when the diff contains no AL changes or no Agent SDK implementation or usage.
|
|
|
|
An orchestrator invokes this skill with either a `pr-diff` or a `file-path`. The skill produces one JSON document conforming to the DO output contract.
|
|
|
|
## Source
|
|
|
|
Read the root `knowledge-index.json` generated by Entry and select entries whose `domain` is `agents` across every enabled layer. Use index metadata for candidate selection and open an article body only after it enters the worklist.
|
|
|
|
## Relevance
|
|
|
|
Apply READ's frontmatter matching semantics to the target BC version, AL technology, countries, and application areas. If a dimension is unknown, retain conditionally applicable guidance only when configuration permits it; cap resulting confidence at `medium` and name the unknown dimension in the finding message.
|
|
|
|
## Worklist
|
|
|
|
Match changed objects, procedures, interfaces, and tokens against article keywords, titles, descriptions, and paths. Give particular weight to:
|
|
|
|
- Implementations of `IAgentFactory`, `IAgentMetadata`, and `IAgentTaskExecution`.
|
|
- Agent setup tables and `ConfigurationDialog` pages using `Agent Setup`, `Agent Setup Buffer`, or `Agent Setup Part`.
|
|
- Agent creation, upgrade, capability registration, profile configuration, access controls, and subscriber binding.
|
|
- Instruction construction, `SecretText`, documented instruction keywords, task messages, trusted input, warnings, errors, and review behavior.
|
|
- Public APIs invoked by agent tasks across app boundaries.
|
|
|
|
Use these targeted rules to avoid broad token-only matches:
|
|
|
|
- Worklist setup-page shape guidance when the page returned by agent metadata is not a `ConfigurationDialog` or omits `Agent Setup Part`.
|
|
- Worklist temporary-source guidance when setup writes occur before a non-Cancel close path or a setup page is not temporary.
|
|
- Worklist permission guidance when default access controls are broad or when code assumes an agent can exceed the assigning user's permissions.
|
|
- Worklist instruction guidance only for text used as agent instructions; do not flag unrelated prompts, labels, or user-facing help.
|
|
- Worklist session-binding guidance only when subscribers are bound outside an agent session or left bound after execution.
|
|
|
|
After selection, resolve conflicting guidance using READ's layer precedence. Record displaced candidates in `suppressed` with `reason: "layer-precedence"`; record disabled-layer candidates with `reason: "configuration"`.
|
|
|
|
An empty worklist caused by absent applicable knowledge produces `no-knowledge`. An empty worklist caused by no match produces `completed` with no findings.
|
|
|
|
## Action
|
|
|
|
Evaluate each worklisted article's `## Best Practice` and `## Anti Pattern` against the changed code:
|
|
|
|
- Emit `major` for a clear anti-pattern and `minor` for a concrete best-practice contradiction.
|
|
- Use `blocker` only when the article identifies a violated platform guarantee.
|
|
- Do not emit a finding from applicability alone.
|
|
- Set confidence to `high` for unambiguous syntax or identifier evidence, `medium` for heuristic or conditionally applicable evidence, and `low` only for an explicit advisory.
|
|
|
|
Agent-originated findings without a matching article must follow the DO contract: prefix the ID with `agent:`, use `references: []`, cap severity at `minor` and confidence at `medium`, and emit only concrete defects within the agents domain.
|
|
|
|
Provide `suggested-code` when the repair is small, local, and unambiguous. Otherwise, when a mechanical-looking repair depends on missing context or has multiple valid forms, set `suggested-code-omission-reason`.
|
|
|
|
Use the standard DO outcomes: `completed`, `no-knowledge`, `not-applicable`, `partial`, or `failed`.
|
|
|
|
## Output
|
|
|
|
Return only one JSON document conforming to the DO output contract. Every finding emitted by this skill MUST set `findings[].domain` to `"Agents"`. Knowledge-backed finding IDs and references MUST use the exact repository-relative article path from the knowledge index. |