Skip to content

vt-d-specs-from-prd

Generate implementation specs from a Product Requirements Document (PRD). Reads the PRD feature table, creates per-feature spec files, and registers them for the development workflow.

Plugin: vt-product-dev
Category: Other
Command: /vt-d-specs-from-prd

/vt-d-specs-from-prd — Generate Specs from PRD

Break down a PRD into implementation-sized specs for development. Produces spec files that feed directly into /vt-d-activate → /vt-d-2-plan → /vt-d-3-build.

When to Use

  • You have a completed PRD and want to generate implementation specs
  • You are transitioning from product design to development
  • You need to break a PRD's feature table into governed, dependency-ordered specs

Invocation

/vt-d-specs-from-prd                    # Uses default: 03-PRD/PRD.md
/vt-d-specs-from-prd path/to/PRD.md     # Explicit PRD path

Workflow Position

/vt-d-pd-2-prd → /vt-d-pd-3-prototype → /vt-d-pd-4-validate → /vt-d-pd-6-handoff
                                                                        ↓
                                                            /vt-d-specs-from-prd  ← YOU ARE HERE
                                                                        ↓
                                                              /vt-d-activate → /vt-d-2-plan → ...

For single specs from informal requirements (no PRD), use /vt-d-spec-from-requirements instead.

Execution Instructions

Step 0: Context Detection

  1. Detect project name from the nearest CLAUDE.md, package.json, .repo-manifest.yaml, or directory name.

  2. Locate specs directory using this search order: a. Read .design-state.yaml — use specs_directory field if present b. Check for existing specs/ directory c. Check for 05-specs/, 05-specs/, docs/specs/, specs/ d. If nothing found, default to specs/ (will create in Step 5)

  3. Allocate SPEC IDs — run the allocator and use its stdout verbatim:

    python3 ~/.claude/skills/vt-d-spec-from-requirements/scripts/allocate_spec_id.py --specs-dir ''

Substitute the directory resolved in item 2, inside the single quotes, and first reject any resolved value containing a character outside [A-Za-z0-9._/-], falling back to the default. The value's first source is the specs_directory field of .design-state.yaml — repo-tracked content an attacker can set via a pull request or a repo you cloned — so an unquoted substitution lets $(...)/backtick content execute in the user's shell. Unquoted also breaks on an innocent path containing a space: it word-splits, argparse rejects the stray argument, and stdout is empty.

Omit the flag only when nothing was found — the allocator then defaults to <repo root>/specs. Passing it is not cosmetic: without it the allocator scans specs/ while this skill writes to 05-specs/ or docs/specs/, so the free-ID probe and the all-refs floor both look at a directory that does not exist and return nothing, silently.

Do NOT compute IDs by hand, and do not pre-scan the registry or the spec files to do so — that is this script's job, and a hand scan sees only the current worktree, so two branches in flight allocate the same number (SPEC-165). The allocator claims each ID under a lock on a store shared by every worktree of the clone.

This skill mints one ID per feature, so call the allocator once per feature — each call reserves its number. Computing max + 1..N locally would hand out IDs at or below the reserved counter and reintroduce the collision.

  • stdout is exactly one ID (SPEC-NNN), already collision-checked against existing spec directories — use it as-is.
  • The allocator always exits 0. On any failure it falls back to the local scan and prints a warning: on stderr; surface that warning to the user rather than swallowing it, since a silent fallback is indistinguishable from a working one.
  • Never add --no-lock or --no-shared: both are test-only controls that disable the very reservation this step depends on.

Step 1: Read PRD and PID

  1. Read the PRD at the given path (default: 03-PRD/PRD.md)
  2. If the file does not exist, ask the user for the correct path via AskUserQuestion

  3. If the PRD has no feature table (Section 4 or similar), warn and ask the user to identify features

  4. Read the PID if it exists (default: 03-PRD/PID.md) for tech stack constraints

  5. PID is optional — proceed without it if not found

  6. Check for prototype — if 04-prototyp/ exists, note it for prototype references in specs

Step 2: Analyze Features

  1. Extract all features from the PRD's feature table (typically Section 4: Feature Overview)
  2. For each feature, extract:
  3. Feature name and description
  4. Priority (P0/P1/P2)
  5. User stories and acceptance criteria
  6. Technical requirements from PID constraints

  7. Dependencies between features

  8. Display extraction summary: 

    ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
PRD Feature Extraction
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

PRD: [path]
PID: [path or "not found"]
Prototype: [path or "not found"]
Features found: N

| # | Feature | Priority | Dependencies |
|---|---------|----------|--------------|
| 1 | [name]  | P0       | —            |
| 2 | [name]  | P1       | Feature 1    |

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

  9. Confirm with user via AskUserQuestion:

  10. Looks good — proceed to generate specs
  11. Adjust — user modifies feature list, priorities, or dependencies
  12. Cancel — exit without creating files

Step 3: Generate Project Setup Spec

Create specs/0-project-setup/spec.md with: - Shared infrastructure requirements (CI/CD, linting, testing setup) - Tech stack from PID - Environment setup - Design token / CD integration if applicable

YAML frontmatter: 

---
id: SPEC-NNN
title: Project Setup
priority: P0
status: draft
dependencies: []
parent_prd: [relative path to PRD]
deliverable_types: [code]
---

Step 4: Generate Feature Specs

For each PRD feature, create specs/[N]-feature-name/spec.md with:

YAML frontmatter: 

---
id: SPEC-NNN
title: [Feature Name]
priority: P0|P1|P2
status: draft
dependencies: [SPEC-NNN]
parent_prd: [relative path to PRD]
deliverable_types: [code]
---

Body sections (same structure as /vt-d-spec-from-requirements output): 1. # SPEC-NNN: [Title] 2. ## Problem — from PRD problem statement, scoped to this feature 3. ## Goal — from PRD feature description 4. ## User Stories — from PRD, with Given/When/Then acceptance criteria 5. ## Functional Requirements — table extracted from PRD 6. ## Visual Reference — prototype screenshots/paths if 04-prototyp/ exists 7. ## Non-Functional Requirements — from PID constraints 8. ## Edge Cases — identified from PRD and domain analysis 9. ## Scope — In Scope / Out of Scope for this specific feature 10. ## Dependencies — mapped to other generated SPEC IDs 11. ## Success Criteria — measurable outcomes

Rules: - Never use placeholder text ("TBD", "TODO", "N/A") - Omit sections with no content rather than using empty sections - Map inter-feature dependencies to actual SPEC IDs

Step 5: Register and Write Files

For each generated spec (project setup + features):

  1. Create spec directory: specs/[N]-kebab-title/
  2. Write spec file: specs/[N]-kebab-title/spec.md
  3. Write state file: specs/[N]-kebab-title/state.yaml 
    status: proposed
activated_at: null
completed_at: null
    If docs/user-manual/mkdocs.yml exists, also add a docs_page mapping: 
    docs_page: docs/user-manual/docs/features/[feature-slug].md
    where [feature-slug] is the kebab-case feature name matching the page generated by /vt-d-user-manual-generate.
  4. Update .design-state.yaml: Add each spec to specs_status: 
    SPEC-NNN:
  file: [N]-kebab-title/spec.md
  priority: P0|P1|P2
  dependencies: []
  specs_dir: specs/[N]-kebab-title/

If .design-state.yaml does not exist, create it with current_phase: development and specs_directory: specs/.

After all specs are generated, scan intake/pending/ for proposals that may have led to this PRD or its features:

  1. Search intake/pending/from-research/ and intake/pending/from-projects/ for .md files containing the PRD filename or any of the generated spec titles
  2. For each match, display: 
    Related proposal found: [filename]
Content mentions: [matched term]
    Use AskUserQuestion:
  3. Move to processed — update toolkit_proposal_status: spec-created, move to intake/processed/
  4. Skip — leave in pending (may be unrelated)
  5. If no matches found: skip silently

Step 6: Completion Summary

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
Specs Generated from PRD
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

PRD: [path]
Generated: N specs

| ID | Feature | Priority | Dependencies |
|---|---|---|---|
| SPEC-NNN | Project Setup | P0 | — |
| SPEC-NNN | [Feature 1] | P0 | SPEC-NNN |
| SPEC-NNN | [Feature 2] | P1 | SPEC-NNN |

Files written:
  specs/[N]-project-setup/spec.md + state.yaml
  specs/[N]-feature-1/spec.md + state.yaml
  specs/[N]-feature-2/spec.md + state.yaml
  .design-state.yaml (updated)

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
NEXT STEPS
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

1. /vt-d-activate              View spec dashboard and select first spec
2. /vt-d-activate SPEC-NNN     Activate a specific spec for development
3. /vt-d-2-plan                Create implementation plan

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

Edge Cases

ID Scenario Handling
EC-1 PRD has no feature table Ask user to identify features interactively
EC-2 PID does not exist Proceed without tech stack constraints
EC-3 SPEC ID collision Increment until free ID found
EC-4 No .design-state.yaml Create it with default structure
EC-5 No specs/ directory Create it
EC-6 User cancels after extraction Exit without writing files

Integration Points

Skill Relationship
/vt-d-spec-from-requirements Creates single specs from informal input (complementary)
/vt-d-activate Activates specs created by this skill
/vt-d-pd-6-handoff Precedes this skill in the product design workflow
/vt-d-2-plan Follows activation of specs created by this skill