One-line intent in, history-compatible PRD and AI-ready specs out.

Chinese version: README.zh-CN.md

product-requirement-foundry is a requirement foundry for turning a short product request into a development-ready package that stays aligned with historical product assets, online behavior, and team knowledge.

It is designed for teams that already have reusable project understanding assets such as:

• OpenSpec specs and change artifacts
• wiki analysis documents
• codebase knowledge wiki outputs
• historical PRDs and requirement docs
• design docs and interaction notes
• API, data, and tracking documents
• internal enterprise knowledge bases

Choose only one starting path:

If you are evaluating the repository for rollout or maintenance later, use DEVELOPER_GUIDE.md.

Ignore most files on your first pass.

Use this simple rule:

1. Product managers start with PRODUCT_MANAGER_QUICKSTART.md
2. Engineers start with DEVELOPER_QUICKSTART.md
3. People who just want a demo start with examples/quickstart/README.md

Product Requirement Foundry standardizes this delivery path:

one-line request
-> baseline loading
-> history-compatible PRD
-> OpenSpec proposal/design/spec/tasks/dev-context
-> confidence report
-> AI-assisted delivery

For 0->1, it helps teams turn rough ideas into structured requirement packages.

For 1->n, it helps teams evolve live products without drifting away from historical features, online behavior, and existing terminology.

Traditional PRD-writing skills tend to expand a one-line request into a clean document, but they often ignore:

• existing product behavior
• requirement lineage
• online compatibility constraints
• cross-module impacts
• terminology consistency

Product Requirement Foundry fixes that by forcing a baseline-loading stage before requirement generation.

Use when creating:

• a new product
• a new business line
• a new module with little or no existing implementation

Use when creating:

• enhancement requests for existing features
• online feature upgrades
• cross-module changes
• compatibility or migration demands
• change requests derived from historical specs or knowledge assets

Everything below this point is for installation, skill-pack usage, repository integration, or deeper customization.

If you are just trying the repository for the first time, you can stop reading here and use one of the three starting paths above.

This repository supports both installation styles:

• all-in-one: install the repo root skill product-requirement-foundry
• composable: install one or more skills from skills/

If you only need the install index and recommended skill paths, go directly to:

• skills/README.md
• skills/README.zh-CN.md
• DEVELOPER_GUIDE.md

If your skill installer accepts GitHub repo paths, the primary install targets are:

<repo>/SKILL.md
<repo>/skills/product-requirement-foundry

For the full repository layout, install variants, and Claude/Codex differences, use DEVELOPER_GUIDE.md.

1. Load and normalize baseline assets
2. Classify the request
3. Choose greenfield or incremental template
4. Generate PRD and side documents
5. Run consistency review
6. Generate OpenSpec package when AI development will start from OpenSpec
7. Generate confidence report before handoff

You can automate the first step with:

node <product-requirement-foundry-root>/scripts/baseline-scan.js <workspace-dir>

You can score generated artifacts with:

node <product-requirement-foundry-root>/scripts/confidence-score.js <workspace-dir>

For CLI-style usage:

node scripts/cli.js init <workspace-dir>
node scripts/cli.js scan <workspace-dir>
node scripts/cli.js score <workspace-dir>

Use the root product-requirement-foundry skill for the full workflow.

Use sub-skills only when you want a narrower trigger or a single stage.

For the detailed breakdown, see skills/README.md.

docs/output/
 prd.md
 impact-analysis.md
 baseline-references.md
 change-checklist.md
 open-questions.md
 consistency-review.md
 confidence-report.md
 confidence-score.json
 openspec/
 proposal.md
 design.md
 spec.md
 tasks.md
 dev-context.md

• adapter guides for OpenSpec, wiki, knowledge-wiki, and enterprise KB sources
• baseline scanner for generating normalized baseline artifacts
• confidence scorer and review gates for product/engineering handoff
• CLI wrapper and smoke tests for open-source usage
• greenfield and incremental PRD templates
• OpenSpec output templates for proposal, design, spec, tasks, and development context
• baseline and review templates
• JSON schemas for normalized artifacts
• a social-product domain pack
• a 5-minute PM quickstart under examples/quickstart
• examples for greenfield, incremental, and OpenSpec-driven use, including social 1->n OpenSpec handoff
• a baseline scanner sample workspace under examples/baseline-scanner-sample
• a complete social incremental example under examples/social-comment-priority-full
• starter workspace guidance under starter/STARTER_USAGE.md

npm test

product-requirement-foundry supports the full requirement handoff path from a short product idea to development-ready context:

• It reduces blank-page PRD writing by turning one-line intent into structured requirement artifacts.
• It is history-aware, so 1-to-n requirements are grounded in existing product behavior instead of being rewritten from scratch.
• It is evidence-driven: confidence comes from source references, historical feature mappings, compatibility proof, and review gates.
• It is friendly to AI development because it produces OpenSpec-style context and task files.
• It separates product review from engineering review, so each role validates the parts they actually own.
• It works especially well for C-side social products where relationship graph, content flow, moderation, tracking, and rollout all interact.

For a new product or module, the skill helps the PM move from a rough idea to a structured PRD and MVP scope.

For an online product enhancement, the skill helps the team move from:

one-line request

to:

historically grounded PRD
-> OpenSpec proposal/design/spec/tasks/dev-context
-> confidence report
-> AI-assisted implementation

The practical effect is that PM work shifts from writing every detail manually to reviewing intent, boundaries, current-state accuracy, and risk assumptions.

1. Create a requirement workspace.

node <product-requirement-foundry-root>/scripts/cli.js init <workspace-dir>

2. Fill the request files.

<workspace-dir>/baseline/request/request.md
<workspace-dir>/baseline/request/request.yaml

3. Add historical materials to the matching folders.

baseline/prd/history/
baseline/wiki/modules/
baseline/openspec/specs/
baseline/knowledge/
baseline/api/interfaces/
baseline/tracking/events/
baseline/glossary/

4. Ask the AI tool to use product-requirement-foundry and read the workspace.

Example prompt:

Use product-requirement-foundry at <product-requirement-foundry-root>.
The requirement workspace is <workspace-dir>.
Generate a Product Requirement Foundry package, OpenSpec artifacts, and a confidence report.
Do not ignore historical baseline files.

5. Run baseline scan.

node <product-requirement-foundry-root>/scripts/cli.js scan <workspace-dir>

6. Let the AI generate PRD and OpenSpec artifacts under docs/output/.

7. Run confidence scoring.

node <product-requirement-foundry-root>/scripts/cli.js score <workspace-dir>

8. Product reviews:

• requirement goal
• non-goals
• current online behavior
• delta scope
• open questions
• confidence report evidence chain

9. Engineering reviews:

• affected modules
• API/data/tracking impact
• compatibility and rollback
• OpenSpec scenarios
• task executability

10. If the confidence report is Pass or accepted as Review Required, use the OpenSpec package as AI development context.

For team usage standards, start with:

• Baseline Input Guide
• Baseline Layout Spec

For a 5-minute PM onboarding path, start with:

• examples/quickstart/README.md

For a ready-to-fill workspace skeleton, use:

• starter/STARTER_USAGE.md

For PRD-to-OpenSpec handoff, use:

• OpenSpec Output Adapter

These documents explain how teams should prepare inputs, arrange baseline materials, review generated requirements, and understand package changes.

For open-source collaboration and repository setup, use:

• CONTRIBUTING.md
• CODE_OF_CONDUCT.md
• SECURITY.md
• GITHUB_PROJECT_SUMMARY.md
• GITHUB_PROJECT_SUMMARY.zh-CN.md

For repository automation and contribution flow, also use:

• .github/workflows/test.yml
• .github/ISSUE_TEMPLATE/bug_report.md
• .github/ISSUE_TEMPLATE/feature_request.md
• .github/PULL_REQUEST_TEMPLATE.md

This package is already usable for internal pilot projects and early open-source adoption. It can significantly reduce the amount of manual PRD writing, but for high-risk or high-impact changes, product and engineering should still jointly confirm the goal, boundaries, current online behavior, and evidence chain before implementation starts.

• add more domain packs such as ecommerce, saas, and content
• connect a real parser that builds the normalized baseline JSON automatically
• add a validator that checks PRD completeness against the schemas
• add a requirement lineage builder for long-term historical traceability

This repository now includes direct adapters for:

• Codex via AGENTS.md
• Claude Code via CLAUDE.md
• Cursor via .cursor/rules/product-requirement-foundry.mdc
• GitHub Copilot via .github/copilot-instructions.md

For installation and usage across macOS, Windows, and Linux, see:

• AI_TOOL_SETUP.md
• AI_TOOL_SETUP.zh-CN.md

For a PM-first usage path, see:

• PRODUCT_MANAGER_GUIDE.md
• PRODUCT_MANAGER_GUIDE.zh-CN.md

For an engineer-first usage path, see:

• DEVELOPER_QUICKSTART.md
• DEVELOPER_GUIDE.md