Skip to content
Projects

itai-gendler/pdd-kit has 106 GitHub stars and 11 forks. GitHot measured 0 stars in 24 hours and +1 in 7 days. Last checked 2026-11-17 02:49 UTC. Last push 2026-11-15.

How these counts are measured

What you can do

  • Card proposals creates a proposed card, never a card.
  • Proposed card acceptance is what turns it into a card on the board.
  • Proposed card dismissal changes the proposal and leaves the board alone.
  • The agent connection offers one capability: proposing cards.

Measured star growth

in 24h
0
in 7 days
+1
in 15 days
Collecting history
in 1 month
Collecting history

Net star changes over overlapping periods, not daily totals. Missing measurements are left blank. Stars measure attention, not software quality.

About

Product-Driven Development for coding agents

Developer Tools

README.md

Original

pdd-kit

Product-Driven Development for coding agents (OSS)

The definition of your product already exists, just unstructured, incomplete and scattered across docs, code, tickets, chats and people.
Every coding agent reconstructs it from scratch, and differently each time.
PDD gives agents and humans a shared product model that is git-tracked, reviewable, and verifiable.

npm version Check MIT license

npx pdd-toolkit install

Map your own repo today!

The problem · The Product Model · Where it fits · Example · Get started · Development loop · FAQ

The problem

The definition of your product already exists, just unstructured, incomplete and scattered across docs, code, tickets, chats and people. Every coding agent reconstructs it from scratch, and differently each time (AI is writing code for products it doesn't understand).

Spec-driven development (SDD) tools such as OpenSpec, spec-kit and Kiro describe each change, with the product mixed into its design, plan and tasks and spread across feature folders (SDD describes the change, not the product).

Product-Driven Development (PDD) keeps the product in one place, apart from how it's built: a shared product model for agents and humans that is git-tracked, reviewable and verifiable (Introducing pdd-kit).

The Product Model

product-model/, a Product Model: one definition of what the product does, as plain Markdown next to the code. It is made of:

  • Entities: what the product keeps, and who acts on it (Order, Customer, Payment provider).
  • Interfaces: how people and systems reach the product (Web app, Mobile app, Partner API).
  • Domains: the subject areas the product is split into (Ordering, Catalog, Billing).
  • Capabilities: what the product lets someone do (Check out, Cancel order, Refund).
  • Journeys: one goal, carried across several capabilities (Browse and buy, Sign up, Reorder).
  • Business Rules: what must always hold, and who may do what (Max 3 per order, Only managers refund, Total includes tax).
  • Variations: where the product works in more than one way (Feature flag, Plan tier, A/B test).

Clear product model. Focused sources.

Bring knowledge from docs, designs, code, and people into one product model. Fill gaps, clarify uncertainty, and make every source leaner and more focused.

An engraved wheel with the product model at its center, connecting user-facing documentation, internal documentation, design and architecture, code and tests, and tickets, chats, and people.

Each information source’s purpose, supported by a shared product model

Information source Purpose
User docs Teaches people to use
the product
Internal docs Records architecture, design
decisions, and onboarding
Design &
architecture
Describes how it should
look and work
Code & tests Implements and verifies
how it is built
Tickets, chats
& people
Carry context, requests,
and undocumented knowledge

More in the FAQ: Why a Product Model.

Why a Product Model in the AI era

Agents write code faster than anyone can explain to them what the product is. They fill the gaps by guessing, and the guesses ship.

  1. One definition. Not scattered across tickets, docs, chats and people, but one model beside the code.
  2. Agents know what to build. They read the Journeys, Scenarios and Rules instead of guessing.
  3. Done means it matches the product. Verify checks the code against the approved model.
  4. Drift is easy to spot. The model stays a clear reference as behavior changes.
  5. Decisions travel with the code. Model and code changes are reviewed in one pull request.

Today, every stage of plan, code, review, deploy and operate reconstructs intent from tickets, PRDs, docs, tests, code, chats and people. With Product-Driven Development, those sources feed one defined, versioned, agreed product model, and every stage reads from it, with human approval at plan and review.

Example: the Product Model of a kanban board

To show what a Product Model answers, here is one for a kanban board: a conceptual product where a small team plans its work on shared boards of columns and cards, and an AI agent proposes the next cards. It is the Kanban Board Blueprint, a model with no code behind it. Every answer below is read from the model.

The Kanban Board Blueprint open in the pdd-kit report: the Product Overview with its description, intent and product details

View the Kanban Board Product Model live

Or open it on your machine:

npx pdd-toolkit blueprint pull kanban-board
npx pdd-toolkit view

1. Entities, and which capabilities change them

All 9 entities in the kanban model: what the product keeps, and who acts on it.

Entities list: the start of the kanban model's 9 entities, grouped by domain

Which capabilities create, change or remove each entity, filtered to the four capabilities around a proposed card:

  • Card proposals creates a proposed card, never a card.
  • Proposed card acceptance is what turns it into a card on the board.
  • Proposed card dismissal changes the proposal and leaves the board alone.
Changes, filtered to four capabilities: Card and Proposed card against Card proposals, Proposed card acceptance, Proposed card dismissal and Card creation

2. Capabilities, and which interfaces offer them

All 23 capabilities in the kanban model: what the product lets someone do.

Capabilities list: the start of the kanban model's 23 capabilities, grouped by domain

Which interfaces offer each capability, filtered to six card capabilities:

  • The agent connection offers one capability: proposing cards.
  • Every change to a card happens in the board web application, by a member.
Delivery, filtered to six card capabilities: which of them the Agent connection and the Board web application offer

3. Business rules, and where they apply

All 32 business rules in the kanban model: what must always hold, and who may do what.

Business rules list: the start of the kanban model's 32 business rules, grouped by domain

Where each business rule is attached, filtered to the five attached to the Proposed card entity:

  • Creating one: only an AI agent a member connected proposes cards.
  • Deciding on one: only the board's members accept or dismiss it.
  • Deleting one: it goes only with its board.
Attachments, filtered to the Proposed card entity: five business rules, as creates, changes, reads, removes and attached

4. An entity: what it keeps, and how its state changes

The Proposed card entity, one of the 9, and the information kept about it:

  • Four pieces of information: its title, description, reason and suggested column.
Proposed card overview: its description and the four pieces of information it keeps

How it moves through its states, and the capability behind every move:

  • Three states: Proposed, then Accepted or Dismissed. Created and Removed mark where its life begins and ends.
  • Removing it on its own is forbidden from every state; deleting its board removes it.
Proposed card lifecycle: Card proposals creates it in Proposed; members accept or dismiss it. Removing it on its own is forbidden; deleting its board removes it

5. A capability's scenarios, and one step by step

The 4 scenarios of the Card proposals capability:

  • Four scenarios: proposing cards for a goal, proposing a next step for a stalled card, and two refusals.
Card proposals scenarios: the four scenarios with their triggers and outcomes

One of them, opened step by step:

  • Refuse a direct change from the AI agent: the agent tries to move a card itself, and the product refuses. Every step says who acts, what is read, where, and which business rules govern it.
  • Its edge case: editing, deleting or creating a card, or accepting its own proposal, is refused the same way.
The Refuse a direct change from the AI agent scenario: three steps, each with who acts, entity effects, where and the governing business rules, and its edge case

Review a change as a product change

In a Git repository, npx pdd-toolkit view also shows what changed in the model: your uncommitted edits, or everything since your branch left main, as a pull request shows it. Here is pdd-kit's own model on the branch that added the feature:

  • Every change reads as a sentence, grouped by Domain: a new Screen, two Screens that now host a new Scenario's Steps, and a Capability whose description changed.
Changes since origin/main in pdd-kit's own model: five changed resources in the Model inspection domain, two added and three modified, each read as a sentence
  • Each changed resource has a Changes tab with its before and after: here the new paragraph in the Capability's description, its two new References and its new Scenario.
The View the Product Model Capability's Changes tab: its description with the added paragraph highlighted, two added References, and its added Scenario

The earlier version is read from Git without touching your checkout.

Who it helps

One shared definition of what the product does helps everyone who works on it:

  • Maintainers and reviewers see a behavior change as a change to the model, reviewed in the same pull request as the code.
  • New contributors learn what the product does, who may do what and where, without reading the whole codebase first.
  • Product managers and docs writers find product answers in one place, with optional references to the code and material behind them.
  • Coding agents read the scenarios and business rules before they change anything, instead of guessing. The pdd-verify skill checks the code against the model.

Dogfooded: pdd-kit is developed with pdd-kit. Its own Product Model lives in this repository's product-model/ folder; open it with npx pdd-toolkit view itai-gendler/pdd-kit.

Features

  • 🤖 Agent skills: map, ideate and verify for Claude Code, Codex, Cursor, Gemini CLI and GitHub Copilot

  • 📝 Markdown-native: every resource is a plain .md file in your repo, reviewed in pull requests

  • ✅ Lint and verify: npx pdd-toolkit lint checks the files; pdd-verify checks the code against them

  • 🔁 Fits your workflow: implement with plan mode, an SDD tool or freestyle; check the code against the model when you choose

  • 🖥️ Local report: npx pdd-toolkit view opens the model in your browser, follows your edits, and shows what changed since your last commit or since your branch left main

  • 📦 Blueprints: start from a reviewed model for a common product instead of a blank page

  • 🔒 Local-first: no account, no hosted service; the skills read your code and never run it

  • 🆓 MIT-licensed and open source


Get started

npx pdd-toolkit install

The npm package is pdd-toolkit; it installs the pdd-kit command, so after npm install --global pdd-toolkit you can run pdd-kit install instead.

This adds the skills to the coding agents it detects (Claude Code, Codex, Cursor, Gemini CLI or GitHub Copilot), or to Claude Code and Codex when it detects none; you can change the selection. Then start from where you are, inside your agent (Codex uses $ instead of /):

Map existing repo (recommended)

Have code? Run the map skill:

/pdd-map

It reads the code without running it, asks what the code can't answer, and writes product-model/ once you approve. Then open the report:

npx pdd-toolkit view

From your repo

Start from an idea

No code yet? Describe the product you want:

/pdd-ideate I want to build a booking app for dog walkers

You pick from a few product shapes, then approve the model. From an idea

Start from a Blueprint

A familiar kind of product? List the reviewed models and pull one:

npx pdd-toolkit blueprint list
npx pdd-toolkit blueprint pull <name>

Browse the Blueprints · From a Blueprint

The development loop

The development loop: ideate with /pdd-ideate, implement your way with your own agent, check the code against the model with /pdd-verify

  • Ideate (/pdd-ideate): the agent records the change in the model first, and nothing is written until you approve it.
  • Implement: your agent builds it your way, with plan mode, an SDD tool, or freestyle. pdd-kit doesn't change how you implement.
  • Verify (/pdd-verify): the agent checks the code against the model, reports every gap, and fixes the ones you choose.

Optionally, let pdd-kit orchestrate the implementation and verification loop: verify plans the work in phases, your agent implements each phase, and verify checks it before the next. Turn it on with npx pdd-toolkit install --orchestrate=on or one sentence in your AGENTS.md; see Implement with verify.

CLI

install, update, lint, view and the blueprint commands. Every command and option: CLI reference, or npx pdd-toolkit --help.

FAQ

Read the frequently asked questions about adopting pdd-kit, what the Product Model covers, and getting help.

License

pdd-kit is released under the MIT License: do anything, just give credit. See LICENSE.