Skip to content
doraval
Esc
↑↓navigate↵open⌘Jpreview
On this page

Quickstart

End-to-end tutorial — install the skill, install the CLI, scan, review, fix, scaffold, and remember principles.

Outcome: doraval skill installed, dora available, project scanned and reviewed, and you know the main commands.

Short path only (skill + review)? Use Audit my agent context instead.

What you will do

  1. Install the doraval skill
  2. Install the CLI (or keep using npx)
  3. Scan the project
  4. Review and fix
  5. Scaffold new context (optional)
  6. Record a principle (optional)

Time: about 10–15 minutes. Needs: Node (for npx), a project with or without agent files.

1. Install the doraval skill

npx skills add saif-shines/doraval

Agents load this checklist when you edit skills, plugins, rules, or agent config. The skill runs the same dora engine you use by hand (or npx @hacksmith/doraval if dora is not on PATH).

What if npx skills add fails?
  • Need network and a current Node
  • Retry: npx skills add saif-shines/doraval
  • List installed skills: npx skills list

2. Put the CLI on PATH (or use npx)

One-shot (no install):

npx @hacksmith/doraval --version

Permanent (pick one):

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

# npm
npm install -g @hacksmith/doraval

# Bun
bun add -g @hacksmith/doraval

After install, dora and doraval are the same binary. Verify:

dora --version
PATH / Alpine notes
  • Global install but dora not found: add your npm/Bun global bin directory to PATH
  • Alpine/musl: use Bun (bunx / bun add -g); platform binaries target glibc

Full matrix: Installation.

3. Scan the project

dora
# same as: dora scan
# or: npx @hacksmith/doraval

Read-only. No API key. You get:

Section Meaning
Agent surfaces Which agents look configured
Health Skill / manifest issues
Next Numbered follow-ups (dora fix …, dora review …) 
dora --format json    # for agents / scripts
dora --ci             # implies JSON

4. Review quality

dora review .
dora review ./path/to/skill-dir
dora review --all
dora review --quick .              # structure + heuristics only
dora review --all --quick --ci     # CI gate, no LLM
Exit Meaning
0 Clean
1 Issues found
2 Could not run

Tiers (structure → heuristics → LLM → sessions): Review tiers.

5. Fix mechanical issues

dora fix .
dora fix --dry-run
dora fix --yes                 # agents / CI (no TTY prompt)
dora fix --brief               # prompt for judgment items
Kind Examples Behavior
Mechanical Frontmatter, paths Diff first; apply on approval or --yes
Judgment Vague descriptions Not auto-written; use --brief then re-review

Re-run dora review . until exit 0.

6. Scaffold new context (optional)

dora new
dora new skill --for claude --name review-pr --description "Reviews PRs" --yes
dora new rule --for cursor --name no-default-exports --yes
dora new plugin --for claude --name my-plugin --yes
Type Meaning
skill Reusable SKILL.md
rule Always-on convention
agent Subagent role
plugin Package to ship

Always pass --for <agent> for non-interactive runs. Then dora review the new path.

7. Record a principle (optional)

dora memory add "Never use default exports" --weight 8
dora memory list
dora memory promote              # hard rules → AGENTS.md (diff + confirm)
dora memory context --json --quiet   # SessionStart hooks

Weights: 8+ hard rule · 5 default · 1–3 soft. Memory concept.

8. Cross-agent conflicts (when scan reports them)

dora reconcile --dry-run
dora reconcile
# or: dora reconcile --apply --yes

Settles contradictions into shared AGENTS.md. dora reconcile.

Use with your agent

After step 1, paste or rely on the skill:

Review my agent context with dora (npx @hacksmith/doraval). Fix mechanical issues with --yes. Do not report done until review exits 0.

JSON, exit codes, CI examples: Use with your agent.

Command map

Job Command
Scan project dora
Review dora review
Fix dora fix
Scaffold dora new --for …
Principles dora memory
Conflicts dora reconcile
Sessions dora sessions
Config / judge dora config

Full flags: Command reference.

Next

Was this page helpful?