From Cluttered Cards to Clarity: Supercharging Our Workflow UI with Markdown and Dynamic Expert Teams

Every once in a while, a development session comes along that truly levels up the user experience. Our latest sprint was one of those, focusing on a critical aspect of our platform: the workflow execution UI. We tackled everything from presentation clarity to the intelligence behind our prompt generation, culminating in a more intuitive, powerful, and developer-friendly interface.

Our goals were ambitious but clear:

Transform the Workflow UI: Replace those restrictive collapsed prompt section cards with full, beautiful Markdown rendering.
Empower Users with Data: Add a .md download option for completed steps.
Boost Prompt Intelligence: Integrate dynamic "Expert Team" creation into all core implementation prompt templates.

I'm thrilled to report that all three objectives are now live, compiled clean, and thoroughly verified with a brand-new test workflow, "Expert Team Test." Let's dive into the details of how we got there.

Elevating the Workflow UI: From Cards to Clarity

Previously, our workflow execution UI used collapsed cards for displaying step outputs. While functional, this approach often truncated valuable information and hindered readability, especially for lengthy or complex outputs. It was a clear bottleneck for understanding the nuances of a workflow's progress.

Our solution? A complete overhaul. We've replaced the old PromptSectionCard component with a full inline MarkdownRenderer. This means that as each step completes, its output is now displayed with rich formatting, code blocks, lists, and everything you'd expect from well-structured Markdown. The difference in readability and comprehension is night and day.

But we didn't stop there. To further enhance interaction, we introduced a new action toolbar above each completed step. This toolbar replaces the previous bottom-only Edit/Retry buttons and now includes:

.md Download: A crucial addition! Users can now download the full Markdown content of any completed step output directly to their local machine. This was made possible by a handy downloadMarkdown(content, filename) helper that creates a Blob and triggers a browser download with a sanitized filename based on the step label.
Copy: Quickly copy the raw Markdown content to the clipboard.
Edit: Re-enter the prompt to make adjustments.
Retry: Re-run a specific step.

This set of changes dramatically improves how users interact with and leverage the output of their workflows, making it easier to analyze, share, and iterate.

The Brain Trust: Assembling Expert Teams for Smarter Prompts

Beyond UI aesthetics, we also focused on intelligence. A key enhancement involves a new "Expert Team" pattern integrated into our prompt templates. The idea is simple yet powerful: by dynamically assembling a team of virtual domain experts relevant to the task at hand, we can significantly improve the quality and specificity of the generated prompts.

Here's how it works:

Dynamic Assembly: We've updated our extensionPrompt, deepPrompt, and secPrompts templates to include a new "Step 0: Assemble the Expert Team" section. This system now intelligently identifies 3-5 domain experts whose skills match the target repository's stack, the project's tech stack, or the specific vulnerability classes found (for security prompts).
Assigned Expertise: Each subsequent prompt within the workflow now includes an "Assigns Expert(s)" field, ensuring that the right virtual specialist is contributing to the relevant part of the task.
System-Wide Mention: Even our core systemPrompt fields have been updated to acknowledge and leverage this expert team assembly.

To verify this game-changing feature, we created and executed a dedicated test workflow called "Expert Team Test." This 3-step workflow (Analyze Idea → Design Features → Implementation Prompts) successfully demonstrated the generation of a diverse expert team: Sarah Chen (Full-Stack), Marcus Rodriguez (DB Architect), an AI Integration Specialist, Alex Kim (Frontend), and Jordan Taylor (DevOps). Crucially, each expert was correctly assigned to relevant prompts, proving the system's ability to tailor expertise dynamically.

This feature is a significant leap forward in making our AI-driven workflows more context-aware and capable of generating highly specialized and accurate outputs.

Navigating the Trenches: Lessons Learned & Workarounds

No significant development session is without its challenges. Here are a few "pain points" we encountered and the valuable lessons we learned along the way:

Playwright Path Problems

Challenge: Attempting to run a Playwright screenshot script from a temporary directory (/tmp/) resulted in Cannot find module 'playwright'.
Lesson Learned: Node.js module resolution is context-dependent. node_modules are typically resolved relative to the current working directory or NODE_PATH. Running scripts from outside the project root often breaks this.
Workaround: Copying the script into the project root and running it from there solved the issue, followed by cleanup. Simple, but a good reminder about execution environments.

Auth Secret Snafu

Challenge: Forging a JWT using process.env.NEXTAUTH_SECRET failed during testing.
Lesson Learned: Project-specific environment variable naming conventions are crucial. In this project, the authentication secret was defined as AUTH_SECRET, not NEXTAUTH_SECRET.
Workaround: A quick dotenv.config() combined with process.env.AUTH_SECRET resolved the authentication issue. Always double-check your .env files and code for variable names!

Workflow Execution Mechanics

Challenge: After calling a tRPC start mutation for a workflow, it remained in a "running" state with all steps "pending."
Lesson Learned: The start mutation only updates the database status. Actual workflow execution, especially for asynchronous, long-running processes, requires active consumption of an SSE (Server-Sent Events) endpoint. The system needs a client to "drive" the AsyncGenerator execution by listening for events.
Workaround: The solution involved connecting to the /api/v1/events/workflows/[id] SSE endpoint via fetch and a ReadableStream reader after initiating the workflow. This ensures the client actively participates in driving the workflow's progression.

Zod Input Type Gotcha

Challenge: Passing workflow input as a simple string to a workflow creation mutation resulted in a Zod validation error.
Lesson Learned: Our Zod schema for the input field expected z.record(z.string()) (an object), not a bare string. While {{input}} template resolvers can handle objects, direct string input isn't implicitly converted.
Workaround: Changing the input to input: { text: "..." } correctly satisfied the schema. This highlights the importance of aligning frontend data structures with backend validation schemas.

Looking Ahead: What's Next on Our Roadmap

With these significant improvements under our belt, our focus now shifts to further refining the experience. Here are some immediate next steps we're eager to tackle:

Workflow Cleanup: Address stale workflows (like db096fa7 which got stuck in a running state due to the SSE consumer issue) by implementing proper failure states or deletion mechanisms.
Input Flexibility: Consider enhancing the {{input}} template resolver to directly handle string inputs from the create mutation, reducing the need for an explicit object wrapper.
Accurate Cost Estimation: Update the estimateWorkflowCost function to properly account for the generateCount multiplier, providing more precise cost projections.
Alternatives Selection Flow: Conduct end-to-end testing of the alternatives selection feature, ensuring that generating multiple alternatives (generateCount: 3), selecting one, and continuing the workflow all work seamlessly.
Prompt Editing Verification: Thoroughly test the prompt editing functionality: expanding a PROMPT section on a pending workflow, editing it, saving, and verifying that the updated prompt is indeed used for the next execution.
Long Output Navigation: For extremely long implementation prompt outputs (10k+ tokens), consider adding a "Section View" toggle or a table of contents to improve navigation, building on the success of the full Markdown rendering.

This session was a fantastic stride forward for our platform. By focusing on both the visual clarity of our UI and the underlying intelligence of our prompt system, we're continuously striving to create a more powerful, intuitive, and enjoyable experience for all our developers. Stay tuned for more updates!