quality.md 0.4.1 → 0.5.1

package/README.md

@@ -1,23 +1,14 @@
 # QUALITY.md
 
-**QUALITY.md** is an agent-friendly file format and companion agent skill and
-CLI for continuously improving the quality of coding agent and AI assistant projects/harnesses.
+**QUALITY.md** is an [open format](./SPECIFICATION.md) for modeling quality:
+what matters most, why, and how. Use it with the `/quality` agent skill to
+continuously improve AI assistant and coding agent projects.
 
-## Why QUALITY.md
-
-As software — and the agents that write it — moves faster, quality erodes
-quietly through three accumulating debts:
-
-- **Technical debt** — code drifting from where it should be.
-- **Cognitive debt** — the mounting burden of understanding complex or
-  under-documented systems.
-- **Intent debt** — software diverging from what stakeholders actually need.
-
-QUALITY.md makes a team's quality expectations explicit and checkable, so those
-gaps stay visible and addressable instead of compounding.
-
-> The three-debt framing draws on Margaret-Anne Storey, *The Triple Debt of
-> Software Development* ([arXiv:2603.22106](https://arxiv.org/abs/2603.22106)).
+A QUALITY.md file is a Markdown file with a quality model and supporting
+context. The `/quality` skill helps set up the file, evaluate quality, and
+evolve the model as you learn. The `qualitymd` CLI provides support tooling for
+validating QUALITY.md files, managing quality evaluations, and maintaining a
+QUALITY.md workspace.
 
 ## Install
 
@@ -30,27 +21,11 @@ npx skills add qualitymd/quality.md
 2. Install the CLI:
 
 ```sh
-npm install quality.md -g
+npm install -g quality.md
 ```
 
 ## Usage
 
-Create and check a first model with the CLI:
-
-```sh
-qualitymd init
-qualitymd lint
-```
-
-Expected first result:
-
-```text
-Created QUALITY.md
-
-Next: qualitymd lint QUALITY.md
-QUALITY.md is valid.
-```
-
 Invoke the `/quality` skill to manage quality for your project:
 
 ```text
@@ -58,23 +33,40 @@ Invoke the `/quality` skill to manage quality for your project:
 /quality wizard                                 Have your AI assistant/agent help you manage quality
 /quality evaluate                               Evaluate the quality of your project
 /quality evaluate security                      Evaluate a specific quality factor or characteristic
-/quality evaluate payments-api                  Evaluate specific target or project component
+/quality evaluate payments-api                  Evaluate a specific target or project component
 /quality evaluate payments-api maintainability  Evaluate a target's specific quality
 ```
 
-## The Format
+Most users should work with `QUALITY.md` through their coding agent, the
+`/quality` skill, or direct edits. The CLI is primarily support tooling for
+validation, status, and evaluation records.
 
-A `QUALITY.md` file combines a structured quality model with plain-language
-rationale. The structured model names what is being evaluated, which quality
-factors matter, what requirements define those factors, and how each requirement
-should be assessed. The Markdown body explains the context: what the work is,
-what "good" means, where the boundaries are, and why these standards matter.
+To keep the model visible to agents, add a short note to `AGENTS.md` or
+`CLAUDE.md`:
 
-### Specification
+```text
+See [QUALITY.md](./QUALITY.md) for how this project models and evaluates quality.
+```
 
-The format is specified in [`SPECIFICATION.md`](SPECIFICATION.md).
+## Why QUALITY.md
+
+### Manage Quality Debt
 
-### Example QUALITY.md
+As software — and the agents that write it — moves faster, quality erodes
+quietly through three accumulating debts:
+
+- **Technical debt** — code drifting from where it should be.
+- **Cognitive debt** — the mounting burden of understanding complex or
+  under-documented systems.
+- **Intent debt** — software diverging from what stakeholders actually need.
+
+QUALITY.md makes a team's quality expectations explicit and checkable, so those
+gaps stay visible and addressable instead of compounding.
+
+> The three-debt framing draws on Margaret-Anne Storey, *The Triple Debt of
+> Software Development* ([arXiv:2603.22106](https://arxiv.org/abs/2603.22106)).
+
+## Example QUALITY.md
 
 ```markdown
 ---
@@ -133,45 +125,23 @@ This model covers message triage and written replies in the support workspace.
 It does not cover billing system behavior or product incident response.
 ```
 
-An agent that reads this file can evaluate support work against the stated
-requirements, produce findings, and rate the results against the model's scale.
-
-For a completed evaluation run, the CLI renders a concise summary and the full
-report from records supplied by the `/quality` skill:
-
-```text
-Wrote quality/evaluations/0001-subject-quality-eval/report-summary.md, quality/evaluations/0001-subject-quality-eval/report.md, and quality/evaluations/0001-subject-quality-eval/report.json
-```
-
-A summary excerpt looks like this:
-
-```md
-# Quality Evaluation Summary
-
-| Field          | Value  |
-| -------------- | ------ |
-| Overall rating | Target |
-
-## Top Issues
-
-None recorded.
-```
+## Format
 
-## The Specification
+### Specification
 
-The full format specification lives at [`SPECIFICATION.md`](SPECIFICATION.md).
-What follows is a condensed reference.
+The full format is specified in [`SPECIFICATION.md`](SPECIFICATION.md).
 
 ### File Structure
 
-A `QUALITY.md` file has two layers:
+A QUALITY.md file has two layers:
 
-1. **YAML frontmatter** - the structured quality model.
-2. **Markdown body** - the context, rationale, scope, needs, risks, and known
-   gaps that help people and agents interpret the model.
+1. **YAML frontmatter** — the structured quality model.
+2. **Markdown body** — the judgment context, rationale, scope, needs, risks,
+   unknowns, and open questions that help people and agents build, interpret,
+   and evaluate the model.
 
 The document begins with the YAML frontmatter. The Markdown body can be empty,
-but it is where the model explains itself.
+but it is where the model explains its purpose and context.
 
 ### Model Schema
 
@@ -211,7 +181,7 @@ Targets can nest recursively. `ratingScale` exists only on the root model.
 
 | Concept      | Meaning                                                         |
 | ------------ | --------------------------------------------------------------- |
-| Model        | The root quality model in a `QUALITY.md` file.                  |
+| Model        | The root quality model in a QUALITY.md file.                    |
 | Target       | The thing being evaluated.                                      |
 | Source       | The material assessed for a target, such as a path or selector. |
 | Factor       | A quality dimension that matters for a target.                  |
@@ -220,72 +190,25 @@ Targets can nest recursively. `ratingScale` exists only on the root model.
 | Finding      | An observation produced by an assessment.                       |
 | Rating Scale | The ordered model-wide scale used to rate results.              |
 
-### Evaluation Semantics
-
-Each requirement has exactly one `assessment`. An evaluator performs that
-assessment against the target source, records findings, and rates the
-requirement's findings against the model's `ratingScale`. A finding records what
-was observed; the rating result records how that observation compares with the
-model's scale.
-
-```text
-assessment -> findings -> rating result
-```
-
-## The CLI
-
-> **The CLI is an early work in progress.** Today the binary ships
-> `qualitymd init`, `qualitymd lint`, `qualitymd spec`, `qualitymd status`, and the
-> `qualitymd evaluation` run-record surface.
-
-`qualitymd` draws one hard line: the **CLI never asks an AI model to judge your
-project.** It creates and checks `QUALITY.md` files, shows what the file covers,
-writes evaluation records for the `/quality` skill, renders reports, and can
-fail CI when ratings fall below your chosen bar. The judgment work happens in
-the skill, not in the CLI.
-
-### Common commands
-
-| Goal                   | Command                          |
-| ---------------------- | -------------------------------- |
-| Show the format rules  | `qualitymd spec`                 |
-| Create a starter file  | `qualitymd init [path]`          |
-| Check a file           | `qualitymd lint [path]`          |
-| Fix simple lint issues | `qualitymd lint --fix [path]`    |
-| Show project status    | `qualitymd status [path] --json` |
-| Show version info      | `qualitymd version --json`       |
-| Check for updates      | `qualitymd upgrade --check`      |
-| Show command help      | `qualitymd <command> --help`     |
-
-Typical local loop:
-
-```sh
-qualitymd spec
-qualitymd init
-qualitymd lint
-qualitymd status --json
-```
-
-The `/quality` skill uses additional evaluation commands behind the scenes.
-The detailed command guide lives in the bundled
-[`CLI Quick Reference`](skills/quality/resources/cli-quick-reference.md).
-
-## Conceptual model
+## CLI Quick Reference
 
-The way `QUALITY.md` frames quality is informed by the **ISO/IEC 25000 (SQuaRE)**
-family of software-quality standards — particularly ISO/IEC 25010 — and, for the
-shape of a well-formed requirement, **ISO/IEC/IEEE 29148**. We acknowledge these
-as the conceptual lineage, not a conformance target: `QUALITY.md` borrows their
-ideas and vocabulary where they help and diverges where they don't (it uses
-*Factors* where ISO says *characteristics*), optimizing first for a practical,
-readable format.
+| Task                  | Command                          |
+| --------------------- | -------------------------------- |
+| Show format spec      | `qualitymd spec`                 |
+| Create a starter file | `qualitymd init [path]`          |
+| Validate a file       | `qualitymd lint [path]`          |
+| Fix lint issues       | `qualitymd lint --fix [path]`    |
+| Show project status   | `qualitymd status [path] --json` |
+| Show version info     | `qualitymd version --json`       |
+| Check for updates     | `qualitymd update --check`       |
+| Show command help     | `qualitymd <command> --help`     |
 
 ## Status
 
-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.
+The QUALITY.md format, `qualitymd` CLI, and `/quality` skill are early and
+under active development. Expect the format and tooling to change as they
+mature.
 
 ## Contributing
 
 Contributor setup and local tasks live in [`CONTRIBUTING.md`](CONTRIBUTING.md).
-The release runbook lives in
-[`docs/guides/cut-a-release.md`](docs/guides/cut-a-release.md).

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "quality.md",
-  "version": "0.4.1",
+  "version": "0.5.1",
   "description": "Companion CLI for the QUALITY.md file format and /quality agent skill, used to evaluate and improve AI assistant projects and harnesses.",
   "homepage": "https://getquality.md",
   "keywords": [
@@ -34,12 +34,12 @@
     "bin"
   ],
   "optionalDependencies": {
-    "@qualitymd/cli-darwin-arm64": "0.4.1",
-    "@qualitymd/cli-darwin-x64": "0.4.1",
-    "@qualitymd/cli-linux-arm64": "0.4.1",
-    "@qualitymd/cli-linux-x64": "0.4.1",
-    "@qualitymd/cli-win32-arm64": "0.4.1",
-    "@qualitymd/cli-win32-x64": "0.4.1"
+    "@qualitymd/cli-darwin-arm64": "0.5.1",
+    "@qualitymd/cli-darwin-x64": "0.5.1",
+    "@qualitymd/cli-linux-arm64": "0.5.1",
+    "@qualitymd/cli-linux-x64": "0.5.1",
+    "@qualitymd/cli-win32-arm64": "0.5.1",
+    "@qualitymd/cli-win32-x64": "0.5.1"
   },
   "publishConfig": {
     "access": "public"