feat: add comprehensive GitHub Copilot configuration by anakrish · Pull Request #694 · microsoft/regorus

anakrish · 2026-04-26T20:39:46Z

Configure GitHub Copilot for regorus with deep domain knowledge,
multi-perspective code review, and automated codebase auditing.

Copilot Instructions and Knowledge Base

Add copilot-instructions.md with project identity, coding rules, build
commands, and references to 20 knowledge files covering every major
subsystem: value semantics, interpreter architecture, Rego compiler,
RVM, builtin system, FFI boundary, Azure policy/RBAC languages, error
handling, feature composition, security, and more. Each knowledge file
maps domain concepts to specific source files so Copilot understands
what code implements what behavior.

Code Review Instructions

Add copilot-code-review-instructions.md with severity categories,
multi-scale thinking guidance, and 10 embedded review perspectives.
Reviews are organized around the concern being examined (security,
reliability, semantics, performance, API design) rather than a
checklist, encouraging Copilot to think freely about each change.

Agents and Skills

Add 17 role-based agents under .github/agents/ — each is a specialist
persona (architect, security-auditor, red-teamer, semantics-expert,
test-engineer, reliability-engineer, performance-engineer, etc.) with
domain-specific instructions grounded in regorus internals.

Add 6 skills under .github/skills/ for structured workflows:
add-builtin, design-alternatives, opa-conformance, security-review,
thorough-review, and verification.

Multi-Perspective PR Review (GitHub Actions)

Add perspective-review.yml workflow and perspective-review.sh script.
On every PR, the system parses the diff to extract valid line anchors
with actual code content, selects relevant perspectives based on
changed file paths, calls the GitHub Models API (gpt-4o-mini) for
each perspective, and posts inline PR review comments via the GitHub
PR Review API. Findings include severity tags, code snippets, and
perspective attribution.

Codebase Audit System

Add codebase-audit.yml workflow and codebase-audit.sh script for
analyzing existing code — not just PR diffs. Uses deterministic-first
file discovery: searches knowledge files for topic relevance, extracts
referenced source paths, expands via grep, then LLM reranks for precision.
Files are analyzed in clusters per perspective, with findings posted as
rolling GitHub Issues (one per topic, updated on rerun).

11 audit presets covering: panic safety, FFI boundary, security hardening,
undefined propagation, resource limits, performance, design alternatives,
code cleanup, test gaps, API ergonomics, and knowledge accuracy. Runs on
a Mon/Wed/Fri schedule rotating through all presets (~4 week full cycle).

Knowledge Accuracy Audit

Add knowledge-accuracy.sh as a specialized audit that compares each
docs/knowledge/*.md file against the actual source code it documents.
Detects factual inaccuracies, stale descriptions from refactoring,
deleted/renamed files, and significant source files (>100 lines) with
no knowledge documentation.

Configuration Validation

Add copilot-config-validation.yml workflow that validates YAML syntax,
checks that all knowledge file references resolve, verifies skill
frontmatter, and tracks knowledge-to-source freshness. Runs on config
changes, weekly, and on manual dispatch.

Cloud Agent Setup

Add copilot-setup-steps.yml to configure the Copilot cloud agent
environment with Rust toolchain, cargo cache, and dependency fetch.

63 files changed, ~9000 insertions
Replaces #693 which had 47 files (missing perspective review, codebase audit, and knowledge accuracy audit).

Copilot

Pull request overview

Adds a full GitHub Copilot “operating system” for the regorus repo: baseline instructions + deep subsystem knowledge, role-based agents/skills, and CI workflows/scripts to automate multi-perspective PR reviews and recurring codebase audits.

Changes:

Added a 20-file domain knowledge base under docs/knowledge/ plus a Copilot configuration architecture doc.
Added role-based agents (.github/agents/) and task skills (.github/skills/) for structured review and engineering workflows.
Added GitHub Actions workflows + scripts for perspective-based PR reviews, scheduled/topic-driven codebase audits, and configuration validation.

Reviewed changes

Copilot reviewed 63 out of 63 changed files in this pull request and generated 4 comments.

Show a summary per file

File	Description
.github/copilot-instructions.md	Baseline Copilot identity, coding rules, build commands, and knowledge index
.github/copilot-code-review-instructions.md	Review guidance (severity, perspectives, multi-scale thinking)
docs/copilot-architecture.md	Explains how instructions/knowledge/agents/skills/CI fit together
.github/workflows/perspective-review.yml	Runs multi-perspective PR review automation
.github/workflows/codebase-audit.yml	Scheduled/manual audits that open/update GitHub Issues with findings
.github/workflows/copilot-config-validation.yml	Validates config structure, references, and basic freshness signals
.github/workflows/copilot-setup-steps.yml	Cloud-agent environment setup (Rust toolchain, cache, fetch)
.github/scripts/perspective-review.sh	Implements PR diff anchoring + per-perspective model calls + PR review posting
.github/scripts/codebase-audit.sh	Implements topic-based codebase discovery + analysis + issue reporting
.github/scripts/knowledge-accuracy.sh	Compares knowledge docs vs referenced source for drift/incorrectness
.github/prompts/audit-panic-safety.json	Audit preset: panic safety
.github/prompts/audit-ffi-boundary.json	Audit preset: FFI boundary safety
.github/prompts/audit-security-hardening.json	Audit preset: security hardening
.github/prompts/audit-undefined-propagation.json	Audit preset: undefined propagation correctness
.github/prompts/audit-resource-limits.json	Audit preset: resource limits / DoS protection
.github/prompts/audit-performance.json	Audit preset: performance
.github/prompts/audit-design-alternatives.json	Audit preset: design alternatives
.github/prompts/audit-code-cleanup.json	Audit preset: code cleanup
.github/prompts/audit-test-gaps.json	Audit preset: test gaps
.github/prompts/audit-api-ergonomics.json	Audit preset: API ergonomics
.github/prompts/audit-knowledge-accuracy.json	Audit preset: knowledge accuracy (scripted)
.github/skills/thorough-review/SKILL.md	Multi-agent review orchestration workflow
.github/skills/security-review/SKILL.md	Security-focused review workflow
.github/skills/opa-conformance/SKILL.md	OPA conformance workflow
.github/skills/verification/SKILL.md	Verification workflow (Miri/property testing/etc.)
.github/skills/design-alternatives/SKILL.md	Structured design alternatives workflow
.github/skills/add-builtin/SKILL.md	Step-by-step builtin addition workflow
.github/agents/tech-lead.agent.md	Synthesis/decision agent with guardrails
.github/agents/semantics-expert.agent.md	Rego/Azure semantics correctness agent
.github/agents/red-teamer.agent.md	Adversarial review agent
.github/agents/security-auditor.agent.md	Systematic security assurance agent
.github/agents/reliability-engineer.agent.md	Reliability/failure-mode agent
.github/agents/performance-engineer.agent.md	Performance/hot-path agent
.github/agents/architect.agent.md	Cross-boundary architecture agent
.github/agents/api-steward.agent.md	API stability/cross-binding parity agent
.github/agents/test-engineer.agent.md	Test strategy/coverage agent
.github/agents/verification-engineer.agent.md	Formal verification/property obligations agent
.github/agents/support-engineer.agent.md	Debuggability/operational diagnostics agent
.github/agents/refactorer.agent.md	Maintainability/refactoring agent
.github/agents/ci-engineer.agent.md	CI/caching/workflow agent
.github/agents/dx-engineer.agent.md	Developer experience agent
.github/agents/demo-engineer.agent.md	Examples/tutorials/demo agent
.github/agents/program-manager.agent.md	Scope/user-impact/success-criteria agent
docs/knowledge/value-semantics.md	Value/Number semantics + Undefined rules
docs/knowledge/rego-semantics.md	Rego evaluation semantics and pitfalls
docs/knowledge/rego-compiler.md	Rego→RVM compilation concepts
docs/knowledge/interpreter-architecture.md	Tree-walking interpreter internals
docs/knowledge/rvm-architecture.md	RVM structure/execution/limits
docs/knowledge/compilation-pipeline.md	Scheduler/hoisting/destructuring pipeline
docs/knowledge/builtin-system.md	Builtin registration/feature gating/conformance rules
docs/knowledge/engine-api.md	Public Engine API behavior and flow
docs/knowledge/error-handling-migration.md	anyhow→thiserror migration guidance
docs/knowledge/policy-evaluation-security.md	Threat model, limits, panic-safety posture
docs/knowledge/ffi-boundary.md	FFI invariants across bindings
docs/knowledge/feature-composition.md	Feature matrix + no_std/arc/rvm composition rules
docs/knowledge/telemetry-and-diagnostics.md	Diagnostics/telemetry architecture and roadmap
docs/knowledge/causality-and-partial-eval.md	Planned causality + partial evaluation design
docs/knowledge/tooling-architecture.md	LSP/linter/analyzer architectural hooks
docs/knowledge/language-extension-guide.md	How to add new policy languages
docs/knowledge/time-builtins-compat.md	Time builtin + Go time.Parse compatibility notes
docs/knowledge/azure-policy-language.md	Azure Policy language architecture
docs/knowledge/azure-policy-aliases.md	Azure Policy alias normalization/denormalization details
docs/knowledge/azure-rbac-language.md	Azure RBAC condition language architecture

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

anakrish

⚙️ Reliability Engineer — 4 finding(s)

anakrish

🧪 Test Engineer — 5 finding(s)

anakrish

⚙️ Reliability Engineer — 5 finding(s)

anakrish

🧪 Test Engineer — 6 finding(s)

Copilot

Pull request overview

Copilot reviewed 67 out of 68 changed files in this pull request and generated 1 comment.

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

anakrish

⚙️ Reliability Engineer — 5 finding(s)

anakrish

🧪 Test Engineer — 5 finding(s)

Copilot

Pull request overview

Copilot reviewed 67 out of 68 changed files in this pull request and generated 4 comments.

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

Copilot

Pull request overview

Copilot reviewed 66 out of 67 changed files in this pull request and generated 5 comments.

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

Copilot

Pull request overview

Copilot reviewed 67 out of 68 changed files in this pull request and generated 7 comments.

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

Copilot

Pull request overview

Copilot reviewed 67 out of 67 changed files in this pull request and generated no new comments.

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

Copilot

Pull request overview

Copilot reviewed 67 out of 67 changed files in this pull request and generated 3 comments.

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

Copilot

Pull request overview

Copilot reviewed 67 out of 67 changed files in this pull request and generated 3 comments.

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

Configure GitHub Copilot for regorus with deep domain knowledge, multi-perspective code review, and automated codebase auditing. Copilot Instructions and Knowledge Base ──────────────────────────────────────── Add copilot-instructions.md with project identity, coding rules, build commands, and references to 20 knowledge files covering every major subsystem: value semantics, interpreter architecture, Rego compiler, RVM, builtin system, FFI boundary, Azure policy/RBAC languages, error handling, feature composition, security, and more. Each knowledge file maps domain concepts to specific source files so Copilot understands what code implements what behavior. Code Review Instructions ──────────────────────── Add copilot-code-review-instructions.md with severity categories, multi-scale thinking guidance, and 10 embedded review perspectives. Reviews are organized around the concern being examined (security, reliability, semantics, performance, API design) rather than a checklist, encouraging Copilot to think freely about each change. Agents and Skills ───────────────── Add 16 role-based agents under .github/agents/ — each is a specialist persona (architect, security-auditor, red-teamer, semantics-expert, test-engineer, reliability-engineer, performance-engineer, etc.) with domain-specific instructions grounded in regorus internals. Add 6 skills under .github/skills/ for structured workflows: add-builtin, design-alternatives, opa-conformance, security-review, thorough-review, and verification. Multi-Perspective PR Review (GitHub Actions) ──────────────────────────────────────────── Add perspective-review.yml workflow and perspective-review.sh script. On every PR, the system parses the diff to extract valid line anchors with actual code content, selects relevant perspectives based on changed file paths, calls the GitHub Models API (gpt-4o-mini) for each perspective, and posts inline PR review comments via the GitHub PR Review API. Findings include severity tags, code snippets, and perspective attribution. Codebase Audit System ───────────────────── Add codebase-audit.yml workflow and codebase-audit.sh script for analyzing existing code — not just PR diffs. The system uses a deterministic-first file discovery strategy: it searches knowledge files for topic relevance, extracts referenced source paths, expands via grep, then lets the LLM rerank for precision. Files are analyzed in clusters per perspective, with findings posted as rolling GitHub Issues (one issue per topic, updated on rerun). Add 11 audit presets under .github/prompts/ covering: panic safety, FFI boundary, security hardening, undefined propagation, resource limits, performance, design alternatives, code cleanup, test gaps, API ergonomics, and knowledge accuracy. The workflow runs on a Mon/Wed/Fri schedule rotating through all presets for continuous coverage (~4 week full cycle). Knowledge Accuracy Audit ──────────────────────── Add knowledge-accuracy.sh as a specialized audit that compares each docs/knowledge/*.md file against the actual source code it documents. It detects factual inaccuracies, stale descriptions from refactoring, deleted or renamed files still referenced in docs, and significant source files (>100 lines) with no knowledge documentation. Configuration Validation ──────────────────────── Add copilot-config-validation.yml workflow that validates YAML syntax, checks that all knowledge file references resolve, verifies skill frontmatter, and tracks knowledge-to-source freshness (warns when source files change more recently than their knowledge docs). Runs on config changes, weekly, and on manual dispatch. Cloud Agent Setup ───────────────── Add copilot-setup-steps.yml to configure the Copilot cloud agent environment with Rust toolchain, cargo cache, and dependency fetch. Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>

Copilot

Pull request overview

Copilot reviewed 67 out of 67 changed files in this pull request and generated 5 comments.

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

Copilot · 2026-04-28T21:39:02Z

+for f in "${VALID_FILES[@]}"; do
+  file_size=$(wc -c < "$f" 2>/dev/null || echo 0)
+
+  # If adding this file exceeds 15KB, start a new cluster
+  if [ $current_size -gt 0 ] && [ $((current_size + file_size)) -gt 15000 ]; then
+    CLUSTERS+=("$current_cluster")
+    CLUSTER_FILE_LISTS+=("$current_files")
+    current_cluster=""
+    current_files=""
+    current_size=0
+  fi
+
+  # Add file to current cluster (truncate individual files at 8KB)
+  file_content=$(head -c 8000 "$f")
+  current_cluster="${current_cluster}
+--- file: ${f} ---
+${file_content}
+"
+  current_files="${current_files}${f} "
+  current_size=$((current_size + ${#file_content}))
+done


In the clustering loop, the “would this exceed 15KB?” check uses the full on-disk file size (wc -c) even though you only include up to 8KB of content (head -c 8000). For any file >8KB this will artificially split clusters early, increasing the number of model/API calls (and runtime/cost) without improving context quality. Consider basing the threshold on the number of bytes actually appended (e.g., content_len=${#file_content} / min(file_size, 8000)) and including the fixed overhead of the --- file: ... --- header in the size accounting.

Copilot · 2026-04-28T21:39:02Z

+Go's `time.Parse` allows missing year or time components. Chrono is stricter.
+The compatibility layer fills in defaults:
+- Missing year → 0 (or current year depending on context)
+- Missing time → 00:00:00
+- Missing timezone → UTC


The docs say missing year defaults to “0 (or current year depending on context)”, but src/builtins/time/compat.rs always fills missing year with 0 (see the parsed.set_year(0)? block when no year fields are present). Please adjust this bullet to match the actual behavior, or update the implementation if “current year” is intended.

Copilot · 2026-04-28T21:39:03Z

+### NodeRef Pattern
+
+AST nodes use `Ref<T>` (Rc-based) with pointer-identity comparison:
+```rust
+type Ref<T> = Rc<T>;
+```


This code block claims Ref<T> is just an alias of Rc<T>, but in src/ast.rs it’s a NodeRef<T> newtype wrapping Rc<T> (with pointer-identity Eq/Ord). Since the exact type matters for tooling (e.g., comparisons/ordering), please update the snippet to reflect the real definition.

Copilot · 2026-04-28T21:39:03Z

+## Essential Coding Rules
+
+**No panics — ever** (deny lints enforce this):
+```rust
+// Use typed errors for new code
+let v = map.get("key").ok_or(MyError::MissingKey("key"))?;
+// Or anyhow in existing modules
+let v = map.get("key").ok_or_else(|| anyhow!("missing key"))?;
+```
+
+**No unchecked indexing** — use `.get()` + `?` or iterate.
+
+**No unchecked arithmetic** — use `checked_add()`, `saturating_add()`, etc.


The “No unchecked indexing” rule reads as an absolute invariant, but the codebase explicitly allows clippy::indexing_slicing in a number of modules (e.g., src/value.rs and several compiler/builtin modules) for performance. To avoid contradicting the actual project conventions, consider rephrasing this as “avoid unchecked indexing in new code unless you’re in a documented, performance-critical hotspot and add a local #[allow(clippy::indexing_slicing)] with rationale.”

Copilot · 2026-04-28T21:39:03Z

+
+**Purpose**: Orient the agent to regorus identity, coding rules, build commands,
+and provide a reference table of all 20 knowledge files.
+
+**Design principle**: Keep this lean (~5 KB). Deep knowledge lives in
+`docs/knowledge/` — this file just tells the agent where to look.
+
+### 2. Code Review Instructions (`copilot-code-review-instructions.md`)
+
+**When loaded**: Automatically during GitHub PR code reviews.
+
+**Purpose**: Guide review thinking with severity categories, multi-scale review
+approach, and domain-specific context (Undefined, FFI, dual-path, telemetry).
+
+**Design principle**: "Think freely" — provides domain knowledge as context,
+not a prescriptive checklist. The agent decides what to focus on.
+
+### 3. Knowledge Files (`docs/knowledge/*.md`)
+
+**When loaded**: On demand, when an agent or skill references them.
+
+**Purpose**: Deep institutional knowledge about specific subsystems. Each file
+captures knowledge that is not obvious from reading the code alone.
+
+**20 files, ~70 KB total:**
+
+| Category | Files |
+|----------|-------|
+| Core engine | `value-semantics`, `engine-api`, `error-handling-migration` |
+| Execution | `interpreter-architecture`, `rvm-architecture`, `compilation-pipeline` |
+| Rego language | `rego-semantics`, `rego-compiler`, `builtin-system` |
+| Azure languages | `azure-policy-language`, `azure-policy-aliases`, `azure-rbac-language` |
+| Safety & security | `policy-evaluation-security`, `ffi-boundary`, `feature-composition` |
+| Diagnostics | `telemetry-and-diagnostics`, `causality-and-partial-eval` |
+| Extensibility | `language-extension-guide`, `tooling-architecture`, `time-builtins-compat` |
+


This document states there are “20 knowledge files”, but docs/knowledge/ currently contains 21 files (including workflow-security.md), and .github/copilot-instructions.md also references workflow-security.md. Please either update the count/table here to include workflow-security, or remove/relocate that file so the numbers and lists stay consistent.

anakrish requested a review from Copilot April 26, 2026 20:41

Copilot started reviewing on behalf of anakrish April 26, 2026 20:41 View session

anakrish force-pushed the copilot-config branch from d88f8a4 to f09dd6d Compare April 26, 2026 20:42

Copilot AI reviewed Apr 26, 2026

View reviewed changes

Comment thread docs/knowledge/value-semantics.md Outdated

Comment thread .github/workflows/perspective-review.yml Outdated

Comment thread .github/workflows/perspective-review.yml Outdated

Comment thread .github/workflows/codebase-audit.yml

anakrish force-pushed the copilot-config branch from f09dd6d to 975e204 Compare April 26, 2026 20:52

anakrish commented Apr 26, 2026

View reviewed changes

Comment thread .github/agents/api-steward.agent.md

Comment thread .github/agents/reliability-engineer.agent.md

Comment thread .github/agents/semantics-expert.agent.md

Comment thread .github/agents/support-engineer.agent.md

anakrish commented Apr 26, 2026

View reviewed changes

Comment thread .github/agents/api-steward.agent.md

Comment thread .github/agents/api-steward.agent.md

Comment thread .github/agents/api-steward.agent.md

Comment thread .github/agents/api-steward.agent.md

Comment thread .github/agents/api-steward.agent.md

anakrish force-pushed the copilot-config branch 2 times, most recently from 75bbe28 to 061edf1 Compare April 26, 2026 21:48

anakrish requested a review from Copilot April 27, 2026 01:03

anakrish force-pushed the copilot-config branch from 061edf1 to db735be Compare April 27, 2026 01:04

anakrish commented Apr 27, 2026

View reviewed changes

Copilot AI reviewed Apr 27, 2026

View reviewed changes

Comment thread .github/workflows/codebase-audit.yml Outdated

anakrish force-pushed the copilot-config branch from db735be to c2f5f8e Compare April 27, 2026 15:25

anakrish requested a review from Copilot April 27, 2026 15:28

Copilot started reviewing on behalf of anakrish April 27, 2026 15:29 View session

anakrish commented Apr 27, 2026

View reviewed changes

Comment thread .github/agents/api-steward.agent.md

Comment thread .github/agents/api-steward.agent.md

Comment thread .github/agents/api-steward.agent.md

Comment thread .github/agents/api-steward.agent.md

Comment thread .github/agents/api-steward.agent.md

Copilot AI reviewed Apr 27, 2026

View reviewed changes

Comment thread .github/workflows/codebase-audit.yml

Comment thread .github/workflows/#miri.yml# Outdated

Comment thread docs/knowledge/workflow-security.md

Comment thread .github/workflows/copilot-config-validation.yml

anakrish force-pushed the copilot-config branch 3 times, most recently from ea0036a to 9b48621 Compare April 27, 2026 16:37

anakrish requested a review from Copilot April 27, 2026 16:39

Copilot started reviewing on behalf of anakrish April 27, 2026 16:40 View session

Copilot AI reviewed Apr 27, 2026

View reviewed changes

Comment thread .github/skills/add-builtin/SKILL.md

Comment thread .github/skills/add-builtin/SKILL.md

Comment thread .github/scripts/perspective-review.sh Outdated

Comment thread .github/scripts/perspective-review.sh Outdated

Comment thread docs/knowledge/time-builtins-compat.md

anakrish force-pushed the copilot-config branch 4 times, most recently from cdbb511 to ff13e6b Compare April 27, 2026 19:36

anakrish force-pushed the copilot-config branch 2 times, most recently from ca51cd0 to 49a2111 Compare April 27, 2026 23:06

anakrish requested a review from Copilot April 28, 2026 00:03

Copilot started reviewing on behalf of anakrish April 28, 2026 00:04 View session