Codebase intelligence for AI and humans: code health scores, auto-generated docs, git analytics, dead code detection, and architectural decisions via MCP.
Python aicode-complexitycode-healthcode-intelligencecode-qualitydead-codedeveloper-toolsdocumentationgit-analyticsmcpopen-sourcepythonrefactoringstatic-analysistechnical-debt
docs: onboard contributors through repowise itself, trim README badges (#1110)
Raghav Chamadiya1bf54bf6ed5d
diff --git a/.github/CONTRIBUTING.md b/.github/CONTRIBUTING.mdindex e74ac7c21..5a021b199 100644--- a/.github/CONTRIBUTING.md+++ b/.github/CONTRIBUTING.md@@ -34,6 +34,79 @@ uv run repowise --versionuv 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 Workflow1. **Fork** the repository@@ -48,7 +121,17 @@ uv run pytest tests/unit/npm run lintnpm 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 Namingdiff --git a/README.md b/README.mdindex 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 --versionuv 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)