docs: update README and documentation to include Code Quality domain alongside Accessibility and FinOps

emmanuelknafo · emmanuelknafo · commit b9daaea098fd · 2026-04-16T10:02:34.000-04:00
diff --git a/README.md b/README.md
@@ -183,7 +183,7 @@ Each domain has a scanner platform repo (demo-app) and a workshop template repo:
 
 ## DIY: Build a New Domain
 
-Ready to build the Code Quality domain from scratch? The framework includes a `DomainScaffolder` agent and complete automation artifacts for generating scanner demo-app and workshop repositories with full parity to the existing Accessibility and FinOps domains.
+Ready to build the Code Quality domain from scratch? The framework includes a `DomainScaffolder` agent and complete automation artifacts for generating scanner demo-app and workshop repositories with full parity to the existing Accessibility, Code Quality, and FinOps domains.
 
 See the **[DIY: Build the Code Quality Domain](docs/DIY-Code-Quality-Domain.md)** guide for step-by-step instructions covering repo creation, sample app development, SARIF converters, workshop labs, Power BI PBIP, and ADO pipeline setup.
 
diff --git a/agents/domain-scaffolder.agent.md b/agents/domain-scaffolder.agent.md
@@ -1,6 +1,6 @@
 ---
 name: DomainScaffolder
-description: "Scaffolds new domain scanner demo-app and workshop repositories with full parity to existing Accessibility and FinOps domains. Generates repo structures, bootstrap scripts, CI/CD pipelines, Power BI PBIP, and screenshot automation."
+description: "Scaffolds new domain scanner demo-app and workshop repositories with full parity to existing Accessibility, Code Quality, and FinOps domains. Generates repo structures, bootstrap scripts, CI/CD pipelines, Power BI PBIP, and screenshot automation."
 tools:
   # Read tools
   - read/readFile
@@ -106,6 +106,9 @@ Generate the complete `{domain}-scan-workshop` repository structure following th
 12. Add `nav_exclude: true` frontmatter to ALL screenshot inventory pages (`images/lab-NN/README.md`) so they do not appear in the sidebar navigation. Only labs and the home page should appear in the sidebar.
 13. Update `.devcontainer/post-create.sh` to auto-fork or clone the scanner demo-app repo as a sibling directory for workshop participants.
 14. All code blocks in lab markdown MUST use a language identifier (`powershell`, `json`, `yaml`, `text`, etc.) to enable the Just the Docs copy-to-clipboard button on each code block. Never use bare fenced code blocks without a language tag.
+15. Create `.github/agents/{domain}-workshop.agent.md` — a Copilot agent definition for the workshop repository, following the naming pattern in the scaffolding skill.
+16. Create `.github/instructions/{domain}-workshop.instructions.md` — Copilot instructions specific to the workshop repository, covering lab conventions and domain context.
+17. Create `.github/copilot-instructions.md` — repo-wide Copilot instructions for the workshop repository, referencing the domain agent and instructions files.
 
 ### Step 6: Configure Repository Settings
 
diff --git a/docs/domain-parity-and-contribution.md b/docs/domain-parity-and-contribution.md
diff --git a/docs/related-repositories.md b/docs/related-repositories.md
@@ -18,8 +18,8 @@ agentic-accelerator-workshop            ← Framework workshop
 ├── accessibility-scan-workshop         ← 8 labs teaching accessibility scanning
 ├── finops-scan-demo-app                ← FinOps scanner + 5 demo apps
 ├── finops-scan-workshop                ← 8 labs teaching FinOps scanning
-├── code-quality-scan-demo-app          ← Code Quality scanner + 5 demo apps (planned)
-└── code-quality-scan-workshop          ← 8 labs teaching code quality scanning (planned)
+├── code-quality-scan-demo-app          ← Code Quality scanner + 5 demo apps
+└── code-quality-scan-workshop          ← 8 labs teaching code quality scanning
 ```
 
 ## Repository Catalog
@@ -32,8 +32,8 @@ agentic-accelerator-workshop            ← Framework workshop
 | 4 | `accessibility-scan-workshop` | Workshop | Accessibility | Active | PowerShell |
 | 5 | `finops-scan-demo-app` | Scanner Demo | FinOps | Active | PowerShell |
 | 6 | `finops-scan-workshop` | Workshop | FinOps | Active | PowerShell |
-| 7 | `code-quality-scan-demo-app` | Scanner Demo | Code Quality | Planned | TypeScript/Multi |
-| 8 | `code-quality-scan-workshop` | Workshop | Code Quality | Planned | PowerShell |
+| 7 | `code-quality-scan-demo-app` | Scanner Demo | Code Quality | Active | TypeScript/Multi |
+| 8 | `code-quality-scan-workshop` | Workshop | Code Quality | Active | PowerShell |
 
 All repositories live under the `devopsabcs-engineering` GitHub organization.
 
@@ -97,7 +97,7 @@ Eight hands-on labs teaching FinOps scanning and cost governance. Delivered as a
 
 ## Code Quality Domain
 
-### `code-quality-scan-demo-app` (Planned)
+### `code-quality-scan-demo-app`
 
 Multi-language code quality scanner using MegaLinter, jscpd, Lizard, and per-language coverage tools. Follows the 4-tool architecture defined in the framework's [code-quality-scan skill](../skills/code-quality-scan/SKILL.md).
 
@@ -108,9 +108,9 @@ Multi-language code quality scanner using MegaLinter, jscpd, Lizard, and per-lan
 | SARIF generation | Mixed: MegaLinter and jscpd native; Lizard via `lizard-to-sarif.py`, coverage via `coverage-to-sarif.py` |
 | Copilot artifacts | 2 agents (CodeQualityDetector, TestGenerator), 2 prompts, instructions, 1 skill |
 | SARIF category | `code-quality/coverage/` |
-| Power BI PBIP | `power-bi/` (planned — 4 pages: Quality Overview, Coverage by Repository, Complexity Analysis, Test Generation Tracking) |
+| Power BI PBIP | `power-bi/` (4 pages: Quality Overview, Coverage by Repository, Complexity Analysis, Test Generation Tracking) |
 
-### `code-quality-scan-workshop` (Planned)
+### `code-quality-scan-workshop`
 
 Eight hands-on labs teaching code quality scanning across multiple languages.
 
@@ -119,7 +119,7 @@ Eight hands-on labs teaching code quality scanning across multiple languages.
 | Labs | 8 labs (Lab 00–07) covering ESLint, Pylint, Checkstyle, dotnet-coverage, SARIF, CI/CD |
 | Delivery tiers | 5 tiers following the standard half-day/full-day/dual pattern |
 | Dual platform | GitHub Actions (Lab 06-github, Lab 07-github) and ADO Pipelines (Lab 06-ado, Lab 07-ado) |
-| Template repo | Yes (planned) |
+| Template repo | Yes |
 
 ## Two-Repo Pattern
 
diff --git a/instructions/domain-scaffolding.instructions.md b/instructions/domain-scaffolding.instructions.md
@@ -5,7 +5,7 @@ applyTo: "**"
 
 # Domain Scaffolding Conventions
 
-These conventions apply when generating new domain scanner and workshop repositories. All scaffolded repos MUST follow these standards to maintain parity with existing Accessibility and FinOps domains.
+These conventions apply when generating new domain scanner and workshop repositories. All scaffolded repos MUST follow these standards to maintain parity with existing Accessibility, Code Quality, and FinOps domains.
 
 ## Naming Conventions
 
@@ -561,6 +561,46 @@ The workshop `_includes/head_custom.html` MUST use `startOnLoad: false` with an
 </style>
 ```
 
+## Workshop Copilot Artifacts
+
+Workshop repositories MUST include a `.github/` directory with Copilot customization artifacts. These artifacts enable GitHub Copilot to provide domain-aware assistance to workshop participants.
+
+### Required Directory Structure
+
+```text
+{domain}-scan-workshop/
+└── .github/
+    ├── agents/
+    │   └── {domain}-workshop.agent.md           # Workshop-specific Copilot agent
+    ├── instructions/
+    │   └── {domain}-workshop.instructions.md    # Workshop-specific Copilot instructions
+    └── copilot-instructions.md                  # Repo-wide Copilot instructions
+```
+
+### Minimum Artifacts
+
+| Artifact | File | Purpose |
+|----------|------|---------|
+| Agent | `.github/agents/{domain}-workshop.agent.md` | Defines a workshop-aware Copilot agent with domain context, lab navigation, and troubleshooting capabilities |
+| Instructions | `.github/instructions/{domain}-workshop.instructions.md` | Provides domain-specific conventions, lab structure, and coding patterns for Copilot |
+| Copilot Instructions | `.github/copilot-instructions.md` | Repo-wide Copilot instructions referencing the domain agent and instructions files |
+
+### Agent File Conventions
+
+The workshop agent MUST:
+
+1. Reference the domain scan skill for scanning methodology context.
+2. Include tools for reading files, searching the codebase, and running terminal commands.
+3. Provide guidance on lab completion, troubleshooting common errors, and navigating the workshop structure.
+
+### Instructions File Conventions
+
+The workshop instructions MUST:
+
+1. Define the lab numbering scheme and directory structure.
+2. Specify the domain-specific tool stack and configuration.
+3. Reference the demo-app repository as the working directory for scanning labs.
+
 ## Power BI PBIP Conventions
 
 ### Directory Structure
@@ -590,6 +630,15 @@ One `.tmdl` file per table in `definition/tables/`. Use descriptive table names
 
 Connect to Azure Data Lake Storage Gen2 via `AzureStorage.DataLake()` with OAuth (Organizational Account). Store scan results in date-partitioned paths: `{yyyy}/{MM}/{dd}/{appId}-{tool}.json`.
 
+### Centralized Dashboard Integration
+
+In addition to per-domain PBIPs, the framework provides a centralized `advsec-pbi-report-ado` dashboard that aggregates Advanced Security findings across all domains. New domain PBIPs MUST integrate with this centralized dashboard:
+
+1. **Shared `Repositories` dimension** — use the `scan_domain` column to identify the domain (e.g., `Accessibility`, `CodeQuality`, `FinOps`). This enables cross-domain filtering in the centralized report.
+2. **Consistent fact table schema** — align `finding_id`, `repo_name`, `rule_id`, `severity`, `tool_name`, and `scan_date` columns with the centralized schema so the AdvSec report can union findings across domains.
+3. **ADLS Gen2 path convention** — store scan results in `{domain}/{yyyy}/{MM}/{dd}/{appId}-{tool}.json` so the centralized report's Power Query expressions can discover data from all domains.
+4. **Three-tier architecture** — the centralized `advsec-pbi-report-ado` provides the Advanced Security cross-domain view, while per-domain PBIPs provide domain-specific deep dives. Together they offer a holistic view across all scanning domains.
+
 ## Workshop Lab Conventions
 
 ### Lab Numbering
diff --git a/prompts/scaffold-domain.prompt.md b/prompts/scaffold-domain.prompt.md
@@ -17,5 +17,5 @@ argument-hint: "[domain=...] [tools=...]"
 1. Load the domain scaffolding skill and the domain-specific scan skill.
 2. Generate the complete `{domain}-scan-demo-app` repository structure with 5 sample apps, CI/CD pipelines, bootstrap scripts, SARIF converters, and Power BI PBIP.
 3. Generate the complete `{domain}-scan-workshop` repository structure with 10 labs, screenshot automation, dev container, and Jekyll site.
-4. Ensure structural parity with accessibility-scan-demo-app and finops-scan-demo-app.
+4. Ensure structural parity with accessibility-scan-demo-app, code-quality-scan-demo-app, and finops-scan-demo-app.
 5. Produce a scaffolding summary with file counts and next steps.
diff --git a/skills/domain-scaffolding/SKILL.md b/skills/domain-scaffolding/SKILL.md
@@ -23,6 +23,7 @@ The demo-app repo owns all scanning logic, Copilot customization artifacts, and
 | Domain | Demo App | Workshop |
 |--------|----------|----------|
 | Accessibility | `accessibility-scan-demo-app` | `accessibility-scan-workshop` |
+| Code Quality | `code-quality-scan-demo-app` | `code-quality-scan-workshop` |
 | FinOps | `finops-scan-demo-app` | `finops-scan-workshop` |
 
 ## Demo App Repository Template
@@ -154,6 +155,12 @@ The following directory tree is the canonical structure for any `{domain}-scan-w
 ├── _config.yml                                  # Jekyll configuration
 ├── index.md                                     # Workshop home / GitHub Pages landing
 ├── Gemfile                                      # Jekyll dependencies
+├── .github/
+│   ├── agents/
+│   │   └── {domain}-workshop.agent.md           # Workshop-specific Copilot agent
+│   ├── instructions/
+│   │   └── {domain}-workshop.instructions.md    # Workshop-specific Copilot instructions
+│   └── copilot-instructions.md                  # Repo-wide Copilot instructions
 ├── _includes/
 │   └── head_custom.html                         # Mermaid v11 ESM support
 ├── .devcontainer/
@@ -608,6 +615,15 @@ Path pattern: {yyyy}/{MM}/{dd}/{appId}-{tool}.json
 | `power-bi/scripts/deploy.ps1` | Deploy PBIP to Power BI workspace using `FabricPS-PBIP` module |
 | `power-bi/scripts/setup-parameters.ps1` | Configure data source parameters (storage account, container) |
 
+### Centralized Dashboard Integration
+
+In addition to per-domain PBIPs, the framework maintains a centralized `advsec-pbi-report-ado` dashboard that aggregates Advanced Security findings across all domains. Per-domain PBIPs integrate with this centralized dashboard through:
+
+1. **Shared `Repositories` dimension** — the `scan_domain` column identifies each domain (`Accessibility`, `CodeQuality`, `FinOps`), enabling cross-domain filtering.
+2. **Consistent fact table schema** — `finding_id`, `repo_name`, `rule_id`, `severity`, `tool_name`, and `scan_date` columns align across all domain PBIPs.
+3. **ADLS Gen2 path convention** — scan results stored at `{domain}/{yyyy}/{MM}/{dd}/{appId}-{tool}.json` allow the centralized report to discover data from all domains.
+4. **Three-tier architecture** — the centralized `advsec-pbi-report-ado` provides the cross-domain Advanced Security view, per-domain PBIPs provide deep dives, and together they offer a holistic view across all scanning domains.
+
 ## CI/CD Pipeline Templates
 
 ### GitHub Actions
