[Extension]: Add ProductShape PRODUCT workflows (pdac-product) #4453

Extension ID

pdac-product

Extension Name

ProductShape PRODUCT workflows

Version

0.1.0

Description

Author, refine, validate, apply, archive and recover ProductShape product meaning in a separate Spec Kit lane.

Author

Juan G. Carmona (@juangcarmona)

Repository URL

https://github.com/juangcarmona/productshape

Download URL

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

License

Apache-2.0

Homepage (optional)

https://pdac.dev

Documentation URL (optional)

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

Changelog URL (optional)

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

Required Spec Kit Version

=1.0.4

Required Tools (optional)

• prodshape (>=0.19.0) - required. The ProductShape CLI, installed in the consumer repository with npm install --save-dev @prodshape/cli; every command runs it. Needs Node.js 22 or newer.

Number of Commands

6

Number of Hooks (optional)

0

Tags

product, product-change, recovery, pdac

Key Features

• A separate PRODUCT lane beside the delivery workflow: specify, clarify, plan, tasks and implement are not altered, and nothing is stored under .specify/extensions/.
• speckit.pdac-product.change creates or continues one Product Change under .specify/productshape/changes/<name>/, with --initial for the reserved CHG-INITIAL baseline.
• speckit.pdac-product.refine refines the same change with graph-guided questions, recorded decisions and a persisted impact report.
• speckit.pdac-product.validate runs deterministic overlay validation of the delta against the accepted model, with stable PRODUCT### diagnostic codes and exit codes.
• speckit.pdac-product.apply is human-authorized and fail-closed: it revalidates immediately before writing, refuses before any write when the change is not approved, invalid or its base revision moved, writes only docs/product/model, never commits, and lists every delivery citation the change turns stale.
• speckit.pdac-product.archive files an applied change separately from apply; an applied, unarchived change is inert for concurrency.
• speckit.pdac-product.recover runs one bounded, resumable brownfield recovery round from authorized evidence, persisted under .specify/productshape/recoveries/<session>/.
• Pairs with the pdac extension (delivery-lane citation grounding and verification), which is submitted separately.

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).
• The same CLI rail 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, plus a real delivery feature (specs/001-overdue-invoice-display/ with spec, plan and tasks) grounded through the sibling pdac extension.

Test scenarios:

1. Installed from the ProductShape catalog by name (specify extension add pdac-product, which downloads this exact release asset and verifies its sha256) and, separately, with specify extension add pdac-product --from <download URL> into a fresh project; both register six skills and specify extension info pdac-product shows the manifest.
2. Ran the full lane three times: baseline change with --initial (five artifacts), then two modifications of the business rule (30 to 45 days, 45 to 60 days): change, refine with a recorded note, validate, human approval by editing status: approved, apply with --dry-run then for real, archive.
3. Negative probes with byte-identical hashes of docs/product/model and the change container before and after: apply refused while status: draft (PRODUCT028, exit 1); validation rejected an unknown frontmatter key (PRODUCT002, exit 1); apply refused after the base revision was pointed at an older commit (PRODUCT027, exit 1).
4. Apply named the delivery documents whose citations turned stale (spec.md and plan.md), and prodshape citations verify --provider speckit reported the same citations; re-grounding brought them back to current.
5. Recovery: recover-start, recover-next, recover-record, recover-candidate and recover-round on a fresh repository; the round reported the intended validation finding for a candidate without provenance and persisted the session files.
6. Lifecycle: specify extension update pdac-product (already current), specify extension remove pdac-product --force with .specify/productshape/ surviving, specify extension add pdac-product again.

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-product

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

# The CLI every command runs
npm install --save-dev @prodshape/cli

# In the agent: author, validate, approve by hand, apply, archive
/speckit.pdac-product.change due-45
/speckit.pdac-product.validate due-45
/speckit.pdac-product.apply due-45
/speckit.pdac-product.archive due-45

Proposed Catalog Entry

{
  "pdac-product": {
    "name": "ProductShape PRODUCT workflows",
    "id": "pdac-product",
    "description": "Author, refine, validate, apply, archive and recover ProductShape product meaning in a separate Spec Kit lane.",
    "author": "Juan G. Carmona (@juangcarmona)",
    "version": "0.1.0",
    "download_url": "https://github.com/juangcarmona/productshape/releases/download/speckit-pdac-product-v0.1.0/speckit-pdac-product.zip",
    "repository": "https://github.com/juangcarmona/productshape",
    "homepage": "https://pdac.dev",
    "documentation": "https://github.com/juangcarmona/productshape/blob/main/extensions/speckit-pdac-product/README.md",
    "changelog": "https://github.com/juangcarmona/productshape/blob/main/extensions/speckit-pdac-product/CHANGELOG.md",
    "license": "Apache-2.0",
    "category": "process",
    "effect": "read-write",
    "requires": {
      "speckit_version": ">=1.0.4",
      "tools": [
        {
          "name": "prodshape",
          "version": ">=0.19.0",
          "required": true
        }
      ]
    },
    "provides": {
      "commands": 6,
      "hooks": 0
    },
    "tags": ["product", "product-change", "recovery", "pdac"]
  }
}

Additional Context

• The extension lives in the ProductShape monorepo under extensions/speckit-pdac-product/; the release archive is that directory alone, built by the repository's release workflow on the speckit-pdac-product-v0.1.0 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 (68e7bbfc3b601f091ff5c166205bf54e66c7c86041519f374e142afd69990009); this listing is for discovery.
• Effect is read-write because apply writes the accepted product model, and only there, after a human sets status: approved. The extension never edits Spec Kit's own files.
• 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