feat(copilot): add repo-level Copilot instruction files

.github/copilot-instructions.md

@@ -0,0 +1,76 @@
+# Copilot Instructions — .github-private
+
+> **Note:** This file applies to the `petry-projects/.github-private` repository only. Org-wide rules are in [`petry-projects/.github/copilot-instructions.md`](https://github.com/petry-projects/.github/blob/main/.github/copilot-instructions.md). This file covers only what is specific to .github-private.
+
+## About
+
+.github-private is the org's private CI infrastructure repository — it hosts Copilot custom agent profiles (org-wide), sophisticated agentic GitHub Actions workflows (PR review, content-twin audit, standards-sync, CI failure analysis, stale management, etc.), and agentic framework subtrees (bmad-method, spec-kit, gsd).
+
+## Tech Stack
+
+- **Runtime:** Bash (scripts) · GitHub-hosted runners (Actions)
+- **Framework:** GitHub Actions (YAML) · BMad Method (via `frameworks/` git subtrees)
+- **Testing:** ShellCheck (scripts) · `gh-aw compile` (agentic workflow YAML linting — CI-gated in `lint.yml`)
+- **Linting:** ShellCheck (zero warnings) · markdownlint (agent profiles + docs) · `gh-aw compile` (`.github/aw/` workflows)
+- **Key tools:** `gh` CLI · `gh-aw` (agentic workflow compiler)
+
+## Project Structure
+
+```text
+agents/                 # Copilot custom agent profiles (org-wide effect)
+  agentic-workflows.md
+  compliance-auditor.md
+  feature-ideator.md
+  pr-reviewer.md
+.github/
+  workflows/
+    dev-lead.yml            # Primary AI automation for this repo (inline steps)
+    dev-lead-reusable.yml   # Cross-org reusable workflow (edit to affect all repos)
+    pr-review.yml           # Automated PR review
+    lint.yml                # ShellCheck + markdownlint + gh-aw-compile (repo-specific gate)
+    content-twin-audit.yml  # Scheduled content-twin compliance check
+    standards-sync.yml      # Standards propagation across org repos
+    ci-failure-analyst.*    # CI failure triage automation
+    stale-manager.*         # Stale PR/issue management
+    ...
+  aw/                   # Agentic workflow definitions (compiled by gh-aw)
+  rulesets/             # Branch protection ruleset JSON
+frameworks/             # git subtree managed — do not edit directly
+scripts/                # Shell orchestration for GitHub Actions
+docs/                   # Workflow documentation
+prompts/                # Agent prompt library
+```
+
+## Local Dev Commands
+
+- Lint scripts:         `shellcheck scripts/*.sh`
+- Lint agentic flows:   `gh-aw compile .github/aw/`
+- No install or test commands (infrastructure-only)
+
+## Required Environment Variables
+
+- `GITHUB_TOKEN`: Auto-provided by Actions; PAT with org scopes for manual runs
+- `ANTHROPIC_API_KEY`: Used by dev-lead and pr-review workflows (stored as Actions secret)
+
+## Testing Framework
+
+- Runner: `gh-aw compile` (agentic workflow YAML compilation — required CI gate in `lint.yml`)
+- Shell: ShellCheck (required CI gate)
+- Coverage: N/A
+- Mutation testing: N/A
+
+## Repo-Specific Overrides
+
+**Never modify `agent-shield.yml`** — exempted from agent modification per org agent-standards.md.
+
+**`dev-lead.yml` vs `dev-lead-reusable.yml`:** To change AI automation behavior for this repo only, edit `dev-lead.yml`. To change behavior across all org repos, edit `dev-lead-reusable.yml` (the cross-org reusable).
+
+**`lint.yml` `gh-aw-compile` job** is a documented repo-specific addition — do not remove it when syncing org CI templates; if the org template gains an equivalent, remove this note and defer to the template.
+
+**`frameworks/` directories** are managed via `git subtree` — do not edit them directly. Use `git subtree pull` against the upstream remote to update.
+
+**Agent profiles** in `agents/*.md` must have YAML frontmatter with `name`, `description`, and `tools`. Agent names must be kebab-case matching the filename. Changes are org-wide.
+
+## Org Standards
+
+See [petry-projects/.github — AGENTS.md](https://github.com/petry-projects/.github/blob/main/AGENTS.md).

.github/instructions/shell.instructions.md

@@ -0,0 +1,139 @@
+---
+description: Shell script development standards for the Petry Projects organization
+applyTo: "**/*.sh,**/*.bash"
+---
+
+# Shell Script Development Standards
+
+These rules extend the org-level `copilot-instructions.md`. Shell scripts are used for CI
+helper utilities, compliance automation, and infrastructure orchestration.
+
+## Safety Flags
+
+Every shell script MUST begin with:
+
+```bash
+#!/usr/bin/env bash
+set -euo pipefail
+```
+
+- `set -e` — exit immediately on any command failure
+- `set -u` — treat unset variables as errors
+- `set -o pipefail` — propagate failures through pipelines (not just the last command)
+
+For scripts that intentionally handle errors inline (e.g., checking return codes manually),
+disable `set -e` locally within a subshell or use `|| true` with a comment explaining why.
+
+## ShellCheck Compliance
+
+All scripts MUST pass `shellcheck` with zero warnings:
+
+```bash
+shellcheck --shell=bash <script>.sh
+```
+
+Run ShellCheck before committing. Common issues to fix proactively:
+
+- Unquoted variables — always quote: `"$variable"`, `"${array[@]}"`
+- Unsafe `$()` with user-controlled input — validate input first
+- Deprecated constructs — use `[[ ... ]]` over `[ ... ]` for bash conditionals
+
+## Quoting and Variable Expansion
+
+- **Always quote variable expansions:** `"$var"`, `"${var}"`, `"${array[@]}"`.
+- Use `${var:-default}` for safe defaults. Use `${var:?error message}` to fail fast on required
+  variables.
+- Use `$( )` for command substitution, not backticks.
+- Use `[[ ... ]]` for conditionals (bash built-in, safer than `[ ]`).
+- Use `(( ... ))` for arithmetic expressions.
+
+## Function Organization
+
+- Extract reusable logic into functions. Name functions with `snake_case`.
+- Declare local variables with `local` inside functions to avoid polluting global scope.
+- Functions that produce output should write to stdout. Functions that report errors should write
+  to stderr: `echo "Error: message" >&2`.
+
+  ```bash
+  log_info()  { echo "[INFO]  $*"; }
+  log_error() { echo "[ERROR] $*" >&2; }
+
+  process_item() {
+    local item="$1"
+    local output_dir="$2"
+    # ...
+  }
+  ```
+
+## Error Handling
+
+- Check return codes for commands that can fail silently (e.g., `curl`, `jq`, `aws`).
+- Use `|| { log_error "..."; exit 1; }` patterns to provide descriptive failure messages.
+- Use `trap 'cleanup' EXIT` to ensure cleanup runs even on error:
+
+  ```bash
+  cleanup() {
+    rm -f "$tmp_file"
+  }
+  trap 'cleanup' EXIT
+  ```
+
+## Command Injection Prevention
+
+- Never pass user-controlled input directly to shell commands without validation.
+- Use arrays to pass arguments to commands (avoids word-splitting and globbing):
+
+  ```bash
+  # Wrong — subject to word splitting:
+  run_command "$user_args"
+
+  # Right — use an array:
+  args=("--flag" "$user_value")
+  run_command "${args[@]}"
+  ```
+
+- Avoid `eval` with untrusted input.
+
+## Style and Readability
+
+- Use heredocs for multi-line strings instead of multiple `echo` statements:
+
+  ```bash
+  cat <<'EOF'
+  Usage: script.sh [options]
+    -h, --help    Show this help message
+  EOF
+  ```
+
+- Keep lines under 100 characters where practical. Use `\` to break long commands.
+- Add a one-line comment before each function and non-obvious command explaining *why*, not
+  *what*.
+- Use `readonly` for constants at the top of the script:
+
+  ```bash
+  readonly SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+  readonly MAX_RETRIES=3
+  ```
+
+## Makefile Standards
+
+- Use `.PHONY` for all non-file targets to prevent conflicts with files of the same name.
+- Use `$(MAKE)` recursively, not bare `make`.
+- Document each target with a `##` comment on the same line (enables `make help` patterns):
+
+  ```makefile
+  .PHONY: test lint
+
+  test: ## Run the full test suite with coverage
+  	go test ./... -coverprofile=coverage.out
+
+  lint: ## Run golangci-lint
+  	golangci-lint run
+  ```
+
+## Testing Shell Scripts
+
+- Test scripts with `bats` (Bash Automated Testing System) where feasible.
+- At minimum, test the happy path and common error paths.
+- Use `shellcheck` in CI as a required status check for repositories with significant shell
+  script surface area.