Quick Start

Initialize your project

Run notarai init in your project root:

notarai init

This does several things:

Adds a PostToolUse hook to .claude/settings.json so spec files are automatically validated when Claude Code writes or edits them.
Copies the /notarai-reconcile skill to .claude/skills/ for drift detection.
Copies the /notarai-bootstrap skill to .claude/skills/ for bootstrapping specs from an existing codebase.
Copies notarai.spec.json to .notarai/notarai.spec.json so the schema is available for validation.
Writes .notarai/README.md with workflow instructions.
Replaces the ## NotarAI section in CLAUDE.md with a concise description of the workflow.
Appends .notarai/.cache/ to .gitignore so the hash cache DB is never committed.
Writes .mcp.json registering notarai mcp as a local MCP server, so MCP-accelerated reconciliation works out of the box.

Running init again is safe: it always refreshes skills and the schema copy, and replaces the ## NotarAI section in CLAUDE.md with the current content.

Create your first spec

Specs live in a .notarai/ directory at the root of your repository:

project/
  .notarai/
    system.spec.yaml
    auth.spec.yaml
    billing.spec.yaml
    _shared/
      security.spec.yaml
  src/
  docs/

Here’s a minimal spec:

# .notarai/auth.spec.yaml
schema_version: '0.6'

intent: |
  Users can sign up, log in, and reset passwords.
  Sessions expire after 30 min of inactivity.

behaviors:
  - name: 'signup'
    given: 'valid email + password (>= 12 chars)'
    then: 'account created, welcome email sent'
  - name: 'login'
    given: 'valid credentials'
    then: 'JWT issued, session created'

artifacts:
  code:
    - path: 'src/auth/**'
      role: 'primary implementation'
  docs:
    - path: 'docs/auth.md'

Validate specs

# Validate all spec files in .notarai/
notarai validate

# Validate a specific file
notarai validate .notarai/auth.spec.yaml

# Validate a directory
notarai validate .notarai/subsystems/

Output is PASS <file> or FAIL <file> with an indented error list. Exit code is 0 if all files pass, 1 if any fail.

Update NotarAI

Check for and install updates:

notarai update

NotarAI will also print a hint when a newer version is available during validate or init.

Bump schema version

When you upgrade to a new version of NotarAI, update all spec files with:

notarai schema-bump

This overwrites .notarai/notarai.spec.json with the bundled schema and updates the schema_version field in every .notarai/*.spec.yaml file.

Bootstrap from an existing codebase

Use the /notarai-bootstrap skill in Claude Code to generate specs from your existing code via a structured developer interview.

Detect drift

Use the /notarai-reconcile skill in Claude Code to detect drift between specs and code, and propose aligned updates.

Keyboard shortcuts

NotarAI