Greenfield projects can complete speckit with no PRD/SPECIFICATION export and no prompt

[MScottAdams]

Summary

A user can complete the entire speckit workflow on a greenfield project and end up with no PRD.md, no SPECIFICATION.md, and no prompt anywhere asking whether to create them. The vBRIEF is fully populated, but the human-readable exports never come into existence.

This is a follow-up gap from #398's deliberate "warn if present, ignore if absent" design.

Reproduction

1. New empty repo. Install deft. No PRD.md or SPECIFICATION.md exists.
2. Run an agent through deft-directive-setup -> Phase 2 -> Phase 3 (speckit strategy) -> Phase 4 (Tasks).
3. Inspect the project: vbrief/PROJECT-DEFINITION.vbrief.json, vbrief/specification.vbrief.json, vbrief/plan.vbrief.json are all populated. PRD.md and SPECIFICATION.md do not exist.
4. Run task check. Per Auto-render PRD.md and SPECIFICATION.md when specification.vbrief.json changes #398's "skip silently if absent" rule, no warning. The user never learns the exports exist.

Why this happens

deft-directive-setup/SKILL.md correctly forbids the agent from generating an authoritative PRD.md:

Anti-pattern: "Generate an authoritative PRD.md -- PRD.md is a read-only export via task prd:render, never a source of truth"

speckit.md Phase 3 mentions task spec:render (see companion issue), but never mentions task prd:render at all -- speckit's Artifacts Summary table goes directly from specification.vbrief.json to "Code + tests" with no PRD step.

deft-directive-pre-pr auto-renders both at PR-prep time (per #398), but a solo user / agentic walkthrough that never opens a PR never hits that hook.

task check skips when files are absent (per #398).

Result: nothing in the greenfield path tells the user "by the way, there are human-readable exports you can generate."

Why this is its own issue (not part of the speckit-render bug)

The companion issue is about speckit saying ! Run task spec:render and not enforcing it. This issue is about speckit not even mentioning task prd:render, plus #398's silent-on-absent behavior making the discoverability problem invisible.

Even if the speckit-render bug is fixed, a greenfield user still won't be told about task prd:render unless a) speckit's Artifacts Summary is updated, b) task check nags on absent exports for spec'd projects, or c) deft-directive-setup ends with a "you may want to render exports now" prompt.

Proposed fix (sketch)

Pick one or combine:

1. Speckit Artifacts Summary: add a "3c. Render PRD" step (analogous to "3b. Render SPECIFICATION") so PRD is at least mentioned in the canonical workflow doc.

2. Setup skill end-of-flow prompt: at the end of deft-directive-setup Phase 3, after the spec is written and approved, ask the user: "Would you like to generate SPECIFICATION.md and/or PRD.md now? (recommended for stakeholder review)" -- one-time opt-in.

3. task check opt-in nudge: when vbrief/specification.vbrief.json exists but neither export does, emit a one-line info (not a warning) on first run only: "tip: task spec:render / task prd:render produce human-readable exports."

4. Status quo (no change): accept that solo users who never invoke render commands and never open a PR will never see the exports. Documented as intended behavior.

Related

• Auto-render PRD.md and SPECIFICATION.md when specification.vbrief.json changes #398 / PR fix(scripts,skills): auto-render staleness warning + pre-pr auto-render step (#398) #400 -- design ancestor.
• docs(readme): Document Generation table missing task prd:render row #420 -- README discoverability gap for task prd:render.
• Companion issue: speckit Phase 3 -> Phase 4 advances without enforcing ! task spec:render.

Severity

Workflow / discoverability gap. No data loss (vBRIEF is source of truth). Affects greenfield + agentic workflows specifically. Existing brownfield projects already have the exports, so this is invisible to anyone who migrated.

Discovered

During greenfield walkthrough of speckit Phase 1-4 in agentic mode.

[MScottAdams]

Companion issue: #432 (speckit Phase 3 -> Phase 4 advances without enforcing ! task spec:render).

[MScottAdams]

Related: #434 (spec_render.py is item-centric and silently drops all speckit narratives) -- even when SPECIFICATION.md does get rendered, it is currently near-empty for speckit specs.

[MScottAdams]

Related: #435 (spec rendering does not aggregate scope vBRIEFs) and #436 (speckit Phase 4 collides with plan.vbrief.json definition).

[MScottAdams]

Tracked by #437 (v0.20 vBRIEF-centric rendering is half-shipped).

[MScottAdams]

Decision (2026-04-20): widen from speckit-only to all spec-generating strategies

Per tracker #437 deep-think walkthrough. #433 originally framed the PRD-export discoverability gap as a speckit problem. The strategies audit done alongside #432 shows it is broader: task prd:render is explicit in only 1 of 5 spec-generating strategies.

Current state across spec-generating strategies

• enterprise.md:38 — ✓ ! Run task prd:render explicit, gated by approval (Gate 1).
• interview.md:245 (Full path step 3) — ⚠ "Generate PRD.md" with no specified mechanism. A reasonable reader might hand-author instead of invoking the renderer.
• yolo.md — ⚠ inherits interview's vagueness.
• speckit.md — ✗ no mention of task prd:render anywhere. Artifacts Summary goes directly from specification.vbrief.json → "Code + tests."
• rapid.md:53 — ✓ explicitly opts out (⊗ Generate a PRD or require approval -- rapid skips both).

Adopted fix

Coordinated doc edits across all affected strategies, landing in one PR alongside #432:

1. interview.md Full path step 3 — replace "Generate PRD.md" with ! Run task prd:render to produce PRD.md as a read-only rendered export. Also add to Transition Criteria and to ## Exit Commands (per the contract established in speckit Phase 3 -> Phase 4 advances without enforcing ! task spec:render #432 decision).
2. yolo.md — inherits interview; no edit needed, but verify the inherited path is current after the interview.md edit.
3. speckit.md Artifacts Summary — add row "3c. Render PRD -- PRD.md (rendered via task prd:render) -- Read-only stakeholder review export." Add ! Run task prd:render to Phase 3 Exit Commands.
4. enterprise.md — already correct; no edit.
5. rapid.md — already correct; no edit.

deft-directive-setup end-of-flow behavior

No interactive prompt. Relies on the Exit Commands contract from #432: setup skill mechanically runs each strategy's declared post-phase commands (including task prd:render where applicable) before advancing. No "Would you like to render now? [Y/n]" required in autopilot mode because the render is unconditional.

In autopilot / yolo mode: renders silently as part of phase transition. In interactive mode: user sees the renderer's output message and knows the export exists.

Explicitly dropped from scope

• No end-of-flow "Would you like to generate exports now?" prompt. Redundant once Exit Commands runs the render unconditionally.
• No task check nag when exports are absent. Auto-render PRD.md and SPECIFICATION.md when specification.vbrief.json changes #398's "warn if present, ignore if absent" design stays intact.
• No separate "PRD discoverability" README edits; the strategies audit makes PRD an inline concern of each strategy's doc.

GA status

Blocker for v0.20.0 GA. Lands alongside #432 (render-enforcement audit), #434 (renderer narrative pass), #435 (lifecycle aggregator), and #436 (speckit Opt 1 + migrator).