continuum-code 0.2.1
Rule engine so coding agents obey repo rules (block/warn/ask) with clear explanations.
Requires Python: >=3.10

# Continuum

Rule engine so coding agents **obey repo rules** across Cursor, Claude, and ChatGPT: they get **blocked**, **warned**, or **asked** before breaking rules, with clear explanations of which rule fired and how to fix.

## v0.1 promise

- Add `continuum.yaml` to your repo.
- Run `continuum check` locally and in CI.
- Cursor (MCP) agents are gated: **blocked** / **warned** / **clarification_required** before breaking rules.
- The system **explains** which rule fired and how to fix it.

## Install

```bash
pip install -e .   # from repo
# or when published:
pip install continuum-code
```

Requires Python 3.10+. The CLI is installed as **`continuum`**. If another tool named `continuum` is in your PATH, use **`continuum-code`** instead (e.g. `continuum-code --version`, `continuum-code init --pack data-dbt-airflow`), or run **`python -m continuum`**.

### Development on Windows (WSL2)

Keep the repo on the WSL filesystem (e.g. `~/repos/continuum`) for best compatibility.

**One-time (PowerShell as Admin):**

```powershell
wsl --install -d Ubuntu-24.04
```

After WSL install, open Ubuntu and run:

```bash
# Base (keep repo under WSL, e.g. ~/repos/continuum)
sudo apt update && sudo apt install -y build-essential git curl

# Python via uv (fast, clean venvs)
curl -LsSf https://astral.sh/uv/install.sh | sh
source ~/.local/bin/env  # or restart shell
```

**Per clone (inside WSL, in repo root):**

```bash
cd ~/repos/continuum   # or your path
uv venv
source .venv/bin/activate
uv pip install -e ".[dev]"
```

**Run tests:**

```bash
pytest
```

**Run CLI:**

```bash
continuum check
continuum init --pack python-fastapi
```

For a broader Windows + WSL2 dev setup (Terminal, Docker, Antigravity safety), see your preferred guide.

## Quick start

```bash
# Create config (optional: use a pack)
continuum init
continuum init --pack python-fastapi   # or node-backend, typescript-monorepo

# Check current changes (git diff)
continuum check
continuum check --staged              # only staged
continuum check --base origin/main    # diff against branch

# Explain why a rule fired
continuum explain
continuum explain ban_lodash

# List active contracts
continuum inspect
```

## Config: `continuum.yaml`

```yaml
version: 0.1
scopes:
  - id: repo
    match: ["**/*"]
    contracts:
      - type: ban
        id: ban_lodash
        match:
          deps: ["lodash"]
        message: "Use native JS or approved utils."
      - type: ask_first
        id: confirm_migrations
        match:
          paths: ["**/migrations/**"]
        prompt: "Touching migrations. Confirm: (A) add-only (B) destructive (C) refactor"
  - id: backend
    match: ["backend/**"]
    precedence: 10
    contracts:
      - type: require
        id: require_tests
        match:
          paths: ["backend/**"]
        require:
          - kind: tests
            hint: "Add or adjust unit tests for changed modules."
```

Contract types: **ban** (deps/paths/commands), **require** (tests/logging/ADR), **ask_first** (confirmation gate), **define** (metadata).

## Escape hatch

To skip checks (e.g. emergency hotfix), set `CONTINUUM_SKIP=1`; `continuum check` will exit 0 without running contracts. Prefer adjusting rules (e.g. `severity: warn`) in `continuum.yaml` when possible. See [docs/adoption.md](docs/adoption.md).

## CI (GitHub Action)

```yaml
- uses: actions/checkout@v4
  with:
    fetch-depth: 0
- uses: ./actions/continuum-check
  with:
    base_ref: ${{ github.event.pull_request.base.sha }}
```

Or in another repo: `uses: your-org/continuum/actions/continuum-check@v0.1` (and install `continuum` via pip in the action).

## Cursor / MCP

Run the MCP server so the Cursor agent can call `continuum_check` before applying changes:

```bash
continuum mcp --transport stdio
```

Add to Cursor MCP config:

```json
{
  "mcpServers": {
    "continuum": {
      "command": "continuum",
      "args": ["mcp", "--transport", "stdio"]
    }
  }
}
```

See [docs/cursor-mcp.md](docs/cursor-mcp.md) and [docs/demo.md](docs/demo.md) for setup and the “Refactor auth middleware” demo.

**Golden demo:** Run the 3 scenarios in [demo/README.md](demo/README.md) (dbt marts require, airflow ask-first, banned command) in under 10 minutes.

## Packs

Starter configs:

- **node-backend** – Node/JS backend (ban lodash, require tests, ask on migrations).
- **python-fastapi** – FastAPI app (ban requests in favor of httpx, require tests, ask on migrations).
- **typescript-monorepo** – TS monorepo (ban lodash, require tests in packages).
- **data-dbt-airflow** – dbt + Airflow repos (ask_first on marts/DAGs, require tests on marts, ban risky commands).

```bash
continuum init --pack python-fastapi
continuum init --pack data-dbt-airflow   # dbt + Airflow
```

### 5-minute adoption (dbt + Airflow)

1. `pip install continuum-code` (or `pip install -e .` from repo).
2. `continuum init --pack data-dbt-airflow` → writes `continuum.yaml`.
3. `continuum validate` → confirm the file is valid.
4. `continuum check` (or `continuum check --base origin/main` for PRs).
5. Add the GitHub Action for CI; optionally run `continuum mcp --transport stdio` for Cursor.

## Next steps (after v0.1)

- Richer dependency detection (poetry, pnpm, pip-tools).
- Pattern bans (regex on diffs).
- Stricter “require” checks (e.g. tests touched when src touched).
- Decision diffs / supersession (v0.2).

## License

MIT.