Add CLAUDE.md with build commands and architecture overview

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

Author: jmchilton

CLAUDE.md

@@ -0,0 +1,51 @@
+# CLAUDE.md
+
+This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
+
+## Common commands
+
+All `make` targets assume `.venv` exists. Bootstrap once with `make setup-venv` (creates `.venv`, installs `requirements.txt` + `dev-requirements.txt`).
+
+- `make test` — full pytest run (slow; downloads Galaxy + deps)
+- `make quick-test` — skips slow + Galaxy tests via `PLANEMO_SKIP_SLOW_TESTS=1 PLANEMO_SKIP_GALAXY_TESTS=1`
+- `make lint` — runs `tox -e lint` (flake8 + black --check + isort --check + ruff)
+- `make format` — apply ruff format + isort + black (line length 120)
+- `make tox ENV=py37-unit ARGS='--tests tests/test_x.py'` — single-file or single-test runs
+- Single test directly: `pytest tests/test_foo.py::TestClass::test_method` (after sourcing `.venv`)
+- `make docs` / `make open-docs` — Sphinx HTML build (requires `make ready-docs` first, which regenerates `commands.rst` from CLI introspection)
+- `make release` — full release flow; prefer the `/ready-release` slash command which wraps it with safety checks
+
+Test markers: `tests_galaxy_branch` (gated by `PLANEMO_TEST_GALAXY_BRANCH`). Skip envvars: `PLANEMO_SKIP_SLOW_TESTS`, `PLANEMO_SKIP_GALAXY_TESTS`, `PLANEMO_SKIP_GALAXY_CLIENT_TESTS`, `PLANEMO_SKIP_REDUNDANT_TESTS`, `PLANEMO_SKIP_SHED_TESTS`.
+
+`pytest.ini` ignores `planemo/commands/cmd_test.py` (would self-discover as test).
+
+## Architecture
+
+Planemo is a CLI toolkit (entrypoint `planemo.cli:planemo`) for Galaxy and CWL tool/workflow development. The CLI is built on Click with a custom `MultiCommand` that auto-discovers subcommands.
+
+**Command discovery (`planemo/cli.py`)**: Every file `planemo/commands/cmd_<name>.py` exporting a `cli` function becomes the subcommand `planemo <name>`. There are ~70 commands. Aliases live in `COMMAND_ALIASES` (`l`→`lint`, `t`→`test`, `s`→`serve`, `o`→`open`). To add a command, drop a new `cmd_*.py` — no registration needed. `command_function` decorator handles profile-based option blending and translates `ExitCodeException` into `sys.exit`.
+
+**Context (`planemo/context.py`, extended in `cli.py`)**: `PlanemoCliContext` carries config, workspace dir, verbosity, option-source tracking. Passed to every command via `@pass_context`.
+
+**Runnables (`planemo/runnable.py`)**: Central abstraction over things that can be run/tested/linted. `RunnableType` enum covers `galaxy_tool`, `galaxy_datamanager`, `galaxy_workflow`, `cwl_tool`, `cwl_workflow`, `directory`. `runnable_resolve.py` turns CLI paths/URIs (including `gxid://`, `trs://`) into `Runnable` objects.
+
+**Engines (`planemo/engine/`)**: `Engine` ABC in `interface.py` with `run`/`test`/`cleanup`. Implementations: `galaxy.py` (downloads/serves Galaxy), `cwltool.py`, `toil.py`. `factory.py` selects engine based on runnable type and CLI flags. The `test` engine wraps another engine and structures results.
+
+**Galaxy integration (`planemo/galaxy/`)**: Largest subsystem. `config.py` builds Galaxy configs; `serve.py`/`run.py` start/run Galaxy; `api.py` wraps bioblend; `workflows.py` parses/describes workflows; `invocations/` tracks workflow runs; `test/` formats Galaxy test results into planemo's report format.
+
+**Linting**: Two parallel systems — tools (`tool_lint.py` + `linters/`, integrating with `galaxy.tool_util.lint`) and workflows (`workflow_lint.py`). Both invoked via `planemo lint`.
+
+**Tool Shed (`planemo/shed/`)**: Upload/download/diff repositories against the Galaxy Tool Shed.
+
+**Reports (`planemo/reports/`)**: Jinja templates for HTML/Markdown test output (`tool_test_output.html`).
+
+## Code style
+
+- Line length 120 (black, ruff, flake8 all aligned)
+- `pyproject.toml` ruff config selects `E`/`W`/`F` only — match flake8 default
+- mypy runs via `tox -e mypy`; many modules are not yet typed
+- `planemo/autopygen/` is excluded from ruff (legacy)
+
+## Release flow
+
+Version lives in `planemo/__init__.py` (`__version__`). The `/ready-release` Claude slash command (`.claude/commands/ready-release.md`) walks the steps: clean status check, version confirmation, `make add-history`, `make lint`, then `make release` (which chains `commit-version` + `new-version` + `check-dist` + `push-release`). The `UPSTREAM` Make variable defaults to `galaxyproject` — must be a configured remote before `push-release` runs.