quality.md 0.2.0 → 0.2.1
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 +218 -7
- package/package.json +28 -10
package/README.md
CHANGED
|
@@ -1,14 +1,225 @@
|
|
|
1
1
|
# QUALITY.md
|
|
2
2
|
|
|
3
|
-
|
|
3
|
+
**`QUALITY.md`** is a plain-text *quality model*: one checked-in file that
|
|
4
|
+
declares what *good* means for a software system — its quality requirements —
|
|
5
|
+
and how each is checked. Where a test suite pins down behavior, a `QUALITY.md`
|
|
6
|
+
pins down quality — reliability, security, maintainability, and the rest —
|
|
7
|
+
stated explicitly instead of living in reviewers' heads.
|
|
8
|
+
|
|
9
|
+
The file has two parts: **YAML frontmatter** holding the structured model — a
|
|
10
|
+
recursive tree of *targets*, scoped *factors*, and *requirements* — and a
|
|
11
|
+
**Markdown body** documenting what the system is, what *good* means for it, and
|
|
12
|
+
why those are the right requirements. It is written for whoever decides quality:
|
|
13
|
+
**authors** declare the model, **coding agents** read it to build and evaluate
|
|
14
|
+
against, and **CI** gates on the result.
|
|
15
|
+
|
|
16
|
+
> 🚧 **Alpha.** The `QUALITY.md` format, `qualitymd` CLI, and `/quality` skill
|
|
17
|
+
> are early and under active development. The format is specified in
|
|
18
|
+
> [`SPECIFICATION.md`](SPECIFICATION.md). Expect the format and tooling to change
|
|
19
|
+
> as they mature.
|
|
20
|
+
|
|
21
|
+
## What a QUALITY.md looks like
|
|
22
|
+
|
|
23
|
+
```markdown
|
|
24
|
+
---
|
|
25
|
+
title: Orders API
|
|
26
|
+
ratingScale:
|
|
27
|
+
- level: outstanding
|
|
28
|
+
title: Outstanding
|
|
29
|
+
criterion: "Exceeds the requirement; satisfies it with margin to spare."
|
|
30
|
+
- level: target
|
|
31
|
+
title: Target
|
|
32
|
+
criterion: "Satisfies the requirement."
|
|
33
|
+
- level: minimum
|
|
34
|
+
title: Minimum
|
|
35
|
+
criterion: "Falls short of the goal but holds the acceptable floor."
|
|
36
|
+
- level: unacceptable
|
|
37
|
+
title: Unacceptable
|
|
38
|
+
criterion: "Falls below the acceptable floor."
|
|
39
|
+
targets:
|
|
40
|
+
api:
|
|
41
|
+
source: ./internal/api
|
|
42
|
+
requirements:
|
|
43
|
+
"accepted orders are durable":
|
|
44
|
+
factors: [reliability]
|
|
45
|
+
assessment: >
|
|
46
|
+
A write is acknowledged to the client only after it is committed to
|
|
47
|
+
durable storage. Failures surface as errors, never as false successes.
|
|
48
|
+
factors:
|
|
49
|
+
reliability:
|
|
50
|
+
description: The API behaves predictably under ordinary and failure conditions.
|
|
51
|
+
requirements:
|
|
52
|
+
"the write path is covered end-to-end":
|
|
53
|
+
assessment: >
|
|
54
|
+
The write path is exercised by automated tests that would fail if a
|
|
55
|
+
write were lost or acknowledged before it was durable.
|
|
56
|
+
security:
|
|
57
|
+
description: Customer data and privileged operations are protected.
|
|
58
|
+
requirements:
|
|
59
|
+
"no secrets are committed":
|
|
60
|
+
assessment: >
|
|
61
|
+
No credentials, API keys, or tokens appear in source, config, or
|
|
62
|
+
fixtures; secrets are loaded from the environment at runtime.
|
|
63
|
+
docs:
|
|
64
|
+
source: ./docs
|
|
65
|
+
factors:
|
|
66
|
+
usability:
|
|
67
|
+
description: Integrators can understand and use the documentation unaided.
|
|
68
|
+
requirements:
|
|
69
|
+
"integration docs describe the order lifecycle":
|
|
70
|
+
assessment: >
|
|
71
|
+
The documentation explains how an order moves from request to durable
|
|
72
|
+
acknowledgement, including failure responses and retry guidance.
|
|
73
|
+
---
|
|
74
|
+
|
|
75
|
+
# Quality model — Orders API
|
|
76
|
+
|
|
77
|
+
## Overview
|
|
78
|
+
|
|
79
|
+
The Orders API is the public HTTP interface customers integrate against,
|
|
80
|
+
maintained by the platform team. "Good" here means it never silently loses or
|
|
81
|
+
corrupts an order. This model covers the service and its data layer; the
|
|
82
|
+
third-party payment provider is a dependency, not part of it.
|
|
83
|
+
|
|
84
|
+
## Targets and factors
|
|
85
|
+
|
|
86
|
+
### api
|
|
87
|
+
|
|
88
|
+
The API target covers the HTTP boundary and storage path.
|
|
89
|
+
|
|
90
|
+
#### Reliability
|
|
91
|
+
|
|
92
|
+
Customers build on our acknowledgements, so a confirmed write must be durable.
|
|
93
|
+
When durability and latency conflict, durability wins.
|
|
94
|
+
|
|
95
|
+
#### Security
|
|
96
|
+
|
|
97
|
+
The API handles customer data, so access is authenticated and least-privilege.
|
|
98
|
+
```
|
|
99
|
+
|
|
100
|
+
The **frontmatter** is the structured model: **targets** (things evaluated),
|
|
101
|
+
**factors** (quality characteristics scoped to the target where they are
|
|
102
|
+
declared), and **requirements** under either a target or a factor. Each
|
|
103
|
+
requirement carries one **`assessment`** and is connected to at least one factor; the
|
|
104
|
+
evaluator turns that assessment into a finding, then rates the finding against
|
|
105
|
+
the scale criteria. A target's **`source`** identifies the
|
|
106
|
+
material assessed, and child `targets:` decompose or narrow the subject. The
|
|
107
|
+
**body** holds the reasoning the frontmatter cannot: what the system is, what
|
|
108
|
+
*good* means for it, and why these are the right requirements.
|
|
109
|
+
|
|
110
|
+
A coding agent with the `/quality` skill reads this file to evaluate the Orders
|
|
111
|
+
API against it — performing each `assessment` against the target source, then
|
|
112
|
+
reporting where the subject falls short. The `qualitymd` CLI owns deterministic
|
|
113
|
+
mechanical steps such as scaffolding, linting, spec grounding, and evaluation
|
|
114
|
+
artifact mechanics; judging is the skill's part.
|
|
115
|
+
|
|
116
|
+
## Skill-first onboarding
|
|
117
|
+
|
|
118
|
+
Install the skill first, then make sure the CLI prerequisite is available:
|
|
4
119
|
|
|
5
120
|
```sh
|
|
6
|
-
npx quality.md
|
|
121
|
+
npx skills add qualitymd/quality.md
|
|
122
|
+
qualitymd --version
|
|
7
123
|
```
|
|
8
124
|
|
|
9
|
-
|
|
10
|
-
|
|
11
|
-
|
|
125
|
+
Then use the skill in your agent:
|
|
126
|
+
|
|
127
|
+
```text
|
|
128
|
+
/quality setup
|
|
129
|
+
/quality wizard
|
|
130
|
+
/quality evaluate
|
|
131
|
+
```
|
|
132
|
+
|
|
133
|
+
`setup` and `wizard` verify that the `qualitymd` CLI is installed and compatible
|
|
134
|
+
with the skill. Released skill installs use the CLI SemVer range declared by
|
|
135
|
+
that skill release. If the CLI is missing or stale, they stop and help you
|
|
136
|
+
install or upgrade it before continuing. See [`install.md`](install.md) for the
|
|
137
|
+
full bootstrap flow.
|
|
138
|
+
|
|
139
|
+
## The CLI
|
|
140
|
+
|
|
141
|
+
> **The CLI is an early work in progress.** Today the binary ships
|
|
142
|
+
> `qualitymd init`, `qualitymd lint`, `qualitymd spec`, and the
|
|
143
|
+
> `qualitymd evaluation` run-record surface.
|
|
144
|
+
|
|
145
|
+
`qualitymd` draws one hard line: the **CLI is deterministic and never calls a
|
|
146
|
+
model** — it scaffolds and validates a `QUALITY.md`, resolves target nodes and
|
|
147
|
+
their `source` manifests, records evaluation artifacts, renders reports, and
|
|
148
|
+
gates CI — while
|
|
149
|
+
**skills carry the judgment**, driving the evaluation loop and performing each
|
|
150
|
+
`assessment` against the model.
|
|
151
|
+
|
|
152
|
+
The deterministic CLI:
|
|
153
|
+
|
|
154
|
+
- **`qualitymd init`** — scaffold a starter `QUALITY.md` to fill in.
|
|
155
|
+
- **`qualitymd lint`** — validate a file's structure, fast and deterministic,
|
|
156
|
+
exiting non-zero on errors so it drops into CI.
|
|
157
|
+
- **`qualitymd spec`** — emit the bundled `QUALITY.md` format specification.
|
|
158
|
+
- **`qualitymd evaluation create-run`** — create and number an evaluation run
|
|
159
|
+
folder.
|
|
160
|
+
- **`qualitymd evaluation add-record`** — write assessment, analysis, and
|
|
161
|
+
recommendation records from judgment payloads.
|
|
162
|
+
- **`qualitymd evaluation set-planned-coverage`** — write optional planned
|
|
163
|
+
assessment and analysis coverage for resume diagnostics.
|
|
164
|
+
- **`qualitymd evaluation show-status`** — inspect whether a run is ready to
|
|
165
|
+
render.
|
|
166
|
+
- **`qualitymd evaluation build-report`** — derive `report.md` / `report.json`
|
|
167
|
+
and optionally gate with `--fail-at-or-below`.
|
|
168
|
+
|
|
169
|
+
The deep, judgment-based evaluation of a subject against its model is carried by
|
|
170
|
+
**skills** that orchestrate those resources — not by a CLI command.
|
|
171
|
+
|
|
172
|
+
## Install
|
|
173
|
+
|
|
174
|
+
> **Status.** The format spec is settled — see
|
|
175
|
+
> [`SPECIFICATION.md`](SPECIFICATION.md) — but implementation is in progress.
|
|
176
|
+
> The documented CLI surface includes **`init`**, **`lint`**, **`spec`**, and
|
|
177
|
+
> **`evaluation`**.
|
|
178
|
+
|
|
179
|
+
Install the `/quality` skill with Agent Skills tooling:
|
|
180
|
+
|
|
181
|
+
```sh
|
|
182
|
+
npx skills add qualitymd/quality.md
|
|
183
|
+
```
|
|
184
|
+
|
|
185
|
+
Install the `qualitymd` CLI with a pre-built binary — via npm:
|
|
186
|
+
|
|
187
|
+
```sh
|
|
188
|
+
npm install -g quality.md
|
|
189
|
+
```
|
|
190
|
+
|
|
191
|
+
or Homebrew:
|
|
192
|
+
|
|
193
|
+
```sh
|
|
194
|
+
brew install qualitymd/tap/qualitymd
|
|
195
|
+
```
|
|
196
|
+
|
|
197
|
+
Or build from source with Go 1.26+:
|
|
198
|
+
|
|
199
|
+
```sh
|
|
200
|
+
go install github.com/qualitymd/quality.md/cmd/qualitymd@latest
|
|
201
|
+
```
|
|
202
|
+
|
|
203
|
+
## Specification
|
|
204
|
+
|
|
205
|
+
The `QUALITY.md` format is specified in [`SPECIFICATION.md`](SPECIFICATION.md),
|
|
206
|
+
the source of truth for the format. The `qualitymd` CLI, `/quality` skill, and
|
|
207
|
+
format specification are versioned separately; see
|
|
208
|
+
[`docs/reference/versioning.md`](docs/reference/versioning.md) for the
|
|
209
|
+
compatibility policy.
|
|
210
|
+
|
|
211
|
+
## Conceptual model
|
|
212
|
+
|
|
213
|
+
The way `QUALITY.md` frames quality is informed by the **ISO/IEC 25000 (SQuaRE)**
|
|
214
|
+
family of software-quality standards — particularly ISO/IEC 25010 — and, for the
|
|
215
|
+
shape of a well-formed requirement, **ISO/IEC/IEEE 29148**. We acknowledge these
|
|
216
|
+
as the conceptual lineage, not a conformance target: `QUALITY.md` borrows their
|
|
217
|
+
ideas and vocabulary where they help and diverges where they don't (it uses
|
|
218
|
+
*Factors* where ISO says *characteristics*), optimizing first for a practical,
|
|
219
|
+
readable format.
|
|
220
|
+
|
|
221
|
+
## Contributing
|
|
12
222
|
|
|
13
|
-
|
|
14
|
-
|
|
223
|
+
Contributor setup and local tasks live in [`CONTRIBUTING.md`](CONTRIBUTING.md).
|
|
224
|
+
The release runbook lives in
|
|
225
|
+
[`docs/guides/cut-a-release.md`](docs/guides/cut-a-release.md).
|
package/package.json
CHANGED
|
@@ -1,13 +1,31 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "quality.md",
|
|
3
|
-
"version": "0.2.
|
|
4
|
-
"description": "
|
|
5
|
-
"homepage": "https://
|
|
3
|
+
"version": "0.2.1",
|
|
4
|
+
"description": "Companion CLI for the QUALITY.md file format and /quality agent skill, used to evaluate and improve AI assistant projects and harnesses.",
|
|
5
|
+
"homepage": "https://getquality.md",
|
|
6
|
+
"keywords": [
|
|
7
|
+
"quality",
|
|
8
|
+
"qualitymd",
|
|
9
|
+
"quality.md",
|
|
10
|
+
"quality-model",
|
|
11
|
+
"quality-evaluation",
|
|
12
|
+
"quality-improvement",
|
|
13
|
+
"context-engineering",
|
|
14
|
+
"harness-engineering",
|
|
15
|
+
"cli"
|
|
16
|
+
],
|
|
6
17
|
"repository": {
|
|
7
18
|
"type": "git",
|
|
8
|
-
"url": "https://github.com/qualitymd/quality.md.git"
|
|
19
|
+
"url": "https://github.com/qualitymd/quality.md.git",
|
|
20
|
+
"directory": "npm/quality.md"
|
|
21
|
+
},
|
|
22
|
+
"bugs": {
|
|
23
|
+
"url": "https://github.com/qualitymd/quality.md/issues"
|
|
9
24
|
},
|
|
10
25
|
"license": "MIT",
|
|
26
|
+
"scripts": {
|
|
27
|
+
"prepack": "node ../../scripts/sync-npm-readme.mjs"
|
|
28
|
+
},
|
|
11
29
|
"bin": {
|
|
12
30
|
"qualitymd": "bin/qualitymd.js",
|
|
13
31
|
"quality.md": "bin/qualitymd.js"
|
|
@@ -16,12 +34,12 @@
|
|
|
16
34
|
"bin"
|
|
17
35
|
],
|
|
18
36
|
"optionalDependencies": {
|
|
19
|
-
"@qualitymd/cli-darwin-arm64": "0.2.
|
|
20
|
-
"@qualitymd/cli-darwin-x64": "0.2.
|
|
21
|
-
"@qualitymd/cli-linux-arm64": "0.2.
|
|
22
|
-
"@qualitymd/cli-linux-x64": "0.2.
|
|
23
|
-
"@qualitymd/cli-win32-arm64": "0.2.
|
|
24
|
-
"@qualitymd/cli-win32-x64": "0.2.
|
|
37
|
+
"@qualitymd/cli-darwin-arm64": "0.2.1",
|
|
38
|
+
"@qualitymd/cli-darwin-x64": "0.2.1",
|
|
39
|
+
"@qualitymd/cli-linux-arm64": "0.2.1",
|
|
40
|
+
"@qualitymd/cli-linux-x64": "0.2.1",
|
|
41
|
+
"@qualitymd/cli-win32-arm64": "0.2.1",
|
|
42
|
+
"@qualitymd/cli-win32-x64": "0.2.1"
|
|
25
43
|
},
|
|
26
44
|
"publishConfig": {
|
|
27
45
|
"access": "public"
|