pai-prd-cli

Scaffold and validate PRDs against the Splitting Test — atomic, verifiable, ideal-state criteria for AI-driven engineering work.

bun add -g pai-prd-cli
pai-prd init feat-user-onboarding --effort advanced
pai-prd validate ./MEMORY/WORK/feat-user-onboarding/PRD.md

What it does

A PRD (Product Requirements Document) is only useful when its acceptance criteria are atomic — one verifiable end-state per criterion. Compound criteria like "All tests pass and the build is green" hide unverified sub-requirements and silently rot under AI execution.

pai-prd-cli enforces atomicity programmatically:

Command	What it does
pai-prd init <slug> --effort <tier>	Creates a MEMORY/WORK/<slug>/PRD.md skeleton with frontmatter, 4 standard sections, and the ISC-count floor for the chosen effort tier.
pai-prd validate <path>	Runs the Splitting Test on every ISC criterion: rejects joiners (and / with / including), unenumerated scope words (all / every / complete), placeholders left from scaffold, and >20-word lines that are almost certainly compound. Also verifies the frontmatter progress: N/M matches the actual checkbox state.

Why this exists

Across hundreds of AI-executed PRDs, two failure modes dominate:

1. Compound criteria — "User signs up and email is verified and welcome message is sent" is three independent things that can fail independently. When the AI marks it [x], you have no idea which sub-step actually shipped.
2. Phantom progress — frontmatter says progress: 7/10 but only 3 checkboxes are marked. Dashboards lie. Reviews drift from reality.

Both fail silently. The Splitting Test catches both at write-time, before they ossify.

Effort tiers and ISC floors

Tier	ISC floor	Use when
standard	8	Normal request, <2 min of work
extended	16	Quality must be extraordinary
advanced	24	Substantial multi-file work
deep	40	Complex design
comprehensive	64	No time pressure

Tiers are not arbitrary — they exist because audits of 50 production PRDs showed 0 of 10 Extended PRDs ever hit the 16-criterion minimum without the gate. The floor is the fix.

Splitting Test rules (what validate enforces)

For every - [ ] ISC-N: ... line:

1. AND / WITH / INCLUDING / PLUS joining two verifiable things → split.
2. ALL / EVERY / COMPLETE / FULL / ENTIRE without enumeration → enumerate.
3. >20 words → almost certainly compound, split.
4. <placeholder> left from scaffold → write the real criterion.

Plus: declared progress: N/M must match real checkbox state.

Install

Requires Bun ≥ 1.0 or Node ≥ 18.

# global
bun add -g pai-prd-cli
# or per-project
bun add -d pai-prd-cli

Local development

bun install
bun run build        # bundles src/cli.ts → dist/cli.js
bun test             # runs Splitting Test on its own test fixtures
bun run dev validate ./README.md   # smoke-run the CLI

License

MIT © Ivan Mokan