apex

# APEX - Copilot Instructions

> VS Code Copilot-specific orchestration instructions.
> For general project conventions, build commands, and code style, see the root `AGENTS.md`.

## Azure Defaults (canonical)

This section is the canonical declaration of Azure infrastructure defaults.
Azure-producing skills, agents, and prompts use this section — never restate
the values inline. The IaC workflow, CAF naming guidance, AVM procedure,
and reference index live in
[`.github/skills/apex-azure-defaults/SKILL.md`](skills/apex-azure-defaults/SKILL.md).

### Default Regions

| Service             | Default Region       | Reason                         |
| ------------------- | -------------------- | ------------------------------ |
| **All resources**   | `swedencentral`      | EU GDPR-compliant              |
| **Static Web Apps** | `westeurope`         | Not available in swedencentral |
| **Failover**        | `germanywestcentral` | EU paired alternative          |

### Required Tags (Azure Policy Enforced)

Tag schema is **whatever live Azure Policy enforces** in the target
subscription. Governance Discovery (Step 3.5) discovers the real
contract via `discover.py` and writes it to
`04-governance-constraints.json` (`tag_contract.tags[]`,
`tag_contract.source: "policy"`); that always wins.

**Greenfield fallback** (no tag policy found at any inherited scope):
the APEX-standard 9-tag set — `environment`, `owner`, `costcenter`,
`application`, `workload`, `sla`, `backup-policy`, `maint-window`,
`technical-contact` — all lowercase. This mirrors the org-wide
resource-group tag-deny policy (every key must exist on the RG or the
deployment is denied). Citation + greenfield decision checklist:
[`apex-azure-defaults/references/tag-strategy.md`](skills/apex-azure-defaults/references/tag-strategy.md).

> The PascalCase set (`Environment`, `ManagedBy`, `Project`, `Owner`)
> is a **deprecated convention** retained only for backward
> compatibility on existing projects whose deployed resources already
> carry that casing. Do not propagate it to new projects. `ManagedBy`
> and `Project` are not part of the required contract — `ManagedBy` may
> still be emitted as an optional deploy-provenance marker.

### Security baseline + AVM mandate

Non-negotiable: HTTPS-only, TLS 1.2 minimum, no public blob, Managed Identity
over keys, AVM-first. PaaS data services use private endpoints and disabled
public access in every environment, except Log Analytics and workspace-based Application Insights:
authenticated public query/ingestion is permitted when policy and approved requirements allow it;
AMPLS is required for mandated private monitoring, not by default. App Service APIs are private; public-facing
web applications may use public HTTPS ingress. Private DNS resolution is required;
verified DINE ownership avoids duplicate DNS deployment, not DNS itself.
Full rules:
[`iac-policy-compliance.md`](instructions/references/iac-policy-compliance.md)
and
[`iac-security-baseline.md`](instructions/references/iac-security-baseline.md).

### SKU source of truth

Creative SKU decisions (App Service, VM, SQL, Cosmos, AKS pools, Redis,
APIM, App Gateway, Storage replication) flow through
`agent-output/{project}/sku-manifest.{json,md}` — never re-derive SKUs
from artifact prose. Authoring rules:
[`sku-manifest.instructions.md`](instructions/sku-manifest.instructions.md).

## Session State — apex-recall

All session state flows through `apex-recall`. Do not read or write
`00-session-state.json` directly.

```bash
# Lifecycle
apex-recall init <project> --json                                    # new project
apex-recall show <project> --json                                    # context: step, decisions, findings, artifacts
apex-recall checkpoint <project> <step> <phase> --json               # after each phase
apex-recall complete-step <project> <step> --json                    # on step completion
apex-recall review-audit <project> <step> ... --json                 # after challenger reviews

# Atomic step transition — PREFERRED for moving between steps. Bundles
# complete-step (with challenger gate) + decide + start-step into one
# 00-session-state.json write, avoiding partial-update drift.
apex-recall transition <project> --from-step <s> --to-step <t> \
    --complete --decision key=value --json

# Decisions + findings
apex-recall decide <project> --key <k> --value <v> --json
apex-recall decide <project> --decision "<text>" --rationale "<why>" --json
apex-recall finding <project> --add "<text>" --json

# Read-only orientation: sessions | files | search '<term>' | decisions (all accept --json)
```

If recall returns sufficient, current context, skip redundant file reads.
A file inventory is not its content. Read missing required sections directly;
after edits, compaction, or a new chat, refresh what is no longer current or available.
Empty/failed recall does not waive required inputs or approvals: recover existing
project state before advancing, and never infer completion from artifact numbering.

Canonical `show --json` schema (including the `session.steps` shape and
jq query templates) lives at
[`tools/apex-recall/docs/show-schema.md`](../tools/apex-recall/docs/show-schema.md).
The valid decision-keys registry lives at
[`tools/apex-recall/docs/decision-keys.md`](../tools/apex-recall/docs/decision-keys.md).

## Multi-Step Workflow

The Steps 1–7 + Post-Lessons table is in [AGENTS.md](../AGENTS.md#agent-workflow);
the machine-readable source is
[`.github/skills/apex-workflow-engine/templates/workflow-graph.json`](skills/apex-workflow-engine/templates/workflow-graph.json).
Each step's outputs land in `agent-output/{project}/`; context flows via artifacts
and handoffs. Follow the graph's review contract and [workflow table](../AGENTS.md#agent-workflow),
including the independent Step 2 cost-feasibility review. Reuse valid completed reviews;
missing/stale evidence or blocking findings must be resolved before approval.
Deep review requires `decisions.review_depth = "deep"` or an explicit user request,
never complexity alone. Production handoffs and approval gates remain human-controlled.

## Skills

Skills auto-discover via the `description` field in `.github/skills/{name}/SKILL.md`.
Agents read `SKILL.md` files on demand and load `references/*.md` only when the
body explicitly points to one. There is one tier — no digest, no minimal.

## Harness And Runtime Boundaries

- Local prompt files are adapters, not Agent Host entry points. On Agent Host,
  use the shared skill and explicitly select its owning main agent before consequential work.
  Skills inherit the caller's model/tools; they do not switch agents or confer permissions.
- Main agents, including `10-Challenger`, use `disable-model-invocation: true`.
  The Orchestrator routes through human handoffs only. Explicit caller allowlists
  must not override that boundary; legacy discovery settings are not a security boundary.
- If a required reviewer is unavailable, STOP and request a human handoff to `10-Challenger`;
  never invoke a nested wrapper or fabricate an inline review. Missing/empty reviewer output
  permits exactly one identical-input retry, then a human handoff under the
  [review protocol](skills/apex-azure-defaults/references/adversarial-review-protocol.md#subagent-discovery-fallback-default--deep).
- Keep essential role, approval, security, output, and stop rules in main agent bodies.
  Authoring `applyTo` matches do not prove runtime attachment. Load required guidance
  when missing; do not automatically load vendor-authoring guidance during production work.
- Agent frontmatter owns model assignments. Sol, Terra, and Luna labels do not prove
  runtime cost-tier eligibility, availability, or API support. Stop on unsupported routing;
  do not substitute models automatically. Local and Agent Host behavior needs separate verification.
- Use available editing tools for existing files, preserve user work, and validate before
  dependent follow-up edits. No shared procedure requires a particular bulk-edit tool.

## Chat Triggers

- Messages starting with `gh` are GitHub operations (e.g., `gh pr create`,
  `gh workflow run`, `gh api`). Follow `.github/skills/apex-github-operations/SKILL.md`
  (`gh` CLI-first, MCP fallback).

### GitHub Tool Priority (Mandatory)

For issues and pull requests, prefer the `gh` CLI over GitHub MCP tools — the
CLI is always available in this dev container and is the more stable primitive.
Fall back to MCP only when an operation has no `gh` CLI equivalent (e.g., rich
PR review thread management or bulk GraphQL queries). In devcontainers,
do not run `gh auth` commands unless the user explicitly asks for CLI auth
troubleshooting. Git normally uses VS Code-forwarded host credentials;
`gh` uses its explicitly authenticated config volume or optional `GH_TOKEN`
inherited by the host VS Code process at launch (`${localEnv:GH_TOKEN}`).
`terminal.integrated.env.*` affects terminals only, not that substitution
or all hooks, MCP processes, and the extension host. Never request tokens
through chat, expose them to the model, or store secrets in repository files.
For an identity mismatch, compare `gh api user --jq .login` with the account
named in Git's denial. Only with explicit user authorization, use
`git -c credential.helper= -c credential.helper='!gh auth git-credential' push origin <approved-feature-branch>`.
Keep the helper single-quoted. Never switch credentials automatically, change
persistent Git configuration, force-push, or infer approval to push to `main`.

### Explore Subagent Thoroughness

Specify thoroughness explicitly when invoking Explore:

| Lookup Type                           | Thoroughness | Examples                                                  |
| ------------------------------------- | ------------ | --------------------------------------------------------- |
| Single file read, config check        | `quick`      | "What's in azure.yaml?", "Find the main.bicep path"       |
| Multi-file comparison, pattern search | `medium`     | "How do agents reference skills?", "What modules exist?"  |
| Deep codebase research                | `thorough`   | "Audit all security patterns", "Full dependency analysis" |

Check whether the needed information is already in context from earlier
file reads before calling Explore.

## Conventions, Key Files & Validation

See `AGENTS.md` for all conventions, project structure, key file paths,
and build/validation commands.

**Terminal hygiene**: Never use `mv -i`, `rm -i`, `cp -i`, `read -p`, or any
prompt-driven shell builtin (incl. inside `bash -c '...'`). Pipe >50-line
output to a file. See `.github/instructions/no-interactive-shell.instructions.md`
for the full ruleset; `npm run lint:safe-shell` enforces it on committed
agent/skill/instruction snippets.

**Artifact lint delegation**: Agents do not call `npm run lint:artifact-templates`
or `markdownlint-cli2` directly against `agent-output/**`. The lefthook
`artifact-validation` pre-commit hook and the `10-Challenger` review own the
contract. Validator-tracked anti-pattern — see
[`agent-authoring.instructions.md`](instructions/agent-authoring.instructions.md#no-direct-markdownlint-on-agent-output-rule).