[{"data":1,"prerenderedAt":539},["ShallowReactive",2],{"faq-page":3},{"title":4,"description":5,"content":6},"FAQ","Where to start from an existing repo, an idea, or a Blueprint — and what Product-Driven Development costs, sends, and replaces.",{"hero":7,"groups":8,"cta":531},{"title":4},[9,112,180,364,460],{"id":10,"title":11,"description":12,"questions":13},"why-a-product-model","Why a Product Model","How the model relates to the documentation, agent instructions, and knowledge you already have.",[14,62,87],{"label":15,"answer":16,"stack":40},"We already have documentation. Why do we need a Product Model?",[17,29],[18,20,23,25,27],{"text":19},"Your product definition is scattered across multiple information sources, and ",{"text":21,"bold":22},"some of it might not appear anywhere at all",true,{"text":24},". Each source holds a piece, none holds all of it, and they drift from each other. The Product Model brings order: ",{"text":26,"bold":22},"a structured, single definition of what the product is",{"text":28},", readable and maintainable by both humans and coding agents.",[30,32,34,36,38],{"text":31},"Yes, it is a new source. But it makes every other source ",{"text":33,"bold":22},"leaner and focused on its own concern",{"text":35},". The model becomes the core: documentation can teach users and include the product knowledge they need, without doubling as a spec for contributors. Architecture files can describe how the system is built. Design files can shape how it looks. Code can implement. Each source draws from the model what its audience needs, and carries material that is not product definition at all (setup guides, style systems, deployment configuration, onboarding). It also ",{"text":37,"bold":22},"makes uncovered aspects visible",{"text":39},": if something is not in the model, nobody decided it.",{"lead":41,"caption":42,"layers":43},"With the model as the foundation, each source focuses on what it is good at.","What each source of information focuses on when the Product Model holds the product definition",[44,47,50,53,56,59],{"label":45,"description":46,"highlight":22},"Product Model","Defines what the product is",{"label":48,"description":49},"User-facing documentation","Teaches people to use the product",{"label":51,"description":52},"Internal documentation","Records architecture, design decisions, and onboarding",{"label":54,"description":55},"Design and architecture","Describes how it should look and work",{"label":57,"description":58},"Code and tests","Implements and verifies how it is built",{"label":60,"description":61},"Tickets, chats, and people","Carry context, requests, and undocumented knowledge",{"label":63,"answer":64},"We already have AGENTS.md and docs. Isn't that enough?",[65,80],[66,68,70,72,74,76,78],{"text":67},"It can, and they help. But user docs hold the user subset, and even internal docs are free-form: each written its own way, with no common structure, ",{"text":69,"bold":22},"mixing product decisions with design and implementation",{"text":71},". The rest stays in the code, or worse, ",{"text":73,"bold":22},"is not defined anywhere at all",{"text":75},". Every agent reconstructs it from scratch, possibly differently each time, ",{"text":77,"bold":22},"with nobody reviewing what it concluded",{"text":79},".",[81,83,86],{"text":82},"The model is a structured way to define a product: a fixed set of resource types (entities, interfaces, capabilities, scenarios, business rules, variations) and how they connect. Technical aspects (architecture, design docs, ADRs) stay out of it, so you keep maintaining those however you like. ",{"text":84,"to":85},"Read why your agent is guessing","\u002Fblog\u002Fyour-agent-is-guessing",{"text":79},{"label":88,"answer":89},"Why a structured format instead of free-form documentation?",[90,97,109],[91,93,95],{"text":92},"The format is the point. I have spent the recent months building this, drawing on years of product and engineering experience to pin down ",{"text":94,"bold":22},"where the boundary between product and non-product falls",{"text":96},": what belongs in the model (entities, interfaces, capabilities, scenarios, business rules, variations) and what stays out (architecture, layout, API style, libraries). That boundary is what makes the model useful.",[98,100,103,105,107],{"text":99},"A well-defined format means agents achieve greater accuracy because they know exactly where to find each decision and how the pieces connect. It means humans can review the entire product in a rich, visual report using the ",{"text":101,"to":102},"view command","\u002Fdocs\u002Fcli-view",{"text":104}," instead of piecing it together from scattered sources. And it means different roles in the organization, from product to engineering to design, finally ",{"text":106,"bold":22},"see the same definition and evolve it together",{"text":108}," in the most structured way they have ever had.",[110],{"text":111},"The format is still in its early phases. It will evolve as adoption grows and feedback comes in, and it is open source precisely so that evolution is shared.",{"id":113,"title":114,"description":115,"questions":116},"adopting-it","Adopting it","What changes for your team, your workflow, and your reviews — and what does not.",[117,134,144,158,168],{"label":118,"answer":119},"Why should we add yet another tool to our stack?",[120,127],[121,123,125],{"text":122},"PDD is not a standard tool you add to your workflow. It is a format, and the tooling around it just helps maintain it. The product definition ",{"text":124,"bold":22},"already exists",{"text":126},", scattered across docs, code, tickets, and people. PDD gives it a structured home so the rest of your tools can do their jobs better.",[128,130,132],{"text":129},"Contributors who do not use agents work exactly as they do today. ",{"text":131,"bold":22},"Updating the model is the same kind of work",{"text":133}," as updating docs or tests when behavior changes, not a new kind. You control when in your existing development loop the model gets updated and by whom, although the recommendation is to update the model before initiating new work as a best practice.",{"label":135,"answer":136},"Doesn't this lock me into a new development lifecycle?",[137],[138,140,142],{"text":139},"No. ",{"text":141,"bold":22},"PDD does not touch how you implement",{"text":143},". You keep your current workflow, your coding agent, your planning tools. What PDD adds is a structured format for the product definition you already have, informally scattered across docs, code, tickets, and people. You are not adopting a new paradigm; you are giving a home to decisions that today live nowhere in particular.",{"label":145,"answer":146},"Doesn't keeping the model current add work to every PR?",[147],[148,150,152,154,156],{"text":149},"The split makes maintenance easier, not harder. Today a behavior change can touch the code, the user docs and any internal docs, each holding part of it in its own way, so they drift and nobody knows which one is right. With the model, ",{"text":151,"bold":22},"each fact has one home",{"text":153},": the agent updates the model along with the code, and the user docs take the part users need from it, adding only what is truly user-facing (installation, setup, examples). ",{"text":155,"bold":22},"It does not have to block a PR either",{"text":157},": the model can catch up after changes land.",{"label":159,"answer":160},"How do reviewers see a model change?",[161],[162,164,167],{"text":163},"Currently a model change can only be reviewed as a Git diff. That is a gap being closed: every change to the model will be visualized in a diff mode in the report. In the flow we envision, that change is reviewed and approved first, before implementation even starts. ",{"text":165,"to":166,"external":22},"Follow the diff visualization issue","https:\u002F\u002Fgithub.com\u002Fitai-gendler\u002Fpdd-kit\u002Fissues\u002F19",{"text":79},{"label":169,"answer":170},"Can I share the report without running it locally?",[171,174,177],[172],{"text":173},"Local only today, but one command opens the model of any PR without cloning:",[175],{"text":176,"code":22},"npx @itai-gendler\u002Fpdd-kit view \u003Cowner>\u002F\u003Crepo> --pr \u003Cn>",[178],{"text":179},"A hosted, shareable link is something we are considering, but we do not see it as a blocker.",{"id":181,"title":182,"description":183,"questions":184},"what-it-is","What it is and isn't","How the Product Model relates to SDD frameworks, AI-generated docs, PRDs, user stories, ERDs, and design.",[185,199,209,265,277,324,337],{"label":186,"answer":187},"How is this different from SDD?",[188],[189,191,193,195,198],{"text":190},"They work at different altitudes and are meant to coexist. ",{"text":192,"bold":22},"PDD defines the product, not the change",{"text":194},". Spec-driven frameworks like OpenSpec and spec-kit own the change level: how one piece of work is designed, built, and split into tasks. PDD lets you choose whatever tool you want for implementation. It does not touch that phase. ",{"text":196,"to":197},"Read how PDD and SDD fit together","\u002Fblog\u002Fpdd-and-spec-driven-development",{"text":79},{"label":200,"answer":201},"How is this different from DeepWiki or AI-generated docs?",[202],[203,205,207],{"text":204},"Tools like DeepWiki are useful for exploration, but they mix product rules, architecture, implementation details, and configuration together without drawing a boundary. ",{"text":206,"bold":22},"A Product Model draws that boundary explicitly",{"text":208},": it holds what the product is, and leaves everything else (user docs, internal docs, design, architecture, code) to the sources that already own it.",{"label":210,"answer":211,"comparison":219},"Isn't this just a fancy PRD?",[212],[213,215,218],{"text":214},"A PRD can inform the Product Model, but it does not replace it. Attach it as a PRD Reference with the intent role when it shaped approved meaning, or the context role when it preserves supporting history. The Product Model remains the self-contained statement of what the product has been approved to do. ",{"text":216,"to":217,"external":22},"See how references work","\u002Fdocs\u002Freferences",{"text":79},{"lead":220,"caption":221,"columns":222,"rows":224},"No. A PRD and a Product Model are different artifacts with different jobs.","PRD and Product Model comparison",[223,45],"PRD",[225,230,235,240,245,250,255,260],{"label":226,"values":227},"Primary job",[228,229],"Help a team decide and communicate what product or change to pursue","Keep approved product intent and the implementation aligned over time",{"label":231,"values":232},"Contains",[233,234],"Research, alternatives, assumptions, scope, metrics, rollout plans, and proposed requirements","The resulting durable product decisions",{"label":236,"values":237},"Structure",[238,239],"Flexible and chosen for the document","A defined, repeatable structure of resource types and relationships",{"label":241,"values":242},"Scope",[243,244],"May cover a feature, initiative, or entire product","Connects the modeled product scope in one coherent definition",{"label":246,"values":247},"Lifetime",[248,249],"Often follows a decision or initiative and may later become historical","Evolves with the product and remains versioned alongside the implementation",{"label":251,"values":252},"Audience",[253,254],"Primarily supports human discussion and approval","Designed to be read by both people and coding agents",{"label":256,"values":257},"Relationship to code",[258,259],"Informs implementation but is not normally checked against it","Can be linted, built from, and verified against the implementation",{"label":261,"values":262},"Role in PDD",[263,264],"Optional decision record and supporting evidence","Required source of truth and build-and-verification contract",{"label":266,"answer":267},"Why doesn't the product model have a user story resource type?",[268,271],[269],{"text":270},"A user story can describe one ability, one acceptance case, or an entire multi-ability goal, depending on how a team sizes its backlog. It therefore has no single Product Model equivalent.",[272,274,276],{"text":273},"pdd-kit maps its lasting meaning instead: the Entity that acts, a Capability and its Capability Scenarios for one ability, or a Journey and its Journey Scenarios for a broader goal. The original Jira story can remain linked as a context Reference. ",{"text":275,"to":217,"external":22},"Link external work with references",{"text":79},{"label":278,"answer":279,"comparison":290},"Isn't the Product Model just an ERD?",[280,283],[281],{"text":282},"Only its top layer, and deliberately. An ERD is usually drawn at three levels: conceptual entities and their relationships, then logical attributes and keys, then physical tables and types. The Product Model works at the conceptual level and stops there. It also carries three things no ERD has: a lifecycle for each thing, composed from every Scenario Step that creates, changes, or removes it; edges into behavior, because a Step declares what it does to a thing and a Screen declares which facts it shows and which it collects; and who may act, because a Business Rule says who may perform an operation on a thing.",[284,286,289],{"text":285},"Neither replaces the other. An ERD answers how the data is shaped; the Product Model answers what the product keeps and what changes it. An engineer designing storage still needs types, keys, and indexes, and none of them belong in the model. Attach the schema as a Reference with the implementation role instead — realization, never meaning. ",{"text":287,"to":288},"Read how Entities carry product meaning","\u002Fdocs\u002Fentities",{"text":79},{"lead":291,"caption":292,"columns":293,"rows":295},"No. They describe different things, and only the top layer overlaps.","ERD and Product Model comparison",[294,45],"ERD",[296,301,305,310,315,320],{"label":297,"values":298},"Question it answers",[299,300],"How is the data shaped and stored","What does the product keep, and what changes it",{"label":231,"values":302},[303,304],"Entities, attributes, keys, cardinality, types, indexes, and join tables","Things a user can point at, what the product keeps about them, and how they relate",{"label":306,"values":307},"Lifecycle",[308,309],"None — an ERD does not describe a thing changing","States, with transitions composed from the Scenario Steps that create, change, or remove a thing",{"label":311,"values":312},"Link to behavior",[313,314],"None","Steps declare what they do to Entities, and Screens the facts they show and collect",{"label":316,"values":317},"What it excludes",[318,319],"Nothing about storage — that is its subject","Types, keys, indexes, and join tables; a thing no user can name is a table, not an Entity",{"label":261,"values":321},[322,323],"Optional implementation Reference alongside the model","The product-level source of truth the implementation is verified against",{"label":325,"answer":326},"Is the Product Model a design spec?",[327,330],[328],{"text":329},"No, and deliberately not. A design system answers how the product looks and is built; the model answers what an Actor can reach, see, do and trigger at each place: the facts a Screen shows or collects, the abilities it offers, who may act, and what happens next.",[331,333,336],{"text":332},"One test decides every case: rebuild a view with a different component library, layout, colors and copy. Whatever would still have to be true is the model's; whatever the redesign is free to change is design's. Design files attach to the place they shape as References. ",{"text":334,"to":335},"Read where the model stops and design begins","\u002Fdocs\u002Finterfaces#is-this-a-design-spec",{"text":79},{"label":338,"answer":339,"boundary":346},"Does the Product Model replace my UI\u002FUX design?",[340],[341,343,345],{"text":342},"To tell which side something falls on, imagine rebuilding the product from scratch: a web app on a different component library, a CLI with a different command style, an API in RPC instead of CRUD. Whatever would still have to be true after the rebuild is the model's; whatever the rebuild is free to change is design. Design files, help text and API descriptions attach to the place they shape as References. ",{"text":344,"to":335},"Read where the model stops",{"text":79},{"lead":347,"kept":348,"left":356},"No. It holds the experience your design has to serve, never the design itself.",{"label":349,"items":350},"In the model",[351,352,353,354,355],"Who can reach each place","What it shows and asks for","What can be done there","Which rules apply","What happens next",{"label":357,"items":358},"Left to design",[359,360,361,362,363],"Colors, typography, copy","Components, layout, modals","Tabs, wizards and menus","CLI syntax and flags","API style: CRUD or RPC",{"id":365,"title":366,"description":367,"questions":368},"getting-started","Getting started","Three ways in, what each one leaves in your repository, and the projects supported today.",[369,382,395,408,421,434,451],{"label":370,"answer":371},"I already have a codebase — where do I start?",[372,375],[373],{"text":374},"Install the skills and run \u002Fpdd-map. It reads the code without running it, asks what the code can’t settle, and writes product-model\u002F only after you approve. npx @itai-gendler\u002Fpdd-kit view then opens it as a report.",[376,378,381],{"text":377},"Nothing is rewritten and no framework is imposed; the model is added beside the code. ",{"text":379,"to":380},"Walk through mapping an existing product","\u002Fdocs\u002Ffrom-your-repo",{"text":79},{"label":383,"answer":384},"I have an idea but nothing built yet.",[385,388],[386],{"text":387},"Start by deciding what the product is. Ideation proposes distinct product shapes — who each one serves, the single job it does, and what it deliberately is not — and writes nothing until you pick one. The same conversation turns your approved choice into the model your coding agent implements.",[389,391,394],{"text":390},"That order matters: an agent given a one-line idea invents the missing product decisions silently. ",{"text":392,"to":393},"Walk through starting from an idea","\u002Fdocs\u002Ffrom-an-idea",{"text":79},{"label":396,"answer":397},"I want to start from something proven.",[398,401],[399],{"text":400},"Pull a Blueprint. It expands into an empty directory as a complete Product Model you can hand straight to a coding agent, and you choose the stack. A Blueprint carries the product definition, not an implementation.",[402,404,407],{"text":403},"Every Blueprint has cleared the same bar: given the pulled model and the words “build this” and nothing else, an agent ships a working product. ",{"text":405,"to":406},"Browse the Blueprints","\u002Fblueprints",{"text":79},{"label":409,"answer":410},"What actually lands in my repository?",[411,414],[412],{"text":413},"A product-model\u002F directory of Markdown files — the Product and its Entities, the people and systems that act on it among them, Interfaces, optional Experiences, Screens and Domains, Capabilities with local Scenarios, optional Journeys with end-to-end Scenarios, Business Rules, and Variations where one product choice has several supported answers. Plain text, reviewable in a pull request, versioned with the code it describes.",[415,417,420],{"text":416},"No database, no service, and no lock-in: delete the directory and your repository is exactly as it was. ",{"text":418,"to":419},"Read about the Product Model","\u002Fdocs\u002Fproduct-model",{"text":79},{"label":422,"answer":423},"When do I use map, and when do I use verify?",[424,427],[425],{"text":426},"Map is for adoption, a deliberately untrusted area, or expanding model coverage. It is not a daily command. Verify is for normal product changes, refactors, suspected drift, pre-release checks, and full or named current-state audits.",[428,430,433],{"text":429},"You rarely name either. Ask your agent to implement a change and PDD will run it in phases: your agent implements each phase, and verify checks it before the next. Ask whether the code still matches the model whenever you want to be sure, for example before a release. ",{"text":431,"to":432},"Read the verification loop","\u002Fdocs\u002Fskill-pdd-verify",{"text":79},{"label":435,"answer":436},"Is this meant for open-source projects or also closed-source commercial ones?",[437,444],[438,440,442],{"text":439},"Both. ",{"text":441,"bold":22},"Open-source projects are natural candidates",{"text":443}," because most of their information sources are already in the repository, and they usually live in a single repo.",[445,447,450],{"text":446},"Closed-source commercial projects benefit just as much, as long as the project is in a single repository. Multi-repository support is planned. ",{"text":448,"to":449,"external":22},"Follow the multi-repository support issue","https:\u002F\u002Fgithub.com\u002Fitai-gendler\u002Fpdd-kit\u002Fissues\u002F17",{"text":79},{"label":452,"answer":453},"My product spans multiple repositories — is that supported?",[454],[455,457,458],{"text":456},"Not yet. pdd-kit currently works with one repository at a time. ",{"text":448,"to":449,"external":22},{"text":459}," for the design and implementation progress.",{"id":461,"title":462,"description":463,"questions":464},"trust-and-help","Trust and help","What it costs, what leaves your machine, and where to get help.",[465,474,492,498,515],{"label":466,"answer":467},"What does it cost?",[468,471],[469],{"text":470},"Nothing, and there is nothing to buy. The format, the CLI, the skills, and the Blueprints are all MIT licensed. There is no pricing page, no plan, and no billing.",[472],{"text":473},"The framework is useful entirely on its own, with no account and no hosted service. If that ever changes, it will not change what the MIT licensed framework already gives you.",{"label":475,"answer":476},"Does my code leave my machine?",[477,480],[478],{"text":479},"The pdd-kit CLI does not upload your code or Product Model. Linting, export, and expanding a pulled model run locally. The map, ideate, and verify skills run inside the coding-agent harness you chose, so that harness’s data handling and permissions still apply.",[481,483,486,488,491],{"text":482},"The CLI reaches the network only for explicit operations: listing and pulling download Blueprints from a GitHub Release, contributing uses your own authenticated GitHub CLI to open a public pull request, and running the package through npx contacts the registry. Everything the CLI does is auditable in the ",{"text":484,"to":485,"external":22},"public source","https:\u002F\u002Fgithub.com\u002Fitai-gendler\u002Fpdd-kit",{"text":487},". What we collect is set out in the ",{"text":489,"to":490},"privacy policy","\u002Fprivacy",{"text":79},{"label":493,"answer":494},"Do I need an account?",[495],[496],{"text":497},"No. Listing and pulling Blueprints are anonymous — no account, sign-in, or credential is involved at any point, and the site has no accounts at all.",{"label":499,"answer":500},"How do I contribute a Blueprint?",[501,508],[502,504,506],{"text":503},"By pull request against ",{"text":505,"to":485,"external":22},"itai-gendler\u002Fpdd-kit",{"text":507},". The CLI drives it, projecting away repository-local implementation paths so the contribution carries the product and nothing from your repository.",[509,511,514],{"text":510},"The bar is an executable brief: small enough for an agent to build end to end, complete enough that nothing is missing, and generic rather than a model of a named product. The test is whether a coding agent that has never seen it can build the product from “build this” alone. ",{"text":512,"to":513,"external":22},"Read the contributing guide","https:\u002F\u002Fgithub.com\u002Fitai-gendler\u002Fpdd-kit\u002Fblob\u002Fmain\u002FCONTRIBUTING.md",{"text":79},{"label":516,"answer":517},"Where do I get help?",[518],[519,521,524,526,529],{"text":520},"Bugs, missing product concepts, and format questions belong in ",{"text":522,"to":523,"external":22},"GitHub issues","https:\u002F\u002Fgithub.com\u002Fitai-gendler\u002Fpdd-kit\u002Fissues",{"text":525},". Security reports go through the ",{"text":527,"to":528,"external":22},"security policy","https:\u002F\u002Fgithub.com\u002Fitai-gendler\u002Fpdd-kit\u002Fblob\u002Fmain\u002FSECURITY.md",{"text":530}," rather than a public issue.",{"title":532,"description":533,"primary":534,"secondary":536},"Still have a question?","Ask it in a GitHub issue, or start with the docs.",{"label":535,"to":523},"Open an issue",{"label":537,"to":538},"Read the docs","\u002Fdocs",1791840531133]