Add .github/copilot-instructions.md for coding agent onboarding

[Copilot]

Adds a copilot-instructions.md to give a coding agent (or new contributor) enough context to work efficiently on this repo without manual exploration.

What's documented

• Repo layout – annotated directory tree covering src/aspire, tests, examples, and docs
• Design decisions – Array-API-agnostic architecture (xp pattern via array-api-compat), available array backends (numpy/JAX/torch), flow backends (zuko/flowjax), and the central Samples dataclass contract
• Dev setup – exact install command including the CPU-only PyTorch index used in CI
• Linting & testing – ruff commands, pytest invocation patterns, and what the xp/dtype conftest fixtures parametrise
• CI overview – concise table of all four workflows and their triggers
• Extension patterns – how to add a new sampler or register a custom flow backend via entry points
• Known gotchas – JAX float64 opt-in, SCIPY_ARRAY_API env var requirement, and PyTorch default-dtype behavior

---

✨ Let Copilot coding agent set things up for you — coding agent works faster and does higher quality work when set up for your repo.

[mj-will]

@copilot how should this file be maintained updated as the code changes?

[Copilot]

@copilot how should this file be maintained updated as the code changes?

The file should be treated as living documentation and updated in the same PR as any change that affects the information it covers. Specifically:

• Structural changes (new top-level module, renamed directory, new sampler/flow) → update the repo layout and the relevant "common patterns" section.
• Tooling changes (new linter, different test runner, CI matrix update) → update the linting/testing/CI sections.
• New known issues or workarounds discovered during development → add them to the "Known Issues" section as part of the PR that hits the issue.
• Dependency or setup changes (e.g., different install command, new optional extra) → update the dev-setup section.

The key discipline is: don't merge a PR that makes the instructions stale. Adding a bullet to the PR checklist (e.g. in a CONTRIBUTING.md or a pull-request template) reminding authors to update copilot-instructions.md when relevant is the lightest-weight way to enforce this. Alternatively, a CI lint step that checks for a touched copilot-instructions.md on PRs that touch src/ or pyproject.toml could automate the reminder, but that's optional overhead for a small project.

[mj-will]

@copilot Could one used a weekly CI job to trigger you to check if the file needs updating?

[mj-will]

@copilot Could one used a weekly CI job to trigger you to check if the file needs updating?

[Copilot]

@copilot Could one used a weekly CI job to trigger you to check if the file needs updating?

Yes. GitHub Actions supports schedule (cron) triggers, so a weekly workflow is straightforward. The typical pattern would be:

1. Add a workflow with on: schedule: - cron: '0 9 * * 1' (every Monday at 09:00 UTC).
2. The workflow step creates a GitHub Issue (via gh issue create) with a label that triggers the Copilot coding agent (e.g. copilot), and a body like: "Review .github/copilot-instructions.md against the current state of src/aspire/, pyproject.toml, and .github/workflows/. If anything is stale or missing, open a PR with the necessary updates."
3. The coding agent picks up the issue, checks the file, and opens a PR if needed — or closes the issue with a comment saying everything is up to date.

The only prerequisite is that your repository has the Copilot coding-agent feature enabled and the target label configured to auto-assign issues to the agent.

@copilot Could one used a weekly CI job to trigger you to check if the file needs updating?

Yes — a scheduled workflow is a clean way to do this. Concretely:

# .github/workflows/refresh-copilot-instructions.yml
on:
  schedule:
    - cron: '0 9 * * 1'   # Every Monday 09:00 UTC
  workflow_dispatch:        # Allow manual runs too

jobs:
  create-review-issue:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - name: Open Copilot review issue
        env:
          GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
        run: |
          gh issue create \
            --title "Weekly: review .github/copilot-instructions.md" \
            --label "copilot" \
            --body "Review \`.github/copilot-instructions.md\` against the current state of \`src/aspire/\`, \`pyproject.toml\`, and \`.github/workflows/\`. If anything is stale or missing, open a PR with the necessary updates. If everything is up to date, close this issue with a comment."

The copilot label triggers the coding agent, which then inspects the codebase, patches the file if needed, and opens a PR — or self-closes the issue if nothing has changed. The only prerequisite is that the Copilot coding-agent feature is enabled for the repository and the label is configured to auto-assign to the agent.