![\"pdd-kit\"](\"./layers/nuxt/theme/public/brand/logo/lockup-dark.svg\"){kind=logo}
\n \n \n \n
Product-Driven Development for coding agents (OSS)
\n\nThe definition of your product already exists, just unstructured, incomplete and scattered across docs, code, tickets, chats and people.
\nEvery coding agent reconstructs it from scratch, and differently each time.
\nPDD gives agents and humans a shared product model that is git-tracked, reviewable, and verifiable.\n
\n ![\"npm](\"https://img.shields.io/npm/v/pdd-toolkit\")
![\"Check\"](\"https://github.com/itai-gendler/pdd-kit/actions/workflows/check.yml/badge.svg\"){kind=icon}
\n ![\"MIT](\"https://img.shields.io/badge/license-MIT-blue.svg\"){kind=icon}
\n
\nnpx pdd-toolkit install\n
\nThe problem ·\nThe Product Model ·\nWhere it fits ·\nExample ·\nGet started ·\nDevelopment loop ·\nFAQ\n
\n\n## The problem\n\nThe definition of your product already exists, just **unstructured, incomplete\nand scattered** across docs, code, tickets, chats and people. Every **coding\nagent reconstructs it** from scratch, and **differently each time**\n([AI is writing code for products it doesn't understand](https://pdd-kit.dev/blog/your-agent-is-guessing)).\n\n**Spec-driven development (SDD)** tools such as OpenSpec, spec-kit and Kiro\ndescribe **each change**, with the product mixed into its design, plan and\ntasks and spread across feature folders\n([SDD describes the change, not the product](https://pdd-kit.dev/blog/pdd-and-spec-driven-development)).\n\n**Product-Driven Development (PDD)** keeps the **product in one place**, apart\nfrom how it's built: a shared product model for agents and humans that is\n**git-tracked, reviewable and verifiable**\n([Introducing pdd-kit](https://pdd-kit.dev/blog/introducing-pdd-kit)).\n\n## The Product Model\n\n`product-model/`, a [Product Model](https://pdd-kit.dev/docs/product-model):\none definition of what the product does, as plain Markdown next to the code. It\nis made of:\n\n- **[Entities](https://pdd-kit.dev/docs/entities):** what the product keeps, and who acts on it (Order, Customer, Payment provider).\n- **[Interfaces](https://pdd-kit.dev/docs/interfaces):** how people and systems reach the product (Web app, Mobile app, Partner API).\n- **[Domains](https://pdd-kit.dev/docs/domains):** the subject areas the product is split into (Ordering, Catalog, Billing).\n- **[Capabilities](https://pdd-kit.dev/docs/capabilities):** what the product lets someone do (Check out, Cancel order, Refund).\n- **[Journeys](https://pdd-kit.dev/docs/journeys):** one goal, carried across several capabilities (Browse and buy, Sign up, Reorder).\n- **[Business Rules](https://pdd-kit.dev/docs/business-rules):** what must always hold, and who may do what (Max 3 per order, Only managers refund, Total includes tax).\n- **[Variations](https://pdd-kit.dev/docs/variations):** where the product works in more than one way (Feature flag, Plan tier, A/B test).\n\n## Clear product model. Focused sources.\n\nBring knowledge from docs, designs, code, and people into one product model.\nFill gaps, clarify uncertainty, and make every source leaner and more focused.\n\n![\"An](\"./.github/readme/product-knowledge.webp\")
\n\n*Each information source’s purpose, supported by a shared product model*\n\n| Information source | Purpose |\n| --- | --- |\n| **User docs** | Teaches people to use\n ![\"Today,](\"./.github/readme/today-and-pdd.webp\")
\n
\n ![\"The](\"./.github/readme/report/overview.jpg\")
\n
\nView the Kanban Board Product Model live\n
\n\nOr open it on your machine:\n\n```bash\nnpx pdd-toolkit blueprint pull kanban-board\nnpx pdd-toolkit view\n```\n\n### 1. Entities, and which capabilities change them\n\nAll 9 entities in the kanban model: what the product keeps, and who acts on it.\n\n![\"Entities](\"./.github/readme/report/1a-entities.jpg\")
\n\nWhich capabilities create, change or remove each entity, filtered to the four\ncapabilities around a proposed card:\n\n- **Card proposals** creates a proposed card, never a card.\n- **Proposed card acceptance** is what turns it into a card on the board.\n- **Proposed card dismissal** changes the proposal and leaves the board alone.\n\n![\"Changes,](\"./.github/readme/report/1b-what-changes-what.jpg\")
\n\n### 2. Capabilities, and which interfaces offer them\n\nAll 23 capabilities in the kanban model: what the product lets someone do.\n\n![\"Capabilities](\"./.github/readme/report/2a-capabilities.jpg\")
\n\nWhich interfaces offer each capability, filtered to six card capabilities:\n\n- **The agent connection** offers one capability: proposing cards.\n- **Every change to a card** happens in the board web application, by a member.\n\n![\"Delivery,](\"./.github/readme/report/2b-compare-delivery.jpg\")
\n\n### 3. Business rules, and where they apply\n\nAll 32 business rules in the kanban model: what must always hold, and who may\ndo what.\n\n![\"Business](\"./.github/readme/report/3a-business-rules.jpg\")
\n\nWhere each business rule is attached, filtered to the five attached to the\nProposed card entity:\n\n- **Creating one:** only an AI agent a member connected proposes cards.\n- **Deciding on one:** only the board's members accept or dismiss it.\n- **Deleting one:** it goes only with its board.\n\n![\"Attachments,](\"./.github/readme/report/3b-rule-attachments.jpg\")
\n\n### 4. An entity: what it keeps, and how its state changes\n\nThe Proposed card entity, one of the 9, and the information kept about it:\n\n- **Four pieces of information:** its title, description, reason and suggested\n column.\n\n![\"Proposed](\"./.github/readme/report/4a-proposed-card.jpg\")
\n\nHow it moves through its states, and the capability behind every move:\n\n- **Three states:** Proposed, then Accepted or Dismissed. Created and Removed\n mark where its life begins and ends.\n- **Removing it** on its own is forbidden from every state; deleting its board\n removes it.\n\n![\"Proposed](\"./.github/readme/report/4b-lifecycle.jpg\")
\n\n### 5. A capability's scenarios, and one step by step\n\nThe 4 scenarios of the Card proposals capability:\n\n- **Four scenarios:** proposing cards for a goal, proposing a next step for a\n stalled card, and two refusals.\n\n![\"Card](\"./.github/readme/report/5a-scenarios.jpg\")
\n\nOne of them, opened step by step:\n\n- **Refuse a direct change from the AI agent:** the agent tries to move a card\n itself, and the product refuses. Every step says who acts, what is read,\n where, and which business rules govern it.\n- **Its edge case:** editing, deleting or creating a card, or accepting its own\n proposal, is refused the same way.\n\n![\"The](\"./.github/readme/report/5b-scenario.jpg\")
\n\n## Who it helps\n\nOne shared definition of what the product does helps everyone who works on it:\n\n- **Maintainers and reviewers** see a behavior change as a change to the model,\n reviewed in the same pull request as the code.\n- **New contributors** learn what the product does, who may do what and where,\n without reading the whole codebase first.\n- **Product managers and docs writers** find product answers in one place,\n with optional references to the code and material behind them.\n- **Coding agents** read the scenarios and business rules before they change\n anything, instead of guessing. The `pdd-verify` skill checks the\n code against the model.\n\n**Dogfooded:** pdd-kit is developed with pdd-kit. Its own Product Model\nlives in this repository's [`product-model/` folder](./product-model/); open it\nwith `npx pdd-toolkit view itai-gendler/pdd-kit`.\n\n## Features\n\n* 🤖 **Agent skills:** map, ideate and verify for Claude Code, Codex, Cursor, Gemini CLI and GitHub Copilot\n\n* 📝 **Markdown-native:** every resource is a plain `.md` file in your repo, reviewed in pull requests\n\n* ✅ **Lint and verify:** `npx pdd-toolkit lint` checks the files; `pdd-verify` checks the code against them\n\n* 🔁 **Fits your workflow:** implement with plan mode, an SDD tool or freestyle; check the code against the model when you choose\n\n* 🖥️ **Local report:** `npx pdd-toolkit view` opens the model in your browser and follows your edits\n\n* 📦 **Blueprints:** start from a reviewed model for a common product instead of a blank page\n\n* 🔒 **Local-first:** no account, no hosted service; the skills read your code and never run it\n\n* 🆓 MIT-licensed and open source\n\n---\n\n## ![\"\"](\"./.github/readme/rocket.svg\")
Get started\n\n```bash\nnpx pdd-toolkit install\n```\n\nThe npm package is `pdd-toolkit`; it installs the `pdd-kit` command, so\nafter `npm install --global pdd-toolkit` you can run `pdd-kit install` instead.\n\nThis adds the skills to the coding agents it detects (Claude Code, Codex,\nCursor, Gemini CLI or GitHub Copilot), or to Claude Code and Codex when it\ndetects none; you can change the selection. Then start from where you are,\ninside your agent (Codex uses `$` instead of `/`):\n\n### Map existing repo (recommended)\n\nHave code? Run the map skill:\n\n```text\n/pdd-map\n```\n\nIt reads the code without running it, asks what the code can't answer, and\nwrites `product-model/` once you approve. Then open the report:\n\n```bash\nnpx pdd-toolkit view\n```\n\n[From your repo](https://pdd-kit.dev/docs/from-your-repo)\n\n### Start from an idea\n\nNo code yet? Describe the product you want:\n\n```text\n/pdd-ideate I want to build a booking app for dog walkers\n```\n\nYou pick from a few product shapes, then approve the model.\n[From an idea](https://pdd-kit.dev/docs/from-an-idea)\n\n### Start from a Blueprint\n\nA familiar kind of product? List the reviewed models and pull one:\n\n```bash\nnpx pdd-toolkit blueprint list\nnpx pdd-toolkit blueprint pull \n ![\"The](\"./.github/readme/development-loop.svg\")
\n
![\"\"](\"./.github/readme/square-terminal.svg\")
CLI\n\n`install`, `update`, `lint`, `view` and the `blueprint` commands. Every command\nand option: [CLI reference](https://pdd-kit.dev/docs/cli), or\n`npx pdd-toolkit --help`.\n\n## FAQ\n\nRead the [frequently asked questions](docs/faq.md) about adopting pdd-kit,\nwhat the Product Model covers, and getting help.\n\n## License\n\npdd-kit is released under the **MIT License**: do anything, just give\ncredit. See [LICENSE](./LICENSE).\n","readmeFilename":"README.md"}