Skip to content

copilot instructions

Jump to bottom
Emmanuel Knafo edited this page Apr 3, 2026 · 3 revisions

description: "Required conventions for authoring, structuring, and maintaining the Agentic Accelerator Framework wiki" applyTo: "**/*.md"

Wiki Purpose

This wiki documents the hands-on journey of building, extending, and operating the Agentic Accelerator Framework — a comprehensive framework that combines GitHub Advanced Security, custom GitHub Copilot agents, and Microsoft Defender for Cloud to shift security and compliance left across four domains: Security, Accessibility, Code Quality, and FinOps.

The wiki captures non-deterministic, agentic workflows — real Copilot sessions where subagents scaffold repositories, generate sample apps, build SARIF converters, produce Power BI PBIPs, create workshop labs, and automate screenshot capture. Every page should read as a narrative log with rich screenshot context so readers can follow along and reproduce the journey.

Source Repository Context

The home repository is devopsabcs-engineering/agentic-accelerator-framework. Key structural facts to reference when writing wiki pages:

Path Purpose
agents/ 15 custom GitHub Copilot agent definitions (.agent.md)
instructions/ Path-specific instruction files (a11y-remediation, code-quality, WCAG 2.2 rules)
prompts/ Reusable prompt templates (a11y-fix, a11y-scan, scaffold-domain)
skills/ On-demand domain knowledge packages (SKILL.md files)
scripts/ Agent validation tooling and bootstrap scripts
docs/ 9+ framework documentation guides
sample-app/ Next.js demo application with Bicep infrastructure
samples/azure-devops/ 3 sample ADO pipeline YAML files
.github/workflows/ 7 GitHub Actions CI/CD pipelines
apm.yml APM dependency manifest
mcp.json MCP server configuration (ADO work items)

Agent Inventory (15 Agents)

Domain Agents Category Prefix
Security SecurityAgent, SecurityReviewerAgent, SecurityPlanCreator, PipelineSecurityAgent, IaCSecurityAgent, SupplyChainSecurityAgent security/
Accessibility A11yDetector, A11yResolver accessibility-scan/
Code Quality CodeQualityDetector, TestGenerator code-quality/coverage/
FinOps CostAnalysisAgent, FinOpsGovernanceAgent, CostAnomalyDetector, CostOptimizerAgent, DeploymentCostGateAgent finops-finding/v1

CI/CD Workflows

Workflow Trigger Purpose
security-scan.yml PR and push to main SCA, SAST (CodeQL), IaC, container, and DAST scanning
accessibility-scan.yml PR and weekly schedule Three-engine a11y scan with threshold gating
code-quality.yml PR Lint, type check, test, and 80 % coverage gate
finops-cost-gate.yml PR (IaC file changes) Infracost estimate against monthly budget
apm-security.yml PR (agent config file changes) APM audit for prompt file supply chain attacks
ci-full-test.yml Push and PR to main Agent validation (structure, cross-refs, domain rules)
deploy-to-github-private.yml Push to main Syncs agent config to org-wide .github-private repository

Related Repositories and Workshops

DIY Domain Scaffolding

The DomainScaffolder agent and /scaffold-domain prompt automate the creation of new domain repositories with full parity to existing Accessibility and FinOps domains. The Code Quality domain is the current build target, producing: 5 demo apps, SARIF converters (coverage-to-sarif.py, lizard-to-sarif.py), Power BI PBIP, bootstrap scripts, screenshot automation, and 10 workshop labs.

Wiki Structure

Organize wiki pages using the following hierarchy. Create new pages as the journey progresses. Each page focuses on one logical phase or topic.

Home.md                              ← Landing page and journey overview
_Sidebar.md                          ← Navigation sidebar (auto-rendered by GitHub)
DIY-Code-Quality-Domain.md           ← Full DIY walkthrough with screenshots
Non-Deterministic-Journey-1.md       ← First agentic session log
Non-Deterministic-Journey-2.md       ← Subsequent iteration logs (one per session)
Verification-and-Validation.md       ← Post-build verification steps and results
Agent-Inventory.md                   ← Agent catalog with descriptions and domains
CI-CD-Pipelines.md                   ← Workflow documentation and trigger matrix
Architecture.md                      ← Framework architecture diagrams and notes
Workshop-Labs.md                     ← Lab summaries and cross-references
Power-BI-Dashboards.md               ← PBIP setup, semantic model, report pages
Screenshot-Automation.md             ← capture-screenshots.ps1 and manifest docs
Troubleshooting.md                   ← Common issues and resolutions

Screenshot and Image Rules

Strip Dimensions from Image Tags

All <img> tags MUST omit width and height attributes. These force fixed pixel sizes that stretch or compress images on different viewports. Let the browser or GitHub renderer handle responsive sizing.

Wrong — never do this:

<img width="2082" height="977" alt="image" src="..." />

Correct — always do this:

<img alt="Copilot automode session showing DomainScaffolder agent running" src="..." />

When editing existing pages, actively search for and strip any width="..." or height="..." attributes from <img> tags.

Enforcement: Before committing any wiki edit, run a global search for width= and height= inside <img> tags across the entire file. New content pasted from GitHub issue bodies or browser screenshots almost always includes dimensions. Strip them immediately — do not leave this for a follow-up edit.

Descriptive Alt Text (OCR-Driven)

Every screenshot MUST have a descriptive alt attribute that summarizes the visible content of the image. Do not use generic alt text like "image" or "screenshot". Instead, OCR the image and describe:

  1. What UI is shown — VS Code editor, GitHub Actions run, terminal output, Power BI report, GitHub Security Tab, etc.
  2. Key visible text — Agent names, file names, status messages, error text, todo list items, terminal commands, or conversation snippets.
  3. What action is happening — Agent generating code, pipeline running, scaffolding in progress, task completing, etc.

Examples of good alt text:

  • "VS Code Copilot Chat showing DomainScaffolder subagent creating code-quality-scan-demo-app with todo list showing 8 of 12 tasks completed"
  • "GitHub repository file tree for code-quality-scan-demo-app showing src/converters, infra, and .github/workflows directories"
  • "Terminal output of bootstrap-demo-apps.ps1 creating Azure AD app registrations and configuring GitHub secrets"
  • "Power BI report page showing Code Quality Overview with coverage by repository bar chart and complexity heatmap"

Contextual Prose Around Screenshots

Never place screenshots in isolation. Every screenshot MUST be surrounded by contextual prose that explains:

  • Before the image: What is about to happen or what triggered this step
  • After the image: What the reader should observe, key takeaways, or what comes next

Wrong — bare images with no context:

<img alt="image" src="..." />

<img alt="image" src="..." />

Correct — narrated screenshot flow:

With the `DomainScaffolder` agent invoked via `/scaffold-domain domain=code-quality`,
Copilot enters automode and begins creating the repository structure. The todo
list in the chat panel tracks each scaffolding phase:

<img alt="VS Code Copilot Chat in automode with DomainScaffolder agent showing todo list — Phase 1 Repository Structure marked in-progress, 3 of 12 tasks completed" src="https://github.com/user-attachments/assets/e8a5b151-f1ed-4610-b56f-dc9c026441b6" />

The agent delegates heavy lifting to subagents — the Explore agent for
codebase analysis and the Phase Implementor for file generation. Notice the
chat log shows subagent invocations with their return summaries.

Screenshot Grouping

When multiple consecutive screenshots document the same logical step, group them under a single narrative paragraph. Use ordered context to explain progression:

The scaffolding proceeds through sample app creation. The agent generates C#
first, then Python, then Java:

<img alt="VS Code showing DomainScaffolder creating code-quality-demo-app-001 C# ASP.NET project with Program.cs visible" src="..." />

After the C# app, the agent moves to the Python Flask implementation:

<img alt="VS Code showing code-quality-demo-app-002 Python Flask project with app.py and requirements.txt generated" src="..." />

Image Source URLs

Wiki screenshots use GitHub user-attachment URLs in the format:

https://github.com/user-attachments/assets/<uuid>

These are stable, authenticated URLs managed by GitHub. Do not modify or fabricate these URLs. When adding new screenshots, paste them into the GitHub wiki editor or issue body to generate the upload URL automatically.

Page Authoring Conventions

Page Structure

Every wiki page MUST follow this structure:

  1. Title — A single H1 heading describing the page topic
  2. Introduction — 2–3 sentences explaining what this page covers and why
  3. Body — Organized under H2/H3 sections with narrated screenshots
  4. Next Steps — Links to the next logical page or related pages

Heading Hierarchy

  • Start each page with one H1 (#) heading
  • Use H2 (##) for major sections
  • Use H3 (###) for subsections
  • Never skip heading levels

Linking Between Pages

Use wiki-style links for internal cross-references:

See [[Non-Deterministic-Journey-1]] for the first scaffolding session.

Use full URLs for references to the main repository:

See the [DIY guide](https://github.com/devopsabcs-engineering/agentic-accelerator-framework/blob/main/docs/DIY-Code-Quality-Domain.md) for step-by-step instructions.

Code Blocks

  • Always specify a language identifier (powershell, bash, csharp, python, json, yaml, bicep, text, etc.)
  • Prefer powershell over bash for command examples (Windows-first audience)
  • Do not prefix commands with $ or > prompts

Terminology

Use these exact terms consistently:

Term Usage
Agentic Accelerator Framework Full framework name (first mention per page)
DomainScaffolder The agent that scaffolds new domain repositories
automode Copilot's autonomous execution mode
subagent A delegated agent invoked by the primary agent
SARIF Static Analysis Results Interchange Format (always uppercase)
PBIP Power BI Project (always uppercase)
demo-app Scanner demonstration application repository
workshop Hands-on lab repository

Maintenance Workflow

When updating the wiki:

  1. Read the existing page before editing — understand current content
  2. Strip dimensions from any <img> tags encountered — search the entire file for width= and height= before finishing
  3. Replace generic alt text (alt="image", alt="screenshot") with OCR-driven descriptive alt text
  4. Wrap screenshots in narrative context — never leave images bare; add a paragraph before (trigger/context) and after (observation/next)
  5. Rewrite informal notes — convert casual shorthand ("stuff getting created", "didn't take too long") into professional narrative prose
  6. Add heading structure — group related screenshots under H3 subsections; never have more than 2 consecutive screenshots without a heading
  7. Maintain sidebar — update _Sidebar.md when adding new pages
  8. Cross-reference — link related pages and main-repo documentation
  9. Verify links — ensure image URLs resolve and wiki links use correct page names
  10. Final scan — before committing, grep the file for width=, height=, and alt="image" to catch any missed instances

Content Expansion Guidelines

When fleshing out sparse pages (like the current Home.md), follow this process:

  1. Identify each screenshot — OCR or describe visible content
  2. Group screenshots by logical phase (setup, scaffolding, generation, verification)
  3. Write narrative transitions between screenshots explaining what happened and what to look for
  4. Add section headings for each phase
  5. Include cross-references to the main repo's docs (architecture, DIY guide, agent patterns)
  6. Create separate pages for lengthy sections — keep Home.md as an overview with links to detail pages

Common Patterns in Sparse Wiki Content

User-authored wiki entries frequently exhibit these patterns. Apply the corrections below during every edit pass:

Pattern Problem Fix
<img width="2560" height="1392" alt="image" ...> Fixed dimensions + generic alt Strip width/height, write descriptive alt text
Bare screenshot with one-line caption No narrative context Add a paragraph before (what triggered this) and after (what to observe)
Informal notes ("still need to check", "stuff getting created") Not reader-facing Rewrite as professional narrative explaining the verification finding
Missing heading structure Flat list of screenshots Group into H3 subsections by logical topic
alt="image" Fails accessibility and discoverability OCR the screenshot and describe UI, visible text, and action
Raw code block used as observation log Not structured Convert to blockquote callout with numbered observations
Azure portal walkthrough with no step labeling Steps are unclear Number the steps, describe what to click, and what to copy

Post-Scaffolding Verification Pages

Verification sections document what the agent produced versus what still requires manual completion. Structure verification pages using this pattern:

  1. Introduction — State that verification is manual and explain why (agentic output is non-deterministic)
  2. Per-finding subsections — One H3 per issue found, with:
    • Description of the expected state
    • Screenshot showing the current (incorrect) state
    • What needs to be done to fix it
  3. Known issues callout — Use a blockquote (>) to list known rendering or configuration issues
  4. Next steps checklist — Numbered list of manual actions required before the domain reaches parity with existing domains
  5. Critical observations — Use a blockquote with numbered items for deployment or workflow improvements discovered during verification

Known Scaffolding Gaps

The DomainScaffolder agent consistently misses several configuration steps that require GitHub UI or CLI actions outside the file system. Document these when they occur:

  • Template repository flag — gh repo edit --template or Settings UI
  • GitHub Pages enablement — Settings → Pages source branch selection
  • Repository topics/tags — gh repo edit --add-topic or About section
  • Repository description — gh repo edit --description
  • About section website URL — gh repo edit --homepage
  • Mermaid diagram rendering — Jekyll does not support Mermaid natively; requires a JS include or pre-rendered SVGs
  • Screenshot capture — capture-screenshots.ps1 must run after demo apps are deployed, not during scaffolding
  • Missing deploy workflows — Individual sample app repositories may lack deploy.yml workflows that deploy-all.yml expects to call
  • Sequential deployment — deploy-all.yml deploys apps one at a time; should use a matrix strategy for parallel execution
  • Silent failure masking — deploy-all.yml may report success even when individual deployments fail; needs fail-fast or per-job status checks
  • Missing workflow summary — Deployed app URLs are not published to the GitHub Actions job summary; Accessibility and FinOps domains include these

Bootstrap and Deployment Learnings

The bootstrap and deployment process consistently surfaces these issues. Document them as part of any verification or journey page:

  • Script execution order matters — setup-oidc.ps1 must run before bootstrap-demo-apps.ps1, which must complete before deploy-all.yml
  • Idempotency is critical — Both bootstrap scripts must be safe to re-run without duplicating resources. Use az ad app list --filter and gh repo view --json guard checks before creating resources
  • Subscription-scope RBAC chicken-or-egg — The OIDC app registration may need subscription-level Contributor because the target resource group does not exist yet. Document this as a POC trade-off and recommend pre-creating the resource group in production
  • Iterative debugging is normal — Bootstrap scripts rarely work on the first run. Document each error and fix as a subsection to help future users anticipate the same issues

SARIF and Standards Context

Reference these standards when documenting agent output or pipeline results:

  • SARIF v2.1.0 — All agents produce findings in this format
  • WCAG 2.2 Level AA — Accessibility domain standard
  • OWASP Top 10 — Security domain standard
  • CIS Azure Benchmarks, NIST 800-53, PCI-DSS — Compliance frameworks
  • Category prefixes: security/, accessibility-scan/, code-quality/coverage/, finops-finding/v1

Clone this wiki locally