notarai 0.3.3

CLI validator for NotarAI spec files
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64

# NotarAI

<div align="center">

<img src="https://raw.githubusercontent.com/davidroeca/NotarAI/main/img/NotarAI.png" alt="NotarAI logo" width="300" height="300">

_Intent captured. Drift reconciled._

[![crates.io](https://img.shields.io/crates/v/notarai)](https://crates.io/crates/notarai)
[![CI](https://github.com/davidroeca/NotarAI/actions/workflows/ci.yml/badge.svg)](https://github.com/davidroeca/NotarAI/actions/workflows/ci.yml)
[![License](https://img.shields.io/badge/License-Apache%202.0-blue.svg)](LICENSE)

</div>

NotarAI is a continuous intent reconciliation tool that keeps your specs, code, and documentation in sync as all three evolve. It uses LLMs as a bidirectional reconciliation engine, not just to generate code from specs, but to detect drift, surface conflicts, and propose updates across your entire artifact chain.

## Getting started

The docsite has detailed [docs for getting started](https://notarai.dev/docs/getting-started/installation).

## Spec: complementary, not competing

Use whatever tools you would like to create your code base, then let NotarAI track alignment as the project evolves. The `.notarai/` spec format captures the same intent, behaviors, and constraints that Spec Driven Development (SDD) workflows produce. It just keeps watching after the initial generation is done. NotarAI can work downstream of any SDD tool.

For the full reference, check [here](https://notarai.dev/docs/guides/spec-format).

## Coverage Model

Every file in the repo falls into one of four tiers:

- **Tier 1 (Full Spec)** -- Business logic, APIs, user-facing features. Full behavioral specification.
- **Tier 2 (Registered)** -- Utilities, config, sidecars. Intent and artifact mapping only, no behaviors required.
- **Tier 3 (Excluded)** -- Generated code, vendor deps, editor configs. Explicitly out of scope.
- **Tier 4 (Derived)** -- Generated outputs tracked for staleness but not authored directly (build artifacts, compiled bundles).

Files not covered by any tier are flagged as "unspecced" -- a lint warning, not a blocker.

## Status

This project is in early development. What's implemented:

- Spec schema v0.6 (`notarai.spec.json`) with validation CLI — includes optional blocks for `output`, `content`, `states`, `design`, `audience`, `variants`, `pipeline`, and `feedback`; Tier 4 (Derived); per-artifact tier overrides; and extended `behaviors` with `interaction` and `state_transition`
- `/notarai-reconcile` slash command for drift detection
- `/notarai-bootstrap` slash command for bootstrapping specs from an existing codebase via developer interview
- BLAKE3+SQLite hash cache (`notarai cache`) to skip unchanged files during reconciliation
- MCP server (`notarai mcp`) that serves pre-filtered diffs and artifact lists, keeping reconciliation context proportional to what changed
- Self-update (`notarai update`) with install method detection and passive version hints

Future goals include:

- Supporting other models and agentic ecosystems beyond Claude Code
- Richer invariant elicitation and multi-repo support in the bootstrap flow

## Inspirations

NotarAI draws from Cucumber/Gherkin, IaC tools like Terraform, JSON Schema, Design by Contract, and Architecture Decision Records. See the [Inspirations page](https://notarai.dev/docs/background/inspirations) for details.

## Contributing

See [CONTRIBUTING.md](https://notarai.dev/docs/contributing) for development setup, code style, and PR workflow.

## License

Apache License 2.0. See [LICENSE](LICENSE) for details.