The shared format
Protocol overview
A shared Markdown format for plans and optional milestones. Readable by people, useful to tools, and flexible enough for your project.
A little structure.
Room for the whole idea.
The format connects human-readable planning with fields that tools can recognize.
- YAML frontmatter
- Identity, creation and update times, revision, status, and the current protocol marker.
- Markdown body
- Explain the outcome, scope, decisions, and validation. Use the headings that fit.
- Acceptance criteria
- Testable requirements with stable IDs, such as AC-01, under any heading.
- Optional milestones
- A companion file for work that benefits from separate reviewable units.
---
id: 1792612800_search-feedback
created_at: 2026-10-21T20:00:00Z
updated_at: 2026-10-21T20:00:00Z
revision: 1
status: pending
protocol: "0.2"
---
# Search feedback
Explain an empty search result and suggest removing filters.
## Scope
Update the empty-state message and add a clear reset action.
## Validation
Check keyboard access, narrow layouts, and search with no matching results.
## Acceptance criteria
- AC-01: Empty search results explain the filters and offer a keyboard-accessible reset action.Write
Generate the preferred format so other tools can recognize it.
Read
Keep useful observations from edited or incomplete documents.
Extend
Retain project metadata and custom status observations with diagnostics.
Protocol 0.2
Complete reference
The jg-plans protocol
A plan is an ordinary Markdown document. Optional metadata makes it easier to identify and revise; acceptance criteria with stable IDs say what done means; optional milestones describe progress when a task benefits from separate review boundaries.
| Version | Status | Specification |
|---|---|---|
| 0.2 | Provisional draft, current | Protocol 0.2 |
Protocol 0.2 is the only supported version. New plans declare protocol: "0.2"; unversioned Markdown uses the same rules. Unsupported declarations receive diagnostics while source remains readable.
The protocol belongs to jg-plans. Applications choose their own approval, execution, coordination, and retention policies. The reference library and CLI are implementations of this protocol, not prerequisites for using it.
Start with the small plan, compare optional milestones, see acceptance criteria in a 0.2 plan, or explore the examples.
Protocol versions are independent of npm package versions. Version 0.2 remains provisional until at least two independent consumers exercise separately approved integrations.
Continue exploring