plan-doc

Typed parser for plan-file YAML frontmatter (schema v1). Extracts the machine-readable fields a plan-driven-PR workflow needs — template, disposal, branch, a planner-handoff dossier block — from markdown plan documents. Validation is strict on plan-doc's own fields (loud failures on bad values and typos) but lenient on foreign top-level fields a host project carries alongside the schema (captured in .extra).

from pathlib import Path
from plan_doc import PlanDoc, PlanDocError, NonDraftPrFrontmatterError

doc = PlanDoc.from_path(Path("docs/plans/my-plan.md"))
if doc.disposal == "delete-on-merge":
    ...
if doc.dossier is not None:
    files = doc.dossier.get("files", [])

What it enforces

  • Schema v1. plan_schema: 1 is required; template, disposal, phase, cleanup_trigger, ticket, branch, tdd_mode, dossier are plan-doc's own top-level keys. Foreign top-level keys (a host project's own frontmatter convention — id, title, status, …) are tolerated and captured in PlanDoc.extra, so a plan can carry both schemas at once. The typo guard survives: an unknown key within edit-distance 1 of a known field still raises PlanDocError (dispozal fails loud), so a misspelling can't silently disable disposal/minimal handling. (Lenient policy since 0.1.1; 0.1.0 rejected every non-schema key.)
  • First-block-only parsing. Only a ---...--- block at the very top of the file is frontmatter. Body-level --- horizontal rules are never split on.
  • Foreign-document discrimination. Valid frontmatter with no plan_schema and no plan indicator fields raises the typed subclass NonDraftPrFrontmatterError, so callers can treat non-plan documents leniently without swallowing real validation errors.
  • No frontmatter at all raises PlanDocError with an actionable message (add plan_schema: 1).

Dependency note

pyyaml is a hard dependency, and the module also keeps a minimal no-yaml fallback parser (_parse_yaml_minimal) for simple key: value frontmatter. Both halves are deliberate: the upstream source of this module runs in a zero-pip environment and relies on the fallback, while the package declares full functionality. The fallback is covered by tests here — don't remove either half.

Provenance

Originally extracted (code byte-identical, module docstring reframed) from the draft-pr skill of the m0j0d portfolio plugin. As of 2026-06-14 this package is the canonical source of truth: the plugin's vendored copy was deleted and plugin now consumes this package via editable install.

Pool purity rule: transport-free, LLM-agnostic, no secrets. Pure parsing; the only I/O is Path.read_text in PlanDoc.from_path.

License

MIT

Project links

Data verified by PyPI on Aug 22, 2026
Data provided by the project maintainers, verified at the time the release was uploaded to PyPI.

Key dates

PyPI data
Data sourced directly from PyPI's database.
  • Released:
Newer release available (0.1.3)

1 maintainer

PyPI data
Data sourced directly from PyPI's database.
Avatar for m0j0d from gravatar.com m0j0d

Credits

Author: Mike Donnelly

GitHub Statistics

Data verified by PyPI on Aug 22, 2026
The GitHub source repository was provided by the project maintainers and verified by PyPI at the time of upload. Stars, forks, and open issues/PRs are derived from that repository and have not been independently verified.

License

MIT License (MIT)

Requires

Python >=3.10

Provides Extra

dev

Classifiers

Report project as malware

Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Source Distribution

plan_doc-0.1.2.tar.gz (16.5 kB view details)

Uploaded Source

Built Distribution

If you're not sure about the file name format, learn more about wheel file names.

plan_doc-0.1.2-py3-none-any.whl (11.0 kB view details)

Uploaded Python 3

File details

Details for the file plan_doc-0.1.2.tar.gz.

File metadata

  • Download URL: plan_doc-0.1.2.tar.gz
  • Upload date:
  • Size: 16.5 kB
  • Tags: Source
  • Uploaded using Trusted Publishing? Yes
  • Uploaded via: twine/7.0.0 CPython/3.13.14

File hashes

Hashes for plan_doc-0.1.2.tar.gz
Algorithm Hash digest
SHA256 dace861d7f2d26ddbdee7bed0146614e6af9e26d26b85acaca2935b6cca26096
MD5 4dd26c31ec0aa824dbbba3ea229c0079
BLAKE2b-256 5af58e4c693c597b645b369c47759caa4fccbc198de72ea467e6d6d3a05c43c0

See more details on using hashes here.

Provenance

The following attestation bundles were made for plan_doc-0.1.2.tar.gz:

Publisher: release-plan-doc.yml on m0j0d/libs

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

File details

Details for the file plan_doc-0.1.2-py3-none-any.whl.

File metadata

  • Download URL: plan_doc-0.1.2-py3-none-any.whl
  • Upload date:
  • Size: 11.0 kB
  • Tags: Python 3
  • Uploaded using Trusted Publishing? Yes
  • Uploaded via: twine/7.0.0 CPython/3.13.14

File hashes

Hashes for plan_doc-0.1.2-py3-none-any.whl
Algorithm Hash digest
SHA256 b00a470ce43bd85d9c8e48214c312bd786b37222723ca9826da900c3f468d6e1
MD5 11d414d7e8c54d53093138708645f604
BLAKE2b-256 f132eeb58a6fa5dfb168b32e1a5dcdc112a02dd440c35a8d5502c108b361c4af

See more details on using hashes here.

Provenance

The following attestation bundles were made for plan_doc-0.1.2-py3-none-any.whl:

Publisher: release-plan-doc.yml on m0j0d/libs

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

Release history Release notifications | RSS feed

0.1.3

2 files

This release

0.1.2 This release

2 files

0.1.1

2 files

0.1.0

2 files

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page