mirror of
https://github.com/microsoft/regorus.git
synced 2026-08-05 02:16:11 +00:00
212 lines
11 KiB
Markdown
212 lines
11 KiB
Markdown
<!-- Copyright (c) Microsoft Corporation. All rights reserved. -->
|
|
<!-- Licensed under the MIT License. -->
|
|
|
|
# Copilot Configuration Architecture
|
|
|
|
This document describes the GitHub Copilot configuration for regorus — how the
|
|
pieces fit together, when each layer activates, and how to extend or modify the
|
|
configuration.
|
|
|
|
## Overview
|
|
|
|
```
|
|
┌─────────────────────────────────────────────────────────────────┐
|
|
│ GitHub Copilot Layers │
|
|
├─────────────────────────────────────────────────────────────────┤
|
|
│ │
|
|
│ Auto-loaded every session: │
|
|
│ ┌───────────────────────────────────────────┐ │
|
|
│ │ .github/copilot-instructions.md (5 KB) │ ← Identity, │
|
|
│ │ Lean orientation + knowledge file refs │ coding rules │
|
|
│ └───────────────────────────────────────────┘ │
|
|
│ │
|
|
│ Auto-loaded during code review: │
|
|
│ ┌───────────────────────────────────────────┐ │
|
|
│ │ .github/copilot-code-review-instructions │ ← "Think freely"│
|
|
│ │ Severity categories + domain context │ review guide │
|
|
│ └───────────────────────────────────────────┘ │
|
|
│ │
|
|
│ Loaded on demand (by description match or explicit invocation):│
|
|
│ ┌──────────────┐ ┌──────────────┐ ┌──────────────┐ │
|
|
│ │ Skills (6) │ │ Agents (16) │ │ Knowledge │ │
|
|
│ │ Task workflows│ │ Role personas│ │ Files (20) │ │
|
|
│ └──────────────┘ └──────────────┘ └──────────────┘ │
|
|
│ │
|
|
│ Cloud agent environment: │
|
|
│ ┌───────────────────────────────────────────┐ │
|
|
│ │ copilot-setup-steps.yml │ ← Rust toolchain │
|
|
│ │ Rust 1.92.0 + clippy + fmt + cache │ + dependencies │
|
|
│ └───────────────────────────────────────────┘ │
|
|
│ │
|
|
│ CI validation: │
|
|
│ ┌───────────────────────────────────────────┐ │
|
|
│ │ copilot-config-validation.yml │ ← Freshness + │
|
|
│ │ YAML syntax, refs, staleness detection │ correctness │
|
|
│ └───────────────────────────────────────────┘ │
|
|
│ │
|
|
└─────────────────────────────────────────────────────────────────┘
|
|
```
|
|
|
|
## Layer Details
|
|
|
|
### 1. Instructions (`copilot-instructions.md`)
|
|
|
|
**When loaded**: Automatically, every Copilot session.
|
|
|
|
**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` |
|
|
|
|
**To add a knowledge file**: Create `docs/knowledge/<name>.md`, add it to the
|
|
reference table in `copilot-instructions.md`, and reference it from relevant
|
|
agents/skills.
|
|
|
|
### 4. Skills (`.github/skills/`)
|
|
|
|
**When loaded**: When the agent determines a skill is relevant (by description
|
|
match) or when explicitly invoked via `/skill-name`.
|
|
|
|
**Purpose**: Task-oriented workflows — step-by-step guidance for specific
|
|
operations.
|
|
|
|
| Skill | Purpose |
|
|
|-------|---------|
|
|
| `thorough-review` | Multi-agent parallel review with cross-agent context |
|
|
| `design-alternatives` | Generate 3+ approaches, evaluate against 9 dimensions |
|
|
| `add-builtin` | Step-by-step guide for adding a new builtin function |
|
|
| `opa-conformance` | OPA conformance testing workflow |
|
|
| `security-review` | Adversarial threat analysis |
|
|
| `verification` | Miri, property testing, Z3, Verus verification strategies |
|
|
|
|
### 5. Agents (`.github/agents/`)
|
|
|
|
**When loaded**: When explicitly invoked via `@agent-name` in chat, or when
|
|
another agent/skill spawns them as subagents.
|
|
|
|
**Purpose**: Role-based personas — each brings a distinct thinking mode to
|
|
code review, feature planning, or technical decisions.
|
|
|
|
**16 agents organized by function:**
|
|
|
|
| Group | Agents | When to use |
|
|
|-------|--------|-------------|
|
|
| **Core engineering** | `red-teamer`, `semantics-expert`, `architect`, `performance-engineer` | Every significant change |
|
|
| **Quality** | `test-engineer`, `verification-engineer`, `security-auditor` | Test coverage, safety-critical changes |
|
|
| **Operations** | `reliability-engineer`, `support-engineer`, `ci-engineer` | Production behavior, diagnostics, CI changes |
|
|
| **Evolution** | `refactorer`, `api-steward` | Cleanup, API surface changes |
|
|
| **Product** | `program-manager`, `demo-engineer`, `dx-engineer` | Feature planning, examples, contributor experience |
|
|
| **Leadership** | `tech-lead` | Reconcile multi-agent findings, make decisions |
|
|
|
|
**Key features:**
|
|
- **Constitutional rules** in `tech-lead` — 9 inviolable guardrails
|
|
- **Cross-agent context protocol** — agents can build on each other's findings
|
|
- **Decision framework** — priority ordering: correctness > security > reliability > stability > performance > maintainability > DX
|
|
|
|
### 6. Cloud Agent Setup (`copilot-setup-steps.yml`)
|
|
|
|
**When loaded**: Before the cloud agent starts working on an issue/PR.
|
|
|
|
**Purpose**: Install Rust 1.92.0, clippy, rustfmt, cargo cache, and fetch
|
|
dependencies so the agent can build and test immediately.
|
|
|
|
### 7. Config Validation (`copilot-config-validation.yml`)
|
|
|
|
**When loaded**: On PR (config file changes), push to main, weekly Monday 7AM UTC.
|
|
|
|
**Purpose**: Validate YAML syntax, knowledge file references, skill frontmatter,
|
|
and detect stale knowledge files (source changed but knowledge file didn't).
|
|
|
|
## How It All Connects
|
|
|
|
### PR Review Flow
|
|
|
|
```
|
|
PR opened
|
|
│
|
|
├─ GitHub auto-loads: copilot-instructions.md
|
|
├─ GitHub auto-loads: copilot-code-review-instructions.md
|
|
│
|
|
├─ Single-pass review (default)
|
|
│ Agent uses domain knowledge to review freely
|
|
│
|
|
└─ /thorough-review (when invoked)
|
|
├─ Phase 1: Understand the change
|
|
├─ Phase 2: Run automated checks
|
|
├─ Phase 3: Select and invoke agents (3-5 based on change type)
|
|
│ ├─ Wave 1: Independent agents (parallel)
|
|
│ ├─ Cross-agent context sharing
|
|
│ └─ Wave 2: Agents informed by Wave 1 findings
|
|
├─ Phase 4: tech-lead synthesizes + applies constitutional rules
|
|
└─ Phase 5: Iterate on critical findings
|
|
```
|
|
|
|
### Feature Development Flow
|
|
|
|
```
|
|
@program-manager "Should we build X?"
|
|
→ Scope, stakeholders, success criteria
|
|
@architect "How should we design X?"
|
|
→ System design, boundary impact, trade-offs
|
|
@design-alternatives "What are the options?"
|
|
→ 3+ approaches, evaluation matrix
|
|
@red-teamer "What could go wrong?"
|
|
→ Attack vectors, failure modes
|
|
@tech-lead "Which approach should we take?"
|
|
→ Decision with rationale
|
|
```
|
|
|
|
## Extending the Configuration
|
|
|
|
### Adding a Knowledge File
|
|
1. Create `docs/knowledge/<name>.md`
|
|
2. Add to the table in `.github/copilot-instructions.md`
|
|
3. Reference from relevant agents and skills
|
|
4. The CI validation workflow will check for broken references
|
|
|
|
### Adding an Agent
|
|
1. Create `.github/agents/<name>.agent.md` with YAML frontmatter
|
|
2. Include: description, tools, user-invocable, argument-hint
|
|
3. Add to the agent selection guide in `thorough-review` skill
|
|
4. Follow the existing pattern: Identity → Mission → What You Look For → Rules → Output Format
|
|
|
|
### Adding a Skill
|
|
1. Create `.github/skills/<name>/SKILL.md` with YAML frontmatter
|
|
2. Include: name, description, allowed-tools
|
|
3. Skills are task workflows — step-by-step guidance, not personas
|
|
|
|
### Modifying Constitutional Rules
|
|
Constitutional rules in `tech-lead.agent.md` are inviolable guardrails.
|
|
They should only change through deliberate, reviewed decisions — never
|
|
as a side effect of another change.
|