Implement working uv/pytest environment in copilot-setup-steps workflow and add documentation

[Copilot]

Plan: Update copilot-setup-steps.yml to have working setup environment

• Analyze the current copilot-setup-steps.yml workflow structure
• Review working patterns from other workflows (release.yml, claude-code-test.yml, validate.yml)
• Update copilot-setup-steps.yml to use uv/Python setup instead of Nix
• Add proper setup steps for Python 3.11 environment
• Add uv installation and dependency sync
• Add verification step to confirm pytest and tools are available
• Address code review feedback for better consistency
• Add ruff verification to confirm dev tools are available
• Validate YAML syntax
• Pass code review with no issues
• Pass CodeQL security scan with no vulnerabilities
• Fix CI failure - use uv run instead of python -m for tool verification
• Add commented Nix setup as documentation explaining the workaround
• Create .github/copilot-instructions.md documenting development setup
• Make copilot-instructions.md terse and focused
• Complete implementation

Summary of Changes:

The .github/workflows/copilot-setup-steps.yml workflow has been successfully updated from a non-functional skeleton (with all steps commented out) to a fully working workflow that sets up a complete Python development environment.

What Changed:

1. Removed commented-out Nix setup - The previous Nix-based setup was causing bash tool calls to hang silently
2. Added working uv/Python setup pattern - Implemented the same proven pattern used in release.yml and claude-code-test.yml
3. Added dependency caching - UV dependencies are now cached to speed up workflow runs
4. Fixed verification commands - Use uv run to execute pytest and ruff in the virtual environment (fixed CI failure)
5. Re-added commented Nix setup as documentation - Explains that Nix is preferred but causes issues with Copilot agent Bash tool calls
6. Created .github/copilot-instructions.md - Concise documentation for Copilot agents (references AGENTS.md, lists tools, provides test commands)

Workflow Steps:

1. Checkout code with actions/checkout@v4
2. Install uv with astral-sh/setup-uv@v4
3. Set up Python 3.11 with actions/setup-python@v5
4. Cache UV dependencies with actions/cache@v4
5. Install project dependencies with uv sync --extra dev
6. Verify environment setup with version checks for Python, uv, pytest, and ruff (using uv run)

Usage:

The workflow can be used in three ways:

• As a reusable workflow via workflow_call
• Manually triggered via workflow_dispatch from GitHub UI
• Automatically on PRs that modify the workflow file itself

Documentation:

• .github/copilot-instructions.md - Terse guide for Copilot agents
  • References AGENTS.md for complete context
  • Lists available tools (pytest, ruff, mypy, deepwork)
  • Provides test running commands

Validation:

✅ YAML syntax validated
✅ Code review passed with no issues
✅ CodeQL security scan passed with no vulnerabilities
✅ Pattern follows established working workflows in the repository
✅ CI failure fixed - tools now run in virtual environment via uv run
✅ Documented why Nix setup is not used (Copilot agent compatibility issue)
✅ Created concise Copilot development documentation

Original prompt

Update .github/workflows/copilot-setup-steps.yml to have a working copilot setup environment that can run uv/pytest etc

---

💡 You can make Copilot smarter by setting up custom instructions, customizing its development environment and configuring Model Context Protocol (MCP) servers. Learn more Copilot coding agent tips in the docs.

[github-actions]

Thank you for your submission, we really appreciate it. Like many open-source projects, we ask that you all sign our Developer Certificate of Origin before we can accept your contribution. You can sign the DCO by just posting a Pull Request Comment same as the below format.

---

I have read the CLA Document and I hereby sign the CLA

---

1 out of 2 committers have signed the DCO.
✅ (ncrmro)[https://github.com/ncrmro]
❌ @Copilot
_{You can retrigger this bot by commenting recheck in this Pull Request. Posted by the DCO Assistant Lite bot.}

[ncrmro]

@copilot fix

2026-01-22T23:50:50.5911967Z ##[group]Run echo "Python version:"
2026-01-22T23:50:50.5912323Z �[36;1mecho "Python version:"�[0m
2026-01-22T23:50:50.5912572Z �[36;1mpython --version�[0m
2026-01-22T23:50:50.5912986Z �[36;1mecho ""�[0m
2026-01-22T23:50:50.5913171Z �[36;1mecho "UV version:"�[0m
2026-01-22T23:50:50.5913395Z �[36;1muv --version�[0m
2026-01-22T23:50:50.5913586Z �[36;1mecho ""�[0m
2026-01-22T23:50:50.5913774Z �[36;1mecho "Pytest available:"�[0m
2026-01-22T23:50:50.5914061Z �[36;1mpython -m pytest --version�[0m
2026-01-22T23:50:50.5914300Z �[36;1mecho ""�[0m
2026-01-22T23:50:50.5914485Z �[36;1mecho "Ruff available:"�[0m
2026-01-22T23:50:50.5914734Z �[36;1mpython -m ruff --version�[0m
2026-01-22T23:50:50.5914962Z �[36;1mecho ""�[0m
2026-01-22T23:50:50.5915163Z �[36;1mecho "Environment setup complete!"�[0m
2026-01-22T23:50:50.5947947Z shell: /usr/bin/bash -e {0}
2026-01-22T23:50:50.5948187Z env:
2026-01-22T23:50:50.5948415Z UV_CACHE_DIR: /home/runner/work/_temp/setup-uv-cache
2026-01-22T23:50:50.5948791Z pythonLocation: /opt/hostedtoolcache/Python/3.11.14/x64
2026-01-22T23:50:50.5949254Z PKG_CONFIG_PATH: /opt/hostedtoolcache/Python/3.11.14/x64/lib/pkgconfig
2026-01-22T23:50:50.5949669Z Python_ROOT_DIR: /opt/hostedtoolcache/Python/3.11.14/x64
2026-01-22T23:50:50.5950033Z Python2_ROOT_DIR: /opt/hostedtoolcache/Python/3.11.14/x64
2026-01-22T23:50:50.5950584Z Python3_ROOT_DIR: /opt/hostedtoolcache/Python/3.11.14/x64
2026-01-22T23:50:50.5950956Z LD_LIBRARY_PATH: /opt/hostedtoolcache/Python/3.11.14/x64/lib
2026-01-22T23:50:50.5951252Z ##[endgroup]
2026-01-22T23:50:50.6007244Z Python version:
2026-01-22T23:50:50.6026345Z Python 3.11.14
2026-01-22T23:50:50.6029658Z
2026-01-22T23:50:50.6029808Z UV version:
2026-01-22T23:50:50.6077135Z uv 0.9.26
2026-01-22T23:50:50.6082996Z
2026-01-22T23:50:50.6083252Z Pytest available:
2026-01-22T23:50:50.6222314Z /opt/hostedtoolcache/Python/3.11.14/x64/bin/python: No module named pytest
2026-01-22T23:50:50.6266007Z ##[error]Process c

[Copilot]

@copilot fix

...

Fixed in 97ecfcb. Changed verification commands to use uv run pytest --version and uv run ruff --version instead of python -m, which ensures tools run in the virtual environment where dependencies are installed.

[ncrmro]

@copilot leave the original commented out nix code to explain the situation as nix would be the preferred environment

[Copilot]

@copilot leave the original commented out nix code to explain the situation as nix would be the preferred environment

Added in 910c40e. The commented Nix setup now includes a note explaining that Nix is the preferred environment but causes Copilot agent Bash tool calls to silently hang, which is why we're using the uv/Python setup as a workaround.

[ncrmro]

@copilot create .github/copilot-instructions.md that indicates how development can be done given these setup steps.

It should only really document this leaving the primary context defined in AGENTS.md

[Copilot]

Created in ec99005. The .github/copilot-instructions.md file documents:

• Environment setup steps (uv, Python 3.11, dependencies)
• Available tools and how to use them via uv run
• Development workflow (testing, linting, type checking)
• Why Nix isn't used for Copilot workflows
• References to AGENTS.md for primary context

[ncrmro]

@copilot make this terse, it should only document the AGENTS.md and the tools available as well as instructions for running tests

[Copilot]

Made terse in fb2f320. The file now only includes:

• Reference to AGENTS.md for primary context
• Available tools table (pytest, ruff, mypy, deepwork)
• Test running instructions
  Reduced from 128 lines to 35 lines.