Microsoft/bcquality
1
0
Fork 0
mirror of https://github.com/microsoft/BCQuality.git synced 2026-08-07 18:06:53 +01:00
Code Issues Projects Releases Packages Wiki Activity Actions

Add AL code generation skill contracts

Browse source 
Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com>

Copilot-Session: bd6344b4-eafd-4a58-a1c9-5a2d96fa2938
This commit is contained in:
Jesper Schulz-Wedde 2026-07-14 13:43:31 +02:00
parent be1b92b624
commit b0d71418fa
17 changed files with 1885 additions and 39 deletions
Download patch file Download diff file Expand all files Collapse all files

6
skills/README.md
View file

@ -9,16 +9,18 @@ This folder contains the skills that are not owned by any single layer. There ar
| File | Role |
|---|---|
| [`entry.md`](entry.md) | **ENTRY** — Given a task context, returns a dispatch record naming the action skill(s) to invoke. The agent's first call when pointed at BCQuality. |
| [`entry.md`](entry.md) | **ENTRY** — Given a task context, returns a dispatch record naming the action skill(s), input subset, and exact output kind/version. The agent's first call when pointed at BCQuality. |
Routing logic lives in Entry, not in the orchestrator. An agent that knows only "invoke `/skills/entry.md` first" has enough to drive the rest of the repo.
Entry preserves legacy review contexts. Create-only generation is separately capability-gated by explicit `action: generate`, `requirement-spec`, and acceptance of `generated-files-report` version 1; mixed review/generation inputs require explicit action.
## The meta-skill contracts
| # | File | Role | Who reads it |
|---|---|---|---|
| 1 | [`read.md`](read.md) | **READ** — Schema + Use. How to read a knowledge file: frontmatter fields, section semantics, matching rules, layer precedence, conflict resolution. | Any agent or action skill that consumes knowledge files. |
| 2 | [`do.md`](do.md) | **DO** — Action Skill contract. The Source → Relevance → Worklist → Action template and the structured output every action skill produces. Includes super-skill composition. | Any agent invoking an action skill; every action-skill author. |
| 2 | [`do.md`](do.md) | **DO** — Action Skill contract. The Source → Relevance → Worklist → Action template and negotiated `findings-report` or `generated-files-report` output. Includes review super-skill composition. | Any agent invoking an action skill; every action-skill author. |
| 3 | [`write.md`](write.md) | **WRITE** — New Knowledge. Authoring rules for knowledge files. Defers to `read.md` for the schema. | Contributors (human or agent) adding or editing knowledge files. Not used during consumption. |
READ and DO are read on demand — typically by the first action skill the agent executes after dispatch. They are not prerequisites for invoking Entry. WRITE is only used when scaffolding new content.

44
skills/bcquality-al-generate/SKILL.md Normal file
View file

@ -0,0 +1,44 @@
---
name: bcquality-al-generate
description: Generate new Business Central AL object files from a bounded requirement-spec JSON file using BCQuality guidance. Use only for explicit create-only AL generation, never for review.
---
# BCQuality AL generation
This bridge drives the BCQuality Entry protocol for explicit, create-only AL generation. It is intentionally separate from `bcquality-al-review`; review behavior and legacy review task contexts remain unchanged.
## When to use
Use only when the caller supplies a path to a bounded UTF-8 requirement specification that conforms to `schemas/requirement-spec-v1.schema.json` and explicitly requests AL generation.
Do not use this bridge for PR review, working-tree review, or single-file review. Do not convert inline prompt text into a requirement specification.
## Plugin root
Resolve `PLUGIN_ROOT` to the directory containing `.claude-plugin/plugin.json`. This file lives at `PLUGIN_ROOT/skills/bcquality-al-generate/SKILL.md`.
## Steps
1. Treat the caller's `requirement-spec` value only as a filesystem path. Do not interpolate the referenced JSON into Entry's `goal`.
2. Read `PLUGIN_ROOT/skills/entry.md` and invoke it with explicit capability negotiation:
```yaml
task-context:
goal: "Generate the bounded AL requirement"
action: generate
inputs-available: [requirement-spec]
accepted-outputs:
- kind: generated-files-report
version: 1
technologies: [al]
enabled-layers: [microsoft, community, custom]
```
3. Pass only the requirement-spec path to the dispatched `al-code-generation` skill. The generation skill validates and reads the bounded JSON file.
4. Return exactly one `generated-files-report` v1 JSON document. Do not write generated files to the workspace.
If Entry returns `no-match` or `failed`, return the dispatch record unchanged.
## Consumer boundary
BCQuality owns the contracts, routing, knowledge retrieval, ranking, and generation report. The consumer owns acquiring the requirement file and, after validating the complete report atomically, staging files, compiling, analyzing, testing, delivering, approving, and publishing them. The consumer must fail closed and independently enforce destination, symlink, size, and ID-range policy before materialization.

29
skills/do.md
View file

@ -32,6 +32,7 @@ title: AL code review
description: Reviews AL source changes against performance and security guidance.
inputs: [pr-diff, object-list]
outputs: [findings-report]
output-version: 1
bc-version: [26..28]
technologies: [al]
countries: [w1]
@ -39,11 +40,20 @@ application-area: [all]
---
```
`kind`, `id`, `version`, `title`, `description`, `inputs`, `outputs` are required and specific to action skills.
`kind`, `id`, `version`, `title`, `description`, `inputs`, `outputs` are required and specific to action skills. `output-version` is optional for backward compatibility and defaults to 1; new output kinds MUST declare it explicitly.
`bc-version`, `technologies`, `countries`, `application-area` are optional filters that let an orchestrator pre-select applicable skills for a task. They follow the same semantics as in READ.
`inputs` is a list of abstract input types the skill **accepts**. Standard values: `pr-diff`, `object-list`, `file-path`, `repository`, `telemetry-query`. Semantics are any-of: the orchestrator supplies whichever listed input types it has, and the skill is invoked with a non-empty subset of its declared `inputs`. A skill that cannot proceed with the supplied subset MUST return `outcome: "not-applicable"`. `outputs` is always a single-element list naming the output kind; today only `findings-report` is defined.
`inputs` is a list of abstract input types the skill **accepts**. Standard values: `pr-diff`, `object-list`, `file-path`, `repository`, `telemetry-query`, `requirement-spec`. Semantics are any-of: the orchestrator supplies whichever listed input types it has, and the skill is invoked with a non-empty subset of its declared `inputs`. A skill that cannot proceed with the supplied subset MUST return `outcome: "not-applicable"`.
`requirement-spec` is a path-valued input: its value is only a path to a bounded UTF-8 JSON file conforming to the published requirement contract. It is never inline requirement JSON and is never interpolated into prompt or goal text.
`outputs` MUST be a single-element list naming the output kind. Defined kinds are:
- `findings-report` version 1 for review and audit skills; and
- `generated-files-report` version 1 for create-only generation skills, defined by [`schemas/generated-files-report-v1.schema.json`](../schemas/generated-files-report-v1.schema.json).
Entry negotiates the exact kind/version and includes it in every dispatch record. An action skill emits one JSON document of only that negotiated kind.
`sub-skills` is an optional field. When present and non-empty, the skill is a **super-skill** that composes other action skills; see *Composition* below. Values are repo-relative paths to action-skill files.
@ -67,9 +77,9 @@ Every action skill MUST contain these five sections, in order:
**Action.** Execute the skill's work against the worklist. Evaluate each item in the worklist against the task input and emit findings. The action step is where skill behavior differs; the preceding three steps are uniform.
## Output contract
## Findings-report output contract
Every action skill emits a single JSON document that conforms to this schema:
Every action skill with `outputs: [findings-report]` emits a single JSON document that conforms to this schema:
```json
{
@ -219,6 +229,8 @@ A **super-skill** is an action skill whose frontmatter declares a non-empty `sub
Composition is flat: a super-skill MAY list only leaf skills (skills without their own `sub-skills`). Nested super-skills are not permitted in v1.
Generation skills are leaves. They MUST NOT declare `sub-skills` or compose other generation skills.
### Section interpretation for super-skills
The five required sections still apply. Their meaning shifts from knowledge files to sub-skills:
@ -285,8 +297,13 @@ For each worklist entry, emit one finding with severity `info`, a message naming
Conforms to the DO output contract.
```
## Generated-files-report output contract
The `generated-files-report` v1 contract is published as JSON Schema at [`schemas/generated-files-report-v1.schema.json`](../schemas/generated-files-report-v1.schema.json). Its path-valued input contract is [`schemas/requirement-spec-v1.schema.json`](../schemas/requirement-spec-v1.schema.json). The stable generation action skill is [`microsoft/skills/generate/al-code-generation.md`](../microsoft/skills/generate/al-code-generation.md).
Unlike a findings report, a generated-files report has no `findings` field. It carries create-only UTF-8 AL artifacts, detailed retrieval coverage, immutable revision-scoped guidance references, omissions, and suppression. Consumers MUST validate the complete JSON document atomically and fail closed before materialization, then independently enforce filesystem symlink, destination non-existence, byte-size, and normalized ID-range policy.
## How orchestrators consume output
An orchestrator invokes an action skill with an input appropriate to the skill's declared `inputs`, receives the JSON output, and maps findings to its delivery surface (PR comments, build gates, IDE diagnostics). The orchestrator MUST NOT interpret skill-specific fields beyond the schema above. Skills that need richer semantics MUST encode them within the schema (for example, by adding structured `message` text) rather than extending the output shape.
An orchestrator invokes an action skill with an input appropriate to the skill's declared `inputs`, receives the negotiated JSON output kind/version, and validates that published contract without inferring shape from the skill ID. Findings reports map to review delivery surfaces. Generated-files reports are create-only proposals and require consumer-owned validation and staging before any workspace change. Skills that need richer semantics MUST evolve a versioned shared output contract rather than add unversioned skill-specific fields.

88
skills/entry.md
View file

@ -20,9 +20,13 @@ The agent invokes Entry with a **task context** supplied by the orchestrator:
```yaml
task-context:
goal: string # free-text description of what needs doing
action: review # optional explicit intent: review | generate
inputs-available: # values the orchestrator has ready to pass to a chosen skill
- pr-diff
- file-path
accepted-outputs: # exact output capability negotiation
- kind: findings-report
version: 1
technologies: [al]
bc-version: 28
countries: [w1]
@ -31,11 +35,21 @@ task-context:
disabled-skills: [] # repo-relative paths the consumer has opted out of
```
`goal` and `inputs-available` are required. Filter dimensions (`technologies`, `bc-version`, `countries`, `application-area`) are optional; omitting a dimension is equivalent to "unconstrained" — see Relevance for the exact matching rule. `enabled-layers` defaults to all three. `disabled-skills` defaults to empty.
`goal` and `inputs-available` are required. `action` is optional for backward compatibility and, when present, is exactly `review` or `generate`. `accepted-outputs` is optional for legacy review contexts; when supplied, every entry is an exact `{kind, version}` pair. Filter dimensions (`technologies`, `bc-version`, `countries`, `application-area`) are optional; omitting a dimension is equivalent to "unconstrained" — see Relevance for the exact matching rule. `enabled-layers` defaults to all three. `disabled-skills` defaults to empty.
Generation is capability-gated. It requires all three of:
1. `action: generate`;
2. `inputs-available` containing `requirement-spec`; and
3. `accepted-outputs` containing exactly `{kind: generated-files-report, version: 1}`.
The `requirement-spec` value passed after dispatch is only a path to a bounded UTF-8 JSON file; its contents are not part of `goal` or Entry routing.
Legacy review contexts remain valid without `action` or `accepted-outputs`. For those contexts Entry treats the intended output as `findings-report` version 1. A current consumer that advertises only existing review inputs, and does not advertise `action`, `requirement-spec`, and `generated-files-report` v1 (including BCAppsBCQuality), is generation-ineligible.
## Preparation — knowledge index
Before routing, ensure the knowledge index is current for the **live** clone. The dispatched review skills read `knowledge-index.json` (at the clone root) at their Source step instead of opening every knowledge file — see READ's [Retrieval workflow](read.md). Because a consumer prunes its clone to policy *before* the agent runs, the index MUST be built over the clone as it exists now, so it lists exactly the articles that survived pruning and never an article the consumer denied:
Before routing, ensure the knowledge index is current for the **live** clone. Dispatched review and generation skills read `knowledge-index.json` (at the clone root) at their Source step instead of opening every knowledge file — see READ's [Retrieval workflow](read.md). Because a consumer prunes its clone to policy *before* the agent runs, the index MUST be built over the clone as it exists now, so it lists exactly the articles that survived pruning and never an article the consumer denied:
- If `knowledge-index.json` is absent — or you cannot confirm it reflects the current knowledge tree — regenerate it by running, from the checkout root:
@ -57,17 +71,26 @@ All action skills under `*/skills/**/*.md` across the layers named in `enabled-l
A candidate is relevant when every condition below holds:
1. Its frontmatter `kind` is `action-skill`.
2. `task-context.inputs-available` intersects its declared `inputs` — the orchestrator has at least one of the input types the skill accepts. A skill is NOT required to accept every input the orchestrator can supply; it is the skill's responsibility to return `outcome: "not-applicable"` if the supplied subset is insufficient.
3. Its frontmatter filter dimensions (`bc-version`, `technologies`, `countries`, `application-area`) match the task context per READ's matching semantics. A dimension omitted from `task-context` is treated as a wildcard and matches any value the skill declares; a dimension explicitly supplied in `task-context` must match the skill's declared values per READ. Conditionally-applicable candidates (any dimension `unknown` per READ) are admitted; they are not filtered out at Entry and are the dispatched skill's concern.
4. Its repo-relative path is not in `task-context.disabled-skills`.
2. It belongs to the selected action family. `generated-files-report` is the `generate` family; `findings-report` is the `review` family.
3. `task-context.inputs-available` intersects its declared `inputs` — the orchestrator has at least one of the input types the skill accepts. A skill is NOT required to accept every input the orchestrator can supply; it is the skill's responsibility to return `outcome: "not-applicable"` if the supplied subset is insufficient.
4. The candidate's single declared output kind and version are accepted exactly. `output-version` defaults to 1 for existing findings-report skills that omit it.
5. Its frontmatter filter dimensions (`bc-version`, `technologies`, `countries`, `application-area`) match the task context per READ's matching semantics. A dimension omitted from `task-context` is treated as a wildcard and matches any value the skill declares; a dimension explicitly supplied in `task-context` must match the skill's declared values per READ. Conditionally-applicable candidates (any dimension `unknown` per READ) are admitted; they are not filtered out at Entry and are the dispatched skill's concern.
6. Its repo-relative path is not in `task-context.disabled-skills`.
Candidates that fail any condition go to `skipped` with the corresponding reason (`inputs-unsatisfied`, `filter-mismatch`, `configuration`). Skills excluded because they are not `kind: action-skill` are not reported in `skipped`.
Determine the action family before fuzzy goal matching:
- If `action` is explicit, consider only that family even when inputs from both families are present.
- If both `requirement-spec` and any review input (`pr-diff`, `object-list`, `file-path`, `repository`, or `telemetry-query`) are present without `action`, fail with `outcome-reason: "ambiguous-action"`. Do not use `goal` to break the tie.
- If only review inputs are present and `action` is absent, use the legacy review family.
- If `requirement-spec` is present without `action: generate`, fail with `outcome-reason: "explicit-generate-action-required"`.
Candidates that fail a condition go to `skipped` with the corresponding reason (`action-mismatch`, `inputs-unsatisfied`, `output-negotiation`, `filter-mismatch`, `configuration`). Skills excluded because they are not `kind: action-skill` are not reported in `skipped`.
## Worklist
Narrow the relevant set to the skills that will actually be dispatched:
1. **Goal match.** Score each candidate's `description` and `id` against `task-context.goal`. Drop candidates that do not plausibly address the goal; record them in `skipped` with `reason: "goal-mismatch"`. Scoring is implementation-defined; agents MUST prefer exact keyword overlap before fuzzy signals.
1. **Goal match.** Within the already-selected action family, score each candidate's `description` and `id` against `task-context.goal`. Drop candidates that do not plausibly address the goal; record them in `skipped` with `reason: "goal-mismatch"`. Scoring is implementation-defined; agents MUST prefer exact keyword overlap before fuzzy signals. Never use fuzzy goal text to choose between review and generation.
2. **Super-skill precedence.** When a super-skill and any skill listed in its `sub-skills` are both in the remaining set, the super-skill supersedes the sub-skill **only when the goal is a broader match for the super-skill than for the sub-skill**. When the goal specifically names a concern the sub-skill handles (for example, goal = *"performance review"* with `al-code-review` and `al-performance-review` both present), the sub-skill wins and the super-skill is dropped with `reason: "narrower-sub-skill-selected"`. Otherwise the super-skill wins and each listed sub-skill in the set is dropped with `reason: "superseded-by-super-skill"`. The principle is: Entry dispatches the narrowest skill that satisfies the goal. A dropped sub-skill's `skipped` entry MUST carry `superseded-by` naming the super-skill that won; a dropped super-skill's entry MUST carry `superseded-by` naming the winning sub-skill.
3. **Layer precedence.** When two remaining candidates share the same `id` across layers, keep the highest-precedence one. Skill layer precedence is `/custom/` over `/community/` over `/microsoft/` — the same ordering READ defines for knowledge files. Drop the losers with `reason: "layer-precedence"` and `superseded-by` naming the winning path.
@ -94,13 +117,14 @@ Emit a single JSON document conforming to the output contract below. Entry does
"path": "microsoft/skills/review/al-code-review.md"
},
"rationale": "string",
"inputs": ["pr-diff"]
"inputs": ["pr-diff"],
"output": { "kind": "findings-report", "version": 1 }
}
],
"skipped": [
{
"skill": { "id": "string", "path": "string" },
"reason": "inputs-unsatisfied | filter-mismatch | goal-mismatch | layer-precedence | superseded-by-super-skill | narrower-sub-skill-selected | configuration",
"reason": "action-mismatch | inputs-unsatisfied | output-negotiation | filter-mismatch | goal-mismatch | layer-precedence | superseded-by-super-skill | narrower-sub-skill-selected | configuration",
"superseded-by": { "id": "string", "path": "string", "version": 1 }
}
]
@ -121,12 +145,15 @@ Emit a single JSON document conforming to the output contract below. Entry does
- `skill.version` — copied from the dispatched skill's frontmatter so the orchestrator can detect drift between dispatch time and execution.
- `rationale` — short human-readable string, for logs and traceability.
- `inputs` — the intersection of `task-context.inputs-available` and the skill's declared `inputs`. The agent MUST pass exactly this subset when invoking the skill. Sending a strict intersection avoids accidental information leakage between skills.
- `output` — the candidate's single declared output kind and contract version. This field is additive for existing consumers and is present in every dispatch entry. The version is `output-version` from frontmatter, defaulting to 1 for existing findings-report skills.
Ordering of `dispatch[]` is not significant.
**`skipped[]`** — MUST list every candidate that was considered and dropped. Each dropped candidate appears at most once; the first drop reason wins. Reasons:
- `inputs-unsatisfied` — `task-context.inputs-available` did not intersect the skill's declared `inputs`.
- `action-mismatch` — the skill belongs to the action family not selected by explicit intent or legacy review inference.
- `output-negotiation` — the skill's exact output kind/version was not accepted by the consumer.
- `filter-mismatch` — one or more frontmatter filter dimensions explicitly did not match.
- `goal-mismatch` — Relevance admitted the candidate but it failed the goal-match step.
- `layer-precedence` — a higher-precedence skill with the same `id` won. `superseded-by` is required.
@ -158,7 +185,8 @@ Populated example (PR review on a repo where only `al-performance-review` is ena
{
"skill": { "id": "al-performance-review", "version": 1, "path": "microsoft/skills/review/al-performance-review.md" },
"rationale": "Goal 'review pull request' matched; inputs-available contains pr-diff.",
"inputs": ["pr-diff"]
"inputs": ["pr-diff"],
"output": { "kind": "findings-report", "version": 1 }
}
],
"skipped": [
@ -168,11 +196,47 @@ Populated example (PR review on a repo where only `al-performance-review` is ena
}
```
Deterministic generation-only example:
```yaml
task-context:
goal: "Generate the bounded AL requirement"
action: generate
inputs-available: [requirement-spec]
accepted-outputs:
- kind: generated-files-report
version: 1
technologies: [al]
```
This dispatches only `microsoft/skills/generate/al-code-generation.md`, with `inputs: [requirement-spec]` and `output: {kind: generated-files-report, version: 1}`.
Deterministic review-only example:
```yaml
task-context:
goal: "Review the AL changes"
inputs-available: [pr-diff]
technologies: [al]
```
This remains backward compatible and routes to the applicable review skill with `output: {kind: findings-report, version: 1}`.
When both input families are available, `action: generate` routes only generation and `action: review` routes only review, subject to exact accepted-output negotiation. The same context without `action` fails:
```yaml
task-context:
goal: "Handle these AL inputs"
inputs-available: [pr-diff, requirement-spec]
```
The result is `outcome: failed`, `outcome-reason: "ambiguous-action"`, and an empty `dispatch`. Goal text never resolves this ambiguity.
## How the agent uses the dispatch
1. Invoke Entry with the orchestrator-supplied task context.
2. Receive the dispatch record.
3. For each entry in `dispatch[]`, read the referenced action skill, execute its Source → Relevance → Worklist → Action steps per DO, and produce a findings-report.
4. Return the findings-reports to the orchestrator. When `outcome` is `no-match` or `failed`, return the dispatch record itself so the orchestrator can log the reason.
3. For each entry in `dispatch[]`, read the referenced action skill, execute its Source → Relevance → Worklist → Action steps per DO, and produce exactly the negotiated `output` kind/version.
4. Return the action-skill reports to the orchestrator. When `outcome` is `no-match` or `failed`, return the dispatch record itself so the orchestrator can log the reason.
READ and DO are the contracts that govern what the dispatched skills do. An agent that has not yet read READ and DO reads them when it executes the first dispatched skill — they are not prerequisites for invoking Entry.

4
skills/read.md
View file

@ -141,9 +141,9 @@ Consumers that surface sample code to an end user or agent SHOULD cite the sampl
The standard workflow for finding applicable files:
1. Collect candidates from the knowledge index (`knowledge-index.json`). BCQuality maintains it: Entry's preparation step (see [entry.md](entry.md)) regenerates it over the live, already-filtered clone, so it lists exactly the articles that survived the consumer's layer/allow-deny pruning, each with the frontmatter, `keywords`, `title`, and one-line `description` that steps 2-3 need — candidates are enumerated without opening each file. The index is **discovery metadata only**: it tells you *which* files to open, it does not substitute for them. A finding MUST cite only an article that was opened and read in full; an index row whose file is absent from the clone MUST be discarded *before* ranking or worklisting, and its metadata MUST NOT seed a finding. Absent an index, collect candidates by path (typically by `domain` subfolder, across enabled layers).
1. Collect candidates from the knowledge index (`knowledge-index.json`). BCQuality maintains it: Entry's preparation step (see [entry.md](entry.md)) regenerates it over the live, already-filtered clone, so it lists exactly the articles that survived the consumer's layer/allow-deny pruning, each with the frontmatter, `keywords`, `title`, and one-line `description` that steps 2-3 need — candidates are enumerated without opening each file. The index is **discovery metadata only**: it tells you *which* files to open, it does not substitute for them. A finding or generated artifact MUST cite only an article that was opened and read in full; an index row whose file is absent from the clone MUST be discarded *before* ranking or worklisting, and its metadata MUST NOT seed output. Absent an index, review skills may collect candidates by path (typically by `domain` subfolder, across enabled layers). Generation is stricter: `al-code-generation` is index-only and fails rather than walking the repository.
2. Filter by frontmatter using the matching rules above. Files that are not applicable are discarded.
3. Rank or narrow by `keywords` relevance to the task.
3. Rank or narrow by `keywords` relevance to the task. Cross-domain generation additionally uses exact title, object, and domain cues before lower-confidence description signals, as specified by its action skill.
4. Resolve conflicts via layer precedence.
Steps 1–3 are deterministic; step 4 is applied only when conflicts are detected.