Prototype conversational project build flow

[isayahc]

Draft: Replace staged context gathering with a tool-driven project chat

Status: Draft — not ready to merge

This PR documents an implementation experiment. It establishes useful pieces, but the current branch should be split and simplified before merge.

Summary

The intended product experience is a single conversational interface:

1. The assistant talks with the user and asks only useful follow-up questions.
2. When the request is sufficiently clear—or the user says to proceed—the assistant calls a project-build tool.
3. Build progress and the generated project render inline in the same chat.
4. Later user messages iterate the rendered project.

The user should not see a separate context-gathering form or have to understand workflow states. Skip context gathering should simply tell the assistant to build now and choose reasonable defaults for anything noncritical.

This branch attempted that flow, but implemented it across several competing control layers. The result behaves like a growing collection of workflow exceptions rather than one agent using tools.

Related issue

No issue linked yet.

Change type

• Feature
• Refactor
• Test
• Documentation

The breadth of these changes is itself a reason this PR is not ready to merge.

What this branch attempted

• Replaced the visible human-context checkpoint and linear intake form with chat.
• Added a Skip context gathering action.
• Added model-selected actions named ask_question, build_project, render_project, and iterate_project.
• Added build-readiness evaluation and canonical worker-plan dispatch.
• Added API polling so the chat can display generation progress.
• Connected successful generation back to the existing inline project component.
• Added canonical project revision persistence for chat-driven iteration.
• Added hierarchical electrical, mechanical, and firmware system architecture output so downstream agents can receive subsystem-level context without every pin-level detail.
• Changed default model/provider configuration toward OpenAI reasoning models.

What worked

• The model can distinguish a conversational question such as “what can I build?” from an instruction such as “go ahead and build it” in targeted smoke tests.
• A build can be dispatched from the chat endpoint and represented by a persisted worker plan.
• The frontend can poll the plan and feed the completed project into the existing inline renderer.
• Canonical projects can append immutable revisions for later iterations.
• Targeted backend tests, TypeScript type checking, and diff checks passed during development.

These checks validate individual mechanisms, not the complete user experience or production architecture.

Why the approach failed

1. There is no single owner of the conversation

The model router, context updater, workflow state machine, readiness service, API handlers, frontend event handlers, and project renderer can all decide what happens next. A user message therefore passes through several partially overlapping interpretations.

The intended architecture was “the chat agent uses tools.” The current implementation is still structured classification followed by imperative backend branches. Naming the classifications after tools did not create an actual agent/tool loop.

2. Questions and context updates are still treated as workflow mechanics

Ordinary conversation, context extraction, build intent, and project iteration remain separate code paths. This caused canned replies, repeated questions, and failures to answer basic conversational messages naturally.

The assistant should speak normally and update its working brief as a side effect. Asking a question does not need to be a special tool or workflow transition.

3. “Skip” accumulated three meanings

During development, Skip was implemented as:

• a transition to ready_to_build;
• a separate start-plan endpoint; and
• an explicit build_project request sent through the chat endpoint.

Only the last meaning matches the product: build now, allowing the agent to fill noncritical gaps. The earlier implementations added stale-state and dispatch edge cases.

4. Two project data models are active

Generation moved toward canonical DesignBrief / ProjectWorkflow / ProjectRevision records, while existing project pages, history, and iteration paths still expected legacy generated-project records. This required fallback readers, adapters, and a second revision path inside the same change.

Project generation and iteration need one canonical model before chat orchestration is layered on top.

5. Background execution is not production-safe

The initial FastAPI background task kept the request visibly stuck on “Thinking…” during a long generation. It was replaced with a detached daemon thread so the API could return and the frontend could poll.

That fixes the symptom locally, but a daemon thread is process-local: it is not reliably recoverable across restarts, deploys, or multiple replicas. Persisting a plan does not make the execution itself durable.

6. Rendering ownership moved into navigation logic

The first completion path navigated to a separate project page. That directly violated the intended product behavior: the project component belongs inside the chat. The navigation was removed, but the regression shows that the frontend had too much responsibility for interpreting workflow completion.

7. Progress is inferred instead of event-driven

The chat displays estimated legacy pipeline stages while the canonical worker performs generation elsewhere. It does not yet render persisted tool-call and worker-progress events from a single source of truth.

8. The PR mixed independent concerns

The current diff touches 42 tracked files and adds new modules. It combines:

• conversational intake;
• agent action routing;
• worker dispatch and polling;
• canonical project persistence and revisions;
• inline rendering and navigation;
• provider/model defaults; and
• hierarchical hardware-system output.

This makes the behavior difficult to reason about and the change unsafe to review as one unit.

User-visible failures observed

• A stale or missing route produced Not Found.
• The assistant asked linear, repeated questions and returned canned acknowledgements instead of conversing.
• A prominent context checkpoint exposed internal workflow mechanics.
• “Go,” “start,” and “do it now” were acknowledged without starting generation.
• Generation remained on “Thinking…” for roughly two minutes.
• The assistant announced that a design revision was ready without rendering the project component.
• A completion path opened the project page instead of integrating the project into the chat.
• After context was skipped, later chat messages could hit a state error instead of building or iterating.

Proposed replacement

Use one persisted chat event stream and one actual agent tool loop.

The assistant may either respond conversationally or call one of these tools:

• build_project(brief_snapshot, allow_agent_defaults)
• render_project(project_id, revision_id)
• iterate_project(project_id, instruction)

Asking a follow-up question remains an ordinary assistant response. Context extraction can update a draft brief internally, but it must not control the visible conversation.

The server should execute tool calls and append tool status/results to the same chat event stream. The UI should remain passive:

• render assistant and user messages;
• render build progress for a build tool call;
• render the project component inline for a render result; and
• send later messages back to the same agent for iteration.

Skip should issue the same build intent as “go ahead,” with allow_agent_defaults=true. It should not create a separate workflow or endpoint.

Long-running builds should run through a durable worker queue with retry and recovery, not an in-process daemon thread.

Recommended PR split

1. Chat tool contract and event persistence — one agent loop, tool-call/result events, and no generation UI changes.
2. Durable project build and inline rendering — worker execution, real progress events, and the existing project component embedded in chat.
3. Canonical project iteration — one project/revision model used by both the page and chat.
4. Hierarchical system architecture output — subsystem trees and agent-specific context scopes as an independent generation feature.
5. Provider/default-model changes — isolated configuration change with its own compatibility review.

Salvageable work

• The inline project renderer integration.
• Canonical immutable revision support, after choosing one project model.
• Worker-plan status records, if execution is moved to a durable queue.
• The hierarchical system architecture model and tests, in a separate PR.
• Targeted intent examples as evaluation fixtures for the new agent loop.

The structured action router, duplicated workflow transitions, separate start-build path, and process-local generation thread should not be carried forward as the orchestration foundation.

Verification

Checks observed during development:

Focused Python tests: 73 passed, 1 failed
  - tests.providers.test_llm_runtime.LLMRuntimeTests.test_cloudflare_retries_when_reasoning_uses_budget_before_visible_content
  - Existing Cloudflare behavior sent enable_thinking=true where the test expected false; this path is unchanged by the branch.
npx tsc --noEmit: passed after merging current dev
git diff --check: passed
Live model smoke: conversational question -> reply; explicit build request -> build selection

The complete repository quality suite has not been rerun against the final dirty worktree. End-to-end behavior is not considered verified.

Configuration or migration requirements

• OpenAI provider/model defaults and environment examples changed.
• Canonical project revision persistence was expanded.
• A production implementation would require a durable worker runtime and a migration plan away from legacy generated-project records.

Visual changes

The experiment changed the intake UI from a visible context form to conversational messages, added a Skip button and build progress, and attempted to render the project inline. The screenshots captured during development also document the regressions listed above.

Safety and compatibility

• Do not merge the daemon-thread build runner as production infrastructure.
• Existing legacy projects and canonical projects do not yet share one fully compatible read/iterate path.
• Agent-chosen electrical and radio design details still require the normal hardware-safety and regulatory checks; skipping intake must not skip safety-critical validation.
• The hierarchical system output should remain additive until all consumers support it.

AI assistance

The implementation and this retrospective were substantially AI-assisted. Reviewers should independently validate orchestration boundaries, persistence behavior, worker durability, hardware safety, and user-facing behavior.

Checklist

• This pull request targets dev and the branch started from an up-to-date dev.
• The change addresses one logical concern and contains no unrelated cleanup.
• Temporary, fixup, and unrelated commits were cleaned up where practical.
• Python code is typed and public classes and functions are documented where applicable.
• Relevant targeted deterministic tests were added or updated.
• ./scripts/quality/test.sh passes, or failures are explained above.
• Frontend type checking passed during development.
• Documentation was updated while behavior changed.
• No secrets, logs, databases, build artifacts, or generated temporary files are included.
• Hardware safety implications were considered.
• Breaking and compatibility risks are identified above.

Merge recommendation

Do not merge this branch as a feature PR. Use it as a design spike: retain the useful persistence, rendering, and architecture pieces, then rebuild the interaction around one real chat-agent tool loop in the smaller PRs above.

[supabase]

This pull request has been ignored for the connected project knmuwxhfrgkykyvblzwi because there are no changes detected in supabase directory. You can change this behaviour in Project Integrations Settings ↗︎.

---

Preview Branches by Supabase.
Learn more about Supabase Branching ↗︎.

[vercel]

The latest updates on your projects. Learn more about Vercel for GitHub.

Project	Deployment	Actions	Updated (UTC)
blueprint-oss	Ready	Preview	Aug 4, 2026 1:03am

[cloudflare-workers-and-pages]

Deploying with    Cloudflare Workers

The latest updates on your project. Learn more about integrating Git with Workers.

Status	Name	Latest Commit	Updated (UTC)
❌ Deployment failed View logs	forma-oss	829a764	Aug 04 2026, 02:30 AM