← nyxcore-systems
8 min read

Empowering AI Workflows with Context: Injecting Live Repository Documentation

Giving AI agents the context they need directly from your codebase. We dive into building a documentation injection system for AI-driven workflows, tackling Prisma quirks and template evolution along the way.

AIWorkflowsNext.jsPrismaGitHub APIDeveloper ToolsProductivityLLMOps

As developers, we're constantly striving to build tools that make us more productive. In the world of AI-assisted development, that often means giving our AI agents the richest, most relevant context possible. Imagine an AI agent tasked with extending a feature, or analyzing a complex codebase – it needs more than just a prompt; it needs documentation.

This past session, our mission was clear: empower our AI workflows to pull in live repository documentation directly from GitHub, making it available as a dynamic variable within our prompt templates. This wasn't just about a new feature; it was about transforming how our AI agents understand and interact with codebases.

The Vision: {{docs}} - Your AI's New Best Friend

The core idea was simple yet powerful: introduce a {{docs}} template variable. When an AI workflow runs, this variable would magically expand to include selected documentation files from a linked GitHub repository. Need docs for a specific project within a monorepo? We even planned for {{docs.ProjectName}}.

This wasn't just a theoretical exercise. We envisioned an "Extension Builder" workflow, where an AI could analyze an existing repository, understand its features from its documentation, and then propose new extensions or refactors. For this to work, the AI needed to see the docs.

Under the Hood: The Technical Journey

Bringing {{docs}} to life required touching almost every layer of our stack.

1. Data Model & Validation

First, we needed a place to store which documentation files a workflow should reference. We extended our Workflow model in prisma/schema.prisma with a new field:

prisma
// prisma/schema.prisma
model Workflow {
  // ... other fields
  docRefs Json? // Stores an array of { projectId, filePath }
  // ...
}

This docRefs field, a Json? type, would hold an array of objects, each specifying a project and the path to a document within that project. Naturally, this required corresponding Zod validation (docRefSchema) for our create and duplicate workflow mutations in src/server/trpc/routers/workflows.ts.

2. Server-Side Magic: Fetching, Truncating, and Context

The real heavy lifting happens in src/server/services/workflow-engine.ts.

loadDocumentationContent(): This new function is the heart of the operation.

  • It takes our docRefs and, for each reference, uses a BYOK (Bring Your Own Key) GitHub token to fetch the file content.
  • We implemented robust per-file error handling, ensuring that if one doc fails to load, the entire workflow doesn't crash.
  • Crucially, to prevent overwhelming the AI's context window, we introduced a 50,000 character truncation limit per file.

Extending ChainContext: Once fetched, this documentation content needed to be available to the prompt resolver. We extended our ChainContext (the object passed to our prompt templating engine) with:

  • documentationContent: The combined, truncated content of all selected documents.
  • documentationByProject: A Map for accessing content specific to {{docs.ProjectName}}.

resolvePrompt(): Our prompt templating function was updated to recognize and substitute {{docs}} and {{docs.ProjectName}} variables with the loaded content.

3. The User Experience: Picking Docs & Managing Workflows

A powerful backend is useless without an intuitive frontend.

Documentation Picker UI: In src/app/(dashboard)/dashboard/workflows/new/page.tsx, we built a sleek UI that allows users to:

  • Toggle between available GitHub projects (sourced from a new availableDocProjects query).
  • Add specific file paths for documentation, defaulting to common files like CLAUDE.md and README.md.

Visibility & Control:

  • The selected "Linked Documentation" is now clearly displayed in the settings panel of an active workflow.
  • We enhanced workflow management across the board:
    • Added Pause, Stop, and Delete action buttons to each workflow card on the dashboard.
    • Introduced a cancel mutation to gracefully stop running or paused workflows.
    • For interactive review steps, we added an inline "Continue" button and ensured that paused review steps auto-expand, making the button immediately visible. This significantly streamlines the human-in-the-loop experience.

4. Smart Agents & Templates

Finally, we built out the templates that would leverage this new capability:

  • Extension-Specific Steps: We created five new step templates (extensionAnalyze, extensionFeatures, extensionReview, extensionExtend, extensionPrompt) specifically designed for the "Extension Builder" workflow. These templates correctly chained their inputs using labels like {{steps.Analyze Target Repo.content}}.
  • Extension Builder Workflow: A new, sophisticated workflow template that orchestrates these steps, allowing an AI to deeply analyze a target repository and propose extensions based on its documentation.
  • Updating Existing Templates: Our existing deepWisdom and deepPrompt templates were also updated to include the {{docs}} section, instantly making them more powerful.

Navigating the Minefield: Lessons Learned

No development session is complete without a few head-scratching moments. These "pain logs" are often the most valuable lessons.

Lesson 1: The Elusive Prisma Client Cache

The Problem: After adding docRefs to our Prisma schema and running npx prisma db push and npx prisma generate, the dev server kept throwing type errors, complaining that docRefs didn't exist on the Workflow model. Grepping node_modules/@prisma/client/ yielded nothing.

The Discovery: The generated Prisma client types are actually located in node_modules/.prisma/client/. A quick check there confirmed docRefs was indeed present. The issue wasn't the generation; it was the dev server holding onto an outdated version of the Prisma client in memory.

The Fix: The classic developer's mantra: "When in doubt, nuke it from orbit."

bash
# Kill the dev server
kill <process_id_of_next_dev_server>

# Remove Next.js build cache
rm -rf .next

# Restart the dev server
npm run dev # or yarn dev

This cleared the cache, and suddenly, docRefs was recognized.

Takeaway: Prisma client generation can sometimes be a bit finicky with dev server caching. If you're seeing schema-related type errors after a db push/generate, always try a full dev server restart and clearing the .next cache. It's a common pitfall that can waste precious debugging time.

Lesson 2: Workflow Immutability & Template Evolution

The Problem: When building the "Extension Builder" workflow, I initially tried to reuse existing deepFeatures, deepReview, etc., steps. However, these steps referenced previous step outputs by hardcoded labels (e.g., {{steps.Idea.content}}, {{steps.Research.content}}). The "Extension Builder" pipeline starts with "Analyze Target Repo," not "Idea," leading to broken prompt chains.

The Discovery: Our existing workflow creation process bakes the step prompts, including their variable references, directly into the database rows when a workflow is initially created. Changing constants in src/lib/constants.ts after a workflow has been created does not retroactively update existing workflow instances.

The Fix: The solution was to create entirely new, extension-specific step templates (extensionAnalyze, extensionFeatures, etc.) with their {{steps.Label.content}} references correctly aligned to the Extension Builder's step labels. This meant users would need to create new Extension Builder workflows to benefit from the updated logic.

Takeaway: Be mindful of the lifecycle of your workflow definitions. If your system persists workflow configurations (especially prompt templates) in a database, changes to "master" templates or constants won't automatically propagate to existing, active workflows. Plan for migration strategies or clearly communicate that users need to instantiate new workflows to pick up the latest template versions.

What's Next? Refining the AI-Developer Experience

With documentation injection now live, our immediate focus shifts to polishing the AI's output and overall user experience:

  1. Improved Prompt Output: The "Implementation Prompts" step, especially in the Extension Builder, can generate multiple prompts. We want to display each as a separate, collapsible card with a brief description, rather than one monolithic markdown blob.
  2. Copy-to-Clipboard: A small but mighty feature: add a "copy single prompt" button to each prompt card for easy clipboard access.
  3. End-to-End Testing: A full, real-world test of the Extension Builder pipeline with a live GitHub repository is crucial to validate its effectiveness.
  4. Prompt Count Indicator: Adding a simple "(7 prompts)" indicator to step headers will provide immediate context to the user.

Conclusion

This session was a significant leap forward in making our AI agents more intelligent and context-aware. By directly linking our workflows to live repository documentation, we've unlocked new possibilities for AI-driven code analysis, feature generation, and refactoring. While the journey had its share of technical puzzles (looking at you, Prisma client cache!), each challenge reinforced valuable lessons in building robust, AI-powered developer tools. The future of context-rich AI is here, and it's looking pretty smart.

json
{
  "thingsDone": [
    "Added docRefs field to Workflow model in Prisma",
    "Implemented loadDocumentationContent() for GitHub file fetching, truncation, and error handling",
    "Extended ChainContext with documentationContent and documentationByProject",
    "Added {{docs}} and {{docs.ProjectName}} template variables in resolvePrompt()",
    "Implemented docRefSchema Zod validation for workflow mutations",
    "Created availableDocProjects query for UI",
    "Added cancel mutation for workflows",
    "Created 5 extension-specific step templates for Extension Builder",
    "Developed Extension Builder workflow template",
    "Updated deepWisdom and deepPrompt templates to include {{docs}}",
    "Built documentation picker UI in new workflow page",
    "Added 'Linked Documentation' display in workflow settings",
    "Implemented inline 'Continue' button on paused review steps",
    "Auto-expanded paused review steps for visibility",
    "Added Pause/Stop/Delete action buttons to workflow cards",
    "Fixed Next.js 14 params unwrapping issue"
  ],
  "pains": [
    "Prisma client not updating after db push/generate due to dev server caching",
    "Workflow step template references breaking when reusing generic steps in specific pipelines"
  ],
  "successes": [
    "Successfully implemented dynamic documentation injection for AI workflows",
    "Created a robust system for fetching and truncating documentation from GitHub",
    "Enhanced user control and visibility over workflows and documentation links",
    "Developed a powerful 'Extension Builder' AI workflow template",
    "Identified and resolved critical Prisma client caching behavior",
    "Understood and adapted to the immutability of workflow step prompts post-creation"
  ],
  "techStack": [
    "Next.js 14",
    "Prisma",
    "PostgreSQL",
    "Redis",
    "tRPC",
    "Zod",
    "GitHub API",
    "TypeScript",
    "AI/LLM Workflow Engine"
  ]
}