Skip to content

Codebase intelligence for AI and humans: code health scores, auto-generated docs, git analytics, dead code detection, and architectural decisions via MCP.

docs: onboard contributors through repowise itself, trim README badges (#1110)

Raghav Chamadiya1bf54bf6ed5d
diff --git a/.github/CONTRIBUTING.md b/.github/CONTRIBUTING.md
index e74ac7c21..5a021b199 100644
--- a/.github/CONTRIBUTING.md
+++ b/.github/CONTRIBUTING.md
@@ -34,6 +34,79 @@ uv run repowise --version
uv run pytest tests/unit/
```
+## Getting oriented
+
+This is a ~3,000 file codebase, and reading it front to back is not the plan. Repowise
+exists to make that unnecessary, so use it on itself.
+
+### Without installing anything
+
+We keep a public, always-fresh index of this repository at
+**[repowise.dev/repo/repowise-dev/repowise](https://repowise.dev/repo/repowise-dev/repowise)**.
+It re-indexes on every push. Pick the tab that matches your question:
+
+| Your question | Where to look |
+|---|---|
+| What are the moving parts? | [Overview](https://repowise.dev/repo/repowise-dev/repowise/overview) and [Architecture](https://repowise.dev/repo/repowise-dev/repowise/architecture) |
+| Where does this symbol live? | [Files](https://repowise.dev/repo/repowise-dev/repowise/files) |
+| Which files are dangerous to touch? | [Code Health](https://repowise.dev/repo/repowise-dev/repowise/code-health), and the hotspot table on the landing page |
+| Who knows this area? | [People & History](https://repowise.dev/repo/repowise-dev/repowise/owners) |
+| Why is it built this way? | [Decisions](https://repowise.dev/repo/repowise-dev/repowise/decisions) |
+| What changed recently, and how risky was it? | [Commits](https://repowise.dev/repo/repowise-dev/repowise/commits) |
+
+### Locally, with your agent
+
+Better still, index this repo with the tool you are contributing to. It is free, needs
+no API key, and takes a couple of minutes:
+
+```bash
+uv run repowise init --no-prose -y # graph, git history, health, decisions. No LLM, no spend.
+uv run repowise serve # dashboard + MCP server on localhost
+```
+
+Then point your coding agent at the MCP server (see the
+[Quickstart](../README.md#quickstart-under-5-minutes-no-api-key) for Claude Code, Codex
+and others) and ask it questions directly:
+
+```
+get_context for packages/core/src/repowise/core/pipeline/orchestrator.py
+get_why "why is doc generation split from ingestion?"
+```
+
+If something about this experience is bad, that is a bug worth reporting. Contributors
+are the only people who use repowise on repowise with fresh eyes.
+
+### Then read
+
+- [docs/architecture/](../docs/architecture/README.md) for the written architecture
+- [docs/layers/INTELLIGENCE_LAYERS.md](../docs/layers/INTELLIGENCE_LAYERS.md) for what
+ each of the five layers computes and where its code lives
+- [docs/reference/CLI_REFERENCE.md](../docs/reference/CLI_REFERENCE.md) for every
+ command and flag
+
+## Looking for something to work on
+
+- **[Good first issues](https://github.com/repowise-dev/repowise/labels/good%20first%20issue)** on the tracker.
+- **[The refactoring backlog](https://repowise.dev/repo/repowise-dev/repowise/refactoring).**
+ Repowise ranks its own concrete refactoring plans (Extract Class, Split File, Break
+ Cycle, and so on) with the blast radius attached. Each card has a copy-to-agent
+ button. Picking one off that list is a genuinely useful contribution, and it is the
+ fastest way to learn how the health layer thinks.
+- **Language support.** Adding a language is one `.scm` query file and one config entry.
+ See [docs/layers/LANGUAGE_SUPPORT.md](../docs/layers/LANGUAGE_SUPPORT.md).
+
+Before you start, check the file you are about to edit:
+
+```bash
+uv run repowise health --file <path> # score, markers, findings
+uv run repowise risk HEAD # or ask get_risk from your agent
+```
+
+Some files in this repo are bug magnets: high churn, a long run of prior fixes, often a
+bus factor of one. The
+[hotspot table](https://repowise.dev/repo/repowise-dev/repowise/code-health) names the
+current ones. Changes there are welcome, but expect closer review and bring tests.
+
## Development Workflow
1. **Fork** the repository
@@ -48,7 +121,17 @@ uv run pytest tests/unit/
npm run lint
npm run type-check
```
-5. **Push** to your fork and open a **Pull Request** against `main`
+5. **Check your own change** with the tool you are contributing to:
+ ```bash
+ uv run repowise risk main..HEAD # 0-10 defect score, plus will_break,
+ # missing_cochanges and missing_tests
+ uv run repowise impacted-tests --staged # the tests your diff actually exercises
+ uv run repowise health --file <path> # did the file you touched get worse?
+ ```
+ None of this is a gate, and none of it calls an LLM. It is the same signal the
+ reviewer will be looking at, and running it yourself catches the boring problems
+ (a forgotten companion file, an untested hotspot) before anyone else has to.
+6. **Push** to your fork and open a **Pull Request** against `main`
## Branch Naming
diff --git a/README.md b/README.md
index 62897a7e6..ea731efc5 100644
--- a/README.md
+++ b/README.md
@@ -6,16 +6,14 @@
<p align="center">
<a href="https://www.repowise.dev"><img src="https://img.shields.io/badge/LIVE_DEMO-repowise.dev-F59520?style=for-the-badge&labelColor=0A0A0A" alt="Live demo: repowise.dev" /></a>
- <a href="https://github.com/repowise-dev/repowise"><img src="https://img.shields.io/badge/Star_this_repo-1E293B?style=for-the-badge&logo=github&logoColor=white&labelColor=0A0A0A" alt="Star repowise on GitHub" /></a>
</p>
<p align="center">
<a href="https://repowise.dev/repo/repowise-dev/repowise"><img src="https://api.repowise.dev/badge/wiki/repowise-dev/repowise.svg?style=for-the-badge" alt="repowise: explore code" /></a>
<a href="https://repowise.dev/repo/repowise-dev/repowise/code-health"><img src="https://api.repowise.dev/badge/health/repowise-dev/repowise.svg?style=for-the-badge" alt="Code health" /></a>
+ <a href="https://github.com/repowise-dev/repowise/actions/workflows/ci.yml"><img src="https://img.shields.io/github/actions/workflow/status/repowise-dev/repowise/ci.yml?branch=main&style=for-the-badge&label=CI&labelColor=0A0A0A" alt="CI status" /></a>
<a href="https://pypi.org/project/repowise/"><img src="https://img.shields.io/pypi/v/repowise?style=for-the-badge&color=1E293B&labelColor=0A0A0A&logo=pypi&logoColor=white" alt="PyPI version" /></a>
<a href="https://www.gnu.org/licenses/agpl-3.0"><img src="https://img.shields.io/badge/License-AGPL--v3-059669?style=for-the-badge&labelColor=0A0A0A" alt="License: AGPL v3" /></a>
- <a href="https://pypi.org/project/repowise/"><img src="https://img.shields.io/badge/Python-3.11%2B-1E293B?style=for-the-badge&labelColor=0A0A0A&logo=python&logoColor=white" alt="Python 3.11+" /></a>
- <a href="https://modelcontextprotocol.io"><img src="https://img.shields.io/badge/MCP-compatible-1E293B?style=for-the-badge&labelColor=0A0A0A" alt="MCP compatible" /></a>
<a href="https://github.com/repowise-dev/repowise/stargazers"><img src="https://img.shields.io/github/stars/repowise-dev/repowise?style=for-the-badge&logo=github&color=1E293B&labelColor=0A0A0A&logoColor=white" alt="GitHub stars" /></a>
</p>
@@ -574,6 +572,13 @@ uv run repowise --version
uv run pytest tests/unit/
```
+New here? You do not have to read 3,000 files to start. We keep a public index of this
+repo built by repowise itself, re-indexed on every push:
+[**explore repowise with repowise →**](https://repowise.dev/repo/repowise-dev/repowise)
+(architecture, hotspots, ownership, decisions, and a ranked
+[refactoring backlog](https://repowise.dev/repo/repowise-dev/repowise/refactoring) you
+are welcome to pick from).
+
Full guide, including how to add languages and LLM providers:
[CONTRIBUTING.md](.github/CONTRIBUTING.md) · architecture:
[docs/architecture/](docs/architecture/README.md)