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

[Copilot]

Onboard the repository to Copilot coding agent by adding structured instructions that capture project conventions, build/lint/test commands, and known pitfalls.

What's in the file

• Project overview — pipeline description, entry-point commands, repository layout
• Setup — uv sync and pip install -e ".[dev]" paths
• Lint/format/test commands — ruff check, ruff format, pytest invocations
• Coding conventions — from __future__ import annotations everywhere, str | None style, @dataclass models, Google-style docstrings, Conventional Commits
• Security rules — no shell=True, SAFE_ENV duplication across executor.py and subprocess_utils.py, PowerShell single-quote injection prevention
• Known CI bug — tests/ is gitignored but CI runs ruff check src/ tests/, causing E902 No such file or directory; workaround documented
• What not to touch — plugins/ (generated), output/ (gitignored)

---

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

[github-actions]

🔍 AI Code Review

🔵 Info

• Workflow adds manual trigger (workflow_dispatch) with PR number input, increasing flexibility.
• Permissions scoped to contents: read and pull-requests: write, which is good practice.
• Consolidates two previous jobs into one unified ai-review job, simplifying maintenance.

🟡 Warning

• Diff extraction logic:

  • Uses git diff ${{ github.event.pull_request.base.sha || github.sha }}~1...${{ github.sha }} which may fail or produce unexpected diffs if base.sha is missing or incorrect.
  • Fallback to git diff HEAD~1 may not correspond to the PR changes, possibly reviewing unrelated commits.
  • Consider explicitly fetching PR refs and using git fetch origin pull/${PR_NUM}/head to ensure accurate diffs.

• Diff truncation to 6000 bytes (head -c 6000) may cut off important context, potentially reducing review quality.

• The diff filters only *.js, *.ts, *.py, *.yml files; if other file types are relevant, they will be ignored.

🔴 Critical

• The PR number extraction in the script:

  if [ "${{ github.event_name }}" = "workflow_dispatch" ]; then
    PR_NUM=${{ inputs.pr_number }}
  else
    PR_NUM=${{ github.event.pull_request.number }}
  fi

  • inputs.pr_number is a number input, but used directly in shell without validation or sanitization.
  • Potential injection risk if the input is manipulated (unlikely but possible).
  • Recommend validating PR_NUM is a positive integer before use.

• The curl command sends the diff content directly in JSON without escaping special characters beyond what jq does:

  • This is mostly safe due to jq -n --arg diff "$DIFF", but very large diffs or unexpected characters could cause malformed JSON or API errors.
  • Consider adding error handling for JSON encoding failures or API response parsing.

• Posting the review comment:

  • No deduplication or update logic for existing comments.
  • This can cause comment spam on repeated runs or multiple pushes.
  • Recommend checking for existing bot comments and updating instead of always creating new comments.

---

Summary:

• Improve PR diff fetching for accuracy.
• Validate and sanitize inputs.
• Handle large diffs more gracefully.
• Add logic to update existing review comments to avoid spam.
• Otherwise, well-structured and clear workflow leveraging GitHub Models API securely with token from secrets.

---

🤖 gpt-4.1-mini · 1719 tokens · GitHub Models free tier · 0 premium requests