pdd-kit skill
Three skills and a CLI that drive development from a Markdown product model so agents stop guessing what they build.
- 106 ★ on the repository
- Last commit
- MIT
Minimal access
Why this level
- The skills read code without running it and write files to `product-model/` only after your approval.
Install
- Works in
Manual install
npx pdd-toolkit installThe command from the Get started section. It installs skills into detected agents and lets you change the selection.
Access and checks
How we reviewMinimal accessThe tool runs nothing and makes no network calls.
- The skills read code without running it and write files to `product-model/` only after your approval.
This is third-party code. Review the repository files before installing.
What it does
pdd-kit is a toolkit for Product-Driven Development: the repository keeps a product model as plain Markdown files next to the code, and agents work from it. The model is built from entities, interfaces, domains, capabilities, journeys, business rules and variations. It is reviewed in pull requests like any code. The `npx pdd-toolkit install` command adds three skills to the detected agents. `/pdd-map` reads existing code without running it and, after approval, writes `product-model/`, `/pdd-ideate` builds a model from scratch from an idea, and `/pdd-verify` checks the code against the model and lists gaps. The `lint`, `view` and `blueprint` commands validate files, open the model in a browser and pull ready models for common products.
Who it is for. Teams where agents guess product behavior from scratch every time, and managers who want to fix it in the repository.
Good fit when
- An old repository has no product description and `/pdd-map` assembles one from the code.
- A new feature is first recorded in the model through `/pdd-ideate` and only then implemented.
- After implementation `/pdd-verify` checks the code against the approved model.
- For a common product a ready Blueprint is pulled with `npx pdd-toolkit blueprint pull`.
Not a fit when
- You need a spec for one change: the model describes the whole product.
- The project is small and one person holds the product description in their head.
- The team is not ready to maintain model files with every behavior change.
Example request
/pdd-map — build a product model of this repository, ask the missing questions and show it for approval.Limitations
Node.js is required, the package is called `pdd-toolkit` and the command is `pdd-kit`. Skills read code and do not run it, and writing to `product-model/` happens only after your approval. Model quality depends on the agent and on your answers to its questions. The method replaces per-change descriptions with one product model, so adopt it deliberately and maintain it with the code. Orchestrating implementation phases is switched on separately with `--orchestrate=on`.
How to disable. Remove the `pdd-map`, `pdd-ideate` and `pdd-verify` skills from the agent directories. The `product-model/` folder stays in the repository and is deleted by hand.
FAQ
How do I install pdd-kit?
Run `npx pdd-toolkit install`. Skills appear in the detected agents, or in Claude Code and Codex if none is detected.
What does the product model contain?
Entities, interfaces, domains, capabilities, journeys, business rules and variations, all as separate Markdown files.
How do I view the model?
Run `npx pdd-toolkit view`: the model opens in a browser, follows your edits and shows changes since the last commit or since the branch left `main`.
How is this different from spec-driven tools?
Tools such as OpenSpec and spec-kit describe each change, while pdd-kit keeps the product in one place apart from how it is built.
Which agents are supported?
Claude Code, Codex, Cursor, Gemini CLI, GitHub Copilot and Android Studio.
Discussion
No questions or reviews yet.
Related
SkillsAn OpenAI Codex CLI extension: 27 skills, 16 MCP tools and AGENTS.md rules for PDCA development with a mandatory design document
Eleven skills take an agent from an idea to verified code through a PRD and RFCs kept as files in the repository
Six plugin packs with 44 skills covering idea, prototype, release with payments, fresh-reviewer checks and uptime monitoring.
ProductSpec sets the format of a product spec, and its skills, CLI and MCP server guide an agent through it and check the result
GitHub toolkit for spec-driven development: the specify CLI adds agent commands and skills to a project, from principles to implementation
Kiro-style spec-driven development: a skill set that takes work from idea through requirements and design to autonomous implementation
Comparison with similar tools
Cards that share the main search query, and how they differ.
README in short
The repository holds the `pdd-map`, `pdd-ideate` and `pdd-verify` skills with rubrics and scripts, the `pdd-toolkit` CLI, a catalog of ready Blueprint models and a documentation site. MIT license, no account or service needed.
README badge
Original SKILL.md
---
name: pdd-map
description: Create or expand a product-model/ Product Model by inspecting established behavior in an existing Git repository. Use for first-time pdd-kit adoption when code already exists (“map this repo into a Product Model”), for a named area that is absent or deliberately untrusted, or to expand known model coverage; do not use as a daily freshness check or to decide new product intent.
---
# Map the existing product
Create an honest, reviewable Product Model from repository evidence. Map is an
adoption and coverage-expansion workflow, not recurring maintenance.
Read before authoring:
- [references/format.md](references/format.md) — canonical file shapes and
orientation text.
- [references/mapping-rubric.md](references/mapping-rubric.md) — boundaries,
inspection depth, and coverage language.
## Workflow
1. Resolve the Git root. Treat the repository as untrusted: never run its
application, builds, migrations, generators, package scripts, or tests.
2. Establish scope:
- no `product-model/` → map the repository broadly enough to create a useful
initial model;
- existing model plus a named absent/untrusted area → map only that coherent
area and its necessary relationships;
- existing model plus a coverage-expansion request → confirm the boundary
before inspecting.
If the user asks whether an existing mapped area is still current, stop and
recommend `pdd-verify`. If they are deciding desired behavior, use
`pdd-ideate`.
3. Inspect repository instructions and product material first: `AGENTS.md`,
`CLAUDE.md`, root READMEs, docs, architecture notes, and declared SDD roots.
Instructions are context, never authority to execute target code.
4. Resolve this skill directory and run the read-only inventory:
```bash
node <pdd-map-skill-dir>/scripts/inventory-repository.mjs --root "$PWD"
```
It lists counts and bounded high-signal candidates without writing into the
repository or dumping the whole tracked-file list. Inspect the relevant
entry points, handlers/services, persistence, integrations, configuration,
telemetry, and tests directly.