makelore/.project-docs/30-worklog/tasks/20260906-project-setup-ux-90fe6cf2.md

Task: Review new project setup UX

Identity

• Task ID: 20260906-project-setup-ux-90fe6cf2
• Mode: Feature
• Branch: codex/20260906-project-setup-ux-90fe6cf2-project-setup-ux
• Worktree: D:\Datas\OthersProjects.codex-worktrees\makelore\20260906-project-setup-ux-90fe6cf2
• Base commit: 5c61110f46
• Owner: codex
• Status: In Progress

Scope

• Review the new-project transition from Project Configuration to the first Coding Conversation, with particular attention to the zero-Agent state and the discoverability of the return/continue action.
• Verify the persisted readiness rule, route behavior, empty states, model prerequisite, and current product terminology before recommending an interaction change.
• Implement the accepted interaction direction with one shared Conversation-readiness rule, a strong first-Agent setup path, deterministic navigation, and a recoverable zero-Agent Conversation state.
• Add focused unit and Electron E2E coverage while keeping persistence, Pi runtime, Provider, Plugin, and Main/Renderer contracts unchanged.

Intent And Constraints

• Preserve the explicit product decision that new projects have no default project Agent and that the user chooses the Agent identity, model, responsibility, and Skills.
• Keep project-owned parent Agents distinct from short-lived runtime child Agents; do not describe the Project Configuration entity as a child Agent.
• Preserve Pi 0.84.2, .makelore ownership, the single light visual system, and the current Main/Renderer boundary.
• Prefer one explicit first-run completion path over a forced tutorial, compatibility layer, new state machine, or automatically fabricated default Agent.

Outcome

• Confirmed that the screenshot's “项目智能体” is a persisted project-owned parent Agent, not a runtime child Agent. ADR-006 and ADR-008 deliberately keep child Agents ephemeral and without inherited project Plugin resources.
• Confirmed a state-invariant gap: Project Configuration validates only the Agents that exist, so an empty Agent array passes; submit() then saves initialized: true. ProjectChatRoute and MainLayout gate only on that boolean, despite the gate copy claiming that at least one manually configured Agent is required.
• Confirmed the resulting dead-end presentation: Coding chat has no selected Agent, clears the Conversation selection, renders only a small “当前项目还没有可用智能体” sidebar message, leaves the main canvas empty, and disables the Composer without a recovery CTA.
• Confirmed the navigation gap: Project Configuration uses history-relative navigate(-1). The destination depends on how the page was entered and can even be a visually identical Project Configuration history entry; saving does not navigate to the Conversation page.
• Confirmed an additional supported-path gap: first-run Setup does not configure a model. With zero model options, the create-Agent icon shows a toast and opens a read-only model drawer that contains no direct action to /models, so stronger Agent guidance alone would still lead some users into a dead end.
• Recommended the “required but escapable” flow: an incomplete project may exist and the user may leave, but completion/Conversation readiness requires at least one enabled, unarchived, fully configured project Agent. In the empty state, replace the icon-only instruction with a prominent text CTA; after the first Agent is valid, make the primary action “保存并进入对话” with deterministic /chat navigation. Keep a full chat recovery state for legacy/archived-all data and route it directly back to Agent creation.
• Recommended treating zero models as an explicit prerequisite state with a “先配置模型” CTA and a return intent, and replacing history-relative back behavior with context-aware, labelled destinations such as “返回对话” or “稍后设置”.
• No product behavior or source code was changed.

Verification

• Inspected the supplied 1493×891 Project Configuration screenshot at original detail.
• Read the project memory startup set, relevant product/domain rules, ADR-006, ADR-008, and related concurrent task scopes after passing the ownership and planning gates.
• Inspected src/pages/ProjectConfiguration/index.tsx, src/App.tsx, src/components/layout/MainLayout.tsx, src/components/layout/Sidebar.tsx, src/pages/Chat/CodingChatPanel.tsx, CodingConversationSidebar.tsx, AgentCreationDialog.tsx, the project configuration schema/service, Setup, README, focused tests, and relevant Git blame/history.
• Queried the UI/UX reference for onboarding, empty-state, primary-action, keyboard, and predictable-back guidance. Its generated dark palette was rejected because Makelore's repository contract requires the existing single light visual system.
• No automated test was run because this task intentionally made no behavior change; a future implementation requires focused unit coverage and the shared Electron E2E flow.

Follow-ups

• If the recommended direction is accepted, implement one shared readiness predicate and cover zero Agents, all Agents archived, no configured model, first Agent completion, deterministic return/continue navigation, unsaved changes, and chat recovery.
• Update README only with the accepted final interaction behavior, not this discussion or a historical worklog.

Promotion Candidates

• None recorded.