qualitymd

README

QUALITY.md

QUALITY.md is an open format 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.

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. That agentic workflow is the primary experience; the qualitymd CLI provides support tooling for validating QUALITY.md files, managing quality evaluations, and maintaining a QUALITY.md workspace.

Install

1. Install the agent skill:

npx skills add qualitymd/quality.md

1. Install the CLI:

npm install -g quality.md

Usage

Invoke the /quality skill to manage quality for your project:

/quality setup                                  Get started working with QUALITY.md
/quality                                        Get read-only guidance on the next workflow
/quality evaluate                               Evaluate the quality of your project
/quality evaluate Security                      Evaluate a specific quality factor or characteristic
/quality evaluate Triage                        Evaluate a specific area or project component
/quality evaluate Triage Accuracy
                                                Evaluate an area's specific quality

For exact or ambiguous scoped evaluations, use qualified model references such as /quality evaluate area:triage or /quality evaluate factor:triage::accuracy.

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.

To keep the model visible to agents, add a short note to AGENTS.md or CLAUDE.md:

See [QUALITY.md](./QUALITY.md) for how this project models and evaluates quality.

Why QUALITY.md

Manage Quality Debt

As work changes faster, quality erodes quietly unless expectations stay visible and current. One useful software-specific framing names 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).

Working with QUALITY.md

A QUALITY.md file is your project's reward signal for quality — the explicit, shared definition of good that aligns your team, AI assistants, and coding agents with what matters in this context. You capture it once, then run a quality loop that keeps both the work and the signal sharp.

The quality loop:

1. Align — agree on what good means for this context, and capture it as the signal.
2. Evaluate — grade the work against the signal; every gap is a gap in the work or a gap in the bar.
3. Improve — close the gaps in the work.
4. Learn — feed what you learned back into the signal as the product and its risks evolve.

Getting started

1. Run /quality setup to make your quality bar visible. The skill runs a guided setup workflow that inspects available context, asks concrete setup questions with recommended defaults, and writes a QUALITY.md with likely quality factors, assessable requirements, needs, risks, unknowns, open questions, and agent-accessibility gaps. → A shared starting point for what good means here: the expectations already visible in the project, the judgments that still need human input, and the context gaps agents and contributors need to close before they can know what matters most.

2. Run /quality evaluate to see where you stand. The skill analyzes each area of your project against the quality requirements defined in your model, then provides ratings, findings, recommendations, and opportunities to improve both the work and QUALITY.md itself. → A concrete read on where the work meets the bar, where it falls short, and where the model needs to become clearer, more complete, or better grounded.

3. Review and act on the evaluation. Weigh the quality ratings for each area and factor, use the findings to understand the evidence behind the gaps, and apply the recommended actions or hand them off to your issue tracker. → Clear next steps from the evaluation: what to fix now, what to track for later, and why each action matters.

4. Refine the model as you learn. Revise QUALITY.md when the evaluation reveals missing context, unclear requirements, changed risks, or a quality bar that no longer matches the project. → A quality bar that gets clearer and more useful every time you use it.

   Tip: Discuss and apply changes to QUALITY.md with your agent. The /quality skill applies authoring best practices so model changes stay well-formed, grounded, and current, with meaningful changes recorded in the quality log.

Keeping the skill and CLI current

Run /quality update to update the /quality agent skill and qualitymd CLI. Keep them up to date to take advantage of the latest improvements to the efficiency and efficacy of working with QUALITY.md files.

Keeping the loop running

Once you have a model, the loop keeps going at whatever cadence fits your team:

• On demand. Run /quality evaluate whenever you need a read — before a release, during review, when you inherit an unfamiliar project, or when something just feels off. Scope it down when you don't need the whole model: /quality evaluate Triage or /quality evaluate Triage Accuracy. Qualified references such as /quality evaluate area:triage remain available for exact addressing.

• On a cadence. Make the model and its latest evaluation a recurring team review — per sprint, monthly, or whatever rhythm maintainers already use. Close gaps in the work, and sharpen the model where the bar proved wrong, unclear, or out of date — so the shared definition stays current as the product evolves.

• Recurring. Use Codex automations, Claude Code routines, or another maintainer-owned workflow when you want that cadence to run without someone remembering. Keep the loop tied to review habits, not CI or release gates by default.

Example QUALITY.md

The example below is an illustrative support-operations model. It is not a default domain or factor set for QUALITY.md.

---
title: Support Inbox
ratingScale:
  - level: outstanding
    title: Outstanding
    description: The work clearly exceeds the shared quality bar.
    criterion: "Consistently exceeds the requirement with clear margin."
  - level: target
    title: Target
    description: The work meets the shared quality bar.
    criterion: "Meets the expected quality bar."
  - level: minimum
    title: Minimum
    description: The work is acceptable, but has gaps worth improving.
    criterion: "Meets the lowest acceptable bar, with visible gaps."
  - level: unacceptable
    title: Unacceptable
    description: The work is below the shared quality bar.
    criterion: "Falls below the minimum acceptable bar."
areas:
  triage:
    title: Triage
    source: ./support
    factors:
      responsiveness:
        title: Responsiveness
        description: Customers receive timely, useful attention.
        requirements:
          "urgent messages are visible":
            assessment: >
              New messages are classified so urgent customer-impacting issues
              are separated from routine requests.
      accuracy:
        title: Accuracy
        description: Replies are correct, complete, and grounded in policy.
        requirements:
          "answers cite the current policy":
            assessment: >
              Customer-facing replies use the active support policy and do not
              rely on outdated guidance or unsupported assumptions.
---

# Quality model: Support Inbox

## Overview

This model describes the quality bar for daily support triage. Good support
means urgent issues are easy to see, routine requests still move, and customers
receive answers grounded in the current policy.

## Scope

This model covers message triage and written replies in the support workspace.
It does not cover billing system behavior or product incident response.

Format

Specification

The full format is specified in SPECIFICATION.md.

File Structure

A QUALITY.md file has two layers:

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 its purpose and context.

Model Schema

The root model is an area plus a model-wide ratingScale.

title: <string>                 # Required
description: <string>           # Optional
ratingScale:                    # Required, ordered best to worst
  - level: <rating-level-id>    # Required, unique within the scale
    title: <string>             # Required
    description: <string>       # Recommended
    criterion: <string>         # Required
source: <string>                # Optional
factors:                        # Optional*
  <factor-name>:
    title: <string>             # Required
    description: <string>       # Recommended
    factors:                    # Optional
      <sub-factor-name>: <Factor>
    requirements:               # Optional
      <requirement-statement>: <Requirement>
requirements:                   # Optional*
  <requirement-statement>:
    assessment: <string>        # Required, exactly one
    factors: [<factor-name>]    # Required for direct area requirements
    ratings:                    # Optional per-level criteria
      <rating-level-id>: <criterion>
areas:                          # Optional*
  <area-name>: <Area>

At least one of factors, requirements, or areas must be supplied. Areas can nest recursively. ratingScale exists only on the root model.

Core Concepts

Concept	Meaning
Model	The root quality model in a QUALITY.md file.
Area	The thing being evaluated.
Source	The material assessed for an area, such as a path or selector.
Factor	A quality dimension that matters for an area.
Requirement	A specific quality expectation.
Assessment	The means of checking a requirement against an area source.
Finding	An observation produced by an assessment.
Rating Scale	The ordered model-wide scale used to rate results.

CLI Quick Reference

Task	Command
Show format spec	qualitymd spec
Show frontmatter schema	qualitymd schema
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. Expect the format and tooling to change as they mature.

Contributing

Contributor setup and local tasks live in CONTRIBUTING.md.

Documentation

Index

• func Schema() []byte
• func Specification() []byte

Functions

func Schema

func Schema() []byte

Schema returns the bundled companion JSON Schema for QUALITY.md frontmatter. The schema is structural-only and non-normative; SPECIFICATION.md remains the normative source of truth.

func Specification

func Specification() []byte

Specification returns the bundled QUALITY.md format specification.