mloda-ai · TomKaltofen · May 6, 2026 · May 6, 2026 · May 6, 2026 · May 6, 2026
diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
@@ -0,0 +1,87 @@
+# Contributing to mloda-plugin-template
+
+Thanks for considering a contribution to the **template** repo itself. This document is for people who want to improve the scaffold (CI workflows, examples, dev tooling, docs) that downstream plugin authors will inherit.
+
+> **If you arrived here after clicking "Use this template" on GitHub:** this file does not apply to your new plugin repo. Follow the README's [Use this template](README.md#use-this-template) section, which includes a step that removes this file along with the other template-only community files.
+
+By participating in this project, you agree to abide by the [Code of Conduct](CODE_OF_CONDUCT.md).
+
+## Getting Started
+
+### Prerequisites
+
+- Python 3.10 or higher
+- [uv](https://docs.astral.sh/uv/) for dependency management
+- `tox` for running checks (installed via the dev extras)
+
+### Local Development Setup
+
+1. Fork the repository and clone your fork:
+
+```bash
+git clone https://github.com/<your-username>/mloda-plugin-template.git
+cd mloda-plugin-template
+```
+
+2. Create the virtualenv and install dependencies:
+
+```bash
+uv venv
+source .venv/bin/activate
+uv sync --all-extras
+```
+
+3. Verify your setup by running the full check suite:
+
+```bash
+tox
+```
+
+## Code Style
+
+`tox` is the gate. It runs:
+
+- `pytest` for tests
+- `ruff format --check --line-length 120` for formatting
+- `ruff check` for linting
+- `mypy --strict --ignore-missing-imports` for type checking
+- `bandit -c pyproject.toml -r -q` for security
+
+All of these must pass before a PR is mergeable. A separate `tox -e security` environment runs `pip-audit` for CVE scanning of installed dependencies.
+
+### Conventions
+
+- **Type hints**: use modern forms (`list[str]`, `dict[str, int]`, `X | None`).
+- **Line length**: 120.
+- **Tests**: every new feature or bug fix must come with tests; follow the patterns in `tests/` and `placeholder/.../tests/`.
+- **Commits**: use [Conventional Commits](https://www.conventionalcommits.org/) (`feat:`, `fix:`, `chore:`, `docs:`, `test:`, `refactor:`, `style:`, `ci:`, `build:`, `perf:`). semantic-release uses standard rules: `feat:` triggers a minor bump, all others trigger a patch (see `.releaserc.yaml`).
+- **No `Co-Authored-By` lines or other AI agent mentions** in commit messages or PR descriptions.
+
+## Pull Request Workflow
+
+1. Create a feature branch from `main`:
+
+```bash
+git checkout -b fix/short-description
+```
+
+2. Make your changes; run `tox` locally and confirm it passes.
+3. Commit using Conventional Commits format.
+4. Push to your fork and open a pull request targeting `main`.
+5. CI runs the full tox suite. All checks must pass before merge.
+
+## Reporting Issues
+
+Use the issue form at [.github/ISSUE_TEMPLATE/issue.yml](.github/ISSUE_TEMPLATE/issue.yml). It asks for a one-sentence summary, reproduction or motivation, optional code pointers, and an optional definition of done. See the **Issue Creation** section in [AGENTS.md](AGENTS.md) for more guidance.
+
+## Plugin Development vs. Template Contribution
+
+This repo is the **scaffold** for new mloda plugins, not a plugin itself. If you want to:
+
+- **Build a new plugin**: click "Use this template" on GitHub, then follow [docs/getting-started.md](docs/getting-started.md) and the README's [Use this template](README.md#use-this-template) section. The full plugin development walkthrough lives in [mloda-registry/docs/guides/](https://github.com/mloda-ai/mloda-registry/tree/main/docs/guides/).
+- **Contribute to the core framework**: see [mloda](https://github.com/mloda-ai/mloda).
+- **Contribute to community plugins**: see [mloda-registry](https://github.com/mloda-ai/mloda-registry).
+
+## License
+
+By contributing, you agree that your contributions will be licensed under the [Apache License, Version 2.0](LICENSE).
diff --git a/README.md b/README.md
@@ -6,15 +6,22 @@
 
 > **A GitHub template for creating standalone mloda plugins.** Part of the [mloda](https://github.com/mloda-ai/mloda) ecosystem for open data access. Visit [mloda.ai](https://mloda.ai) for an overview and business context, the [GitHub repository](https://github.com/mloda-ai/mloda) for technical context, or the [documentation](https://mloda-ai.github.io/mloda/) for detailed guides.
 
-Create your own FeatureGroups, ComputeFrameworks, and Extenders as standalone packages. See the [Getting Started guide](docs/getting-started.md) to create your repository, then follow the setup steps below.
+Create your own FeatureGroups, ComputeFrameworks, and Extenders as standalone packages. This repository serves two audiences:
+
+- **Plugin authors**: click *Use this template* on GitHub to scaffold a new plugin repository, then follow the [Use this template](#use-this-template) section below.
+- **Template contributors**: improving the scaffold itself? See [CONTRIBUTING.md](CONTRIBUTING.md) and the [Contribute to this template](#contribute-to-this-template) section.
 
 ## Related Repositories
 
 - **[mloda](https://github.com/mloda-ai/mloda)**: The core library for open data access. Declaratively define what data you need, not how to get it. mloda handles feature resolution, dependency management, and compute framework abstraction automatically.
 
 - **[mloda-registry](https://github.com/mloda-ai/mloda-registry)**: The central hub for discovering and sharing mloda plugins. Browse community-contributed FeatureGroups, find integration guides, and publish your own plugins for others to use.
 
-## Structure
+## Use this template
+
+Click *Use this template* on GitHub to scaffold a new plugin repository. See [docs/getting-started.md](docs/getting-started.md) for the GitHub template-creation walkthrough; once your repository is in place, follow the steps below to customize the scaffold for your organization.
+
+### Structure
 
 ```
 placeholder/
@@ -34,18 +41,14 @@ placeholder/
         └── my_extender.py
 ```
 
-## Key Files
+### Key files
 
-- `placeholder/` - Root namespace (users rename to company name)
-- `pyproject.toml` - Package config (users edit directly, not auto-generated)
+- `placeholder/` - Root namespace (rename to your organization's name)
+- `pyproject.toml` - Package config (edit directly, not auto-generated)
 - `.github/workflows/test.yml` - CI workflow running pytest
 
-## Common Tasks
-
 ### Setup Your Plugin
 
-Follow these steps to customize the template for your organization:
-
 #### 1. Rename the directory
 
 ```bash
@@ -56,18 +59,18 @@ mv placeholder acme
 
 Edit the following fields in `pyproject.toml`:
 
-- `name`: Change `"placeholder-my-plugin"` to `"acme-my-plugin"`
-- `authors`: Update name and email
-- `description`: Update to describe your plugin
-- `tool.setuptools.packages.find.include`: Change `["placeholder*"]` to `["acme*"]`
-- `tool.pytest.ini_options.testpaths`: Change `["placeholder", "tests"]` to `["acme", "tests"]`
+- `name`: change `"placeholder-my-plugin"` to `"acme-my-plugin"`
+- `authors`: update name and email
+- `description`: update to describe your plugin
+- `tool.setuptools.packages.find.include`: change `["placeholder*"]` to `["acme*"]`
+- `tool.pytest.ini_options.testpaths`: change `["placeholder", "tests"]` to `["acme", "tests"]`
 
 #### 3. Update .releaserc.yaml
 
 Edit the following fields in `.releaserc.yaml`:
 
-- `message`: Change `mloda-plugin-template` to your package name (e.g., `"chore(release acme-my-plugin): ${nextRelease.version}"`)
-- `repositoryUrl`: Change to your repository URL
+- `message`: change `mloda-plugin-template` to your package name (e.g., `"chore(release acme-my-plugin): ${nextRelease.version}"`)
+- `repositoryUrl`: change to your repository URL
 
 #### 4. Update Python imports
 
@@ -86,56 +89,33 @@ Update imports in these files (change `from placeholder.` to `from acme.`):
 uv venv && source .venv/bin/activate && uv sync --all-extras && tox
 ```
 
-### Development Setup with uv
+#### 6. Remove the template-only contributor guide
 
-**Install uv** (if not already installed):
-```bash
-curl -LsSf https://astral.sh/uv/install.sh | sh
-```
+`CONTRIBUTING.md` describes how to contribute to the template repo itself; it does not apply to your plugin. Remove it after `tox` passes:
 
-**Create virtual environment and install dependencies:**
 ```bash
-uv venv
-source .venv/bin/activate
-uv sync --all-extras
+rm CONTRIBUTING.md
 ```
 
-**Run all checks with tox:**
-```bash
-# Install tox with uv backend
-uv tool install tox --with tox-uv
+The remaining baseline files apply to your plugin out of the box and can be edited to match your conventions:
 
-# Run all checks (pytest, ruff, mypy, bandit)
-tox
-```
-
-### Run individual checks
-
-```bash
-# Tests only
-pytest
-
-# Format check
-ruff format --check --line-length 120 .
-
-# Lint check
-ruff check .
-
-# Type check
-mypy --strict --ignore-missing-imports .
-
-# Security check
-bandit -c pyproject.toml -r -q .
-```
+- `AGENTS.md` and `CLAUDE.md` — toolchain and project practices for the same `tox`/ruff/mypy/bandit pipeline you inherit. Tune the bullets if you change the toolchain.
+- `CODE_OF_CONDUCT.md` — short, plain-English baseline. Update the contact (`conduct@mloda.ai` → your address) if you want enforcement to come to you.
+- `.github/ISSUE_TEMPLATE/issue.yml` — unified issue form. Update the placeholder file paths to point at your renamed package.
 
-## Related Documentation
+You may also want to replace this `README.md` with one that describes your plugin.
 
-Guides for plugin development can be found in mloda-registry:
+### Where to next
 
-- https://github.com/mloda-ai/mloda-registry/tree/main/docs/guides/
+- **[mloda-registry/docs/guides/](https://github.com/mloda-ai/mloda-registry/tree/main/docs/guides/)** — full plugin development walkthrough (FeatureGroups, ComputeFrameworks, Extenders, packaging, publishing).
+- **[mloda](https://github.com/mloda-ai/mloda)** — core framework reference.
+- **[Claude Code skills](https://github.com/mloda-ai/mloda-registry/tree/main/.claude/skills/)** — pattern guidance and best practices for AI-assisted plugin development.
+- **[docs/github-workflows.md](docs/github-workflows.md)** — CI/CD setup and required secrets for the included workflows.
 
-Claude Code users can leverage the skills in mloda-registry for assisted plugin development:
+## Contribute to this template
 
-- https://github.com/mloda-ai/mloda-registry/tree/main/.claude/skills/
+This section is for people improving the scaffold itself (CI workflows, dev tooling, docs, examples). See [CONTRIBUTING.md](CONTRIBUTING.md) for the full contributor guide. Quick pointers:
 
-This template includes pre-configured GitHub Actions workflows for testing, security scanning, and automated releases. See the [GitHub Workflows documentation](docs/github-workflows.md) for setup instructions and required secrets.
+- [Code of Conduct](CODE_OF_CONDUCT.md)
+- [AGENTS.md](AGENTS.md) — agent guidance, project practices, issue creation
+- [Issue template](.github/ISSUE_TEMPLATE/issue.yml)
diff --git a/docs/getting-started.md b/docs/getting-started.md
@@ -49,3 +49,5 @@ Regardless of which option you chose, follow the setup steps in the [README](../
 4. Update `.releaserc.yaml` (change `mloda-plugin-template` to your package name and update `repositoryUrl`)
 5. Update Python imports
 6. Verify with `tox`
+7. Remove `CONTRIBUTING.md` — it describes contributing to the template repo, not your plugin
+8. Keep `CODE_OF_CONDUCT.md`, `AGENTS.md`, `CLAUDE.md`, and `.github/ISSUE_TEMPLATE/` as inherited baselines; tune them later (contact email, placeholder paths, toolchain bullets) if you want