Discussion: YAML frontmatter support at the top of .jaw files

[dishmint]

Summary

Should JAW support a YAML frontmatter block at the top of .jaw files (delimited by ---), the way Markdown tooling does? This issue is to discuss whether it's worth adding.

Motivation

A frontmatter block could carry file-level metadata that doesn't belong in the body — e.g.:

---
title: Vector Add
author: ...
version: 1
tags: [math, vectors]
---

Today the only metadata mechanism is decorators (#name / #name:value), which attach to a variable, step, or function rather than to the file as a whole.

Why this might not be necessary

JAW already has a Markdown story:

• Fenced ```jaw blocks are recognized inside Markdown via the injection grammar (editors/vscode/syntaxes/jaw-markdown-injection.json), and samples/markdown.md demonstrates it.
• Markdown already supports YAML frontmatter natively, and most Markdown toolchains parse it.

So anyone who wants file-level YAML metadata alongside JAW can author a .md file with a frontmatter block and embed their JAW in a fenced block — no changes to the JAW spec/parser required. Adding a second, JAW-native frontmatter syntax risks duplicating a capability that the Markdown path already covers.

Questions to resolve

• Is there a concrete use case that the .jaw-in-Markdown path does not cover?
• If we add it, where does the work land — lexer/parser (jaw-parse), grammar (jaw-grammar.md), the TextMate grammar, and the LSP would all need to account for a leading --- block.
• Do we want metadata to be semantically meaningful (consumed by the LSP/tooling) or purely informational?
• Does this overlap or conflict with the existing decorator system?

Proposed default

Lean toward not adding native YAML frontmatter to .jaw and instead documenting the "use a .md file with frontmatter + a fenced jaw block" pattern as the recommended way to attach file-level metadata — unless a use case the Markdown path can't serve comes up here.

---

Filed by Claude (Claude Code) on behalf of @dishmint.

[dishmint]

Concrete use case: agent-discoverable JAW via skill-style frontmatter

A use case the Markdown-wrapping path doesn't cleanly cover: an agent could reference a .jaw file directly if it carried frontmatter in a skill format — i.e. a YAML header with name/description fields, the same shape Claude Code skills use in SKILL.md.

That makes the .jaw file itself self-describing and indexable: an agent can scan the frontmatter to decide whether the JAW is relevant, without the file having to be a .md wrapper around a fenced jaw block. The Markdown path gets you file-level metadata, but the artifact is then a .md file, not a .jaw file — so the JAW stops being the primary, directly-referenceable unit.

---
name: Vector Add
description: Zip two 1D vectors and sum elementwise.
---
/FUNC
...

This shifts the proposed default: there is a capability the .jaw-in-Markdown path doesn't provide — keeping the file natively .jaw while still being agent-discoverable like a skill. Worth weighing the parser/grammar/LSP cost against that.

---

Generated by Claude Code