Skip to content

Contribution Paths

Where can I help in 30 minutes, half a day, or one weekend?

CONTRIBUTING.md is the full setup-and-style reference. This page is the shortcut: pick the kind of help you want to give and jump straight to the relevant section, commands, and issue labels — without reading the whole repo first.

Every path below runs the same validation gate. Confirm your environment is healthy before you start:

pip install -e ".[dev]"
make ci        # fmt + lint + type + test + schemas-check + example + demo

Pick your path

I want to… Time Start here Issue labels
Improve docs 30 min Docs documentation, good first issue
Add an adapter 1 weekend Adapters enhancement, area/adapters
Add a benchmark scenario half a day Benchmarks area/eval
Improve adoption / growth half a day Adoption documentation, enhancement
Grab a good first issue 30 min–½ day Good first issue good first issue
Drive it with an AI assistant any AI assistant agent-friendly

I want to improve docs

The lowest-friction way in. Docs live under docs/ and the site is built with make docs (preview with make docs-serve at http://127.0.0.1:8000).

  • README clarity — tighten README.md; the first screen is the category pitch.
  • Recipes — add a copy-paste pattern to the Cookbook. Most recipes are runnable core-only code, so they don't bitrot; a few drive an external CLI as a subprocess for illustration (e.g. Recipe 7's safety gate) and document that they add no runtime dependency.
  • Integration pages — docs/integration_<framework>.md explains wiring a specific runtime. Use an existing page (e.g. MCP) as a template.
  • Troubleshooting examples — extend docs/troubleshooting.md with a concrete failure you hit and how you fixed it.

New pages must be added to the nav: block in mkdocs.yml. Look for the documentation and good first issue labels.

I want to add an adapter

Adapters convert between contextweaver's domain types and an external protocol or framework. The full checklist is in CONTRIBUTING § Adding a new adapter. In short:

  1. Implement src/contextweaver/adapters/<name>.py using the from_<protocol>(..., into=...) -> list[ContextItem] / to_<protocol>(items) -> payload convention.
  2. Re-export the public surface from adapters/__init__.py.
  3. Add tests/test_adapters_<name>.py covering both directions (round-trip where applicable).
  4. Add a worked examples/<name>_adapter_demo.py and wire it into the example: target in the Makefile.
  5. Add docs/integration_<name>.md and a row to the interop matrix in How contextweaver Fits.
  6. Never import the third-party SDK at module load — use guarded imports and put heavy dependencies under [project.optional-dependencies].

I want to add a benchmark scenario

The committed scorecard at benchmarks/scorecard.md is regenerated deterministically. Adding a scenario extends the gold dataset it reports on — see CONTRIBUTING § Adding a new benchmark scenario and docs/benchmarks.md "Known limits" for gaps worth measuring.

  1. Drop a JSONL file under benchmarks/scenarios/ (one ContextItem-shaped event per line).
  2. Target a specific behaviour the scorecard does not yet capture.
  3. Run make benchmark-matrix && make scorecard to regenerate, and commit both benchmarks/scorecard.md and benchmarks/results/latest.json.

I want to improve adoption / growth

Help adopters say "yes" faster.

  • Examples — add a deterministic, network-free script under examples/ (see CONTRIBUTING § Adding a new example script) and a row to the Examples table in README.md.
  • Demo assets — the contextweaver demo scenarios power README and docs hero content.
  • Comparison pages — sharpen Where it fits and the Ecosystem Map so readers can place contextweaver in their stack.
  • Honest limitations — the Launch Kit sets the responsible-claims guardrails; keep new copy inside them.

I want a good first issue

good first issue items are scoped to roughly one file or one module, with explicit acceptance criteria and no deep architectural context required.

Comment on the issue first so it can be assigned to you — that avoids duplicate work. A good first contribution in this repo:

  • touches a single module and keeps it ≤ 300 lines;
  • adds or updates a test for every changed public function;
  • updates CHANGELOG.md under ## [Unreleased];
  • passes make ci locally before the PR is opened.

I am using an AI coding assistant

contextweaver is friendly to AI coding agents (Claude Code, GitHub Copilot Agent Mode, Codex, …). Load these first, in order:

  1. AGENTS.md — module map, conventions, and pipeline summary (the single source of truth).
  2. .claude/CLAUDE.md and .github/copilot-instructions.md — assistant-specific operating overlays.
  3. llms.txt / llms-full.txt — machine-readable repo summary.

Then follow the same rules everyone else does: no print() in library code, no business logic in __init__.py, every public function gets a test, and make ci is the gate. Tasks tagged agent-friendly are scoped for end-to-end agent work.