diff --git a/.gitignore b/.gitignore index ce89292..f5279e6 100644 --- a/.gitignore +++ b/.gitignore @@ -1,418 +1,25 @@ -## Ignore Visual Studio temporary files, build results, and -## files generated by popular Visual Studio add-ons. -## -## Get latest from https://github.com/github/gitignore/blob/main/VisualStudio.gitignore - -# User-specific files -*.rsuser -*.suo -*.user -*.userosscache -*.sln.docstates +# Environment *.env +.env.* -# User-specific files (MonoDevelop/Xamarin Studio) -*.userprefs +# Python +__pycache__/ +*.pyc +*.pyo +.venv/ +.pytest_cache/ -# Mono auto generated files -mono_crash.* - -# Build results -[Dd]ebug/ -[Dd]ebugPublic/ -[Rr]elease/ -[Rr]eleases/ -x64/ -x86/ -[Ww][Ii][Nn]32/ -[Aa][Rr][Mm]/ -[Aa][Rr][Mm]64/ -[Aa][Rr][Mm]64[Ee][Cc]/ -bld/ -[Oo]bj/ -[Oo]ut/ -[Ll]og/ -[Ll]ogs/ - -# Build results on 'Bin' directories -**/[Bb]in/* -# Uncomment if you have tasks that rely on *.refresh files to move binaries -# (https://github.com/github/gitignore/pull/3736) -#!**/[Bb]in/*.refresh - -# Visual Studio 2015/2017 cache/options directory +# Editors .vs/ -# Uncomment if you have tasks that create the project's static files in wwwroot -#wwwroot/ +.vscode/ +.idea/ -# Visual Studio 2017 auto generated files -Generated\ Files/ +# OS +.DS_Store +Thumbs.db -# MSTest test Results -[Tt]est[Rr]esult*/ -[Bb]uild[Ll]og.* -*.trx - -# NUnit -*.VisualState.xml -TestResult.xml -nunit-*.xml - -# Approval Tests result files -*.received.* - -# Build Results of an ATL Project -[Dd]ebugPS/ -[Rr]eleasePS/ -dlldata.c - -# Benchmark Results -BenchmarkDotNet.Artifacts/ - -# .NET Core -project.lock.json -project.fragment.lock.json -artifacts/ - -# ASP.NET Scaffolding -ScaffoldingReadMe.txt - -# StyleCop -StyleCopReport.xml - -# Files built by Visual Studio -*_i.c -*_p.c -*_h.h -*.ilk -*.meta -*.obj -*.idb -*.iobj -*.pch -*.pdb -*.ipdb -*.pgc -*.pgd -*.rsp -# but not Directory.Build.rsp, as it configures directory-level build defaults -!Directory.Build.rsp -*.sbr -*.tlb -*.tli -*.tlh -*.tmp -*.tmp_proj -*_wpftmp.csproj -*.log -*.tlog -*.vspscc -*.vssscc -.builds -*.pidb -*.svclog -*.scc - -# Chutzpah Test files -_Chutzpah* - -# Visual C++ cache files -ipch/ -*.aps -*.ncb -*.opendb -*.opensdf -*.sdf -*.cachefile -*.VC.db -*.VC.VC.opendb - -# Visual Studio profiler -*.psess -*.vsp -*.vspx -*.sap - -# Visual Studio Trace Files -*.e2e - -# TFS 2012 Local Workspace -$tf/ - -# Guidance Automation Toolkit -*.gpState - -# ReSharper is a .NET coding add-in -_ReSharper*/ -*.[Rr]e[Ss]harper -*.DotSettings.user - -# TeamCity is a build add-in -_TeamCity* - -# DotCover is a Code Coverage Tool -*.dotCover - -# AxoCover is a Code Coverage Tool -.axoCover/* -!.axoCover/settings.json - -# Coverlet is a free, cross platform Code Coverage Tool -coverage*.json -coverage*.xml -coverage*.info - -# Visual Studio code coverage results -*.coverage -*.coveragexml - -# NCrunch -_NCrunch_* -.NCrunch_* -.*crunch*.local.xml -nCrunchTemp_* - -# MightyMoose -*.mm.* -AutoTest.Net/ - -# Web workbench (sass) -.sass-cache/ - -# Installshield output folder -[Ee]xpress/ - -# DocProject is a documentation generator add-in -DocProject/buildhelp/ -DocProject/Help/*.HxT -DocProject/Help/*.HxC -DocProject/Help/*.hhc -DocProject/Help/*.hhk -DocProject/Help/*.hhp -DocProject/Help/Html2 -DocProject/Help/html - -# Click-Once directory -publish/ - -# Publish Web Output -*.[Pp]ublish.xml -*.azurePubxml -# Note: Comment the next line if you want to checkin your web deploy settings, -# but database connection strings (with potential passwords) will be unencrypted -*.pubxml -*.publishproj - -# Microsoft Azure Web App publish settings. Comment the next line if you want to -# checkin your Azure Web App publish settings, but sensitive information contained -# in these scripts will be unencrypted -PublishScripts/ - -# NuGet Packages -*.nupkg -# NuGet Symbol Packages -*.snupkg -# The packages folder can be ignored because of Package Restore -**/[Pp]ackages/* -# except build/, which is used as an MSBuild target. -!**/[Pp]ackages/build/ -# Uncomment if necessary however generally it will be regenerated when needed -#!**/[Pp]ackages/repositories.config -# NuGet v3's project.json files produces more ignorable files -*.nuget.props -*.nuget.targets - -# Microsoft Azure Build Output -csx/ -*.build.csdef - -# Microsoft Azure Emulator -ecf/ -rcf/ - -# Windows Store app package directories and files -AppPackages/ -BundleArtifacts/ -Package.StoreAssociation.xml -_pkginfo.txt -*.appx -*.appxbundle -*.appxupload - -# Visual Studio cache files -# files ending in .cache can be ignored -*.[Cc]ache -# but keep track of directories ending in .cache -!?*.[Cc]ache/ - -# Others -ClientBin/ -~$* -*~ -*.dbmdl -*.dbproj.schemaview -*.jfm -*.pfx -*.publishsettings -orleans.codegen.cs - -# Including strong name files can present a security risk -# (https://github.com/github/gitignore/pull/2483#issue-259490424) -#*.snk - -# Since there are multiple workflows, uncomment next line to ignore bower_components -# (https://github.com/github/gitignore/pull/1529#issuecomment-104372622) -#bower_components/ - -# RIA/Silverlight projects -Generated_Code/ - -# Backup & report files from converting an old project file -# to a newer Visual Studio version. Backup files are not needed, -# because we have git ;-) -_UpgradeReport_Files/ -Backup*/ -UpgradeLog*.XML -UpgradeLog*.htm -ServiceFabricBackup/ -*.rptproj.bak - -# SQL Server files -*.mdf -*.ldf -*.ndf - -# Business Intelligence projects -*.rdl.data -*.bim.layout -*.bim_*.settings -*.rptproj.rsuser -*- [Bb]ackup.rdl -*- [Bb]ackup ([0-9]).rdl -*- [Bb]ackup ([0-9][0-9]).rdl - -# Microsoft Fakes -FakesAssemblies/ - -# GhostDoc plugin setting file -*.GhostDoc.xml - -# Node.js Tools for Visual Studio -.ntvs_analysis.dat +# Node (if scripts ever need it) node_modules/ -# Visual Studio 6 build log -*.plg - -# Visual Studio 6 workspace options file -*.opt - -# Visual Studio 6 auto-generated workspace file (contains which files were open etc.) -*.vbw - -# Visual Studio 6 auto-generated project file (contains which files were open etc.) -*.vbp - -# Visual Studio 6 workspace and project file (working project files containing files to include in project) -*.dsw -*.dsp - -# Visual Studio 6 technical files -*.ncb -*.aps - -# Visual Studio LightSwitch build output -**/*.HTMLClient/GeneratedArtifacts -**/*.DesktopClient/GeneratedArtifacts -**/*.DesktopClient/ModelManifest.xml -**/*.Server/GeneratedArtifacts -**/*.Server/ModelManifest.xml -_Pvt_Extensions - -# Paket dependency manager -**/.paket/paket.exe -paket-files/ - -# FAKE - F# Make -**/.fake/ - -# CodeRush personal settings -**/.cr/personal - -# Python Tools for Visual Studio (PTVS) -**/__pycache__/ -*.pyc - -# Cake - Uncomment if you are using it -#tools/** -#!tools/packages.config - -# Tabs Studio -*.tss - -# Telerik's JustMock configuration file -*.jmconfig - -# BizTalk build output -*.btp.cs -*.btm.cs -*.odx.cs -*.xsd.cs - -# OpenCover UI analysis results -OpenCover/ - -# Azure Stream Analytics local run output -ASALocalRun/ - -# MSBuild Binary and Structured Log -*.binlog -MSBuild_Logs/ - -# AWS SAM Build and Temporary Artifacts folder -.aws-sam - -# NVidia Nsight GPU debugger configuration file -*.nvuser - -# MFractors (Xamarin productivity tool) working folder -**/.mfractor/ - -# Local History for Visual Studio -**/.localhistory/ - -# Visual Studio History (VSHistory) files -.vshistory/ - -# BeatPulse healthcheck temp database -healthchecksdb - -# Backup folder for Package Reference Convert tool in Visual Studio 2017 -MigrationBackup/ - -# Ionide (cross platform F# VS Code tools) working folder -**/.ionide/ - -# Fody - auto-generated XML schema -FodyWeavers.xsd - -# VS Code files for those working on multiple tools -.vscode/* -!.vscode/settings.json -!.vscode/tasks.json -!.vscode/launch.json -!.vscode/extensions.json -!.vscode/*.code-snippets - -# Local History for Visual Studio Code -.history/ - -# Built Visual Studio Code Extensions -*.vsix - -# Windows Installer files from build outputs -*.cab -*.msi -*.msix -*.msm -*.msp +# Build artifacts +*.log diff --git a/CODEOWNERS b/CODEOWNERS new file mode 100644 index 0000000..c4fb72e --- /dev/null +++ b/CODEOWNERS @@ -0,0 +1,9 @@ +# Microsoft-endorsed content and skills require maintainer review +/microsoft/ @jeschulz +/skills/ @jeschulz + +# GitHub Actions and CI +/.github/ @jeschulz + +# Community content — open to broader review +# /community/ reviewers are added as the contributor base grows diff --git a/LICENSE b/LICENSE new file mode 100644 index 0000000..cf7bcb2 --- /dev/null +++ b/LICENSE @@ -0,0 +1,21 @@ +MIT License + +Copyright (c) 2026 Microsoft Corporation + +Permission is hereby granted, free of charge, to any person obtaining a copy +of this software and associated documentation files (the "Software"), to deal +in the Software without restriction, including without limitation the rights +to use, copy, modify, merge, publish, distribute, sublicense, and/or sell +copies of the Software, and to permit persons to whom the Software is +furnished to do so, subject to the following conditions: + +The above copyright notice and this permission notice shall be included in all +copies or substantial portions of the Software. + +THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR +IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, +FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE +AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER +LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, +OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE +SOFTWARE. diff --git a/README.md b/README.md new file mode 100644 index 0000000..356f5d7 --- /dev/null +++ b/README.md @@ -0,0 +1,134 @@ +# 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's in this repo + +BCQuality contains **knowledge** and **skills**. It does not contain agents. Agents that consume BCQuality ship with [AL-Go](https://github.com/microsoft/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 two flavors: + +- **Meta-skills** (`/skills/`) — the three globally shared skills that bootstrap every interaction with BCQuality: + 1. **Schema + Use** (READ) — how to read a knowledge file: interpret frontmatter, parse sections, understand layer precedence. This is the consumer's reference — any agent or skill that reads knowledge files depends on it. + 2. **Action Skill** (DO) — the template every action skill follows. Defines the four-step pattern (Source → Relevance → Worklist → Action) and the structured output format that orchestrators expect. This is the skill author's reference. + 3. **New Knowledge** (WRITE) — how to author a valid knowledge file. References Schema + Use for the format specification and adds authoring rules (atomicity, section guidance, sample references). This is the contributor's reference. + + Schema + Use and New Knowledge are deliberately separate: one is the reader's contract, the other is the writer's guide. New Knowledge depends on Schema + Use but does not duplicate it. + +- **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/`). + +### Agent bootstrapping + +Agents discover BCQuality through `/skills/`. An orchestrator (such as AL-Go) points the agent at the repository, and the agent reads the meta-skills in `/skills/` first to learn how to interpret knowledge files, follow the action-skill pattern, and produce output the orchestrator can consume. The meta-skills are the entry point — no prior knowledge of BCQuality's structure is required. + +## 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) + +```yaml +--- +bc-version: [26..28] # BC versions this applies to +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 `/samples/`, not in the knowledge file itself. Knowledge files must not contain fenced code blocks. + +## Scope + +BCQuality covers Business Central broadly — the application domains it supports, the technologies used to extend it, and the practices that keep implementations healthy. The scope includes: + +- **Business Central domains** — Finance, Supply Chain Management, Manufacturing, Jobs, Warehousing, Service, and the many other functional areas BC covers. Domain knowledge helps agents understand the business context they are working in. +- AL language patterns and anti-patterns +- PowerShell scripting for BC +- Pipelines (AL-Go, GitHub Actions) +- Business Central APIs +- Power Platform integration +- Telemetry and KQL +- AppSource lifecycle + +A BC developer's actual job spans all of this, and BCQuality reflects that. + +## How agents consume BCQuality + +Action skills follow a four-step pattern: + +1. **Source** — which knowledge folders and tags to search +2. **Relevance** — filter by frontmatter (version, technology, country, area) +3. **Worklist** — narrow from N candidates to the M that apply to the current task +4. **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 includes findings (what the skill observed), references (which knowledge files informed each finding), and confidence signals. This contract is defined in the Action Skill meta-skill so that orchestrators and action skills remain independently evolvable. + +The meta-skills in `/skills/` define this pattern. Every concrete action skill follows it. + +## Repository structure + +``` +├── /skills/ # Global meta-skills (Schema+Use, Action Skill, New Knowledge) +├── /.github/ # Actions and workflows +├── /microsoft/ # Microsoft-endorsed layer +│ ├── /knowledge/ # Knowledge files by domain +│ │ └── // +│ └── /skills/ # Microsoft-endorsed action skills +├── /community/ # BC community layer +│ ├── /knowledge/ # Knowledge files by domain +│ │ └── // +│ └── /skills/ # Community action skills +├── /custom/ # Partner/customer-specific overrides (empty; populated in forks) +│ ├── /knowledge/ +│ └── /skills/ +├── /samples/ # Sample code referenced by knowledge files +└── /docs/ # Documentation and process artifacts +``` + +## Contributing + +Contributions are welcome. Before submitting a PR: + +1. Read the knowledge file format above — frontmatter and sections are validated by CI. +2. Keep files atomic: one concern per file, under 100 lines. +3. Put code examples in `/samples/`, not in the knowledge file. +4. Target your contribution to the right layer — most community contributions go in `/community/knowledge/`. + +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. + +## License + +[MIT](LICENSE) diff --git a/community/knowledge/performance/.gitkeep b/community/knowledge/performance/.gitkeep new file mode 100644 index 0000000..e69de29 diff --git a/community/skills/.gitkeep b/community/skills/.gitkeep new file mode 100644 index 0000000..e69de29 diff --git a/custom/README.md b/custom/README.md new file mode 100644 index 0000000..28d7aa9 --- /dev/null +++ b/custom/README.md @@ -0,0 +1,17 @@ +# Custom layer + +This folder is the template for partner- and customer-specific overrides. Use it to add knowledge and skills that apply to your organization but are not appropriate for the shared Microsoft or Community layers. + +## Structure + +``` +custom/ +├── knowledge/ # Your organization's knowledge files (same format as /microsoft/knowledge/) +└── skills/ # Your organization's action skills +``` + +## How to use + +Fork or clone BCQuality into your own repository and add your content here. Knowledge files in `/custom/knowledge/` follow the same frontmatter schema and section requirements as every other layer. Action skills in `/custom/skills/` follow the Action Skill template defined in `/skills/`. + +When agents consume BCQuality, the custom layer is loaded alongside Microsoft and Community — your overrides apply automatically. diff --git a/custom/knowledge/.gitkeep b/custom/knowledge/.gitkeep new file mode 100644 index 0000000..e69de29 diff --git a/custom/skills/.gitkeep b/custom/skills/.gitkeep new file mode 100644 index 0000000..e69de29 diff --git a/docs/.gitkeep b/docs/.gitkeep new file mode 100644 index 0000000..e69de29 diff --git a/microsoft/skills/.gitkeep b/microsoft/skills/.gitkeep new file mode 100644 index 0000000..e69de29 diff --git a/samples/.gitkeep b/samples/.gitkeep new file mode 100644 index 0000000..e69de29 diff --git a/skills/.gitkeep b/skills/.gitkeep new file mode 100644 index 0000000..e69de29