Project overview — "Generate spec" CTA seeds the first requirements turn from the stored create prompt

[hevayo]

Problem

Creating a project (ADR-0005) provisions a repo but generates nothing: CreateProject only provisions the OC project + repo + webhook — it never uses the prompt to start derivation (the contract's prompt wording oversells here). So on the overview, the Spec card in its not-generated state ("Start here") only opens an empty Spec view, and the build prompt the user typed at create time is thrown away — they'd have to re-type their idea into the agent chat to get anywhere.

Users

Developer/User (PRD persona) — just described what they want to build and expects the platform to turn it into a spec.

Experience walkthrough

1. User creates a project with a prompt. The console saves the prompt to localStorage, keyed to the project.
2. On the overview, the Spec card reads status. Because hasSpec: false, the card (in this state only) drops the whole-card navigation and shows a prominent Generate spec button.
3. User clicks Generate spec → navigate to the Spec view and auto-send a room turn wrapping the stored prompt: "Generate a complete requirements specification (requirements/requirements.md) for this project based on: <prompt>." (Generic instruction if no stored prompt.)
4. The agent joins the room and writes requirements/requirements.md live; the reactive spec list shows it appear, the chat panel narrates.
5. Once requirements commit (hasSpec: true), the card returns to the normal spec-status states.

Scope

In:

• Persist the create-project prompt to localStorage (keyed by project) on successful create.
• Spec card: in the hasSpec === false state, plain card + a single Generate spec button (no whole-card click).
• The button navigates to the Spec view and auto-sends a room turn seeded with the wrapped stored prompt (generic instruction as fallback).

Out (explicitly):

• Any BE/contract change.
• Design/validation generation and the build trigger (Spec view — full-screen spec workspace (requirement + design files) with build trigger #80/ADR-0007).
• Regenerate-after-requirements-exist.
• A re-trigger guard (duplicate-generation gap) — deferred to Spec generation lacks an in-flight signal — "Generate spec" can start duplicate turns #151.
• Cross-device prompt recovery (localStorage is per-browser).

Contract changes

None. Composes POST /projects, GET /projects/{p}/status (hasSpec), the room-scoped agent turn (#86 ph4), + localStorage. No BE handshake. A future BE in-flight signal to guard duplicate generation is tracked in #151.

States to design

• Spec card — hasSpec:false: plain card + Generate spec button.
• Spec card — generated: unchanged whole-card states ("In collaboration" / "Awaiting your review" / "vN published" / "Derivation failed").
• No stored prompt: CTA still fires with a generic instruction.
• Spec view on arrival: the turn auto-starting → live writing.

Decisions

Resolved in grilling — see the decisions comment. Deferred re-trigger guard tracked in #151.

🤖 Generated with Claude Code

[hevayo]

Grilling decisions

Key finding (reshapes the premise): CreateProject (project_service.go:146) does not kick off spec derivation despite the contract's prompt description saying so — it only provisions the OC project + repo + webhook. So hasSpec: false after create is a stable state, not transient, and there's no double-generation race with a BE auto-derive. (Contract description oversells — a small BE doc fix, out of scope here.)

Decided

1. "Not generated" signal: hasSpec === false. That's the sole condition for showing the CTA.
2. Prompt source — localStorage (keyed by project). Resolved by exploration, not preference: the BE persists prompt on create but the Project read schema exposes no prompt field, so the console can't read it back — localStorage is the only client option without a contract change.
3. Turn message — wrapped generate instruction (not the raw prompt): e.g. "Generate a complete requirements specification (requirements/requirements.md) for this project based on the following idea: <stored prompt>." Auto-sent on arrival in the Spec view (per the original ask, "a call should be sent to the agent").
4. No-prompt fallback — still generate, generic instruction: when localStorage has no prompt (old project / other browser / cleared), the CTA still fires with a generic "Generate a complete requirements specification for this project." The agent can ask for details in chat. The one-click path never disappears.
5. Card layout — plain card + button, only in the not-generated state: drop the whole-card click and render the copy plus one contained Generate spec button as the single action. The generated states keep today's whole-card navigation to Spec.
6. Re-trigger guard — none, for now. A room turn keeps hasSpec false until it commits (~60s), so navigating back mid-generation could start a duplicate turn. Shipping without a guard to keep it simple; the gap is tracked in Spec generation lacks an in-flight signal — "Generate spec" can start duplicate turns #151, with a BE in-flight signal as the intended durable fix.

Rejected

• Raw prompt verbatim — the agent might treat it as a chat opener rather than a generate command.
• Hide/disable the CTA when no prompt — breaks the one-click promise for those projects.
• Button nested inside the whole-card CardActionArea — button-in-a-button a11y smell and ambiguous click target.
• Client-side re-trigger guards (reading the agent-chat store's active-turn state, or a localStorage "generation-started" flag) — coupling / staleness; deferred to a BE signal (Spec generation lacks an in-flight signal — "Generate spec" can start duplicate turns #151).

Out of scope (unchanged)

Design/validation generation and the build trigger (#80/ADR-0007); regenerate-after-requirements-exist; cross-device prompt recovery.

Contract changes

None. Composes POST /projects, GET /projects/{p}/status (hasSpec), the room-scoped agent turn (#86 ph4), + localStorage. No BE handshake for this feature; the future in-flight signal is tracked separately in #151.

[hevayo]

Built (mock mode) — on feature-collab-with-agents

Landed directly on feature-collab-with-agents (per the developer's call — no separate branch), so it rides the existing integration PR #138 into aep-rewrite rather than getting its own PR. Commit 892d4c7.

What shipped:

• promptStore — persists the create prompt to localStorage keyed by (org, project) on create success; builds the wrapped generate instruction (generic fallback when none stored).
• StatusCards — GenerateSpecCard renders when hasSpec === false (plain card + single Generate spec button); generated states keep the whole-card status.
• Spec route gains a generate search param; AppLayout opens the agent panel on it and clears it after; AgentChatPanel fires the wrapped turn exactly once.

No contract change. No re-trigger guard (deferred, #151).

Verified in mock mode (VITE_API_MODE=mock, fresh status scenario):

• The Spec card shows the emphasized Generate spec CTA (Build/Deployment stay as status cards).
• Clicking it navigates to the Spec view, the ?generate=1 param is cleared, the agent panel opens, and the wrapped instruction auto-sends once — seeded with the stored prompt ("Generate a complete requirements specification … based on the following idea: An online store for handmade ceramics …").
• Typecheck, lint, tests (34/34, incl. a new promptStore unit test) all green.

Screenshots are saved locally for the developer to drag-drop onto PR #138 (screenshots are never pushed to git):

• 150-generate-spec-cta.png — the CTA on the overview
• 150-generate-spec-autosend.png — the Spec view with the auto-sent turn

All further feedback goes on PR #138.

[hevayo]

Live-stack verification ✅

Rebuilt/redeployed the console (:8091) and ran the full flow against the live stack (Thunder auth, real agents + collab).

1. Created a fresh project (ceramics-livetest-t150, "Online store" prompt). The prompt was persisted to localStorage["aep.createPrompt.default.ceramics-livetest-t150"].
2. Overview showed the Generate spec CTA (fresh project → hasSpec: false), Build/Deployment as normal status cards.
3. Clicked Generate spec → navigated to the Spec view, ?generate=1 was set then cleared, the agent panel opened, and the wrapped instruction auto-sent once.
4. The real agent generated a genuine requirements spec (not a chat echo) — finishReason=stop, 2956 output tokens. It wrote a full "Requirements Specification: Handmade Ceramics Online Store" (Introduction, Definitions, Stakeholders, functional/NFR, scope) to specs/requirements/requirements.md.
5. Reactive list showed requirements.md appear live; the committer landed it at specs/requirements/requirements.md (commit 5f5b3282) — correct single-prefix path, no review gate (new file).

The buildSpecGenerationInstruction phrasing reliably triggers real generation — no tuning needed. Verified on feature-collab-with-agents (rides PR #138).