docs: track examples via issues (claim + draft PR workflow) (#52)

## What & why

We're now tracking planned examples (internal and external) in GitHub
Issues. To make in-flight work visible and avoid duplication,
contributors should **comment on an issue to claim it** and **open a
draft PR that links the issue**. This PR surfaces that workflow
everywhere it's documented and adds a lightweight issue form to keep
proposals consistent.

Closes #<!-- process/meta change; no tracking issue -->

Changes:
- **New** `.github/ISSUE_TEMPLATE/example_proposal.yml` — lightweight
form (required Bucket + What & why, optional Opik-products multi-select)
with a claim/draft-PR note at the top.
- **New** `.github/ISSUE_TEMPLATE/config.yml` — keeps blank issues
enabled, links Opik docs.
- `CONTRIBUTING.md` — new step 1 (find/claim an issue) and a
draft-PR-linking-the-issue step; renumbered.
- `AGENTS.md` — claim-the-issue and open-a-linked-draft-PR bullets for
coding agents.
- `.github/pull_request_template.md` — explicit `Closes #` line +
"linked to its tracking issue" checklist item.
- `README.md` — points contributors to Issues to browse/claim/propose.

> Note: the issue form only renders once this is on `main`.

## Checklist

- [x] Docs/index updated where the workflow is surfaced
- [x] No credentials or `.env` files committed

Author: LeoRoccoBreedt

.github/ISSUE_TEMPLATE/config.yml

@@ -0,0 +1,5 @@
+blank_issues_enabled: true
+contact_links:
+  - name: 📚 Opik documentation
+    url: https://www.comet.com/docs/opik/
+    about: Product docs and API reference for Opik.

.github/ISSUE_TEMPLATE/example_proposal.yml

@@ -0,0 +1,53 @@
+name: 💡 Example proposal
+description: Propose a new Opik example, guide, integration, or utility script
+title: "[Example]: "
+labels: ["enhancement"]
+body:
+  - type: markdown
+    attributes:
+      value: |
+        Thanks for proposing an example! **Want to build it yourself?**
+        Comment on this issue to claim it, then open a **draft PR that links back here**
+        (`Closes #<this issue>`) so we can see it's in-flight.
+        See the [contributing guide](https://github.com/comet-ml/opik-examples/blob/main/CONTRIBUTING.md).
+  - type: dropdown
+    id: bucket
+    attributes:
+      label: Bucket
+      description: Which part of the repo would this live in?
+      options:
+        - Guide (how-to for an Opik workflow)
+        - Integration (add Opik to a framework/library)
+        - Use-case (end-to-end app using Opik)
+        - Utility script (automate/manage Opik resources)
+        - Chore (repo maintenance / CI)
+    validations:
+      required: true
+  - type: textarea
+    id: what-why
+    attributes:
+      label: What & why
+      description: What problem does this solve, and what should the example demonstrate?
+      placeholder: e.g. Show how to visualise multi-turn feedback scores to understand conversation trajectory.
+    validations:
+      required: true
+  - type: dropdown
+    id: opik-products
+    attributes:
+      label: Opik products / features involved
+      description: Select all that apply (optional).
+      multiple: true
+      options:
+        - Tracing / observability
+        - Datasets
+        - Experiments & evaluation (offline)
+        - Online evaluation (LLM-as-judge rules)
+        - Test suites
+        - Prompt optimization (Optimizer)
+        - Prompt library / versioning
+        - Annotation queues
+        - Feedback scores / human review
+        - Threads (multi-turn conversations)
+        - Metrics (built-in / custom)
+        - Guardrails
+        - Other / not sure

.github/pull_request_template.md

@@ -1,11 +1,14 @@
 ## What & why
 
-<!-- What does this PR change, and why? Link any related issue. -->
+<!-- What does this PR change, and why? -->
+
+Closes #<!-- the tracking issue this PR implements; comment on it to claim it before starting -->
 
 ## Checklist
 
 <!-- See CONTRIBUTING.md for details. Tick what applies; delete rows that don't. -->
 
+- [ ] Linked to its tracking issue (commented to claim it before starting)
 - [ ] Example is in the right bucket (`integrations` / `guides` / `use-cases` / `scripts`)
 - [ ] Folder name is `lowercase_with_underscores`
 - [ ] `README.md` has all required sections; index tables updated if examples were added/renamed/removed

AGENTS.md

@@ -68,6 +68,8 @@ Every example is a `uv` project: its `pyproject.toml` is the single source of tr
 - **Principles:** DRY, KISS, SOLID, YAGNI. Prefer reusing an existing helper over adding a new one.
 - **Type hints** on function signatures. Match the surrounding file's style, naming, and comment density.
 - **Git / PR safety:**
+  - **Claim the tracking issue before starting.** Work is tracked in [GitHub Issues](https://github.com/comet-ml/opik-examples/issues) — comment on the relevant issue to claim it before writing code. If none exists, ask the user whether to open one (via the *Example proposal* form).
+  - **Open a draft PR that links the issue early.** Right after cutting the branch, open a **draft** PR with `Closes #<issue>` in the body so in-flight work is visible; mark it ready for review only when complete.
   - Never `git commit` or `git push` on `main`/`master`. Cut a feature branch (`<user>/<topic>`, e.g. `fschlz/feature/...`), push there, open a PR, and let a human merge.
   - Commits follow **Conventional Commits**: `feat:`, `fix:`, `chore:`, `refactor:`, `docs:`.
   - Never `gh pr merge`, `gh pr close`, or `gh pr review --approve` — author/reviewer actions only. Blocked in [`.claude/settings.json`](.claude/settings.json).

CONTRIBUTING.md

@@ -12,15 +12,16 @@ Thank you for contributing. This repo is a reference library for Opik users —
 
 This is the loop we follow for non-trivial contributions. The slash-commands in brackets come from Claude Code plugins (see below) and are optional but recommended. **Start every contribution with `/brainstorming`** to agree on scope, and **finish by reviewing your own PR with `/review`** before asking a human.
 
-1. **Plan first.** Switch Claude Code to plan mode on the best available model with reasoning effort maxed before writing any code.
-2. **Brainstorm the scope** (`/brainstorming`) — agree on *what* to build before *how*.
-3. **Write the plan** (`/writing-plans`) — turn the agreed scope into an implementation plan.
-4. **Cut a feature branch** — `git switch -c <user>/<topic>` (never commit on `main`).
-5. **Implement and commit frequently** — small [Conventional Commits](https://www.conventionalcommits.org/) (`feat:`, `fix:`, `chore:`, `refactor:`, `docs:`).
-6. **Test and fix** — run the example in dry-run (and with credentials if you have them) until it works; `uv run ruff check .` is clean.
-7. **Update the READMEs** — the example's own README plus any index tables (see the [PR checklist](#pr-checklist)).
-8. **Open a PR with a description** — what changed and why. A human merges it.
-9. **Review your own PR** (`/review`) before requesting human review.
+1. **Find or open an issue, and claim it.** Planned examples are tracked in [GitHub Issues](https://github.com/comet-ml/opik-examples/issues). Pick one you want to build (or file one with the *Example proposal* form), then **comment on it to claim it** so we don't double up.
+2. **Plan first.** Switch Claude Code to plan mode on the best available model with reasoning effort maxed before writing any code.
+3. **Brainstorm the scope** (`/brainstorming`) — agree on *what* to build before *how*.
+4. **Write the plan** (`/writing-plans`) — turn the agreed scope into an implementation plan.
+5. **Cut a feature branch** — `git switch -c <user>/<topic>` (never commit on `main`).
+6. **Open a draft PR early that links the issue.** As soon as you branch, open a **draft** PR with `Closes #<issue>` in the description — this is how we track what's in-flight.
+7. **Implement and commit frequently** — small [Conventional Commits](https://www.conventionalcommits.org/) (`feat:`, `fix:`, `chore:`, `refactor:`, `docs:`).
+8. **Test and fix** — run the example in dry-run (and with credentials if you have them) until it works; `uv run ruff check .` is clean.
+9. **Update the READMEs** — the example's own README plus any index tables (see the [PR checklist](#pr-checklist)).
+10. **Mark the PR ready for review** with a description of what changed and why, then **review your own PR** (`/review`) before requesting human review. A human merges it.
 
 **Recommended Claude Code plugins:** `superpowers` (provides `/brainstorming`, `/writing-plans`, and `/review`) and `caveman` (terse output mode). Install `superpowers` from inside Claude Code:
 

README.md

@@ -69,4 +69,6 @@ Browse them in [community/](community/), or add your own via
 
 ## Contributing
 
+Planned examples are tracked in [Issues](https://github.com/comet-ml/opik-examples/issues) — browse open ones to see what's wanted, or propose your own with the **Example proposal** template. Comment to claim an issue before you start.
+
 See [CONTRIBUTING.md](CONTRIBUTING.md) for the contribution guide and example template.