Metadata-Version: 2.4
Name: necronomicon
Version: 0.5.1
Classifier: Development Status :: 3 - Alpha
Classifier: Environment :: Console
Classifier: Intended Audience :: Developers
Classifier: Programming Language :: Rust
Classifier: Topic :: Software Development :: Quality Assurance
Requires-Dist: gdtoolkit==4.5.0 ; extra == 'gdscript'
Provides-Extra: gdscript
License-File: LICENSE
Summary: Agent mind control for your codebase: house rules that teach. Pre-commit checks tell coding agents what's wrong, why, and what to do instead.
Keywords: linter,pre-commit,static-analysis,code-quality,coding-agents,rust
License-Expression: Apache-2.0
Requires-Python: >=3.9
Description-Content-Type: text/markdown; charset=UTF-8; variant=GFM
Project-URL: Repository, https://github.com/WahahaYes/necronomicon

<p align="center"><img src="https://raw.githubusercontent.com/WahahaYes/necronomicon/main/docs/banner.png" width="640" alt="necronomicon: lint errors that explain themselves to coding agents. A spiral-eyed pixel robot, wrapped by a green tentacle, takes a dashed feed from a glowing, floating book."></p>

# necronomicon

[![PyPI](https://img.shields.io/pypi/v/necronomicon.svg)](https://pypi.org/project/necronomicon/) [![crates.io](https://img.shields.io/crates/v/necronomicon.svg)](https://crates.io/crates/necronomicon) [![License: Apache-2.0](https://img.shields.io/badge/License-Apache_2.0-blue.svg)](https://github.com/WahahaYes/necronomicon/blob/main/LICENSE)

A simple way to organize a repo's pre-commit hooks for progressive disclosure, steering coding agents toward the repo's conventions and intended architecture. Each rule pairs a command that finds violations with what to say about them: what's wrong, why the rule exists, and what to do instead. An agent sees a rule only when its commit breaks it, at the line it broke, with the long form one `necro --explain` away.

![You write a rule; an agent's commit breaks it; pre-commit blocks it and pushes the why; the agent pulls the rest and commits the fix](https://raw.githubusercontent.com/WahahaYes/necronomicon/main/docs/mind-control.svg)

## Why not AGENTS.md

An instruction file is read every session, whether or not today's work touches it, and followed when the agent remembers to. A rule costs nothing until it's broken, and then it blocks the commit. Use both: AGENTS.md for orientation and a one-line pointer to the rules that shape the code, rules for every "never do X" a command can check. [docs/agents-and-rules.md](https://github.com/WahahaYes/necronomicon/blob/main/docs/agents-and-rules.md) covers keeping the two in step.

## Agent mind control

When an agent trips a rule, necro tells it just enough, and the rest is one command away. From [examples/layers](https://github.com/WahahaYes/necronomicon/tree/main/examples/layers):

```yaml
core-isolated:
  command: necro grep '^\s*(from|import)\s+app\b' -- 'src/core/*.py'
  message: core imports the app layer
  why: Core runs in tests without a database; importing app/ drags one in.
  fix: Take a port from core/ports.py as an argument; app/ passes the real one in.
  details: …   # the long form, and bad and good examples, for necro --explain
```

<details>
<summary><b>An agent that never read the rule commits <code>from app.db import session</code> in core.</b> The commit fails, and 11 lines land in its context.</summary>

```text
error[core-isolated]: core imports the app layer
 --> src/core/pricing.py:2:1
  |
2 | from app.db import session
  | ^^^^^^^^
  |
  = why: Core runs in tests without a database; importing app/ drags one in.
  = fix: Take a port from core/ports.py as an argument; app/ passes the real one in.
  = more: necro --explain core-isolated

necro: 1 error (core-isolated ×1)
```

<details>
<summary><b>It wants the bigger picture</b>, so it runs the command it was handed and pulls 22 more.</summary>

```text
$ necro --explain core-isolated
core-isolated: core imports the app layer

Why: Core runs in tests without a database; importing app/ drags one in.

Fix: Take a port from core/ports.py as an argument; app/ passes the real one in.

Core is the inner layer: app/ may import core, never the reverse.
Exceptions: none. Shared types move into core.

Bad:
    from app.db import session

    def price(order):
        return session.rates(order.region) * order.total

Good:
    from core.ports import Rates

    def price(order, rates: Rates):
        return rates.for_region(order.region) * order.total

Command: necro grep '^\s*(from|import)\s+app\b' -- 'src/core/*.py'
```

</details>
</details>

**Re-steered,** it takes `rates: Rates` as an argument, and the commit passes.

## What necro is, and isn't

- **An organizer, not a parser.** A rule's `command` is anything that prints one `path[:line[:col]]` per violation: `necro grep` for a pattern, a short script for more, or a tool you already run. necro owns the wording, allows and output, so rules work in any language.
- **A replacement for the lint script you'd write anyway.** Repos that work with agents tend to grow a `lint_style.py` that greps for house rules and prints one-line errors. necro keeps those rules as config and adds the why, the fix and `--explain`.
- **Exceptions with reasons.** `necro-allow <rule>: <reason>` in a comment on the line or the one above. An allow without a reason, or one that suppresses nothing, fails the run.
- **Packs for common languages.** `include: [necro:rust]` adds Rust rules that default clippy leaves off, like no `unwrap` or `expect` outside tests, and `necro:rust-style` adds doc and naming conventions; `necro:gdscript` and `necro:gdscript-style` do the same for Godot, with gdtoolkit from the `necronomicon[gdscript]` extra; `necro:agent-files` keeps AGENTS.md, CLAUDE.md and skills where every coding agent finds them. Packs are versioned with necro; `disable:` turns one off, `override:` changes the paths it judges or its parameters, and `necro --list` shows what's on.
- **Fixes, when a rule knows one.** `necro grep --replace` fixes a pattern in place, and `autofix:` names any other fixing command (a formatter, a script). `necro --fix` applies them, then says what it changed and which hits it couldn't fix.
- **A ratchet for rollout.** Grandfather existing hits in a committed snapshot so new ones fail alone; refresh it deliberately as debt gets fixed. See [Baseline](https://github.com/WahahaYes/necronomicon/blob/main/spec/v0.md#baseline).

## Install

```sh
uv tool install necronomicon   # PyPI wheel around the necro binary, no Rust needed
pip install necronomicon       # the same wheel, into the current environment
cargo install necronomicon     # from crates.io, built from source
```

As a hook for [prek](https://github.com/j178/prek) or pre-commit, which installs the wheel into the hook's own environment:

```yaml
- repo: local
  hooks:
    - id: necro
      name: necro
      entry: necro --fix
      language: python
      additional_dependencies: ['necronomicon']
      always_run: true
      require_serial: true
```

For `necro:gdscript`, install `necronomicon[gdscript]` instead, which pins gdtoolkit beside necro.

The runner passes the changed files, so a commit runs only the rules that concern them, and `--fix` applies the fixes rules carry, failing the commit until you re-stage, as a formatter does; in CI, `prek run --from-ref origin/main --to-ref HEAD` (or `pre-commit run`, the same) does it for a branch. `necro` with no files checks everything.

Pin below the next 0.x: any 0.x may break the format.

## Skills for agents

`npx skills add WahahaYes/necronomicon --skill necro-adopt` gives a coding agent a skill for setting necro up in a repo. Its last step, `necro skills install`, adds two skills versioned with your necro: `necro`, for working with its hits, and `necro-rules`, for writing rules and keeping `AGENTS.md` in step. They go in `.agents/skills`, linked from `.claude/skills`; after an upgrade, `necro --fix` rewrites them.

## More

- [docs/writing-rules.md](https://github.com/WahahaYes/necronomicon/blob/main/docs/writing-rules.md): writing rules and allows, and the pre-commit hook.
- [examples/](https://github.com/WahahaYes/necronomicon/tree/main/examples): small repos, each checked by CI.
- [spec/v0.md](https://github.com/WahahaYes/necronomicon/blob/main/spec/v0.md): the contract; [tests/conformance/](https://github.com/WahahaYes/necronomicon/tree/main/tests/conformance) makes it executable.

Pre-release (version 0): any 0.x may break the format. Licensed under [Apache-2.0](https://github.com/WahahaYes/necronomicon/blob/main/LICENSE).

