Skip to content

spec-from-requirements

Plugin: core-standards
Category: Other
Command: /spec-from-requirements

/vt-c-spec-from-requirements — Spec from Requirements

Create a spec without needing a formal PRD first. Produces a valid spec file that feeds directly into /vt-c-activate → /vt-c-2-plan → /vt-c-3-build.

When to Use

  • You have requirements in a document but no formal PRD
  • You have a feature idea and want to create a governed spec interactively
  • You want a lightweight path from informal requirements to a governed spec

Invocation

/vt-c-spec-from-requirements                          # Interactive: guided questioning
/vt-c-spec-from-requirements path/to/requirements.md  # From document
/vt-c-spec-from-requirements "add webhook support"    # From topic hint

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, note this for Step 5 (will ask user)

  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 and any specs-*.md or SPEC-*.md files in discovered directories. Read frontmatter id: fields.

  5. Compute next 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)

  10. EC-1: If a file or directory already exists for the computed ID, increment until a free ID is found

  11. Display context banner: 

    ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
Spec from Requirements
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

Project: [name]
Input: [document path | topic hint | interactive]
Specs directory: [path or "not yet created"]
Next SPEC ID: SPEC-NNN

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

Step 1: Input Classification

Classify the argument provided by the user:

Case A — File path: Argument looks like a file path (contains / or . extension) → Verify the file exists with Read. If it exists, proceed to Step 1.5. → If the file does not exist, tell the user and fall through to Case C.

Case B — No argument: Skill invoked with no argument → Proceed to Step 1.5 (intent triage).

Case C — Topic hint: Argument is a short text string (not a file path) → Use as starting context, proceed to Step 1.5 with the hint pre-loaded.

Step 1.5: Intent Triage (FR-16 — always runs)

This step runs for ALL input modes (Case A, B, and C). Use AskUserQuestion to ask:

What kind of work is this?

Options: 1. Feature — New capability for a software project 2. Bug fix — Something is broken and needs fixing 3. Prototype — Quick proof of concept to validate an idea 4. Other — (user describes freely)

Context adaptations: - If a topic hint was provided: "You mentioned '[hint]'. What kind of work is this?" - If a file was provided: "You provided '[filename]'. What kind of work is this?"

Carry the selected category forward — it determines which Round 1 questions to use in Step 2b, and informs extraction focus in Step 2a.

After triage: - Case A (file input) → proceed to Step 2a - Case B or C (interactive/topic) → proceed to Step 2b

Step 2a: Document Extraction (for file input)

  1. Read the input file using the Read tool.
  2. For PDF files: use the Read tool's pages parameter. If the PDF is large, read pages 1-10 first.

  3. EC-3: If the file is unreadable (binary, corrupted), ask the user to summarize the key requirements instead, then switch to Step 2b.

  4. Extract these elements from the document:

  5. Problem: What issue or need does this address?
  6. Goal: What is the desired outcome?
  7. Requirements: Functional and non-functional requirements
  8. Constraints: Technical, business, or timeline constraints
  9. Acceptance criteria: How to verify the feature works

  10. Scope: What is in and out of scope

  11. Present extraction summary (mandatory) — always show the user what was extracted: 

    Extraction Summary
─────────────────────────────────────────────────────
Problem:       [1-2 sentence summary]
Goal:          [1-2 sentence summary]
Requirements:  [count] functional, [count] non-functional
Constraints:   [list or "none detected"]
Acceptance:    [count] criteria found
Scope:         [in-scope summary] / [out-of-scope summary]
Gaps:          [list missing sections, or "none detected"]
─────────────────────────────────────────────────────

  12. Ask about additional files via AskUserQuestion:

  13. "Do you have additional files or context to include?"
  14. Options: No, this is complete | Yes, add more files (user provides paths)

  15. If "Yes": read the additional files, merge their content into the extraction, and re-display the updated summary

  16. Confirm with user via AskUserQuestion — always ask, regardless of whether gaps were detected:

  17. If gaps were found, include targeted questions (max 3) about the missing sections
  18. Always include the question: "Is this extraction complete and correct? Anything to add or change?"
  19. Options: Looks good — proceed to Step 3 | Add/correct — user provides additions or corrections
  20. If "Add/correct": incorporate the user's feedback, then proceed to Step 3

Step 2b: Interactive Questioning (for verbal/topic input)

Guide the user through a structured conversation. Max 3 rounds, max 3 questions per round. Use AskUserQuestion for each round.

Round 1 (always — questions depend on the category selected in Step 1.5):

If Feature: 1. What feature do you want to build? (or: "You mentioned [topic hint]. Can you describe the feature?") 2. What problem does this solve for users? 3. Which project/codebase is this for?

If Bug fix: 1. What is the symptom? What do you observe? 2. What is the expected behavior? 3. Which project/codebase is this bug in?

If Prototype: 1. What hypothesis or idea are you testing? 2. Which project/codebase is this for? 3. Is this throwaway or potentially production-bound, and what tech stack or constraints apply?

If Other: 1. Describe what you want to accomplish. 2. What problem does this solve? 3. Who benefits from this? (user role, persona, or system)

Round 2 (if needed — skip if Round 1 answers are comprehensive): 1. What is in scope and what is explicitly out of scope? 2. What priority level? (P0 = must-have, P1 = should-have, P2 = nice-to-have) 3. Does this depend on any existing specs or features?

Round 3 (if needed — skip if enough information gathered): 1. What are the key acceptance criteria? How will you know this works? 2. Are there edge cases or constraints worth noting? 3. What components or files will be affected?

After each round, assess whether enough information exists to draft a spec. If yes, proceed to Step 3 without asking more rounds.

Inference rule (FR-7): For information not explicitly provided: - Priority defaults to P1 - Dependencies default to empty - Status defaults to specified - Created date uses today's date - ui_scope defaults to backend - Omit sections with no content rather than using placeholders (FR-15)

Step 3: Spec Drafting

Assemble the gathered information into the canonical spec format.

YAML frontmatter (required fields): 

---
id: SPEC-NNN
title: [Descriptive title]
priority: P0|P1|P2
status: specified
created: YYYY-MM-DD
depends_on: []
ui_scope: frontend|backend|mixed  # optional, defaults to backend
source: [path to input document, if provided — omit if interactive]
---

Body sections — include only sections that have real content. Never write placeholder text like "TBD", "TODO", "N/A", or empty tables.

Sections in order (omit any that are empty): 1. # SPEC-NNN: [Title] 2. ## Problem — the observed issue or need 3. ## Goal — desired outcome 4. ## User Stories — with Given/When/Then acceptance criteria 5. ## Functional Requirements — table with ID | Requirement columns 6. ## Visual Reference — screenshot paths (relative to project root), mockup links, design file references, or inline text descriptions of visual intent. When ui_scope is backend, this section may be omitted or contain "Not applicable — no UI component" 7. ## Non-Functional Requirements — performance, security, etc. 8. ## Edge Cases — table with ID | Edge Case | Expected Behavior columns 9. ## Scope — In Scope / Out of Scope subsections 10. ## Dependencies — what this spec depends on 11. ## Success Criteria — numbered list of measurable outcomes

Step 3b: Visual Reference Validation

When ui_scope is frontend or mixed, validate that the ## Visual Reference section contains at least one reference (file path, URL, or text description). If the section is empty or missing:

⚠ Visual Reference section is empty but ui_scope is [frontend|mixed].
Add at least one visual reference, or set ui_scope to "backend" if no UI is involved.

When ui_scope is backend, the section may be omitted or contain "Not applicable — no UI component" — no validation warning is emitted.

Step 4: Review Gate (US-4)

Present the complete drafted spec to the user. Display it in full.

Then use AskUserQuestion: - Write as-is — proceed to write the spec file - Revise — user provides feedback, skill updates the draft and presents again - Cancel — exit without writing any files or changing any state

If "Revise": incorporate feedback, re-display the updated draft, and ask again. This loop has no limit (the user controls when they're satisfied).

If "Cancel": display "Cancelled. No files were written." and stop.

Step 5: File Writing

  1. Determine specs directory:
  2. If a specs directory was found in Step 0 → use it
  3. EC-4: If no specs directory exists, use AskUserQuestion:
    • specs/ (Recommended) — standard convention
    • 05-specs/ — product design convention
    • Custom path — user specifies

  4. Create the directory if it doesn't exist

  5. Create spec directory: specs/[N]-kebab-title/

  6. N = numeric part of the SPEC ID
  7. kebab-title = title converted to lowercase kebab-case

  8. Example: SPEC-052 "Webhook Support" → specs/52-webhook-support/

  9. Write spec file: specs/[N]-kebab-title/spec.md

  10. Use the Write tool with the complete spec content from Step 3

  11. Write state file: specs/[N]-kebab-title/state.yaml 

    status: specified
activated_at: null
completed_at: null

  12. Update .design-state.yaml:

EC-4 — If .design-state.yaml does NOT exist: Create it: 

current_phase: development
specs_directory: specs/
specs_status:
  SPEC-NNN:
    file: [N]-kebab-title/spec.md
    priority: P0|P1|P2
    dependencies: []
    specs_dir: specs/[N]-kebab-title/

EC-5 — If .design-state.yaml exists but has no specs_status key: Add the key using the Edit tool without disturbing other content.

Normal case — .design-state.yaml exists with specs_status: Add the new entry using the Edit tool: 

SPEC-NNN:
  file: [N]-kebab-title/spec.md
  priority: P0|P1|P2
  dependencies: []
  specs_dir: specs/[N]-kebab-title/

Only write static metadata (file, priority, dependencies, specs_dir). Never write status, activated_at, or completed_at to .design-state.yaml.

Step 5.5: Close Source Proposal

If the spec's source: frontmatter field points to a file in intake/pending/:

  1. Read the proposal file
  2. Update its YAML frontmatter:
  3. Set toolkit_proposal_status: spec-created
  4. Add spec_id: SPEC-NNN
  5. Stage the update: git add [proposal_path]
  6. Move to processed: git mv [proposal_path] intake/processed/[from-source]/
  7. Preserve the from-source subdirectory (e.g., from-research/, from-projects/)
  8. Create the target directory if it doesn't exist: mkdir -p intake/processed/[from-source]/
  9. Display: Proposal processed: [filename] → intake/processed/ (spec SPEC-NNN created)

If source: does not point to an intake/pending/ file, or the file doesn't exist: skip silently.

Step 6: Completion Summary

Display:

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
Spec Created: SPEC-NNN — [Title]
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

Files written:
  specs/[N]-kebab-title/spec.md
  specs/[N]-kebab-title/state.yaml
  .design-state.yaml (updated)

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

1. /vt-c-activate SPEC-NNN    Activate the spec for development
2. /vt-c-2-plan               Create implementation plan
3. /vt-c-3-build              Start building

Or run /vt-c-activate --status to see the full wave dashboard.
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━