From b958c468c3beedb143e38ccff185ce4eb616f5a9 Mon Sep 17 00:00:00 2001 From: "copilot-swe-agent[bot]" <198982749+Copilot@users.noreply.github.com> Date: Thu, 22 Jan 2026 23:41:52 +0000 Subject: [PATCH 1/7] Initial plan From 52756d0322010a0265b73d8710fb62d73be26e7f Mon Sep 17 00:00:00 2001 From: "copilot-swe-agent[bot]" <198982749+Copilot@users.noreply.github.com> Date: Thu, 22 Jan 2026 23:44:34 +0000 Subject: [PATCH 2/7] Update copilot-setup-steps.yml with working uv/pytest environment Co-authored-by: ncrmro <8276365+ncrmro@users.noreply.github.com> --- .github/workflows/copilot-setup-steps.yml | 54 +++++++++++++++-------- 1 file changed, 35 insertions(+), 19 deletions(-) diff --git a/.github/workflows/copilot-setup-steps.yml b/.github/workflows/copilot-setup-steps.yml index 2e6004ed..7c3f3317 100644 --- a/.github/workflows/copilot-setup-steps.yml +++ b/.github/workflows/copilot-setup-steps.yml @@ -15,22 +15,38 @@ jobs: - name: Checkout code uses: actions/checkout@v4 - # TODO this will cause all of copilot agents Bash tool calls to silently hang (which it won't complain about) - # - name: Install Nix - # uses: cachix/install-nix-action@v31 - # with: - # nix_path: nixpkgs=channel:nixos-unstable - # - uses: nicknovitski/nix-develop@v1 - - # - name: Cache UV dependencies - # uses: actions/cache@v4 - # with: - # path: | - # ~/.cache/uv - # .venv - # key: ${{ runner.os }}-uv-${{ hashFiles('uv.lock') }} - # restore-keys: | - # ${{ runner.os }}-uv- - - # - name: Install dependencies - # run: uv sync --extra dev + - name: Install uv + uses: astral-sh/setup-uv@v4 + with: + version: "latest" + + - name: Set up Python + uses: actions/setup-python@v5 + with: + python-version: "3.11" + + - name: Cache UV dependencies + uses: actions/cache@v4 + with: + path: | + ~/.cache/uv + .venv + key: ${{ runner.os }}-uv-${{ hashFiles('uv.lock') }} + restore-keys: | + ${{ runner.os }}-uv- + + - name: Install dependencies + run: uv sync --extra dev + + - name: Verify environment setup + run: | + echo "Python version:" + python --version + echo "" + echo "UV version:" + uv --version + echo "" + echo "Pytest available:" + uv run pytest --version + echo "" + echo "Environment setup complete!" From f17e693fb0d9bfd6aade7887d6d9ab089f5e4f06 Mon Sep 17 00:00:00 2001 From: "copilot-swe-agent[bot]" <198982749+Copilot@users.noreply.github.com> Date: Thu, 22 Jan 2026 23:47:24 +0000 Subject: [PATCH 3/7] Improve verification step with ruff check and direct tool invocation Co-authored-by: ncrmro <8276365+ncrmro@users.noreply.github.com> --- .github/workflows/copilot-setup-steps.yml | 5 ++++- 1 file changed, 4 insertions(+), 1 deletion(-) diff --git a/.github/workflows/copilot-setup-steps.yml b/.github/workflows/copilot-setup-steps.yml index 7c3f3317..dd4128d0 100644 --- a/.github/workflows/copilot-setup-steps.yml +++ b/.github/workflows/copilot-setup-steps.yml @@ -47,6 +47,9 @@ jobs: uv --version echo "" echo "Pytest available:" - uv run pytest --version + python -m pytest --version + echo "" + echo "Ruff available:" + python -m ruff --version echo "" echo "Environment setup complete!" From 97ecfcbebac3443cf11525a5eb40efb8c38b98cf Mon Sep 17 00:00:00 2001 From: "copilot-swe-agent[bot]" <198982749+Copilot@users.noreply.github.com> Date: Fri, 23 Jan 2026 00:01:07 +0000 Subject: [PATCH 4/7] Fix pytest/ruff verification to use uv run instead of python -m Co-authored-by: ncrmro <8276365+ncrmro@users.noreply.github.com> --- .github/workflows/copilot-setup-steps.yml | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/.github/workflows/copilot-setup-steps.yml b/.github/workflows/copilot-setup-steps.yml index dd4128d0..a92d7d5f 100644 --- a/.github/workflows/copilot-setup-steps.yml +++ b/.github/workflows/copilot-setup-steps.yml @@ -47,9 +47,9 @@ jobs: uv --version echo "" echo "Pytest available:" - python -m pytest --version + uv run pytest --version echo "" echo "Ruff available:" - python -m ruff --version + uv run ruff --version echo "" echo "Environment setup complete!" From 910c40ed62c0edfdbee33de73cf8ac3dd528fbf4 Mon Sep 17 00:00:00 2001 From: "copilot-swe-agent[bot]" <198982749+Copilot@users.noreply.github.com> Date: Fri, 23 Jan 2026 16:34:18 +0000 Subject: [PATCH 5/7] Add commented Nix setup to explain why uv/Python is used instead Co-authored-by: ncrmro <8276365+ncrmro@users.noreply.github.com> --- .github/workflows/copilot-setup-steps.yml | 8 ++++++++ 1 file changed, 8 insertions(+) diff --git a/.github/workflows/copilot-setup-steps.yml b/.github/workflows/copilot-setup-steps.yml index a92d7d5f..e97cd89f 100644 --- a/.github/workflows/copilot-setup-steps.yml +++ b/.github/workflows/copilot-setup-steps.yml @@ -15,6 +15,14 @@ jobs: - name: Checkout code uses: actions/checkout@v4 + # NOTE: Nix would be the preferred environment, but it causes Copilot agent + # Bash tool calls to silently hang. Using uv/Python setup as a workaround. + # - name: Install Nix + # uses: cachix/install-nix-action@v31 + # with: + # nix_path: nixpkgs=channel:nixos-unstable + # - uses: nicknovitski/nix-develop@v1 + - name: Install uv uses: astral-sh/setup-uv@v4 with: From ec99005a45d8de4b65c1486f9f11d1d426e74ff2 Mon Sep 17 00:00:00 2001 From: "copilot-swe-agent[bot]" <198982749+Copilot@users.noreply.github.com> Date: Fri, 23 Jan 2026 17:34:54 +0000 Subject: [PATCH 6/7] Add .github/copilot-instructions.md documenting development setup for Copilot agents Co-authored-by: ncrmro <8276365+ncrmro@users.noreply.github.com> --- .github/copilot-instructions.md | 128 ++++++++++++++++++++++++++++++++ 1 file changed, 128 insertions(+) create mode 100644 .github/copilot-instructions.md diff --git a/.github/copilot-instructions.md b/.github/copilot-instructions.md new file mode 100644 index 00000000..0f796ea2 --- /dev/null +++ b/.github/copilot-instructions.md @@ -0,0 +1,128 @@ +# GitHub Copilot Development Environment + +This document describes the development environment setup for GitHub Copilot agents working on this repository. + +## Overview + +GitHub Copilot agents use a **uv/Python-based environment** rather than the Nix environment recommended for human developers. This is because Nix causes Copilot agent Bash tool calls to silently hang during workflow execution. + +For comprehensive agent instructions and repository context, see [`AGENTS.md`](../AGENTS.md) in the root directory. + +## Environment Setup + +The environment is configured via the `.github/workflows/copilot-setup-steps.yml` workflow and includes: + +### Prerequisites + +- **Python 3.11** - Base interpreter +- **uv** - Python package manager for dependency installation +- **Git** - Version control + +### Setup Steps + +The following steps are executed in GitHub Actions workflows to prepare the development environment: + +1. **Install uv** - Modern Python package manager + ```bash + # Installed via astral-sh/setup-uv@v4 + uv --version + ``` + +2. **Set up Python 3.11** - Using actions/setup-python@v5 + ```bash + python --version # Should show Python 3.11.x + ``` + +3. **Install dependencies** - All development tools and project dependencies + ```bash + uv sync --extra dev + ``` + +4. **Verify environment** - Check that tools are available + ```bash + uv run pytest --version # Test runner + uv run ruff --version # Linter and formatter + ``` + +### Available Tools + +After setup, the following tools are available via `uv run`: + +| Tool | Command | Description | +|------|---------|-------------| +| **pytest** | `uv run pytest` | Test runner with all plugins | +| **ruff** | `uv run ruff` | Fast Python linter and formatter | +| **mypy** | `uv run mypy` | Static type checker | +| **deepwork** | `uv run deepwork` | DeepWork CLI (local source) | + +### Running Commands + +All Python tools must be executed via `uv run` to ensure they run in the virtual environment where dependencies are installed: + +```bash +# ✅ Correct - runs in virtual environment +uv run pytest tests/ +uv run ruff check src/ +uv run mypy src/ + +# ❌ Incorrect - may not find installed packages +python -m pytest tests/ +pytest tests/ +``` + +## Development Workflow + +### Running Tests + +```bash +# Run all tests +uv run pytest tests/ -v + +# Run specific test file +uv run pytest tests/test_example.py -v + +# Run with coverage +uv run pytest tests/ --cov=deepwork --cov-report=html +``` + +### Code Quality Checks + +```bash +# Format code +uv run ruff format src/ tests/ + +# Check linting +uv run ruff check src/ tests/ + +# Type checking +uv run mypy src/ +``` + +### Working with DeepWork CLI + +```bash +# Run deepwork commands +uv run deepwork --help +uv run deepwork install --platform claude +uv run deepwork sync +``` + +## Why Not Nix? + +While Nix is the **preferred and recommended** development environment for human developers (see [`CONTRIBUTING.md`](../CONTRIBUTING.md)), it cannot be used in GitHub Copilot workflows because: + +1. Nix installation causes Copilot agent Bash tool calls to silently hang +2. The `nix-develop` action interferes with interactive command execution +3. Workflow timeouts and failures occur with no useful error messages + +The uv/Python setup provides a compatible alternative that: +- ✅ Works reliably in GitHub Actions with Copilot agents +- ✅ Provides all necessary development tools (pytest, ruff, mypy) +- ✅ Uses dependency caching for fast workflow execution +- ✅ Follows the same patterns as `release.yml` and `claude-code-test.yml` + +## Additional Resources + +- **Primary Agent Instructions**: [`AGENTS.md`](../AGENTS.md) - Complete context for AI agents +- **Human Developer Setup**: [`CONTRIBUTING.md`](../CONTRIBUTING.md) - Nix-based setup for local development +- **Workflow Definition**: [`.github/workflows/copilot-setup-steps.yml`](workflows/copilot-setup-steps.yml) From fb2f3200510b998db7d5d9aa166a285f6e8a0fca Mon Sep 17 00:00:00 2001 From: "copilot-swe-agent[bot]" <198982749+Copilot@users.noreply.github.com> Date: Fri, 23 Jan 2026 17:43:22 +0000 Subject: [PATCH 7/7] Make copilot-instructions.md terse - focus on AGENTS.md reference, tools, and tests Co-authored-by: ncrmro <8276365+ncrmro@users.noreply.github.com> --- .github/copilot-instructions.md | 127 +++++--------------------------- 1 file changed, 17 insertions(+), 110 deletions(-) diff --git a/.github/copilot-instructions.md b/.github/copilot-instructions.md index 0f796ea2..f34031d1 100644 --- a/.github/copilot-instructions.md +++ b/.github/copilot-instructions.md @@ -1,128 +1,35 @@ # GitHub Copilot Development Environment -This document describes the development environment setup for GitHub Copilot agents working on this repository. - -## Overview - -GitHub Copilot agents use a **uv/Python-based environment** rather than the Nix environment recommended for human developers. This is because Nix causes Copilot agent Bash tool calls to silently hang during workflow execution. - -For comprehensive agent instructions and repository context, see [`AGENTS.md`](../AGENTS.md) in the root directory. +**Primary agent instructions**: See [`AGENTS.md`](../AGENTS.md) for complete repository context. ## Environment Setup -The environment is configured via the `.github/workflows/copilot-setup-steps.yml` workflow and includes: - -### Prerequisites - -- **Python 3.11** - Base interpreter -- **uv** - Python package manager for dependency installation -- **Git** - Version control - -### Setup Steps - -The following steps are executed in GitHub Actions workflows to prepare the development environment: - -1. **Install uv** - Modern Python package manager - ```bash - # Installed via astral-sh/setup-uv@v4 - uv --version - ``` - -2. **Set up Python 3.11** - Using actions/setup-python@v5 - ```bash - python --version # Should show Python 3.11.x - ``` - -3. **Install dependencies** - All development tools and project dependencies - ```bash - uv sync --extra dev - ``` - -4. **Verify environment** - Check that tools are available - ```bash - uv run pytest --version # Test runner - uv run ruff --version # Linter and formatter - ``` - -### Available Tools - -After setup, the following tools are available via `uv run`: - -| Tool | Command | Description | -|------|---------|-------------| -| **pytest** | `uv run pytest` | Test runner with all plugins | -| **ruff** | `uv run ruff` | Fast Python linter and formatter | -| **mypy** | `uv run mypy` | Static type checker | -| **deepwork** | `uv run deepwork` | DeepWork CLI (local source) | - -### Running Commands - -All Python tools must be executed via `uv run` to ensure they run in the virtual environment where dependencies are installed: +GitHub Copilot agents use uv/Python (not Nix) because Nix causes Bash tool calls to hang. Setup is handled by `.github/workflows/copilot-setup-steps.yml`: ```bash -# ✅ Correct - runs in virtual environment -uv run pytest tests/ -uv run ruff check src/ -uv run mypy src/ - -# ❌ Incorrect - may not find installed packages -python -m pytest tests/ -pytest tests/ +uv sync --extra dev ``` -## Development Workflow +## Available Tools + +All tools must be run via `uv run`: -### Running Tests +| Tool | Command | +|------|---------| +| **pytest** | `uv run pytest tests/ -v` | +| **ruff** | `uv run ruff check src/` | +| **mypy** | `uv run mypy src/` | +| **deepwork** | `uv run deepwork` | + +## Running Tests ```bash -# Run all tests +# All tests uv run pytest tests/ -v -# Run specific test file +# Specific test file uv run pytest tests/test_example.py -v -# Run with coverage +# With coverage uv run pytest tests/ --cov=deepwork --cov-report=html ``` - -### Code Quality Checks - -```bash -# Format code -uv run ruff format src/ tests/ - -# Check linting -uv run ruff check src/ tests/ - -# Type checking -uv run mypy src/ -``` - -### Working with DeepWork CLI - -```bash -# Run deepwork commands -uv run deepwork --help -uv run deepwork install --platform claude -uv run deepwork sync -``` - -## Why Not Nix? - -While Nix is the **preferred and recommended** development environment for human developers (see [`CONTRIBUTING.md`](../CONTRIBUTING.md)), it cannot be used in GitHub Copilot workflows because: - -1. Nix installation causes Copilot agent Bash tool calls to silently hang -2. The `nix-develop` action interferes with interactive command execution -3. Workflow timeouts and failures occur with no useful error messages - -The uv/Python setup provides a compatible alternative that: -- ✅ Works reliably in GitHub Actions with Copilot agents -- ✅ Provides all necessary development tools (pytest, ruff, mypy) -- ✅ Uses dependency caching for fast workflow execution -- ✅ Follows the same patterns as `release.yml` and `claude-code-test.yml` - -## Additional Resources - -- **Primary Agent Instructions**: [`AGENTS.md`](../AGENTS.md) - Complete context for AI agents -- **Human Developer Setup**: [`CONTRIBUTING.md`](../CONTRIBUTING.md) - Nix-based setup for local development -- **Workflow Definition**: [`.github/workflows/copilot-setup-steps.yml`](workflows/copilot-setup-steps.yml)