doraval (dora)

doraval is a context engineering toolkit for coding agents. It scans, reviews, fixes, and remembers agent context — skills, plugins, rules, and decisions — so Claude, Cursor, Codex, Copilot, and Grok work on every try instead of burning tokens on context you cannot rely on.

Installing · Building from source · Documentation · Repository layout · Development · Contributing · License

Learn more about doraval at doraval.dev

This repository contains the TypeScript source for the dora / doraval CLI, its validators, and the agent skill shipped via npx skills add saif-shines/doraval.

Pronunciation: dor-uh-val · Doraemon + eval

---

Installing

Skill (recommended first step)

Installs the agent skill so coding agents load the Doraval checklist when you edit skills, plugins, rules, or agent config:

npx skills add saif-shines/doraval

CLI

Prebuilt binaries for macOS, Linux, and Windows:

# one-shot (no install)
npx @hacksmith/doraval

# permanent
npm install -g @hacksmith/doraval

# macOS
brew tap saif-shines/tap && brew trust saif-shines/tap && brew install doraval

# Bun
bun add -g @hacksmith/doraval

dora --version    # same binary as doraval

Node ≥ 14.18. Alpine/musl: use Bun. See the changelog and installation guide.

First run

npx @hacksmith/doraval              # scan this project
npx @hacksmith/doraval review .     # quality gate

$ dora

  Health
    ✓ .claude/skills/review    valid
    ✗ .claude/skills/deploy    Missing "description"

  Next
    1. dora fix .claude/skills/deploy
    2. dora review --all

Read-only scan. No API key. Exit codes: 0 clean · 1 issues · 2 could not run.

Paths: Audit my agent context · Quickstart · Use with your agent

npx @hacksmith/doraval review --all --quick --ci

Building from source

Requirements:

• Bun ≥ 1.3
• Node ≥ 14.18 for the published binary target

bun install
bun run dev -- --help          # run CLI from source
bun run build                  # emit bin/doraval.js

Documentation

Full documentation: doraval.dev

Path	Contents
Getting started	Audit vs Quickstart
Command reference	All flags on one page
Use with your agent	Skill, JSON, exit codes, CI
Memory	Principles that stick
Review tiers	Structure → heuristics → LLM → sessions

Commands

Command	Job
dora / scan	Surfaces, health, contradictions, next actions
review	Quality gate (structure → heuristics → LLM → sessions)
fix	Mechanical fixes (--yes / --dry-run / --brief)
new --for	Scaffold skill, rule, agent, or plugin
memory	Principles; enforce in review; promote to AGENTS.md
reconcile	Cross-agent contradictions → shared AGENTS.md
sessions	List / show recent agent sessions
config	Judge / model / settings
bump	Semver in plugin / marketplace manifests
providers	Packaging/spec matrix
update	Self-update

dora review . --quick --ci
dora fix . --dry-run
dora memory add "Never use default exports" --weight 8
dora reconcile --dry-run

Shell completions: dora --completion zsh (or bash / fish).

Repository layout

Path	Contents
src/cli/	citty CLI surface (dora / doraval)
src/core/	Scan, review, fix, memory, sessions, scaffold
src/validators/	Per-agent validators (Claude, Cursor, Codex, Copilot, Grok)
src/providers/	Packaging / provider specs
skills/doraval/	Agent skill shipped via npx skills add saif-shines/doraval
apps/website/	Docs site (Blume)
scripts/	Release, platform packages, publish helpers
test/	Fixtures and CLI tests
bin/	Built CLI entry (doraval.cjs)

Development

bun install
bun run dev -- --help          # run from source
bun test                       # unit + CLI tests
bun run typecheck
bun run build                  # emit bin/doraval.js

See CONTRIBUTING.md and AGENTS.md for conventions (ponytail ladder, no version bumps unless releasing).

Contributing

Issues and PRs are welcome. See CONTRIBUTING.md.

License

MIT — see package.json ("license": "MIT").