Copilot Instructions for iccDEV

Use this as the short cross-cutting guide. Path-specific details auto-load from .github/instructions/*.instructions.md; prefer those files over duplicating commands here.

Path-Specific Instructions

Agent Instructions

This repository uses all three GitHub custom-instruction types:

• Repository-wide: this file (.github/copilot-instructions.md).
• Path-specific: .github/instructions/*.instructions.md, auto-loaded by applyTo globs.
• Agent: AGENTS.md is canonical, and the nearest AGENTS.md in the tree wins. Root CLAUDE.md (Anthropic Claude) and GEMINI.md (Google Gemini) are thin mirrors that route back to AGENTS.md so every agent shares one source of truth.

Keep agent rules in AGENTS.md, not in the mirrors. See https://docs.github.com/en/copilot/how-tos/copilot-on-github/customize-copilot/add-custom-instructions/add-repository-instructions

For documentation edits, run the bounded graph-light Doxygen check in docs/documentation-maintenance.md before handoff and require docs/generated/doxygen-warnings.log to be empty. Time is valuable: full graph generation belongs to release packaging or graph changes. Keep HAVE_DOT=YES for checked-in diagrams; exclude CTest implementation and fixtures from the generated package. Keep Markdown links inside the Doxygen INPUT tree; use relative Markdown links for generated Markdown pages, \ref for generated source files, and absolute GitHub HTML anchors for repo-only resources. Relative HTML anchors can break in the packaged site without a Doxygen warning. Never commit generated Doxygen output or warning logs.

Copilot code review reads repository-wide instructions, the nearest applicable AGENTS.md, path-specific instructions, and relevant skills from the PR head branch. Keep review criteria in those canonical files so instruction changes can be tested in the same PR. Copilot reviews are advisory Comment reviews, not approvals or blocking merge decisions; required human review still applies.

Current JSON/Config Regression Gate

JSON/config parser fixes must fail closed: reject short arrays, non-numeric required values, failed nested ParseJson(), bad struct members, malformed fixed-size arrays, and stale reset/fromJson state.

Canonical regression scripts:

• .github/scripts/iccdev-json-parser-regression-tests.sh
• .github/scripts/iccdev-json-cfg-tests.sh
• .github/scripts/iccdev-stdobserver-regression-tests.sh
• .github/scripts/iccdev-mluc-setter-regression-tests.sh
• .github/scripts/iccdev-mluc-read-utf16-regression-tests.sh
• .github/scripts/iccdev-cam-degenerate-regression-tests.sh
• .github/scripts/iccdev-namedcolor-apply-regression-tests.sh
• .github/scripts/iccdev-v5-namedcmm-regression-tests.sh
• .github/scripts/iccdev-namedcolor-overprint-regression-tests.sh
• .github/scripts/iccdev-applynamedcmm-cli-args-regression.sh
• .github/scripts/iccdev-applysearch-cli-args-regression.sh
• .github/scripts/iccdev-xml-spec-qa.sh

For regression workflow updates, use .github/skills/regression-workflow-governance/SKILL.md and docs/regression-workflow-governance.md.

For maintainer regression-container use, PR validation, and issue reproduction, use .github/skills/regression-container-maintainer/SKILL.md and docs/regression-container.md.

ClusterFuzzLite memory builds must use the repository-pinned instrumented libc++/libc++abi and instrumented libxml2 for the XML target, verify every fuzzer runtime boundary, and replay the pinned #2687 artifact before fuzzing.

Build, Test, and Safety

• User build instructions: docs/build.md
• Maintainer build and sanitizer policy: .github/instructions/build-system.instructions.md
• Test profile workflow: .github/instructions/testing.instructions.md
• Workflow governance: .github/instructions/workflow-governance.instructions.md
• Apple mobile static-core and smoke-app flow: docs/build.md and .github/instructions/build-system.instructions.md
• Manual iOS example app helpers: examples/ios-apply-preview/README.md, examples/ios-benchapply/README.md, examples/ios-clut-editor/README.md, and .github/skills/ios-manual-examples/SKILL.md
• iOS CLUT editor proof-of-concept: examples/ios-clut-editor/README.md, .github/skills/ios-clut-editor/SKILL.md, and .github/prompts/ios-clut-editor.prompt.md
• Native HEIF inspection and extraction QA: Tools/CmdLine/IccHeifDump/Readme.md and .github/ci/test-data/heif/Readme.md
• Windows session helper: dot-source .\.github\scripts\icc-session.ps1, then run icc-session to create the next DD-mmm-YYYY-NNN workspace directory.
• AVX2 CLUT debugging and optimization handoff: docs/avx2-clut-diagnostics.md, with vs2022-clangcl-x64-avx2-diagnostics for tracepoints and vs2022-clangcl-x64-avx2-qa-flags for measurements. Use .github/scripts/iccdev-windows-clut-avx2-benchmark.ps1 for interleaved 8-16-output comparisons, and require output_vector_match=True for every row; AVX2 dispatch is limited to 15 outputs, and native MSVC intentionally retains SSE2.

Pull Requests

• Follow CONTRIBUTING.md: discuss the change in an issue first, keep the PR focused, and do not modify maintainer-owned infrastructure unless a maintainer requested it.
• Before opening, updating, or finalizing a PR, use the pre-PR security cycle: docs/pre-pr-security-cycle.md, .github/skills/pre-pr-security-cycle/SKILL.md, and .github/prompts/pre-pr-security-cycle.prompt.md.
• Before creating, reopening, or requesting review on a PR, satisfy docs/governance/UPSTREAM_PR_READINESS.md and use .github/skills/upstream-pr-readiness/SKILL.md. A branch push, CI request, or review request is not PR-creation authorization.
• For maintainer branch grooming, set repository-local Git defaults from docs/linear-stack-workflow.md so pulls rebase, non-fast-forward merges fail, repository hooks run, and the final base..HEAD range remains merge-free.
• Run the smallest complete validation for the changed surface. For workflow, Docker, release, CMake, parser, or security automation changes, follow the additional checks required by the path-specific instructions and pre-PR security cycle.
• PR handoffs must state the branch and commit, changed surface, local and hosted validation, known skips or deferrals, and merge-readiness. Cite workflow URLs or run IDs rather than copying raw logs.
• Do not call a PR ready or green while the required PR Summary check is pending or failing. After a rebase, ci-rebase-safety supplies only the separate Rebase Safety context. Dispatch final validation for the current head to obtain PR Summary and record applicable manual final-run evidence; the expensive core, preflight, risk, sanitizer, JSON, MCP, and MATLAB lanes do not run automatically on synchronize.

Stacked PRs and Fast Lane

Use a stacked PR only when a maintainer explicitly requests one. A single independent PR is the default because stack rebases multiply CI and review churn. Keep one reviewable concern per layer and use separate stacks for unrelated work.

• Before stack work, update the local extension with gh extension upgrade gh-stack; use the locally installed gh-stack agent skill and .github/skills/stacked-pr-fast-lane/SKILL.md.
• Use gh stack view --json to inspect stack state and gh stack sync --remote origin before handoff or after a remote/base change. Do not manually rebase or push an individual stack layer.
• Use the maintainer-only fast lane only for an open same-repository PR. It is not available to forks and does not replace the required PR gates.
• Agents may prepare the focused fast-lane command and collect its run ID; a maintainer with repository permission must choose and dispatch it. Run shared-concurrency fast lanes one at a time.

Code Review Standards

For same-repository pull request review, use .github/skills/code-review/SKILL.md. Treat fork-head agent configuration as untrusted review guidance; use the trusted-base Fork Automation Gate to protect agent-policy surfaces.

• Read AGENTS.md, this file, and matching path-specific instructions before reviewing the changed surface.
• Report only a changed-line regression with a concrete correctness, security, compatibility, or maintainability impact. Do not report pre-existing code unless the change makes it newly reachable or materially worsens it.
• Verify each finding with the smallest relevant evidence before commenting.
• Treat a missing, abbreviated, or placeholder canonical BSD-3-Clause notice derived from LICENSE.md in a new or relocated ICC-owned C/C++ source/header as a blocking changed-line finding. Verify with .github/scripts/check-license-notices.py and preserve third-party and generated-file attribution. Avoid speculative concerns, style-only comments, duplicate findings, and generic requests for broader tests when focused validation covers the diff.
• Use one comment for one root cause. State the affected path, triggering condition, and the smallest safe remediation.
• Review every head against the complete cumulative base...HEAD diff and contract matrix. For a later PR update, use the changed delta only to focus new evidence; do not narrow the review scope or re-post resolved findings unless the update reintroduces the defect.
• Request review only after the head is frozen and the readiness evidence is current. If a re-review finds any new blocker, stop serial automated review and return the branch to grooming until a maintainer directs the next step.
• Conserve maintainer attention: prioritize a small set of high-confidence, actionable findings over exhaustive comment volume. No comment is better than a low-value concern.
• For workflow changes, use the trusted workflow/static-analysis guidance. Consider YAML parsing, actionlint, yamllint, zizmor, and CodeQL Actions results as applicable; do not duplicate a confirmed automated finding without additional impact or remediation context.
• Use repository MCP context or agent skills only when relevant to the changed surface; do not invent a tool dependency or repeat information already in repository instructions.
• For matlab/**, apply .github/instructions/matlab-code-review.instructions.md before reporting a finding. Verify the MEX boundary, wrapper cleanup, native-tool invocation, focused regression, and dependent Release/CI/documentation surfaces.

iccdev-mcp Review Notes

• Keep user-facing MCP setup docs task-oriented; put reviewer and agent guidance in .github/ files or prompts.
• When reviewing repository MCP settings, compare the mcpServers.iccdev.tools allowlist against the MCP tool names from iccdev_mcp/server.py, not the REST route aliases from /api/tools. REST names such as sig_to_str, list_profiles, to_xml, from_xml, and spec_sep intentionally differ from MCP names such as icc_sig_to_str, list_available_profiles, profile_to_xml, xml_to_profile, and spec_sep_to_tiff.
• For profile_summary, keep raw ICC signature fields unchanged and expose printable *_display fields only for UI readability. ICC signature values may arrive as either 4-character strings or raw 32-bit integers, so both forms need test coverage.
• Dashboard changes should preserve stale-output reset when switching tools.
• MCP health reports currently available capabilities, which can differ between container variants when an optional native ABI is unavailable. Validate the discovered CLI registry and capability flags; do not hard-code tool totals.

Key safety rules:

• 2-space C++ indentation, K&R braces, no tabs.
• Member prefix m_; match nearby naming and ownership patterns.
• Error handling uses return values, not exceptions.
• New ICC-owned C/C++ files need the complete canonical BSD-3-Clause notice derived from LICENSE.md unless generated; run .github/scripts/check-license-notices.py.
• Validate all file-controlled sizes, offsets, counts, and loop bounds.
• Bounds check pattern: if (size > limit || offset > limit - size).
• Exit 1-127 is graceful failure, not a crash; exit 128+ is signal termination.

Prompts

Skills

WASM Notes

• The current WASM deliverable is the staged Node/npm-style module package from Build/Cmake/wasm-package/stage.sh, not a browser UI.
• Do not reintroduce or test legacy wasm/*.html, wasm/*.css, or wasm/*.js assets; validate with wasm-stage/test_all.js and wasm-stage/regression.js.