Building a Documentation-Aware Workflow Engine: From Template Variables to UI Components

Ever wished your automated workflows could actually read your project documentation? Last week, I tackled exactly that challenge while building a feature that lets workflows dynamically pull in documentation from GitHub repositories and inject it into AI prompts using simple template variables like {{docs}}.

What started as a straightforward "add a template variable" task turned into a full-stack adventure involving database schema changes, GitHub API integration, custom UI components, and some valuable lessons about development server caching. Here's how it all came together.

The Vision: Documentation-Aware Workflows

The goal was simple: allow workflows to reference project documentation directly in their prompts. Instead of manually copying README files or API docs into every prompt, users could just add {{docs}} to their templates and have the system automatically fetch and inject the relevant content.

For more granular control, we also wanted project-specific references like {{docs.MyProject}} to pull documentation from specific repositories.

Database Schema: The Foundation

First step was extending our Prisma schema to store documentation references:

model Workflow {
  // ... existing fields
  docRefs Json?
}

The docRefs field stores an array of documentation references, each containing a project name and file paths to fetch from GitHub.

GitHub Integration: Fetching Documentation on Demand

The core service logic lives in our workflow engine, where we implemented a loadDocumentationContent() function that:

• Fetches files from GitHub repositories using BYOK (Bring Your Own Key) tokens
• Handles per-file error cases gracefully
• Truncates content to 50k characters to stay within prompt limits
• Caches results in the workflow context for performance

interface DocRef {
  projectName: string;
  filePaths: string[];
}

async function loadDocumentationContent(docRefs: DocRef[]): Promise<string> {
  // GitHub API calls with error handling
  // Content truncation and formatting
  // Return formatted documentation string
}

Template Variable Magic

The template resolution system now recognizes two new patterns:

• {{docs}} - Injects all linked documentation
• {{docs.ProjectName}} - Injects documentation from a specific project

These variables get resolved during workflow execution, pulling fresh content from GitHub each time.

UI Components: Making It User-Friendly

The backend work was only half the battle. We needed an intuitive way for users to select which documentation to include. This led to building a documentation picker component featuring:

• Project toggles - Enable/disable documentation from different repositories
• File path editor - Customize which files to include (defaults to README.md and CLAUDE.md)
• Real-time validation - Only show projects that have GitHub repositories configured

The picker integrates seamlessly into our workflow creation flow, and selected documentation appears in the workflow settings panel for easy reference.

Extension Builder: A Specialized Workflow Template

With documentation injection working, we created a specialized "Extension Builder" workflow template designed specifically for generating browser extensions. This template uses a carefully orchestrated sequence of steps:

1. Analyze Target Repo - Examine the codebase structure
2. Design Features - Plan extension functionality
3. Review Architecture - Validate the technical approach
4. Extend Implementation - Generate additional components
5. Implementation Prompts - Output final code generation prompts

Each step references outputs from previous steps using variables like {{steps.Analyze Target Repo.content}}, creating a coherent chain of reasoning.

Lessons Learned: The Debugging Chronicles

The Prisma Client Caching Mystery

The biggest challenge wasn't the feature implementation—it was a seemingly simple database update that refused to work. After running npx prisma db push and npx prisma generate, the commands reported success, but our application couldn't find the new docRefs field.

The Investigation:

• Searched node_modules/@prisma/client/ - found nothing
• Discovered types are actually in node_modules/.prisma/client/
• Found 39 occurrences of docRefs in the generated types
• Runtime still threw "property doesn't exist" errors

The Solution: The development server was caching the old Prisma client in memory! The fix was simple but not obvious:

# Kill the dev server
# rm -rf .next
# Restart the dev server

Lesson: When Prisma schema changes don't seem to take effect, it's often a caching issue, not a generation problem.

Template Reference Mismatches

Another gotcha emerged when creating the Extension Builder template. We initially tried reusing existing step templates, but they referenced variables like {{steps.Idea.content}} and {{steps.Research.content}} - labels that didn't exist in our new workflow.

The Problem: Existing workflows bake step prompts into database rows at creation time. Changing template constants doesn't retroactively fix existing workflows.

The Solution: Created extension-specific step templates with correct label references matching our new workflow structure.

Lesson: Template systems need careful variable management, and changes require creating new workflow instances.

Enhanced User Experience Features

Beyond the core documentation feature, we added several UX improvements:

• Inline continue buttons on paused review steps
• Auto-expansion of paused steps so action buttons are visible
• Workflow control buttons (Pause/Stop/Delete) on each workflow card
• Linked documentation display in workflow settings panels

What's Next: Better Output Formatting

The current implementation works great, but there's room for improvement. Right now, when the Extension Builder generates multiple implementation prompts, they appear as one large markdown blob.

The next iteration will display each prompt as a separate collapsible card with:

• Brief descriptions of what each prompt builds
• Individual copy buttons for easy clipboard access
• Prompt count indicators in step headers
• Better visual organization for complex outputs

Wrapping Up

Building documentation-aware workflows required touching every layer of the stack - from database schemas to UI components to GitHub API integration. The technical challenges were interesting, but the debugging lessons were invaluable.

The most important takeaway? Modern development often involves more caching layers than we realize. When something should work but doesn't, clearing caches (development server, build artifacts, etc.) should be step one in your debugging process.

Have you built similar documentation integration features? I'd love to hear about your approaches and the challenges you encountered. The intersection of AI workflows and dynamic content injection feels like fertile ground for developer tooling innovation.