quality.md 0.2.1 → 0.2.2

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.
Files changed (2) hide show
  1. package/README.md +147 -147
  2. package/package.json +7 -7
package/README.md CHANGED
@@ -1,141 +1,180 @@
1
1
  # QUALITY.md
2
2
 
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
3
+ **QUALITY.md** is an agent-friendly file format and companion agent skill and
4
+ CLI for continuously improving the quality of coding agent and AI assistant projects/harnesses.
5
+
6
+ ## Install
7
+
8
+ 1. Install the agent skill:
9
+
10
+ ```sh
11
+ npx skills add qualitymd/quality.md
12
+ ```
13
+
14
+ 2. Install the CLI:
15
+
16
+ ```sh
17
+ npm install quality.md -g
18
+ ```
19
+
20
+ ## Usage
21
+
22
+ Invoke the `/quality` skill to manage quality for your project:
23
+
24
+ ```text
25
+ /quality setup Get started working with QUALITY.md
26
+ /quality wizard Have your AI assistant/agent help you manage quality
27
+ /quality evaluate Evaluate the quality of your project
28
+ /quality evaluate security Evaluate a specific quality factor or characteristic
29
+ /quality evaluate payments-api Evaluate specific target or project component
30
+ /quality evaluate payments-api maintainability Evaluate a target's specific quality
31
+ ```
32
+
33
+ ## The Format
34
+
35
+ A `QUALITY.md` file combines a structured quality model with plain-language
36
+ rationale. The structured model names what is being evaluated, which quality
37
+ factors matter, what requirements define those factors, and how each requirement
38
+ should be assessed. The Markdown body explains the context: what the work is,
39
+ what "good" means, where the boundaries are, and why these standards matter.
40
+
41
+ ### Specification
42
+
43
+ The format is specified in [`SPECIFICATION.md`](SPECIFICATION.md).
44
+
45
+ ### Example QUALITY.md
22
46
 
23
47
  ```markdown
24
48
  ---
25
- title: Orders API
49
+ title: Support Inbox
26
50
  ratingScale:
27
51
  - level: outstanding
28
52
  title: Outstanding
29
- criterion: "Exceeds the requirement; satisfies it with margin to spare."
53
+ description: The work clearly exceeds the shared quality bar.
54
+ criterion: "Consistently exceeds the requirement with clear margin."
30
55
  - level: target
31
56
  title: Target
32
- criterion: "Satisfies the requirement."
57
+ description: The work meets the shared quality bar.
58
+ criterion: "Meets the expected quality bar."
33
59
  - level: minimum
34
60
  title: Minimum
35
- criterion: "Falls short of the goal but holds the acceptable floor."
61
+ description: The work is acceptable, but has gaps worth improving.
62
+ criterion: "Meets the lowest acceptable bar, with visible gaps."
36
63
  - level: unacceptable
37
64
  title: Unacceptable
38
- criterion: "Falls below the acceptable floor."
65
+ description: The work is below the shared quality bar.
66
+ criterion: "Falls below the minimum acceptable bar."
39
67
  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.
68
+ triage:
69
+ source: ./support
48
70
  factors:
49
- reliability:
50
- description: The API behaves predictably under ordinary and failure conditions.
71
+ responsiveness:
72
+ description: Customers receive timely, useful attention.
51
73
  requirements:
52
- "the write path is covered end-to-end":
74
+ "urgent messages are visible":
53
75
  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.
76
+ New messages are classified so urgent customer-impacting issues
77
+ are separated from routine requests.
78
+ accuracy:
79
+ description: Replies are correct, complete, and grounded in policy.
58
80
  requirements:
59
- "no secrets are committed":
81
+ "answers cite the current policy":
60
82
  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.
83
+ Customer-facing replies use the active support policy and do not
84
+ rely on outdated guidance or unsupported assumptions.
73
85
  ---
74
86
 
75
- # Quality model — Orders API
87
+ # Quality model: Support Inbox
76
88
 
77
89
  ## Overview
78
90
 
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.
91
+ This model describes the quality bar for daily support triage. Good support
92
+ means urgent issues are easy to see, routine requests still move, and customers
93
+ receive answers grounded in the current policy.
89
94
 
90
- #### Reliability
95
+ ## Scope
91
96
 
92
- Customers build on our acknowledgements, so a confirmed write must be durable.
93
- When durability and latency conflict, durability wins.
94
-
95
- #### Security
97
+ This model covers message triage and written replies in the support workspace.
98
+ It does not cover billing system behavior or product incident response.
99
+ ```
96
100
 
97
- The API handles customer data, so access is authenticated and least-privilege.
101
+ An agent that reads this file can evaluate support work against the stated
102
+ requirements, produce findings, and rate the results against the model's scale.
103
+
104
+ ## The Specification
105
+
106
+ The full format specification lives at [`SPECIFICATION.md`](SPECIFICATION.md).
107
+ What follows is a condensed reference.
108
+
109
+ ### File Structure
110
+
111
+ A `QUALITY.md` file has two layers:
112
+
113
+ 1. **YAML frontmatter** - the structured quality model.
114
+ 2. **Markdown body** - the context, rationale, scope, needs, risks, and known
115
+ gaps that help people and agents interpret the model.
116
+
117
+ The document begins with the YAML frontmatter. The Markdown body can be empty,
118
+ but it is where the model explains itself.
119
+
120
+ ### Model Schema
121
+
122
+ The root model is a target plus a model-wide `ratingScale`.
123
+
124
+ ```yaml
125
+ title: <string> # Recommended
126
+ description: <string> # Optional
127
+ ratingScale: # Required, ordered best to worst
128
+ - level: <level-name> # Required, unique within the scale
129
+ title: <string> # Optional
130
+ description: <string> # Recommended
131
+ criterion: <string> # Required
132
+ source: <string> # Optional
133
+ factors: # Optional*
134
+ <factor-name>:
135
+ description: <string> # Recommended
136
+ factors: # Optional
137
+ <sub-factor-name>: <Factor>
138
+ requirements: # Optional
139
+ <requirement-statement>: <Requirement>
140
+ requirements: # Optional*
141
+ <requirement-statement>:
142
+ assessment: <string> # Required, exactly one
143
+ factors: [<factor-name>] # Required for direct target requirements
144
+ ratings: # Optional per-level criteria
145
+ <level-name>: <criterion>
146
+ targets: # Optional*
147
+ <target-name>: <Target>
98
148
  ```
99
149
 
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.
150
+ At least one of `factors`, `requirements`, or `targets` must be supplied.
151
+ Targets can nest recursively. `ratingScale` exists only on the root model.
109
152
 
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.
153
+ ### Core Concepts
115
154
 
116
- ## Skill-first onboarding
155
+ | Concept | Meaning |
156
+ | ------------ | --------------------------------------------------------------- |
157
+ | Model | The root quality model in a `QUALITY.md` file. |
158
+ | Target | The thing being evaluated. |
159
+ | Source | The material assessed for a target, such as a path or selector. |
160
+ | Factor | A quality dimension that matters for a target. |
161
+ | Requirement | A specific quality expectation. |
162
+ | Assessment | The means of checking a requirement against a target source. |
163
+ | Finding | An observation produced by an assessment. |
164
+ | Rating Scale | The ordered model-wide scale used to rate results. |
117
165
 
118
- Install the skill first, then make sure the CLI prerequisite is available:
166
+ ### Evaluation Semantics
119
167
 
120
- ```sh
121
- npx skills add qualitymd/quality.md
122
- qualitymd --version
123
- ```
124
-
125
- Then use the skill in your agent:
168
+ Each requirement has exactly one `assessment`. An evaluator performs that
169
+ assessment against the target source, records findings, and rates the
170
+ requirement's findings against the model's `ratingScale`. A finding records what
171
+ was observed; the rating result records how that observation compares with the
172
+ model's scale.
126
173
 
127
174
  ```text
128
- /quality setup
129
- /quality wizard
130
- /quality evaluate
175
+ assessment -> findings -> rating result
131
176
  ```
132
177
 
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
178
  ## The CLI
140
179
 
141
180
  > **The CLI is an early work in progress.** Today the binary ships
@@ -143,13 +182,12 @@ full bootstrap flow.
143
182
  > `qualitymd evaluation` run-record surface.
144
183
 
145
184
  `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
185
+ model.** It scaffolds and validates a `QUALITY.md`, resolves target nodes and
147
186
  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.
187
+ gates CI. The deep, judgment-based evaluation of a subject against its model is
188
+ carried by **skills**, not by any CLI command.
151
189
 
152
- The deterministic CLI:
190
+ The deterministic surface:
153
191
 
154
192
  - **`qualitymd init`** — scaffold a starter `QUALITY.md` to fill in.
155
193
  - **`qualitymd lint`** — validate a file's structure, fast and deterministic,
@@ -166,48 +204,6 @@ The deterministic CLI:
166
204
  - **`qualitymd evaluation build-report`** — derive `report.md` / `report.json`
167
205
  and optionally gate with `--fail-at-or-below`.
168
206
 
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
207
  ## Conceptual model
212
208
 
213
209
  The way `QUALITY.md` frames quality is informed by the **ISO/IEC 25000 (SQuaRE)**
@@ -218,6 +214,10 @@ ideas and vocabulary where they help and diverges where they don't (it uses
218
214
  *Factors* where ISO says *characteristics*), optimizing first for a practical,
219
215
  readable format.
220
216
 
217
+ ## Status
218
+
219
+ The `QUALITY.md` format, `qualitymd` CLI, and `/quality` skill are early and under active development. The format is specified in [`SPECIFICATION.md`](SPECIFICATION.md). Expect the format and tooling to change as they mature.
220
+
221
221
  ## Contributing
222
222
 
223
223
  Contributor setup and local tasks live in [`CONTRIBUTING.md`](CONTRIBUTING.md).
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "quality.md",
3
- "version": "0.2.1",
3
+ "version": "0.2.2",
4
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
5
  "homepage": "https://getquality.md",
6
6
  "keywords": [
@@ -34,12 +34,12 @@
34
34
  "bin"
35
35
  ],
36
36
  "optionalDependencies": {
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"
37
+ "@qualitymd/cli-darwin-arm64": "0.2.2",
38
+ "@qualitymd/cli-darwin-x64": "0.2.2",
39
+ "@qualitymd/cli-linux-arm64": "0.2.2",
40
+ "@qualitymd/cli-linux-x64": "0.2.2",
41
+ "@qualitymd/cli-win32-arm64": "0.2.2",
42
+ "@qualitymd/cli-win32-x64": "0.2.2"
43
43
  },
44
44
  "publishConfig": {
45
45
  "access": "public"