bbs.profullstack/logicsrc
1
0
Fork 0
mirror of https://github.com/profullstack/logicsrc.git synced 2026-08-13 14:37:26 +00:00
Code Issues Projects Releases Packages Wiki Activity Actions

feat(openprd): implement the OpenPRD standard — engine, CLI, conformance bundle (#100)

Browse source 
OpenPRD has existed as a document (docs/openprd.md), a front-matter schema, a
template, and this repo's prd/ collection. Nothing enforced it. This adds the
reference implementation.

@logicsrc/openprd
  - parser: front-matter + the eight `##` sections + numbered requirements.
    `###` stays content so a long Requirements section can be organized, and
    headings or R#-shaped lines inside code fences are ignored
  - validation splits the standard's four conformance rules (filename,
    front-matter schema, id-matches-prefix, eight sections in order) from
    lint (empty section, missing priority tag, numbering gaps, duplicate R#,
    date order, one-sided supersession, stale index). Conformance failures are
    errors; --strict promotes the rest. Stable codes, file, line, hint
  - collection rules the per-file view cannot see: unique ids, monotonic
    numbering with no gaps, 0000 reserved for the template, cross-references
    that resolve
  - lifecycle enforced rather than advisory: Draft cannot jump to Final,
    terminal statuses do not resume, Superseded must name its replacement
  - deterministic index generation, so `prd index` is idempotent and CI can
    diff it
  - front-matter rewriting that leaves the body byte-identical
  - the optional LogicSRC task bridge the standard describes: each R# becomes
    one logicsrc.task, validated against logicsrc-task.schema.json before it
    is emitted; creator DID derived from the author email

CLI: logicsrc prd init|new|list|show|validate|lint|index|status|next|tasks|
export. Exit codes stable for CI (0 ok, 1 invalid, 2 usage, 3 not found).

Conformance bundle: packages/schemas/fixtures/openprd/ — 6 documents that must
validate and 12 that must fail, each naming the error code it must produce.
Several rules depend on the filename, so every fixture records the name it is
validated as.

Docs: an Implementation section in docs/openprd.md (CLI, validation model,
task bridge, conformance bundle), the spec added to the site's docs surface,
nav and sitemap entries, and a README section.

Verification: 76 new tests; full monorepo build and all 451 workspace tests
pass. The suite dogfoods this repo — prd/ validates with zero errors and zero
warnings, the embedded template is byte-identical to docs/openprd/0000-
template.md, and all 210 requirements in PRD 0001 map to schema-valid tasks.
prd/README.md is regenerated by the tool it now ships.

Refs: docs/openprd.md

Co-authored-by: Claude Opus 5 (1M context) <noreply@anthropic.com>
This commit is contained in:
Anthony Ettinger 2026-07-28 04:11:07 -07:00 • committed by GitHub
parent 58c942c67f
commit 296775e003
No known key found for this signature in database
GPG key ID: B5690EEEBB952194
45 changed files with 3605 additions and 5 deletions
Download patch file Download diff file Expand all files Collapse all files

50
docs/openprd.md
View file

@ -4,7 +4,7 @@ OpenPRD is a lightweight, open standard for **product requirements documents** a
It borrows the shape of a BIP/EIP/DIP process: a repo keeps a **numbered, committed collection** of PRDs under `prd/`, each one a single Markdown file with a fixed set of sections and a lifecycle. Where [OpenSpec](./openspec-comparison.md) models a *change* as a multi-file bundle, OpenPRD models a *product decision* as **one numbered file** you can read a year from now to recover the *why*.
Tools such as the moshcode CLI consume this standard to publish PRDs into whatever repo you're working in.
Tools such as the moshcode CLI consume this standard to publish PRDs into whatever repo you're working in. LogicSRC ships its own reference implementation — see [Implementation](#implementation).
## When to write one
@ -87,6 +87,54 @@ See [`0000-template.md`](./openprd/0000-template.md) for the copy-paste template
OpenPRD is intentionally decoupled from the rest of LogicSRC: a PRD is just a file and needs no service to exist. When coordination is wanted, a PRD's `Requirements` map cleanly onto LogicSRC `task` documents (each `R#` → one task), and `owner`/`repo` reuse LogicSRC identity and repo conventions. That bridge is optional and lives in tooling, not in this standard.
## Implementation
`@logicsrc/openprd` is the reference implementation, exposed through the LogicSRC CLI. A PRD is
still just a file: nothing below is required for a document to conform.
```bash
logicsrc prd init # create prd/ with the template and an index
logicsrc prd new "Expand the service" # next free number, filled front-matter, eight stub sections
logicsrc prd list # id, title, status, tags, requirement count
logicsrc prd show 0001 # front-matter, sections, and parsed requirements
logicsrc prd validate --strict # conformance + lint, exit 1 on error
logicsrc prd index --write # regenerate prd/README.md from what is on disk
logicsrc prd status 0001 Review # lifecycle move, refusing illegal transitions
logicsrc prd tasks 0001 # the optional LogicSRC task bridge
```
Validation separates the four conformance rules below from lint. Conformance failures are errors;
everything else — an empty section, a requirement with no priority tag, numbering that skips, a
stale index, a one-sided supersession link — is a warning or a note, and `--strict` promotes them.
Findings carry stable codes (`OP-C-SECTION-ORDER`, `OP-L-REQ-DUPLICATE`, …), the file, the line,
and a remediation hint. Exit codes: `0` ok, `1` invalid, `2` usage, `3` not found.
The lifecycle is enforced rather than advisory: `Draft` cannot jump to `Final`, terminal statuses
do not resume, and moving to `Superseded` requires naming the PRD that replaces it.
Requirement numbering, id uniqueness, and "no gaps" are checked across the whole collection, not
just per file — a repo with `0001` and `0003` and no `0002` fails.
### Task bridge
The optional mapping described above lives in tooling:
```bash
logicsrc prd tasks 0001 --priority P0 --format ndjson
```
Each `R#` becomes one `logicsrc.task` document, validated against `logicsrc-task.schema.json`
before it is emitted. The board defaults to `/prd/<id>`, `repo` carries over to `github_repo`, and
the creator DID is derived from the first author (`anthony@profullstack.com` →
`anthony.profullstack`) unless `--creator` says otherwise.
### Conformance bundle
`packages/schemas/fixtures/openprd/` holds fixtures a third-party implementation can run:
`conformance.json` lists documents that must validate and documents that must fail, each with the
error code it must produce. Because several rules depend on the filename, each fixture records the
name it must be validated as.
## Conformance
A document conforms to OpenPRD `0.2` when: