diff --git a/.azure-pipelines/AGENTS.md b/.azure-pipelines/AGENTS.md new file mode 100644 index 0000000000..843695c085 --- /dev/null +++ b/.azure-pipelines/AGENTS.md @@ -0,0 +1,12 @@ +# Pipeline Definitions + +## Verification +- Run: `src\dev.cmd build` + +## Conventions +- Keep pipeline edits minimal and consistent with existing YAML structure. +- Prefer existing scripts and variables over introducing new execution paths. + +## Constraints +- Never add production deployment behavior unless explicitly requested. +- Never bypass security, signing, or compliance checks in pipeline changes. diff --git a/.github/agents/docs-writer.agent.md b/.github/agents/docs-writer.agent.md new file mode 100644 index 0000000000..a33872831f --- /dev/null +++ b/.github/agents/docs-writer.agent.md @@ -0,0 +1,14 @@ +--- +name: docs-writer +description: Produces docs-only changes under docs/ and README-linked guidance. +tools: ['read', 'edit', 'search'] +--- + +# Docs Writer + +Use this agent for documentation updates and contributor guidance improvements. + +## TODO + +- Add team style and tone rules. +- Add required sections for new documentation pages. diff --git a/.github/agents/test-specialist.agent.md b/.github/agents/test-specialist.agent.md new file mode 100644 index 0000000000..2f7c90c97f --- /dev/null +++ b/.github/agents/test-specialist.agent.md @@ -0,0 +1,14 @@ +--- +name: test-specialist +description: Focuses on unit and integration test design and regression safety for src/Test. +tools: ['read', 'edit', 'search', 'runTerminalCommand'] +--- + +# Test Specialist + +Use this agent for test-first changes, flaky test triage, and coverage-focused edits. + +## TODO + +- Add team-specific coverage thresholds. +- Add preferred xUnit patterns for L0 and L1 tests. diff --git a/.github/hooks/security-policy.json b/.github/hooks/security-policy.json new file mode 100644 index 0000000000..e5d95e036c --- /dev/null +++ b/.github/hooks/security-policy.json @@ -0,0 +1,12 @@ +{ + "version": 1, + "hooks": { + "preToolUse": [ + { + "type": "command", + "bash": "./scripts/security-check.sh", + "powershell": "pwsh -File scripts/security-check.ps1" + } + ] + } +} diff --git a/.github/instructions/ci-workflows.instructions.md b/.github/instructions/ci-workflows.instructions.md new file mode 100644 index 0000000000..687c1a2ca4 --- /dev/null +++ b/.github/instructions/ci-workflows.instructions.md @@ -0,0 +1,9 @@ +--- +applyTo: '.github/workflows/*.yml,.github/workflows/*.yaml' +--- +# GitHub Actions Workflow Conventions +**When to read:** Editing GitHub Actions workflow files. + +- Keep workflow changes minimal and job-scoped. +- Reuse existing actions and patterns already used in this repo before introducing new ones. +- Do not bypass required checks or loosen security settings in workflow YAML. diff --git a/.github/instructions/powershell-scripts.instructions.md b/.github/instructions/powershell-scripts.instructions.md new file mode 100644 index 0000000000..1f2257493f --- /dev/null +++ b/.github/instructions/powershell-scripts.instructions.md @@ -0,0 +1,9 @@ +--- +applyTo: '**/*.ps1' +--- +# PowerShell Script Conventions +**When to read:** Editing PowerShell scripts in any directory. + +- Use `$ErrorActionPreference = 'Stop'` for deterministic failure behavior. +- Prefer explicit parameters and clear failure messages over silent fallbacks. +- Avoid destructive operations unless explicitly requested by the task. diff --git a/.github/prompts/generate-tests.prompt.md b/.github/prompts/generate-tests.prompt.md new file mode 100644 index 0000000000..de2c094936 --- /dev/null +++ b/.github/prompts/generate-tests.prompt.md @@ -0,0 +1,12 @@ +--- +description: Generate tests for the current C# change. +--- + +# Generate Tests + +Create or update tests that validate the current code change. + +## TODO + +- Add the exact prompt steps for L0 vs L1 selection. +- Add naming and assertion conventions used in this repo. diff --git a/.github/prompts/security-review.prompt.md b/.github/prompts/security-review.prompt.md new file mode 100644 index 0000000000..e712205bc2 --- /dev/null +++ b/.github/prompts/security-review.prompt.md @@ -0,0 +1,12 @@ +--- +description: Review the current file for security and safety issues. +--- + +# Security Review + +Analyze the active file for security vulnerabilities and risky patterns. + +## TODO + +- Add the repo-specific security checklist. +- Add escalation guidance for high-severity findings. diff --git a/.github/skills/agent-dev-loop/SKILL.md b/.github/skills/agent-dev-loop/SKILL.md new file mode 100644 index 0000000000..dc604d6b62 --- /dev/null +++ b/.github/skills/agent-dev-loop/SKILL.md @@ -0,0 +1,33 @@ +--- +name: agent-dev-loop +description: 'Run the standard Azure Pipelines Agent development loop. Use when implementing code changes in src/, updating tests, and validating with dev scripts.' +--- + +# Agent Development Loop + +Standardize implementation flow with repo entrypoints. + +## When to Use + +- Any feature or fix in `src/`. +- Test updates in `src/Test/`. + +## Process + +### Step 1: Bootstrap environment + + +### Step 2: Build and test + + +### Step 3: Prepare PR-ready changes + + +## Constraints + +- Use `src/dev.*` scripts as source of truth. +- Avoid unrelated refactors. + +## Validation + +- `src\dev.cmd test` passes and changed behavior is covered. diff --git a/.github/skills/ci-failure-triage/SKILL.md b/.github/skills/ci-failure-triage/SKILL.md new file mode 100644 index 0000000000..b056c646c9 --- /dev/null +++ b/.github/skills/ci-failure-triage/SKILL.md @@ -0,0 +1,33 @@ +--- +name: ci-failure-triage +description: 'Triage Azure Pipelines and GitHub Actions failures. Use when build checks fail, tests regress, or pipeline jobs become unstable.' +--- + +# CI Failure Triage + +Identify failing job, map to owning area, and reproduce locally. + +## When to Use + +- Failing `.azure-pipelines/*.yml` or `.github/workflows/*`. +- Repeated flaky test or build failures. + +## Process + +### Step 1: Capture failing job context + + +### Step 2: Reproduce locally + + +### Step 3: Contain and fix + + +## Constraints + +- Do not bypass checks, signing, or security gates. +- Keep fixes minimal and traceable. + +## Validation + +- Re-run failing pipeline and the local verification command. diff --git a/.github/skills/test-tier-selection/SKILL.md b/.github/skills/test-tier-selection/SKILL.md new file mode 100644 index 0000000000..f1317da13a --- /dev/null +++ b/.github/skills/test-tier-selection/SKILL.md @@ -0,0 +1,33 @@ +--- +name: test-tier-selection +description: 'Select and run the right test tier (L0/L1/full). Use when deciding fast feedback vs integration confidence in src/Test.' +--- + +# Test Tier Selection + +Choose the smallest reliable test surface first, then expand. + +## When to Use + +- Unsure whether to run L0, L1, or full tests. +- Investigating test regressions. + +## Process + +### Step 1: Classify change impact + + +### Step 2: Pick minimum tier + + +### Step 3: Escalate if needed + + +## Constraints + +- Prefer deterministic tests. +- Do not reduce assertions to hide failures. + +## Validation + +- Selected tier passes and is justified in PR notes. diff --git a/.github/workflows/copilot-setup-steps.yml b/.github/workflows/copilot-setup-steps.yml new file mode 100644 index 0000000000..0161a652ef --- /dev/null +++ b/.github/workflows/copilot-setup-steps.yml @@ -0,0 +1,12 @@ +name: Copilot Setup Steps + +on: + workflow_dispatch: + +jobs: + copilot-setup: + runs-on: ubuntu-latest + steps: + - uses: actions/checkout@v4 + - name: Setup environment + run: ./scripts/setup diff --git a/.gitignore b/.gitignore index 7aa898e0bf..461aad84a5 100644 --- a/.gitignore +++ b/.gitignore @@ -26,3 +26,4 @@ src/Misc/dotnet-install.* #generated src/Microsoft.VisualStudio.Services.Agent/BuildConstants.cs +.github/.bootstrap-wizard-state.json diff --git a/AGENTS.md b/AGENTS.md new file mode 100644 index 0000000000..4c20091453 --- /dev/null +++ b/AGENTS.md @@ -0,0 +1,31 @@ +# AGENTS.md + +## Verification +- Run: `src\dev.cmd test` +- If it fails, fix the root cause and re-run. + +## Environment +- Use `src\dev.cmd` (Windows) and `src/dev.sh` (Linux/macOS) as canonical entrypoints. +- Use repo-managed .NET bootstrap via `src/dev.*` rather than ad-hoc local SDK assumptions. +- Use npm only for the two existing Node utility folders; do not introduce new JS package managers. + +## Guardrails +- Run `layout` before first build/test on a machine. +- Keep code changes in `src/` and tests in `src/Test/` unless requested otherwise. +- Avoid drive-by refactors; keep diffs task-scoped. +- Do not duplicate instructions across `AGENTS.md` and `.github/copilot-instructions.md`. + +## Constraints +- Keep diffs minimal and scoped to the request. +- Update/add tests for behavior changes. +- Do not modify CI, dependency versions, or security settings unless asked. +- Never print, log, or commit secrets. + +## Definition of Done +- Verification passes with `src\dev.cmd test`. +- No new lint/test warnings introduced. +- Changes are scoped to the request. + +## Where to find more +- Path-specific rules: `.github/instructions/` +- Multi-step workflows: `.github/skills/*/SKILL.md` diff --git a/scripts/security-check.ps1 b/scripts/security-check.ps1 new file mode 100644 index 0000000000..229d0f1bde --- /dev/null +++ b/scripts/security-check.ps1 @@ -0,0 +1,18 @@ +$ErrorActionPreference = 'Stop' + +# Block destructive commands. Extend this list as needed. +$blockedPatterns = @( + 'git reset --hard', + 'rm -rf /', + 'DROP DATABASE', + 'format C:', + 'mkfs' +) + +$inputCommand = $args -join ' ' +foreach ($pattern in $blockedPatterns) { + if ($inputCommand -match [regex]::Escape($pattern)) { + Write-Error "Blocked: destructive pattern detected: $pattern" + exit 1 + } +} diff --git a/scripts/security-check.sh b/scripts/security-check.sh new file mode 100644 index 0000000000..f2ba995cbd --- /dev/null +++ b/scripts/security-check.sh @@ -0,0 +1,19 @@ +#!/usr/bin/env bash +set -euo pipefail + +# Block destructive commands. Extend this list as needed. +BLOCKED_PATTERNS=( + "git reset --hard" + "rm -rf /" + "DROP DATABASE" + "format C:" + "mkfs" +) + +INPUT="$*" +for pattern in "${BLOCKED_PATTERNS[@]}"; do + if echo "$INPUT" | grep -qi "$pattern"; then + echo "Blocked: destructive pattern detected: $pattern" >&2 + exit 1 + fi +done diff --git a/scripts/setup b/scripts/setup new file mode 100644 index 0000000000..22574b2147 --- /dev/null +++ b/scripts/setup @@ -0,0 +1,5 @@ +#!/usr/bin/env bash +set -euo pipefail + +# Bootstrap dependencies and layout for agent builds/tests. +./src/dev.sh layout diff --git a/scripts/setup.ps1 b/scripts/setup.ps1 new file mode 100644 index 0000000000..71fa389f5c --- /dev/null +++ b/scripts/setup.ps1 @@ -0,0 +1,4 @@ +$ErrorActionPreference = 'Stop' + +# Bootstrap dependencies and layout for agent builds/tests. +& "$PSScriptRoot\..\src\dev.cmd" layout diff --git a/src/Test/AGENTS.md b/src/Test/AGENTS.md new file mode 100644 index 0000000000..e405f298fb --- /dev/null +++ b/src/Test/AGENTS.md @@ -0,0 +1,12 @@ +# Test Projects + +## Verification +- Run: `src\dev.cmd test` + +## Conventions +- Prefer extending existing test patterns in `src/Test/` over inventing new harnesses. +- Keep tests deterministic; avoid clock, network, or environment flakiness. + +## Constraints +- Never weaken assertions just to make tests pass. +- Never change production code for test-only requests unless explicitly asked.