[Extension]: Add Product Definition as Code (PDaC) (pdac) #4454

Extension ID

pdac

Extension Name

Product Definition as Code (PDaC)

Version

0.2.1

Description

Ground Spec Kit features in an accepted product definition: fetch a cited context projection before specifying, then verify citations after specify, plan and tasks. Never writes the product model.

Author

Juan G. Carmona (@juangcarmona)

Repository URL

https://github.com/juangcarmona/productshape

Download URL

https://github.com/juangcarmona/productshape/releases/download/speckit-pdac-v0.2.1/speckit-pdac.zip

License

Apache-2.0

Homepage (optional)

https://pdac.dev

Documentation URL (optional)

https://github.com/juangcarmona/productshape/blob/main/extensions/speckit-pdac/README.md

Changelog URL (optional)

https://github.com/juangcarmona/productshape/blob/main/extensions/speckit-pdac/CHANGELOG.md

Required Spec Kit Version

=0.7.2

Required Tools (optional)

• prodshape (>=0.16.0) - required. The ProductShape CLI, installed in the consumer repository with npm install --save-dev @prodshape/cli; both commands run it. Needs Node.js 22 or newer. The three hooks degrade to a successful no-op in a workspace without it, so a missing ProductShape never breaks a Spec Kit run.

Number of Commands

2

Number of Hooks (optional)

3

Tags

product, citations, pdac, traceability, governance

Key Features

• speckit.pdac.context fetches a bounded, cited context projection of the product artifacts a feature implements (actors, journeys, use cases, business rules, requirements) with ready-made citation records, so the spec is grounded in accepted product text instead of a paraphrase.
• speckit.pdac.verify runs deterministic citation verification over the feature's spec.md, plan.md and tasks.md: every citation binds consumer text to an artifact id and a sha256 content digest, and reports current, stale, tampered or unresolved, with stable PRODUCT### codes and exit codes.
• Three optional lifecycle hooks (after_specify, after_plan, after_tasks) run the verification gate automatically; validation.warnings-as-errors in the consumer's ProductShape config decides whether stale citations block.
• Every gated document ends up bound or explicitly exempt with a reasoned pdac-scope declaration, so an ungrounded document is a visible gate failure rather than a silent gap.
• Read-only towards the product model: the extension never writes docs/product/model, which changes only through a Product Change (the separate pdac-product extension, submitted as [Extension]: Add ProductShape PRODUCT workflows (pdac-product) #4453, hosts that lane).

Testing Checklist

• Extension installs successfully via download URL
• All commands execute without errors
• Documentation is complete and accurate
• No security vulnerabilities identified
• Tested on at least one real project

Submission Requirements

• Valid extension.yml manifest included
• README.md with installation and usage instructions
• LICENSE file included
• GitHub release created with version tag
• All command files exist and are properly formatted
• Extension ID follows naming conventions (lowercase-with-hyphens)

Testing Details

Tested on:

• Windows 11, PowerShell 7.6.5, Node.js 24.11.1, Spec Kit 1.0.4 (specify init --integration claude --script ps), @prodshape/cli 0.19.0 and 0.19.1 (current latest).
• Install and registration also verified on Spec Kit 0.7.2 (the declared floor) and 1.0.1: both commands register and all three hooks land.
• The CLI the commands run is exercised on Ubuntu, macOS and Windows with Node 22 and 24 by the ProductShape test suite and CI on every change.

Test project: an isolated Spec Kit project created with specify init, holding a small invoicing product definition (actor, journey, use case, business rule, functional requirement) in docs/product/model, and a delivery feature specs/001-overdue-invoice-display/ taken through specify, plan and tasks.

Test scenarios:

1. Installed from the ProductShape catalog by name (specify extension add pdac) and with specify extension add pdac --from <download URL> into a fresh project; specify extension list and specify extension info pdac show two commands and three hooks. Version 0.2.1 differs from the 0.2.0 archive only in the manifest metadata and the bundled LICENSE; the command files are byte-identical, so the command runs below apply to it.
2. speckit.pdac.context for the rule, the requirement and the use case produced the cited projection with correct digests; the spec was authored from it with three citations and the pdac-scope: cited declaration.
3. The after_specify, after_plan and after_tasks hooks (prodshape citations verify --provider speckit) reported 1, 2 and 3 bound documents with every citation current (3, 4 and 5 citations).
4. Drift: a Product Change that modified the cited business rule made the citations in spec.md and plan.md stale (PRODUCT061, warning, exit 0); with validation.warnings-as-errors: true the same verification exited 1; re-grounding with fresh digests returned every citation to current under both settings.
5. The feature was implemented as a small Node module with tests from the grounded tasks.

Example Usage

# Install through the ProductShape catalog (pins the release asset and its sha256)
specify extension catalog add https://raw.githubusercontent.com/juangcarmona/productshape/main/extensions/catalog.json --name pdac --install-allowed
specify extension add pdac

# Or directly from the release archive
specify extension add pdac --from https://github.com/juangcarmona/productshape/releases/download/speckit-pdac-v0.2.1/speckit-pdac.zip

# The CLI both commands run
npm install --save-dev @prodshape/cli
npx prodshape integration add speckit

# In the agent: ground the spec, then let the hooks verify after specify, plan and tasks
/speckit.pdac.context BR-INVOICE-DUE-001 FR-INVOICE-DUE-001
/speckit.specify Show an invoice as overdue once its due date has passed
/speckit.pdac.verify

Proposed Catalog Entry

{
  "pdac": {
    "name": "Product Definition as Code (PDaC)",
    "id": "pdac",
    "description": "Ground Spec Kit features in an accepted product definition: fetch a cited context projection before specifying, then verify citations after specify, plan and tasks. Never writes the product model.",
    "author": "Juan G. Carmona (@juangcarmona)",
    "version": "0.2.1",
    "download_url": "https://github.com/juangcarmona/productshape/releases/download/speckit-pdac-v0.2.1/speckit-pdac.zip",
    "repository": "https://github.com/juangcarmona/productshape",
    "homepage": "https://pdac.dev",
    "documentation": "https://github.com/juangcarmona/productshape/blob/main/extensions/speckit-pdac/README.md",
    "changelog": "https://github.com/juangcarmona/productshape/blob/main/extensions/speckit-pdac/CHANGELOG.md",
    "license": "Apache-2.0",
    "category": "process",
    "effect": "read-write",
    "requires": {
      "speckit_version": ">=0.7.2",
      "tools": [
        {
          "name": "prodshape",
          "version": ">=0.16.0",
          "required": true
        }
      ]
    },
    "provides": {
      "commands": 2,
      "hooks": 3
    },
    "tags": ["product", "citations", "pdac", "traceability", "governance"]
  }
}

Additional Context

• The extension lives in the ProductShape monorepo under extensions/speckit-pdac/; the release archive is that directory alone, built by the repository's release workflow on the speckit-pdac-v0.2.1 tag. The download URL pins that tag rather than releases/latest, so the entry always names the artifact it serves.
• Installs are served from the ProductShape catalog (extensions/catalog.json), whose entry pins the same asset with its sha256 (0a6722d920ecbdae583b5e2e91da949f096e712d9a6825a4fc0ce0df94a49b05); this listing is for discovery.
• Effect is read-write because speckit.pdac.verify repairs the feature documents it reports on. It never writes the product model.
• Companion extension: pdac-product ([Extension]: Add ProductShape PRODUCT workflows (pdac-product) #4453) hosts the PRODUCT lane that changes the model. Background: Product Definition as Code, https://pdac.dev. Adoption guide for an existing Spec Kit repository: https://github.com/juangcarmona/productshape/blob/main/docs/adoption/existing-speckit-repository.md