@hacksmith/doraval 0.2.14 → 0.2.17
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 +79 -142
- package/bin/doraval.js +1 -1
- package/package.json +1 -1
package/README.md
CHANGED
|
@@ -2,137 +2,84 @@
|
|
|
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
|
+
# if Bun is not installed: npm i -g bun
|
|
35
|
+
npm install -g @hacksmith/doraval # or install globally
|
|
46
36
|
```
|
|
47
37
|
|
|
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
|
-
```
|
|
38
|
+
Requires Node.js. If Bun is installed, it runs faster — but Node works fine.
|
|
61
39
|
|
|
62
|
-
|
|
40
|
+
### Bun
|
|
63
41
|
|
|
64
42
|
```bash
|
|
65
|
-
|
|
66
|
-
|
|
67
|
-
alias doraval='npx jsr @hacksmith/doraval'
|
|
68
|
-
|
|
69
|
-
# or an npm script in package.json
|
|
70
|
-
# "doraval": "jsr @hacksmith/doraval"
|
|
43
|
+
bunx @hacksmith/doraval validate . # run without installing
|
|
44
|
+
bun add -g @hacksmith/doraval # or install globally
|
|
71
45
|
```
|
|
72
46
|
|
|
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
47
|
## Usage
|
|
86
48
|
|
|
87
49
|
### `validate` — Auto-detect and validate
|
|
88
50
|
|
|
89
|
-
|
|
51
|
+
Point it at a directory or GitHub URL. It finds what's there and checks it.
|
|
90
52
|
|
|
91
53
|
```bash
|
|
92
|
-
|
|
93
|
-
|
|
94
|
-
|
|
54
|
+
doraval validate . # local directory
|
|
55
|
+
doraval validate https://github.com/obra/superpowers # remote repo
|
|
56
|
+
doraval validate https://github.com/obra/superpowers/tree/main/skills/brainstorming
|
|
95
57
|
```
|
|
96
58
|
|
|
97
|
-
Filter by provider or
|
|
59
|
+
Filter by provider or validator:
|
|
98
60
|
|
|
99
61
|
```bash
|
|
100
|
-
|
|
101
|
-
|
|
62
|
+
doraval validate . --for claude # all Claude validators
|
|
63
|
+
doraval validate . --for claude:plugin # just the plugin validator
|
|
102
64
|
```
|
|
103
65
|
|
|
104
|
-
####
|
|
66
|
+
#### Validators (Claude)
|
|
105
67
|
|
|
106
|
-
| Validator | Detects |
|
|
68
|
+
| Validator | Detects | Checks |
|
|
107
69
|
|---|---|---|
|
|
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`
|
|
70
|
+
| `claude:skill` | `SKILL.md` | Frontmatter, body, supporting files, dynamic injection, advanced fields |
|
|
71
|
+
| `claude:plugin` | `.claude-plugin/plugin.json` | Manifest fields, component paths |
|
|
72
|
+
| `claude:marketplace` | `plugins/` | Plugin directory structure, README, LICENSE |
|
|
73
|
+
| `claude:hooks` | `hooks/hooks.json` | Valid JSON, known event names |
|
|
112
74
|
| `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
|
|
75
|
+
| `claude:subagent` | `agents/*.md` | Frontmatter with description, non-empty body |
|
|
76
|
+
| `claude:command` | `commands/*.md` | Frontmatter, body, advanced fields |
|
|
115
77
|
| `claude:memory` | `CLAUDE.md` | Non-empty, length limit, @path import resolution |
|
|
116
78
|
|
|
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.
|
|
79
|
+
### `skill validate` — Single skill structural check
|
|
133
80
|
|
|
134
81
|
```bash
|
|
135
|
-
|
|
82
|
+
doraval skill validate ./skills/my-skill/
|
|
136
83
|
```
|
|
137
84
|
|
|
138
85
|
```
|
|
@@ -146,91 +93,81 @@ dora skill validate ./skills/my-skill/
|
|
|
146
93
|
✓ Markdown body is non-empty
|
|
147
94
|
✓ references/ directory exists
|
|
148
95
|
✓ advanced frontmatter: allowed-tools, context
|
|
149
|
-
✓ uses dynamic context injection
|
|
96
|
+
✓ uses dynamic context injection
|
|
150
97
|
|
|
151
98
|
Result: 0 error(s), 0 warning(s)
|
|
152
99
|
```
|
|
153
100
|
|
|
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
101
|
### `skill drift` — Rubric deviation
|
|
157
102
|
|
|
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`) |
|
|
103
|
+
Measure how far a skill has drifted from known-good rubric standards.
|
|
168
104
|
|
|
169
105
|
```bash
|
|
170
|
-
|
|
106
|
+
doraval skill drift ./skills/my-skill/
|
|
171
107
|
```
|
|
172
108
|
|
|
173
109
|
```
|
|
174
110
|
doraval skill drift — Measuring rubric drift
|
|
175
111
|
|
|
176
|
-
Path: ./skills/my-skill/
|
|
177
|
-
|
|
178
112
|
· Trigger Description includes activation phrases
|
|
179
113
|
· Structure Has step-by-step instructions
|
|
180
|
-
· Voice Uses imperative voice
|
|
181
|
-
↗ Example No code blocks found
|
|
182
|
-
↗ Guardrail No explicit constraints
|
|
114
|
+
· Voice Uses imperative voice
|
|
115
|
+
↗ Example No code blocks found
|
|
116
|
+
↗ Guardrail No explicit constraints
|
|
183
117
|
· Clarity No ambiguous language found
|
|
184
118
|
|
|
185
119
|
2/6 rubric areas have drifted.
|
|
186
120
|
```
|
|
187
121
|
|
|
188
|
-
|
|
122
|
+
| Category | Checks |
|
|
123
|
+
|---|---|
|
|
124
|
+
| **Trigger** | Description includes activation phrases (`Use when...`) |
|
|
125
|
+
| **Structure** | Body has numbered steps or checklists |
|
|
126
|
+
| **Voice** | Uses imperative language (`Create`, `Run`, `Ensure`) |
|
|
127
|
+
| **Example** | Contains code blocks |
|
|
128
|
+
| **Guardrail** | Has explicit `MUST` / `MUST NOT` constraints |
|
|
129
|
+
| **Clarity** | Free of ambiguous words (`maybe`, `perhaps`, `consider`) |
|
|
130
|
+
|
|
131
|
+
### `journal` — Decision memory
|
|
189
132
|
|
|
190
|
-
|
|
191
|
-
> Not yet implemented. This command will send the skill to an LLM for qualitative review of clarity, completeness, and effectiveness.
|
|
133
|
+
Record and sync project principles so future you (and agents) don't accidentally contradict past choices.
|
|
192
134
|
|
|
193
135
|
```bash
|
|
194
|
-
|
|
136
|
+
doraval init # set up journal + configure agent
|
|
137
|
+
doraval journal list # view active principles
|
|
138
|
+
doraval journal add "..." # propose a decision
|
|
139
|
+
doraval journal sync # publish pending entries
|
|
140
|
+
doraval journal update # pull latest from remote
|
|
195
141
|
```
|
|
196
142
|
|
|
143
|
+
Requires the GitHub CLI (`gh`). Journal lives in a private GitHub repo you control.
|
|
144
|
+
|
|
197
145
|
## Options
|
|
198
146
|
|
|
199
147
|
| Flag | Short | Description |
|
|
200
148
|
|---|---|---|
|
|
201
|
-
| `--format <type>` | `-f` |
|
|
202
|
-
| `--for <spec>` | | Target a provider
|
|
149
|
+
| `--format <type>` | `-f` | `table` (default) or `json` |
|
|
150
|
+
| `--for <spec>` | | Target a provider or specific validator |
|
|
203
151
|
| `--verbose` | `-v` | Show detailed diagnostics |
|
|
204
152
|
| `--ci` | | Machine-friendly output, non-zero exit on issues |
|
|
205
153
|
|
|
206
|
-
### CI/CD
|
|
207
|
-
|
|
208
|
-
Use `--format json` and `--ci` for pipeline-friendly output:
|
|
154
|
+
### CI/CD
|
|
209
155
|
|
|
210
156
|
```bash
|
|
211
|
-
|
|
212
|
-
|
|
213
|
-
|
|
157
|
+
doraval validate . --for claude --format json --ci
|
|
158
|
+
doraval skill validate ./my-skill/ --format json --ci
|
|
159
|
+
doraval skill drift ./my-skill/ --format json --ci
|
|
214
160
|
```
|
|
215
161
|
|
|
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.
|
|
162
|
+
Exits with code `1` when errors are found. Pipe `--format json` output to `jq` or consume programmatically.
|
|
221
163
|
|
|
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
|
-
```
|
|
164
|
+
## Providers
|
|
231
165
|
|
|
232
|
-
|
|
166
|
+
Claude Code validators built in. Cursor, Codex, and Windsurf coming next.
|
|
233
167
|
|
|
234
|
-
|
|
168
|
+
## Links
|
|
235
169
|
|
|
236
|
-
|
|
170
|
+
- [Docs](https://thehacksmith.dev)
|
|
171
|
+
- [JSR package](https://jsr.io/@hacksmith/doraval)
|
|
172
|
+
- [npm package](https://www.npmjs.com/package/@hacksmith/doraval)
|
|
173
|
+
- [GitHub Releases](https://github.com/saif-shines/doraval/releases)
|
package/bin/doraval.js
CHANGED