code-governance

Stop spaghetti imports. Enforce module boundaries in Python and TypeScript.

Before / After

Setup

Option 1: With Claude Code (recommended)

Install the plugin — Claude handles everything interactively. Run each command separately — pasting them all at once will concatenate into a single broken URL:

/plugin marketplace add useparadigm/code-governance-plugin

/plugin install code-governance

/reload-plugins

Then run:

/governance-init

Without /reload-plugins, the new commands won't be registered yet and /governance-init will fail with Unknown command.

What happens:

1. Claude installs code-governance in your project
2. Scans your codebase — discovers modules, maps every import
3. Shows you the dependency map: "I found 8 modules. api imports from db directly — should it?"
4. You discuss architecture: which dependencies are intentional, which are spaghetti
5. Claude creates governance.toml based on your answers
6. Enables rules: no_cycles, enforce_cannot_depend_on, optionally enforce_layers
7. If existing violations: "Want a baseline? I'll accept these and only fail on new ones."
8. Sets up GitHub Actions — CI check on every PR + /governance fix command
9. Done. Every PR is now gated on architecture rules.

After setup, two more commands available:

Option 2: Manual

pip install code-governance

Quick scan — no config needed, instant results:

$ governance-ast --auto src/

Governance Report (python)
Modules: 8 | Files scanned: 47

Violations (1):
  [E] [no_cycles] Circular dependency: payments -> notifications -> payments

FAILED

Works on TypeScript too — language auto-detected from source:

$ governance-ast --auto src/

Governance Report (typescript)
Modules: 6 | Files scanned: 82
...

.ts, .tsx, .js, .jsx, .mts, .cts, .mjs, .cjs all supported. tsconfig.json path aliases (@/*, extends chains) are honored.

Full setup — generate config, review, enforce:

# Generate config: detect modules + seed cannot_depend_on by locking down
# every module pair that does not currently import from each other.
governance-ast --generate --source-root src/

# See the dependency map
governance-ast --discover

# Edit governance.toml — remove dependencies you don't want, add layers
# Then enforce:
governance-ast

Set up CI — add to .github/workflows/governance.yml:

- uses: actions/checkout@v4
- name: Governance
  uses: useparadigm/code-governance@main
  with:
    config: governance.toml
    diff: origin/main

See governance-fix workflow to enable the /governance fix PR command.

GitLab CI — add to .gitlab-ci.yml:

governance:
  image: python:3.12-slim
  variables:
    GIT_DEPTH: 0
  before_script:
    - pip install code-governance
  script:
    - governance-ast --config governance.toml --diff origin/$CI_MERGE_REQUEST_TARGET_BRANCH_NAME
  rules:
    - if: $CI_PIPELINE_SOURCE == "merge_request_event"

See GitLab MR comments to post the report as an MR note.

What it catches

What happens in CI

Every PR gets a governance comment:

❌ Governance — 1 violation, 1 new module

🔴 🔗 core: Forbidden dependency: 'core' imports 'db' (cannot_depend_on: ['db'])
  core/service.py:2

📦 New module exporters (exporters/) — not in governance.toml

Reply /governance fix to apply.

🤖 AI: The core→db import creates tight coupling. Extract shared
types into a common module, or remove "db" from core's cannot_depend_on.

New module detected? Reply /governance fix — bot adds it to config, commits to your branch.

Violation? Fix the import or update governance.toml. Use /governance-check in Claude Code for interactive help.

Pre-commit

repos:
  - repo: https://github.com/useparadigm/code-governance
    rev: main
    hooks:
      - id: governance-check
      - id: governance-diff

Adopting on legacy codebases

governance-ast --save-baseline .governance-baseline.json
governance-ast --baseline .governance-baseline.json

Accept existing violations. Only fail on new ones.

Transitive detection

governance-ast --transitive

Detects indirect violations through dependency chains. If api has cannot_depend_on = ["db"] and api → service → db, the transitive check catches it. Also works with layer enforcement. Enable permanently in config with transitive = true under [rules].

LLM advice

export OPENAI_API_KEY=sk-...   # or ANTHROPIC_API_KEY
governance-ast --advise

Analyzes violations and suggests: accept the dependency, restructure the code, or extract a shared module. Works with OpenAI and Anthropic.

HTML report

governance-ast --format html > report.html

Self-contained dependency matrix with module metrics. Drop any governance JSON into it.

Comparison

Choose tach if you need interface enforcement or visibility control. Choose code-governance if you want transitive detection, AI-guided setup, CI integration, or zero-config scanning.

name: Governance Fix

on:
  issue_comment:
    types: [created]

permissions:
  contents: write
  pull-requests: write

jobs:
  apply-fix:
    name: Apply config fix
    runs-on: ubuntu-latest
    if: |
      github.event.issue.pull_request &&
      contains(github.event.comment.body, '/governance fix')
    steps:
      - name: Acknowledge
        env:
          GH_TOKEN: ${{ github.token }}
        run: |
          gh api repos/${{ github.repository }}/issues/comments/${{ github.event.comment.id }}/reactions \
            -X POST -f content=eyes

      - uses: actions/checkout@v4

      - name: Checkout PR branch
        env:
          GH_TOKEN: ${{ github.token }}
        run: gh pr checkout ${{ github.event.issue.number }}

      - name: Find and apply fix
        id: fix
        env:
          GH_TOKEN: ${{ github.token }}
        run: |
          PAYLOAD=$(gh api repos/${{ github.repository }}/issues/${{ github.event.issue.number }}/comments \
            --jq '.[] | select(.body | contains("<!-- governance-fix:")) | .body' \
            | grep -oP '<!-- governance-fix:\K[A-Za-z0-9+/=]+' | tail -1)

          if [ -z "$PAYLOAD" ]; then
            gh api repos/${{ github.repository }}/issues/comments/${{ github.event.comment.id }}/reactions \
              -X POST -f content=confused
            exit 1
          fi

          DECODED=$(echo "$PAYLOAD" | base64 -d)
          CONFIG_PATH=$(echo "$DECODED" | python3 -c "import sys,json; print(json.load(sys.stdin)['config_path'])")
          echo "$DECODED" | python3 -c "import sys,json; print(json.load(sys.stdin)['updated_config'])" > "$CONFIG_PATH"

          pip install code-governance
          echo "Config updated"

          git config user.name "github-actions[bot]"
          git config user.email "41898282+github-actions[bot]@users.noreply.github.com"
          git add "$CONFIG_PATH"
          git diff --cached --quiet && exit 0

          git commit -m "governance: add new modules to config"
          git push
          echo "sha=$(git rev-parse --short HEAD)" >> $GITHUB_OUTPUT

      - name: Confirm
        if: steps.fix.outputs.sha
        env:
          GH_TOKEN: ${{ github.token }}
        run: |
          gh api repos/${{ github.repository }}/issues/comments/${{ github.event.comment.id }}/reactions \
            -X POST -f content='+1'
          gh pr comment ${{ github.event.issue.number }} \
            --body "✅ Config fix applied in \`${{ steps.fix.outputs.sha }}\`. Re-run checks to verify."

governance:
  image: python:3.12-slim
  variables:
    GIT_DEPTH: 0
  before_script:
    - pip install code-governance
    - apt-get update && apt-get install -y --no-install-recommends curl jq && rm -rf /var/lib/apt/lists/*
  script:
    - set +e
    - governance-ci-report --config governance.toml --json > report.json
    - set -e
    - PASSED=$(jq -r '.passed' report.json)
    - jq -r '.markdown' report.json | tee report.md
    - |
      if [ "$CI_PIPELINE_SOURCE" = "merge_request_event" ] && [ -n "$GOVERNANCE_GITLAB_TOKEN" ]; then
        BODY=$(jq -Rs . < report.md)
        curl -sf --request POST \
          --header "PRIVATE-TOKEN: $GOVERNANCE_GITLAB_TOKEN" \
          --header "Content-Type: application/json" \
          --data "{\"body\": $BODY}" \
          "$CI_API_V4_URL/projects/$CI_PROJECT_ID/merge_requests/$CI_MERGE_REQUEST_IID/notes"
      fi
    - test "$PASSED" = "true"
  artifacts:
    when: always
    paths: [report.json, report.md]
  rules:
    - if: $CI_PIPELINE_SOURCE == "merge_request_event"
    - if: $CI_COMMIT_BRANCH == $CI_DEFAULT_BRANCH

Updating

There are two pieces to update independently:

CLI (PyPI package):

pip install --upgrade code-governance

Check the installed version against the flags — if you don't see --language {auto,python,typescript} in governance-ast --help, you're on a pre-0.4 CLI and the TypeScript feature won't work.

Claude Code plugin (skills):

/plugin marketplace update useparadigm-code-governance-plugin

/reload-plugins

Or enable auto-update once: /plugin → Marketplaces → toggle Enable auto-update. Then every session picks up the latest skills automatically.

License

MIT