@hacksmith/doraval 0.2.14 → 0.2.16
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/README.md +78 -142
- package/bin/doraval.js +1 -1
- package/package.json +1 -1
package/README.md
CHANGED
|
@@ -2,137 +2,83 @@
|
|
|
2
2
|
|
|
3
3
|
The context engineering toolkit for coding agents.
|
|
4
4
|
|
|
5
|
-
|
|
5
|
+
If you've ever shipped a Claude Code skill that stopped firing after a refactor, or wondered whether your plugin's structure actually matches what the agent expects — doraval validates that before it becomes a runtime surprise.
|
|
6
6
|
|
|
7
|
-
> **Quick start:**
|
|
8
|
-
>
|
|
7
|
+
> **Quick start:**
|
|
8
|
+
> ```bash
|
|
9
|
+
> # macOS
|
|
10
|
+
> brew install saif-shines/tap/doraval
|
|
11
|
+
> doraval validate .
|
|
12
|
+
>
|
|
13
|
+
> # Everyone else
|
|
14
|
+
> npx @hacksmith/doraval validate .
|
|
15
|
+
> ```
|
|
9
16
|
|
|
10
|
-
|
|
17
|
+
Point it at any local directory or GitHub URL. It auto-detects what you have and tells you what's broken.
|
|
11
18
|
|
|
12
|
-
|
|
13
|
-
- **Multi-provider** — Claude Code validators built in; Cursor, Codex, Windsurf planned
|
|
14
|
-
- **Remote validation** — Point at a GitHub URL instead of cloning first
|
|
15
|
-
- **Rubric drift detection** — Measure deviation across trigger phrases, voice, examples, guardrails, and clarity
|
|
16
|
-
- **AI-driven judging** — Qualitative skill assessment via LLM *(coming soon)*
|
|
17
|
-
- **CI-friendly** — JSON output and non-zero exit codes for pipeline integration
|
|
19
|
+
## Install
|
|
18
20
|
|
|
19
|
-
|
|
20
|
-
|
|
21
|
-
doraval is published on [JSR](https://jsr.io/@hacksmith/doraval) as **`@hacksmith/doraval`**.
|
|
22
|
-
|
|
23
|
-
It is **not** on the npm registry — `npx doraval` and `bunx doraval` will 404.
|
|
24
|
-
|
|
25
|
-
### 1. Install Bun (required)
|
|
26
|
-
|
|
27
|
-
doraval is a **Bun CLI**. Having Node.js installed is not enough.
|
|
21
|
+
### macOS (Homebrew — recommended)
|
|
28
22
|
|
|
29
23
|
```bash
|
|
30
|
-
|
|
31
|
-
|
|
24
|
+
brew tap saif-shines/tap
|
|
25
|
+
brew install doraval
|
|
32
26
|
```
|
|
33
27
|
|
|
34
|
-
|
|
35
|
-
|
|
36
|
-
### 2. Run doraval
|
|
28
|
+
No runtime required. The binary is self-contained.
|
|
37
29
|
|
|
38
|
-
|
|
30
|
+
### npm / npx
|
|
39
31
|
|
|
40
32
|
```bash
|
|
41
|
-
#
|
|
42
|
-
|
|
43
|
-
|
|
44
|
-
# Node/npm users (still requires Bun — doraval runs on Bun, not Node)
|
|
45
|
-
npx jsr @hacksmith/doraval validate .
|
|
33
|
+
npx @hacksmith/doraval validate . # run without installing
|
|
34
|
+
npm install -g @hacksmith/doraval # or install globally
|
|
46
35
|
```
|
|
47
36
|
|
|
48
|
-
|
|
49
|
-
|
|
50
|
-
**Aliases:** subcommands are `validate`, `skill`, `journal`, etc. (there is no separate `dora` binary on your PATH unless you add one — see below).
|
|
51
|
-
|
|
52
|
-
### `jsr add` is not a global CLI install
|
|
53
|
-
|
|
54
|
-
`npx jsr add @hacksmith/doraval` adds doraval as a **project dependency** in `package.json`. It does **not** put `dora` or `doraval` on your shell PATH. JSR’s npm compatibility layer also omits the `bin` field today, so `node_modules/.bin/doraval` is not created.
|
|
55
|
-
|
|
56
|
-
To **run** the CLI, use `npx jsr @hacksmith/doraval` (no `add`):
|
|
57
|
-
|
|
58
|
-
```bash
|
|
59
|
-
npx jsr @hacksmith/doraval validate .
|
|
60
|
-
```
|
|
37
|
+
Requires Node.js. If Bun is installed, it runs faster — but Node works fine.
|
|
61
38
|
|
|
62
|
-
|
|
39
|
+
### Bun
|
|
63
40
|
|
|
64
41
|
```bash
|
|
65
|
-
|
|
66
|
-
|
|
67
|
-
alias doraval='npx jsr @hacksmith/doraval'
|
|
68
|
-
|
|
69
|
-
# or an npm script in package.json
|
|
70
|
-
# "doraval": "jsr @hacksmith/doraval"
|
|
42
|
+
bunx @hacksmith/doraval validate . # run without installing
|
|
43
|
+
bun add -g @hacksmith/doraval # or install globally
|
|
71
44
|
```
|
|
72
45
|
|
|
73
|
-
### What does *not* work
|
|
74
|
-
|
|
75
|
-
| Command | Why |
|
|
76
|
-
|---------|-----|
|
|
77
|
-
| `npx doraval …` | Package is not on npmjs.org |
|
|
78
|
-
| `bunx doraval …` | Same — looks up npm, not JSR |
|
|
79
|
-
| `npx jsr add @hacksmith/doraval` then `dora` | `add` installs a library dep, not a global binary |
|
|
80
|
-
| `node …` / Deno only | CLI uses Bun APIs (`Bun.file`, etc.) |
|
|
81
|
-
|
|
82
|
-
> [!NOTE]
|
|
83
|
-
> **Node users:** use `npx jsr @hacksmith/doraval` to *fetch* the tool, but install **Bun** first to *run* it. There is no Node-native build today.
|
|
84
|
-
|
|
85
46
|
## Usage
|
|
86
47
|
|
|
87
48
|
### `validate` — Auto-detect and validate
|
|
88
49
|
|
|
89
|
-
|
|
50
|
+
Point it at a directory or GitHub URL. It finds what's there and checks it.
|
|
90
51
|
|
|
91
52
|
```bash
|
|
92
|
-
|
|
93
|
-
|
|
94
|
-
|
|
53
|
+
doraval validate . # local directory
|
|
54
|
+
doraval validate https://github.com/obra/superpowers # remote repo
|
|
55
|
+
doraval validate https://github.com/obra/superpowers/tree/main/skills/brainstorming
|
|
95
56
|
```
|
|
96
57
|
|
|
97
|
-
Filter by provider or
|
|
58
|
+
Filter by provider or validator:
|
|
98
59
|
|
|
99
60
|
```bash
|
|
100
|
-
|
|
101
|
-
|
|
61
|
+
doraval validate . --for claude # all Claude validators
|
|
62
|
+
doraval validate . --for claude:plugin # just the plugin validator
|
|
102
63
|
```
|
|
103
64
|
|
|
104
|
-
####
|
|
65
|
+
#### Validators (Claude)
|
|
105
66
|
|
|
106
|
-
| Validator | Detects |
|
|
67
|
+
| Validator | Detects | Checks |
|
|
107
68
|
|---|---|---|
|
|
108
|
-
| `claude:skill` | `SKILL.md` | Frontmatter
|
|
109
|
-
| `claude:plugin` | `.claude-plugin/plugin.json` | Manifest fields, component paths
|
|
110
|
-
| `claude:marketplace` | `plugins/`
|
|
111
|
-
| `claude:hooks` | `hooks/hooks.json`
|
|
69
|
+
| `claude:skill` | `SKILL.md` | Frontmatter, body, supporting files, dynamic injection, advanced fields |
|
|
70
|
+
| `claude:plugin` | `.claude-plugin/plugin.json` | Manifest fields, component paths |
|
|
71
|
+
| `claude:marketplace` | `plugins/` | Plugin directory structure, README, LICENSE |
|
|
72
|
+
| `claude:hooks` | `hooks/hooks.json` | Valid JSON, known event names |
|
|
112
73
|
| `claude:mcp` | `.mcp.json` | Valid JSON, server definitions |
|
|
113
|
-
| `claude:subagent` | `agents/*.md` | Frontmatter with description, non-empty body
|
|
114
|
-
| `claude:command` | `commands/*.md` | Frontmatter
|
|
74
|
+
| `claude:subagent` | `agents/*.md` | Frontmatter with description, non-empty body |
|
|
75
|
+
| `claude:command` | `commands/*.md` | Frontmatter, body, advanced fields |
|
|
115
76
|
| `claude:memory` | `CLAUDE.md` | Non-empty, length limit, @path import resolution |
|
|
116
77
|
|
|
117
|
-
|
|
118
|
-
|
|
119
|
-
`dora validate` accepts GitHub URLs (and any Git URL). It clones the repo to a temp directory, validates, and cleans up. For GitHub repos, it tries `gh` first (handles private repos via your existing auth), then falls back to `git clone`.
|
|
120
|
-
|
|
121
|
-
Supported URL forms:
|
|
122
|
-
|
|
123
|
-
```bash
|
|
124
|
-
dora validate https://github.com/owner/repo
|
|
125
|
-
dora validate https://github.com/owner/repo/tree/branch
|
|
126
|
-
dora validate https://github.com/owner/repo/tree/main/sub/dir
|
|
127
|
-
dora validate github.com/owner/repo # shorthand
|
|
128
|
-
```
|
|
129
|
-
|
|
130
|
-
### `skill validate` — Structural checks (single skill)
|
|
131
|
-
|
|
132
|
-
Validate a single skill directory. This is the original command and continues to work unchanged.
|
|
78
|
+
### `skill validate` — Single skill structural check
|
|
133
79
|
|
|
134
80
|
```bash
|
|
135
|
-
|
|
81
|
+
doraval skill validate ./skills/my-skill/
|
|
136
82
|
```
|
|
137
83
|
|
|
138
84
|
```
|
|
@@ -146,91 +92,81 @@ dora skill validate ./skills/my-skill/
|
|
|
146
92
|
✓ Markdown body is non-empty
|
|
147
93
|
✓ references/ directory exists
|
|
148
94
|
✓ advanced frontmatter: allowed-tools, context
|
|
149
|
-
✓ uses dynamic context injection
|
|
95
|
+
✓ uses dynamic context injection
|
|
150
96
|
|
|
151
97
|
Result: 0 error(s), 0 warning(s)
|
|
152
98
|
```
|
|
153
99
|
|
|
154
|
-
> Note: `name` and `description` are recommended (not hard requirements). Missing them produces warnings rather than errors. The directory name usually provides the invocable `/command`.
|
|
155
|
-
|
|
156
100
|
### `skill drift` — Rubric deviation
|
|
157
101
|
|
|
158
|
-
Measure how far a skill has drifted from known-good rubric standards.
|
|
159
|
-
|
|
160
|
-
| Category | What it checks |
|
|
161
|
-
|---|---|
|
|
162
|
-
| **Trigger** | Description or `when_to_use` includes activation phrases (`Use when...`) |
|
|
163
|
-
| **Structure** | Body has numbered steps or checklists |
|
|
164
|
-
| **Voice** | Uses imperative language (`Create`, `Run`, `Ensure`) |
|
|
165
|
-
| **Example** | Contains code blocks |
|
|
166
|
-
| **Guardrail** | Has explicit `MUST` / `MUST NOT` constraints |
|
|
167
|
-
| **Clarity** | Free of ambiguous words (`maybe`, `perhaps`, `consider`) |
|
|
102
|
+
Measure how far a skill has drifted from known-good rubric standards.
|
|
168
103
|
|
|
169
104
|
```bash
|
|
170
|
-
|
|
105
|
+
doraval skill drift ./skills/my-skill/
|
|
171
106
|
```
|
|
172
107
|
|
|
173
108
|
```
|
|
174
109
|
doraval skill drift — Measuring rubric drift
|
|
175
110
|
|
|
176
|
-
Path: ./skills/my-skill/
|
|
177
|
-
|
|
178
111
|
· Trigger Description includes activation phrases
|
|
179
112
|
· Structure Has step-by-step instructions
|
|
180
|
-
· Voice Uses imperative voice
|
|
181
|
-
↗ Example No code blocks found
|
|
182
|
-
↗ Guardrail No explicit constraints
|
|
113
|
+
· Voice Uses imperative voice
|
|
114
|
+
↗ Example No code blocks found
|
|
115
|
+
↗ Guardrail No explicit constraints
|
|
183
116
|
· Clarity No ambiguous language found
|
|
184
117
|
|
|
185
118
|
2/6 rubric areas have drifted.
|
|
186
119
|
```
|
|
187
120
|
|
|
188
|
-
|
|
121
|
+
| Category | Checks |
|
|
122
|
+
|---|---|
|
|
123
|
+
| **Trigger** | Description includes activation phrases (`Use when...`) |
|
|
124
|
+
| **Structure** | Body has numbered steps or checklists |
|
|
125
|
+
| **Voice** | Uses imperative language (`Create`, `Run`, `Ensure`) |
|
|
126
|
+
| **Example** | Contains code blocks |
|
|
127
|
+
| **Guardrail** | Has explicit `MUST` / `MUST NOT` constraints |
|
|
128
|
+
| **Clarity** | Free of ambiguous words (`maybe`, `perhaps`, `consider`) |
|
|
129
|
+
|
|
130
|
+
### `journal` — Decision memory
|
|
189
131
|
|
|
190
|
-
|
|
191
|
-
> Not yet implemented. This command will send the skill to an LLM for qualitative review of clarity, completeness, and effectiveness.
|
|
132
|
+
Record and sync project principles so future you (and agents) don't accidentally contradict past choices.
|
|
192
133
|
|
|
193
134
|
```bash
|
|
194
|
-
|
|
135
|
+
doraval init # set up journal + configure agent
|
|
136
|
+
doraval journal list # view active principles
|
|
137
|
+
doraval journal add "..." # propose a decision
|
|
138
|
+
doraval journal sync # publish pending entries
|
|
139
|
+
doraval journal update # pull latest from remote
|
|
195
140
|
```
|
|
196
141
|
|
|
142
|
+
Requires the GitHub CLI (`gh`). Journal lives in a private GitHub repo you control.
|
|
143
|
+
|
|
197
144
|
## Options
|
|
198
145
|
|
|
199
146
|
| Flag | Short | Description |
|
|
200
147
|
|---|---|---|
|
|
201
|
-
| `--format <type>` | `-f` |
|
|
202
|
-
| `--for <spec>` | | Target a provider
|
|
148
|
+
| `--format <type>` | `-f` | `table` (default) or `json` |
|
|
149
|
+
| `--for <spec>` | | Target a provider or specific validator |
|
|
203
150
|
| `--verbose` | `-v` | Show detailed diagnostics |
|
|
204
151
|
| `--ci` | | Machine-friendly output, non-zero exit on issues |
|
|
205
152
|
|
|
206
|
-
### CI/CD
|
|
207
|
-
|
|
208
|
-
Use `--format json` and `--ci` for pipeline-friendly output:
|
|
153
|
+
### CI/CD
|
|
209
154
|
|
|
210
155
|
```bash
|
|
211
|
-
|
|
212
|
-
|
|
213
|
-
|
|
156
|
+
doraval validate . --for claude --format json --ci
|
|
157
|
+
doraval skill validate ./my-skill/ --format json --ci
|
|
158
|
+
doraval skill drift ./my-skill/ --format json --ci
|
|
214
159
|
```
|
|
215
160
|
|
|
216
|
-
|
|
217
|
-
|
|
218
|
-
## `journal` — Decision memory with pushback
|
|
219
|
-
|
|
220
|
-
Record, view, and sync project principles and decisions so that future you (and agents) don't accidentally contradict past choices.
|
|
161
|
+
Exits with code `1` when errors are found. Pipe `--format json` output to `jq` or consume programmatically.
|
|
221
162
|
|
|
222
|
-
|
|
223
|
-
|
|
224
|
-
```bash
|
|
225
|
-
dora init # Recommended: set up journal + the coding agent dora will use on the fly for rich `add`
|
|
226
|
-
dora journal list # View active principles
|
|
227
|
-
dora journal update # Pull latest from the remote into local cache
|
|
228
|
-
dora journal add "..." # Propose a decision/note (or long rich markdown via --raw-markdown); staged locally; uses configured agent when input is minimal
|
|
229
|
-
dora journal sync # Publish pending entries + refresh cache
|
|
230
|
-
```
|
|
163
|
+
## Providers
|
|
231
164
|
|
|
232
|
-
|
|
165
|
+
Claude Code validators built in. Cursor, Codex, and Windsurf coming next.
|
|
233
166
|
|
|
234
|
-
|
|
167
|
+
## Links
|
|
235
168
|
|
|
236
|
-
|
|
169
|
+
- [Docs](https://thehacksmith.dev)
|
|
170
|
+
- [JSR package](https://jsr.io/@hacksmith/doraval)
|
|
171
|
+
- [npm package](https://www.npmjs.com/package/@hacksmith/doraval)
|
|
172
|
+
- [GitHub Releases](https://github.com/saif-shines/doraval/releases)
|
package/bin/doraval.js
CHANGED