assura

Early warning signals for AI-assisted work

Catch project drift before review.

AI agents change projects faster than teams can review them. Assura turns structure, docs, references, and branch changes into early warnings before drift becomes failed hooks, broken CI, or rushed cleanup refactors.

Set up with your agent See how rules apply
  • Fast local checks
  • Branch-aware review
  • Thresholded signals
  • Warn before commit
  • Gate before merge
example output 
$ assura reviewProject status: failBranch    1 file | +3/-0 lines | 1 commitWorktree  1 modified | 1 untracked | +2/-0 Needs attention! apps/web/src/   file naming   1 violation Next  assura check --format agent .
Cold checks 1.62× faster across 8 LS-Lint comparison projects
Warm agent loop 21.59× faster Assura session vs rerunning native LS-Lint CLI
Benchmark evidence How we measured it

The problem

The current workflow catches problems too late.

Teams layer naming linters, code linters, custom scripts, hooks, CI, and convention docs. Each tool sees a slice. Agents often hit the combined wall only after a large batch of work, when the pressure is to make the commit pass instead of choosing the right repair.

Without Assura

  1. Agent changes 18 files
  2. Hooks fail after the batch
  3. Agent rushes a broad refactor
  4. Commit passes with debt

With Assura

  1. Agent changes files
  2. Assura shows hot spots early
  3. Agent makes small repairs
  4. Review stays focused

Small drift

A new helper lands in the wrong folder, docs reference an old path, or generated output escapes its boundary.

Hook pressure

Git hooks fire after the batch, so the agent optimizes for a green commit instead of evaluating the right refactor.

Rushed repair

A fix that could have moved one file becomes a wide patch that passes checks but leaves structural debt.

edit small drift drift grows hook blocks rushed refactor debt lands

The command model

Review the change. Check the contract.

Review keeps agents informed while work is moving. Check makes the final policy decision.

During agent work

Review

Advisory signal
assura review

Compare the branch and worktree, rank attention, and show the next useful action without blocking the loop.

  • Changed work
  • Hot directories
  • Advisory result
Before commit or merge

Check

Policy gate
assura check

Evaluate the configured project contract and return a deterministic pass or fail for hooks and CI.

  • Configured rules
  • Exact violations
  • Pass / fail exit
Set up the baseline assura agent onboard
Investigate one path assura explain <path>

Config to feedback

Define the project once. Make every path checkable.

Assura applies one language-agnostic project policy from the root down. Agents see which paths fit, which rule failed, and the concrete threshold they crossed while the repair is still small.

Project contract

.assura/config.yml

rules:  # Reused at root and package level.  agent-doc:    max_lines: 160    severity: low    message: See docs/agents.md.  # Applied to every package.  workspace:    AGENTS.md: exists:1 | $agent-doc1    package.json: exists:1structure:  # Project entrypoints.  AGENTS.md: exists:1 | $agent-doc1  README.md: exists:1  # Repeat the package contract.  packages/:    ./*/: $workspace2  # Source defaults at every depth.  ./**/:    .ts: kebab-case | max_lines:5003
Same rules, applied

Project tree

  • · project/top-down policy
    • ✓AGENTS.md1 required file
    • ·packages/core/2 workspace contract
      • ✓AGENTS.md1 required guidance
      • ✓package.jsonrequired manifest
      • ·src/recursive defaults
        • ✓user-menu.ts3 184 / 500 lines
        • !BadName.ts3 expected kebab-case
        • !checkout-flow.ts3 537 / 500 lines
passes blocking
What the compact example leaves out

The complete policy adds project-local skills, closed-directory boundaries, directory-health limits, optional apps, and generated-output exclusions.

Open the complete monorepo policy

Where it fits

One signal layer above your existing tools.

Assura does not replace linters, hooks, CI, or docs. It covers the language-agnostic signals they leave scattered: line counts, structure, docs, references, reusable rules, and repair guidance.

Tool Good at Assura adds
Language linters Details inside source files for one language or runtime. One fast language-agnostic policy for line limits, structure, Markdown, config, generated files, and agent guidance.
LS-Lint Fast filesystem naming rules. File-content checks, reusable policy layers, rule-specific repair guidance, agent output, and warm sessions.
Pre-commit Running local gates after a batch of work. Earlier project-review signals and the same bounded policy at the eventual gate.
CI Authoritative post-push validation. Local branch and worktree context before the failure leaves the machine.
Custom scripts One-off project policy and bespoke checks. Shared configuration, one report shape, reusable rules, lifecycle integration, and performance discipline.
Convention docs Explaining project intent to people and agents. Deterministic findings with the path, rule, and concrete repair context.
Language linters
Good at
Details inside source files for one language or runtime.
Assura adds
One fast language-agnostic policy for line limits, structure, Markdown, config, generated files, and agent guidance.
LS-Lint
Good at
Fast filesystem naming rules.
Assura adds
File-content checks, reusable policy layers, rule-specific repair guidance, agent output, and warm sessions.
Pre-commit
Good at
Running local gates after a batch of work.
Assura adds
Earlier project-review signals and the same bounded policy at the eventual gate.
CI
Good at
Authoritative post-push validation.
Assura adds
Local branch and worktree context before the failure leaves the machine.
Custom scripts
Good at
One-off project policy and bespoke checks.
Assura adds
Shared configuration, one report shape, reusable rules, lifecycle integration, and performance discipline.
Convention docs
Good at
Explaining project intent to people and agents.
Assura adds
Deterministic findings with the path, rule, and concrete repair context.
Project baseline structure, docs, agent readiness
Active branch / worktree changed files, line churn, hot directories
Specialized extensions language, content, release, domain checks

Top down first

Assura watches the project as a whole.

Start with broad, language-agnostic health and safety. Then attach language or domain-specific checks only where file contents need deeper validation.

Structure fit

New top-level paths, folder growth, required files, naming drift, and generated-output boundaries.

Change heat

Files changed since base, line churn, untracked paths, renames, commits, and hot directories.

Knowledge drift

Docs, references, agent guidance, skill indexes, stale links, and unchecked content models.

Extension hooks

Project-specific and language-specific checks attach after the broad project layer is stable.

Watch, warn, gate

Small fixes while the work is still small.

Assura separates advisory signals from merge blockers, so agents get timely feedback without turning every observation into a hard stop.

while editing

Watch

Run bounded advisory feedback during supported agent events without blocking the working loop.

before commit

Warn

Show advisory and changed-path findings before the branch reaches its merge gate.

before merge

Gate

Block only the serious configured policy violations that should not land.

Agent-ready onboarding

Checked is not the same as complete.

Assura does not pretend unchecked behavior passed. It tells the agent what is active, what is inactive, and which human decisions are still needed before adding project-specific rules.

$ assura agent onboard . --agent auto --format json

Detect the project, materialize compatible rules into project-owned configuration, run local verification, and leave conflicts or uncertain conventions as explicit questions.

Detects and applies

  • project and agent harness detected
  • editable policy added to the project
  • agent guidance and skills
  • onboarding packet
  • watch / warn / gate profile

Leaves undecided

  • language and framework rules
  • project-specific naming
  • domain content models
  • source-document custody
  • human decisions still needed

Fast enough for the loop

Cheap signals early. Deeper checks near gates.

Assura is designed to run while work is happening, not only after work is done. It starts as fast structural linting and grows into an incremental project signal layer.

0

Git and worktree scan

Find changed paths, line churn, untracked files, and the source branch first.

1

Structure on affected areas

Run cheap project-shape checks where edits can actually change the answer.

2

Docs and references

Layer markdown, frontmatter, links, and project-context checks when they are relevant.

3

Gates and extensions

Run deeper custom or language-specific checks when the workflow moves toward commit or merge.

Start small

Give your agent one local project signal.

Start with your agent Read onboarding
Agent setup

Start with one agent instruction.

Give this prompt to the coding agent already working in your project. It installs Assura, establishes a broad baseline, verifies the setup, and leaves unresolved project decisions visible.

Recommended Agent prompt 
Install Assura in this repository and set it up for agent-ready checks.
If assura is not installed, run:
ASSURA_INSTALL=https://assura.dev/install.sh
curl -fsSL "$ASSURA_INSTALL" | sh

Then run:
assura init . --recipe agentic-core --recipe structure-health --no-git-hooks
assura agent onboard . --agent auto --format json
assura check --format json .

Read .assura/onboarding/agent-next.md, summarize what is active, what is inactive, and what questions need human answers before adding project-specific rules.
Manual install curl -fsSL https://assura.dev/install.sh | sh