# Continuous Code Guardian

AI-powered continuous code assistant for **Cursor IDE**, **VS Code**, **Antigravity**, and **Claude Code** via MCP.

## Overview

![Cover — Code Assistant](./docs/presentation/00-cover-code-assistant.png)

![Architecture](./docs/presentation/01-architecture.png)

![Features](./docs/presentation/02-features.png)

![How to use](./docs/presentation/03-how-to-use.png)

![Advantages of continuous guardianship](./docs/presentation/04-advantages-continuous.png)

![Problem and solution](./docs/presentation/05-problem-solution.png)

![Scorecards and proceed gates](./docs/presentation/06-scorecards-proceed.png)

![Demo journey](./docs/presentation/07-demo-journey.png)

![Tool boundaries](./docs/presentation/08-tool-boundaries.png)

![Guardian loop details](./docs/presentation/09-guardian-loop-details.png)

![Closing summary](./docs/presentation/10-closing-summary.png)

![Multi-client MCP](./docs/presentation/11-multi-client-mcp.png)

![Supported languages](./docs/presentation/12-supported-languages.png)

Focused public surface:

- **`/ca-checkit`** — evidence-ranked advisor (`routing_cues` + urgent|optional recommendations) → confirm subset (default prefers urgent) → run selected children (`ca-aurait` is never recommended; run it separately)
- **`/ca-smellit`** — quality-depth + architecture/clean-code prompt (ranked `smell_scorecard`, severity order) → proceed → apply → post-apply ran/skipped gate (for Sonar/CI gate prep use `/ca-sonarit`)
- **`/ca-testit`** — gap scorecard → merge/append into related non-empty tests when appropriate → ran/skipped verify (≤1 fix) → conditional coverit handoff for coverage focus or local misses
- **`/ca-commentit`**, **`/ca-docit`**, **`/ca-smellit`** — lightweight JS/TS export, JSDoc, surface, and smell heuristics (not full AST analysis)
- **`/ca-docit`** — structured companion markdown (canonical outline + API extract + drift scorecard) under `docs/` → reconcile or report in sync (no comment edits)
- **`/ca-coverit`** — coverage readiness → local Cobertura/JSON/LCOV/Clover/Istanbul evidence when present → source-first proceed → source then tests → agent measure→iterate toward goal
- **`/ca-sonarit`** — Sonar/CI gate-prep helper → local SARIF/Sonar/GitLab/ESLint report evidence → source-first prompt → proceed → source then tests → optional report-driven improve→recheck (≤3 rounds; not a gate pass)
- **`/ca-aurait`** — Cognite Flows design-quality helper → scored prompt → confirm → apply design fixes

## Polyglot support

All context packs accept UTF-8 text source files through an open suffix matrix. Go, Java, C#, and Dart have named heuristics; C++ and Scala have light heuristics; unknown but source-like files use the `other` generic profile. Flutter is detected as Dart and receives Flutter test/coverage guidance. These are advisory heuristics, not compiler or language-server analysis; see the [Feature 026 quickstart](./specs/026-polyglot-language-support/quickstart.md).

## Install

For end users installing this MCP into Cursor, VS Code, Antigravity, or Claude Code (Git, PyPI/`uvx`, local, or binary), see **[INSTALLATION.md](./INSTALLATION.md)**.

Contributor / local editable install:

```bash
python -m pip install -e ".[dev]"
cp guardian.config.example.yaml guardian.config.yaml
```

Requires Python 3.12+. Optional analyzer CLIs (Ruff, ESLint, Semgrep, …) are only used when tools run with `analyzer_mode=lint` or `all`.

## MCP tools

| Tool (slash) | Purpose |
|--------------|---------|
| `/ca-checkit` | Advisor: evidence-ranked plan from file cues → ask which to run (default prefers urgent) → invoke selected children; never recommends `/ca-aurait` |
| `/ca-smellit` | Quality-depth + architecture/clean-code prompt (`smell_scorecard`) → proceed → apply → post-apply ran/skipped gate; hand off Sonar/CI gate prep to `/ca-sonarit` |
| `/ca-testit` | Gap scorecard → focused-complete unit tests → ran/skipped verify (≤1 fix); coverit handoff for coverage goals |
| `/ca-commentit` | Ranked `comment_scorecard` → targeted comment plan (≤10) → proceed when non-empty → in-source comments only (no blanket refresh; not companion docs) |
| `/ca-docit` | Structured companion markdown (`outline_contract` + `api_surface_extract` + `doc_drift_scorecard`) under local `docs/` with CAPITAL basename; in-sync skip rewrite; no comment edits |
| `/ca-coverit` | Coverage readiness → aspire-high + 80% floor → proceed → source then tests → agent measure→iterate (bounded rounds; MCP does not run coverage) |
| `/ca-sonarit` | Sonar/CI gate-prep helper (not Sonar / not gate-pass) → source-first prompt → proceed → source then tests → optional report-driven iterate (≤3 rounds; MCP does not run Sonar) |
| `/ca-aurait` | Flows design-quality helper → scored prompt (Q1–Q10 / 3.8+) → ask proceed → apply listed design fixes |

How to use them in Cursor, VS Code, Antigravity, or Claude Code: **[HOW_TO_USE_TOOLS.md](./HOW_TO_USE_TOOLS.md)**.

Slash autocomplete (`/ca…`) is installed **automatically** into the workspace —
`.cursor/commands/` in Cursor, `.github/prompts/` in VS Code, `.agent/workflows/` in
Antigravity, `.claude/commands/` in Claude Code — when the MCP server starts (requires
`"cwd": "${workspaceFolder}"` in `mcp.json`, where supported). Obsolete older `/ca-*`
shortcut files are removed on install, independently per editor.

## Configuration

See `guardian.config.example.yaml`. Local `guardian.config.yaml` and `.code-guardian/`
are gitignored.

- `smellit_max_excerpt_bytes` / `testit_max_excerpt_bytes` / `commentit_max_excerpt_bytes` / `docit_max_excerpt_bytes` / `coverit_max_excerpt_bytes` / `sonarit_max_excerpt_bytes` / `aurait_max_excerpt_bytes` (default `65536`)
- `coverit_max_report_bytes` / `sonarit_max_report_bytes` (default `65536`); `sonarit_max_related_files` (default `4`)
- `smellit_analyzer_mode` / `testit_analyzer_mode` / `commentit_analyzer_mode` / `docit_analyzer_mode` / `coverit_analyzer_mode` / `sonarit_analyzer_mode` / `aurait_analyzer_mode` (default `none` = fast)
- Optional `analyzers:` toggles for when `analyzer_mode` is `lint` or `all`
- Invalid config returns `CONFIG_INVALID` without leaking secrets

## Validation

- Commentit scorecard & proceed gate: `specs/021-commentit-scorecard-gate/quickstart.md`
- Sonarit report-driven iterate: `specs/020-sonarit-report-iterate/quickstart.md`
- Smellit: `specs/016-smellit-quality-depth/quickstart.md` (also `specs/013-smellit-architecture-refactor/quickstart.md`)
- Testit: `specs/017-testit-verify-loop/quickstart.md` (also `specs/004-testit-unit-tests/quickstart.md`)
- Commentit / Docit split: `specs/010-commentit-docit-split/quickstart.md`
- Coverit iterate coverage: `specs/015-coverit-iterate-coverage/quickstart.md`
- Coverit max coverage: `specs/014-coverit-max-coverage/quickstart.md`
- Coverit / Sonarit source prep: `specs/012-coverit-sonarit-source-prep/quickstart.md`
- Aurait: `specs/008-aurait-design-quality/quickstart.md`

```bash
pytest -q
```

## Spec Kit docs

- Feature 021: `specs/021-commentit-scorecard-gate/`
- Feature 020: `specs/020-sonarit-report-iterate/`
- Feature 017: `specs/017-testit-verify-loop/`
- Feature 016: `specs/016-smellit-quality-depth/`
- Feature 015: `specs/015-coverit-iterate-coverage/`
- Feature 014: `specs/014-coverit-max-coverage/`
- Feature 013: `specs/013-smellit-architecture-refactor/`
- Feature 012: `specs/012-coverit-sonarit-source-prep/`
- Feature 008: `specs/008-aurait-design-quality/`
- Feature 007: `specs/007-coverit-coverage-prep/`
- Feature 004: `specs/004-testit-unit-tests/`
- Feature 003: `specs/003-smellit-cleanup-prompt/`