prd-os

name	prd-os
description	PRD creation and PRD execution operating system. Use when the founder asks to turn a rough idea into a PRD, run a Codex review on a PRD or issue, decompose an approved PRD into issue specs, or execute an issue with scope enforcement and receipt-based closeout. Not for general product ideation or casual drafting; this is the formal gated workflow.

prd-os

Formal, repo-native workflow for PRD creation and PRD execution inside Claude Code. Codex is the review gate at both phases.

Status

Scaffold only at plugin version 0.1.0. This skill describes the target system so Claude knows what is coming; the implementation lands in later steps. Until the commands and runner scripts ship, do not claim the workflow is operational.

State machines

PRD: idea -> draft -> in-review -> draft (on revise) -> approved -> archived.

Issue: open -> in-progress -> closed. Receipts required between approve and close: verified, reviewed, findings_triaged.

Commands (once wired)

PRD side: /prd-start, /prd-review, /prd-revise, /prd-approve, /prd-split.

Issue side: /issue-start <id>, /issue-approve, /issue-verify, /issue-review, /issue-closeout.

Bootstrap: /prd-os-init (runs once per repo to scaffold .prd-os/ and register hooks).

Non-negotiables

• PRD drafting must not drift into implementation. Scope enforcement restricts edits to the PRD file during drafting.
• Issue planning stays in open status. The stop-gate does not arm until /issue-approve transitions to in-progress.
• Empty allowed_files means deny-all except the active spec itself (control-plane carve-out). This is a fixed contract; do not propose allow-all behavior.
• Every Codex finding gets a disposition before approve or closeout. The dispositions are must-fix, optional, deferred, or rejected-with-reason. No finding may be left unset.
• Concurrent PRD and issue contexts are blocked. /prd-start refuses if an issue is in-progress; /issue-start refuses if a PRD is in-review.
• Codex never edits. Claude is the sole editor. Codex runs through /codex:review and /codex:adversarial-review and returns findings for Claude to triage.
• Runtime state (.claude/state/active-{prd,issue}.json) is never committed. The bootstrap command adds the state directory to .gitignore.

Portable core vs repo-local split

Plugin (portable): commands, runner scripts, hooks, templates, review rubric, findings schema, tests.

Repo (local): .prd-os/config.json, .prd-os/prds/, .prd-os/issues/, .prd-os/findings/, .claude/state/.

What to do right now (pre-implementation)

The plugin is not yet wired. If the founder asks to run /prd-start, /prd-review, or any /prd-* command, say explicitly that the command does not exist yet and point to the current build step in CHANGELOG.md. Do not simulate the workflow with ad-hoc markdown.

For issue execution, continue using the existing .claude/commands/issue-*.md commands until the plugin-scoped replacements land and are proven in parallel.

Upgrade policy

Plugin follows semver. MAJOR bumps may change the state machine, remove commands, or change the findings schema; they require operator action. MINOR bumps are additive. PATCH bumps are fixes. Config schema version is tracked separately in .prd-os/config.json and bumps only when the runner cannot load older configs without migration. See CHANGELOG.md.