assura

Repository policy for coding agents

Make repository conventions executable.

Assura gives coding agents precise feedback on project structure, naming and guidance, with the same local policy available in CI.

A convention says “use kebab-case.” A check can name UserMenu.ts, explain the rule, and verify the rename to user-menu.ts.

Set up with your agent See how rules apply
  • Project structure
  • File naming
  • Agent guidance
  • Local and CI policy
Recorded source example CLI, generator and fixture input revision: 5f7ca26de7aab9265c21b65740b431621492b8c0. Source checkout output; published release output may differ. assura review . Example output below preserves the raw generated CLI evidence.
assura review 
Assura reviewStatus     needs attentionScope      feature/agent-review -> origin/mainFindings   blocking=1 advisory=3 new=4Branch     feature/agent-review files=1 lines=+3/-0 commits=1Worktree   files=2 modified=1 untracked=1 lines=+2/-0Watch      blocking-validation=1/1Hot path   apps/web/src violations=1 changed=2 lines=+2/-0Fix first  apps/web/src/BadName.tsx: File 'BadName.tsx' does not match naming convention 'kebab-case'Run        assura check --format agent .

The problem

Written conventions need a checkable counterpart.

A new file can use the wrong name or miss a required location even when its code works. Keep those repository conventions in project-owned configuration so a coding agent and CI can ask the same policy question.

Config to feedback

A rule, a violation, and a verified rename.

This runnable fixture uses the configuration shown below. The recorded check fails on one filename, then passes after that file is renamed. The policy and file contents stay the same.

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

Config → violation → rename → recheck

One recorded naming repair

Recorded CLI output from this fixture, not executed in your browser. The operation below renames one file; it is not autonomous repair.

CLI, generator and fixture input revision: 5f7ca26de7aab9265c21b65740b431621492b8c0. Source checkout output; published release output may differ.

1

Keep the configuration

.ts: kebab-case | max_lines:500

2

Check the wrong name · Exit 1

File 'UserMenu.ts' does not match naming convention 'kebab-case'

file_naming
3

Recorded file rename

packages/core/src/UserMenu.ts → packages/core/src/user-menu.ts

4

Recheck the same policy · Exit 0

6 files · 4 directories · 0 violations

Configuration and file contents unchanged.

The unrepaired file also failed a second check (exit 1).

Selected fields from the actual CLI JSON follow; other report fields are omitted.

Violation: selected CLI JSON fields assura check --format json . 
{
  "dirs_checked": 4,
  "files_checked": 6,
  "success": false,
  "violations": [
    {
      "blocking": true,
      "corrective_context": "Rename the file to match the effective naming rule, or update files.naming/naming_patterns when the policy is stale.",
      "message": "File 'UserMenu.ts' does not match naming convention 'kebab-case'",
      "path": "packages/core/src/UserMenu.ts",
      "rule": "file_naming",
      "severity": "medium",
      "severity_label": "Medium"
    }
  ]
}
Recheck: selected CLI JSON fields assura check --format json . 
{
  "dirs_checked": 4,
  "files_checked": 6,
  "success": true,
  "violations": []
}
Separate policy examples

Policy, paths, and violations

  • · project/ top-down policy
  • • AGENTS.md 1present in passing fixture
  • · packages/core/ 2workspace contract
  • • AGENTS.md 1present in passing fixture
  • • package.json present in passing fixture
  • · src/ recursive defaults
  • • user-menu.ts 3184 / 500 lines in passing fixture
  • ! BadName.ts 3expected kebab-case
  • ! checkout-flow.ts 3537 / 500 lines
observed fixture path check violation 8 files · 4 dirs

These additional naming and line-limit violations are not repaired by the single rename above. The tree organizes policy scopes and observed fixture paths. Only red rows are violations emitted by assura check --format json .; observed paths are not per-path pass records or a separate CLI format.

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

Version-aware start

Choose a version, then set up your project.

Start with the published release. The project owns its policy; generated setup still needs deliberate specialization and host approval.

Published v0.4.1. $ assura agent onboard .

The installer provides the published release. This source checkout may contain newer changes. Keep assura and assura-full together, confirm the selected version, and follow any installer PATH correction.

Start with your agent

Published release installation

Detects and applies

  • project and agent harness detected
  • editable policy added to the project
  • agent guidance and onboarding packet

Leaves undecided

  • language and framework rules
  • project-specific naming
  • host activation and permissions

Where it fits

Repository conventions alongside your existing tools.

Native linters and tests remain necessary. Assura checks configured structure, naming and guidance; use language tools for code semantics and tests for application behavior. Hooks and CI can run both.

Tool Good at Assura adds
Language linters Details inside source files for one language or runtime. Configured repository structure, required paths and guidance alongside native lint, type checks and tests.
LS-Lint Filesystem naming, regex rules and file or directory cardinality. Use Assura when content conventions or repair feedback meet an additional need; keep LS-Lint when its policy is sufficient.
Pre-commit Installing, selecting and running multi-language hooks. Run Assura as another check under the existing runner; retain native commands and hook ownership.
Dependency tools Import direction, dependency relationships and unused code analysis. Repository path conventions alongside specialist dependency analysis. File presence does not establish code usage or test quality.
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
Configured repository structure, required paths and guidance alongside native lint, type checks and tests.
LS-Lint
Good at
Filesystem naming, regex rules and file or directory cardinality.
Assura adds
Use Assura when content conventions or repair feedback meet an additional need; keep LS-Lint when its policy is sufficient.
Pre-commit
Good at
Installing, selecting and running multi-language hooks.
Assura adds
Run Assura as another check under the existing runner; retain native commands and hook ownership.
Dependency tools
Good at
Import direction, dependency relationships and unused code analysis.
Assura adds
Repository path conventions alongside specialist dependency analysis. File presence does not establish code usage or test quality.
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.

The command model

Review the change. Check the contract.

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

Published v0.4.1. The installer provides the published release. This source checkout may contain newer changes. Keep assura and assura-full together, confirm the selected version, and follow any installer PATH correction.

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 --format agent .

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 the current project directory assura explain .
Cold checks Under review No current speed claim.
Warm agent loop Under review No current speed claim.
Performance evidence under review Historical 2026-09-30 · 8 generated naming fixtures. How we measured it
Historical report (recorded version 0.4.1) Warm samples reuse an already running Assura session; session startup and installed hooks are excluded.

Evidence and limitations

Every result has a scope.

The rename above is one recorded fixture result. Historical benchmarks do not establish current speed, and generated setup is not proof of active integration.

Scope

Configured policy

A passing check covers the policies configured for that project. It does not certify software correctness.

Complement

Native tools

Keep language linters, type checks and tests. Assura supplies repository policy feedback alongside them.

Verify

Host activation

Watch and event feedback require a configured integration. Generated files alone do not prove that your host activated it.

Feedback and creator

Bring a convention from your own repository.

Share feedback Meet Nick Roth Read onboarding
Agent setup

Set up this project with Assura.

Copy one instruction to the coding agent already working in your project. It will establish the baseline, define the expected shape, and verify it.

Agent goal Inspect, constrain, verify
Published v0.4.1. The installer provides the published release. This source checkout may contain newer changes. Keep assura and assura-full together, confirm the selected version, and follow any installer PATH correction.
First command assura agent onboard .
  1. Inspect manifests, tooling, generated output, and the intentional layout.
  2. Define project-owned rules for the expected stack. Close stable scopes so unexpected paths fail; preserve legitimate paths and ask only where evidence is ambiguous.
  3. Verify with assura review and assura check --format agent.
Installation details published release pair
curl -fsSL https://assura.dev/install.sh | sh

The copied setup instruction includes this command and the mandatory checks below.

assura --version && assura-full --version