Skip to content

specs-from-prd

Plugin: core-standards
Category: Other
Command: /specs-from-prd

/vt-c-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-c-activate → /vt-c-2-plan → /vt-c-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-c-specs-from-prd                    # Uses default: 03-PRD/PRD.md
/vt-c-specs-from-prd path/to/PRD.md     # Explicit PRD path

Workflow Position

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

For single specs from informal requirements (no PRD), use /vt-c-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. Read .design-state.yaml if it exists. Extract all existing SPEC IDs from the specs_status keys.

  4. Scan existing spec files — glob for specs/*/spec.md. Read frontmatter id: fields.

  5. Compute next available SPEC ID:

  6. Collect all IDs from .design-state.yaml keys AND spec file frontmatter
  7. Parse numeric part from both SPEC-NNN and spec-N patterns
  8. Next ID = max across all sources + 1
  9. Format as SPEC-0NN (zero-padded to 3 digits)

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-c-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-c-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-c-activate              View spec dashboard and select first spec
2. /vt-c-activate SPEC-NNN     Activate a specific spec for development
3. /vt-c-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-c-spec-from-requirements Creates single specs from informal input (complementary)
/vt-c-activate Activates specs created by this skill
/vt-c-pd-6-handoff Precedes this skill in the product design workflow
/vt-c-2-plan Follows activation of specs created by this skill