---
name: validate-markdown
description: Use when an agent needs to check whether an authored Markdown artifact is structurally valid with quire-cli. Covers quire validate (markdown-only), parse-based sanity checks, required-section checks, and how to report actionable validation failures without doing domain review.
metadata:
  short-description: Validate quire artifacts
---

# Validate Markdown

If this plugin is not initialized or an Agent IX command fails, read [the quire-cli setup guide](https://github.com/agent-ix/quire-cli/blob/main/setup.md) for its prerequisites and local diagnosis.

Use this skill to check structure and schema. Do not turn this into domain review; report concrete CLI failures and missing sections.

## Validate a Markdown Document

`quire validate` is markdown-only: it structurally checks an authored artifact
(`body_extraction` asserts + frontmatter schema + per-level heading uniqueness).
`--module` is required so the archetype can be resolved. On success it exits 0
with no output; on failure it exits 1 with line-numbered diagnostics on stderr.

```bash
quire validate path/to/artifact.md --module path/to/module
```

The archetype is resolved from the document's frontmatter `type` (the OKF
discriminator). Pass `--archetype <NAME>` to override that resolution (or supply
it when the document has no `type`):

```bash
quire validate path/to/artifact.md --module path/to/module --archetype FR
```

To validate a document streamed on stdin, pass `-` as the positional argument:

```bash
cat path/to/artifact.md | quire validate - --module path/to/module
```

## Validate an OKF Bundle (`--okf`)

Use `--okf` to read a *foreign* OKF bundle directory under the permissive
posture. `type` is still required and non-empty, but unknown types, broken
`ix://` links, and `index.md` completeness gaps are reported as **warnings**
(exit 0) rather than hard failures. An untyped document is still a hard error.

```bash
quire validate --okf path/to/bundle --module path/to/module
quire validate --okf --scope path/to/bundle   # scoped module discovery
```

Strict bundle validation is the default per-file behavior — `--okf` only loosens
it for portability. Both postures enforce the base **concept** contract: `type`
is required and non-empty, and the optional OKF fields `description` (string) and
`tags` (string array) are type-checked when present.

## Inspect Structure with parse

For finer-grained structural inspection beyond pass/fail, use parse:

```bash
quire parse path/to/artifact.md | jq '.frontmatter'
quire parse path/to/artifact.md | jq -r '.. | objects | select(has("heading")) | "\(.level) \(.heading)"'
```

## Required Sections

When required sections are known, fetch each one and check content:

```bash
quire lookup path/to/artifact.md --heading Behavior --content
quire lookup path/to/artifact.md --heading Acceptance --content
```

Treat empty output, placeholder-only content, or missing selectors as validation findings.

## Reporting

Report failures with:

- command run
- exit code
- stderr summary
- missing or invalid field/section
- file path and selector, when relevant