product-spec

name	product-spec
description	Generate PRODUCT_SPEC.md through guided Q&A. Use as the first step when starting a new greenfield project.
allowed-tools	Read, Write, AskUserQuestion, Bash

Generate a product specification document for the current project.

Workflow

Copy this checklist and track progress:

Product Spec Progress:
- [ ] Step 1: Directory guard
- [ ] Step 2: Project root confirmation
- [ ] Step 3: Check for existing PRODUCT_SPEC.md
- [ ] Step 4: Conduct guided Q&A with user
- [ ] Step 5: Write PRODUCT_SPEC.md
- [ ] Step 6: Handle deferred decisions
- [ ] Step 7: Review and refine with user
- [ ] Step 8: Suggest next step (/technical-spec)

Directory Guard

1. If .toolkit-marker exists in the current working directory → STOP: "You're in the toolkit repo. Run this from your project directory instead: cd ~/Projects/your-project && /product-spec"

Project Root Confirmation

Before generating any files, confirm the output location with the user:

Will write PRODUCT_SPEC.md to: {absolute path of cwd}/
Continue? (Yes / Change directory)

If the user says "Change directory", ask for the correct path and instruct them to cd there first.

Existing File Guard (Prevent Overwrite)

Before asking any questions, check whether PRODUCT_SPEC.md already exists in the current directory.

• If it does not exist: continue normally.
• If it exists: STOP and ask the user what to do:
  1. Backup then overwrite (recommended): read the existing file and write it to PRODUCT_SPEC.md.bak.YYYYMMDD-HHMMSS, then write the new document to PRODUCT_SPEC.md
  2. Overwrite: replace PRODUCT_SPEC.md with the new document
  3. Abort: do not write anything; suggest they rename/move the existing file first

Process

Read .claude/skills/product-spec/PROMPT.md and follow its instructions exactly:

1. Ask the user to describe their idea
2. Work through each question category (Problem, Users, Experience, Features, Data)
3. Make recommendations with confidence levels
4. Generate the final PRODUCT_SPEC.md document

Output

Write the completed specification to PRODUCT_SPEC.md in the current directory.

After writing PRODUCT_SPEC.md, verify the file exists and is non-empty by reading the first few lines. If the file was not created successfully, report the error and retry.

Deferred Requirements Capture (During Q&A)

IMPORTANT: Capture deferred requirements interactively during the Q&A process, not after.

When to Trigger

During the Q&A, watch for signals that the user is deferring a requirement:

• "out of scope"
• "not for MVP" / "post-MVP"
• "v2" / "version 2" / "future"
• "later" / "eventually"
• "maybe" / "nice to have"
• "we'll skip that for now"
• "not right now"
• "that's a separate thing"

Capture Flow

When you detect a deferral signal, immediately use AskUserQuestion:

Question: "Would you like to save this to your deferred requirements?"
Header: "Defer?"
Options:
  - "Yes, capture it" — I'll ask a few quick questions to document it
  - "No, skip" — Don't record this

If user selects "Yes, capture it":

Ask these clarifying questions (can be combined into one AskUserQuestion with multiple questions):

1. What's being deferred? "In one sentence, what's the requirement or feature?" (Pre-fill with your understanding from context)

2. Why defer it? Options: "Out of scope for MVP" / "Needs more research" / "V2 feature" / "Resource constraints" / "Other"

3. Notes for later? "Any context that will help when revisiting this?" (Optional — user can skip)

Write to DEFERRED.md Immediately

After collecting answers, append to DEFERRED.md right away (don't wait until end).

If file doesn't exist, create it:

# Deferred Requirements

> Captured during specification Q&A. Review when planning future versions.

## From PRODUCT_SPEC.md ({date})

| Requirement | Reason | Notes |
|-------------|--------|-------|
| {user's answer} | {selected reason} | {notes or "—"} |

If file exists, append:

| {user's answer} | {selected reason} | {notes or "—"} |

(If appending to a different spec's section, add a new section header first.)

Continue Q&A

After capturing (or skipping), continue the spec Q&A where you left off. Don't break the flow.

Cross-Model Review (Automatic)

After writing PRODUCT_SPEC.md, run cross-model review if Codex CLI is available:

1. Check if Codex CLI is installed: codex --version
2. If available, run /codex-consult on the generated document
3. Present any findings to the user before proceeding

Consultation invocation:

/codex-consult --research "product requirements, user stories" PRODUCT_SPEC.md

If Codex finds issues:

• Show critical issues and recommendations
• Ask user: "Address findings before proceeding?" (Yes/No)
• If Yes: Apply suggested fixes
• If No: Continue with noted issues

If Codex unavailable: Skip silently and proceed to Next Step.

Error Handling

Situation	Action
PROMPT.md not found at .claude/skills/product-spec/PROMPT.md	Stop and report "Skill asset missing — reinstall toolkit or run /setup"
DEFERRED.md write fails (permissions or disk)	Output deferred items to terminal, warn user, continue with spec generation
Codex CLI invocation fails or times out	Log the error, skip cross-model review, proceed to Next Step

Next Step

When complete, inform the user:

PRODUCT_SPEC.md created at ./PRODUCT_SPEC.md
Deferred Requirements: {count} items captured to DEFERRED.md
Cross-Model Review: PASSED | PASSED WITH NOTES | SKIPPED

Next: Run /technical-spec