Building AI Workflows: From Gendered Experts to Gender-Neutral Teams

Last week, I wrapped up session 3 of building our AI workflow system, and it was one of those development sessions that perfectly captures the messy, iterative nature of real software development. What started as a simple template update turned into a masterclass in async patterns, user experience design, and the importance of inclusive AI personas.

The Mission: Better Expert Teams

Our goal was straightforward: finalize the expert team templates in our AI workflow system. We had three implementation prompt templates that were generating AI "experts" to help with different types of projects, but they had a problem - they were using gendered personas with overly creative titles. Time to modernize.

The fix involved updating our src/lib/constants.ts file to use gender-neutral agents with standard professional titles across all three templates: extensionPrompt, deepPrompt, and secPrompts. Each template now includes a "Step 0: Assemble the Expert Team" phase that assigns domain-specific experts to match the project's technical requirements.

UI Improvements That Actually Matter

While working on the templates, we also shipped some quality-of-life improvements that make the workflow experience much smoother:

• Full markdown rendering: Replaced the custom parsePromptSections() function with inline MarkdownRenderer for better formatting
• Download capabilities: Added .md download functionality with a clean toolbar including Copy, Edit, and Retry options
• Better file handling: Implemented a downloadMarkdown(content, filename) helper that actually works

The end result? Users can now export their AI-generated workflows as proper markdown files - something that sounds simple but required careful attention to content formatting and browser download APIs.

Lessons Learned (AKA The Pain Log)

Every development session teaches you something new, usually the hard way. Here's what caught me off guard:

1. Playwright's Location Sensitivity

The Problem: Tried running Playwright tests from /tmp/ and got cryptic failures.
The Solution: Playwright needs to run from the project root to access node_modules. Seems obvious in retrospect, but cost me 30 minutes of debugging.

2. Environment Variable Naming Gotchas

The Problem: Spent time debugging process.env.NEXTAUTH_SECRET only to discover it should be AUTH_SECRET.
The Lesson: When upgrading dependencies (especially auth libraries), always double-check environment variable naming conventions.

3. Async Generators Are Tricky

This was the big one. Our workflow engine uses AsyncGenerators, which only run when consumed. I initially tried starting workflows via tRPC's start mutation and then polling for results, but workflows would just sit there doing nothing.

The Fix: After calling the start mutation, you must immediately connect to the SSE (Server-Sent Events) endpoint at /api/v1/events/workflows/[id]. The workflow literally won't execute until something is consuming the generator.

// Wrong approach - workflow won't run
await startWorkflow.mutate({ id: workflowId });
// polling for results... but nothing happens

// Right approach - connect to SSE immediately
await startWorkflow.mutate({ id: workflowId });
const eventSource = new EventSource(`/api/v1/events/workflows/${workflowId}`);

4. Zod Schema Mismatches

The Problem: Passing input as a string to our create mutation failed validation.
The Solution: Our Zod schema expects z.record(z.string()), so the correct format is { text: "your input here" }.

Success Metrics

Despite the challenges, we shipped a complete feature. Our test workflow (2ae7dd55-d48b-48c0-a42e-14a60b11a4a5) completed successfully in 173.6 seconds, generating 5 domain experts perfectly matched to a real-time collaborative editor tech stack. The LLM correctly identified needs for frontend, backend, WebSocket, database, and DevOps expertise.

What's Next

The immediate roadmap includes:

1. Testing the alternatives selection flow (when generateCount: 3)
2. Updating estimateWorkflowCost to account for the generateCount multiplier
3. Cleaning up some stale workflows that got stuck without SSE consumers

The Bigger Picture

This session reinforced something important about AI system development: the human experience design matters just as much as the AI capabilities. Gender-neutral expert personas aren't just about inclusivity (though that's crucial) - they're about creating AI systems that feel professional and trustworthy to all users.

The technical challenges around async patterns and environment configuration remind us that even "simple" features often involve complex system interactions. But when you get it right, the result is a system that feels magical to use - AI experts assembling on demand to help with whatever technical challenge you're facing.

Currently running on localhost:3000 with PostgreSQL on localhost:5432. The workflow system is live and generating expert teams for real projects. Next up: making the cost estimation more accurate for multi-alternative workflows.