`playbook add` silently drops standard Scope, per-rule examples, and extra markdown

[mghantous]

Description

packmind-cli playbook add silently drops parts of a standard markdown file: Scope is not stored, per-rule examples are not stored, and anything after the rule bullets is discarded with no error. The web UI still has those fields, so the same artifact is poorer (and incomplete) when submitted from the CLI.

This is adjacent to #392 (CLI cannot reliably edit/delete rules). That issue is about the edit lifecycle. This one is about which standard fields the markdown parser maps.

Current Behavior

Create a standard from the CLI documents this file shape:

# <Standard name>

A description of the standard (not mandatory)

- some rule that the agent should follow
- another rule the agent should follow

playbook add maps that to:

• Name — CLI: # Title / UI: Standard
• Description — CLI: paragraph after the H1 / UI: Description (markdown)
• Scope — CLI: not parsed / UI: glob patterns (e.g. **/*.spec.ts)
• Rules — CLI: - / * bullets / UI: Rules
• Per-rule examples — CLI: not parsed / UI: Good / Bad examples on each rule

The same docs page's web example uses labeled fields (**Scope**, **Rules**, Good/Bad snippets). Those labels are UI layout, not CLI syntax. Putting ## Scope, **Scope**, extra headings, tables, or code fences in the markdown file does not fill the Scope field or attach examples.

Packmind's own packmind-update-playbook / create-standard procedure states this explicitly:

• Only * / - bullets are parsed as rules (### subsections are not)
• ## Scope is not parsed (always returns empty string)
• The ## Rules heading is optional; the parser starts at the first bullet

Artifact rendering uses scope globs so Cursor / Claude Code / Copilot only load the standard on matching files. If Scope is empty after a CLI submit, those agents do not get glob filtering. Extra markdown after the rule list is dropped rather than stored.

The older standards create JSON path included scope and rules[].examples (and packmind-create-standard still describes that schema). standards create is deprecated in favor of playbook add, and the markdown importer did not keep those mappings.

Expected Behavior

playbook add of a .packmind/standards/*.md file should be able to set the same standard model as the UI:

1. Scope as comma-separated globs (see Standard skill creator lacks context to create proper scope patterns #181 — globs, not natural language), so install/render can apply file-pattern filtering.
2. Per-rule examples (positive / negative / language) from a documented markdown convention (for example Good/Bad fences under a rule), matching the UI and the old JSON schema.
3. Documented, lossless mapping: content that is not stored as a field should fail validation rather than being silently dropped.

Optional but useful: keep extra markdown (subsections, tables) as part of description or a first-class body field, instead of truncating at the last rule bullet.

Motivation

Anyone authoring standards as markdown and submitting them with the CLI cannot set Scope or examples without a follow-up edit in the UI. That makes the two authoring surfaces diverge, and it is easy for Scope/examples to stay empty after a CLI publish.

Workarounds today:

• Put a glob into a rule bullet — agents may read it; native glob filtering still does not run.
• Set Scope and examples in the UI after submit — those values are not represented in the markdown file, so the next CLI update can drift or omit them.
• Move long-form guidance into a skill (free-form body) — different artifact type and load behavior.

Proposed Solution

Extend the standard markdown parser used by playbook add / playbook submit so it fills UI fields, for example:

# Standard name

Description paragraph (index blurb).

## Scope

**/*.spec.ts,**/*.test.ts

- First rule
- Second rule

And/or restore a documented way to pass the full JSON model (scope, rules[].examples) that standards create used to accept, if markdown cannot express examples cleanly.

packmind-cli playbook diff should show Scope and example changes, not only rule-bullet diffs.

Impact Assessment

• User impact: CLI markdown can set glob scope and examples; rendered agent files get correct file filtering; CLI and UI stay at parity.
• Related: CLI: support updating and deleting standard rules and package membership via playbook #392 (rule update/delete parity), RFC: Introducing Slugs to Standard Rules #196 (rule slugs; deferred per-rule scope), Standard skill creator lacks context to create proper scope patterns #181 (closed; skill should emit glob scope, not prose).

TODO

• Documentation updated (CLI shape vs UI fields)
• Update changelog

[jracenet]

Hey @mghantous 👋

You're right on all of it, and thanks for digging that deep. The two authoring surfaces have drifted, and the worst part is that it fails quietly.

Scope is being fixed right now, a colleague is on it. Standards files will take comma-separated globs, and install/render will do real file filtering after a CLI submit.

For the rest I'd rather be upfront: I don't think we'll do what you're proposing.

You're asking us to teach the importer the fields it's missing. We'd rather get rid of it. It exists because we don't keep the file you hand us, we keep a structured version of it and rebuild a file from that later. Almost everything in your report comes out of that one choice: examples get dropped (#393), the format is imposed on you, and anything past the last rule is discarded.

Which means teaching the importer examples and strict validation is building something we'd throw away a few months later. We're reshaping standards instead, and there's nothing to show yet. Scope lands soon, the rest follows that work, and I'd rather leave this open than close it on a partial answer.

Two things that might help you meanwhile.

• Examples you set in the UI are safer than your report assumes. A later CLI submit doesn't wipe them, and rewording a rule keeps them attached. You only lose them if you actually delete the rule.

• And your prose isn't truncated if you move it above the rules. Anything between the title and the rule list is kept, code blocks and tables included, and it survives the round trip. Only what sits after the last rule is lost. So long-form guidance, and even Good/Bad snippets, can live there today, and it won't bloat what the agents load.

[mghantous]

Thank you. We will use pre-rule description for prose for now, and be on the lookout for the reshape.

[mghantous]

Follow-up after aligning our standards repo to the documented CLI shape and running a full submit + consumer install.

What looks good

• Rule completeness - a previously truncated standard (~45 rules) now round-trips fully on install. That was our main pain point.
• Description blurb - on install, the pre-rule paragraph survives correctly (index entries and agent summaries show the authored one-liner, not just the title). The server raw view frontmatter looked title-only, but install output matched what we submitted.

Assuming interim behavior (per your reply)

We’re treating the following as expected until the Scope work ships, but wanted to confirm:

1. ## Scope folded into description on install - scoped standards render with ## Scope + globs appended to the description field and embedded in standards index list entries, which breaks the index layout (headings mid-list). We assume that’s because Scope isn’t a separate field yet and everything before the first rule bullet is still one blob - not a signal that we should stop authoring ## Scope.

2. alwaysApply: true / no file-path globs on render - rendered agent rules still use alwaysApply: true even when we author globs under ## Scope. Assuming install/render filtering arrives with the in-progress Scope fix.

Still curious (not necessarily blockers)

• Rule order - rules appear alphabetized in the server UI and install output, not in authoring order. Is that intentional long-term, or will the reshape preserve order?

• Minor text changes on ingest - we noticed small wording differences between submitted markdown and what the server stores/renders (e.g. qualifying words dropped from a rule, a longer bullet slightly shortened or rephrased). Rules aren’t missing, but the text isn’t always byte-identical. Is that expected normalization, or something we should treat as a bug?

Thanks again - content completeness looks good on our side; we’ll keep authoring toward the documented shape while Scope lands.