V2 rewrite in progress: the previous repository-monitoring and issue-feed prototype has been retired. The current branch is a deliberately small foundation, not a usable recommender yet.
Contribution Compass is becoming a personalized OSS investment recommender. It will help a serious engineer decide which few open-source projects deserve the next several months of their attention, given their background, desired growth, career goals, and the project’s ability to absorb outside contributors.
Product rule: project first, issue second. Concrete GitHub issues become calls to action only after their repository has been judged worth a sustained investment.
Read the authoritative product and architecture specification.
developer profile
→ semantic and dependency neighborhood
→ candidate discovery
→ evidence collection
→ hard taste floors
→ Fit / Absorption / Upside
→ Pareto shortlist and diverse portfolio
→ 2–4 concrete issues per recommended project
The final output should feel like:
These are the few open-source projects where your next six months of effort are most likely to teach you something, matter to the community, and strengthen your engineering career—and here is the evidence.
The August 2026 reset removed the v1 product model and all generated v1 artifacts:
- fixed repository groups and Project Sensors;
- daily Signals, full snapshots, Observation Events, state, and reports;
- Contribution Lead and Triage Lead scoring;
- Hacker News, news feeds, RSS, catalog overlays, and browser-only personalization;
- catalog-shaped CLI and MCP tools;
- the scheduled collector that would otherwise regenerate obsolete output.
The retained foundation is intentionally narrow:
- Python 3.12,
uv, Ruff, mypy, and pytest; - domain/application/adapter/controller/view separation;
- bounded GitHub transport and pagination;
- dependency-manifest parsing and package-to-repository resolution;
- Jinja2 static publication and GitHub Pages;
- an MCP transport entry point with a rewrite-status resource;
- GitHub Actions CI;
- evidence/measurement/taste separation as an architectural invariant.
Requirements: Python 3.12+ and uv.
uv sync --all-extras
uv run ruff check .
uv run ruff format --check .
uv run mypy src
uv run pytest
uv run contribution-compass siteThe generated reset page is written to .site/. No model credential is required. Future GitHub
profile, discovery, and evidence commands will use GITHUB_TOKEN.
src/contribution_compass/
domain/ factual, transport-independent concepts
application/ recommendation use cases as they are validated
ports.py seams introduced only when real adapters vary
adapters/ GitHub, manifests, and package registries
controllers/ CLI and MCP transports
views/ packaged Jinja2 static presentation
The intended v2 domain is described in CONTEXT.md. Architectural decisions live in docs/adr.
The rewrite is validation-first. Please read CONTRIBUTING.md and discuss a task before implementing a broad feature. The first milestone is proving project evaluation quality—not maximizing repositories indexed or commands shipped.
MIT—see LICENSE. Some retained GitHub and dependency-discovery patterns originated in or were adapted during work based on the MIT-licensed agents-radar; see NOTICE.md.