gxy-tool-bot 0.1.0__tar.gz

gxy_tool_bot-0.1.0/.gitignore

@@ -0,0 +1,30 @@
+# Python
+__pycache__/
+*.py[cod]
+*$py.class
+*.egg-info/
+*.egg
+dist/
+build/
+.eggs/
+
+# Virtual environments
+.conda/
+.env
+
+# IDE
+.vscode/
+.idea/
+
+# OS
+.DS_Store
+Thumbs.db
+
+# Test artifacts
+.pytest_cache/
+test-output/
+site-output/
+generated/
+
+# Exemplar cache
+gxy-exemplars-*/

gxy_tool_bot-0.1.0/DEVELOPMENT.md

@@ -0,0 +1,104 @@
+# Developer Guide
+
+This guide helps developers find their way around the codebase when adding new
+conventions, validation checks, or prompt changes.
+
+## Key Files
+
+### Prompts (system + user templates)
+
+| File | Used by | Purpose |
+|------|---------|---------|
+| `gxy_tool_bot/templates/generator_system.txt` | Generation flow | System prompt — tells the agent how to write Galaxy tool XML, IUC conventions, available tools |
+| `gxy_tool_bot/templates/generator_user.txt` | Generation flow | User prompt — contains the plan, exemplar tools, and instructions |
+| `gxy_tool_bot/templates/feedback_system.txt` | Feedback flow | System prompt — tells the agent how to fix existing tools based on CI/reviewer feedback |
+| `gxy_tool_bot/templates/_conventions.txt` | Both flows | Shared IUC conventions included via Jinja2 `{% include %}` in both system prompts. Update this file once to change a convention in both flows. |
+| `gxy_tool_bot/address_feedback.py` (`_build_feedback_user_prompt`) | Feedback flow | User prompt — built dynamically from PR comments, CI artifacts, and file listing |
+
+### Validation
+
+| File | Purpose |
+|------|---------|
+| `gxy_tool_bot/validation.py` | `ValidationResult`, `validate_generated_files`, and `run_agent_with_validation` — all validation logic lives here |
+| `gxy_tool_bot/generator.py` | `FileWriter`, `GeneratedFile`, `GeneratedTool`, tool definitions, and the `generate_tool` entry point |
+| `gxy_tool_bot/address_feedback.py` | Feedback collection, prompt building, and the `address_feedback` entry point |
+
+### Agent loop
+
+| File | Purpose |
+|------|---------|
+| `gxy_tool_bot/agent_loop.py` | Core agent loop — handles tool calls, message history, iteration limits |
+
+## When to Put Things Where
+
+There are three places a convention can live. The goal is a concise prompt that
+gets the agent writing quickly, with validation as a safety net — and letting
+planemo CI catch the rest.
+
+### 1. System prompts (proactive guidance)
+
+**Use when:** The convention can't be tested by inspecting files, or requires
+judgment/context the agent needs before writing.
+
+**Files:** `templates/generator_system.txt`, `templates/feedback_system.txt`
+(usually add to both).
+
+**Examples:** "use `galaxy_slots` for threading", "make asserts strong and
+specific", "use `mv` instead of `cp`".
+
+**Keep concise** — every line costs tokens on every LLM call. Prefer getting
+the agent to write something and iterate rather than bogging it down with
+exhaustive rules upfront.
+
+### 2. Validation checks (structural safety net)
+
+**Use when:** The convention can be detected by inspecting the generated files
+(XML structure, attribute patterns, missing test data, etc.).
+
+**File:** `gxy_tool_bot/validation.py` → `validate_generated_files`
+
+**Each check must produce a clear error message** telling the agent exactly
+what to fix. These run after the agent writes, so they don't bloat the prompt
+but still catch mistakes on retry.
+
+**Examples:** "don't use the bare default output label", "missing
+`expect_num_outputs` on `<test>`", "Cheetah in `<xml>` macros".
+
+### 3. Neither (let planemo CI catch it)
+
+**Use when:** Planemo already checks it explicitly (e.g. XML well-formedness,
+shed metadata, duplicated output labels).
+
+The CI workflow reports these failures and the feedback flow picks them up on
+the next iteration. Only add a check to validation or the prompt if the bot is
+**consistently** making that specific mistake, wasting tokens and maintainer time 
+on retries that a simple upfront rule would prevent.
+
+### Quick reference
+
+| Tier | Where | When | Token cost |
+|------|-------|------|------------|
+| Prompt | `templates/*_system.txt` | Can't test by inspection; needs judgment | Every LLM call |
+| Validation | `validation.py` | Can inspect files; clear fix message | Only on retry |
+| Neither | Planemo CI | Planemo already checks it | Zero |
+
+### Adding a new tool for the agent
+
+Add the tool definition to `_build_tool_definitions` in `gxy_tool_bot/generator.py`.
+If the tool has a handler method, add it to the `FileWriter` class (for file-related
+tools) or as a standalone function.
+
+### Modifying the feedback prompt
+
+The feedback user prompt is built dynamically in `_build_feedback_user_prompt`
+in `gxy_tool_bot/address_feedback.py`. The system prompt is in
+`templates/feedback_system.txt`.
+
+## Running Tests
+
+```bash
+conda run -n gxy-tool-bot python -m pytest tests/ -v
+```
+
+Validation tests are in `tests/test_generator.py` (they test
+`validate_generated_files` from `gxy_tool_bot/validation.py`).

gxy_tool_bot-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Danielle Callan
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

gxy_tool_bot-0.1.0/PKG-INFO

@@ -0,0 +1,177 @@
+Metadata-Version: 2.4
+Name: gxy-tool-bot
+Version: 0.1.0
+Summary: Agentic bot that generates Galaxy tool wrappers from user requests
+Author: gxy-tool-bot contributors
+License: MIT
+License-File: LICENSE
+Requires-Python: >=3.12
+Requires-Dist: beautifulsoup4>=4.12
+Requires-Dist: click>=8.1
+Requires-Dist: httpx>=0.27
+Requires-Dist: jinja2>=3.1
+Requires-Dist: pyyaml>=6.0
+Provides-Extra: dev
+Requires-Dist: pytest-mock>=3.12; extra == 'dev'
+Requires-Dist: pytest>=8.0; extra == 'dev'
+Requires-Dist: respx>=0.21; extra == 'dev'
+Requires-Dist: ruff>=0.5; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# gxy-tool-bot
+
+Because once upon a time Björn said to Danielle: Wouldn't an Agentic Galaxy Tool Bot be cool? :smile:
+
+So this is an agentic bot that generates [Galaxy](https://galaxyproject.org/) tool wrappers from user requests, powered by LLM APIs and orchestrated through GitHub Actions.
+
+## Overview
+
+`gxy-tool-bot` is a Python library + companion GitHub Actions workflows that automate the creation of Galaxy tool wrappers. It is **not a tool repo itself** — it's a library consumed by repos that house Galaxy tools.
+
+## Current Status
+
+This repository is under active development. The bot can plan tool wrappers, generate XML/macros/test data, and open PRs automatically. It has been tested end-to-end on real tool requests. Expect rough edges and iterate on configuration as needed.
+
+## How it works
+
+1. **Request:** Users file a GitHub issue using the "Tool Request" issue template (structured fields for tool name, description, links, contact).
+2. **Plan:** The `tool-request` label triggers a workflow. An agent researches the tool (bioconda, GitHub, publications, web) and posts a plan as an issue comment with a `plan-ready` label.
+3. **Review:** A maintainer reviews the plan and adds the `ready-to-implement` label.
+4. **Generate:** An agent generates the tool XML, macros, and test data, then opens a PR with a `pr-opened` label on the issue. If the agent gives up or crashes, a `generation-failed` label is applied instead. If generation completes but validation finds issues, the PR is still created with the validation errors noted in the description — apply the `address-feedback` label to have the bot attempt fixes.
+
+## Setup (for consuming repos)
+
+### 1. Install the bot
+
+The bot can be installed from PyPI or directly from GitHub:
+
+```bash
+pip install gxy-tool-bot              # from PyPI
+pip install git+https://github.com/d-callan/gxy-tool-bot.git  # latest from GitHub
+```
+
+### 2. Create a config file
+
+Create `.gxy-tool-bot.yml` in the repo root:
+
+```yaml
+api:
+  base_url: https://openrouter.ai/api/v1   # or https://api.openai.com/v1
+  model: z-ai/glm-5.2                       # or gpt-4o, etc.
+  fallback_models:                          # optional; tried in order if primary fails
+    - deepseek-ai/deepseek-r1
+    - gpt-4o
+  max_tool_iterations: 25
+  temperature_plan: 0.4
+  temperature_generate: 0.2
+  max_context_chars: 100000
+  max_validation_retries: 3
+  read_timeout: 600                         # seconds; increase for slow models
+
+exemplars:
+  - url: https://raw.githubusercontent.com/galaxyproject/tools-iuc/main/tools/bcftools/bcftools_view.xml
+    macros: https://raw.githubusercontent.com/galaxyproject/tools-iuc/main/tools/bcftools/macros.xml
+    shed_yml: https://raw.githubusercontent.com/galaxyproject/tools-iuc/main/tools/bcftools/.shed.yml
+  - url: https://raw.githubusercontent.com/galaxyproject/tools-iuc/main/tools/seqtk/seqtk_seq.xml
+    macros: https://raw.githubusercontent.com/galaxyproject/tools-iuc/main/tools/seqtk/macros.xml
+    shed_yml: https://raw.githubusercontent.com/galaxyproject/tools-iuc/main/tools/seqtk/.shed.yml
+
+# repo is optional — falls back to GITHUB_REPOSITORY env var (set automatically in GitHub Actions)
+repo: your-org/your-repo
+
+allowed_maintainers:
+  - your-github-handle
+```
+
+### 3. Create GitHub labels
+
+Create these labels in the repo (Settings → Labels):
+
+| Label | Color | Purpose |
+|-------|-------|---------|
+| `tool-request` | `#0075ca` | Applied automatically by issue template; triggers planning |
+| `plan-ready` | `#a2eeef` | Applied by bot after plan is posted |
+| `ready-to-implement` | `#0e8a16` | Applied by maintainer to approve plan; triggers generation |
+| `pr-opened` | `#1d76db` | Applied by bot after PR is created |
+| `generation-failed` | `#b60205` | Applied by bot if generation or planning fails |
+| `retry-plan` | `#fbca04` | Applied by user/maintainer to re-trigger planning after a failure |
+| `retry-generate` | `#fbca04` | Applied by user/maintainer to re-trigger generation after a failure |
+| `address-feedback` | `#5319e7` | Applied to a PR to have the bot address review comments and CI failures |
+
+### 4. Add the issue template
+
+Copy `examples/issue-template-tool-request.yml` from this repo into your repo's `.github/ISSUE_TEMPLATE/tool-request.yml`. The template auto-applies the `tool-request` label so the planning workflow triggers automatically.
+
+### 5. Add workflow files
+
+Copy the workflow templates from the [`workflows/`](workflows/) directory in this repo into your repo's `.github/workflows/`:
+
+- **`on-tool-request.yml`** → `.github/workflows/gxy-on-tool-request.yml` — triggers on new issues with `tool-request` label or when `retry-plan` label is added; runs the planner
+- **`on-ready-to-implement.yml`** → `.github/workflows/gxy-on-ready-to-implement.yml` — triggers when `ready-to-implement` or `retry-generate` label is added; runs the generator and opens a PR
+- **`on-pr-feedback.yml`** → `.github/workflows/gxy-on-pr-feedback.yml` — triggers when `address-feedback` label is added to a PR; reads review comments and CI failures, pushes fixes as new commits
+
+> **CI artifact assumption:** The feedback workflow fetches CI failure details from GitHub Actions artifacts. This assumes the CI workflow uploads failure reports as artifacts (e.g. lint reports as `.txt` files, planemo test results as `.json`), following the same conventions as the [tools-iuc](https://github.com/galaxyproject/tools-iuc) repo's `pr.yaml` workflow. If your repo uses a different CI setup that doesn't upload artifacts on failure, the bot will not be able to include CI failure details in its feedback context.
+
+> **Validation flag file:** When generation or feedback addressing completes but validation finds issues, the CLI writes a `.validation-failed` flag file to `GITHUB_WORKSPACE` (a built-in GitHub Actions env var). The workflows check for this file to post a comment on the PR noting that validation issues exist. The file is cleaned up after use and is never committed.
+
+Both workflows install the bot from PyPI (pinned to a specific version):
+
+```yaml
+- run: pip install gxy-tool-bot==0.1.0
+```
+
+### 6. Add repo secrets
+
+Go to Settings → Secrets and variables → Actions → New repository secret:
+
+| Secret | Value | Used by |
+|--------|-------|---------|
+| `GXY_TOOL_BOT_API_KEY` | Your LLM API key (e.g. OpenRouter key) | Plan + generate workflows |
+
+The `GITHUB_TOKEN` (automatically provided by GitHub Actions) is used for issue comments, labels, and PR creation — no extra secret needed.
+
+### 7. Enable Issues
+
+If the repo is a fork, Issues may be disabled by default. Enable them under Settings → General → Features → check "Issues".
+
+### 8. Enable Actions
+
+Make sure Actions are enabled: Settings → Actions → General → "Allow all actions and reusable workflows".
+
+### 9. Test it
+
+1. Go to Issues → New Issue → "Tool Request" template
+2. Fill in the fields and submit
+3. Check the Actions tab — the planning workflow should run
+4. After the plan is posted, add the `ready-to-implement` label
+5. The generation workflow should run and open a PR
+
+## Philosophy & Design Decisions
+
+### Run in GitHub Actions, not a black box
+
+The bot runs entirely in GitHub Actions. This keeps agent traces, plans, generated files, and CI results publicly inspectable. Every run produces logs and artifacts you can review after the fact — to diagnose why a specific tool was written a certain way, or to identify patterns to improve the bot. The Actions logs capture tool calls, context size per iteration, and validation results; combined with file-based artifacts (generated files, test data) and summary comments posted to issues and PRs, this provides enough transparency to understand what the bot did and why.
+
+### Validate files, don't over-prompt
+
+Best practices don't go in the system prompt — they go in a [validation loop](gxy_tool_bot/validation.py) that inspects generated files for common mistakes (missing test data, bare output labels, Cheetah in macros, etc.) and instructs the agent to fix them in a retry loop. This keeps prompts concise (every line costs tokens on every LLM call) and prevents unnecessary bloat that might distract or confuse the agent, while still catching errors structurally. See [DEVELOPMENT.md](DEVELOPMENT.md) for the full tiered guidance on where to put conventions.
+
+### Incremental feedback, not infinite loops
+
+The validation loop only runs a limited number of times before forcing the result back to human hands — a commit is pushed to a PR that a maintainer can review and provide further direction on. The maintainer adds the `address-feedback` label to trigger another loop with CI failures and review comments incorporated. This keeps the bot autonomous for the common case but avoids burning tokens indefinitely on a problem it can't solve alone.
+
+### Let planemo CI catch the rest
+
+Things planemo already checks (XML well-formedness, shed metadata, duplicated output labels) are deliberately not duplicated in validation. The CI workflow reports these failures and the feedback flow picks them up on the next iteration. Only add a validation check if the bot is consistently making a specific mistake that wastes tokens and maintainer time.
+
+### Give the agent a way out
+
+The agent has a `give_up` tool that lets it stop and explain why it can't proceed — open assumptions, unresolved questions, or fundamental issues with the request. A tool request might produce a recommendation not to make a tool rather than a plan to make one. A feedback request might result in push back with no commit until something the agent flags is resolved. This prevents forcing the agent into action when it doesn't have enough information, which would produce low-quality output. Better to surface the problem to a human than to generate a confident but wrong tool wrapper.
+
+## Development
+
+See [DEVELOPMENT.md](DEVELOPMENT.md) for guidance on the codebase structure, where to add new conventions (prompts vs. validation vs. let CI catch it), and how the generation and feedback flows are organized.
+
+## License
+
+MIT

gxy_tool_bot-0.1.0/README.md

@@ -0,0 +1,157 @@
+# gxy-tool-bot
+
+Because once upon a time Björn said to Danielle: Wouldn't an Agentic Galaxy Tool Bot be cool? :smile:
+
+So this is an agentic bot that generates [Galaxy](https://galaxyproject.org/) tool wrappers from user requests, powered by LLM APIs and orchestrated through GitHub Actions.
+
+## Overview
+
+`gxy-tool-bot` is a Python library + companion GitHub Actions workflows that automate the creation of Galaxy tool wrappers. It is **not a tool repo itself** — it's a library consumed by repos that house Galaxy tools.
+
+## Current Status
+
+This repository is under active development. The bot can plan tool wrappers, generate XML/macros/test data, and open PRs automatically. It has been tested end-to-end on real tool requests. Expect rough edges and iterate on configuration as needed.
+
+## How it works
+
+1. **Request:** Users file a GitHub issue using the "Tool Request" issue template (structured fields for tool name, description, links, contact).
+2. **Plan:** The `tool-request` label triggers a workflow. An agent researches the tool (bioconda, GitHub, publications, web) and posts a plan as an issue comment with a `plan-ready` label.
+3. **Review:** A maintainer reviews the plan and adds the `ready-to-implement` label.
+4. **Generate:** An agent generates the tool XML, macros, and test data, then opens a PR with a `pr-opened` label on the issue. If the agent gives up or crashes, a `generation-failed` label is applied instead. If generation completes but validation finds issues, the PR is still created with the validation errors noted in the description — apply the `address-feedback` label to have the bot attempt fixes.
+
+## Setup (for consuming repos)
+
+### 1. Install the bot
+
+The bot can be installed from PyPI or directly from GitHub:
+
+```bash
+pip install gxy-tool-bot              # from PyPI
+pip install git+https://github.com/d-callan/gxy-tool-bot.git  # latest from GitHub
+```
+
+### 2. Create a config file
+
+Create `.gxy-tool-bot.yml` in the repo root:
+
+```yaml
+api:
+  base_url: https://openrouter.ai/api/v1   # or https://api.openai.com/v1
+  model: z-ai/glm-5.2                       # or gpt-4o, etc.
+  fallback_models:                          # optional; tried in order if primary fails
+    - deepseek-ai/deepseek-r1
+    - gpt-4o
+  max_tool_iterations: 25
+  temperature_plan: 0.4
+  temperature_generate: 0.2
+  max_context_chars: 100000
+  max_validation_retries: 3
+  read_timeout: 600                         # seconds; increase for slow models
+
+exemplars:
+  - url: https://raw.githubusercontent.com/galaxyproject/tools-iuc/main/tools/bcftools/bcftools_view.xml
+    macros: https://raw.githubusercontent.com/galaxyproject/tools-iuc/main/tools/bcftools/macros.xml
+    shed_yml: https://raw.githubusercontent.com/galaxyproject/tools-iuc/main/tools/bcftools/.shed.yml
+  - url: https://raw.githubusercontent.com/galaxyproject/tools-iuc/main/tools/seqtk/seqtk_seq.xml
+    macros: https://raw.githubusercontent.com/galaxyproject/tools-iuc/main/tools/seqtk/macros.xml
+    shed_yml: https://raw.githubusercontent.com/galaxyproject/tools-iuc/main/tools/seqtk/.shed.yml
+
+# repo is optional — falls back to GITHUB_REPOSITORY env var (set automatically in GitHub Actions)
+repo: your-org/your-repo
+
+allowed_maintainers:
+  - your-github-handle
+```
+
+### 3. Create GitHub labels
+
+Create these labels in the repo (Settings → Labels):
+
+| Label | Color | Purpose |
+|-------|-------|---------|
+| `tool-request` | `#0075ca` | Applied automatically by issue template; triggers planning |
+| `plan-ready` | `#a2eeef` | Applied by bot after plan is posted |
+| `ready-to-implement` | `#0e8a16` | Applied by maintainer to approve plan; triggers generation |
+| `pr-opened` | `#1d76db` | Applied by bot after PR is created |
+| `generation-failed` | `#b60205` | Applied by bot if generation or planning fails |
+| `retry-plan` | `#fbca04` | Applied by user/maintainer to re-trigger planning after a failure |
+| `retry-generate` | `#fbca04` | Applied by user/maintainer to re-trigger generation after a failure |
+| `address-feedback` | `#5319e7` | Applied to a PR to have the bot address review comments and CI failures |
+
+### 4. Add the issue template
+
+Copy `examples/issue-template-tool-request.yml` from this repo into your repo's `.github/ISSUE_TEMPLATE/tool-request.yml`. The template auto-applies the `tool-request` label so the planning workflow triggers automatically.
+
+### 5. Add workflow files
+
+Copy the workflow templates from the [`workflows/`](workflows/) directory in this repo into your repo's `.github/workflows/`:
+
+- **`on-tool-request.yml`** → `.github/workflows/gxy-on-tool-request.yml` — triggers on new issues with `tool-request` label or when `retry-plan` label is added; runs the planner
+- **`on-ready-to-implement.yml`** → `.github/workflows/gxy-on-ready-to-implement.yml` — triggers when `ready-to-implement` or `retry-generate` label is added; runs the generator and opens a PR
+- **`on-pr-feedback.yml`** → `.github/workflows/gxy-on-pr-feedback.yml` — triggers when `address-feedback` label is added to a PR; reads review comments and CI failures, pushes fixes as new commits
+
+> **CI artifact assumption:** The feedback workflow fetches CI failure details from GitHub Actions artifacts. This assumes the CI workflow uploads failure reports as artifacts (e.g. lint reports as `.txt` files, planemo test results as `.json`), following the same conventions as the [tools-iuc](https://github.com/galaxyproject/tools-iuc) repo's `pr.yaml` workflow. If your repo uses a different CI setup that doesn't upload artifacts on failure, the bot will not be able to include CI failure details in its feedback context.
+
+> **Validation flag file:** When generation or feedback addressing completes but validation finds issues, the CLI writes a `.validation-failed` flag file to `GITHUB_WORKSPACE` (a built-in GitHub Actions env var). The workflows check for this file to post a comment on the PR noting that validation issues exist. The file is cleaned up after use and is never committed.
+
+Both workflows install the bot from PyPI (pinned to a specific version):
+
+```yaml
+- run: pip install gxy-tool-bot==0.1.0
+```
+
+### 6. Add repo secrets
+
+Go to Settings → Secrets and variables → Actions → New repository secret:
+
+| Secret | Value | Used by |
+|--------|-------|---------|
+| `GXY_TOOL_BOT_API_KEY` | Your LLM API key (e.g. OpenRouter key) | Plan + generate workflows |
+
+The `GITHUB_TOKEN` (automatically provided by GitHub Actions) is used for issue comments, labels, and PR creation — no extra secret needed.
+
+### 7. Enable Issues
+
+If the repo is a fork, Issues may be disabled by default. Enable them under Settings → General → Features → check "Issues".
+
+### 8. Enable Actions
+
+Make sure Actions are enabled: Settings → Actions → General → "Allow all actions and reusable workflows".
+
+### 9. Test it
+
+1. Go to Issues → New Issue → "Tool Request" template
+2. Fill in the fields and submit
+3. Check the Actions tab — the planning workflow should run
+4. After the plan is posted, add the `ready-to-implement` label
+5. The generation workflow should run and open a PR
+
+## Philosophy & Design Decisions
+
+### Run in GitHub Actions, not a black box
+
+The bot runs entirely in GitHub Actions. This keeps agent traces, plans, generated files, and CI results publicly inspectable. Every run produces logs and artifacts you can review after the fact — to diagnose why a specific tool was written a certain way, or to identify patterns to improve the bot. The Actions logs capture tool calls, context size per iteration, and validation results; combined with file-based artifacts (generated files, test data) and summary comments posted to issues and PRs, this provides enough transparency to understand what the bot did and why.
+
+### Validate files, don't over-prompt
+
+Best practices don't go in the system prompt — they go in a [validation loop](gxy_tool_bot/validation.py) that inspects generated files for common mistakes (missing test data, bare output labels, Cheetah in macros, etc.) and instructs the agent to fix them in a retry loop. This keeps prompts concise (every line costs tokens on every LLM call) and prevents unnecessary bloat that might distract or confuse the agent, while still catching errors structurally. See [DEVELOPMENT.md](DEVELOPMENT.md) for the full tiered guidance on where to put conventions.
+
+### Incremental feedback, not infinite loops
+
+The validation loop only runs a limited number of times before forcing the result back to human hands — a commit is pushed to a PR that a maintainer can review and provide further direction on. The maintainer adds the `address-feedback` label to trigger another loop with CI failures and review comments incorporated. This keeps the bot autonomous for the common case but avoids burning tokens indefinitely on a problem it can't solve alone.
+
+### Let planemo CI catch the rest
+
+Things planemo already checks (XML well-formedness, shed metadata, duplicated output labels) are deliberately not duplicated in validation. The CI workflow reports these failures and the feedback flow picks them up on the next iteration. Only add a validation check if the bot is consistently making a specific mistake that wastes tokens and maintainer time.
+
+### Give the agent a way out
+
+The agent has a `give_up` tool that lets it stop and explain why it can't proceed — open assumptions, unresolved questions, or fundamental issues with the request. A tool request might produce a recommendation not to make a tool rather than a plan to make one. A feedback request might result in push back with no commit until something the agent flags is resolved. This prevents forcing the agent into action when it doesn't have enough information, which would produce low-quality output. Better to surface the problem to a human than to generate a confident but wrong tool wrapper.
+
+## Development
+
+See [DEVELOPMENT.md](DEVELOPMENT.md) for guidance on the codebase structure, where to add new conventions (prompts vs. validation vs. let CI catch it), and how the generation and feedback flows are organized.
+
+## License
+
+MIT

gxy_tool_bot-0.1.0/examples/issue-template-tool-request.yml

@@ -0,0 +1,45 @@
+name: Tool Request
+description: Request a new Galaxy tool wrapper to be generated
+labels: ["tool-request"]
+body:
+  - type: markdown
+    attributes:
+      value: |
+        Fill out this form to request a new Galaxy tool wrapper.
+        The bot will research the tool and post a plan as a comment.
+        A maintainer will then review and approve it for generation.
+  - type: input
+    id: tool-name
+    attributes:
+      label: Tool name
+      description: Name of the bioinformatics tool (e.g. samtools sort)
+      placeholder: e.g. samtools sort
+    validations:
+      required: true
+  - type: textarea
+    id: description
+    attributes:
+      label: Description
+      description: What should the tool do? What are the key inputs and outputs?
+      placeholder: Sort BAM files by coordinate or read name...
+    validations:
+      required: true
+  - type: textarea
+    id: links
+    attributes:
+      label: Links
+      description: Relevant URLs — GitHub repo, Bioconda page, DOI/publication, documentation
+      placeholder: |
+        https://github.com/samtools/samtools
+        https://doi.org/10.1093/bioinformatics/btp352
+        https://bioconda.github.io/recipes/samtools/README.html
+    validations:
+      required: false
+  - type: input
+    id: contact
+    attributes:
+      label: Contact
+      description: GitHub handle for follow-up questions (optional)
+      placeholder: "@your-github-handle"
+    validations:
+      required: false

gxy_tool_bot-0.1.0/gxy_tool_bot/__init__.py

@@ -0,0 +1,3 @@
+"""gxy-tool-bot: Agentic bot that generates Galaxy tool wrappers from user requests."""
+
+__version__ = "0.1.0"